fix(heartbeat): fail closed on internal checks

* feat(webui): refine output timeline and composer queue

* feat(webui): add provider model picker

* fix(webui): polish model settings and heartbeat checks

* chore: keep heartbeat changes out of webui pr

* refactor(webui): isolate settings routes

* fix(providers): align minimax anthropic test

* fix(providers): keep minimax anthropic base sdk-compatible

* fix(providers): normalize anthropic base urls

.agent/gotchas.md

@@ -31,10 +31,6 @@ Tool descriptions, skills, and replayed session history also shape model behavio
 
 Anything written into memory, session history, or prompt inputs can be replayed into future LLM calls. Metadata such as timestamps, local media paths, tool-call echoes, and raw fallback dumps must be bounded and sanitized before they become examples for the model to imitate.
 
-## Heartbeat Virtual Tool Call
-
-The heartbeat service (`heartbeat/service.py`) does not parse free-text LLM output. Instead, it injects a virtual `heartbeat` tool with `action: skip | run` into the conversation. Phase 1 is a structured decision; Phase 2 executes only on `run`. When adding new periodic background checks, follow this virtual-tool-call pattern rather than string matching.
-
 ## Skills as Extension Point
 
 Built-in skills live in `nanobot/skills/` (markdown + YAML frontmatter format). Agent capabilities that are "know-how" rather than code should be added as skills, not hardcoded into the agent loop. External skills can be published to and installed from ClawHub.

.gitignore

@@ -6,6 +6,8 @@
 .env
 .web
 .orion
+nanobot-desktop/
+desktop/
 
 # Claude / AI assistant artifacts
 docs/superpowers/
@@ -98,3 +100,4 @@ tmp/
 temp/
 *.tmp
 exp/
+.playwright-mcp/

CLAUDE.md

@@ -47,7 +47,7 @@ Messages flow through an async `MessageBus` (`nanobot/bus/queue.py`) that decoup
 - **WebUI** (`webui/`): Vite-based React SPA that talks to the gateway over a WebSocket multiplex protocol. The dev server proxies `/api`, `/webui`, `/auth`, and WebSocket traffic to the gateway.
 - **API Server** (`nanobot/api/server.py`): OpenAI-compatible HTTP API (`/v1/chat/completions`, `/v1/models`) for programmatic access.
 - **Command Router** (`nanobot/command/`): Slash command routing and built-in command handlers.
-- **Heartbeat** (`nanobot/heartbeat/`): Periodic agent wake-up service for scheduled task checking.
+- **Heartbeat** (`nanobot/templates/HEARTBEAT.md`): Periodic task list checked via `cron` jobs (legacy dedicated service removed).
 - **Pairing** (`nanobot/pairing/`): DM sender approval store with persistent pairing codes per channel.
 - **Skills** (`nanobot/skills/`): Built-in skill definitions (long-goal, cron, github, image-generation, etc.) loaded into agent context.
 - **Security** (`nanobot/security/`): PTH file guard and other security measures activated at CLI entry.

CONTRIBUTING.md

@@ -12,6 +12,8 @@ software together: with care, clarity, and respect for the next person reading t
 
 ## Maintainers
 
+Maintainers are community stewards who help review, organize, and maintain the project. The list below describes each maintainer's current open-source project responsibilities.
+
 | Maintainer | Focus |
 |------------|-------|
 | [@re-bin](https://github.com/re-bin) | Project lead, `main` branch |

core_agent_lines.sh

@@ -46,17 +46,15 @@ core_agent=$(count_top_level_py_lines "nanobot/agent")
 core_bus=$(count_top_level_py_lines "nanobot/bus")
 core_config=$(count_top_level_py_lines "nanobot/config")
 core_cron=$(count_top_level_py_lines "nanobot/cron")
-core_heartbeat=$(count_top_level_py_lines "nanobot/heartbeat")
 core_session=$(count_top_level_py_lines "nanobot/session")
 
 print_row "agent/" "$core_agent"
 print_row "bus/" "$core_bus"
 print_row "config/" "$core_config"
 print_row "cron/" "$core_cron"
-print_row "heartbeat/" "$core_heartbeat"
 print_row "session/" "$core_session"
 
-core_total=$((core_agent + core_bus + core_config + core_cron + core_heartbeat + core_session))
+core_total=$((core_agent + core_bus + core_config + core_cron + core_session))
 
 echo ""
 echo "Separate buckets"

docs/chat-apps.md

@@ -51,6 +51,43 @@ Connect nanobot to your favorite chat platform. Want to build your own? See the
 nanobot gateway
 ```
 
+**Webhook mode (optional)**
+
+Telegram uses long polling by default. To receive updates through a webhook, expose
+a public HTTPS URL that forwards to nanobot's local listener and set `mode` to
+`webhook`:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "mode": "webhook",
+      "webhookUrl": "https://example.com/telegram",
+      "webhookListenHost": "127.0.0.1",
+      "webhookListenPort": 8081,
+      "webhookPath": "/telegram",
+      "webhookSecretToken": "CHANGE_ME_RANDOM_SECRET",
+      "webhookMaxConnections": 4,
+      "allowFrom": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> `webhookSecretToken` is required in webhook mode. Do not expose the local
+> webhook listener directly to the public internet without a reverse proxy or
+> tunnel in front of it. TLS/Host policy is handled by your proxy; nanobot only
+> listens on `webhookListenHost:webhookListenPort` and validates Telegram's
+> webhook secret token. `webhookMaxConnections` defaults to `4`; nanobot
+> still serializes Telegram updates per conversation before forwarding them to
+> the agent.
+>
+> `webhookUrl` is the public HTTPS URL registered with Telegram.
+> `webhookPath` is the local path nanobot listens on. They often use the same
+> path, but may differ when a reverse proxy or tunnel rewrites the request path.
+
 </details>
 
 <details>

docs/configuration.md

@@ -126,8 +126,10 @@ ANTHROPIC_API_KEY="$(bw get password api/anthropic)" nanobot agent
 > - **VolcEngine / BytePlus Coding Plan**: Use dedicated providers `volcengineCodingPlan` or `byteplusCodingPlan` instead of the pay-per-use `volcengine` / `byteplus` providers.
 > - **Zhipu Coding Plan**: If you're on Zhipu's coding plan, set `"apiBase": "https://open.bigmodel.cn/api/coding/paas/v4"` in your zhipu provider config.
 > - **Alibaba Cloud BaiLian**: If you're using Alibaba Cloud BaiLian's OpenAI-compatible endpoint, set `"apiBase": "https://dashscope.aliyuncs.com/compatible-mode/v1"` in your dashscope provider config.
+> - **StepFun Step Plan**: If you're on StepFun's Step Plan subscription, set `"apiBase": "https://api.stepfun.com/step_plan/v1"` in your stepfun provider config. Supported models include `step-3.5-flash`, `step-3.5-flash-2603`, and `step-router-v1`.
 > - **Step Fun (Mainland China)**: If your API key is from Step Fun's mainland China platform (stepfun.com), set `"apiBase": "https://api.stepfun.com/v1"` in your stepfun provider config.
 > - **Xiaomi MiMo thinking mode**: MiMo models (e.g. `mimo-v2.5-pro`) default to enabled thinking. Use `agents.defaults.reasoningEffort: "none"` to disable it, or `"low"` / `"medium"` / `"high"` to keep it on. Omitting the field preserves the provider's per-model default.
+> - **Xiaomi MiMo Token Plan**: If you're on MiMo's token plan, set `"apiBase": "https://token-plan-sgp.xiaomimimo.com/v1"` in your xiaomi_mimo provider config.
 
 | Provider | Purpose | Get API Key |
 |----------|---------|-------------|
@@ -166,6 +168,43 @@ 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>OpenAI</b></summary>
+
+By default, OpenAI uses `apiType: "auto"`: nanobot calls Chat Completions normally and routes GPT-5/o-series or explicit `reasoningEffort` requests through the Responses API when useful. You can force a specific API surface:
+
+```json
+{
+  "providers": {
+    "openai": {
+      "apiKey": "${OPENAI_API_KEY}",
+      "apiType": "chat_completions"
+    }
+  }
+}
+```
+
+Valid `apiType` values are exactly `auto`, `chat_completions`, and `responses`.
+
+`extraBody` follows the selected OpenAI API surface. With Chat Completions, nanobot passes it through as the SDK `extra_body` value. With Responses, configure it in Responses API body shape; nanobot merges ordinary top-level fields into the Responses request body, appends `extraBody.tools` after generated function tools, and merges `extraBody.include` without duplicates:
+
+```json
+{
+  "providers": {
+    "openai": {
+      "apiKey": "${OPENAI_API_KEY}",
+      "apiType": "responses",
+      "extraBody": {
+        "tools": [{ "type": "web_search" }],
+        "include": ["web_search_call.action.sources"]
+      }
+    }
+  }
+}
+```
+
+</details>
+
 <details>
 <summary><b>Skywork / APIFree</b></summary>
 
@@ -477,6 +516,68 @@ Official model names include `LongCat-Flash-Chat`, `LongCat-Flash-Thinking`,
 
 </details>
 
+<details>
+<summary><b>Xiaomi MiMo</b></summary>
+
+Xiaomi MiMo models are automatically detected by the `xiaomi_mimo` provider when
+the model name contains `mimo`. The default API base is
+`https://api.xiaomimimo.com/v1`.
+
+> **Token Plan**: If you're using MiMo's token plan, override `apiBase` with the
+> dedicated endpoint:
+>
+> ```json
+> {
+>   "providers": {
+>     "xiaomi_mimo": {
+>       "apiKey": "${XIAOMIMIMO_API_KEY}",
+>       "apiBase": "https://token-plan-sgp.xiaomimimo.com/v1"
+>     }
+>   },
+>   "agents": {
+>     "defaults": {
+>       "model": "xiaomi/mimo-v2.5-pro"
+>     }
+>   }
+> }
+> ```
+>
+> No need to set `provider` explicitly — the model name contains `mimo`, which
+> auto-matches to the `xiaomi_mimo` provider spec. Use an API key from the MiMo
+> token plan console and check the MiMo platform for the latest supported model
+> names.
+
+</details>
+
+<details>
+<summary><b>StepFun Step Plan (subscription)</b></summary>
+
+Step Plan is StepFun's subscription-based service for high-frequency AI developers.
+If you're on a Step Plan subscription, override `apiBase` in the existing `stepfun`
+provider config to point to the dedicated Step Plan endpoint.
+
+```json
+{
+  "providers": {
+    "stepfun": {
+      "apiKey": "${STEPFUN_API_KEY}",
+      "apiBase": "https://api.stepfun.com/step_plan/v1"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "stepfun",
+      "model": "step-3.5-flash"
+    }
+  }
+}
+```
+
+Supported models include `step-3.5-flash`, `step-3.5-flash-2603`, and
+`step-router-v1`.
+
+</details>
+
 <details>
 <summary><b>Ant Ling (OpenAI-compatible)</b></summary>
 
@@ -942,6 +1043,7 @@ Global settings that apply to all channels. Configure under the `channels` secti
   "channels": {
     "sendProgress": true,
     "sendToolHints": false,
+    "extractDocumentText": true,
     "sendMaxRetries": 3,
     "transcriptionProvider": "groq",
     "transcriptionLanguage": null,
@@ -955,8 +1057,9 @@ Global settings that apply to all channels. Configure under the `channels` secti
 | `sendProgress` | `true` | Stream agent's text progress to the channel |
 | `sendToolHints` | `false` | Stream tool-call hints (e.g. `read_file("…")`) |
 | `showReasoning` | `true` | Allow channels to surface model reasoning/thinking content (DeepSeek-R1 `reasoning_content`, Anthropic `thinking_blocks`, inline `<think>` tags). Reasoning flows as a dedicated stream with `_reasoning_delta` / `_reasoning_end` markers — channels override `send_reasoning_delta` / `send_reasoning_end` to render in-place updates. Even with `true`, channels without those overrides stay no-op silently. Currently surfaced on CLI and WebSocket/WebUI (italic shimmer header, auto-collapses after the stream ends); Telegram / Slack / Discord / Feishu / WeChat / Matrix keep the base no-op until their bubble UI is adapted. Independent of `sendProgress`. |
+| `extractDocumentText` | `true` | Extract supported document/text attachments into the model prompt. Set to `false` to keep document content out of the prompt and include attachment path references instead. |
 | `sendMaxRetries` | `3` | Max delivery attempts per outbound message, including the initial send (0-10 configured, minimum 1 actual attempt) |
-| `transcriptionProvider` | `"groq"` | Voice transcription backend: `"groq"` (free tier, default) or `"openai"`. API key is auto-resolved from the matching provider config. |
+| `transcriptionProvider` | `"groq"` | Voice transcription backend: `"groq"` (free tier, default) or `"openai"`. API key and optional `apiBase` are auto-resolved from the matching provider config. Chat-style bases such as `https://api.groq.com/openai/v1` are normalized to the audio transcription endpoint. |
 | `transcriptionLanguage` | `null` | Optional ISO-639-1 language hint for audio transcription, e.g. `"en"`, `"ko"`, `"ja"`. |
 
 `sendProgress` and `sendToolHints` can also be overridden per channel. The
@@ -1195,7 +1298,7 @@ If you want to always use the local conversion, you can force it using:
 
 ## Image Generation
 
-Image generation is configured under `tools.imageGeneration` and uses provider credentials from `providers.openrouter` or `providers.aihubmix`.
+Image generation is configured under `tools.imageGeneration` and uses credentials from the selected provider's `providers.<name>` block.
 
 See [Image Generation](./image-generation.md) for WebUI usage, provider examples, artifact storage, and troubleshooting.
 
@@ -1288,6 +1391,7 @@ For API keys, tokens, and other secrets, see [Environment Variables for Secrets]
 | `tools.restrictToWorkspace` | `false` | When `true`, restricts **all** agent tools (shell, file read/write/edit, list) to the workspace directory. Prevents path traversal and out-of-scope access. |
 | `tools.exec.sandbox` | `""` | Sandbox backend for shell commands. Set to `"bwrap"` to wrap exec calls in a [bubblewrap](https://github.com/containers/bubblewrap) sandbox — the process can only see the workspace (read-write) and media directory (read-only); config files and API keys are hidden. Automatically enables `restrictToWorkspace` for file tools. **Linux only** — requires `bwrap` installed (`apt install bubblewrap`; pre-installed in the Docker image). Not available on macOS or Windows (bwrap depends on Linux kernel namespaces). |
 | `tools.exec.enable` | `true` | When `false`, the shell `exec` tool is not registered at all. Use this to completely disable shell command execution. |
+| `tools.exec.timeout` | `60` | Default hard timeout in seconds for shell commands. Config values may exceed the per-call tool cap; set `0` to disable the hard timeout for trusted long-running commands. |
 | `tools.exec.pathAppend` | `""` | Extra directories to append to `PATH` when running shell commands (e.g. `/usr/sbin` for `ufw`). |
 | `channels.*.allowFrom` | omitted | Access control per channel. Omit to use pairing-only mode; set `["*"]` to allow everyone; or list specific user IDs. See [Pairing](#pairing) for details. |
 
@@ -1430,7 +1534,7 @@ By default, nanobot uses `UTC` for runtime time context. If you want the agent t
 }
 ```
 
-This affects runtime time strings shown to the model, such as runtime context and heartbeat prompts. It also becomes the default timezone for cron schedules when a cron expression omits `tz`, and for one-shot `at` times when the ISO datetime has no explicit offset.
+This affects runtime time strings shown to the model, such as runtime context. It also becomes the default timezone for cron schedules when a cron expression omits `tz`, and for one-shot `at` times when the ISO datetime has no explicit offset.
 
 Common examples: `UTC`, `America/New_York`, `America/Los_Angeles`, `Europe/London`, `Europe/Berlin`, `Asia/Tokyo`, `Asia/Shanghai`, `Asia/Singapore`, `Australia/Sydney`.
 

docs/image-generation.md

@@ -23,7 +23,7 @@ The feature is disabled by default. Enable it in `~/.nanobot/config.json`, confi
 }
 ```
 
-See [Provider Notes](#provider-notes) for AIHubMix, MiniMax, Gemini, Ollama, and StepFun configuration examples.
+See [Provider Notes](#provider-notes) for AIHubMix, MiniMax, Gemini, Ollama, StepFun, and Zhipu configuration examples.
 
 > [!TIP]
 > Prefer environment variables for API keys. nanobot resolves `${VAR_NAME}` values from the environment at startup.
@@ -46,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`, `minimax`, `gemini`, `ollama`, `stepfun` |
+| `tools.imageGeneration.provider` | string | `"openrouter"` | Image provider name. Supported values: `openrouter`, `aihubmix`, `minimax`, `gemini`, `ollama`, `stepfun`, `zhipu` |
 | `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` |
@@ -245,6 +245,31 @@ StepPlan is StepFun's subscription tier and uses a different API base URL. The i
 
 `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.
 
+### Zhipu
+
+Zhipu (智谱) `glm-image` model supports text-to-image generation. The API returns temporary image URLs (valid for 30 days); nanobot downloads and re-encodes them as base64 data URLs.
+
+Supported aspect ratios: `1:1`, `16:9`, `9:16`, `3:4`, `4:3`. Sizes can be specified as `WIDTHxHEIGHT` (e.g. `1280x1280`, `1728x960`) or using aspect ratio presets.
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "apiKey": "${ZAI_API_KEY}"
+    }
+  },
+  "tools": {
+    "imageGeneration": {
+      "enabled": true,
+      "provider": "zhipu",
+      "model": "glm-image"
+    }
+  }
+}
+```
+
+Other supported models: `cogview-4`, `cogview-4-250304`, `cogview-3-flash`. Reference images are not supported by this integration.
+
 ## Artifacts
 
 Generated images are stored under the active nanobot instance's media directory:
@@ -299,8 +324,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`, `minimax`, `gemini`, `ollama`, or `stepfun` |
+| `unsupported image generation provider` | Use `openrouter`, `aihubmix`, `minimax`, `gemini`, `ollama`, `stepfun`, or `zhipu` |
 | 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/agent/context.py

@@ -3,22 +3,51 @@
 import base64
 import mimetypes
 import platform
-from contextlib import suppress
-from importlib.resources import files as pkg_files
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from nanobot.agent.memory import MemoryStore
 from nanobot.agent.skills import SkillsLoader
+from nanobot.agent.tools import mcp as mcp_tools
+from nanobot.agent.tools.registry import ToolRegistry
+from nanobot.apps.cli import utils as cli_app_utils
+from nanobot.bus.events import InboundMessage
 from nanobot.session.goal_state import goal_state_runtime_lines
 from nanobot.utils.helpers import (
     current_time_str,
     detect_image_mime,
+    load_bundled_template,
     truncate_text,
 )
 from nanobot.utils.prompt_templates import render_template
 
 
+def session_extra(metadata: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Return persisted kwargs for turn-attached capabilities."""
+    return cli_app_utils.session_extra(metadata) | mcp_tools.session_extra(metadata)
+
+
+def runtime_lines(state: Any, msg: Any, workspace: Path, *, skip: bool = False) -> list[str]:
+    """Return model-visible runtime annotations for turn-attached capabilities."""
+    return [
+        *cli_app_utils.runtime_lines(msg, workspace, skip=skip),
+        *mcp_tools.runtime_lines(
+            msg,
+            configured_server_names=set(state._mcp_servers),
+            connected_server_names=set(state._mcp_stacks),
+            skip=skip,
+        ),
+    ]
+
+
+async def connect_mcp(state: Any, tools: ToolRegistry) -> None:
+    await mcp_tools.connect_missing_servers(state, tools)
+
+
+async def handle_runtime_control(state: Any, msg: InboundMessage, tools: ToolRegistry) -> bool:
+    return await mcp_tools.handle_runtime_control(state, msg, tools)
+
+
 class ContextBuilder:
     """Builds the context (system prompt + messages) for the agent."""
 
@@ -39,11 +68,13 @@ class ContextBuilder:
         skill_names: list[str] | None = None,
         channel: str | None = None,
         session_summary: str | None = None,
+        workspace: Path | None = None,
     ) -> str:
         """Build the system prompt from identity, bootstrap files, memory, and skills."""
-        parts = [self._get_identity(channel=channel)]
+        root = workspace or self.workspace
+        parts = [self._get_identity(channel=channel, workspace=root)]
 
-        bootstrap = self._load_bootstrap_files()
+        bootstrap = self._load_bootstrap_files(root)
         if bootstrap:
             parts.append(bootstrap)
 
@@ -77,9 +108,10 @@ class ContextBuilder:
 
         return "\n\n---\n\n".join(parts)
 
-    def _get_identity(self, channel: str | None = None) -> str:
+    def _get_identity(self, channel: str | None = None, workspace: Path | None = None) -> str:
         """Get the core identity section."""
-        workspace_path = str(self.workspace.expanduser().resolve())
+        root = workspace or self.workspace
+        workspace_path = str(root.expanduser().resolve())
         system = platform.system()
         runtime = f"{'macOS' if system == 'Darwin' else system} {platform.machine()}, Python {platform.python_version()}"
 
@@ -123,12 +155,13 @@ class ContextBuilder:
 
         return _to_blocks(left) + _to_blocks(right)
 
-    def _load_bootstrap_files(self) -> str:
+    def _load_bootstrap_files(self, workspace: Path | None = None) -> str:
         """Load all bootstrap files from workspace."""
         parts = []
+        root = workspace or self.workspace
 
         for filename in self.BOOTSTRAP_FILES:
-            file_path = self.workspace / filename
+            file_path = root / filename
             if file_path.exists():
                 content = file_path.read_text(encoding="utf-8")
                 parts.append(f"## {filename}\n\n{content}")
@@ -138,10 +171,9 @@ class ContextBuilder:
     @staticmethod
     def _is_template_content(content: str, template_path: str) -> bool:
         """Check if *content* is identical to the bundled template (user hasn't customized it)."""
-        with suppress(Exception):
-            tpl = pkg_files("nanobot") / "templates" / template_path
-            if tpl.is_file():
-                return content.strip() == tpl.read_text(encoding="utf-8").strip()
+        tpl = load_bundled_template(template_path)
+        if tpl is not None:
+            return content.strip() == tpl.strip()
         return False
 
     def build_messages(
@@ -157,11 +189,18 @@ class ContextBuilder:
         session_summary: str | None = None,
         session_metadata: Mapping[str, Any] | None = None,
         current_runtime_lines: Sequence[str] | None = None,
+        workspace: Path | None = None,
+        runtime_state: Any | None = None,
+        inbound_message: Any | None = None,
+        skip_runtime_lines: bool = False,
     ) -> list[dict[str, Any]]:
         """Build the complete message list for an LLM call."""
+        root = workspace or self.workspace
         extra = [
             *goal_state_runtime_lines(session_metadata),
         ]
+        if runtime_state is not None and inbound_message is not None:
+            extra.extend(runtime_lines(runtime_state, inbound_message, root, skip=skip_runtime_lines))
         if current_runtime_lines:
             extra.extend(line for line in current_runtime_lines if line)
         runtime_ctx = self._build_runtime_context(
@@ -182,7 +221,15 @@ class ContextBuilder:
         else:
             merged = user_content + [{"type": "text", "text": runtime_ctx}]
         messages = [
-            {"role": "system", "content": self.build_system_prompt(skill_names, channel=channel, session_summary=session_summary)},
+            {
+                "role": "system",
+                "content": self.build_system_prompt(
+                    skill_names,
+                    channel=channel,
+                    session_summary=session_summary,
+                    workspace=root,
+                ),
+            },
             *history,
         ]
         if messages[-1].get("role") == current_role:

nanobot/agent/loop.py

@@ -14,6 +14,7 @@ from typing import TYPE_CHECKING, Any, Awaitable, Callable
 
 from loguru import logger
 
+from nanobot.agent import context as agent_context
 from nanobot.agent import model_presets as preset_helpers
 from nanobot.agent.autocompact import AutoCompact
 from nanobot.agent.context import ContextBuilder
@@ -22,19 +23,26 @@ from nanobot.agent.memory import Consolidator, Dream
 from nanobot.agent.progress_hook import AgentProgressHook
 from nanobot.agent.runner import _MAX_INJECTIONS_PER_TURN, AgentRunner, AgentRunSpec
 from nanobot.agent.subagent import SubagentManager
+from nanobot.agent.tools.context import RequestContext, bind_request_context, reset_request_context
 from nanobot.agent.tools.file_state import FileStateStore, bind_file_states, reset_file_states
 from nanobot.agent.tools.message import MessageTool
 from nanobot.agent.tools.registry import ToolRegistry
 from nanobot.agent.tools.self import MyTool
 from nanobot.bus.events import InboundMessage, OutboundMessage
 from nanobot.bus.queue import MessageBus
-from nanobot.cli_apps import utils as cli_app_utils
 from nanobot.command import CommandContext, CommandRouter, register_builtin_commands
 from nanobot.config.schema import AgentDefaults, ModelPresetConfig
 from nanobot.providers.base import LLMProvider
 from nanobot.providers.factory import ProviderSnapshot
+from nanobot.security.workspace_access import (
+    WorkspaceScopeResolver,
+    bind_workspace_scope,
+    reset_workspace_scope,
+)
 from nanobot.session.goal_state import (
+    goal_state_runtime_lines,
     runner_wall_llm_timeout_s,
+    sustained_goal_active,
 )
 from nanobot.session.manager import Session, SessionManager
 from nanobot.session.webui_turns import (
@@ -42,12 +50,15 @@ from nanobot.session.webui_turns import (
     build_bus_progress_callback,
     mark_webui_session,
 )
-from nanobot.utils.document import extract_documents
+from nanobot.utils.document import extract_documents, reference_non_image_attachments
 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.runtime import (
+    EMPTY_FINAL_RESPONSE_MESSAGE,
+    SUSTAINED_GOAL_CONTINUE_PROMPT,
+)
 
 if TYPE_CHECKING:
     from nanobot.config.schema import (
@@ -109,7 +120,6 @@ class TurnContext:
 
     pending_queue: asyncio.Queue | None = None
     pending_summary: str | None = None
-
     turn_wall_started_at: float = field(default_factory=time.time)
     turn_latency_ms: int | None = None
 
@@ -164,6 +174,7 @@ class AgentLoop:
         workspace: Path,
         model: str | None = None,
         max_iterations: int | None = None,
+        max_concurrent_subagents: int | None = None,
         context_window_tokens: int | None = None,
         context_block_limit: int | None = None,
         max_tool_result_chars: int | None = None,
@@ -235,6 +246,10 @@ class AgentLoop:
             self._image_generation_provider_configs["openrouter"] = image_generation_provider_config
         self.cron_service = cron_service
         self.restrict_to_workspace = restrict_to_workspace
+        self.workspace_scopes = WorkspaceScopeResolver(
+            default_workspace=workspace,
+            default_restrict_to_workspace=restrict_to_workspace,
+        )
         self._start_time = time.time()
         self._last_usage: dict[str, int] = {}
         self._pending_turn_latency_ms: dict[str, int] = {}
@@ -262,6 +277,7 @@ class AgentLoop:
             restrict_to_workspace=restrict_to_workspace,
             disabled_skills=disabled_skills,
             max_iterations=self.max_iterations,
+            max_concurrent_subagents=max_concurrent_subagents,
             llm_wall_timeout_for_session=lambda sk: runner_wall_llm_timeout_s(self.sessions, sk),
         )
         self._unified_session = unified_session
@@ -347,6 +363,7 @@ class AgentLoop:
             workspace=config.workspace_path,
             model=model,
             max_iterations=defaults.max_tool_iterations,
+            max_concurrent_subagents=defaults.max_concurrent_subagents,
             context_window_tokens=context_window_tokens,
             context_block_limit=defaults.context_block_limit,
             max_tool_result_chars=defaults.max_tool_result_chars,
@@ -462,6 +479,7 @@ class AgentLoop:
             provider_snapshot_loader=self._provider_snapshot_loader,
             image_generation_provider_configs=self._image_generation_provider_configs,
             timezone=self.context.timezone or "UTC",
+            workspace_sandbox=self.workspace_scopes.sandbox_status,
         )
         loader = ToolLoader()
         registered = loader.load(ctx, self.tools)
@@ -476,26 +494,8 @@ class AgentLoop:
         logger.info("Registered {} tools: {}", len(registered), registered)
 
     async def _connect_mcp(self) -> None:
-        """Connect to configured MCP servers (one-time, lazy)."""
-        if self._mcp_connected or self._mcp_connecting or not self._mcp_servers:
-            return
-        self._mcp_connecting = True
-        from nanobot.agent.tools.mcp import connect_mcp_servers
-
-        try:
-            self._mcp_stacks = await connect_mcp_servers(self._mcp_servers, self.tools)
-            if self._mcp_stacks:
-                self._mcp_connected = True
-            else:
-                logger.warning("No MCP servers connected successfully (will retry next message)")
-        except asyncio.CancelledError:
-            logger.warning("MCP connection cancelled (will retry next message)")
-            self._mcp_stacks.clear()
-        except BaseException as e:
-            logger.warning("Failed to connect MCP servers (will retry next message): {}", e)
-            self._mcp_stacks.clear()
-        finally:
-            self._mcp_connecting = False
+        """Connect configured MCP servers."""
+        await agent_context.connect_mcp(self, self.tools)
 
     def _set_tool_context(
         self, channel: str, chat_id: str,
@@ -503,7 +503,7 @@ class AgentLoop:
         session_key: str | None = None,
     ) -> None:
         """Update context for all tools that need routing info."""
-        from nanobot.agent.tools.context import ContextAware, RequestContext
+        from nanobot.agent.tools.context import ContextAware
 
         if session_key is not None:
             effective_key = session_key
@@ -568,7 +568,7 @@ class AgentLoop:
         media_paths = [p for p in (msg.media or []) if isinstance(p, str) and p]
         has_text = isinstance(msg.content, str) and msg.content.strip()
         if has_text or media_paths:
-            extra: dict[str, Any] = ({"media": list(media_paths)} if media_paths else {}) | cli_app_utils.session_extra(msg.metadata)
+            extra: dict[str, Any] = ({"media": list(media_paths)} if media_paths else {}) | agent_context.session_extra(msg.metadata)
             extra.update(kwargs)
             text = msg.content if isinstance(msg.content, str) else ""
             session.add_message("user", text, **extra)
@@ -585,6 +585,7 @@ class AgentLoop:
         pending_summary: str | None,
     ) -> list[dict[str, Any]]:
         """Build the initial message list for the LLM turn."""
+        scope = self.workspace_scopes.for_message(msg, session.metadata)
         return self.context.build_messages(
             history=history,
             current_message=image_generation_prompt(msg.content, msg.metadata),
@@ -593,7 +594,10 @@ class AgentLoop:
             chat_id=self._runtime_chat_id(msg),
             sender_id=msg.sender_id,
             session_summary=pending_summary,
-            session_metadata=session.metadata, current_runtime_lines=cli_app_utils.runtime_lines(msg, self.context.workspace),
+            session_metadata=session.metadata,
+            workspace=scope.project_path,
+            runtime_state=self,
+            inbound_message=msg,
         )
 
     async def _dispatch_command_inline(
@@ -707,7 +711,7 @@ class AgentLoop:
                 content = pending_msg.content
                 media = pending_msg.media if pending_msg.media else None
                 if media:
-                    content, media = extract_documents(content, media)
+                    content, media = self._prepare_message_media(content, media)
                     media = media or None
                 user_content = self.context._build_user_content(content, media)
                 return {"role": "user", "content": user_content}
@@ -743,7 +747,30 @@ class AgentLoop:
             return items
 
         active_session_key = session.key if session else session_key
+        effective_scope = self.workspace_scopes.for_turn(
+            channel=channel,
+            message_metadata=metadata,
+            session_metadata=session.metadata if session is not None else None,
+        )
+        request_ctx = RequestContext(
+            channel=channel,
+            chat_id=chat_id,
+            message_id=message_id,
+            session_key=active_session_key,
+            metadata=dict(metadata or {}),
+        )
         file_state_token = bind_file_states(self._file_state_store.for_session(active_session_key))
+        request_token = bind_request_context(request_ctx)
+        workspace_token = bind_workspace_scope(effective_scope)
+        # Build continuation message that embeds the active goal objective so
+        # the LLM can see it even if earlier Runtime Context was truncated.
+        _goal_lines = goal_state_runtime_lines(session.metadata if session is not None else None)
+        _goal_continue = (
+            "You have an active sustained goal:\n\n"
+            + "\n".join(_goal_lines)
+            + "\n\nPlease continue working toward the objective using your tools, "
+            "or call complete_goal if the work is truly finished."
+        ) if _goal_lines else SUSTAINED_GOAL_CONTINUE_PROMPT
         try:
             result = await self.runner.run(AgentRunSpec(
                 initial_messages=initial_messages,
@@ -754,7 +781,7 @@ class AgentLoop:
                 hook=hook,
                 error_message="Sorry, I encountered an error calling the AI model.",
                 concurrent_tools=True,
-                workspace=self.workspace,
+                workspace=effective_scope.project_path,
                 session_key=session.key if session else None,
                 context_window_tokens=self.context_window_tokens,
                 context_block_limit=self.context_block_limit,
@@ -771,8 +798,12 @@ class AgentLoop:
                     session.key if session is not None else session_key,
                     metadata=(session.metadata if session is not None else None),
                 ),
+                goal_active_predicate=lambda: sustained_goal_active(session.metadata) if session is not None else False,
+                goal_continue_message=_goal_continue,
             ))
         finally:
+            reset_workspace_scope(workspace_token)
+            reset_request_context(request_token)
             reset_file_states(file_state_token)
         self._last_usage = result.usage
         if result.stop_reason == "max_iterations":
@@ -812,13 +843,15 @@ class AgentLoop:
                 continue
 
             raw = msg.content.strip()
+            effective_key = self._effective_session_key(msg)
+            if await agent_context.handle_runtime_control(self, msg, self.tools):
+                continue
             if self.commands.is_priority(raw):
                 await self._dispatch_command_inline(
-                    msg, msg.session_key, raw,
+                    msg, effective_key, raw,
                     self.commands.dispatch_priority,
                 )
                 continue
-            effective_key = self._effective_session_key(msg)
             # If this session already has an active pending queue (i.e. a task
             # is processing this session), route the message there for mid-turn
             # injection instead of creating a competing task.
@@ -869,13 +902,13 @@ class AgentLoop:
         lock = self._session_locks.setdefault(session_key, asyncio.Lock())
         gate = self._concurrency_gate or nullcontext()
 
-        # Register a pending queue so follow-up messages for this session are
-        # routed here (mid-turn injection) instead of spawning a new task.
-        pending = asyncio.Queue(maxsize=20)
-        self._pending_queues[session_key] = pending
-
+        pending: asyncio.Queue | None = None
         try:
             async with lock, gate:
+                # Only the task that owns the session lock may publish the
+                # active mid-turn injection queue for this session.
+                pending = asyncio.Queue(maxsize=20)
+                self._pending_queues[session_key] = pending
                 try:
                     on_stream = on_stream_end = None
                     if msg.metadata.get("_wants_stream"):
@@ -959,28 +992,39 @@ class AgentLoop:
                         channel=msg.channel, chat_id=msg.chat_id,
                         content="Sorry, I encountered an error.",
                     ))
+                finally:
+                    # Drain any messages still in the pending queue and re-publish
+                    # them to the bus so they are processed as fresh inbound messages
+                    # rather than silently lost.  Only remove our own queue; a
+                    # later task waiting on the lock must not be able to steal
+                    # cleanup ownership.
+                    queue = None
+                    if self._pending_queues.get(session_key) is pending:
+                        queue = self._pending_queues.pop(session_key, None)
+                    else:
+                        queue = pending
+                    if queue is not None:
+                        leftover = 0
+                        while True:
+                            try:
+                                item = queue.get_nowait()
+                            except asyncio.QueueEmpty:
+                                break
+                            await self.bus.publish_inbound(item)
+                            leftover += 1
+                        if leftover:
+                            logger.info(
+                                "Re-published {} leftover message(s) to bus for session {}",
+                                leftover, session_key,
+                            )
+                    await self._webui_turns.publish_run_status(msg, "idle")
+                    self._pending_turn_latency_ms.pop(session_key, None)
+                    self._webui_turns.discard(session_key)
         finally:
-            # Drain any messages still in the pending queue and re-publish
-            # them to the bus so they are processed as fresh inbound messages
-            # rather than silently lost.
-            queue = self._pending_queues.pop(session_key, None)
-            if queue is not None:
-                leftover = 0
-                while True:
-                    try:
-                        item = queue.get_nowait()
-                    except asyncio.QueueEmpty:
-                        break
-                    await self.bus.publish_inbound(item)
-                    leftover += 1
-                if leftover:
-                    logger.info(
-                        "Re-published {} leftover message(s) to bus for session {}",
-                        leftover, session_key,
-                    )
-            await self._webui_turns.publish_run_status(msg, "idle")
-            self._pending_turn_latency_ms.pop(session_key, None)
-            self._webui_turns.discard(session_key)
+            if pending is None:
+                await self._webui_turns.publish_run_status(msg, "idle")
+                self._pending_turn_latency_ms.pop(session_key, None)
+                self._webui_turns.discard(session_key)
 
     async def close_mcp(self) -> None:
         """Drain pending background archives, then close MCP connections."""
@@ -1049,6 +1093,7 @@ class AgentLoop:
         }
         history = session.get_history(**_hist_kwargs)
         current_role = "assistant" if is_subagent else "user"
+        workspace_scope = self.workspace_scopes.for_message(msg, session.metadata)
 
         messages = self.context.build_messages(
             history=history,
@@ -1058,7 +1103,11 @@ class AgentLoop:
             current_role=current_role,
             sender_id=msg.sender_id,
             session_summary=pending,
-            session_metadata=session.metadata, current_runtime_lines=cli_app_utils.runtime_lines(msg, self.context.workspace, skip=is_subagent),
+            session_metadata=session.metadata,
+            workspace=workspace_scope.project_path,
+            runtime_state=self,
+            inbound_message=msg,
+            skip_runtime_lines=is_subagent,
         )
         t_wall = time.time()
         final_content, _, all_msgs, stop_reason, _ = await self._run_agent_loop(
@@ -1222,7 +1271,7 @@ class AgentLoop:
         msg = ctx.msg
 
         if msg.media:
-            new_content, image_only = extract_documents(msg.content, msg.media)
+            new_content, image_only = self._prepare_message_media(msg.content, msg.media)
             ctx.msg = dataclasses.replace(msg, content=new_content, media=image_only)
             msg = ctx.msg
 
@@ -1234,6 +1283,7 @@ class AgentLoop:
         if ctx.session is None:
             ctx.session = self.sessions.get_or_create(ctx.session_key)
         mark_webui_session(ctx.session, msg.metadata)
+        self.workspace_scopes.persist_message_scope(ctx.session, msg)
 
         if self._restore_runtime_checkpoint(ctx.session):
             self.sessions.save(ctx.session)
@@ -1242,6 +1292,16 @@ class AgentLoop:
 
         return "ok"
 
+    def _prepare_message_media(self, content: str, media: list[str]) -> tuple[str, list[str]]:
+        if self._should_extract_document_text():
+            return extract_documents(content, media)
+        return reference_non_image_attachments(content, media)
+
+    def _should_extract_document_text(self) -> bool:
+        if self.channels_config is None:
+            return True
+        return self.channels_config.extract_document_text
+
     async def _state_compact(self, ctx: TurnContext) -> str:
         ctx.session, pending = self.auto_compact.prepare_session(ctx.session, ctx.session_key)
         ctx.pending_summary = pending
@@ -1301,7 +1361,10 @@ class AgentLoop:
         )
 
         ctx.initial_messages = self._build_initial_messages(
-            ctx.msg, ctx.session, ctx.history, ctx.pending_summary
+            ctx.msg,
+            ctx.session,
+            ctx.history,
+            ctx.pending_summary,
         )
         ctx.user_persisted_early = self._persist_user_message_early(
             ctx.msg, ctx.session
@@ -1604,10 +1667,19 @@ class AgentLoop:
             channel=channel, sender_id="user", chat_id=chat_id,
             content=content, media=media or [],
         )
-        return await self._process_message(
-            msg,
-            session_key=session_key,
-            on_progress=on_progress,
-            on_stream=on_stream,
-            on_stream_end=on_stream_end,
-        )
+        # Share the dispatch lock so direct calls serialize with bus turns.
+        lock = self._session_locks.setdefault(session_key, asyncio.Lock())
+        try:
+            async with lock:
+                return await self._process_message(
+                    msg,
+                    session_key=session_key,
+                    on_progress=on_progress,
+                    on_stream=on_stream,
+                    on_stream_end=on_stream_end,
+                )
+        finally:
+            if channel == "websocket":
+                await self._webui_turns.publish_run_status(msg, "idle")
+                self._pending_turn_latency_ms.pop(session_key, None)
+                self._webui_turns.discard(session_key)

nanobot/agent/runner.py

@@ -8,7 +8,7 @@ import os
 from contextlib import suppress
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 
 from loguru import logger
 
@@ -16,12 +16,14 @@ from nanobot.agent.hook import AgentHook, AgentHookContext
 from nanobot.agent.tools.registry import ToolRegistry
 from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
 from nanobot.utils.file_edit_events import (
+    StreamingFileEditTracker,
     build_file_edit_end_event,
     build_file_edit_error_event,
     build_file_edit_start_event,
-    prepare_file_edit_tracker as _prepare_file_edit_tracker,
     prepare_file_edit_trackers,
-    StreamingFileEditTracker,
+)
+from nanobot.utils.file_edit_events import (
+    prepare_file_edit_tracker as _prepare_file_edit_tracker,
 )
 from nanobot.utils.helpers import (
     IncrementalThinkExtractor,
@@ -42,6 +44,7 @@ from nanobot.utils.prompt_templates import render_template
 from nanobot.utils.runtime import (
     EMPTY_FINAL_RESPONSE_MESSAGE,
     build_finalization_retry_message,
+    build_goal_continue_message,
     build_length_recovery_message,
     ensure_nonempty_tool_result,
     is_blank_text,
@@ -50,6 +53,10 @@ from nanobot.utils.runtime import (
 )
 
 _DEFAULT_ERROR_MESSAGE = "Sorry, I encountered an error calling the AI model."
+_ARREARAGE_ERROR_MESSAGE = (
+    "The AI provider rejected the request because the API key is out of quota or the "
+    "account is in arrears. Please top up / check the billing status of your API key and try again."
+)
 _PERSISTED_MODEL_ERROR_PLACEHOLDER = "[Assistant reply unavailable due to model error.]"
 _MAX_EMPTY_RETRIES = 2
 _MAX_LENGTH_RECOVERIES = 3
@@ -97,6 +104,8 @@ class AgentRunSpec:
     checkpoint_callback: Any | None = None
     injection_callback: Any | None = None
     llm_timeout_s: float | None = None
+    goal_active_predicate: Callable[[], bool] | None = None
+    goal_continue_message: str | None = None
 
 
 @dataclass(slots=True)
@@ -167,6 +176,7 @@ class AgentRunner:
         *,
         phase: str = "after error",
         iteration: int | None = None,
+        allow_goal_continue: bool = False,
     ) -> tuple[bool, int]:
         """Drain pending injections. Returns (should_continue, updated_cycles).
 
@@ -175,12 +185,19 @@ class AgentRunner:
         and *iteration* are both provided) and return (True, cycles+1) so the
         caller continues the iteration loop.  Otherwise return (False, cycles).
         """
-        if injection_cycles >= _MAX_INJECTION_CYCLES:
-            return False, injection_cycles
-        injections = await self._drain_injections(spec)
+        injections: list[dict[str, Any]] = []
+        real_injection = False
+        if injection_cycles < _MAX_INJECTION_CYCLES:
+            injections = await self._drain_injections(spec)
+            real_injection = bool(injections)
+        if not injections and allow_goal_continue and assistant_message is not None:
+            predicate = spec.goal_active_predicate
+            if predicate is not None and predicate():
+                injections = [build_goal_continue_message(spec.goal_continue_message)]
         if not injections:
             return False, injection_cycles
-        injection_cycles += 1
+        if real_injection:
+            injection_cycles += 1
         if assistant_message is not None:
             messages.append(assistant_message)
             if iteration is not None:
@@ -196,10 +213,13 @@ class AgentRunner:
                     },
                 )
         self._append_injected_messages(messages, injections)
-        logger.info(
-            "Injected {} follow-up message(s) {} ({}/{})",
-            len(injections), phase, injection_cycles, _MAX_INJECTION_CYCLES,
-        )
+        if real_injection:
+            logger.info(
+                "Injected {} follow-up message(s) {} ({}/{})",
+                len(injections), phase, injection_cycles, _MAX_INJECTION_CYCLES,
+            )
+        else:
+            logger.info("Injected sustained-goal continuation {}", phase)
         return True, injection_cycles
 
     async def _drain_injections(self, spec: AgentRunSpec) -> list[dict[str, Any]]:
@@ -475,6 +495,7 @@ class AgentRunner:
                 spec, messages, assistant_message, injection_cycles,
                 phase="after final response",
                 iteration=iteration,
+                allow_goal_continue=True,
             )
             if should_continue:
                 had_injections = True
@@ -487,7 +508,10 @@ class AgentRunner:
                 continue
 
             if response.finish_reason == "error":
-                final_content = clean or spec.error_message or _DEFAULT_ERROR_MESSAGE
+                if LLMProvider.is_arrearage_response(response):
+                    final_content = _ARREARAGE_ERROR_MESSAGE
+                else:
+                    final_content = clean or spec.error_message or _DEFAULT_ERROR_MESSAGE
                 stop_reason = "error"
                 error = final_content
                 self._append_model_error_placeholder(messages)
@@ -1256,7 +1280,13 @@ class AgentRunner:
             return messages
 
         system_tokens = sum(estimate_message_tokens(msg) for msg in system_messages)
-        remaining_budget = max(128, budget - system_tokens)
+        fixed_tokens, _ = estimate_prompt_tokens_chain(
+            self.provider,
+            spec.model,
+            system_messages,
+            spec.tools.get_definitions(),
+        )
+        remaining_budget = max(0, budget - max(system_tokens, fixed_tokens))
         kept: list[dict[str, Any]] = []
         kept_tokens = 0
         for message in reversed(non_system):

nanobot/agent/subagent.py

@@ -16,6 +16,12 @@ from nanobot.agent.tools.context import ToolContext
 from nanobot.agent.tools.file_state import FileStates
 from nanobot.agent.tools.loader import ToolLoader
 from nanobot.agent.tools.registry import ToolRegistry
+from nanobot.security.workspace_access import (
+    WorkspaceScope,
+    bind_workspace_scope,
+    reset_workspace_scope,
+    workspace_sandbox_status,
+)
 from nanobot.bus.events import InboundMessage
 from nanobot.bus.queue import MessageBus
 from nanobot.config.schema import AgentDefaults, ToolsConfig
@@ -79,6 +85,7 @@ class SubagentManager:
         restrict_to_workspace: bool = False,
         disabled_skills: list[str] | None = None,
         max_iterations: int | None = None,
+        max_concurrent_subagents: int | None = None,
         llm_wall_timeout_for_session: Callable[[str | None], float | None] | None = None,
     ):
         defaults = AgentDefaults()
@@ -95,7 +102,11 @@ class SubagentManager:
             if max_iterations is not None
             else defaults.max_tool_iterations
         )
-        self.max_concurrent_subagents = defaults.max_concurrent_subagents
+        self.max_concurrent_subagents = (
+            max_concurrent_subagents
+            if max_concurrent_subagents is not None
+            else defaults.max_concurrent_subagents
+        )
         self.runner = AgentRunner(provider)
         self._llm_wall_timeout_for_session = llm_wall_timeout_for_session
         self._running_tasks: dict[str, asyncio.Task[None]] = {}
@@ -123,6 +134,10 @@ class SubagentManager:
             config=cfg,
             workspace=str(root.resolve()),
             file_state_store=FileStates(),
+            workspace_sandbox=workspace_sandbox_status(
+                restrict_to_workspace=cfg.restrict_to_workspace,
+                workspace=root,
+            ),
         )
         ToolLoader().load(ctx, registry, scope="subagent")
         return registry
@@ -140,6 +155,8 @@ class SubagentManager:
         origin_chat_id: str = "direct",
         session_key: str | None = None,
         origin_message_id: str | None = None,
+        temperature: float | None = None,
+        workspace_scope: WorkspaceScope | None = None,
     ) -> str:
         """Spawn a subagent to execute a task in the background."""
         task_id = str(uuid.uuid4())[:8]
@@ -155,7 +172,16 @@ class SubagentManager:
         self._task_statuses[task_id] = status
 
         bg_task = asyncio.create_task(
-            self._run_subagent(task_id, task, display_label, origin, status, origin_message_id)
+            self._run_subagent(
+                task_id,
+                task,
+                display_label,
+                origin,
+                status,
+                origin_message_id,
+                temperature,
+                workspace_scope,
+            )
         )
         self._running_tasks[task_id] = bg_task
         if session_key:
@@ -182,6 +208,8 @@ class SubagentManager:
         origin: dict[str, str],
         status: SubagentStatus,
         origin_message_id: str | None = None,
+        temperature: float | None = None,
+        workspace_scope: WorkspaceScope | None = None,
     ) -> None:
         """Execute the subagent task and announce the result."""
         logger.info("Subagent [{}] starting task: {}", task_id, label)
@@ -191,8 +219,13 @@ class SubagentManager:
             status.iteration = payload.get("iteration", status.iteration)
 
         try:
-            tools = self._build_tools()
-            system_prompt = self._build_subagent_prompt()
+            root = workspace_scope.project_path if workspace_scope is not None else self.workspace
+            cfg = None
+            if workspace_scope is not None:
+                cfg = self._subagent_tools_config()
+                cfg.restrict_to_workspace = workspace_scope.restrict_to_workspace
+            tools = self._build_tools(workspace=root, tools_config=cfg)
+            system_prompt = self._build_subagent_prompt(workspace=root)
             messages: list[dict[str, Any]] = [
                 {"role": "system", "content": system_prompt},
                 {"role": "user", "content": task},
@@ -204,20 +237,27 @@ class SubagentManager:
                 if self._llm_wall_timeout_for_session
                 else None
             )
-            result = await self.runner.run(AgentRunSpec(
-                initial_messages=messages,
-                tools=tools,
-                model=self.model,
-                max_iterations=self.max_iterations,
-                max_tool_result_chars=self.max_tool_result_chars,
-                hook=_SubagentHook(task_id, status),
-                max_iterations_message="Task completed but no final response was generated.",
-                error_message=None,
-                fail_on_tool_error=True,
-                checkpoint_callback=_on_checkpoint,
-                session_key=sess_key,
-                llm_timeout_s=llm_timeout,
-            ))
+            token = bind_workspace_scope(workspace_scope) if workspace_scope is not None else None
+            try:
+                result = await self.runner.run(AgentRunSpec(
+                    initial_messages=messages,
+                    tools=tools,
+                    model=self.model,
+                    temperature=temperature,
+                    max_iterations=self.max_iterations,
+                    max_tool_result_chars=self.max_tool_result_chars,
+                    hook=_SubagentHook(task_id, status),
+                    max_iterations_message="Task completed but no final response was generated.",
+                    error_message=None,
+                    fail_on_tool_error=True,
+                    checkpoint_callback=_on_checkpoint,
+                    session_key=sess_key,
+                    workspace=root,
+                    llm_timeout_s=llm_timeout,
+                ))
+            finally:
+                if token is not None:
+                    reset_workspace_scope(token)
             status.phase = "done"
             status.stop_reason = result.stop_reason
 
@@ -311,20 +351,21 @@ class SubagentManager:
             lines.append(f"- {result.error}")
         return "\n".join(lines) or (result.error or "Error: subagent execution failed.")
 
-    def _build_subagent_prompt(self) -> str:
+    def _build_subagent_prompt(self, workspace: Path | None = None) -> str:
         """Build a focused system prompt for the subagent."""
         from nanobot.agent.context import ContextBuilder
         from nanobot.agent.skills import SkillsLoader
 
         time_ctx = ContextBuilder._build_runtime_context(None, None)
+        root = workspace or self.workspace
         skills_summary = SkillsLoader(
-            self.workspace,
+            root,
             disabled_skills=self.disabled_skills,
         ).build_skills_summary()
         return render_template(
             "agent/subagent_system.md",
             time_ctx=time_ctx,
-            workspace=str(self.workspace),
+            workspace=str(root),
             skills_summary=skills_summary or "",
         )
 

nanobot/agent/tools/apply_patch.py

@@ -88,11 +88,11 @@ def _format_summary(summary: _PatchSummary) -> str:
             items=ObjectSchema(
                 path=StringSchema("Relative path to the file to edit."),
                 action=StringSchema(
-                    "Operation type: replace (find and replace text), add (append new content or create file), delete (remove text).",
-                    enum=["replace", "add", "delete"],
+                    "Operation type: replace or add.",
+                    enum=["replace", "add"],
                 ),
                 old_text=StringSchema(
-                    "Exact text to search for in the file. Required for replace and delete.",
+                    "Exact text to search for in the file. Required for replace.",
                     nullable=True,
                 ),
                 new_text=StringSchema(
@@ -124,7 +124,8 @@ class ApplyPatchTool(_FsTool):
     def description(self) -> str:
         return (
             "Default tool for code edits. Supports multi-file changes in a single call. "
-            "Provide a list of structured edits, each specifying a file path, action (replace/add/delete), and the text to change. "
+            "Provide a list of structured edits, each specifying a file path, action "
+            "(replace/add), and the exact text to change. "
             "Paths must be relative. Set dry_run=true to validate and preview without writing files. "
             "Use edit_file only for small exact replacements on a single file."
         )
@@ -140,7 +141,6 @@ class ApplyPatchTool(_FsTool):
                 raise _PatchError("must provide edits")
 
             writes: dict[Path, str] = {}
-            deletes: set[Path] = set()
             summaries: list[_PatchSummary] = []
 
             for edit in edits:
@@ -183,7 +183,6 @@ class ApplyPatchTool(_FsTool):
                         if uses_crlf:
                             new_norm = new_norm.replace("\n", "\r\n")
                         writes[source] = new_norm
-                        deletes.discard(source)
                         added, deleted = _line_diff_stats(content, new_norm)
                         action_name = "update"
                     else:
@@ -191,7 +190,6 @@ class ApplyPatchTool(_FsTool):
                         if new_norm and not new_norm.endswith("\n"):
                             new_norm += "\n"
                         writes[source] = new_norm
-                        deletes.discard(source)
                         added = _text_line_count(new_norm)
                         deleted = 0
                         action_name = "add"
@@ -246,7 +244,6 @@ class ApplyPatchTool(_FsTool):
                         new_norm = new_norm.replace("\n", "\r\n")
 
                     writes[source] = new_norm
-                    deletes.discard(source)
                     added, deleted = _line_diff_stats(content, new_norm)
                     summaries.append(
                         _PatchSummary(
@@ -254,62 +251,6 @@ class ApplyPatchTool(_FsTool):
                         )
                     )
 
-                elif action == "delete":
-                    old_text = edit.get("old_text") or ""
-                    if not old_text:
-                        raise _PatchError(f"old_text required for delete: {path}")
-
-                    pending = writes.get(source)
-                    if pending is not None:
-                        content = pending
-                    elif source.exists():
-                        raw = source.read_bytes()
-                        try:
-                            content = raw.decode("utf-8")
-                        except UnicodeDecodeError:
-                            raise _PatchError(f"file is not UTF-8 text: {path}")
-                    else:
-                        raise _PatchError(f"file to update does not exist: {path}")
-
-                    if pending is None and not source.is_file():
-                        raise _PatchError(f"path to update is not a file: {path}")
-
-                    uses_crlf = "\r\n" in content
-                    norm_content = content.replace("\r\n", "\n")
-                    norm_old = old_text.replace("\r\n", "\n")
-
-                    pos = norm_content.find(norm_old)
-                    if pos < 0:
-                        raise _PatchError(f"old_text not found in {path}")
-                    if norm_content.find(norm_old, pos + 1) >= 0:
-                        raise _PatchError(f"old_text appears multiple times in {path}")
-
-                    if norm_old == norm_content:
-                        deletes.add(source)
-                        writes.pop(source, None)
-                        added, deleted = 0, _text_line_count(content)
-                        summaries.append(
-                            _PatchSummary(
-                                action="delete", path=path, added=added, deleted=deleted
-                            )
-                        )
-                    else:
-                        new_norm = (
-                            norm_content[:pos] + norm_content[pos + len(norm_old) :]
-                        )
-                        if new_norm and not new_norm.endswith("\n"):
-                            new_norm += "\n"
-                        if uses_crlf:
-                            new_norm = new_norm.replace("\n", "\r\n")
-                        writes[source] = new_norm
-                        deletes.discard(source)
-                        added, deleted = _line_diff_stats(content, new_norm)
-                        summaries.append(
-                            _PatchSummary(
-                                action="update", path=path, added=added, deleted=deleted
-                            )
-                        )
-
                 else:
                     raise _PatchError(f"unknown action: {action}")
 
@@ -319,13 +260,10 @@ class ApplyPatchTool(_FsTool):
                 )
 
             backups: dict[Path, bytes | None] = {}
-            for path in set(writes) | deletes:
+            for path in writes:
                 backups[path] = path.read_bytes() if path.exists() else None
 
             try:
-                for path in deletes:
-                    if path.exists():
-                        path.unlink()
                 for path, content in writes.items():
                     path.parent.mkdir(parents=True, exist_ok=True)
                     path.write_text(content, encoding="utf-8", newline="")
@@ -339,7 +277,7 @@ class ApplyPatchTool(_FsTool):
                         path.write_bytes(data)
                 raise
 
-            for path in set(writes) | deletes:
+            for path in writes:
                 self._file_states.record_write(path)
             return "Patch applied:\n" + "\n".join(
                 _format_summary(summary) for summary in summaries

nanobot/agent/tools/cli_apps.py

@@ -9,7 +9,8 @@ from pydantic import Field
 
 from nanobot.agent.tools.base import Tool, tool_parameters
 from nanobot.agent.tools.schema import ArraySchema, BooleanSchema, IntegerSchema, StringSchema, tool_parameters_schema
-from nanobot.cli_apps import CliAppError, CliAppManager, CliAppsRuntimeConfig
+from nanobot.security.workspace_access import current_tool_workspace
+from nanobot.apps.cli import CliAppError, CliAppManager, CliAppsRuntimeConfig
 from nanobot.config.schema import Base
 
 
@@ -113,7 +114,12 @@ class CliAppsTool(Tool):
         working_dir: str | None = None,
         timeout: int | None = None,
     ) -> str:
-        manager = CliAppManager(workspace=self.workspace, runtime=self.runtime)
+        access = current_tool_workspace(
+            self.workspace,
+            restrict_to_workspace=self.restrict_to_workspace,
+        )
+        workspace = access.project_path or self.workspace
+        manager = CliAppManager(workspace=workspace, runtime=self.runtime)
         try:
             return manager.run(
                 name,
@@ -121,7 +127,7 @@ class CliAppsTool(Tool):
                 json_output=bool(json),
                 working_dir=working_dir,
                 timeout=timeout,
-                restrict_to_workspace=self.restrict_to_workspace,
+                restrict_to_workspace=access.restrict_to_workspace,
             )
         except CliAppError as exc:
             return f"Error: {exc.message}"

nanobot/agent/tools/context.py

@@ -1,9 +1,15 @@
 """Runtime context for tool construction."""
 from __future__ import annotations
 
+from contextvars import ContextVar, Token
 from dataclasses import dataclass, field
 from typing import Any, Callable, Protocol, runtime_checkable
 
+_CURRENT_REQUEST_CONTEXT: ContextVar["RequestContext | None"] = ContextVar(
+    "nanobot_tool_request_context",
+    default=None,
+)
+
 
 @dataclass(frozen=True)
 class RequestContext:
@@ -21,6 +27,23 @@ class ContextAware(Protocol):
         ...
 
 
+def bind_request_context(ctx: RequestContext) -> Token[RequestContext | None]:
+    return _CURRENT_REQUEST_CONTEXT.set(ctx)
+
+
+def reset_request_context(token: Token[RequestContext | None]) -> None:
+    _CURRENT_REQUEST_CONTEXT.reset(token)
+
+
+def current_request_context() -> RequestContext | None:
+    return _CURRENT_REQUEST_CONTEXT.get()
+
+
+def current_request_session_key() -> str | None:
+    ctx = current_request_context()
+    return ctx.session_key if ctx else None
+
+
 @dataclass
 class ToolContext:
     config: Any
@@ -33,3 +56,4 @@ class ToolContext:
     provider_snapshot_loader: Callable[[], Any] | None = None
     image_generation_provider_configs: dict[str, Any] | None = None
     timezone: str = "UTC"
+    workspace_sandbox: Any | None = None

nanobot/agent/tools/exec_session.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import asyncio
-import shutil
 import time
 import uuid
 from contextlib import suppress
@@ -11,8 +10,13 @@ from dataclasses import dataclass
 from typing import Any
 
 from nanobot.agent.tools.base import Tool, tool_parameters
-from nanobot.agent.tools.schema import BooleanSchema, IntegerSchema, StringSchema, tool_parameters_schema
-
+from nanobot.agent.tools.context import current_request_session_key
+from nanobot.agent.tools.schema import (
+    BooleanSchema,
+    IntegerSchema,
+    StringSchema,
+    tool_parameters_schema,
+)
 
 DEFAULT_YIELD_MS = 1000
 MAX_YIELD_MS = 30_000
@@ -43,6 +47,7 @@ class ExecSessionInfo:
     idle_s: float
     remaining_s: float
     returncode: int | None
+    owner_session_key: str | None = None
 
 
 class _ExecSession:
@@ -53,14 +58,17 @@ class _ExecSession:
         process: asyncio.subprocess.Process,
         command: str,
         cwd: str,
-        timeout: int,
+        timeout: int | None,
+        owner_session_key: str | None = None,
     ) -> None:
         self.session_id = session_id
         self.process = process
         self.command = command
         self.cwd = cwd
+        self.owner_session_key = owner_session_key
         self.started_at = time.monotonic()
-        self.deadline = time.monotonic() + timeout
+        # timeout None/0 means no limit; an infinite deadline is never reached.
+        self.deadline = time.monotonic() + timeout if timeout else float("inf")
         self.last_access = time.monotonic()
         self._chunks: list[str] = []
         self._lock = asyncio.Lock()
@@ -169,11 +177,12 @@ class ExecSessionManager:
         command: str,
         cwd: str,
         env: dict[str, str],
-        timeout: int,
+        timeout: int | None,
         shell_program: str | None,
         login: bool,
         yield_time_ms: int,
         max_output_chars: int,
+        owner_session_key: str | None = None,
     ) -> tuple[str, _SessionPoll]:
         async with self._lock:
             await self._cleanup_locked()
@@ -187,6 +196,7 @@ class ExecSessionManager:
                 command=command,
                 cwd=cwd,
                 timeout=timeout,
+                owner_session_key=owner_session_key,
             )
             self._sessions[session_id] = session
 
@@ -205,12 +215,19 @@ class ExecSessionManager:
         terminate: bool,
         yield_time_ms: int,
         max_output_chars: int,
+        owner_session_key: str | None = None,
     ) -> _SessionPoll:
         async with self._lock:
             await self._cleanup_locked()
             session = self._sessions.get(session_id)
         if session is None:
             raise KeyError(session_id)
+        if (
+            owner_session_key
+            and session.owner_session_key
+            and session.owner_session_key != owner_session_key
+        ):
+            raise KeyError(session_id)
 
         if chars:
             error = await session.write(chars)
@@ -235,7 +252,7 @@ class ExecSessionManager:
                 self._sessions.pop(session_id, None)
         return poll
 
-    async def list(self) -> list[ExecSessionInfo]:
+    async def list(self, *, owner_session_key: str | None = None) -> list[ExecSessionInfo]:
         async with self._lock:
             await self._cleanup_locked()
             now = time.monotonic()
@@ -248,8 +265,12 @@ class ExecSessionManager:
                     idle_s=max(0.0, now - session.last_access),
                     remaining_s=max(0.0, session.deadline - now),
                     returncode=session.process.returncode,
+                    owner_session_key=session.owner_session_key,
                 )
                 for session_id, session in sorted(self._sessions.items())
+                if not owner_session_key
+                or not session.owner_session_key
+                or session.owner_session_key == owner_session_key
             ]
 
     async def _cleanup_locked(self) -> None:
@@ -271,29 +292,11 @@ class ExecSessionManager:
         shell_program: str | None,
         login: bool,
     ) -> asyncio.subprocess.Process:
-        from nanobot.agent.tools import shell
+        from nanobot.agent.tools.shell import ExecTool
 
-        if shell._IS_WINDOWS:
-            return await asyncio.create_subprocess_shell(
-                command,
-                stdin=asyncio.subprocess.PIPE,
-                stdout=asyncio.subprocess.PIPE,
-                stderr=asyncio.subprocess.PIPE,
-                cwd=cwd,
-                env=env,
-            )
-        shell_program = shell_program or shutil.which("bash") or "/bin/bash"
-        args = [shell_program]
-        if login and shell_program.rsplit("/", 1)[-1] in {"bash", "zsh"}:
-            args.append("-l")
-        args.extend(["-c", command])
-        return await asyncio.create_subprocess_exec(
-            *args,
+        return await ExecTool._spawn(
+            command, cwd, env, shell_program, login,
             stdin=asyncio.subprocess.PIPE,
-            stdout=asyncio.subprocess.PIPE,
-            stderr=asyncio.subprocess.PIPE,
-            cwd=cwd,
-            env=env,
         )
 
 
@@ -476,6 +479,7 @@ class WriteStdinTool(Tool):
                 terminate=terminate,
                 yield_time_ms=clamp_session_int(yield_time_ms, DEFAULT_YIELD_MS, 0, MAX_YIELD_MS),
                 max_output_chars=output_limit,
+                owner_session_key=current_request_session_key(),
             )
             return format_session_poll(session_id, poll)
         except KeyError:
@@ -509,6 +513,7 @@ class WriteStdinTool(Tool):
                 terminate=terminate if first else False,
                 yield_time_ms=step_ms,
                 max_output_chars=max_output_chars,
+                owner_session_key=current_request_session_key(),
             )
             first = False
             if poll.output:
@@ -572,7 +577,9 @@ class ListExecSessionsTool(Tool):
 
     async def execute(self, **kwargs: Any) -> str:
         try:
-            sessions = await self._manager.list()
+            sessions = await self._manager.list(
+                owner_session_key=current_request_session_key(),
+            )
             if not sessions:
                 return "No active exec sessions."
             lines = []

nanobot/agent/tools/filesystem.py

@@ -10,6 +10,7 @@ from typing import Any
 from nanobot.agent.tools.base import Tool, tool_parameters
 from nanobot.agent.tools.file_state import FileStates, _hash_file, current_file_states
 from nanobot.agent.tools.path_utils import resolve_workspace_path
+from nanobot.security.workspace_access import current_tool_workspace
 from nanobot.agent.tools.schema import (
     BooleanSchema,
     IntegerSchema,
@@ -28,10 +29,18 @@ class _FsTool(Tool):
         allowed_dir: Path | None = None,
         extra_allowed_dirs: list[Path] | None = None,
         file_states: FileStates | None = None,
+        restrict_to_workspace: bool | None = None,
+        sandbox_restricts_workspace: bool = False,
     ):
         self._workspace = workspace
         self._allowed_dir = allowed_dir
         self._extra_allowed_dirs = extra_allowed_dirs
+        self._restrict_to_workspace = (
+            bool(restrict_to_workspace)
+            if restrict_to_workspace is not None
+            else allowed_dir is not None
+        )
+        self._sandbox_restricts_workspace = sandbox_restricts_workspace
         # Explicit state is used by isolated runners like Dream/subagents.
         # Main AgentLoop tools leave this unset and resolve state from the
         # current async task, which keeps shared tool instances session-safe.
@@ -46,13 +55,16 @@ class _FsTool(Tool):
             ctx.config.restrict_to_workspace
             or ctx.config.exec.sandbox
         )
+        sandbox_restricts = bool(ctx.config.exec.sandbox)
         allowed_dir = Path(ctx.workspace) if restrict else None
-        extra_read = [BUILTIN_SKILLS_DIR] if allowed_dir else None
+        extra_read = [BUILTIN_SKILLS_DIR]
         return cls(
             workspace=Path(ctx.workspace),
             allowed_dir=allowed_dir,
             extra_allowed_dirs=extra_read,
             file_states=ctx.file_state_store,
+            restrict_to_workspace=ctx.config.restrict_to_workspace,
+            sandbox_restricts_workspace=sandbox_restricts,
         )
 
     @property
@@ -62,13 +74,21 @@ class _FsTool(Tool):
         return current_file_states(self._fallback_file_states)
 
     def _resolve(self, path: str) -> Path:
+        access = current_tool_workspace(
+            self._workspace,
+            restrict_to_workspace=self._restrict_to_workspace,
+            sandbox_restricts_workspace=self._sandbox_restricts_workspace,
+        )
         return resolve_workspace_path(
             path,
-            self._workspace,
-            self._allowed_dir,
+            access.project_path,
+            access.allowed_root,
             self._extra_allowed_dirs,
         )
 
+    def _display_workspace(self) -> Path | None:
+        return current_tool_workspace(self._workspace).project_path
+
 
 # ---------------------------------------------------------------------------
 # read_file

nanobot/agent/tools/image_generation.py

@@ -14,6 +14,7 @@ from nanobot.agent.tools.schema import (
     StringSchema,
     tool_parameters_schema,
 )
+from nanobot.security.workspace_access import current_tool_workspace
 from nanobot.config.paths import get_media_dir
 from nanobot.config.schema import Base
 from nanobot.providers.image_generation import (
@@ -21,6 +22,7 @@ from nanobot.providers.image_generation import (
     ImageGenerationProvider,
     get_image_gen_provider,
 )
+from nanobot.security.workspace_policy import WorkspaceBoundaryError, resolve_allowed_path
 from nanobot.utils.artifacts import (
     ArtifactError,
     generated_image_tool_result,
@@ -131,18 +133,22 @@ class ImageGenerationTool(Tool):
         return cls(**kwargs)
 
     def _resolve_reference_image(self, value: str) -> str:
-        raw_path = Path(value).expanduser()
-        path = raw_path if raw_path.is_absolute() else self.workspace / raw_path
+        access = current_tool_workspace(self.workspace, restrict_to_workspace=True)
+        workspace = access.project_path or self.workspace
         try:
-            resolved = path.resolve(strict=True)
-        except OSError as exc:
-            raise ImageGenerationError(f"reference image not found: {value}") from exc
-
-        allowed_roots = [self.workspace.resolve(), get_media_dir().resolve()]
-        if not any(_is_relative_to(resolved, root) for root in allowed_roots):
+            resolved = resolve_allowed_path(
+                value,
+                workspace=workspace,
+                allowed_root=access.allowed_root,
+                extra_allowed_roots=[get_media_dir()] if access.allowed_root is not None else None,
+                strict=True,
+            )
+        except WorkspaceBoundaryError as exc:
             raise ImageGenerationError(
                 "reference_images must be inside the workspace or nanobot media directory"
-            )
+            ) from exc
+        except OSError as exc:
+            raise ImageGenerationError(f"reference image not found: {value}") from exc
         if not resolved.is_file():
             raise ImageGenerationError(f"reference image is not a file: {value}")
         raw = resolved.read_bytes()
@@ -201,11 +207,3 @@ class ImageGenerationTool(Tool):
             return generated_image_tool_result(artifacts)
         except (ArtifactError, ImageGenerationError, OSError) as exc:
             return f"Error: {exc}"
-
-
-def _is_relative_to(path: Path, root: Path) -> bool:
-    try:
-        path.relative_to(root)
-    except ValueError:
-        return False
-    return True

nanobot/agent/tools/long_task.py

@@ -16,6 +16,7 @@ There is **no** sub-agent orchestrator and **no** special WebSocket ``agent_ui``
 
 from __future__ import annotations
 
+from contextvars import ContextVar
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
@@ -45,15 +46,22 @@ class _GoalToolsMixin(ContextAware):
     def __init__(self, sessions: SessionManager, bus: Any | None = None) -> None:
         self._sessions = sessions
         self._bus = bus
-        self._request_ctx: RequestContext | None = None
+        # Each subclass gets its own ContextVar so concurrent tasks across
+        # different tool types (LongTaskTool vs CompleteGoalTool) do not
+        # interfere with each other.
+        self._request_ctx: ContextVar[RequestContext | None] = ContextVar(
+            f"{self.__class__.__name__}_request_ctx",
+            default=None,
+        )
 
     def set_context(self, ctx: RequestContext) -> None:
-        self._request_ctx = ctx
+        self._request_ctx.set(ctx)
 
     def _session(self):
-        if self._request_ctx is None:
+        request_ctx = self._request_ctx.get()
+        if request_ctx is None:
             return None
-        key = self._request_ctx.session_key
+        key = request_ctx.session_key
         if not key:
             return None
         return self._sessions.get_or_create(key)
@@ -61,7 +69,7 @@ class _GoalToolsMixin(ContextAware):
     async def _publish_goal_state_ws(self, metadata: dict[str, Any]) -> None:
         """Fan-out authoritative goal snapshot for this WebSocket chat only."""
         bus = self._bus
-        rc = self._request_ctx
+        rc = self._request_ctx.get()
         if bus is None or rc is None or rc.channel != "websocket":
             return
         cid = (rc.chat_id or "").strip()
@@ -224,4 +232,3 @@ class CompleteGoalTool(Tool, _GoalToolsMixin):
         if tail:
             return f"Goal marked complete ({ended}). Recap:\n{tail}"
         return f"Goal marked complete ({ended})."
-

nanobot/agent/tools/mcp.py

@@ -6,13 +6,20 @@ import re
 import shutil
 import urllib.parse
 from contextlib import AsyncExitStack, suppress
-from typing import Any
+from typing import Any, Mapping
+from weakref import WeakKeyDictionary
 
 import httpx
 from loguru import logger
 
 from nanobot.agent.tools.base import Tool
 from nanobot.agent.tools.registry import ToolRegistry
+from nanobot.bus.events import (
+    INBOUND_META_RUNTIME_CONTROL,
+    RUNTIME_CONTROL_ACK,
+    RUNTIME_CONTROL_MCP_RELOAD,
+    InboundMessage,
+)
 
 # Transient connection errors that warrant a single retry.
 # These typically happen when an MCP server restarts or a network
@@ -33,6 +40,7 @@ _WINDOWS_SHELL_LAUNCHERS: frozenset[str] = frozenset(("npx", "npm", "pnpm", "yar
 # Characters allowed in tool names by model providers (Anthropic, OpenAI, etc.).
 # Replace anything outside [a-zA-Z0-9_-] with underscore and collapse runs.
 _SANITIZE_RE = re.compile(r"_+")
+_RELOAD_LOCKS: WeakKeyDictionary[Any, asyncio.Lock] = WeakKeyDictionary()
 
 
 def _sanitize_name(name: str) -> str:
@@ -503,6 +511,7 @@ async def connect_mcp_servers(
                     command=command,
                     args=args,
                     env=env,
+                    cwd=cfg.cwd or None,
                 )
                 read, write = await server_stack.enter_async_context(stdio_client(params))
             elif transport_type == "sse":
@@ -662,3 +671,272 @@ async def connect_mcp_servers(
             server_stacks[result[0]] = result[1]
 
     return server_stacks
+
+
+def session_extra(metadata: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Return persisted session kwargs for MCP preset attachments."""
+    mcp_presets = metadata.get("mcp_presets") if isinstance(metadata, Mapping) else None
+    return {"mcp_presets": mcp_presets} if isinstance(mcp_presets, list) and mcp_presets else {}
+
+
+def runtime_lines(
+    message: Any,
+    *,
+    available_server_names: set[str] | None = None,
+    configured_server_names: set[str] | None = None,
+    connected_server_names: set[str] | None = None,
+    skip: bool = False,
+) -> list[str]:
+    """Return model-visible MCP preset annotations for the current turn."""
+    if skip:
+        return []
+    if configured_server_names is None:
+        configured_server_names = available_server_names
+    if connected_server_names is None:
+        connected_server_names = available_server_names
+    metadata = message.metadata if isinstance(getattr(message, "metadata", None), Mapping) else None
+    structured = metadata.get("mcp_presets") if isinstance(metadata, Mapping) else None
+    if not isinstance(structured, list):
+        return []
+
+    lines: list[str] = []
+    for item in structured[:8]:
+        if not isinstance(item, Mapping):
+            continue
+        raw_name = str(item.get("name") or "").strip().lower()
+        if not raw_name:
+            continue
+        display = str(item.get("display_name") or raw_name).strip() or raw_name
+        transport = str(item.get("transport") or "mcp").strip() or "mcp"
+        prefix = f"mcp_{raw_name}_"
+        if configured_server_names is not None and raw_name not in configured_server_names:
+            lines.append(
+                "MCP Preset Attachment: "
+                f"@{raw_name} ({display}; transport={transport}) is configured in WebUI Settings, "
+                "but this gateway has not loaded the latest MCP settings yet. "
+                f"Tools with prefix `{prefix}` may not be available yet; if they are missing, "
+                "tell the user to restart nanobot."
+            )
+            continue
+        if connected_server_names is not None and raw_name not in connected_server_names:
+            lines.append(
+                "MCP Preset Attachment: "
+                f"@{raw_name} ({display}; transport={transport}) is configured, "
+                "but its MCP connection is not currently live. "
+                f"Tools with prefix `{prefix}` may be unavailable; tell the user to open Settings, "
+                "run the preset test, and restart nanobot only if hot reload is unavailable."
+            )
+            continue
+        lines.append(
+            "MCP Preset Attachment: "
+            f"@{raw_name} ({display}; transport={transport}; tool_prefix={prefix}). "
+            f"Prefer available tools whose names start with `{prefix}` for this request; "
+            "do not substitute shell commands for this MCP integration unless the user asks."
+        )
+    return lines
+
+
+async def connect_missing_servers(state: Any, registry: ToolRegistry) -> None:
+    """Connect configured MCP servers that are not currently live."""
+    missing_servers = {
+        name: cfg for name, cfg in state._mcp_servers.items() if name not in state._mcp_stacks
+    }
+    if state._mcp_connecting or not missing_servers:
+        return
+    state._mcp_connecting = True
+    try:
+        connected = await connect_mcp_servers(missing_servers, registry)
+        state._mcp_stacks.update(connected)
+        state._mcp_connected = bool(state._mcp_stacks)
+        if connected:
+            logger.info("MCP connected servers: {}", sorted(connected))
+        else:
+            logger.warning("No MCP servers connected successfully (will retry next message)")
+    except asyncio.CancelledError:
+        logger.warning("MCP connection cancelled (will retry next message)")
+        state._mcp_connected = bool(state._mcp_stacks)
+    except BaseException as e:
+        logger.warning("Failed to connect MCP servers (will retry next message): {}", e)
+        state._mcp_connected = bool(state._mcp_stacks)
+    finally:
+        state._mcp_connecting = False
+
+
+async def reload_servers(state: Any, registry: ToolRegistry) -> dict[str, Any]:
+    """Reconcile live MCP connections with the current config file."""
+    async with _reload_lock(state):
+        try:
+            from nanobot.config.loader import (load_config,
+                                               resolve_config_env_vars)
+
+            config = resolve_config_env_vars(load_config())
+            next_servers = dict(config.tools.mcp_servers)
+        except Exception as exc:
+            logger.warning("MCP hot reload could not read config: {}", exc)
+            return {
+                "ok": False,
+                "message": "Could not reload MCP config. Restart nanobot to pick up changes.",
+                "requires_restart": True,
+                "error": str(exc),
+            }
+
+        current_servers = dict(state._mcp_servers)
+        current_names = set(current_servers)
+        next_names = set(next_servers)
+        removed = sorted(current_names - next_names)
+        added = sorted(next_names - current_names)
+        changed = sorted(
+            name
+            for name in current_names & next_names
+            if _server_signature(current_servers[name]) != _server_signature(next_servers[name])
+        )
+
+        tools_removed = 0
+        for name in [*removed, *changed]:
+            tools_removed += _unregister_server_tools(state, registry, name)
+            await _close_server(state, name)
+
+        state._mcp_servers = next_servers
+        retry_missing = sorted(
+            name
+            for name in next_names
+            if name not in state._mcp_stacks and name not in set(added) | set(changed)
+        )
+        to_connect_names = sorted(set(added) | set(changed) | set(retry_missing))
+        to_connect = {name: next_servers[name] for name in to_connect_names}
+        connected: dict[str, AsyncExitStack] = {}
+        if to_connect:
+            connected = await connect_mcp_servers(to_connect, registry)
+            state._mcp_stacks.update(connected)
+
+        state._mcp_connected = bool(state._mcp_stacks)
+        failed = sorted(set(to_connect) - set(connected))
+        unchanged = not removed and not added and not changed and not retry_missing
+        ok = not failed
+        if failed:
+            message = "MCP config reloaded, but some servers did not connect: " + ", ".join(failed)
+        elif unchanged:
+            message = "MCP config is already live."
+        elif retry_missing and not added and not changed and not removed:
+            message = "MCP connections refreshed without restarting nanobot."
+        else:
+            message = "MCP config reloaded without restarting nanobot."
+
+        logger.info(
+            "MCP hot reload: added={} changed={} removed={} retried={} connected={} failed={} tools_removed={}",
+            added,
+            changed,
+            removed,
+            retry_missing,
+            sorted(connected),
+            failed,
+            tools_removed,
+        )
+        return {
+            "ok": ok,
+            "message": message,
+            "added": added,
+            "changed": changed,
+            "removed": removed,
+            "retried": retry_missing,
+            "connected": sorted(state._mcp_stacks),
+            "configured": sorted(state._mcp_servers),
+            "failed": failed,
+            "tools_removed": tools_removed,
+            "requires_restart": False,
+        }
+
+
+async def request_mcp_reload(bus: Any, *, timeout: float = 15.0) -> dict[str, Any]:
+    """Ask the running agent loop to reconcile live MCP connections."""
+    loop = asyncio.get_running_loop()
+    ack: asyncio.Future[dict[str, Any]] = loop.create_future()
+    await bus.publish_inbound(
+        InboundMessage(
+            channel="system",
+            sender_id="webui-settings",
+            chat_id="runtime",
+            content=RUNTIME_CONTROL_MCP_RELOAD,
+            metadata={
+                INBOUND_META_RUNTIME_CONTROL: RUNTIME_CONTROL_MCP_RELOAD,
+                RUNTIME_CONTROL_ACK: ack,
+            },
+        )
+    )
+    try:
+        result = await asyncio.wait_for(ack, timeout=timeout)
+    except asyncio.TimeoutError:
+        return {
+            "ok": False,
+            "message": "MCP hot reload timed out. Restart nanobot to pick up changes.",
+            "requires_restart": True,
+        }
+    return result if isinstance(result, dict) else {
+        "ok": False,
+        "message": "MCP hot reload returned an unexpected response.",
+        "requires_restart": True,
+    }
+
+
+async def handle_runtime_control(state: Any, msg: InboundMessage, registry: ToolRegistry) -> bool:
+    metadata = msg.metadata if isinstance(msg.metadata, dict) else {}
+    control = metadata.get(INBOUND_META_RUNTIME_CONTROL)
+    if control != RUNTIME_CONTROL_MCP_RELOAD:
+        return False
+
+    ack = metadata.get(RUNTIME_CONTROL_ACK)
+    try:
+        result = await reload_servers(state, registry)
+    except Exception as exc:
+        logger.exception("MCP hot reload failed")
+        result = {
+            "ok": False,
+            "message": "MCP hot reload failed. Restart nanobot to pick up changes.",
+            "requires_restart": True,
+            "error": str(exc),
+        }
+    if isinstance(ack, asyncio.Future) and not ack.done():
+        ack.set_result(result)
+    return True
+
+
+def _reload_lock(state: Any) -> asyncio.Lock:
+    try:
+        return _RELOAD_LOCKS[state]
+    except KeyError:
+        lock = asyncio.Lock()
+        _RELOAD_LOCKS[state] = lock
+        return lock
+
+
+def _server_signature(cfg: Any) -> Any:
+    if hasattr(cfg, "model_dump"):
+        return cfg.model_dump(mode="json")
+    return cfg
+
+
+def _tool_prefix(server_name: str) -> str:
+    safe_name = "".join(ch if ch.isalnum() or ch in {"_", "-"} else "_" for ch in server_name)
+    while "__" in safe_name:
+        safe_name = safe_name.replace("__", "_")
+    return f"mcp_{safe_name}_"
+
+
+def _unregister_server_tools(state: Any, registry: ToolRegistry, server_name: str) -> int:
+    prefix = _tool_prefix(server_name)
+    removed = 0
+    for tool_name in list(registry.tool_names):
+        if tool_name.startswith(prefix):
+            registry.unregister(tool_name)
+            removed += 1
+    return removed
+
+
+async def _close_server(state: Any, server_name: str) -> None:
+    stack = state._mcp_stacks.pop(server_name, None)
+    if stack is None:
+        return
+    try:
+        await stack.aclose()
+    except (RuntimeError, BaseExceptionGroup):
+        logger.debug("MCP server '{}' cleanup error (can be ignored)", server_name)

nanobot/agent/tools/message.py

@@ -8,6 +8,7 @@ from nanobot.agent.tools.base import Tool, tool_parameters
 from nanobot.agent.tools.context import ContextAware, RequestContext
 from nanobot.agent.tools.path_utils import resolve_workspace_path
 from nanobot.agent.tools.schema import ArraySchema, StringSchema, tool_parameters_schema
+from nanobot.security.workspace_access import current_tool_workspace
 from nanobot.bus.events import OutboundMessage
 from nanobot.config.paths import get_workspace_path
 
@@ -82,6 +83,10 @@ class MessageTool(Tool, ContextAware):
             "message_record_channel_delivery",
             default=False,
         )
+        self._suppress_delivery_var: ContextVar[bool] = ContextVar(
+            "message_suppress_delivery",
+            default=False,
+        )
 
     @classmethod
     def create(cls, ctx: Any) -> Tool:
@@ -120,6 +125,14 @@ class MessageTool(Tool, ContextAware):
         """Restore previous proactive delivery recording state."""
         self._record_channel_delivery_var.reset(token)
 
+    def set_suppress_delivery(self, active: bool):
+        """Temporarily suppress real channel delivery for internal checks."""
+        return self._suppress_delivery_var.set(active)
+
+    def reset_suppress_delivery(self, token) -> None:
+        """Restore previous channel delivery suppression state."""
+        self._suppress_delivery_var.reset(token)
+
     @property
     def _sent_in_turn(self) -> bool:
         return self._sent_in_turn_var.get()
@@ -149,15 +162,19 @@ class MessageTool(Tool, ContextAware):
     def _resolve_media(self, media: list[str]) -> list[str]:
         """Resolve local media attachments and enforce workspace restriction when enabled."""
         resolved: list[str] = []
-        allowed_dir = self._workspace if self._restrict_to_workspace else None
+        access = current_tool_workspace(
+            self._workspace,
+            restrict_to_workspace=self._restrict_to_workspace,
+        )
+        workspace = access.project_path or self._workspace
         for p in media:
             if p.startswith(("http://", "https://")):
                 resolved.append(p)
-            elif not self._restrict_to_workspace:
+            elif not access.restrict_to_workspace:
                 path = Path(p).expanduser()
-                resolved.append(p if path.is_absolute() else str(self._workspace / path))
+                resolved.append(p if path.is_absolute() else str(workspace / path))
             else:
-                resolved.append(str(resolve_workspace_path(p, self._workspace, allowed_dir)))
+                resolved.append(str(resolve_workspace_path(p, workspace, access.allowed_root)))
         return resolved
 
     async def execute(
@@ -212,6 +229,9 @@ class MessageTool(Tool, ContextAware):
         if not channel or not chat_id:
             return "Error: No target channel/chat specified"
 
+        if self._suppress_delivery_var.get():
+            return "Message suppressed during internal check"
+
         if not self._send_callback:
             return "Error: Message sending not configured"
 

nanobot/agent/tools/path_utils.py

@@ -3,21 +3,15 @@
 from pathlib import Path
 
 from nanobot.config.paths import get_media_dir
-
-WORKSPACE_BOUNDARY_NOTE = (
-    " (this is a hard policy boundary, not a transient failure; "
-    "do not retry with shell tricks or alternative tools, and ask "
-    "the user how to proceed if the resource is genuinely required)"
+from nanobot.security.workspace_policy import (
+    is_path_within,
+    resolve_allowed_path,
 )
 
 
 def is_under(path: Path, directory: Path) -> bool:
     """Return True when path resolves under directory."""
-    try:
-        path.relative_to(directory.resolve())
-        return True
-    except ValueError:
-        return False
+    return is_path_within(path, directory)
 
 
 def resolve_workspace_path(
@@ -27,16 +21,10 @@ def resolve_workspace_path(
     extra_allowed_dirs: list[Path] | None = None,
 ) -> Path:
     """Resolve path against workspace and enforce allowed directory containment."""
-    p = Path(path).expanduser()
-    if not p.is_absolute() and workspace:
-        p = workspace / p
-    resolved = p.resolve()
-    if allowed_dir:
-        media_path = get_media_dir().resolve()
-        all_dirs = [allowed_dir, media_path, *(extra_allowed_dirs or [])]
-        if not any(is_under(resolved, d) for d in all_dirs):
-            raise PermissionError(
-                f"Path {path} is outside allowed directory {allowed_dir}"
-                + WORKSPACE_BOUNDARY_NOTE
-            )
-    return resolved
+    extra_roots = [get_media_dir(), *(extra_allowed_dirs or [])] if allowed_dir else None
+    return resolve_allowed_path(
+        path,
+        workspace=workspace,
+        allowed_root=allowed_dir,
+        extra_allowed_roots=extra_roots,
+    )

nanobot/agent/tools/runtime_state.py

@@ -42,6 +42,9 @@ class RuntimeState(Protocol):
     @property
     def exec_config(self) -> Any: ...
 
+    @property
+    def workspace_sandbox(self) -> Any: ...
+
     @property
     def subagents(self) -> Any: ...
 

nanobot/agent/tools/search.py

@@ -101,9 +101,10 @@ class _SearchTool(_FsTool):
     _IGNORE_DIRS = set(ListDirTool._IGNORE_DIRS)
 
     def _display_path(self, target: Path, root: Path) -> str:
-        if self._workspace:
+        workspace = self._display_workspace()
+        if workspace:
             with suppress(ValueError):
-                return target.relative_to(self._workspace).as_posix()
+                return target.relative_to(workspace).as_posix()
         return target.relative_to(root).as_posix()
 
     def _iter_files(self, root: Path) -> Iterable[Path]:

nanobot/agent/tools/self.py

@@ -3,16 +3,18 @@
 from __future__ import annotations
 
 import time
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from loguru import logger
 
-from nanobot.agent.subagent import SubagentStatus
 from nanobot.agent.tools.base import Tool
 from nanobot.agent.tools.context import ContextAware, RequestContext
 from nanobot.agent.tools.runtime_state import RuntimeState
 from nanobot.config.schema import Base
 
+if TYPE_CHECKING:
+    from nanobot.agent.subagent import SubagentStatus
+
 
 class MyToolConfig(Base):
     """Self-inspection tool configuration."""
@@ -33,6 +35,12 @@ def _has_real_attr(obj: Any, key: str) -> bool:
     return False
 
 
+def _is_subagent_status(value: Any) -> bool:
+    from nanobot.agent.subagent import SubagentStatus
+
+    return isinstance(value, SubagentStatus)
+
+
 class MyTool(Tool, ContextAware):
     """Check and set the agent loop's runtime configuration."""
 
@@ -68,6 +76,7 @@ class MyTool(Tool, ContextAware):
         "_current_iteration",  # updated by runner only
         "exec_config",  # inspect allowed (e.g. check sandbox), modify blocked
         "web_config",  # inspect allowed (e.g. check enable), modify blocked
+        "workspace_sandbox",  # read-only view of workspace enforcement level
     })
 
     _DENIED_ATTRS = frozenset({
@@ -214,7 +223,7 @@ class MyTool(Tool, ContextAware):
     # ------------------------------------------------------------------
 
     @staticmethod
-    def _format_status(st: SubagentStatus, indent: str = "  ") -> str:
+    def _format_status(st: "SubagentStatus", indent: str = "  ") -> str:
         elapsed = time.monotonic() - st.started_at
         tool_summary = ", ".join(
             f"{e.get('name', '?')}({e.get('status', '?')})" for e in st.tool_events[-5:]
@@ -232,14 +241,14 @@ class MyTool(Tool, ContextAware):
 
     @staticmethod
     def _format_value(val: Any, key: str = "") -> str:
-        if isinstance(val, SubagentStatus):
+        if _is_subagent_status(val):
             header = f"Subagent [{val.task_id}] '{val.label}'"
             detail = MyTool._format_status(val, "  ")
             return f"{header}\n  task: {val.task_description}\n{detail}"
         # SubagentManager: delegate to its _task_statuses dict
         if hasattr(val, "_task_statuses") and isinstance(val._task_statuses, dict):
             return MyTool._format_value(val._task_statuses, key)
-        if isinstance(val, dict) and val and isinstance(next(iter(val.values())), SubagentStatus):
+        if isinstance(val, dict) and val and _is_subagent_status(next(iter(val.values()))):
             prefix = f"{key}: " if key else ""
             lines = [f"{prefix}{len(val)} subagent(s):"]
             for tid, st in val.items():
@@ -349,7 +358,7 @@ class MyTool(Tool, ContextAware):
             parts.append(self._format_value(getattr(state, k, None), k))
         parts.append(self._format_value(state.model_preset, "model_preset"))
         # Other useful top-level keys shown in description
-        for k in ("workspace", "provider_retry_mode", "max_tool_result_chars", "_current_iteration", "web_config", "exec_config", "subagents"):
+        for k in ("workspace", "provider_retry_mode", "max_tool_result_chars", "_current_iteration", "web_config", "exec_config", "workspace_sandbox", "subagents"):
             if _has_real_attr(state, k):
                 parts.append(self._format_value(getattr(state, k, None), k))
         # Token usage

nanobot/agent/tools/shell.py

@@ -16,19 +16,27 @@ from loguru import logger
 from pydantic import Field
 
 from nanobot.agent.tools.base import Tool, tool_parameters
+from nanobot.agent.tools.context import current_request_session_key
 from nanobot.agent.tools.exec_session import (
+    DEFAULT_EXEC_SESSION_MANAGER,
     DEFAULT_MAX_OUTPUT_CHARS,
     DEFAULT_YIELD_MS,
-    DEFAULT_EXEC_SESSION_MANAGER,
     MAX_OUTPUT_CHARS,
     MAX_YIELD_MS,
     clamp_session_int,
     format_session_poll,
 )
 from nanobot.agent.tools.sandbox import wrap_command
-from nanobot.agent.tools.schema import BooleanSchema, IntegerSchema, StringSchema, tool_parameters_schema
+from nanobot.agent.tools.schema import (
+    BooleanSchema,
+    IntegerSchema,
+    StringSchema,
+    tool_parameters_schema,
+)
 from nanobot.config.paths import get_media_dir
 from nanobot.config.schema import Base
+from nanobot.security.workspace_access import current_scope_allows_loopback, current_tool_workspace
+from nanobot.security.workspace_policy import is_path_within
 
 _IS_WINDOWS = sys.platform == "win32"
 
@@ -46,7 +54,7 @@ _WORKSPACE_BOUNDARY_NOTE = (
 class ExecToolConfig(Base):
     """Shell exec tool configuration."""
     enable: bool = True
-    timeout: int = 60
+    timeout: int = Field(default=60, ge=0)  # Hard timeout (s); 0 = no limit. Not capped by the per-call max.
     path_append: str = ""
     sandbox: str = ""
     allowed_env_keys: list[str] = Field(default_factory=list)
@@ -59,7 +67,7 @@ class _PreparedCommand:
     command: str
     cwd: str
     env: dict[str, str]
-    timeout: int
+    timeout: int | None
     shell_program: str | None
     login: bool
 
@@ -140,6 +148,7 @@ class ExecTool(Tool):
             working_dir=ctx.workspace,
             timeout=cfg.timeout,
             restrict_to_workspace=ctx.config.restrict_to_workspace,
+            webui_allow_local_service_access=ctx.config.webui_allow_local_service_access,
             sandbox=cfg.sandbox,
             path_append=cfg.path_append,
             allowed_env_keys=cfg.allowed_env_keys,
@@ -154,6 +163,8 @@ class ExecTool(Tool):
         deny_patterns: list[str] | None = None,
         allow_patterns: list[str] | None = None,
         restrict_to_workspace: bool = False,
+        webui_allow_local_service_access: bool = True,
+        allow_local_preview_access: bool | None = None,
         sandbox: str = "",
         path_append: str = "",
         allowed_env_keys: list[str] | None = None,
@@ -183,6 +194,9 @@ class ExecTool(Tool):
         ]
         self.allow_patterns = allow_patterns or []
         self.restrict_to_workspace = restrict_to_workspace
+        if allow_local_preview_access is not None:
+            webui_allow_local_service_access = allow_local_preview_access
+        self.webui_allow_local_service_access = webui_allow_local_service_access
         self.path_append = path_append
         self.allowed_env_keys = allowed_env_keys or []
         self._session_manager = session_manager or DEFAULT_EXEC_SESSION_MANAGER
@@ -313,6 +327,7 @@ class ExecTool(Tool):
                 shell_program=prepared.shell_program,
                 login=prepared.login,
                 yield_time_ms=clamp_session_int(yield_time_ms, DEFAULT_YIELD_MS, 0, MAX_YIELD_MS),
+                owner_session_key=current_request_session_key(),
                 max_output_chars=clamp_session_int(
                     max_output_chars,
                     DEFAULT_MAX_OUTPUT_CHARS,
@@ -324,6 +339,20 @@ class ExecTool(Tool):
         except Exception as exc:
             return f"Error executing command: {exc}"
 
+    def _resolve_timeout(self, timeout: int | None) -> int | None:
+        """Resolve the effective hard timeout in seconds (None = no limit).
+
+        A per-call timeout supplied by the model stays capped at _MAX_TIMEOUT so
+        the LLM cannot request unbounded execution. The config-level default
+        (self.timeout) may exceed that cap, and 0 disables the limit entirely
+        for trusted long-running tasks (#3595).
+        """
+        if timeout:
+            return min(timeout, self._MAX_TIMEOUT)
+        if self.timeout and self.timeout > 0:
+            return self.timeout
+        return None
+
     def _prepare_command(
         self,
         command: str,
@@ -332,29 +361,39 @@ class ExecTool(Tool):
         shell: str | None = None,
         login: bool | None = None,
     ) -> _PreparedCommand | str:
-        cwd = working_dir or self.working_dir or os.getcwd()
+        access = current_tool_workspace(
+            self.working_dir,
+            restrict_to_workspace=self.restrict_to_workspace,
+            sandbox_restricts_workspace=bool(self.sandbox),
+        )
+        workspace_root = str(access.project_path) if access.project_path is not None else self.working_dir
+        cwd = working_dir or workspace_root or os.getcwd()
 
         # Prevent an LLM-supplied working_dir from escaping the configured
         # workspace when restrict_to_workspace is enabled (#2826). Without
         # this, a caller can pass working_dir="/etc" and then all absolute
         # paths under /etc would pass the _guard_command check that anchors
         # on cwd.
-        if self.restrict_to_workspace and self.working_dir:
+        if access.restrict_to_workspace and workspace_root:
             try:
                 requested = Path(cwd).expanduser().resolve()
-                workspace_root = Path(self.working_dir).expanduser().resolve()
+                resolved_root = Path(workspace_root).expanduser().resolve()
             except Exception:
                 return (
                     "Error: working_dir could not be resolved"
                     + _WORKSPACE_BOUNDARY_NOTE
                 )
-            if requested != workspace_root and workspace_root not in requested.parents:
+            if not is_path_within(requested, resolved_root):
                 return (
                     "Error: working_dir is outside the configured workspace"
                     + _WORKSPACE_BOUNDARY_NOTE
                 )
 
-        guard_error = self._guard_command(command, cwd)
+        guard_error = self._guard_command(
+            command,
+            cwd,
+            restrict_to_workspace=access.restrict_to_workspace,
+        )
         if guard_error:
             return guard_error
 
@@ -365,11 +404,11 @@ class ExecTool(Tool):
                     self.sandbox,
                 )
             else:
-                workspace = self.working_dir or cwd
+                workspace = workspace_root or cwd
                 command = wrap_command(self.sandbox, command, workspace, cwd)
                 cwd = str(Path(workspace).resolve())
 
-        effective_timeout = min(timeout or self.timeout, self._MAX_TIMEOUT)
+        effective_timeout = self._resolve_timeout(timeout)
         env = self._build_env()
 
         if self.path_append:
@@ -397,16 +436,23 @@ class ExecTool(Tool):
         command: str, cwd: str, env: dict[str, str],
         shell_program: str | None = None,
         login: bool = True,
+        *,
+        stdin: int = asyncio.subprocess.DEVNULL,
     ) -> asyncio.subprocess.Process:
         """Launch *command* in a platform-appropriate shell."""
         if _IS_WINDOWS:
-            # create_subprocess_exec re-quotes args via list2cmdline, which
-            # breaks commands containing paths with spaces (e.g. "D:\Program
-            # Files\python.exe" "script.py"). create_subprocess_shell passes
-            # the raw command string to COMSPEC without re-quoting.
+            if "\n" in command:
+                return await asyncio.create_subprocess_exec(
+                    "powershell", "-NoProfile", "-Command", command,
+                    stdin=stdin,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    cwd=cwd,
+                    env=env,
+                )
             return await asyncio.create_subprocess_shell(
                 command,
-                stdin=asyncio.subprocess.DEVNULL,
+                stdin=stdin,
                 stdout=asyncio.subprocess.PIPE,
                 stderr=asyncio.subprocess.PIPE,
                 cwd=cwd,
@@ -420,7 +466,7 @@ class ExecTool(Tool):
         args.extend(["-c", command])
         return await asyncio.create_subprocess_exec(
             *args,
-            stdin=asyncio.subprocess.DEVNULL,
+            stdin=stdin,
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
             cwd=cwd,
@@ -514,7 +560,13 @@ class ExecTool(Tool):
                 env[key] = val
         return env
 
-    def _guard_command(self, command: str, cwd: str) -> str | None:
+    def _guard_command(
+        self,
+        command: str,
+        cwd: str,
+        *,
+        restrict_to_workspace: bool | None = None,
+    ) -> str | None:
         """Best-effort safety guard for potentially destructive commands."""
         cmd = command.strip()
         lower = cmd.lower()
@@ -534,11 +586,17 @@ class ExecTool(Tool):
                 return "Error: Command blocked by allowlist filter (not in allowlist)"
 
         from nanobot.security.network import contains_internal_url
-        if contains_internal_url(cmd):
+        if contains_internal_url(
+            cmd,
+            allow_loopback=current_scope_allows_loopback(
+                enabled=self.webui_allow_local_service_access,
+            ),
+        ):
             # The runner turns this marker into a non-retryable security hint.
             return "Error: Command blocked by safety guard (internal/private URL detected)"
 
-        if self.restrict_to_workspace:
+        should_restrict = self.restrict_to_workspace if restrict_to_workspace is None else restrict_to_workspace
+        if should_restrict:
             if "..\\" in cmd or "../" in cmd:
                 return (
                     "Error: Command blocked by safety guard (path traversal detected)"
@@ -563,11 +621,9 @@ class ExecTool(Tool):
                     continue
 
                 media_path = get_media_dir().resolve()
-                if (p.is_absolute()
-                    and cwd_path not in p.parents
-                    and p != cwd_path
-                    and media_path not in p.parents
-                    and p != media_path
+                if p.is_absolute() and not (
+                    is_path_within(p, cwd_path)
+                    or is_path_within(p, media_path)
                 ):
                     return (
                         "Error: Command blocked by safety guard (path outside working dir)"

nanobot/agent/tools/spawn.py

@@ -7,7 +7,8 @@ from typing import TYPE_CHECKING, Any
 
 from nanobot.agent.tools.base import Tool, tool_parameters
 from nanobot.agent.tools.context import ContextAware, RequestContext
-from nanobot.agent.tools.schema import StringSchema, tool_parameters_schema
+from nanobot.agent.tools.schema import NumberSchema, StringSchema, tool_parameters_schema
+from nanobot.security.workspace_access import current_workspace_scope
 
 if TYPE_CHECKING:
     from nanobot.agent.subagent import SubagentManager
@@ -17,6 +18,15 @@ if TYPE_CHECKING:
     tool_parameters_schema(
         task=StringSchema("The task for the subagent to complete"),
         label=StringSchema("Optional short label for the task (for display)"),
+        temperature=NumberSchema(
+            description=(
+                "Optional sampling temperature for the subagent "
+                "(0.0 = deterministic, higher = more creative). "
+                "Defaults to the provider's configured temperature."
+            ),
+            minimum=0.0,
+            maximum=2.0,
+        ),
         required=["task"],
     )
 )
@@ -58,7 +68,13 @@ class SpawnTool(Tool, ContextAware):
             "and use a dedicated subdirectory when helpful."
         )
 
-    async def execute(self, task: str, label: str | None = None, **kwargs: Any) -> str:
+    async def execute(
+        self,
+        task: str,
+        label: str | None = None,
+        temperature: float | None = None,
+        **kwargs: Any,
+    ) -> str:
         """Spawn a subagent to execute the given task."""
         running = self._manager.get_running_count()
         limit = self._manager.max_concurrent_subagents
@@ -75,4 +91,6 @@ class SpawnTool(Tool, ContextAware):
             origin_chat_id=self._origin_chat_id.get(),
             session_key=self._session_key.get(),
             origin_message_id=self._origin_message_id.get(),
+            temperature=temperature,
+            workspace_scope=current_workspace_scope(),
         )

nanobot/agent/tools/web.py

@@ -455,17 +455,16 @@ class WebSearchTool(Tool):
             return await self._search_duckduckgo(query, n)
         try:
             async with httpx.AsyncClient(proxy=self.proxy) as client:
-                r = await client.get(
-                    "https://kagi.com/api/v0/search",
-                    params={"q": query, "limit": n},
-                    headers={"Authorization": f"Bot {api_key}", "User-Agent": self.user_agent},
+                r = await client.post(
+                    "https://kagi.com/api/v1/search",
+                    json={"query": query, "limit": n},
+                    headers={"Authorization": f"Bearer {api_key}", "User-Agent": self.user_agent},
                     timeout=10.0,
                 )
                 r.raise_for_status()
-            # t=0 items are search results; other values are related searches, etc.
             items = [
                 {"title": d.get("title", ""), "url": d.get("url", ""), "content": d.get("snippet", "")}
-                for d in r.json().get("data", []) if d.get("t") == 0
+                for d in r.json().get("data", {}).get("search", [])
             ]
             return _format_results(query, items, n)
         except Exception as e:

nanobot/apps/__init__.py

@@ -0,0 +1,5 @@
+"""Shared app protocol helpers."""
+
+from nanobot.apps.protocol import APP_PROTOCOL_SCHEMA, app_manifest
+
+__all__ = ["APP_PROTOCOL_SCHEMA", "app_manifest"]

nanobot/apps/cli/__init__.py

@@ -1,6 +1,6 @@
-"""CLI Apps integration helpers."""
+"""CLI app adapter for the unified Apps domain."""
 
-from nanobot.cli_apps.service import (
+from nanobot.apps.cli.service import (
     CliAppError,
     CliAppManager,
     CliAppsRuntimeConfig,

nanobot/apps/cli/service.py

@@ -11,25 +11,36 @@ import subprocess
 import sys
 import time
 from dataclasses import dataclass
+from importlib import metadata as importlib_metadata
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlparse
 
 import httpx
 
+from nanobot.apps.protocol import app_manifest, compact_dict
 from nanobot.config.paths import get_runtime_subdir
+from nanobot.security.workspace_policy import is_path_within
 
 CLI_ANYTHING_REGISTRY_URL = "https://hkuds.github.io/CLI-Anything/registry.json"
 CLI_ANYTHING_PUBLIC_REGISTRY_URL = "https://hkuds.github.io/CLI-Anything/public_registry.json"
 CLI_ANYTHING_RAW_BASE = "https://raw.githubusercontent.com/HKUDS/CLI-Anything/main"
-CLI_ANYTHING_RAW_SKILLS_BASE = f"{CLI_ANYTHING_RAW_BASE}/skills/"
+NANOBOT_EXTENSION_REGISTRY_URL = "https://raw.githubusercontent.com/Re-bin/nanobot-extension/main/registry.json"
+NANOBOT_EXTENSION_RAW_BASE = "https://raw.githubusercontent.com/Re-bin/nanobot-extension/main"
+_CATALOG_SOURCES = (
+    ("harness", CLI_ANYTHING_REGISTRY_URL, CLI_ANYTHING_RAW_BASE, True),
+    ("public", CLI_ANYTHING_PUBLIC_REGISTRY_URL, CLI_ANYTHING_RAW_BASE, True),
+    ("extensions", NANOBOT_EXTENSION_REGISTRY_URL, NANOBOT_EXTENSION_RAW_BASE, False),
+)
 
 _MAX_TOOL_OUTPUT_CHARS = 12_000
 _MAX_ARTIFACT_SCAN_PATHS = 4_000
 _MAX_ARTIFACT_REPORT = 12
 _SAFE_NAME_RE = re.compile(r"[^a-z0-9_-]+")
+_SAFE_NPM_DIR_RE = re.compile(r"^[a-z0-9._-]+$", re.IGNORECASE)
 _MENTION_RE = re.compile(r"(^|[\s([{])@([a-z0-9_-]+)\b", re.IGNORECASE)
 _SHELL_META_CHARS = ("|", "&&", "||", ";", "$(", "`", ">", "<")
+_ENDORSEMENT_WORD_RE = re.compile(r"\bofficial\s+", re.IGNORECASE)
 _ARTIFACT_EXTENSIONS = frozenset({
     ".csv",
     ".drawio",
@@ -139,7 +150,7 @@ _BRANDS: dict[str, tuple[str, str]] = {
 
 _BRAND_DOMAINS: dict[str, tuple[str, str]] = {
     "3mf": ("3mf.io", "#00A1DE"),
-    "anygen": ("anygen.com", "#111827"),
+    "anygen": ("anygen.io", "#111827"),
     "clibrowser": ("github.com/allthingssecurity/clibrowser", "#24292F"),
     "cloudanalyzer": ("github.com/rsasaki0109/CloudAnalyzer", "#2563EB"),
     "cloudcompare": ("cloudcompare.org", "#4D83C3"),
@@ -244,6 +255,29 @@ def _pip_uninstall_args_from_command(command: str) -> list[str] | None:
     return packages
 
 
+def _console_script_distribution(entry_point: str) -> str | None:
+    if not entry_point:
+        return None
+    try:
+        distributions = importlib_metadata.distributions()
+    except Exception:
+        return None
+    for distribution in distributions:
+        try:
+            entry_points = distribution.entry_points
+        except Exception:
+            continue
+        for item in entry_points:
+            if item.group != "console_scripts" or item.name != entry_point:
+                continue
+            try:
+                name = distribution.metadata.get("Name")
+            except Exception:
+                name = None
+            return str(name or getattr(distribution, "name", "") or "").strip() or None
+    return None
+
+
 def _brand_key(value: str) -> str:
     return _SAFE_NAME_RE.sub("-", value.lower()).replace("_", "-").strip("-")
 
@@ -269,6 +303,11 @@ def _brand_candidates(app: dict[str, Any]) -> list[str]:
 
 
 def _brand_payload(app: dict[str, Any]) -> tuple[str | None, str | None]:
+    declared_logo = str(app.get("logo_url") or "").strip()
+    if declared_logo.startswith(("https://", "/")):
+        declared_color = str(app.get("brand_color") or "").strip()
+        return declared_logo, declared_color or None
+
     brand = None
     domain_brand = None
     for candidate in _brand_candidates(app):
@@ -317,16 +356,17 @@ def _safe_skill_path(value: str) -> str | None:
     return value if parts[-1] == "SKILL.md" else None
 
 
-def _skill_content_url(skill_md: str) -> str | None:
+def _skill_content_url(skill_md: str, *, raw_base: str = CLI_ANYTHING_RAW_BASE) -> str | None:
     safe_path = _safe_skill_path(skill_md)
     if safe_path:
-        return f"{CLI_ANYTHING_RAW_BASE}/{safe_path}"
+        return f"{raw_base.rstrip('/')}/{safe_path}"
     parsed = urlparse(skill_md)
     if parsed.scheme != "https" or parsed.netloc != "raw.githubusercontent.com":
         return None
-    if not skill_md.startswith(CLI_ANYTHING_RAW_SKILLS_BASE):
+    raw_prefix = raw_base.rstrip("/") + "/"
+    if not skill_md.startswith(raw_prefix):
         return None
-    suffix = skill_md.removeprefix(f"{CLI_ANYTHING_RAW_BASE}/")
+    suffix = skill_md.removeprefix(raw_prefix)
     return skill_md if _safe_skill_path(suffix) else None
 
 
@@ -337,6 +377,12 @@ def _truncate(text: str, limit: int = _MAX_TOOL_OUTPUT_CHARS) -> str:
     return text[:limit] + f"\n\n... truncated {omitted} characters ..."
 
 
+def _catalog_description(app: dict[str, Any]) -> str:
+    """Return catalog copy without implying vendor endorsement."""
+    description = str(app.get("description") or "")
+    return _ENDORSEMENT_WORD_RE.sub("", description).strip()
+
+
 class CliAppManager:
     """Manage CLI-Anything registry entries and local install state."""
 
@@ -402,27 +448,22 @@ class CliAppManager:
         return data
 
     def catalog(self, *, force_refresh: bool = False) -> tuple[list[dict[str, Any]], str | None]:
-        registries = [
-            (
-                "harness",
-                self._fetch_registry(
-                    CLI_ANYTHING_REGISTRY_URL,
-                    self._cache_path("harness"),
+        registries: list[tuple[str, str, dict[str, Any]]] = []
+        for source, url, raw_base, required in _CATALOG_SOURCES:
+            try:
+                registry = self._fetch_registry(
+                    url,
+                    self._cache_path(source),
                     force_refresh=force_refresh,
-                ),
-            ),
-            (
-                "public",
-                self._fetch_registry(
-                    CLI_ANYTHING_PUBLIC_REGISTRY_URL,
-                    self._cache_path("public"),
-                    force_refresh=force_refresh,
-                ),
-            ),
-        ]
+                )
+            except Exception:
+                if required:
+                    raise
+                continue
+            registries.append((source, raw_base, registry))
         apps_by_name: dict[str, dict[str, Any]] = {}
         updated_values: list[str] = []
-        for source, registry in registries:
+        for source, raw_base, registry in registries:
             meta = registry.get("meta")
             if isinstance(meta, dict) and isinstance(meta.get("updated"), str):
                 updated_values.append(meta["updated"])
@@ -431,6 +472,7 @@ class CliAppManager:
                     continue
                 entry = dict(row)
                 entry["_source"] = source
+                entry["_raw_base"] = raw_base
                 key = str(entry["name"]).lower()
                 previous = apps_by_name.get(key)
                 if previous:
@@ -443,6 +485,15 @@ class CliAppManager:
                     apps_by_name[key] = entry
         return list(apps_by_name.values()), max(updated_values) if updated_values else None
 
+    def _manifest_source(self, app: dict[str, Any]) -> str:
+        source = str(app.get("_source") or "harness")
+        if source == "extensions":
+            return "nanobot-extension"
+        return f"cli-anything:{source}"
+
+    def _trust_registry(self, app: dict[str, Any]) -> str:
+        return "nanobot-extension" if str(app.get("_source") or "") == "extensions" else "cli-anything"
+
     def get_app(self, name: str, *, force_refresh: bool = False) -> dict[str, Any]:
         wanted = name.lower()
         for app in self.catalog(force_refresh=force_refresh)[0]:
@@ -529,7 +580,7 @@ class CliAppManager:
             "name": name,
             "display_name": app.get("display_name") or name,
             "category": app.get("category") or "uncategorized",
-            "description": app.get("description") or "",
+            "description": _catalog_description(app),
             "requires": app.get("requires") or "",
             "source": app.get("_source") or "harness",
             "entry_point": entry_point,
@@ -540,8 +591,86 @@ class CliAppManager:
             "logo_url": logo_url,
             "brand_color": brand_color,
             "skill_installed": self._skill_path(name).is_file(),
+            "manifest": self._manifest_payload(app, logo_url=logo_url, brand_color=brand_color),
         }
 
+    def _package_ref(self, app: dict[str, Any]) -> dict[str, Any] | None:
+        strategy = self._strategy(app)
+        name = ""
+        if strategy == "pip":
+            try:
+                uninstall = self._pip_uninstall_argv(app)
+            except CliAppError:
+                uninstall = None
+            name = uninstall[-1] if uninstall else ""
+        elif strategy == "npm":
+            name = str(app.get("npm_package") or "").strip()
+        elif strategy in {"brew", "uv"}:
+            try:
+                uninstall = self._argv_for_action(app, "uninstall")
+            except CliAppError:
+                uninstall = None
+            if uninstall:
+                name = uninstall[-1]
+        if not strategy or strategy in {"unsupported", "bundled"}:
+            return None
+        return compact_dict({"manager": strategy, "name": name})
+
+    def _manifest_payload(
+        self,
+        app: dict[str, Any],
+        *,
+        logo_url: str | None,
+        brand_color: str | None,
+    ) -> dict[str, Any]:
+        name = str(app["name"])
+        entry_point = str(app.get("entry_point") or "")
+        strategy = self._strategy(app)
+        skill_path = f"skills/{_safe_skill_name(name)}/SKILL.md"
+        capabilities = [
+            compact_dict({
+                "type": "cli",
+                "entry_point": entry_point,
+                "package": self._package_ref(app),
+            }),
+            {"type": "skill", "path": skill_path},
+        ]
+        install_supported = self._install_supported(app)
+        install = compact_dict({
+            "supported": install_supported,
+            "strategy": strategy,
+            "managed_paths": [skill_path],
+            "verification": ["entry_point_available"] if entry_point else [],
+        })
+        remove = compact_dict({
+            "supported": strategy != "unsupported",
+            "strategy": strategy,
+            "managed_paths": [skill_path],
+            "verification": (
+                ["package_manager_ok", "entry_point_absent", "managed_paths_absent"]
+                if strategy not in {"bundled", "unsupported"}
+                else ["nanobot_state_absent", "managed_paths_absent"]
+            ),
+        })
+        return app_manifest(
+            app_id=name,
+            display_name=str(app.get("display_name") or name),
+            version=str(app.get("version") or ""),
+            description=_catalog_description(app),
+            category=str(app.get("category") or "uncategorized"),
+            source=self._manifest_source(app),
+            logo_url=logo_url,
+            brand_color=brand_color,
+            capabilities=capabilities,
+            install=install,
+            remove=remove,
+            trust={
+                "registry": self._trust_registry(app),
+                "level": "catalog",
+                "review_status": "catalog_entry",
+            },
+        )
+
     def payload(self, *, force_refresh: bool = False) -> dict[str, Any]:
         apps, updated = self.catalog(force_refresh=force_refresh)
         installed = self._load_installed()
@@ -581,7 +710,14 @@ class CliAppManager:
             prefix.extend(["--upgrade", "--force-reinstall"])
         return prefix + args
 
-    def _pip_uninstall_argv(self, app: dict[str, Any]) -> list[str]:
+    def _pip_uninstall_argv(
+        self,
+        app: dict[str, Any],
+        installed_entry: dict[str, Any] | None = None,
+    ) -> list[str]:
+        distribution = str((installed_entry or {}).get("pip_distribution") or "").strip()
+        if distribution:
+            return [sys.executable, "-m", "pip", "uninstall", "-y", distribution]
         uninstall_cmd = str(app.get("uninstall_cmd") or "")
         packages = _pip_uninstall_args_from_command(uninstall_cmd)
         if packages:
@@ -605,6 +741,45 @@ class CliAppManager:
             return [npm, "install", "-g", package + "@latest"]
         return [npm, "uninstall", "-g", package]
 
+    def _cleanup_stale_npm_install(self, app: dict[str, Any]) -> bool:
+        npm = shutil.which("npm")
+        package = str(app.get("npm_package") or "").strip()
+        if not npm or not package or "/" in package or _SAFE_NPM_DIR_RE.match(package) is None:
+            return False
+        result = self._run_argv([npm, "root", "-g"], timeout=min(self.runtime.install_timeout, 30))
+        if result.returncode != 0:
+            return False
+        root = Path(result.stdout.strip()).expanduser()
+        try:
+            root = root.resolve(strict=True)
+        except OSError:
+            return False
+        targets = [root / package, *root.glob(f".{package}-*")]
+        removed = False
+        for target in targets:
+            try:
+                resolved = target.resolve(strict=False)
+                if not is_path_within(resolved, root) or not target.is_dir():
+                    continue
+                shutil.rmtree(target)
+                removed = True
+            except OSError:
+                continue
+        return removed
+
+    def _retry_stale_npm_install(
+        self,
+        app: dict[str, Any],
+        argv: list[str],
+        result: subprocess.CompletedProcess[str],
+    ) -> subprocess.CompletedProcess[str]:
+        output = f"{result.stderr}\n{result.stdout}"
+        if "ENOTEMPTY" not in output or "rename" not in output:
+            return result
+        if not self._cleanup_stale_npm_install(app):
+            return result
+        return self._run_argv(argv, timeout=self.runtime.install_timeout)
+
     def _split_safe_command(self, app: dict[str, Any], key: str, expected: str) -> list[str]:
         command = str(app.get(key) or "")
         if not command:
@@ -619,14 +794,19 @@ class CliAppManager:
             raise CliAppError(f"unsupported {expected} command")
         return argv
 
-    def _argv_for_action(self, app: dict[str, Any], action: str) -> list[str] | None:
+    def _argv_for_action(
+        self,
+        app: dict[str, Any],
+        action: str,
+        installed_entry: dict[str, Any] | None = None,
+    ) -> list[str] | None:
         strategy = self._strategy(app)
         if strategy == "pip":
             if action == "install":
                 return self._pip_install_argv(app)
             if action == "update":
                 return self._pip_install_argv(app, update=True)
-            return self._pip_uninstall_argv(app)
+            return self._pip_uninstall_argv(app, installed_entry=installed_entry)
         if strategy == "npm":
             return self._npm_argv(app, action)
         if strategy == "brew":
@@ -648,19 +828,29 @@ class CliAppManager:
         )
 
     def _installed_entry(self, app: dict[str, Any]) -> dict[str, Any]:
-        return {
+        entry_point = str(app.get("entry_point") or "")
+        strategy = self._strategy(app)
+        entry: dict[str, Any] = {
             "version": app.get("version") or "unknown",
-            "entry_point": app.get("entry_point") or "",
+            "entry_point": entry_point,
             "source": app.get("_source") or "harness",
-            "strategy": self._strategy(app),
+            "strategy": strategy,
             "installed_at": int(_now()),
         }
+        resolved = shutil.which(entry_point) if entry_point else None
+        if resolved:
+            entry["entry_point_path"] = resolved
+        if strategy == "pip":
+            distribution = _console_script_distribution(entry_point)
+            if distribution:
+                entry["pip_distribution"] = distribution
+        return entry
 
     def _fetch_skill_content(self, app: dict[str, Any]) -> str | None:
         skill_md = str(app.get("skill_md") or "").strip()
         if not skill_md:
             return None
-        url = _skill_content_url(skill_md)
+        url = _skill_content_url(skill_md, raw_base=str(app.get("_raw_base") or CLI_ANYTHING_RAW_BASE))
         if not url:
             return None
         try:
@@ -677,7 +867,7 @@ class CliAppManager:
         name = str(app.get("name") or "unknown")
         display = str(app.get("display_name") or name)
         entry = str(app.get("entry_point") or f"cli-anything-{name}")
-        description = str(app.get("description") or f"Use {display} from nanobot.")
+        description = _catalog_description(app) or f"Use {display} from nanobot."
         return f"""---
 name: {_safe_skill_name(name)}
 description: >-
@@ -730,31 +920,60 @@ Use the `run_cli_app` tool with `name="{name}"` for command execution. Do not in
         if skill_dir.is_dir():
             shutil.rmtree(skill_dir)
 
-    def _record_installed(self, app: dict[str, Any]) -> None:
+    def _record_installed(self, app: dict[str, Any]) -> dict[str, Any]:
         installed = self._load_installed()
-        installed[str(app["name"])] = self._installed_entry(app)
+        entry = self._installed_entry(app)
+        installed[str(app["name"])] = entry
         self._save_installed(installed)
         self.install_skill(app)
+        return entry
 
     def install(self, name: str) -> dict[str, Any]:
         app = self.get_app(name)
         if not self._install_supported(app):
             raise CliAppError("this CLI app uses an unsupported install strategy")
         strategy = self._strategy(app)
+        entry_point = str(app.get("entry_point") or "")
+        if entry_point and shutil.which(entry_point):
+            self._record_installed(app)
+            return self.payload() | {
+                "last_action": {
+                    "ok": True,
+                    "message": f"CLI for {app['display_name']} is already available.",
+                    "installed": True,
+                    "verification": ["entry_point_available", "state_recorded", "managed_paths_present"],
+                }
+            }
         if strategy == "bundled":
             detect_cmd = str(app.get("detect_cmd") or app.get("entry_point") or "")
             if detect_cmd and _command_exists(detect_cmd):
                 self._record_installed(app)
-                return self.payload() | {"last_action": {"ok": True, "message": f"CLI for {app['display_name']} is available."}}
+                return self.payload() | {
+                    "last_action": {
+                        "ok": True,
+                        "message": f"CLI for {app['display_name']} is available.",
+                        "installed": True,
+                        "verification": ["entry_point_available", "state_recorded"],
+                    }
+                }
             note = app.get("install_notes") or f"{app['display_name']} is bundled with its parent app."
             raise CliAppError(str(note))
         argv = self._argv_for_action(app, "install")
         assert argv is not None
         result = self._run_argv(argv, timeout=self.runtime.install_timeout)
+        if strategy == "npm" and result.returncode != 0:
+            result = self._retry_stale_npm_install(app, argv, result)
         if result.returncode != 0:
             raise CliAppError(_truncate(result.stderr or result.stdout or "install failed"), status=500)
         self._record_installed(app)
-        return self.payload() | {"last_action": {"ok": True, "message": f"Installed CLI for {app['display_name']}."}}
+        return self.payload() | {
+            "last_action": {
+                "ok": True,
+                "message": f"Installed CLI for {app['display_name']}.",
+                "installed": True,
+                "verification": ["package_manager_ok", "state_recorded", "managed_paths_present"],
+            }
+        }
 
     def update(self, name: str) -> dict[str, Any]:
         app = self.get_app(name, force_refresh=True)
@@ -762,30 +981,94 @@ Use the `run_cli_app` tool with `name="{name}"` for command execution. Do not in
             raise CliAppError("CLI app is not installed")
         if self._strategy(app) == "bundled":
             self._record_installed(app)
-            return self.payload() | {"last_action": {"ok": True, "message": f"Checked {app['display_name']}."}}
+            return self.payload() | {
+                "last_action": {
+                    "ok": True,
+                    "message": f"Checked {app['display_name']}.",
+                    "installed": True,
+                    "verification": ["state_recorded"],
+                }
+            }
         argv = self._argv_for_action(app, "update")
         assert argv is not None
         result = self._run_argv(argv, timeout=self.runtime.install_timeout)
         if result.returncode != 0:
             raise CliAppError(_truncate(result.stderr or result.stdout or "update failed"), status=500)
         self._record_installed(app)
-        return self.payload() | {"last_action": {"ok": True, "message": f"Updated CLI for {app['display_name']}."}}
+        return self.payload() | {
+            "last_action": {
+                "ok": True,
+                "message": f"Updated CLI for {app['display_name']}.",
+                "installed": True,
+                "verification": ["package_manager_ok", "state_recorded", "managed_paths_present"],
+            }
+        }
 
     def uninstall(self, name: str) -> dict[str, Any]:
         app = self.get_app(name)
         installed = self._load_installed()
         if str(app["name"]) not in installed:
             raise CliAppError("CLI app is not installed")
-        if self._strategy(app) != "bundled":
-            argv = self._argv_for_action(app, "uninstall")
+        raw_installed_entry = installed.get(str(app["name"]))
+        installed_entry = raw_installed_entry if isinstance(raw_installed_entry, dict) else {}
+        strategy = self._strategy(app)
+        entry_point = str(app.get("entry_point") or "").strip()
+        managed_entry_path = str(installed_entry.get("entry_point_path") or "").strip()
+        if strategy != "bundled":
+            argv = self._argv_for_action(app, "uninstall", installed_entry=installed_entry)
             assert argv is not None
             result = self._run_argv(argv, timeout=self.runtime.install_timeout)
             if result.returncode != 0:
                 raise CliAppError(_truncate(result.stderr or result.stdout or "uninstall failed"), status=500)
+            still_managed = bool(managed_entry_path and Path(managed_entry_path).exists())
+            still_available = bool(entry_point and shutil.which(entry_point))
+            if still_managed or (not managed_entry_path and still_available):
+                reason = (
+                    f"the recorded entry point at {managed_entry_path} still exists"
+                    if still_managed
+                    else f"{entry_point} is still available on PATH"
+                )
+                message = (
+                    f"Uninstall for {app['display_name']} completed, but {reason}, "
+                    "so nanobot kept it installed."
+                )
+                return self.payload() | {
+                    "last_action": {
+                        "ok": False,
+                        "message": message,
+                        "removed": False,
+                        "still_available": True,
+                        "verification_failed": ["entry_point_absent"],
+                    }
+                }
+        else:
+            still_available = bool(entry_point and shutil.which(entry_point))
         installed.pop(str(app["name"]), None)
         self._save_installed(installed)
         self.remove_skill(str(app["name"]))
-        return self.payload() | {"last_action": {"ok": True, "message": f"Uninstalled CLI for {app['display_name']}."}}
+        if strategy == "bundled" and still_available:
+            message = (
+                f"Removed {app['display_name']} from nanobot. {entry_point} "
+                "is still available because it is managed outside nanobot."
+            )
+        elif still_available:
+            message = (
+                f"Uninstalled CLI for {app['display_name']}, but another {entry_point} "
+                "is still available on PATH."
+            )
+        else:
+            message = f"Uninstalled CLI for {app['display_name']}."
+        return self.payload() | {
+            "last_action": {
+                "ok": True,
+                "message": message,
+                "removed": True,
+                "still_available": still_available,
+                "verification": ["state_absent", "managed_paths_absent"]
+                if still_available
+                else ["entry_point_absent", "state_absent", "managed_paths_absent"],
+            }
+        }
 
     def test(self, name: str) -> dict[str, Any]:
         app = self.get_app(name)
@@ -813,7 +1096,7 @@ Use the `run_cli_app` tool with `name="{name}"` for command execution. Do not in
         cwd = Path(working_dir).expanduser() if working_dir else self.workspace
         cwd = cwd.resolve(strict=False)
         workspace = self.workspace.resolve(strict=False)
-        if restrict_to_workspace and cwd != workspace and not cwd.is_relative_to(workspace):
+        if restrict_to_workspace and not is_path_within(cwd, workspace):
             raise CliAppError("working_dir is outside the configured workspace")
         return cwd
 

nanobot/apps/cli/utils.py

@@ -46,7 +46,7 @@ def _cli_app_runtime_lines(
     if "@" not in text:
         return []
     try:
-        from nanobot.cli_apps import CliAppManager
+        from nanobot.apps.cli import CliAppManager
 
         mentions = CliAppManager(workspace=workspace).mentioned_installed_apps(text)
     except Exception:

nanobot/apps/protocol.py

@@ -0,0 +1,56 @@
+"""Neutral manifest shape for settings-managed agent apps.
+
+The manifest is intentionally descriptive. Installers still live in their
+own adapters, while this protocol gives the WebUI and future registries one
+small vocabulary for capabilities, trust, and verified install/remove plans.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+APP_PROTOCOL_SCHEMA = "agent-app.v1"
+
+
+def compact_dict(values: dict[str, Any]) -> dict[str, Any]:
+    """Drop empty optional values while preserving explicit booleans and zeros."""
+    return {
+        key: value
+        for key, value in values.items()
+        if value is not None and value != "" and value != [] and value != {}
+    }
+
+
+def app_manifest(
+    *,
+    app_id: str,
+    display_name: str,
+    description: str,
+    category: str,
+    source: str,
+    capabilities: list[dict[str, Any]],
+    install: dict[str, Any],
+    remove: dict[str, Any],
+    trust: dict[str, Any],
+    version: str | None = None,
+    logo_url: str | None = None,
+    brand_color: str | None = None,
+    docs_url: str | None = None,
+) -> dict[str, Any]:
+    """Build a stable app manifest dictionary."""
+    return compact_dict({
+        "schema": APP_PROTOCOL_SCHEMA,
+        "id": app_id,
+        "display_name": display_name,
+        "version": version,
+        "description": description,
+        "category": category,
+        "source": source,
+        "logo_url": logo_url,
+        "brand_color": brand_color,
+        "docs_url": docs_url,
+        "capabilities": capabilities,
+        "install": install,
+        "remove": remove,
+        "trust": trust,
+    })

nanobot/bus/events.py

@@ -9,6 +9,12 @@ from typing import Any
 # render it and other channels may ignore unknown keys.
 OUTBOUND_META_AGENT_UI = "_agent_ui"
 
+# Internal-only inbound metadata used by in-process channels to ask the agent
+# loop to update runtime state without going through a user session.
+INBOUND_META_RUNTIME_CONTROL = "_runtime_control"
+RUNTIME_CONTROL_ACK = "_ack"
+RUNTIME_CONTROL_MCP_RELOAD = "mcp_reload"
+
 
 @dataclass
 class InboundMessage:
@@ -45,4 +51,3 @@ class OutboundMessage:
     media: list[str] = field(default_factory=list)
     metadata: dict[str, Any] = field(default_factory=dict)
     buttons: list[list[str]] = field(default_factory=list)
-

nanobot/channels/discord.py

@@ -207,6 +207,16 @@ if DISCORD_AVAILABLE:
                 ) -> None:
                     await self._forward_slash_command(interaction, _command_text)
 
+            @self.tree.command(name="model", description="Show or switch runtime model preset")
+            @app_commands.describe(preset="Optional model preset name, such as default")
+            async def model_command(
+                interaction: discord.Interaction,
+                preset: str | None = None,
+            ) -> None:
+                preset = (preset or "").strip()
+                command_text = f"/model {preset}" if preset else "/model"
+                await self._forward_slash_command(interaction, command_text)
+
             @self.tree.command(name="help", description="Show available commands")
             async def help_command(interaction: discord.Interaction) -> None:
                 sender_id = str(interaction.user.id)

nanobot/channels/manager.py

@@ -57,11 +57,17 @@ class ChannelManager:
         *,
         session_manager: "SessionManager | None" = None,
         webui_runtime_model_name: Callable[[], str | None] | None = None,
+        webui_static_dist: bool = True,
+        webui_runtime_surface: str = "browser",
+        webui_runtime_capabilities: dict[str, Any] | None = None,
     ):
         self.config = config
         self.bus = bus
         self._session_manager = session_manager
         self._webui_runtime_model_name = webui_runtime_model_name
+        self._webui_static_dist = webui_static_dist
+        self._webui_runtime_surface = webui_runtime_surface
+        self._webui_runtime_capabilities = dict(webui_runtime_capabilities or {})
         self.channels: dict[str, BaseChannel] = {}
         self._dispatch_task: asyncio.Task | None = None
         self._origin_reply_fingerprints: dict[tuple[str, str, str], str] = {}
@@ -107,12 +113,15 @@ class ChannelManager:
                 if cls.name == "websocket":
                     if self._session_manager is not None:
                         kwargs["session_manager"] = self._session_manager
-                        static_path = _default_webui_dist()
+                        static_path = _default_webui_dist() if self._webui_static_dist else None
                         if static_path is not None:
                             kwargs["static_dist_path"] = static_path
                     kwargs["workspace_path"] = self.config.workspace_path
+                    kwargs["restrict_to_workspace"] = self.config.tools.restrict_to_workspace
                     if self._webui_runtime_model_name is not None:
                         kwargs["runtime_model_name"] = self._webui_runtime_model_name
+                    kwargs["runtime_surface"] = self._webui_runtime_surface
+                    kwargs["runtime_capabilities_overrides"] = self._webui_runtime_capabilities
                 channel = cls(section, self.bus, **kwargs)
                 channel.transcription_provider = transcription_provider
                 channel.transcription_api_key = transcription_key

nanobot/channels/matrix.py

@@ -8,21 +8,23 @@ from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Literal, TypeAlias
+from urllib.parse import quote, urlparse
 
 from pydantic import Field
 
+from nanobot.security.workspace_policy import is_path_within
+
 try:
+    import aiohttp
     import nh3
     from mistune import create_markdown
     from nio import (
         AsyncClient,
         AsyncClientConfig,
-        DownloadError,
         InviteEvent,
         JoinError,
         LoginResponse,
         MatrixRoom,
-        MemoryDownloadResponse,
         RoomEncryptedMedia,
         RoomMessage,
         RoomMessageMedia,
@@ -62,6 +64,10 @@ _MSGTYPE_MAP = {"m.image": "image", "m.audio": "audio", "m.video": "video", "m.f
 MATRIX_MEDIA_EVENT_FILTER = (RoomMessageMedia, RoomEncryptedMedia)
 MatrixMediaEvent: TypeAlias = RoomMessageMedia | RoomEncryptedMedia
 
+
+class _MediaTooLargeError(Exception):
+    """Raised when an inbound Matrix media download exceeds the configured cap."""
+
 MATRIX_MARKDOWN = create_markdown(
     escape=True,
     plugins=["table", "strikethrough", "url", "superscript", "subscript"],
@@ -190,6 +196,7 @@ class MatrixConfig(Base):
     e2ee_enabled: bool = Field(default=True, alias="e2eeEnabled")
     sync_stop_grace_seconds: int = 2
     max_media_bytes: int = 20 * 1024 * 1024
+    max_concurrent_media_downloads: int = 2
     allow_from: list[str] = Field(default_factory=list)
     group_policy: Literal["open", "mention", "allowlist"] = "open"
     group_allow_from: list[str] = Field(default_factory=list)
@@ -231,6 +238,9 @@ class MatrixChannel(BaseChannel):
         self._server_upload_limit_checked = False
         self._stream_bufs: dict[str, _StreamBuf] = {}
         self._started_at_ms: int = 0
+        self._media_download_semaphore = asyncio.Semaphore(
+            max(1, int(self.config.max_concurrent_media_downloads))
+        )
 
 
     async def start(self) -> None:
@@ -344,11 +354,7 @@ class MatrixChannel(BaseChannel):
         """Check path is inside workspace (when restriction enabled)."""
         if not self._restrict_to_workspace or not self._workspace:
             return True
-        try:
-            path.resolve(strict=False).relative_to(self._workspace)
-            return True
-        except ValueError:
-            return False
+        return is_path_within(path, self._workspace)
 
     def _collect_outbound_media_candidates(self, media: list[str]) -> list[Path]:
         """Deduplicate and resolve outbound attachment paths."""
@@ -743,7 +749,7 @@ class MatrixChannel(BaseChannel):
     def _event_declared_size_bytes(self, event: MatrixMediaEvent) -> int | None:
         info = self._event_source_content(event).get("info")
         size = info.get("size") if isinstance(info, dict) else None
-        return size if isinstance(size, int) and size >= 0 else None
+        return size if type(size) is int and size >= 0 else None
 
     def _event_mime(self, event: MatrixMediaEvent) -> str | None:
         info = self._event_source_content(event).get("info")
@@ -772,26 +778,48 @@ class MatrixChannel(BaseChannel):
         event_prefix = (event_id[:24] or "evt").strip("_")
         return self._media_dir() / f"{event_prefix}_{stem}{suffix}"
 
-    async def _download_media_bytes(self, mxc_url: str) -> bytes | None:
-        if not self.client:
+    async def _download_media_bytes(self, mxc_url: str, limit_bytes: int) -> bytes | None:
+        if not self.client or limit_bytes <= 0:
+            raise _MediaTooLargeError
+
+        parsed = urlparse(mxc_url)
+        if parsed.scheme != "mxc" or not parsed.netloc or not parsed.path.strip("/"):
             return None
-        response = await self.client.download(mxc=mxc_url)
-        if isinstance(response, DownloadError):
-            self.logger.warning("download failed for {}: {}", mxc_url, response)
+
+        homeserver = str(getattr(self.client, "homeserver", "") or self.config.homeserver).rstrip("/")
+        media_url = (
+            f"{homeserver}/_matrix/client/v1/media/download/"
+            f"{quote(parsed.netloc, safe='')}/{quote(parsed.path.strip('/'), safe='')}"
+        )
+        token = getattr(self.client, "access_token", None) or self.config.access_token
+        headers = {"Authorization": f"Bearer {token}"} if token else None
+        timeout = aiohttp.ClientTimeout(total=None)
+
+        try:
+            async with aiohttp.ClientSession(timeout=timeout, headers=headers) as session:
+                async with session.get(media_url, params={"allow_remote": "true"}) as response:
+                    if response.status >= 400:
+                        self.logger.warning("download failed for {}: HTTP {}", mxc_url, response.status)
+                        return None
+                    content_length = response.headers.get("Content-Length")
+                    if content_length is not None:
+                        try:
+                            if int(content_length) > limit_bytes:
+                                raise _MediaTooLargeError
+                        except ValueError:
+                            pass
+
+                    chunks = bytearray()
+                    async for chunk in response.content.iter_chunked(64 * 1024):
+                        chunks.extend(chunk)
+                        if len(chunks) > limit_bytes:
+                            raise _MediaTooLargeError
+                    return bytes(chunks)
+        except _MediaTooLargeError:
+            raise
+        except (aiohttp.ClientError, asyncio.TimeoutError, OSError):
+            self.logger.warning("download failed for {}", mxc_url, exc_info=True)
             return None
-        body = getattr(response, "body", None)
-        if isinstance(body, (bytes, bytearray)):
-            return bytes(body)
-        if isinstance(response, MemoryDownloadResponse):
-            return bytes(response.body)
-        if isinstance(body, (str, Path)):
-            path = Path(body)
-            if path.is_file():
-                try:
-                    return path.read_bytes()
-                except OSError:
-                    return None
-        return None
 
     def _decrypt_media_bytes(self, event: MatrixMediaEvent, ciphertext: bytes) -> bytes | None:
         key_obj, hashes, iv = getattr(event, "key", None), getattr(event, "hashes", None), getattr(event, "iv", None)
@@ -820,10 +848,14 @@ class MatrixChannel(BaseChannel):
 
         limit_bytes = await self._effective_media_limit_bytes()
         declared = self._event_declared_size_bytes(event)
-        if declared is not None and declared > limit_bytes:
+        if declared is None or declared > limit_bytes:
             return None, _ATTACH_TOO_LARGE.format(filename)
 
-        downloaded = await self._download_media_bytes(mxc_url)
+        try:
+            async with self._media_download_semaphore:
+                downloaded = await self._download_media_bytes(mxc_url, limit_bytes)
+        except _MediaTooLargeError:
+            return None, _ATTACH_TOO_LARGE.format(filename)
         if downloaded is None:
             return None, fail
 

nanobot/channels/msteams.py

@@ -53,6 +53,13 @@ if MSTEAMS_AVAILABLE:
 
 MSTEAMS_REF_TTL_DAYS = 30
 MSTEAMS_WEBCHAT_HOST = "webchat.botframework.com"
+MSTEAMS_DEFAULT_TRUSTED_SERVICE_URL_HOSTS = [
+    "smba.trafficmanager.net",
+    "smba.infra.gcc.teams.microsoft.com",
+    "smba.infra.gov.teams.microsoft.us",
+    "smba.infra.dod.teams.microsoft.us",
+    "*.botframework.com",
+]
 MSTEAMS_REF_META_FILENAME = "msteams_conversations_meta.json"
 MSTEAMS_REF_LOCK_FILENAME = "msteams_conversations.lock"
 MSTEAMS_REF_TOUCH_INTERVAL_S = 300
@@ -76,6 +83,9 @@ class MSTeamsConfig(Base):
     prune_web_chat_refs: bool = True
     prune_non_personal_refs: bool = True
     ref_touch_interval_s: int = Field(default=MSTEAMS_REF_TOUCH_INTERVAL_S, ge=0)
+    trusted_service_url_hosts: list[str] = Field(
+        default_factory=lambda: MSTEAMS_DEFAULT_TRUSTED_SERVICE_URL_HOSTS.copy()
+    )
 
 
 @dataclass
@@ -242,6 +252,11 @@ class MSTeamsChannel(BaseChannel):
         if not ref:
             raise RuntimeError(f"MSTeams conversation ref not found for chat_id={msg.chat_id}")
 
+        if not self._is_trusted_service_url(ref.service_url):
+            raise RuntimeError(
+                f"MSTeams conversation ref has untrusted service_url for chat_id={msg.chat_id}"
+            )
+
         token = await self._get_access_token()
         base_url = f"{ref.service_url.rstrip('/')}/v3/conversations/{ref.conversation_id}/activities"
         use_thread_reply = self.config.reply_in_thread and bool(ref.activity_id)
@@ -284,6 +299,13 @@ class MSTeamsChannel(BaseChannel):
         if not sender_id or not conversation_id or not service_url:
             return
 
+        if not self._is_trusted_service_url(service_url):
+            self.logger.warning(
+                "Ignoring MSTeams activity with untrusted serviceUrl host: {}",
+                service_url,
+            )
+            return
+
         if recipient.get("id") and from_user.get("id") == recipient.get("id"):
             return
 
@@ -626,6 +648,29 @@ class MSTeamsChannel(BaseChannel):
             return host == MSTEAMS_WEBCHAT_HOST or host.endswith(f".{MSTEAMS_WEBCHAT_HOST}")
         return MSTEAMS_WEBCHAT_HOST in normalized.lower()
 
+    def _is_trusted_service_url(self, service_url: str) -> bool:
+        """Return True for HTTPS Bot Framework service URLs trusted for bearer replies."""
+        parsed = urlparse(service_url.strip())
+        if parsed.scheme.lower() != "https":
+            return False
+
+        host = (parsed.hostname or "").strip().lower().rstrip(".")
+        if not host:
+            return False
+
+        for pattern in self.config.trusted_service_url_hosts:
+            trusted_host = str(pattern or "").strip().lower().rstrip(".")
+            if not trusted_host:
+                continue
+            if trusted_host.startswith("*."):
+                suffix = trusted_host[1:]
+                if host.endswith(suffix) and host != suffix.lstrip("."):
+                    return True
+                continue
+            if host == trusted_host:
+                return True
+        return False
+
     def _prune_conversation_refs(self, *, now: float | None = None) -> bool:
         """Remove stale and unsupported conversation refs from memory."""
         if not self._conversation_refs:
@@ -637,6 +682,10 @@ class MSTeamsChannel(BaseChannel):
         keys_to_drop: list[str] = []
 
         for key, ref in self._conversation_refs.items():
+            if not self._is_trusted_service_url(ref.service_url):
+                keys_to_drop.append(key)
+                continue
+
             if self.config.prune_web_chat_refs and self._is_webchat_service_url(ref.service_url):
                 keys_to_drop.append(key)
                 continue

nanobot/channels/telegram.py

@@ -10,8 +10,9 @@ from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Literal
+from urllib.parse import urlparse
 
-from pydantic import Field
+from pydantic import Field, field_validator, model_validator
 from telegram import (
     BotCommand,
     InlineKeyboardButton,
@@ -225,11 +226,22 @@ class _StreamBuf:
     stream_id: str | None = None
 
 
+@dataclass
+class _QueuedTelegramUpdate:
+    """Telegram update staged for per-session ordered processing."""
+
+    kind: Literal["command", "message"]
+    update: Update
+    context: Any
+    sort_key: tuple[int, int]
+
+
 class TelegramConfig(Base):
     """Telegram channel configuration."""
 
     enabled: bool = False
     token: str = ""
+    mode: Literal["polling", "webhook"] = "polling"
     allow_from: list[str] = Field(default_factory=list)
     proxy: str | None = None
     reply_to_message: bool = False
@@ -241,13 +253,48 @@ class TelegramConfig(Base):
     # Enable inline keyboard buttons in Telegram messages.
     inline_keyboards: bool = False
     stream_edit_interval: float = Field(default=_STREAM_EDIT_INTERVAL_DEFAULT, ge=0.1)
+    webhook_url: str = ""
+    webhook_listen_host: str = "127.0.0.1"
+    webhook_listen_port: int = Field(default=8081, ge=1, le=65535)
+    webhook_path: str = "/telegram"
+    webhook_secret_token: str = ""
+    webhook_max_connections: int = Field(default=4, ge=1, le=100)
+
+    @field_validator("webhook_path")
+    @classmethod
+    def webhook_path_must_start_with_slash(cls, value: str) -> str:
+        value = value.strip() or "/telegram"
+        if not value.startswith("/"):
+            raise ValueError('webhook_path must start with "/"')
+        return value
+
+    @model_validator(mode="after")
+    def validate_webhook_config(self) -> "TelegramConfig":
+        if self.mode != "webhook":
+            return self
+
+        url = self.webhook_url.strip()
+        if not url:
+            raise ValueError("webhook_url is required when Telegram mode is webhook")
+        parsed = urlparse(url)
+        if parsed.scheme != "https" or not parsed.netloc:
+            raise ValueError("webhook_url must be a public HTTPS URL")
+        secret = self.webhook_secret_token.strip()
+        if not secret:
+            raise ValueError("webhook_secret_token is required when Telegram mode is webhook")
+        if len(secret) > 256 or re.match(r"^[A-Za-z0-9_-]+$", secret) is None:
+            raise ValueError(
+                "webhook_secret_token must be 1-256 characters using only A-Z, a-z, 0-9, _ and -"
+            )
+        return self
 
 
 class TelegramChannel(BaseChannel):
     """
-    Telegram channel using long polling.
+    Telegram channel using long polling or webhook mode.
 
-    Simple and reliable - no webhook/public IP needed.
+    Long polling is the default. Webhook mode requires a public HTTPS URL and a
+    Telegram secret token.
     """
 
     name = "telegram"
@@ -294,6 +341,8 @@ class TelegramChannel(BaseChannel):
         self._bot_user_id: int | None = None
         self._bot_username: str | None = None
         self._stream_bufs: dict[str, _StreamBuf] = {}  # chat_id -> streaming state
+        self._inbound_buffers: dict[str, list[_QueuedTelegramUpdate]] = {}
+        self._inbound_workers: dict[str, asyncio.Task] = {}
 
     def is_allowed(self, sender_id: str) -> bool:
         """Preserve Telegram's legacy id|username allowlist matching."""
@@ -326,7 +375,7 @@ class TelegramChannel(BaseChannel):
         return content
 
     async def start(self) -> None:
-        """Start the Telegram bot with long polling."""
+        """Start the Telegram bot."""
         if not self.config.token:
             self.logger.error("bot token not configured")
             return
@@ -394,9 +443,12 @@ class TelegramChannel(BaseChannel):
         else:
             allowed_updates = ["message"]
 
-        self.logger.info("Starting bot (polling mode)...")
+        if self.config.mode == "webhook":
+            self.logger.info("Starting bot (webhook mode)...")
+        else:
+            self.logger.info("Starting bot (polling mode)...")
 
-        # Initialize and start polling
+        # Initialize and start receiving updates
         await self._app.initialize()
         await self._app.start()
 
@@ -412,12 +464,26 @@ class TelegramChannel(BaseChannel):
         except Exception as e:
             self.logger.warning("Failed to register bot commands: {}", e)
 
-        # Start polling (this runs until stopped)
-        await self._app.updater.start_polling(
-            allowed_updates=allowed_updates,
-            drop_pending_updates=False,  # Process pending messages on startup
-            error_callback=self._on_polling_error,
-        )
+        if self.config.mode == "webhook":
+            # ``url_path`` is the local HTTP route. ``webhook_url`` is the
+            # public HTTPS URL Telegram calls; reverse proxies may rewrite it.
+            await self._app.updater.start_webhook(
+                listen=self.config.webhook_listen_host,
+                port=self.config.webhook_listen_port,
+                url_path=self.config.webhook_path.lstrip("/"),
+                webhook_url=self.config.webhook_url.strip(),
+                allowed_updates=allowed_updates,
+                drop_pending_updates=False,
+                secret_token=self.config.webhook_secret_token.strip(),
+                max_connections=self.config.webhook_max_connections,
+            )
+        else:
+            # Start polling (this runs until stopped)
+            await self._app.updater.start_polling(
+                allowed_updates=allowed_updates,
+                drop_pending_updates=False,  # Process pending messages on startup
+                error_callback=self._on_polling_error,
+            )
 
         # Keep running until stopped
         while self._running:
@@ -436,6 +502,11 @@ class TelegramChannel(BaseChannel):
         self._media_group_tasks.clear()
         self._media_group_buffers.clear()
 
+        for task in self._inbound_workers.values():
+            task.cancel()
+        self._inbound_workers.clear()
+        self._inbound_buffers.clear()
+
         if self._app:
             self.logger.info("Stopping bot...")
             await self._app.updater.stop()
@@ -995,10 +1066,85 @@ class TelegramChannel(BaseChannel):
         if len(self._message_threads) > 1000:
             self._message_threads.pop(next(iter(self._message_threads)))
 
+    @staticmethod
+    def _queue_key_for_message(message) -> str:
+        """Return the final nanobot session key used for ordered Telegram ingress."""
+        return TelegramChannel._derive_topic_session_key(message) or f"telegram:{message.chat_id}"
+
+    @staticmethod
+    def _sort_key_for_update(update: Update) -> tuple[int, int]:
+        """Sort by chat message id first, then Telegram update id."""
+        message = getattr(update, "message", None)
+        message_id = int(getattr(message, "message_id", 0) or 0)
+        update_id = int(getattr(update, "update_id", 0) or 0)
+        return (message_id, update_id)
+
+    def _enqueue_ordered_update(
+        self,
+        *,
+        kind: Literal["command", "message"],
+        update: Update,
+        context: ContextTypes.DEFAULT_TYPE,
+    ) -> None:
+        """Stage a Telegram update behind a short per-session reorder window."""
+        message = update.message
+        key = self._queue_key_for_message(message)
+        self._inbound_buffers.setdefault(key, []).append(
+            _QueuedTelegramUpdate(
+                kind=kind,
+                update=update,
+                context=context,
+                sort_key=self._sort_key_for_update(update),
+            )
+        )
+        if key not in self._inbound_workers:
+            self._inbound_workers[key] = asyncio.create_task(
+                self._drain_ordered_updates(key)
+            )
+
+    async def _drain_ordered_updates(self, key: str) -> None:
+        """Drain one Telegram session buffer in stable message order."""
+        try:
+            while self._running:
+                await asyncio.sleep(0.2)
+                batch = self._inbound_buffers.get(key, [])
+                if not batch:
+                    break
+                self._inbound_buffers[key] = []
+                batch.sort(key=lambda item: item.sort_key)
+                for item in batch:
+                    try:
+                        if item.kind == "command":
+                            await self._process_forward_command(item.update, item.context)
+                        else:
+                            await self._process_message_update(item.update, item.context)
+                    except Exception as e:
+                        self.logger.warning(
+                            "Telegram queued update handling failed for {}: {}",
+                            key,
+                            e,
+                        )
+            if not self._inbound_buffers.get(key):
+                self._inbound_buffers.pop(key, None)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            self.logger.warning("Telegram ordered update worker failed for {}: {}", key, e)
+        finally:
+            if not self._inbound_buffers.get(key):
+                self._inbound_workers.pop(key, None)
+
     async def _forward_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         """Forward slash commands to the bus for unified handling in AgentLoop."""
         if not update.message or not update.effective_user:
             return
+        if not self._running:
+            await self._process_forward_command(update, context)
+            return
+        self._enqueue_ordered_update(kind="command", update=update, context=context)
+
+    async def _process_forward_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Process a queued slash command."""
         message = update.message
         user = update.effective_user
         sender_id = self._sender_id(user)
@@ -1027,6 +1173,13 @@ class TelegramChannel(BaseChannel):
         """Handle incoming messages (text, photos, voice, documents)."""
         if not update.message or not update.effective_user:
             return
+        if not self._running:
+            await self._process_message_update(update, context)
+            return
+        self._enqueue_ordered_update(kind="message", update=update, context=context)
+
+    async def _process_message_update(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Process a queued Telegram message update."""
 
         message = update.message
         user = update.effective_user

nanobot/cli/commands.py

@@ -1,6 +1,7 @@
 """CLI commands for nanobot."""
 
 import asyncio
+import functools
 import os
 import select
 import signal
@@ -75,6 +76,7 @@ class SafeFileHistory(FileHistory):
 from nanobot.cli.stream import StreamRenderer, ThinkingSpinner
 from nanobot.config.paths import get_workspace_path, is_default_workspace
 from nanobot.config.schema import Config
+from nanobot.utils.evaluator import evaluate_response
 from nanobot.utils.helpers import sync_workspace_templates
 from nanobot.utils.restart import (
     consume_restart_notice_from_env,
@@ -94,6 +96,20 @@ EXIT_COMMANDS = {"exit", "quit", "/exit", "/quit", ":q"}
 _REASONING_SENTENCE_ENDINGS = (".", "!", "?", "。", "！", "？")
 _REASONING_FLUSH_CHARS = 60
 
+_HEARTBEAT_PREAMBLE = (
+    "[Your response will be delivered directly to the user's messaging app. "
+    "Output ONLY the final user-facing message. Never reference internal "
+    "files (HEARTBEAT.md, AWARENESS.md, etc.), your instructions, or your "
+    "decision process. If nothing needs reporting, respond with a brief "
+    "no-op status and nothing else.]\n\n"
+)
+
+
+@functools.lru_cache(maxsize=None)
+def _heartbeat_template() -> str | None:
+    from nanobot.utils.helpers import load_bundled_template
+    return load_bundled_template("HEARTBEAT.md")
+
 # ---------------------------------------------------------------------------
 # CLI input: prompt_toolkit for editing, paste, history, and display
 # ---------------------------------------------------------------------------
@@ -704,11 +720,144 @@ def gateway(
     _run_gateway(cfg, port=port)
 
 
+def _load_or_create_desktop_config(config: str | None, workspace: str | None) -> Config:
+    """Load the desktop-owned config, creating it on first launch."""
+    from nanobot.config.loader import (
+        get_config_path,
+        load_config,
+        resolve_config_env_vars,
+        save_config,
+        set_config_path,
+    )
+    from nanobot.config.schema import Config as NanobotConfig
+
+    config_path = Path(config).expanduser().resolve() if config else get_config_path()
+    set_config_path(config_path)
+    created = False
+    if config_path.exists():
+        try:
+            loaded = resolve_config_env_vars(load_config(config_path))
+        except ValueError as e:
+            console.print(f"[red]Error: {e}[/red]")
+            raise typer.Exit(1)
+    else:
+        loaded = NanobotConfig()
+        created = True
+
+    if workspace:
+        workspace_path = Path(workspace).expanduser()
+        loaded.agents.defaults.workspace = str(workspace_path)
+        created = True
+
+    if created:
+        save_config(loaded, config_path)
+    return loaded
+
+
+def _configure_desktop_gateway(
+    config: Config,
+    *,
+    webui_port: int,
+    webui_socket: str | None,
+    token_issue_secret: str,
+) -> None:
+    """Force a local WebSocket-only gateway for the desktop app process."""
+    config.gateway.host = "127.0.0.1"
+    config.gateway.port = webui_port
+    config.gateway.heartbeat.enabled = False
+
+    extras = dict(getattr(config.channels, "__pydantic_extra__", None) or {})
+    for name, section in list(extras.items()):
+        if name == "websocket":
+            continue
+        if isinstance(section, dict):
+            extras[name] = {**section, "enabled": False}
+        else:
+            with suppress(Exception):
+                setattr(section, "enabled", False)
+            extras[name] = section
+
+    websocket_cfg = extras.get("websocket")
+    if not isinstance(websocket_cfg, dict):
+        websocket_cfg = {}
+    websocket_cfg.update(
+        {
+            "enabled": True,
+            "host": "127.0.0.1",
+            "port": webui_port,
+            "unix_socket_path": webui_socket or "",
+            "path": "/",
+            "token_issue_secret": token_issue_secret,
+            "websocket_requires_token": True,
+            "allow_from": ["*"],
+            "streaming": True,
+        }
+    )
+    extras["websocket"] = websocket_cfg
+    config.channels.__pydantic_extra__ = extras
+
+
+@app.command("desktop-gateway", hidden=True)
+def desktop_gateway(
+    webui_port: int = typer.Option(0, "--webui-port", min=0, max=65535),
+    webui_socket: str | None = typer.Option(None, "--webui-socket", help="Unix socket path for desktop IPC"),
+    token_issue_secret: str = typer.Option(..., "--token-issue-secret"),
+    workspace: str | None = typer.Option(None, "--workspace", "-w", help="Desktop workspace directory"),
+    config: str | None = typer.Option(None, "--config", "-c", help="Desktop config file"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
+):
+    """Start the private local gateway used by nanobot Desktop."""
+    if not token_issue_secret.strip():
+        console.print("[red]Error: --token-issue-secret is required[/red]")
+        raise typer.Exit(1)
+    if webui_port <= 0 and not (webui_socket or "").strip():
+        console.print("[red]Error: --webui-port or --webui-socket is required[/red]")
+        raise typer.Exit(1)
+    if verbose:
+        logger.remove(_log_handler_id)
+        logger.add(
+            sys.stderr,
+            format=(
+                "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+                "<level>{level: <5}</level> | "
+                "<cyan>{extra[channel]}</cyan> | "
+                "<level>{message}</level>"
+            ),
+            level="DEBUG",
+            colorize=None,
+            filter=lambda record: record["extra"].setdefault("channel", "-") or True,
+        )
+    cfg = _load_or_create_desktop_config(config, workspace)
+    _configure_desktop_gateway(
+        cfg,
+        webui_port=webui_port,
+        webui_socket=webui_socket,
+        token_issue_secret=token_issue_secret,
+    )
+    _run_gateway(
+        cfg,
+        port=webui_port,
+        webui_static_dist=False,
+        webui_runtime_surface="native",
+        webui_runtime_capabilities={
+            "can_restart_engine": True,
+            "can_pick_folder": True,
+            "can_open_logs": True,
+            "can_export_diagnostics": True,
+        },
+        health_server_enabled=False,
+    )
+
+
 def _run_gateway(
     config: Config,
     *,
     port: int | None = None,
     open_browser_url: str | None = None,
+    webui_static_dist: bool = True,
+    webui_runtime_surface: str = "browser",
+    webui_runtime_capabilities: dict[str, Any] | None = None,
+    health_server_enabled: bool = True,
 ) -> None:
     """Shared gateway runtime; ``open_browser_url`` opens a tab once channels are up."""
     from nanobot.agent.tools.cron import CronTool
@@ -718,7 +867,6 @@ def _run_gateway(
     from nanobot.channels.websocket import publish_runtime_model_update
     from nanobot.cron.service import CronService
     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
@@ -810,6 +958,9 @@ def _run_gateway(
     # Set cron callback (needs agent)
     async def on_cron_job(job: CronJob) -> str | None:
         """Execute a cron job through the agent."""
+        async def _silent(*_args, **_kwargs):
+            pass
+
         # Dream is an internal job — run directly, not through the agent loop.
         if job.name == "dream":
             try:
@@ -819,7 +970,64 @@ def _run_gateway(
                 logger.exception("Dream cron job failed")
             return None
 
-        from nanobot.utils.evaluator import evaluate_response
+        # Heartbeat is a system job that checks HEARTBEAT.md for active tasks.
+        if job.name == "heartbeat":
+            heartbeat_file = config.workspace_path / "HEARTBEAT.md"
+            try:
+                content = heartbeat_file.read_text(encoding="utf-8")
+            except OSError:
+                logger.debug("Heartbeat: HEARTBEAT.md missing")
+                return None
+            if not content or content == _heartbeat_template():
+                logger.debug("Heartbeat: HEARTBEAT.md empty or identical to template")
+                return None
+
+            channel, chat_id = _pick_heartbeat_target()
+            if channel == "cli":
+                return None
+
+            prompt = (
+                _HEARTBEAT_PREAMBLE
+                + f"Review the following HEARTBEAT.md and report any active tasks:\n\n{content}"
+            )
+
+            message_suppress_token = None
+            if isinstance(message_tool, MessageTool):
+                message_suppress_token = message_tool.set_suppress_delivery(True)
+
+            try:
+                resp = await agent.process_direct(
+                    prompt,
+                    session_key="heartbeat",
+                    channel=channel,
+                    chat_id=chat_id,
+                    on_progress=_silent,
+                )
+            finally:
+                if isinstance(message_tool, MessageTool) and message_suppress_token is not None:
+                    message_tool.reset_suppress_delivery(message_suppress_token)
+            response = resp.content if resp else ""
+
+            # Keep a small tail of heartbeat history so the loop stays bounded.
+            session = agent.sessions.get_or_create("heartbeat")
+            session.retain_recent_legal_suffix(hb_cfg.keep_recent_messages)
+            agent.sessions.save(session)
+
+            if not response:
+                return None
+
+            should_notify = await evaluate_response(
+                response, prompt, agent.provider, agent.model, default_notify=False,
+            )
+            if should_notify:
+                logger.info("Heartbeat: completed, delivering response")
+                await _deliver_to_channel(
+                    OutboundMessage(channel=channel, chat_id=chat_id, content=response),
+                    record=True,
+                )
+            else:
+                logger.info("Heartbeat: silenced by post-run evaluation")
+            return response
 
         reminder_note = (
             "The scheduled time has arrived. Deliver this reminder to the user now, "
@@ -834,9 +1042,6 @@ def _run_gateway(
         if isinstance(cron_tool, CronTool):
             cron_token = cron_tool.set_cron_context(True)
 
-        async def _silent(*_args, **_kwargs):
-            pass
-
         message_record_token = None
         if isinstance(message_tool, MessageTool):
             message_record_token = message_tool.set_record_channel_delivery(True)
@@ -893,12 +1098,14 @@ def _run_gateway(
         bus,
         session_manager=session_manager,
         webui_runtime_model_name=_webui_runtime_model_name,
+        webui_static_dist=webui_static_dist,
+        webui_runtime_surface=webui_runtime_surface,
+        webui_runtime_capabilities=webui_runtime_capabilities,
     )
 
     def _pick_heartbeat_target() -> tuple[str, str]:
         """Pick a routable channel/chat target for heartbeat-triggered messages."""
         enabled = set(channels.enabled_channels)
-        # Prefer the most recently updated non-internal session on an enabled channel.
         for item in session_manager.list_sessions():
             key = item.get("key") or ""
             if ":" not in key:
@@ -908,70 +1115,8 @@ def _run_gateway(
                 continue
             if channel in enabled and chat_id:
                 return channel, chat_id
-        # Fallback keeps prior behavior but remains explicit.
         return "cli", "direct"
 
-    # Create heartbeat service
-    heartbeat_preamble = (
-        "[Your response will be delivered directly to the user's messaging app. "
-        "Output ONLY the final user-facing message. Never reference internal "
-        "files (HEARTBEAT.md, AWARENESS.md, etc.), your instructions, or your "
-        "decision process. If nothing needs reporting, respond with just "
-        "'All clear.' and nothing else.]\n\n"
-    )
-
-    async def on_heartbeat_execute(tasks: str) -> str:
-        """Phase 2: execute heartbeat tasks through the full agent loop."""
-        channel, chat_id = _pick_heartbeat_target()
-
-        async def _silent(*_args, **_kwargs):
-            pass
-
-        resp = await agent.process_direct(
-            heartbeat_preamble + tasks,
-            session_key="heartbeat",
-            channel=channel,
-            chat_id=chat_id,
-            on_progress=_silent,
-        )
-
-        # Keep a small tail of heartbeat history so the loop stays bounded
-        # without losing all short-term context between runs.
-        session = agent.sessions.get_or_create("heartbeat")
-        session.retain_recent_legal_suffix(hb_cfg.keep_recent_messages)
-        agent.sessions.save(session)
-
-        return resp.content if resp else ""
-
-    async def on_heartbeat_notify(response: str) -> None:
-        """Deliver a heartbeat response to the user's channel.
-
-        In addition to publishing the outbound message, this injects the
-        delivered text as an assistant turn into the *target channel's*
-        session.  Without this, a user reply on the channel (e.g. "Sure")
-        lands in a session that has no context about the heartbeat message
-        and the agent cannot follow through.
-        """
-        channel, chat_id = _pick_heartbeat_target()
-        if channel == "cli":
-            return  # No external channel available to deliver to
-
-        await _deliver_to_channel(
-            OutboundMessage(channel=channel, chat_id=chat_id, content=response),
-            record=True,
-        )
-
-    hb_cfg = config.gateway.heartbeat
-    heartbeat = HeartbeatService(
-        workspace=config.workspace_path,
-        llm_runtime=agent.llm_runtime,
-        on_execute=on_heartbeat_execute,
-        on_notify=on_heartbeat_notify,
-        interval_s=hb_cfg.interval_s,
-        enabled=hb_cfg.enabled,
-        timezone=config.agents.defaults.timezone,
-    )
-
     if channels.enabled_channels:
         console.print(f"[green]✓[/green] Channels enabled: {', '.join(channels.enabled_channels)}")
     else:
@@ -981,7 +1126,11 @@ def _run_gateway(
     if cron_status["jobs"] > 0:
         console.print(f"[green]✓[/green] Cron: {cron_status['jobs']} scheduled jobs")
 
-    console.print(f"[green]✓[/green] Heartbeat: every {hb_cfg.interval_s}s")
+    hb_cfg = config.gateway.heartbeat
+    if hb_cfg.enabled:
+        console.print(f"[green]✓[/green] Heartbeat: every {hb_cfg.interval_s}s")
+    else:
+        console.print("[yellow]✗[/yellow] Heartbeat: disabled")
 
     async def _health_server(host: str, health_port: int):
         """Lightweight HTTP health endpoint on the gateway port."""
@@ -1025,21 +1174,37 @@ def _run_gateway(
         console.print(f"[green]✓[/green] Health endpoint: http://{host}:{health_port}/health")
         async with server:
             await server.serve_forever()
-    # Register Dream system job (always-on, idempotent on restart)
+    # Register Dream system job (idempotent on restart)
     dream_cfg = config.agents.defaults.dream
     if dream_cfg.model_override:
         agent.dream.model = dream_cfg.model_override
     agent.dream.max_batch_size = dream_cfg.max_batch_size
     agent.dream.max_iterations = dream_cfg.max_iterations
     agent.dream.annotate_line_ages = dream_cfg.annotate_line_ages
-    from nanobot.cron.types import CronJob, CronPayload
-    cron.register_system_job(CronJob(
-        id="dream",
-        name="dream",
-        schedule=dream_cfg.build_schedule(config.agents.defaults.timezone),
-        payload=CronPayload(kind="system_event"),
-    ))
-    console.print(f"[green]✓[/green] Dream: {dream_cfg.describe_schedule()}")
+    from nanobot.cron.types import CronJob, CronPayload, CronSchedule
+    if dream_cfg.enabled:
+        cron.register_system_job(CronJob(
+            id="dream",
+            name="dream",
+            schedule=dream_cfg.build_schedule(config.agents.defaults.timezone),
+            payload=CronPayload(kind="system_event"),
+        ))
+        console.print(f"[green]✓[/green] Dream: {dream_cfg.describe_schedule()}")
+    else:
+        console.print("[yellow]○[/yellow] Dream: disabled")
+
+    # Register Heartbeat system job (idempotent on restart)
+    if hb_cfg.enabled:
+        cron.register_system_job(CronJob(
+            id="heartbeat",
+            name="heartbeat",
+            schedule=CronSchedule(
+                kind="every",
+                every_ms=hb_cfg.interval_s * 1000,
+                tz=config.agents.defaults.timezone,
+            ),
+            payload=CronPayload(kind="system_event"),
+        ))
 
     async def _open_browser_when_ready() -> None:
         """Wait for the gateway to bind, then point the user's browser at the webui."""
@@ -1067,12 +1232,12 @@ def _run_gateway(
     async def run():
         try:
             await cron.start()
-            await heartbeat.start()
             tasks = [
                 agent.run(),
                 channels.start_all(),
-                _health_server(config.gateway.host, port),
             ]
+            if health_server_enabled:
+                tasks.append(_health_server(config.gateway.host, port))
             if open_browser_url:
                 tasks.append(_open_browser_when_ready())
             await asyncio.gather(*tasks)
@@ -1085,7 +1250,6 @@ def _run_gateway(
             console.print(traceback.format_exc())
         finally:
             await agent.close_mcp()
-            heartbeat.stop()
             cron.stop()
             agent.stop()
             await channels.stop_all()

nanobot/cli/onboard.py

@@ -1155,7 +1155,7 @@ _SETTINGS_SECTIONS: dict[str, tuple[str, str, set[str] | None]] = {
     "Agent Settings": ("Agent Defaults", "Configure default model, temperature, and behavior", None),
     "Channel Common": ("Channel Common", "Configure cross-channel behavior: progress, tool hints, retries", None),
     "API Server": ("API Server", "Configure OpenAI-compatible API endpoint", None),
-    "Gateway": ("Gateway Settings", "Configure server host, port, and heartbeat", None),
+    "Gateway": ("Gateway Settings", "Configure server host, port", None),
     "Tools": ("Tools Settings", "Configure web search, shell exec, and other tools", {"mcp_servers"}),
 }
 

nanobot/command/builtin.py

@@ -123,7 +123,7 @@ async def cmd_stop(ctx: CommandContext) -> OutboundMessage:
     """Cancel all active tasks and subagents for the session."""
     loop = ctx.loop
     msg = ctx.msg
-    total = await loop._cancel_active_tasks(msg.session_key)
+    total = await loop._cancel_active_tasks(ctx.key)
     content = f"Stopped {total} task(s)." if total else "No active task to stop."
     return OutboundMessage(
         channel=msg.channel, chat_id=msg.chat_id, content=content,

nanobot/config/loader.py

@@ -10,10 +10,11 @@ import pydantic
 from loguru import logger
 from pydantic import BaseModel
 
-from nanobot.config.schema import Config
+from nanobot.config.schema import Config, _resolve_tool_config_refs
 
 # Global variable to store current config path (for multi-instance support)
 _current_config_path: Path | None = None
+_schema_refs_ready = False
 
 
 def set_config_path(path: Path) -> None:
@@ -39,6 +40,11 @@ def load_config(config_path: Path | None = None) -> Config:
     Returns:
         Loaded configuration object.
     """
+    global _schema_refs_ready
+    if not _schema_refs_ready:
+        _resolve_tool_config_refs()
+        _schema_refs_ready = True
+
     path = config_path or get_config_path()
 
     config = Config()

nanobot/config/schema.py

@@ -37,6 +37,7 @@ class ChannelsConfig(Base):
     send_progress: bool = True  # stream agent's text progress to the channel
     send_tool_hints: bool = False  # stream tool-call hints (e.g. read_file("…"))
     show_reasoning: bool = True  # surface model reasoning when channel implements it
+    extract_document_text: bool = True  # extract text from document attachments before sending to the model
     send_max_retries: int = Field(default=3, ge=0, le=10)  # Max delivery attempts (initial send included)
     transcription_provider: str = "groq"  # Voice transcription backend: "groq" or "openai"
     transcription_language: str | None = Field(default=None, pattern=r"^[a-z]{2,3}$")  # Optional ISO-639-1 hint for audio transcription
@@ -47,6 +48,7 @@ class DreamConfig(Base):
 
     _HOUR_MS = 3_600_000
 
+    enabled: bool = True  # Register the periodic Dream consolidation job on startup
     interval_h: int = Field(default=2, ge=1)  # Every 2 hours by default
     cron: str | None = Field(default=None, exclude=True)  # Legacy compatibility override
     model_override: str | None = Field(
@@ -92,6 +94,7 @@ FallbackCandidate = str | InlineFallbackConfig
 class ModelPresetConfig(Base):
     """A named set of model + generation parameters for quick switching."""
 
+    label: str | None = None
     model: str
     provider: str = "auto"
     max_tokens: int = 8192
@@ -170,8 +173,9 @@ class ProviderConfig(Base):
 
     api_key: str | None = None
     api_base: str | None = None
+    api_type: Literal["auto", "chat_completions", "responses"] = "auto"  # Request API surface
     extra_headers: dict[str, str] | None = None  # Custom headers (e.g. APP-Code for AiHubMix)
-    extra_body: dict[str, Any] | None = None  # Extra fields merged into every request body
+    extra_body: dict[str, Any] | None = None  # Extra provider request fields; shape depends on provider/API surface
 
 
 class BedrockProviderConfig(ProviderConfig):
@@ -222,9 +226,19 @@ class ProvidersConfig(Base):
     qianfan: ProviderConfig = Field(default_factory=ProviderConfig)  # Qianfan (百度千帆)
     nvidia: ProviderConfig = Field(default_factory=ProviderConfig)  # NVIDIA NIM (nvapi- keys)
 
+    @model_validator(mode="after")
+    def _validate_api_type_scope(self) -> "ProvidersConfig":
+        for name in self.__class__.model_fields:
+            if name == "openai":
+                continue
+            provider = getattr(self, name, None)
+            if isinstance(provider, ProviderConfig) and provider.api_type != "auto":
+                raise ValueError("providers.<name>.api_type is only supported for providers.openai")
+        return self
+
 
 class HeartbeatConfig(Base):
-    """Heartbeat service configuration."""
+    """Heartbeat service configuration (now backed by cron)."""
 
     enabled: bool = True
     interval_s: int = 30 * 60  # 30 minutes
@@ -254,6 +268,7 @@ class MCPServerConfig(Base):
     command: str = ""  # Stdio: command to run (e.g. "npx")
     args: list[str] = Field(default_factory=list)  # Stdio: command arguments
     env: dict[str, str] = Field(default_factory=dict)  # Stdio: extra env vars
+    cwd: str = ""  # Stdio: working directory for MCP server runtime artifacts
     url: str = ""  # HTTP/SSE: endpoint URL
     headers: dict[str, str] = Field(default_factory=dict)  # HTTP/SSE: custom headers
     tool_timeout: int = 30  # seconds before a tool call is cancelled
@@ -282,7 +297,16 @@ class ToolsConfig(Base):
     image_generation: ImageGenerationToolConfig = Field(
         default_factory=lambda: _lazy_default("nanobot.agent.tools.image_generation", "ImageGenerationToolConfig"),
     )
-    restrict_to_workspace: bool = False  # restrict all tool access to workspace directory
+    restrict_to_workspace: bool = False  # policy intent: keep tool access inside workspace when possible
+    webui_allow_local_service_access: bool = Field(
+        default=True,
+        validation_alias=AliasChoices(
+            "webuiAllowLocalServiceAccess",
+            "webui_allow_local_service_access",
+            "allowLocalPreviewAccess",
+            "allow_local_preview_access",
+        ),
+    )  # allow WebUI Full Access shell checks against localhost services; legacy allowLocalPreviewAccess still reads
     mcp_servers: dict[str, MCPServerConfig] = Field(default_factory=dict)
     ssrf_whitelist: list[str] = Field(default_factory=list)  # CIDR ranges to exempt from SSRF blocking (e.g. ["100.64.0.0/10"] for Tailscale)
 
@@ -301,6 +325,11 @@ class Config(BaseSettings):
         validation_alias=AliasChoices("modelPresets", "model_presets"),
     )
 
+    def __init__(self, **values: Any) -> None:
+        if not type(self).__pydantic_complete__:
+            _resolve_tool_config_refs()
+        super().__init__(**values)
+
     @model_validator(mode="after")
     def _validate_model_preset(self) -> "Config":
         if "default" in self.model_presets:

nanobot/heartbeat/__init__.py

@@ -1,5 +0,0 @@
-"""Heartbeat service for periodic agent wake-ups."""
-
-from nanobot.heartbeat.service import HeartbeatService
-
-__all__ = ["HeartbeatService"]

nanobot/heartbeat/service.py

@@ -1,243 +0,0 @@
-"""Heartbeat service - periodic agent wake-up to check for tasks."""
-
-from __future__ import annotations
-
-import asyncio
-from pathlib import Path
-from typing import Any, Callable, Coroutine
-
-from loguru import logger
-
-from nanobot.providers.base import LLMProvider
-from nanobot.utils.llm_runtime import LLMRuntimeResolver, static_llm_runtime
-
-_HEARTBEAT_TOOL = [
-    {
-        "type": "function",
-        "function": {
-            "name": "heartbeat",
-            "description": "Report heartbeat decision after reviewing tasks.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "action": {
-                        "type": "string",
-                        "enum": ["skip", "run"],
-                        "description": "skip = nothing to do, run = has active tasks",
-                    },
-                    "tasks": {
-                        "type": "string",
-                        "description": "Natural-language summary of active tasks (required for run)",
-                    },
-                },
-                "required": ["action"],
-            },
-        },
-    }
-]
-
-
-class HeartbeatService:
-    """
-    Periodic heartbeat service that wakes the agent to check for tasks.
-
-    Phase 1 (decision): reads HEARTBEAT.md and asks the LLM — via a virtual
-    tool call — whether there are active tasks.  This avoids free-text parsing
-    and the unreliable HEARTBEAT_OK token.
-
-    Phase 2 (execution): only triggered when Phase 1 returns ``run``.  The
-    ``on_execute`` callback runs the task through the full agent loop and
-    returns the result to deliver.
-    """
-
-    def __init__(
-        self,
-        workspace: Path,
-        provider: LLMProvider | None = None,
-        model: str | None = None,
-        on_execute: Callable[[str], Coroutine[Any, Any, str]] | None = None,
-        on_notify: Callable[[str], Coroutine[Any, Any, None]] | None = None,
-        interval_s: int = 30 * 60,
-        enabled: bool = True,
-        timezone: str | None = None,
-        llm_runtime: LLMRuntimeResolver | None = None,
-    ):
-        self.workspace = workspace
-        if llm_runtime is None:
-            if provider is None or model is None:
-                raise ValueError("HeartbeatService requires either llm_runtime or provider/model")
-            llm_runtime = static_llm_runtime(provider, model)
-        self._llm_runtime = llm_runtime
-        self.on_execute = on_execute
-        self.on_notify = on_notify
-        self.interval_s = interval_s
-        self.enabled = enabled
-        self.timezone = timezone
-        self._running = False
-        self._task: asyncio.Task | None = None
-
-    @property
-    def heartbeat_file(self) -> Path:
-        return self.workspace / "HEARTBEAT.md"
-
-    def _read_heartbeat_file(self) -> str | None:
-        if self.heartbeat_file.exists():
-            try:
-                return self.heartbeat_file.read_text(encoding="utf-8")
-            except Exception:
-                return None
-        return None
-
-    async def _decide(self, content: str) -> tuple[str, str]:
-        """Phase 1: ask LLM to decide skip/run via virtual tool call.
-
-        Returns (action, tasks) where action is 'skip' or 'run'.
-        """
-        from nanobot.utils.helpers import current_time_str
-
-        llm = self._llm_runtime()
-
-        response = await llm.provider.chat_with_retry(
-            messages=[
-                {"role": "system", "content": "You are a heartbeat agent. Call the heartbeat tool to report your decision."},
-                {"role": "user", "content": (
-                    f"Current Time: {current_time_str(self.timezone)}\n\n"
-                    "Review the following HEARTBEAT.md and decide whether there are active tasks.\n\n"
-                    f"{content}"
-                )},
-            ],
-            tools=_HEARTBEAT_TOOL,
-            model=llm.model,
-        )
-
-        if not response.should_execute_tools:
-            if response.has_tool_calls:
-                logger.warning(
-                    "Ignoring heartbeat tool calls under finish_reason='{}'",
-                    response.finish_reason,
-                )
-            return "skip", ""
-
-        args = response.tool_calls[0].arguments
-        return args.get("action", "skip"), args.get("tasks", "")
-
-    async def start(self) -> None:
-        """Start the heartbeat service."""
-        if not self.enabled:
-            logger.info("Heartbeat disabled")
-            return
-        if self._running:
-            logger.warning("Heartbeat already running")
-            return
-
-        self._running = True
-        self._task = asyncio.create_task(self._run_loop())
-        logger.info("Heartbeat started (every {}s)", self.interval_s)
-
-    def stop(self) -> None:
-        """Stop the heartbeat service."""
-        self._running = False
-        if self._task:
-            self._task.cancel()
-            self._task = None
-
-    async def _run_loop(self) -> None:
-        """Main heartbeat loop."""
-        while self._running:
-            try:
-                await asyncio.sleep(self.interval_s)
-                if self._running:
-                    await self._tick()
-            except asyncio.CancelledError:
-                break
-            except Exception:
-                logger.exception("Heartbeat error")
-
-    @staticmethod
-    def _is_deliverable(response: str) -> bool:
-        """Check if a heartbeat response is suitable for user delivery.
-
-        Filters out two classes of bad output before the evaluator runs:
-
-        1. **Finalization fallback** — the runner hit empty-response retries
-           and produced a canned error message.  For heartbeat, empty output
-           is a valid "nothing to report" outcome, not a failure.
-        2. **Leaked reasoning** — the model reflected internal file names,
-           decision logic, or meta-commentary instead of a user-facing report.
-        """
-        text = response.lower()
-
-        # Runner finalization fallback
-        if "couldn't produce a final answer" in text:
-            return False
-
-        # Leaked internal reasoning patterns
-        leaked_patterns = [
-            "heartbeat.md",
-            "awareness.md",
-            "judgment call:",
-            "decision logic",
-            "valid options are",
-            "my instructions",
-            "i am supposed to",
-            "strict heartbeat interpretation",
-        ]
-        if any(pattern in text for pattern in leaked_patterns):
-            return False
-
-        return True
-
-    async def _tick(self) -> None:
-        """Execute a single heartbeat tick."""
-        from nanobot.utils.evaluator import evaluate_response
-
-        content = self._read_heartbeat_file()
-        if not content:
-            logger.debug("Heartbeat: HEARTBEAT.md missing or empty")
-            return
-
-        logger.info("Heartbeat: checking for tasks...")
-
-        try:
-            action, tasks = await self._decide(content)
-
-            if action != "run":
-                logger.info("Heartbeat: OK (nothing to report)")
-                return
-
-            logger.info("Heartbeat: tasks found, executing...")
-            if self.on_execute:
-                response = await self.on_execute(tasks)
-
-                if not response:
-                    logger.info("Heartbeat: no response from execution")
-                    return
-
-                if not self._is_deliverable(response):
-                    logger.info(
-                        "Heartbeat: suppressed non-deliverable response ({})",
-                        response[:80],
-                    )
-                    return
-
-                llm = self._llm_runtime()
-                should_notify = await evaluate_response(
-                    response, tasks, llm.provider, llm.model,
-                )
-                if should_notify and self.on_notify:
-                    logger.info("Heartbeat: completed, delivering response")
-                    await self.on_notify(response)
-                else:
-                    logger.info("Heartbeat: silenced by post-run evaluation")
-        except Exception:
-            logger.exception("Heartbeat execution failed")
-
-    async def trigger_now(self) -> str | None:
-        """Manually trigger a heartbeat."""
-        content = self._read_heartbeat_file()
-        if not content:
-            return None
-        action, tasks = await self._decide(content)
-        if action != "run" or not self.on_execute:
-            return None
-        return await self.on_execute(tasks)

nanobot/providers/anthropic_provider.py

@@ -45,13 +45,21 @@ class AnthropicProvider(LLMProvider):
         if api_key:
             client_kw["api_key"] = api_key
         if api_base:
-            client_kw["base_url"] = api_base
+            client_kw["base_url"] = self._normalize_base_url(api_base)
         if extra_headers:
             client_kw["default_headers"] = extra_headers
         # Keep retries centralized in LLMProvider._run_with_retry to avoid retry amplification.
         client_kw["max_retries"] = 0
         self._client = AsyncAnthropic(**client_kw)
 
+    @staticmethod
+    def _normalize_base_url(api_base: str) -> str:
+        """Anthropic SDK appends /v1 to request paths internally."""
+        normalized = api_base.rstrip("/")
+        if normalized.endswith("/v1"):
+            return normalized[: -len("/v1")]
+        return normalized
+
     @classmethod
     def _handle_error(cls, e: Exception) -> LLMResponse:
         response = getattr(e, "response", None)
@@ -228,6 +236,13 @@ class AnthropicProvider(LLMProvider):
                 if converted:
                     result.append(converted)
                 continue
+            if not item.get("type"):
+                # Anthropic requires every content block to declare a "type".
+                # A tool that returned a bare dict (or a list of dicts) lands
+                # here; coerce it to a text block instead of emitting a block
+                # the API rejects with "content.0.type: Field required".
+                result.append({"type": "text", "text": str(item)})
+                continue
             result.append(item)
         return result or "(empty)"
 

nanobot/providers/base.py

@@ -315,6 +315,29 @@ class LLMProvider(ABC):
 
         return cls._is_transient_error(response.content)
 
+    @classmethod
+    def is_arrearage_response(cls, response: LLMResponse) -> bool:
+        """Detect API-key arrearage / quota / billing errors that won't clear on retry.
+
+        These surface as HTTP 402 or as billing semantic tokens (e.g.
+        ``insufficient_quota``, ``payment_required``); reuses the same token and
+        text markers the 429 retry policy treats as non-retryable.
+        """
+        if response.error_status_code is not None and int(response.error_status_code) == 402:
+            return True
+
+        type_token = cls._normalize_error_token(response.error_type)
+        code_token = cls._normalize_error_token(response.error_code)
+        if any(
+            token in cls._NON_RETRYABLE_429_ERROR_TOKENS
+            for token in (type_token, code_token)
+            if token is not None
+        ):
+            return True
+
+        content = (response.content or "").lower()
+        return any(marker in content for marker in cls._NON_RETRYABLE_429_TEXT_MARKERS)
+
     @staticmethod
     def _normalize_error_token(value: Any) -> str | None:
         if value is None:
@@ -557,11 +580,20 @@ class LLMProvider(ABC):
         if reasoning_effort is self._SENTINEL:
             reasoning_effort = self.generation.reasoning_effort
 
+        has_streamed_content = False
+
+        async def _tracking_delta(text: str) -> None:
+            nonlocal has_streamed_content
+            if text:
+                has_streamed_content = True
+            if on_content_delta:
+                await on_content_delta(text)
+
         kw: dict[str, Any] = dict(
             messages=messages, tools=tools, model=model,
             max_tokens=max_tokens, temperature=temperature,
             reasoning_effort=reasoning_effort, tool_choice=tool_choice,
-            on_content_delta=on_content_delta,
+            on_content_delta=_tracking_delta if on_content_delta is not None else None,
             on_thinking_delta=on_thinking_delta,
             on_tool_call_delta=on_tool_call_delta,
         )
@@ -571,6 +603,7 @@ class LLMProvider(ABC):
             messages,
             retry_mode=retry_mode,
             on_retry_wait=on_retry_wait,
+            should_retry_guard=lambda: not has_streamed_content,
         )
 
     async def chat_with_retry(
@@ -717,6 +750,7 @@ class LLMProvider(ABC):
         *,
         retry_mode: str,
         on_retry_wait: Callable[[str], Awaitable[None]] | None,
+        should_retry_guard: Callable[[], bool] | None = None,
     ) -> LLMResponse:
         attempt = 0
         delays = list(self._CHAT_RETRY_DELAYS)
@@ -730,6 +764,11 @@ class LLMProvider(ABC):
             if response.finish_reason != "error":
                 return response
             last_response = response
+            if should_retry_guard is not None and not should_retry_guard():
+                logger.warning(
+                    "LLM stream failed after content was emitted; skipping retry"
+                )
+                return response
             error_key = ((response.content or "").strip().lower() or None)
             if error_key and error_key == last_error_key:
                 identical_error_count += 1

nanobot/providers/factory.py

@@ -98,6 +98,7 @@ def _make_provider_core(
             extra_headers=p.extra_headers if p else None,
             spec=spec,
             extra_body=p.extra_body if p else None,
+            api_type=p.api_type if p and provider_name == "openai" else "auto",
         )
 
     provider.generation = resolved.to_generation_settings()
@@ -183,6 +184,7 @@ def provider_signature(
             config.get_api_base(fallback.model, preset=fallback),
             fp.extra_headers if fp else None,
             fp.extra_body if fp else None,
+            fp.api_type if fp else "auto",
             getattr(fp, "region", None) if fp else None,
             getattr(fp, "profile", None) if fp else None,
             fallback.max_tokens,
@@ -199,6 +201,7 @@ def provider_signature(
         config.get_api_base(resolved.model, preset=resolved),
         p.extra_headers if p else None,
         p.extra_body if p else None,
+        p.api_type if p else "auto",
         getattr(p, "region", None) if p else None,
         getattr(p, "profile", None) if p else None,
         resolved.max_tokens,

nanobot/providers/image_generation.py

@@ -1445,6 +1445,149 @@ def _stepfun_images_from_payload(payload: dict[str, Any]) -> list[str]:
     return images
 
 
+# ---------------------------------------------------------------------------
+# Zhipu (智谱) image generation
+# ---------------------------------------------------------------------------
+
+_ZHIPU_TIMEOUT_S = 300.0
+
+_ZHIPU_ASPECT_RATIO_SIZES = {
+    "1:1": "1280x1280",
+    "16:9": "1728x960",
+    "9:16": "960x1728",
+    "3:4": "1088x1472",
+    "4:3": "1472x1088",
+}
+
+
+class ZhipuImageGenerationClient(ImageGenerationProvider):
+    """Async client for Zhipu (智谱) image generation API.
+
+    Supports:
+    - Text-to-image via glm-image, cogview-4, cogview-3-flash, etc.
+    - Aspect ratio selection
+    - Watermark control
+    """
+
+    provider_name = "zhipu"
+    missing_key_message = "Zhipu API key is not configured. Set providers.zhipu.apiKey."
+    default_timeout = _ZHIPU_TIMEOUT_S
+
+    def _default_base_url(self) -> str:
+        return "https://open.bigmodel.cn/api/paas/v4"
+
+    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)
+
+        if reference_images:
+            raise ImageGenerationError(
+                "Zhipu image generation does not support reference images"
+            )
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            **self.extra_headers,
+        }
+
+        body: dict[str, Any] = {
+            "model": model,
+            "prompt": prompt,
+        }
+
+        size = _zhipu_size(aspect_ratio, image_size)
+        if size:
+            body["size"] = size
+
+        body.update(self.extra_body)
+
+        url = f"{self.api_base}/images/generations"
+
+        client = self._client or httpx.AsyncClient(timeout=self.timeout)
+        try:
+            return await self._generate_with_client(
+                client,
+                headers=headers,
+                body=body,
+                url=url,
+            )
+        finally:
+            if self._client is None:
+                await client.aclose()
+
+    async def _generate_with_client(
+        self,
+        client: httpx.AsyncClient,
+        *,
+        headers: dict[str, str],
+        body: dict[str, Any],
+        url: str,
+    ) -> GeneratedImageResponse:
+        try:
+            response = await self._http_post(url, headers=headers, body=body, client=client)
+        except httpx.TimeoutException as exc:
+            raise ImageGenerationError("Zhipu image generation timed out") from exc
+        except httpx.RequestError as exc:
+            raise ImageGenerationError(f"Zhipu image generation request failed: {exc}") from exc
+
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            detail = response.text[:500]
+            raise ImageGenerationError(f"Zhipu image generation failed: {detail}") from exc
+
+        payload = response.json()
+        images = await _zhipu_images_from_payload(client, payload)
+
+        self._require_images(images, payload)
+
+        return GeneratedImageResponse(images=images, content="", raw=payload)
+
+
+def _zhipu_size(
+    aspect_ratio: str | None,
+    image_size: str | None,
+) -> str:
+    """Resolve aspect ratio / image_size to Zhipu size string.
+
+    Zhipu glm-image model supports: 1280x1280 (default), 1568x1056,
+    1056x1568, 1472x1088, 1088x1472, 1728x960, 960x1728.
+    """
+    if image_size and "x" in image_size.lower():
+        return image_size
+    if aspect_ratio and aspect_ratio in _ZHIPU_ASPECT_RATIO_SIZES:
+        return _ZHIPU_ASPECT_RATIO_SIZES[aspect_ratio]
+    return "1280x1280"
+
+
+async def _zhipu_images_from_payload(
+    client: httpx.AsyncClient,
+    payload: dict[str, Any],
+) -> list[str]:
+    """Extract image data URLs from Zhipu API response.
+
+    Zhipu returns images as temporary URLs that expire after 30 days.
+    We download and re-encode as base64 data URLs.
+    """
+    images: list[str] = []
+    for item in payload.get("data") or []:
+        if not isinstance(item, dict):
+            continue
+        url = item.get("url")
+        if isinstance(url, str) and url:
+            images.append(await _download_image_data_url(client, url))
+    return images
+
+
 # ---------------------------------------------------------------------------
 # Provider registration
 # ---------------------------------------------------------------------------
@@ -1457,3 +1600,4 @@ register_image_gen_provider(MiniMaxImageGenerationClient)
 register_image_gen_provider(OpenAIImageGenerationClient)
 register_image_gen_provider(OpenRouterImageGenerationClient)
 register_image_gen_provider(StepFunImageGenerationClient)
+register_image_gen_provider(ZhipuImageGenerationClient)

nanobot/providers/openai_codex_provider.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import hashlib
 import json
+import os
 from collections.abc import Awaitable, Callable
 from typing import Any
 
@@ -14,7 +15,7 @@ from oauth_cli_kit import get_token as get_codex_token
 
 from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
 from nanobot.providers.openai_responses import (
-    consume_sse,
+    consume_sse_with_reasoning,
     convert_messages,
     convert_tools,
 )
@@ -40,6 +41,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_thinking_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()."""
@@ -61,32 +63,52 @@ class OpenAICodexProvider(LLMProvider):
             "tool_choice": tool_choice or "auto",
             "parallel_tool_calls": True,
         }
-        if reasoning_effort and reasoning_effort.lower() != "none":
-            body["reasoning"] = {"effort": reasoning_effort}
+        reasoning_options = _build_reasoning_options(reasoning_effort)
+        if reasoning_options:
+            body["reasoning"] = reasoning_options
         if tools:
             body["tools"] = convert_tools(tools)
 
         try:
             try:
-                content, tool_calls, finish_reason = await _request_codex(
+                content, tool_calls, finish_reason, reasoning_content = await _request_codex(
                     DEFAULT_CODEX_URL, headers, body, verify=True,
                     on_content_delta=on_content_delta,
+                    on_thinking_delta=on_thinking_delta,
                     on_tool_call_delta=on_tool_call_delta,
                 )
             except Exception as e:
                 if "CERTIFICATE_VERIFY_FAILED" not in str(e):
                     raise
                 logger.warning("SSL verification failed for Codex API; retrying with verify=False")
-                content, tool_calls, finish_reason = await _request_codex(
+                content, tool_calls, finish_reason, reasoning_content = await _request_codex(
                     DEFAULT_CODEX_URL, headers, body, verify=False,
                     on_content_delta=on_content_delta,
+                    on_thinking_delta=on_thinking_delta,
                     on_tool_call_delta=on_tool_call_delta,
                 )
-            return LLMResponse(content=content, tool_calls=tool_calls, finish_reason=finish_reason)
+            return LLMResponse(
+                content=content,
+                tool_calls=tool_calls,
+                finish_reason=finish_reason,
+                reasoning_content=reasoning_content,
+            )
         except Exception as e:
-            msg = f"Error calling Codex: {e}"
-            retry_after = getattr(e, "retry_after", None) or self._extract_retry_after(msg)
-            return LLMResponse(content=msg, finish_reason="error", retry_after=retry_after)
+            response = _codex_error_response(e)
+            exc_type = "CodexHTTPError" if isinstance(e, _CodexHTTPError) else type(e).__name__
+            logger.warning(
+                "Codex API request failed: type={} kind={} retryable={} status={} "
+                "error_type={} error_code={} retry_after={} summary={}",
+                exc_type,
+                response.error_kind,
+                response.error_should_retry,
+                response.error_status_code,
+                response.error_type,
+                response.error_code,
+                response.retry_after,
+                _codex_log_summary(exc_type, response),
+            )
+            return response
 
     async def chat(
         self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None = None,
@@ -105,7 +127,6 @@ class OpenAICodexProvider(LLMProvider):
         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,
@@ -113,6 +134,7 @@ class OpenAICodexProvider(LLMProvider):
             reasoning_effort,
             tool_choice,
             on_content_delta,
+            on_thinking_delta,
             on_tool_call_delta,
         )
 
@@ -126,6 +148,16 @@ def _strip_model_prefix(model: str) -> str:
     return model
 
 
+def _build_reasoning_options(reasoning_effort: str | None) -> dict[str, str] | None:
+    """Opt in to visible summaries without changing provider-default effort."""
+    if reasoning_effort and reasoning_effort.lower() == "none":
+        return {"effort": "none"}
+    options = {"summary": "auto"}
+    if reasoning_effort:
+        options["effort"] = reasoning_effort
+    return options
+
+
 def _build_headers(account_id: str, token: str) -> dict[str, str]:
     return {
         "Authorization": f"Bearer {token}",
@@ -139,9 +171,22 @@ def _build_headers(account_id: str, token: str) -> dict[str, str]:
 
 
 class _CodexHTTPError(RuntimeError):
-    def __init__(self, message: str, retry_after: float | None = None):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        retry_after: float | None = None,
+        error_type: str | None = None,
+        error_code: str | None = None,
+        should_retry: bool | None = None,
+    ):
         super().__init__(message)
+        self.status_code = status_code
         self.retry_after = retry_after
+        self.error_type = error_type
+        self.error_code = error_code
+        self.should_retry = should_retry
 
 
 async def _request_codex(
@@ -150,18 +195,31 @@ async def _request_codex(
     body: dict[str, Any],
     verify: bool,
     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,
-) -> tuple[str, list[ToolCallRequest], str]:
-    async with httpx.AsyncClient(timeout=60.0, verify=verify) as client:
+) -> tuple[str, list[ToolCallRequest], str, str | None]:
+    idle_timeout_s = int(os.environ.get("NANOBOT_STREAM_IDLE_TIMEOUT_S", "90"))
+    async with httpx.AsyncClient(timeout=idle_timeout_s, verify=verify) as client:
         async with client.stream("POST", url, headers=headers, json=body) as response:
             if response.status_code != 200:
                 text = await response.aread()
+                raw = text.decode("utf-8", "ignore")
                 retry_after = LLMProvider._extract_retry_after_from_headers(response.headers)
+                error_type, error_code = LLMProvider._extract_error_type_code(raw)
                 raise _CodexHTTPError(
-                    _friendly_error(response.status_code, text.decode("utf-8", "ignore")),
+                    _friendly_error(response.status_code, raw),
+                    status_code=response.status_code,
                     retry_after=retry_after,
+                    error_type=error_type,
+                    error_code=error_code,
+                    should_retry=_should_retry_status(response.status_code, error_type, error_code, raw),
                 )
-            return await consume_sse(response, on_content_delta, on_tool_call_delta)
+            return await consume_sse_with_reasoning(
+                response,
+                on_content_delta=on_content_delta,
+                on_tool_call_delta=on_tool_call_delta,
+                on_reasoning_delta=on_thinking_delta,
+            )
 
 
 def _prompt_cache_key(messages: list[dict[str, Any]]) -> str:
@@ -170,6 +228,94 @@ def _prompt_cache_key(messages: list[dict[str, Any]]) -> str:
 
 
 def _friendly_error(status_code: int, raw: str) -> str:
+    _ = raw
     if status_code == 429:
         return "ChatGPT usage quota exceeded or rate limit triggered. Please try again later."
-    return f"HTTP {status_code}: {raw}"
+    return f"HTTP {status_code}: Codex API request failed"
+
+
+def _codex_error_response(exc: Exception) -> LLMResponse:
+    """Convert Codex transport/API failures into actionable, retryable metadata."""
+    exc_type = "CodexHTTPError" if isinstance(exc, _CodexHTTPError) else type(exc).__name__
+    detail = str(exc).strip()
+
+    status_code = getattr(exc, "status_code", None)
+    error_kind: str | None = None
+    default_detail: str | None = None
+    should_retry: bool | None = getattr(exc, "should_retry", None)
+
+    if isinstance(exc, (httpx.TimeoutException, asyncio.TimeoutError)):
+        error_kind = "timeout"
+        default_detail = "timed out waiting for response"
+        should_retry = True if should_retry is None else should_retry
+    elif isinstance(exc, httpx.RemoteProtocolError):
+        error_kind = "connection"
+        default_detail = "network protocol error while reading response"
+        should_retry = True if should_retry is None else should_retry
+    elif isinstance(exc, (httpx.NetworkError, httpx.TransportError)):
+        error_kind = "connection"
+        default_detail = "network connection failed"
+        should_retry = True if should_retry is None else should_retry
+    elif isinstance(exc, _CodexHTTPError):
+        error_kind = "http"
+        default_detail = "HTTP request failed"
+
+    if status_code is not None and should_retry is None:
+        retry_content = None if int(status_code) == 429 and isinstance(exc, _CodexHTTPError) else detail
+        should_retry = _should_retry_status(
+            int(status_code),
+            getattr(exc, "error_type", None),
+            getattr(exc, "error_code", None),
+            retry_content,
+        )
+
+    detail = detail or default_detail or "unexpected error"
+    message = f"Error calling Codex ({exc_type}): {detail}"
+    retry_after = getattr(exc, "retry_after", None) or LLMProvider._extract_retry_after(message)
+    return LLMResponse(
+        content=message,
+        finish_reason="error",
+        retry_after=retry_after,
+        error_status_code=int(status_code) if status_code is not None else None,
+        error_kind=error_kind,
+        error_type=getattr(exc, "error_type", None),
+        error_code=getattr(exc, "error_code", None),
+        error_retry_after_s=retry_after,
+        error_should_retry=should_retry,
+    )
+
+
+def _codex_log_summary(exc_type: str, response: LLMResponse) -> str:
+    """Return a bounded diagnostic summary without request body or raw upstream payload."""
+    if response.error_status_code is not None:
+        parts = [f"HTTP {response.error_status_code}"]
+        if response.error_type:
+            parts.append(f"type={response.error_type}")
+        if response.error_code:
+            parts.append(f"code={response.error_code}")
+        return " ".join(parts)
+
+    kind = (response.error_kind or "").strip()
+    if kind:
+        return f"{exc_type} {kind}"
+
+    return exc_type
+
+
+def _should_retry_status(
+    status_code: int,
+    error_type: str | None,
+    error_code: str | None,
+    content: str | None,
+) -> bool:
+    if status_code == 429:
+        return LLMProvider._is_retryable_429_response(
+            LLMResponse(
+                content=content or "",
+                finish_reason="error",
+                error_status_code=status_code,
+                error_type=error_type,
+                error_code=error_code,
+            )
+        )
+    return status_code in LLMProvider._RETRYABLE_STATUS_CODES or status_code >= 500

nanobot/providers/openai_compat_provider.py

@@ -274,6 +274,47 @@ def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any
     return merged
 
 
+def _merge_unique_list(base: Any, override: Any) -> Any:
+    """Append list values while preserving order and removing duplicates."""
+    if not isinstance(base, list) or not isinstance(override, list):
+        return override
+    result: list[Any] = []
+    seen: set[str] = set()
+    for value in [*base, *override]:
+        try:
+            key = json.dumps(value, sort_keys=True, ensure_ascii=False)
+        except Exception:
+            key = repr(value)
+        if key in seen:
+            continue
+        seen.add(key)
+        result.append(value)
+    return result
+
+
+def _merge_responses_extra_body(
+    body: dict[str, Any],
+    extra_body: dict[str, Any],
+) -> dict[str, Any]:
+    """Merge configured Responses API body fields without clobbering tools."""
+    reserved = {"include", "tools"}
+    regular_extra = {key: value for key, value in extra_body.items() if key not in reserved}
+    merged = _deep_merge(body, regular_extra)
+
+    if "include" in extra_body:
+        merged["include"] = _merge_unique_list(body.get("include"), extra_body["include"])
+
+    if "tools" in extra_body:
+        current_tools = body.get("tools")
+        configured_tools = extra_body["tools"]
+        if isinstance(current_tools, list) and isinstance(configured_tools, list):
+            merged["tools"] = [*current_tools, *configured_tools]
+        else:
+            merged["tools"] = configured_tools
+
+    return merged
+
+
 class OpenAICompatProvider(LLMProvider):
     """Unified provider for all OpenAI-compatible APIs.
 
@@ -289,12 +330,14 @@ class OpenAICompatProvider(LLMProvider):
         extra_headers: dict[str, str] | None = None,
         spec: ProviderSpec | None = None,
         extra_body: dict[str, Any] | None = None,
+        api_type: str = "auto",
     ):
         super().__init__(api_key, api_base)
         self.default_model = default_model
         self.extra_headers = extra_headers or {}
         self._spec = spec
         self._extra_body = extra_body or {}
+        self._api_type = api_type if spec and spec.name == "openai" else "auto"
 
         if api_key and spec and spec.env_key:
             self._setup_env(api_key, api_base)
@@ -428,6 +471,10 @@ class OpenAICompatProvider(LLMProvider):
             return tool_call_id
         return hashlib.sha1(tool_call_id.encode()).hexdigest()[:9]
 
+    def _should_normalize_tool_call_ids(self) -> bool:
+        """Return True for providers that reject normal OpenAI tool call IDs."""
+        return bool(self._spec and self._spec.name == "mistral")
+
     @staticmethod
     def _normalize_tool_call_arguments(arguments: Any) -> str:
         """Force function.arguments into a valid JSON object string."""
@@ -466,10 +513,13 @@ class OpenAICompatProvider(LLMProvider):
         id_map: dict[str, str] = {}
         pending_tool_ids: dict[str, deque[str]] = {}
         force_string_content = bool(self._spec and self._spec.name == "deepseek")
+        normalize_tool_ids = self._should_normalize_tool_call_ids()
 
         def map_id(value: Any) -> Any:
             if not isinstance(value, str):
                 return value
+            if not normalize_tool_ids:
+                return value
             return id_map.setdefault(value, self._normalize_tool_call_id(value))
 
         def unique_tool_id(value: Any, used_ids: set[str], idx: int) -> str:
@@ -685,8 +735,14 @@ class OpenAICompatProvider(LLMProvider):
         reasoning_effort: str | None,
     ) -> bool:
         """Use Responses API only for direct OpenAI requests that benefit from it."""
+        if self._api_type == "chat_completions":
+            return False
         if self._spec and self._spec.name not in ("openai", "github_copilot"):
             return False
+        if self._api_type == "responses":
+            # Explicit configuration means Responses is mandatory; do not
+            # consult the circuit breaker or fall back to Chat Completions.
+            return True
         if self._spec is None or self._spec.name != "github_copilot":
             if not _is_direct_openai_base(self._effective_base):
                 return False
@@ -700,7 +756,14 @@ class OpenAICompatProvider(LLMProvider):
         if not wants:
             return False
 
-        # Circuit breaker: skip after repeated failures, probe periodically.
+        return self._responses_circuit_allows_probe(model, reasoning_effort)
+
+    def _responses_circuit_allows_probe(
+        self,
+        model: str | None,
+        reasoning_effort: str | None,
+    ) -> bool:
+        """Return False when the Responses API circuit breaker is open."""
         key = _responses_circuit_key(model, self.default_model, reasoning_effort)
         failures = self._responses_failures.get(key, 0)
         if failures >= _RESPONSES_FAILURE_THRESHOLD:
@@ -792,6 +855,10 @@ class OpenAICompatProvider(LLMProvider):
             body["tools"] = convert_tools(tools)
             body["tool_choice"] = tool_choice or "auto"
 
+        extra_body = getattr(self, "_extra_body", {})
+        if extra_body:
+            body = _merge_responses_extra_body(body, extra_body)
+
         return body
 
     # ------------------------------------------------------------------
@@ -956,7 +1023,7 @@ class OpenAICompatProvider(LLMProvider):
                     args = json_repair.loads(args)
                 ec, prov, fn_prov = _extract_tc_extras(tc)
                 parsed_tool_calls.append(ToolCallRequest(
-                    id=_short_tool_id(),
+                    id=str(tc_map.get("id") or _short_tool_id()),
                     name=str(fn.get("name") or ""),
                     arguments=args if isinstance(args, dict) else {},
                     extra_content=ec,
@@ -999,7 +1066,7 @@ class OpenAICompatProvider(LLMProvider):
                 args = json_repair.loads(args)
             ec, prov, fn_prov = _extract_tc_extras(tc)
             tool_calls.append(ToolCallRequest(
-                id=_short_tool_id(),
+                id=str(getattr(tc, "id", None) or _short_tool_id()),
                 name=tc.function.name,
                 arguments=args,
                 extra_content=ec,
@@ -1262,6 +1329,8 @@ class OpenAICompatProvider(LLMProvider):
                         # falling back to /chat/completions cannot succeed and would
                         # hide the real error.
                         raise
+                    if self._api_type == "responses":
+                        raise
                     if not self._should_fallback_from_responses_error(responses_error):
                         raise
                     self._record_responses_failure(model, reasoning_effort)
@@ -1335,6 +1404,8 @@ class OpenAICompatProvider(LLMProvider):
                         # falling back to /chat/completions cannot succeed and would
                         # hide the real error.
                         raise
+                    if self._api_type == "responses":
+                        raise
                     if not self._should_fallback_from_responses_error(responses_error):
                         raise
                     self._record_responses_failure(model, reasoning_effort)

nanobot/providers/openai_responses/__init__.py

@@ -10,6 +10,7 @@ from nanobot.providers.openai_responses.parsing import (
     FINISH_REASON_MAP,
     consume_sdk_stream,
     consume_sse,
+    consume_sse_with_reasoning,
     iter_sse,
     map_finish_reason,
     parse_response_output,
@@ -22,6 +23,7 @@ __all__ = [
     "split_tool_call_id",
     "iter_sse",
     "consume_sse",
+    "consume_sse_with_reasoning",
     "consume_sdk_stream",
     "map_finish_reason",
     "parse_response_output",

nanobot/providers/openai_responses/parsing.py

@@ -65,10 +65,28 @@ async def consume_sse(
     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, tool_calls, finish_reason, _ = await consume_sse_with_reasoning(
+        response,
+        on_content_delta=on_content_delta,
+        on_tool_call_delta=on_tool_call_delta,
+    )
+    return content, tool_calls, finish_reason
+
+
+async def consume_sse_with_reasoning(
+    response: httpx.Response,
+    on_content_delta: Callable[[str], Awaitable[None]] | None = None,
+    on_tool_call_delta: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+    on_reasoning_delta: Callable[[str], Awaitable[None]] | None = None,
+) -> tuple[str, list[ToolCallRequest], str, str | None]:
+    """Consume a Responses API SSE stream, including visible reasoning summaries."""
     content = ""
     tool_calls: list[ToolCallRequest] = []
     tool_call_buffers: dict[str, dict[str, Any]] = {}
+    tool_call_args_emitted: set[str] = set()
     finish_reason = "stop"
+    reasoning_content: str | None = None
+    streamed_reasoning = False
 
     async for event in iter_sse(response):
         event_type = event.get("type")
@@ -94,6 +112,26 @@ async def consume_sse(
             content += delta_text
             if on_content_delta and delta_text:
                 await on_content_delta(delta_text)
+        elif event_type == "response.reasoning_summary_text.delta":
+            delta_text = event.get("delta") or ""
+            if delta_text:
+                reasoning_content = (reasoning_content or "") + delta_text
+                streamed_reasoning = True
+                if on_reasoning_delta:
+                    await on_reasoning_delta(delta_text)
+        elif event_type == "response.reasoning_summary_text.done":
+            text = event.get("text") or ""
+            if text and not streamed_reasoning and not reasoning_content:
+                reasoning_content = text
+                if on_reasoning_delta:
+                    await on_reasoning_delta(text)
+        elif event_type == "response.reasoning_summary_part.done":
+            part = event.get("part") or {}
+            text = part.get("text") if part.get("type") == "summary_text" else None
+            if text and not streamed_reasoning and not reasoning_content:
+                reasoning_content = text
+                if on_reasoning_delta:
+                    await on_reasoning_delta(text)
         elif event_type == "response.function_call_arguments.delta":
             call_id = event.get("call_id")
             if call_id and call_id in tool_call_buffers:
@@ -108,7 +146,15 @@ async def consume_sse(
         elif event_type == "response.function_call_arguments.done":
             call_id = event.get("call_id")
             if call_id and call_id in tool_call_buffers:
-                tool_call_buffers[call_id]["arguments"] = event.get("arguments") or ""
+                arguments = event.get("arguments") or ""
+                tool_call_buffers[call_id]["arguments"] = arguments
+                if on_tool_call_delta:
+                    tool_call_args_emitted.add(str(call_id))
+                    await on_tool_call_delta({
+                        "call_id": str(call_id),
+                        "name": str(tool_call_buffers[call_id].get("name") or ""),
+                        "arguments": str(arguments),
+                    })
         elif event_type == "response.output_item.done":
             item = event.get("item") or {}
             if item.get("type") == "function_call":
@@ -117,6 +163,13 @@ async def consume_sse(
                     continue
                 buf = tool_call_buffers.get(call_id) or {}
                 args_raw = buf.get("arguments") or item.get("arguments") or "{}"
+                if on_tool_call_delta and str(call_id) not in tool_call_args_emitted:
+                    tool_call_args_emitted.add(str(call_id))
+                    await on_tool_call_delta({
+                        "call_id": str(call_id),
+                        "name": str(buf.get("name") or item.get("name") or ""),
+                        "arguments": str(args_raw),
+                    })
                 try:
                     args = json.loads(args_raw)
                 except Exception:
@@ -135,14 +188,44 @@ async def consume_sse(
                         arguments=args,
                     )
                 )
+            elif item.get("type") == "reasoning" and not reasoning_content:
+                summary = _extract_reasoning_summary_from_output([item])
+                if summary:
+                    reasoning_content = summary
+                    if on_reasoning_delta:
+                        await on_reasoning_delta(summary)
         elif event_type == "response.completed":
-            status = (event.get("response") or {}).get("status")
+            response_obj = event.get("response") or {}
+            status = response_obj.get("status")
             finish_reason = map_finish_reason(status)
+            if not reasoning_content:
+                summary = _extract_reasoning_summary_from_output(response_obj.get("output") or [])
+                if summary:
+                    reasoning_content = summary
+                    if on_reasoning_delta:
+                        await on_reasoning_delta(summary)
         elif event_type in {"error", "response.failed"}:
             detail = event.get("error") or event.get("message") or event
             raise RuntimeError(f"Response failed: {str(detail)[:500]}")
 
-    return content, tool_calls, finish_reason
+    return content, tool_calls, finish_reason, reasoning_content
+
+
+def _extract_reasoning_summary_from_output(output: Any) -> str | None:
+    parts: list[str] = []
+    for item in output or []:
+        if not isinstance(item, dict):
+            dump = getattr(item, "model_dump", None)
+            item = dump() if callable(dump) else vars(item)
+        if item.get("type") != "reasoning":
+            continue
+        for summary in item.get("summary") or []:
+            if not isinstance(summary, dict):
+                dump = getattr(summary, "model_dump", None)
+                summary = dump() if callable(dump) else vars(summary)
+            if summary.get("type") == "summary_text" and summary.get("text"):
+                parts.append(summary["text"])
+    return "".join(parts) or None
 
 
 def parse_response_output(response: Any) -> LLMResponse:
@@ -230,6 +313,7 @@ async def consume_sdk_stream(
     content = ""
     tool_calls: list[ToolCallRequest] = []
     tool_call_buffers: dict[str, dict[str, Any]] = {}
+    tool_call_args_emitted: set[str] = set()
     finish_reason = "stop"
     usage: dict[str, int] = {}
     reasoning_content: str | None = None
@@ -272,7 +356,15 @@ async def consume_sdk_stream(
         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:
-                tool_call_buffers[call_id]["arguments"] = getattr(event, "arguments", "") or ""
+                arguments = getattr(event, "arguments", "") or ""
+                tool_call_buffers[call_id]["arguments"] = arguments
+                if on_tool_call_delta:
+                    tool_call_args_emitted.add(str(call_id))
+                    await on_tool_call_delta({
+                        "call_id": str(call_id),
+                        "name": str(tool_call_buffers[call_id].get("name") or ""),
+                        "arguments": str(arguments),
+                    })
         elif event_type == "response.output_item.done":
             item = getattr(event, "item", None)
             if item and getattr(item, "type", None) == "function_call":
@@ -281,6 +373,13 @@ async def consume_sdk_stream(
                     continue
                 buf = tool_call_buffers.get(call_id) or {}
                 args_raw = buf.get("arguments") or getattr(item, "arguments", None) or "{}"
+                if on_tool_call_delta and str(call_id) not in tool_call_args_emitted:
+                    tool_call_args_emitted.add(str(call_id))
+                    await on_tool_call_delta({
+                        "call_id": str(call_id),
+                        "name": str(buf.get("name") or getattr(item, "name", None) or ""),
+                        "arguments": str(args_raw),
+                    })
                 try:
                     args = json.loads(args_raw)
                 except Exception:

nanobot/providers/transcription.py

@@ -7,6 +7,25 @@ from pathlib import Path
 import httpx
 from loguru import logger
 
+_TRANSCRIPTIONS_PATH = "audio/transcriptions"
+
+
+def _resolve_transcription_url(api_base: str | None, default_url: str) -> str:
+    """Resolve the full transcription endpoint URL.
+
+    Accepts either a chat-style base (e.g. ``https://api.groq.com/openai/v1``)
+    or a complete URL already ending in ``/audio/transcriptions``. A chat-style
+    base — the form users naturally copy from their LLM provider config — gets
+    the path appended instead of being POSTed verbatim and 404ing (#3637).
+    """
+    if not api_base:
+        return default_url
+    base = api_base.rstrip("/")
+    if base.endswith(_TRANSCRIPTIONS_PATH):
+        return base
+    return f"{base}/{_TRANSCRIPTIONS_PATH}"
+
+
 # Up to 3 retries (4 attempts total) with exponential backoff on transient
 # failures. Whisper endpoints occasionally return 502/503 under load, and
 # mobile-network transcription callers hit sporadic connect/read errors.
@@ -127,12 +146,12 @@ class OpenAITranscriptionProvider:
         language: str | None = None,
     ):
         self.api_key = api_key or os.environ.get("OPENAI_API_KEY")
-        self.api_url = (
-            api_base
-            or os.environ.get("OPENAI_TRANSCRIPTION_BASE_URL")
-            or "https://api.openai.com/v1/audio/transcriptions"
+        self.api_url = _resolve_transcription_url(
+            api_base or os.environ.get("OPENAI_TRANSCRIPTION_BASE_URL"),
+            "https://api.openai.com/v1/audio/transcriptions",
         )
         self.language = language or None
+        logger.debug("OpenAI transcription endpoint: {}", self.api_url)
 
     async def transcribe(self, file_path: str | Path) -> str:
         if not self.api_key:
@@ -166,12 +185,12 @@ class GroqTranscriptionProvider:
         language: str | None = None,
     ):
         self.api_key = api_key or os.environ.get("GROQ_API_KEY")
-        self.api_url = (
-            api_base
-            or os.environ.get("GROQ_BASE_URL")
-            or "https://api.groq.com/openai/v1/audio/transcriptions"
+        self.api_url = _resolve_transcription_url(
+            api_base or os.environ.get("GROQ_BASE_URL"),
+            "https://api.groq.com/openai/v1/audio/transcriptions",
         )
         self.language = language or None
+        logger.debug("Groq transcription endpoint: {}", self.api_url)
 
     async def transcribe(self, file_path: str | Path) -> str:
         """

nanobot/security/network.py

@@ -36,15 +36,36 @@ def configure_ssrf_whitelist(cidrs: list[str]) -> None:
     _allowed_networks = nets
 
 
+def _normalize_addr(
+    addr: ipaddress.IPv4Address | ipaddress.IPv6Address,
+) -> ipaddress.IPv4Address | ipaddress.IPv6Address:
+    """Normalize IPv6-mapped IPv4 addresses to their IPv4 form.
+
+    ``::ffff:127.0.0.1`` is semantically identical to ``127.0.0.1`` but
+    Python's ipaddress treats it as an IPv6Address that matches neither
+    ``127.0.0.0/8`` nor ``::1/128``.  Converting it to IPv4 ensures
+    blocklist/allowlist checks work correctly.
+    """
+    if isinstance(addr, ipaddress.IPv6Address) and addr.ipv4_mapped is not None:
+        return addr.ipv4_mapped
+    return addr
+
+
 def _is_private(addr: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
-    if _allowed_networks and any(addr in net for net in _allowed_networks):
+    normalized = _normalize_addr(addr)
+    if _allowed_networks and any(normalized in net for net in _allowed_networks):
         return False
-    return any(addr in net for net in _BLOCKED_NETWORKS)
+    return any(normalized in net for net in _BLOCKED_NETWORKS)
 
 
-def validate_url_target(url: str) -> tuple[bool, str]:
+def validate_url_target(url: str, *, allow_loopback: bool = False) -> tuple[bool, str]:
     """Validate a URL is safe to fetch: scheme, hostname, and resolved IPs.
 
+    ``allow_loopback`` is intentionally narrow: it only permits literal
+    loopback hosts (localhost, 127.0.0.0/8, ::1) when every resolved address is
+    loopback. It does not allow RFC1918, link-local, metadata, or public DNS
+    names that happen to resolve to loopback.
+
     Returns (ok, error_message).  When ok is True, error_message is empty.
     """
     try:
@@ -66,11 +87,16 @@ def validate_url_target(url: str) -> tuple[bool, str]:
     except socket.gaierror:
         return False, f"Cannot resolve hostname: {hostname}"
 
+    addrs: list[ipaddress.IPv4Address | ipaddress.IPv6Address] = []
     for info in infos:
         try:
             addr = ipaddress.ip_address(info[4][0])
         except ValueError:
             continue
+        addrs.append(addr)
+    if allow_loopback and _is_allowed_loopback_target(hostname, addrs):
+        return True, ""
+    for addr in addrs:
         if _is_private(addr):
             return False, f"Blocked: {hostname} resolves to private/internal address {addr}"
 
@@ -109,11 +135,25 @@ def validate_resolved_url(url: str) -> tuple[bool, str]:
     return True, ""
 
 
-def contains_internal_url(command: str) -> bool:
+def contains_internal_url(command: str, *, allow_loopback: bool = False) -> bool:
     """Return True if the command string contains a URL targeting an internal/private address."""
     for m in _URL_RE.finditer(command):
         url = m.group(0)
-        ok, _ = validate_url_target(url)
+        ok, _ = validate_url_target(url, allow_loopback=allow_loopback)
         if not ok:
             return True
     return False
+
+
+def _is_allowed_loopback_target(
+    hostname: str,
+    addrs: list[ipaddress.IPv4Address | ipaddress.IPv6Address],
+) -> bool:
+    if not addrs or not all(_normalize_addr(addr).is_loopback for addr in addrs):
+        return False
+    normalized = hostname.rstrip(".").lower()
+    if normalized == "localhost":
+        return True
+    with suppress(ValueError):
+        return ipaddress.ip_address(hostname).is_loopback
+    return False

nanobot/security/workspace_access.py

@@ -0,0 +1,430 @@
+"""Workspace access scope and sandbox capability helpers."""
+
+from __future__ import annotations
+
+import os
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+WorkspaceAccessMode = Literal["restricted", "full"]
+WORKSPACE_SCOPE_METADATA_KEY = "workspace_scope"
+_ACCESS_MODES = {"restricted", "full"}
+
+_TRUE_VALUES = {"1", "true", "yes", "on", "enabled"}
+_FALSE_VALUES = {"0", "false", "no", "off", "disabled", ""}
+_PROVIDER_LABELS = {
+    "none": "None",
+    "unknown": "Unknown system sandbox",
+    "macos_app_sandbox": "macOS App Sandbox",
+    "bwrap": "Bubblewrap",
+}
+
+_CURRENT_WORKSPACE_SCOPE: ContextVar["WorkspaceScope | None"] = ContextVar(
+    "nanobot_workspace_scope",
+    default=None,
+)
+
+
+class WorkspaceScopeError(ValueError):
+    """Raised when a requested WebUI workspace scope is invalid."""
+
+    status = 400
+
+    def __init__(self, message: str, *, status: int = 400) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+@dataclass(frozen=True)
+class WorkspaceSandboxStatus:
+    """Resolved workspace sandbox state for runtime display and tooling."""
+
+    restrict_to_workspace: bool
+    workspace_root: str
+    level: str
+    enforced: bool
+    provider: str
+    provider_label: str
+    summary: str
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "restrict_to_workspace": self.restrict_to_workspace,
+            "workspace_root": self.workspace_root,
+            "level": self.level,
+            "enforced": self.enforced,
+            "provider": self.provider,
+            "provider_label": self.provider_label,
+            "summary": self.summary,
+        }
+
+
+@dataclass(frozen=True)
+class WorkspaceScope:
+    """Effective project root and access mode for one agent turn."""
+
+    project_path: Path
+    access_mode: WorkspaceAccessMode
+    restrict_to_workspace: bool
+    sandbox_status: WorkspaceSandboxStatus
+    source_channel: str | None = None
+
+    @property
+    def project_name(self) -> str:
+        return self.project_path.name or str(self.project_path)
+
+    def metadata(self) -> dict[str, str]:
+        return {
+            "project_path": str(self.project_path),
+            "access_mode": self.access_mode,
+        }
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            **self.metadata(),
+            "project_name": self.project_name,
+            "restrict_to_workspace": self.restrict_to_workspace,
+            "sandbox_status": self.sandbox_status.as_dict(),
+        }
+
+
+@dataclass(frozen=True)
+class ToolWorkspace:
+    """Workspace policy resolved for a tool call."""
+
+    project_path: Path | None
+    restrict_to_workspace: bool
+    scope: WorkspaceScope | None = None
+
+    @property
+    def allowed_root(self) -> Path | None:
+        if self.restrict_to_workspace and self.project_path is not None:
+            return self.project_path
+        return None
+
+
+@dataclass(frozen=True)
+class WorkspaceScopeResolver:
+    """Resolve the effective workspace scope at an agent turn boundary."""
+
+    default_workspace: str | Path
+    default_restrict_to_workspace: bool
+    scoped_channel: str = "websocket"
+
+    @property
+    def sandbox_status(self) -> WorkspaceSandboxStatus:
+        return self.default().sandbox_status
+
+    def default(self) -> WorkspaceScope:
+        return default_workspace_scope(
+            self.default_workspace,
+            self.default_restrict_to_workspace,
+        )
+
+    def for_message(
+        self,
+        msg: Any,
+        session_metadata: Any,
+    ) -> WorkspaceScope:
+        return self.for_turn(
+            channel=getattr(msg, "channel", None),
+            message_metadata=getattr(msg, "metadata", None),
+            session_metadata=session_metadata,
+        )
+
+    def for_turn(
+        self,
+        *,
+        channel: str | None,
+        message_metadata: Any,
+        session_metadata: Any,
+    ) -> WorkspaceScope:
+        if channel != self.scoped_channel:
+            return self.default()
+        return resolve_effective_workspace_scope(
+            message_metadata=message_metadata,
+            session_metadata=session_metadata,
+            default_workspace=self.default_workspace,
+            default_restrict_to_workspace=self.default_restrict_to_workspace,
+            source_channel=channel,
+        )
+
+    def persist_message_scope(self, session: Any, msg: Any) -> None:
+        if getattr(msg, "channel", None) != self.scoped_channel:
+            return
+        metadata = getattr(msg, "metadata", None)
+        if not isinstance(metadata, dict):
+            return
+        raw = metadata.get(WORKSPACE_SCOPE_METADATA_KEY)
+        if isinstance(raw, dict):
+            session.metadata[WORKSPACE_SCOPE_METADATA_KEY] = dict(raw)
+
+
+def workspace_sandbox_status(
+    *,
+    restrict_to_workspace: bool,
+    workspace: str | Path,
+    environ: dict[str, str] | None = None,
+) -> WorkspaceSandboxStatus:
+    """Return how workspace restriction is enforced in the current host."""
+
+    workspace_root = str(Path(workspace).expanduser().resolve(strict=False))
+    provider = _env_system_provider(environ)
+    if not restrict_to_workspace:
+        return WorkspaceSandboxStatus(
+            restrict_to_workspace=False,
+            workspace_root=workspace_root,
+            level="off",
+            enforced=False,
+            provider="none",
+            provider_label=_provider_label("none"),
+            summary="Workspace restriction is disabled.",
+        )
+
+    if provider:
+        label = _provider_label(provider)
+        return WorkspaceSandboxStatus(
+            restrict_to_workspace=True,
+            workspace_root=workspace_root,
+            level="system",
+            enforced=True,
+            provider=provider,
+            provider_label=label,
+            summary=f"Workspace restriction is system-enforced by {label}.",
+        )
+
+    return WorkspaceSandboxStatus(
+        restrict_to_workspace=True,
+        workspace_root=workspace_root,
+        level="application",
+        enforced=False,
+        provider="none",
+        provider_label=_provider_label("none"),
+        summary="Workspace restriction uses nanobot application-level guards.",
+    )
+
+
+def default_access_mode(restrict_to_workspace: bool) -> WorkspaceAccessMode:
+    return "restricted" if restrict_to_workspace else "full"
+
+
+def build_workspace_scope(
+    project_path: str | Path,
+    access_mode: str,
+    *,
+    source_channel: str | None = None,
+) -> WorkspaceScope:
+    mode = _normalize_access_mode(access_mode)
+    root = Path(project_path).expanduser().resolve(strict=False)
+    restrict = mode == "restricted"
+    return WorkspaceScope(
+        project_path=root,
+        access_mode=mode,
+        restrict_to_workspace=restrict,
+        sandbox_status=workspace_sandbox_status(
+            restrict_to_workspace=restrict,
+            workspace=root,
+        ),
+        source_channel=source_channel,
+    )
+
+
+def default_workspace_scope(
+    workspace: str | Path,
+    restrict_to_workspace: bool,
+    *,
+    source_channel: str | None = None,
+) -> WorkspaceScope:
+    return build_workspace_scope(
+        workspace,
+        default_access_mode(restrict_to_workspace),
+        source_channel=source_channel,
+    )
+
+
+def validate_workspace_scope_payload(
+    raw: Any,
+    *,
+    default_workspace: str | Path,
+    default_restrict_to_workspace: bool,
+    source_channel: str | None = None,
+) -> WorkspaceScope:
+    """Validate a client-requested workspace scope."""
+    if raw is None:
+        return default_workspace_scope(
+            default_workspace,
+            default_restrict_to_workspace,
+            source_channel=source_channel,
+        )
+    if not isinstance(raw, dict):
+        raise WorkspaceScopeError("workspace_scope must be an object")
+
+    raw_path = raw.get("project_path") or raw.get("path")
+    if raw_path is None or raw_path == "":
+        raw_path = str(Path(default_workspace).expanduser().resolve(strict=False))
+    if not isinstance(raw_path, str):
+        raise WorkspaceScopeError("project_path must be a string")
+    if "\0" in raw_path:
+        raise WorkspaceScopeError("project_path contains invalid characters")
+
+    project = Path(raw_path).expanduser()
+    if not project.is_absolute():
+        raise WorkspaceScopeError("project_path must be absolute")
+    project = project.resolve(strict=False)
+    if not project.is_dir():
+        raise WorkspaceScopeError("project_path must be an existing directory")
+
+    raw_mode = raw.get("access_mode")
+    if raw_mode is None:
+        raw_mode = default_access_mode(default_restrict_to_workspace)
+    if not isinstance(raw_mode, str):
+        raise WorkspaceScopeError("access_mode must be a string")
+    return build_workspace_scope(project, raw_mode, source_channel=source_channel)
+
+
+def workspace_scope_from_metadata(
+    metadata: Any,
+    *,
+    default_workspace: str | Path,
+    default_restrict_to_workspace: bool,
+    source_channel: str | None = None,
+) -> WorkspaceScope:
+    """Resolve persisted metadata, falling back safely for old or stale sessions."""
+    if not isinstance(metadata, dict):
+        return default_workspace_scope(
+            default_workspace,
+            default_restrict_to_workspace,
+            source_channel=source_channel,
+        )
+    try:
+        return validate_workspace_scope_payload(
+            metadata.get(WORKSPACE_SCOPE_METADATA_KEY),
+            default_workspace=default_workspace,
+            default_restrict_to_workspace=default_restrict_to_workspace,
+            source_channel=source_channel,
+        )
+    except WorkspaceScopeError:
+        return default_workspace_scope(
+            default_workspace,
+            default_restrict_to_workspace,
+            source_channel=source_channel,
+        )
+
+
+def resolve_effective_workspace_scope(
+    *,
+    message_metadata: Any,
+    session_metadata: Any,
+    default_workspace: str | Path,
+    default_restrict_to_workspace: bool,
+    source_channel: str | None = None,
+) -> WorkspaceScope:
+    if isinstance(message_metadata, dict) and WORKSPACE_SCOPE_METADATA_KEY in message_metadata:
+        return workspace_scope_from_metadata(
+            message_metadata,
+            default_workspace=default_workspace,
+            default_restrict_to_workspace=default_restrict_to_workspace,
+            source_channel=source_channel,
+        )
+    return workspace_scope_from_metadata(
+        session_metadata,
+        default_workspace=default_workspace,
+        default_restrict_to_workspace=default_restrict_to_workspace,
+        source_channel=source_channel,
+    )
+
+
+def bind_workspace_scope(scope: WorkspaceScope) -> Token[WorkspaceScope | None]:
+    return _CURRENT_WORKSPACE_SCOPE.set(scope)
+
+
+def reset_workspace_scope(token: Token[WorkspaceScope | None]) -> None:
+    _CURRENT_WORKSPACE_SCOPE.reset(token)
+
+
+def current_workspace_scope() -> WorkspaceScope | None:
+    return _CURRENT_WORKSPACE_SCOPE.get()
+
+
+def current_tool_workspace(
+    default_workspace: str | Path | None,
+    *,
+    restrict_to_workspace: bool = False,
+    sandbox_restricts_workspace: bool = False,
+) -> ToolWorkspace:
+    """Return the workspace/access policy for the current tool call."""
+
+    scope = current_workspace_scope()
+    project_path = (
+        scope.project_path
+        if scope is not None
+        else Path(default_workspace).expanduser() if default_workspace is not None else None
+    )
+    restrict = (
+        scope.restrict_to_workspace
+        if scope is not None
+        else bool(restrict_to_workspace)
+    ) or sandbox_restricts_workspace
+    return ToolWorkspace(
+        project_path=project_path,
+        restrict_to_workspace=restrict,
+        scope=scope,
+    )
+
+
+def current_scope_allows_loopback(*, enabled: bool) -> bool:
+    """Return True when the current WebUI Full Access turn may touch loopback URLs."""
+
+    scope = current_workspace_scope()
+    return bool(
+        enabled
+        and scope is not None
+        and scope.source_channel == "websocket"
+        and scope.access_mode == "full"
+        and not scope.restrict_to_workspace
+    )
+
+
+def _env_system_provider(environ: dict[str, str] | None = None) -> str | None:
+    env = environ if environ is not None else os.environ
+    explicit_provider = env.get("NANOBOT_WORKSPACE_SANDBOX_PROVIDER")
+    enforced = env.get("NANOBOT_WORKSPACE_SANDBOX_ENFORCED")
+    compatibility = env.get("NANOBOT_SANDBOX_ENFORCED")
+
+    marker = enforced if enforced is not None else compatibility
+    if marker is None:
+        return None
+
+    normalized_marker = marker.strip().lower()
+    if normalized_marker in _FALSE_VALUES:
+        return None
+    if normalized_marker in _TRUE_VALUES:
+        return _normalize_provider(explicit_provider)
+    return _normalize_provider(marker)
+
+
+def _normalize_provider(value: str | None) -> str:
+    if not value:
+        return "unknown"
+    normalized = value.strip().lower().replace("-", "_").replace(" ", "_")
+    return normalized or "unknown"
+
+
+def _provider_label(provider: str) -> str:
+    if provider in _PROVIDER_LABELS:
+        return _PROVIDER_LABELS[provider]
+    return provider.replace("_", " ").title()
+
+
+def _normalize_access_mode(value: str) -> WorkspaceAccessMode:
+    mode = value.strip().lower().replace("_", "-")
+    if mode == "restrict":
+        mode = "restricted"
+    if mode == "full-access":
+        mode = "full"
+    if mode not in _ACCESS_MODES:
+        raise WorkspaceScopeError("access_mode must be restricted or full")
+    return mode  # type: ignore[return-value]

nanobot/security/workspace_policy.py

@@ -0,0 +1,85 @@
+"""Workspace path boundary helpers.
+
+These helpers are application-level guards.  They make path decisions
+consistent across tools, but they are not a replacement for an OS sandbox.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+WORKSPACE_BOUNDARY_NOTE = (
+    " (this is a hard policy boundary, not a transient failure; "
+    "do not retry with shell tricks or alternative tools, and ask "
+    "the user how to proceed if the resource is genuinely required)"
+)
+
+
+class WorkspaceBoundaryError(PermissionError):
+    """Raised when a requested path escapes an allowed workspace boundary."""
+
+
+def resolve_path(path: str | Path, workspace: str | Path | None = None, *, strict: bool = False) -> Path:
+    """Resolve *path*, interpreting relative paths against *workspace* when set."""
+    candidate = Path(path).expanduser()
+    if not candidate.is_absolute() and workspace is not None:
+        candidate = Path(workspace).expanduser() / candidate
+    return candidate.resolve(strict=strict)
+
+
+def is_path_within(path: str | Path, root: str | Path) -> bool:
+    """Return True when *path* resolves to *root* or a descendant of *root*."""
+    try:
+        resolved_path = Path(path).expanduser().resolve(strict=False)
+        resolved_root = Path(root).expanduser().resolve(strict=False)
+        resolved_path.relative_to(resolved_root)
+        return True
+    except (OSError, RuntimeError, TypeError, ValueError):
+        return False
+
+
+def is_path_allowed(path: str | Path, roots: Iterable[str | Path]) -> bool:
+    """Return True when *path* is inside any allowed root."""
+    return any(is_path_within(path, root) for root in roots)
+
+
+def require_path_within(
+    path: str | Path,
+    root: str | Path,
+    *,
+    message: str | None = None,
+) -> Path:
+    """Resolve *path* and require it to be inside *root*."""
+    resolved = Path(path).expanduser().resolve(strict=False)
+    if not is_path_within(resolved, root):
+        raise WorkspaceBoundaryError(
+            message
+            or f"Path {path} is outside allowed directory {Path(root).expanduser()}"
+            + WORKSPACE_BOUNDARY_NOTE
+        )
+    return resolved
+
+
+def resolve_allowed_path(
+    path: str | Path,
+    *,
+    workspace: str | Path | None = None,
+    allowed_root: str | Path | None = None,
+    extra_allowed_roots: Iterable[str | Path] | None = None,
+    strict: bool = False,
+) -> Path:
+    """Resolve a path and enforce containment in allowed roots when configured."""
+    resolved = resolve_path(path, workspace, strict=False)
+    if allowed_root is None:
+        return resolve_path(path, workspace, strict=strict) if strict else resolved
+
+    roots = [allowed_root, *(extra_allowed_roots or [])]
+    if not is_path_allowed(resolved, roots):
+        raise WorkspaceBoundaryError(
+            f"Path {path} is outside allowed directory {Path(allowed_root).expanduser()}"
+            + WORKSPACE_BOUNDARY_NOTE
+        )
+    if strict:
+        return resolve_path(path, workspace, strict=True)
+    return resolved

nanobot/session/manager.py

@@ -19,6 +19,7 @@ from nanobot.utils.helpers import (
     find_legal_message_start,
     image_placeholder_text,
     safe_filename,
+    strip_think,
 )
 from nanobot.utils.subagent_channel_display import scrub_subagent_announce_body
 
@@ -27,6 +28,8 @@ _MESSAGE_TIME_PREFIX_RE = re.compile(r"^\[Message Time: [^\]]+\]\n?")
 _LOCAL_IMAGE_BREADCRUMB_RE = re.compile(r"^\[image: (?:/|~)[^\]]+\]\s*$")
 _TOOL_CALL_ECHO_RE = re.compile(r'^\s*(?:generate_image|message)\([^)]*\)\s*$')
 _SESSION_PREVIEW_MAX_CHARS = 120
+_SESSION_LIST_PREVIEW_MAX_RECORDS = 200
+_SESSION_LIST_PREVIEW_MAX_CHARS = 1_000_000
 
 
 def _sanitize_assistant_replay_text(content: str) -> str:
@@ -74,6 +77,17 @@ def _message_preview_text(message: dict[str, Any]) -> str:
     return _text_preview(content)
 
 
+def _metadata_title(metadata: Any) -> str:
+    if not isinstance(metadata, dict):
+        return ""
+    title = metadata.get("title")
+    if not isinstance(title, str):
+        return ""
+    if metadata.get("title_user_edited") is True:
+        return title
+    return strip_think(title)
+
+
 @dataclass
 class Session:
     """A conversation session."""
@@ -182,6 +196,28 @@ class Session:
                 if cli_lines:
                     breadcrumbs = "\n".join(cli_lines)
                     content = f"{content}\n{breadcrumbs}" if content else breadcrumbs
+            mcp_presets = message.get("mcp_presets")
+            if (
+                role == "user"
+                and isinstance(mcp_presets, list)
+                and mcp_presets
+                and isinstance(content, str)
+            ):
+                mcp_lines: list[str] = []
+                for item in mcp_presets[:8]:
+                    if not isinstance(item, dict):
+                        continue
+                    name = str(item.get("name") or "").strip().lower()
+                    if not name:
+                        continue
+                    transport = str(item.get("transport") or "mcp").strip() or "mcp"
+                    mcp_lines.append(
+                        f"[MCP Preset Attachment: @{name}; tool_prefix=mcp_{name}_; "
+                        f"transport={transport}]"
+                    )
+                if mcp_lines:
+                    breadcrumbs = "\n".join(mcp_lines)
+                    content = f"{content}\n{breadcrumbs}" if content else breadcrumbs
             if include_timestamps:
                 content = self._annotate_message_time(message, content)
             if role == "assistant" and isinstance(content, str) and not content.strip():
@@ -618,12 +654,21 @@ class SessionManager:
                         if data.get("_type") == "metadata":
                             key = data.get("key") or path.stem.replace("_", ":", 1)
                             metadata = data.get("metadata", {})
-                            title = metadata.get("title") if isinstance(metadata, dict) else None
+                            title = _metadata_title(metadata)
                             preview = ""
                             fallback_preview = ""
+                            scanned_records = 0
+                            scanned_chars = 0
                             for line in f:
                                 if not line.strip():
                                     continue
+                                scanned_records += 1
+                                scanned_chars += len(line)
+                                if (
+                                    scanned_records > _SESSION_LIST_PREVIEW_MAX_RECORDS
+                                    or scanned_chars > _SESSION_LIST_PREVIEW_MAX_CHARS
+                                ):
+                                    break
                                 item = json.loads(line)
                                 if item.get("_type") == "metadata":
                                     continue
@@ -640,7 +685,7 @@ class SessionManager:
                                 "key": key,
                                 "created_at": data.get("created_at"),
                                 "updated_at": data.get("updated_at"),
-                                "title": title if isinstance(title, str) else "",
+                                "title": title,
                                 "preview": preview,
                                 "path": str(path)
                             })
@@ -651,11 +696,7 @@ class SessionManager:
                         "key": repaired.key,
                         "created_at": repaired.created_at.isoformat(),
                         "updated_at": repaired.updated_at.isoformat(),
-                        "title": (
-                            repaired.metadata.get("title")
-                            if isinstance(repaired.metadata.get("title"), str)
-                            else ""
-                        ),
+                        "title": _metadata_title(repaired.metadata),
                         "preview": next(
                             (
                                 text

nanobot/session/webui_turns.py

@@ -19,7 +19,7 @@ from nanobot.bus.queue import MessageBus
 from nanobot.providers.base import LLMProvider
 from nanobot.session.goal_state import goal_state_ws_blob
 from nanobot.session.manager import Session, SessionManager
-from nanobot.utils.helpers import truncate_text
+from nanobot.utils.helpers import strip_think, truncate_text
 from nanobot.utils.llm_runtime import LLMRuntime
 
 WEBUI_SESSION_METADATA_KEY = "webui"
@@ -48,6 +48,7 @@ def clean_generated_title(raw: str | None) -> str:
         return ""
     text = re.sub(r"^\s*(title|标题)\s*[:：]\s*", "", text, flags=re.IGNORECASE)
     text = text.strip().strip("\"'`“”‘’")
+    text = strip_think(text)
     text = re.sub(r"\s+", " ", text).strip()
     text = text.rstrip("。.!！?？,，;；:")
     if len(text) > TITLE_MAX_CHARS:
@@ -65,6 +66,9 @@ def _title_inputs(session: Session) -> tuple[str, str]:
         content = message.get("content")
         if not isinstance(content, str) or not content.strip():
             continue
+        content = strip_think(content)
+        if not content:
+            continue
         if role == "user" and not user_text:
             user_text = content.strip()
         elif role == "assistant" and not assistant_text:
@@ -89,7 +93,13 @@ async def maybe_generate_webui_title(
         return False
     current_title = session.metadata.get(WEBUI_TITLE_METADATA_KEY)
     if isinstance(current_title, str) and current_title.strip():
-        return False
+        cleaned_current_title = clean_generated_title(current_title)
+        if cleaned_current_title:
+            if cleaned_current_title != current_title:
+                session.metadata[WEBUI_TITLE_METADATA_KEY] = cleaned_current_title
+                sessions.save(session)
+            return False
+        session.metadata.pop(WEBUI_TITLE_METADATA_KEY, None)
 
     user_text, assistant_text = _title_inputs(session)
     if not user_text:

nanobot/templates/AGENTS.md

@@ -14,10 +14,10 @@ Get USER_ID and CHANNEL from the current session (e.g., `8281248569` and `telegr
 
 ## Heartbeat Tasks
 
-`HEARTBEAT.md` is checked on the configured heartbeat interval. Use file tools to manage periodic tasks.
+`HEARTBEAT.md` is checked periodically when registered as a cron job. Use the built-in `cron` tool to schedule it (e.g. `cron add --name heartbeat --schedule "every 30m" --message "Check HEARTBEAT.md"`).
 
 - Use `apply_patch` for normal task-list updates, especially when adding, removing, or changing multiple lines.
 - Use `edit_file` only for small exact replacements copied from the current `HEARTBEAT.md`.
 - Use `write_file` for first creation or intentional full-file rewrites.
 
-When the user asks for a recurring/periodic task, update `HEARTBEAT.md` instead of creating a one-time cron reminder.
+When the user asks for a recurring/periodic task, update `HEARTBEAT.md` and register it via `cron` instead of creating a one-time reminder.

nanobot/templates/HEARTBEAT.md

@@ -1,9 +1,9 @@
 # Heartbeat Tasks
 
-This file is checked every 30 minutes by your nanobot agent.
-Add tasks below that you want the agent to work on periodically.
+This file is checked periodically by your nanobot agent.
+Register it as a cron job (e.g. `cron add --name heartbeat --schedule "every 30m" --message "Check HEARTBEAT.md"`) to get the same behavior as the legacy heartbeat service.
 
-If this file has no tasks (only headers and comments), the agent will skip the heartbeat.
+If this file has no tasks (only headers and comments), the agent will skip it.
 
 ## Active Tasks
 

nanobot/templates/agent/tool_contract.md

@@ -63,5 +63,5 @@ documents the general tool contract and non-obvious usage patterns.
 ## Scheduling and Background Work
 
 - Use `cron` for scheduled reminders or recurring jobs; do not run `nanobot cron` through `exec`.
-- For heartbeat tasks, update `HEARTBEAT.md` according to the agent instructions.
+- For heartbeat tasks, register `HEARTBEAT.md` as a cron job according to the agent instructions.
 - Do not write reminders only to memory files when the user expects an actual notification.

nanobot/utils/document.py

@@ -7,7 +7,6 @@ from loguru import logger
 
 from nanobot.utils.helpers import detect_image_mime
 
-
 # Supported file extensions for text extraction
 SUPPORTED_EXTENSIONS: set[str] = {
     # Document formats
@@ -232,6 +231,46 @@ def _is_text_extension(ext: str) -> bool:
 _MAX_EXTRACT_FILE_SIZE = 50 * 1024 * 1024  # 50 MB
 
 
+def is_image_file(path: str) -> bool:
+    """Check whether *path* looks like an image file.
+
+    Uses magic-byte detection (reads first 16 bytes) with a ``mimetypes``
+    extension-based fallback.
+    """
+    p = Path(path)
+    mime: str | None = None
+    if p.is_file():
+        try:
+            with p.open("rb") as f:
+                mime = detect_image_mime(f.read(16))
+        except OSError:
+            mime = None
+    if not mime:
+        mime = mimetypes.guess_type(path)[0]
+    return bool(mime and mime.startswith("image/"))
+
+
+def reference_non_image_attachments(
+    content: str, media: list[str],
+) -> tuple[str, list[str]]:
+    """Separate images from non-image attachments without reading file content.
+
+    Image paths are preserved for downstream vision-block construction.
+    Non-image paths are appended as ``[Attachment: path]`` references.
+    """
+    image_paths: list[str] = []
+    attachment_refs: list[str] = []
+    for path in media:
+        if is_image_file(path):
+            image_paths.append(path)
+        else:
+            attachment_refs.append(f"[Attachment: {path}]")
+    if attachment_refs:
+        suffix = "\n".join(attachment_refs)
+        content = f"{content}\n\n{suffix}" if content else suffix
+    return content, image_paths
+
+
 def extract_documents(
     text: str,
     media_paths: list[str],
@@ -267,10 +306,7 @@ def extract_documents(
             )
             continue
 
-        with open(p, "rb") as f:
-            header = f.read(16)
-        mime = detect_image_mime(header) or mimetypes.guess_type(path_str)[0]
-        if mime and mime.startswith("image/"):
+        if is_image_file(path_str):
             image_paths.append(path_str)
         else:
             extracted = extract_text(p)

nanobot/utils/evaluator.py

@@ -44,12 +44,15 @@ async def evaluate_response(
     task_context: str,
     provider: LLMProvider,
     model: str,
+    *,
+    default_notify: bool = True,
 ) -> bool:
     """Decide whether a background-task result should be delivered to the user.
 
-    Uses a lightweight tool-call LLM request (same pattern as heartbeat
-    ``_decide()``).  Falls back to ``True`` (notify) on any failure so
-    that important messages are never silently dropped.
+    Uses a lightweight tool-call LLM request.  ``default_notify`` controls
+    the fallback path when the evaluator cannot produce a valid decision:
+    user-scheduled reminders stay fail-open, while internal checks such as
+    heartbeat can fail closed.
     """
     try:
         llm_response = await provider.chat_with_retry(
@@ -71,19 +74,23 @@ async def evaluate_response(
         if not llm_response.should_execute_tools:
             if llm_response.has_tool_calls:
                 logger.warning(
-                    "evaluate_response: ignoring tool calls under finish_reason='{}', defaulting to notify",
+                    "evaluate_response: ignoring tool calls under finish_reason='{}', defaulting to notify={}",
                     llm_response.finish_reason,
+                    default_notify,
                 )
             else:
-                logger.warning("evaluate_response: no tool call returned, defaulting to notify")
-            return True
+                logger.warning(
+                    "evaluate_response: no tool call returned, defaulting to notify={}",
+                    default_notify,
+                )
+            return default_notify
 
         args = llm_response.tool_calls[0].arguments
-        should_notify = args.get("should_notify", True)
+        should_notify = args.get("should_notify", default_notify)
         reason = args.get("reason", "")
         logger.info("evaluate_response: should_notify={}, reason={}", should_notify, reason)
         return bool(should_notify)
 
     except Exception:
-        logger.exception("evaluate_response failed, defaulting to notify")
-        return True
+        logger.exception("evaluate_response failed, defaulting to notify={}", default_notify)
+        return default_notify

nanobot/utils/file_edit_events.py

@@ -299,6 +299,7 @@ def build_file_edit_end_event(
         deleted=deleted,
         approximate=False,
         binary=(after.binary or after.oversized or after.unreadable) and not counted,
+        operation="delete" if tracker.before.exists and not after.exists else None,
     )
 
 
@@ -324,6 +325,7 @@ def build_file_edit_live_event(
     *,
     added: int,
     deleted: int = 0,
+    operation: str | None = None,
 ) -> dict[str, Any]:
     """Build an approximate in-progress event while tool-call arguments stream."""
     return _event_payload(
@@ -333,6 +335,7 @@ def build_file_edit_live_event(
         added=added,
         deleted=deleted,
         approximate=True,
+        operation=operation,
     )
 
 
@@ -454,15 +457,14 @@ class StreamingFileEditTracker:
             segment_end = path_matches[i + 1].start() if i + 1 < len(path_matches) else len(state.arguments)
             segment = state.arguments[segment_start:segment_end]
 
-            action_match = re.search(r'"action"\s*:\s*"(replace|add|delete)"', segment)
+            action_match = re.search(r'"action"\s*:\s*"(replace|add)"', segment)
             action = action_match.group(1) if action_match else "replace"
 
             old_text = _extract_json_string_prefix(segment, "old_text") or ""
             new_text = _extract_json_string_prefix(segment, "new_text") or ""
 
             added = _text_line_count(new_text) if action in ("replace", "add") else 0
-            deleted = _text_line_count(old_text) if action in ("replace", "delete") else 0
-            delete_file = action == "delete"
+            deleted = _text_line_count(old_text) if action == "replace" else 0
 
             file_state = state.patch_files.get(raw_path)
             if file_state is None:
@@ -475,8 +477,6 @@ class StreamingFileEditTracker:
                 )
                 file_state = _StreamingPatchFileState(tracker=tracker)
                 state.patch_files[raw_path] = file_state
-            if delete_file and added == 0 and deleted == 0 and file_state.tracker.before.countable:
-                deleted = _text_line_count(file_state.tracker.before.text or "")
             if not file_state.should_emit(added, deleted, now):
                 continue
             file_state.mark_emitted(added, deleted, now)
@@ -916,6 +916,7 @@ def _event_payload(
     deleted: int,
     approximate: bool,
     binary: bool = False,
+    operation: str | None = None,
 ) -> dict[str, Any]:
     payload: dict[str, Any] = {
         "version": 1,
@@ -931,6 +932,8 @@ def _event_payload(
     }
     if binary:
         payload["binary"] = True
+    if operation:
+        payload["operation"] = operation
     return payload
 
 

nanobot/utils/helpers.py

@@ -626,3 +626,14 @@ def sync_workspace_templates(workspace: Path, silent: bool = False) -> list[str]
         logger.exception("Failed to initialize git store for {}", workspace)
 
     return added
+
+
+def load_bundled_template(template_name: str) -> str | None:
+    """Read a bundled template file from the nanobot package."""
+    from importlib.resources import files as pkg_files
+
+    with suppress(Exception):
+        tpl = pkg_files("nanobot") / "templates" / template_name
+        if tpl.is_file():
+            return tpl.read_text(encoding="utf-8")
+    return None

nanobot/utils/runtime.py

@@ -29,6 +29,11 @@ LENGTH_RECOVERY_PROMPT = (
     "— no recap, no apology. Break remaining work into smaller steps if needed."
 )
 
+SUSTAINED_GOAL_CONTINUE_PROMPT = (
+    "You have an active sustained goal. Please continue working toward the "
+    "objective using your tools, or call complete_goal if the work is truly finished."
+)
+
 
 def empty_tool_result_message(tool_name: str) -> str:
     """Short prompt-safe marker for tools that completed without visible output."""
@@ -65,6 +70,11 @@ def build_length_recovery_message() -> dict[str, str]:
     return {"role": "user", "content": LENGTH_RECOVERY_PROMPT}
 
 
+def build_goal_continue_message(custom: str | None = None) -> dict[str, str]:
+    """Prompt the model to continue when a sustained goal is still active."""
+    return {"role": "user", "content": custom or SUSTAINED_GOAL_CONTINUE_PROMPT}
+
+
 def external_lookup_signature(tool_name: str, arguments: dict[str, Any]) -> str | None:
     """Stable signature for repeated external lookups we want to throttle."""
     if tool_name == "web_fetch":

nanobot/webui/cli_apps_api.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import re
 from typing import Any
 
-from nanobot.cli_apps import CliAppError, CliAppManager, CliAppsRuntimeConfig
+from nanobot.apps.cli import CliAppError, CliAppManager, CliAppsRuntimeConfig
 from nanobot.config.loader import load_config
 
 QueryParams = dict[str, list[str]]

nanobot/webui/mcp_presets_runtime.py

@@ -0,0 +1,5 @@
+"""Compatibility exports for WebUI-attached MCP preset annotations."""
+
+from nanobot.agent.tools.mcp import runtime_lines, session_extra
+
+__all__ = ["runtime_lines", "session_extra"]

nanobot/webui/media_api.py

@@ -0,0 +1,255 @@
+"""Signed media helpers for the WebUI HTTP surface."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import email.utils
+import hashlib
+import hmac
+import http
+import mimetypes
+import re
+import shutil
+import uuid
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from websockets.datastructures import Headers
+from websockets.http11 import Request as WsRequest
+from websockets.http11 import Response
+
+from nanobot.config.paths import get_media_dir
+from nanobot.utils.helpers import safe_filename
+
+MediaDirProvider = Callable[[str | None], Path]
+
+
+def b64url_encode(data: bytes) -> str:
+    """URL-safe base64 without padding."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def b64url_decode(value: str) -> bytes:
+    """Reverse of :func:`b64url_encode`; caller handles decode errors."""
+    pad = "=" * (-len(value) % 4)
+    return base64.urlsafe_b64decode(value + pad)
+
+
+def _default_media_dir(channel: str | None = None) -> Path:
+    return get_media_dir(channel)
+
+
+# Allowed MIME types we actually serve from the media endpoint. Anything
+# outside this set is degraded to ``application/octet-stream`` so an
+# attacker who somehow gets a signed URL for an unexpected file type can't
+# trick the browser into sniffing executable content.
+_MEDIA_ALLOWED_MIMES: frozenset[str] = frozenset({
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+    "image/svg+xml",
+    "video/mp4",
+    "video/webm",
+    "video/quicktime",
+})
+_SVG_MEDIA_HEADERS: tuple[tuple[str, str], ...] = (
+    (
+        "Content-Security-Policy",
+        "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; sandbox",
+    ),
+)
+
+_BYTE_RANGE_RE = re.compile(r"^bytes=(\d*)-(\d*)$")
+
+
+def _http_response(
+    body: bytes,
+    *,
+    status: int = 200,
+    content_type: str = "text/plain; charset=utf-8",
+    extra_headers: list[tuple[str, str]] | None = None,
+) -> Response:
+    headers = [
+        ("Date", email.utils.formatdate(usegmt=True)),
+        ("Connection", "close"),
+        ("Content-Length", str(len(body))),
+        ("Content-Type", content_type),
+    ]
+    if extra_headers:
+        headers.extend(extra_headers)
+    reason = http.HTTPStatus(status).phrase
+    return Response(status, reason, Headers(headers), body)
+
+
+def _http_error(status: int, message: str | None = None) -> Response:
+    body = (message or http.HTTPStatus(status).phrase).encode("utf-8")
+    return _http_response(body, status=status)
+
+
+def _case_insensitive_header(headers: Any, key: str) -> str:
+    try:
+        value = headers.get(key)
+    except Exception:
+        value = None
+    if value is None:
+        try:
+            value = headers.get(key.lower())
+        except Exception:
+            value = None
+    return str(value or "").strip()
+
+
+def _parse_single_byte_range(range_header: str, size: int) -> tuple[int, int]:
+    """Parse a single HTTP byte range for signed media responses."""
+    if size <= 0 or "," in range_header:
+        raise ValueError("invalid byte range")
+    m = _BYTE_RANGE_RE.fullmatch(range_header.strip())
+    if m is None:
+        raise ValueError("invalid byte range")
+    start_text, end_text = m.groups()
+    if not start_text and not end_text:
+        raise ValueError("invalid byte range")
+    if not start_text:
+        suffix_length = int(end_text)
+        if suffix_length <= 0:
+            raise ValueError("invalid byte range")
+        start = max(size - suffix_length, 0)
+        end = size - 1
+    else:
+        start = int(start_text)
+        end = int(end_text) if end_text else size - 1
+        if start >= size or start > end:
+            raise ValueError("invalid byte range")
+        end = min(end, size - 1)
+    return start, end
+
+
+def sign_media_path(
+    abs_path: Path,
+    *,
+    secret: bytes,
+    media_dir: MediaDirProvider = _default_media_dir,
+) -> str | None:
+    """Return a signed ``/api/media/<sig>/<payload>`` URL for a media-root path."""
+    try:
+        media_root = media_dir(None).resolve()
+        rel = abs_path.resolve().relative_to(media_root)
+    except (OSError, ValueError):
+        return None
+    payload = b64url_encode(rel.as_posix().encode("utf-8"))
+    mac = hmac.new(secret, payload.encode("ascii"), hashlib.sha256).digest()[:16]
+    return f"/api/media/{b64url_encode(mac)}/{payload}"
+
+
+def sign_or_stage_media_path(
+    path: Path,
+    *,
+    secret: bytes,
+    media_dir: MediaDirProvider = _default_media_dir,
+    logger: Any | None = None,
+) -> dict[str, str] | None:
+    """Sign an existing media-root path, or stage an arbitrary file before signing."""
+    signed = sign_media_path(path, secret=secret, media_dir=media_dir)
+    if signed is not None:
+        return {"url": signed, "name": path.name}
+    try:
+        if not path.is_file():
+            return None
+        target_dir = media_dir("websocket")
+        safe_name = safe_filename(path.name) or "attachment"
+        staged = target_dir / f"{uuid.uuid4().hex[:12]}-{safe_name}"
+        shutil.copyfile(path, staged)
+    except OSError as exc:
+        if logger is not None:
+            logger.warning("failed to stage outbound media {}: {}", path, exc)
+        return None
+    signed = sign_media_path(staged, secret=secret, media_dir=media_dir)
+    if signed is None:
+        return None
+    return {"url": signed, "name": path.name}
+
+
+def serve_signed_media(
+    sig: str,
+    payload: str,
+    *,
+    secret: bytes,
+    request: WsRequest | None = None,
+    media_dir: MediaDirProvider = _default_media_dir,
+) -> Response:
+    """Serve a signed media URL, including browser-friendly byte ranges."""
+    try:
+        provided_mac = b64url_decode(sig)
+    except (ValueError, binascii.Error):
+        return _http_error(401, "invalid signature")
+    expected_mac = hmac.new(secret, payload.encode("ascii"), hashlib.sha256).digest()[:16]
+    if not hmac.compare_digest(expected_mac, provided_mac):
+        return _http_error(401, "invalid signature")
+    try:
+        rel_bytes = b64url_decode(payload)
+        rel_str = rel_bytes.decode("utf-8")
+    except (ValueError, binascii.Error, UnicodeDecodeError):
+        return _http_error(400, "invalid payload")
+    try:
+        media_root = media_dir(None).resolve()
+        candidate = (media_root / rel_str).resolve()
+        candidate.relative_to(media_root)
+    except (OSError, ValueError):
+        return _http_error(404, "not found")
+    if not candidate.is_file():
+        return _http_error(404, "not found")
+
+    mime, _ = mimetypes.guess_type(candidate.name)
+    if mime not in _MEDIA_ALLOWED_MIMES:
+        mime = "application/octet-stream"
+    common_headers = [
+        ("Accept-Ranges", "bytes"),
+        ("Cache-Control", "private, max-age=31536000, immutable"),
+        ("X-Content-Type-Options", "nosniff"),
+    ]
+    if mime == "image/svg+xml":
+        common_headers.extend(_SVG_MEDIA_HEADERS)
+    try:
+        size = candidate.stat().st_size
+    except OSError:
+        return _http_error(500, "read error")
+
+    range_header = _case_insensitive_header(request.headers, "Range") if request else ""
+    if range_header:
+        try:
+            start, end = _parse_single_byte_range(range_header, size)
+        except ValueError:
+            return _http_response(
+                b"range not satisfiable",
+                status=416,
+                extra_headers=[
+                    ("Accept-Ranges", "bytes"),
+                    ("Content-Range", f"bytes */{size}"),
+                    ("X-Content-Type-Options", "nosniff"),
+                ],
+            )
+        try:
+            length = end - start + 1
+            with candidate.open("rb") as fh:
+                fh.seek(start)
+                body = fh.read(length)
+        except OSError:
+            return _http_error(500, "read error")
+        return _http_response(
+            body,
+            status=206,
+            content_type=mime,
+            extra_headers=[
+                *common_headers,
+                ("Content-Range", f"bytes {start}-{end}/{size}"),
+            ],
+        )
+
+    try:
+        body = candidate.read_bytes()
+    except OSError:
+        return _http_error(500, "read error")
+    return _http_response(body, content_type=mime, extra_headers=common_headers)

nanobot/webui/settings_api.py

@@ -6,17 +6,64 @@ settings payload shape and the allowlisted config mutations exposed to WebUI.
 
 from __future__ import annotations
 
-from typing import Any
+import os
+import re
+import time
+from contextlib import suppress
+from typing import Any, Literal
 from zoneinfo import ZoneInfo
 
+import httpx
+
 from nanobot.config.loader import get_config_path, load_config, save_config
+from nanobot.config.schema import ModelPresetConfig
 from nanobot.providers.image_generation import (
     get_image_gen_provider,
     image_gen_provider_names,
 )
 from nanobot.providers.registry import PROVIDERS, find_by_name
+from nanobot.security.workspace_access import workspace_sandbox_status
+from nanobot.webui.workspaces import (
+    read_webui_default_access_mode,
+    write_webui_default_access_mode,
+)
 
 QueryParams = dict[str, list[str]]
+RuntimeSurface = Literal["browser", "native"]
+
+_RUNTIME_CAPABILITIES = {
+    "can_restart_engine": False,
+    "can_pick_folder": False,
+    "can_open_logs": False,
+    "can_export_diagnostics": False,
+}
+
+_NATIVE_RUNTIME_CAPABILITIES = {
+    **_RUNTIME_CAPABILITIES,
+    "can_restart_engine": True,
+    "can_pick_folder": True,
+    "can_open_logs": True,
+    "can_export_diagnostics": True,
+}
+
+_BROWSER_RESTART_BEHAVIOR_BY_SECTION = {
+    "appearance": "none",
+    "models": "none",
+    "providers": "none",
+    "runtime": "engineRestart",
+    "browser": "engineRestart",
+    "image": "engineRestart",
+    "apps": "engineRestart",
+    "advanced": "appRestart",
+}
+
+_NATIVE_RESTART_BEHAVIOR_BY_SECTION = {
+    **_BROWSER_RESTART_BEHAVIOR_BY_SECTION,
+    "runtime": "engineRestart",
+    "browser": "engineRestart",
+    "image": "engineRestart",
+    "apps": "engineRestart",
+}
 
 _WEB_SEARCH_PROVIDER_OPTIONS: tuple[dict[str, str], ...] = (
     {"name": "duckduckgo", "label": "DuckDuckGo", "credential": "none"},
@@ -41,6 +88,49 @@ _IMAGE_GENERATION_ASPECT_RATIOS = {
     "2:3",
     "21:9",
 }
+_CONTEXT_WINDOW_TOKEN_OPTIONS = {65_536, 262_144}
+_MODEL_CONFIGURATION_SLUG_RE = re.compile(r"[^a-z0-9_-]+")
+_ENV_REF_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+_MODEL_LIST_UNSUPPORTED_BACKENDS = {
+    "anthropic",
+    "azure_openai",
+    "bedrock",
+    "github_copilot",
+    "openai_codex",
+}
+
+_MODEL_LIST_CATALOG_PROVIDERS = {
+    "aihubmix",
+    "byteplus",
+    "byteplus_coding_plan",
+    "huggingface",
+    "novita",
+    "openrouter",
+    "siliconflow",
+    "volcengine",
+    "volcengine_coding_plan",
+}
+
+_MODEL_LIST_OFFICIAL_PROVIDERS = {
+    "ant_ling",
+    "dashscope",
+    "deepseek",
+    "gemini",
+    "groq",
+    "longcat",
+    "minimax",
+    "minimax_anthropic",
+    "mistral",
+    "moonshot",
+    "nvidia",
+    "openai",
+    "qianfan",
+    "skywork",
+    "stepfun",
+    "xiaomi_mimo",
+    "zhipu",
+}
 
 
 class WebUISettingsError(ValueError):
@@ -52,6 +142,70 @@ class WebUISettingsError(ValueError):
         self.status = status
 
 
+def _normalize_surface(surface: str | None) -> RuntimeSurface:
+    return "native" if surface in {"native", "desktop"} else "browser"
+
+
+def runtime_capabilities(
+    surface: str | None = "browser",
+    overrides: dict[str, Any] | None = None,
+) -> dict[str, bool]:
+    """Return the capability flags exposed to the WebUI runtime."""
+    base = (
+        _NATIVE_RUNTIME_CAPABILITIES
+        if _normalize_surface(surface) == "native"
+        else _RUNTIME_CAPABILITIES
+    )
+    result = dict(base)
+    for key, value in (overrides or {}).items():
+        if key in result:
+            result[key] = bool(value)
+    return result
+
+
+def restart_behavior_by_section(surface: str | None = "browser") -> dict[str, str]:
+    return dict(
+        _NATIVE_RESTART_BEHAVIOR_BY_SECTION
+        if _normalize_surface(surface) == "native"
+        else _BROWSER_RESTART_BEHAVIOR_BY_SECTION
+    )
+
+
+def decorate_settings_payload(
+    payload: dict[str, Any],
+    *,
+    surface: str | None = "browser",
+    runtime_capability_overrides: dict[str, Any] | None = None,
+    restart_required_sections: list[str] | None = None,
+    apply_state: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Attach runtime-surface metadata without changing the core settings shape."""
+    surface_value = _normalize_surface(surface)
+    sections = restart_required_sections
+    if sections is None:
+        raw_sections = payload.get("restart_required_sections") or []
+        sections = [str(section) for section in raw_sections if isinstance(section, str)]
+    sections = sorted(dict.fromkeys(sections))
+    result = dict(payload)
+    result["surface"] = surface_value
+    result["runtime_surface"] = surface_value
+    result["runtime_capabilities"] = runtime_capabilities(
+        surface_value,
+        runtime_capability_overrides,
+    )
+    result["restart_behavior_by_section"] = restart_behavior_by_section(surface_value)
+    result["restart_required_sections"] = sections
+    if sections:
+        result["requires_restart"] = True
+    else:
+        result["requires_restart"] = bool(result.get("requires_restart", False))
+    result["apply_state"] = apply_state or {
+        "status": "pending" if result["requires_restart"] else "idle",
+        "sections": sections,
+    }
+    return result
+
+
 def _query_first(query: QueryParams, key: str) -> str | None:
     values = query.get(key)
     return values[0] if values else None
@@ -70,6 +224,25 @@ def _mask_secret_hint(secret: str | None) -> str | None:
     return f"{secret[:4]}••••{secret[-4:]}"
 
 
+def _resolve_env_placeholders(value: str | None) -> str | None:
+    if not value:
+        return None
+    missing = False
+
+    def replace(match: re.Match[str]) -> str:
+        nonlocal missing
+        env_value = os.environ.get(match.group(1))
+        if env_value is None:
+            missing = True
+            return ""
+        return env_value
+
+    resolved = _ENV_REF_RE.sub(replace, value).strip()
+    if missing and not resolved:
+        return None
+    return resolved or None
+
+
 def _provider_requires_api_key(spec: Any) -> bool:
     if spec.backend == "azure_openai":
         return True
@@ -80,9 +253,57 @@ def _provider_requires_api_key(spec: Any) -> bool:
     return True
 
 
+def _oauth_provider_status(spec: Any) -> dict[str, Any]:
+    if not getattr(spec, "is_oauth", False):
+        return {"configured": False, "account": None, "expires_at": None, "login_supported": False}
+
+    if spec.name == "openai_codex":
+        try:
+            from oauth_cli_kit import get_token as get_codex_token
+        except Exception:
+            return {
+                "configured": False,
+                "account": None,
+                "expires_at": None,
+                "login_supported": False,
+            }
+        token = None
+        with suppress(Exception):
+            token = get_codex_token()
+        expires_at = getattr(token, "expires", None) if token else None
+        return {
+            "configured": bool(token and token.access),
+            "account": getattr(token, "account_id", None) if token else None,
+            "expires_at": expires_at,
+            "login_supported": True,
+        }
+
+    if spec.name == "github_copilot":
+        try:
+            from nanobot.providers.github_copilot_provider import get_github_copilot_login_status
+        except Exception:
+            return {
+                "configured": False,
+                "account": None,
+                "expires_at": None,
+                "login_supported": False,
+            }
+        token = None
+        with suppress(Exception):
+            token = get_github_copilot_login_status()
+        return {
+            "configured": bool(token and token.access and token.expires > int(time.time() * 1000)),
+            "account": getattr(token, "account_id", None) if token else None,
+            "expires_at": getattr(token, "expires", None) if token else None,
+            "login_supported": True,
+        }
+
+    return {"configured": False, "account": None, "expires_at": None, "login_supported": False}
+
+
 def _provider_configured_for_settings(spec: Any, provider_config: Any) -> bool:
     if spec.is_oauth:
-        return True
+        return bool(_oauth_provider_status(spec)["configured"])
     if _provider_requires_api_key(spec):
         return bool(provider_config.api_key)
     return bool(
@@ -93,6 +314,191 @@ def _provider_configured_for_settings(spec: Any, provider_config: Any) -> bool:
     )
 
 
+def _model_catalog_kind(spec: Any) -> str:
+    if spec.name in _MODEL_LIST_CATALOG_PROVIDERS:
+        return "catalog"
+    if spec.name in _MODEL_LIST_OFFICIAL_PROVIDERS:
+        return "official"
+    if spec.is_local:
+        return "local"
+    if spec.is_direct:
+        return "custom"
+    if spec.is_gateway:
+        return "catalog"
+    return "official"
+
+
+def _model_id_from_row(row: Any) -> str | None:
+    if isinstance(row, str):
+        return row.strip() or None
+    if not isinstance(row, dict):
+        return None
+    for key in ("id", "name", "model"):
+        value = row.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _model_context_window(row: Any) -> int | None:
+    if not isinstance(row, dict):
+        return None
+    for key in (
+        "context_window",
+        "context_length",
+        "max_context_length",
+        "max_model_len",
+        "max_input_tokens",
+    ):
+        value = row.get(key)
+        if isinstance(value, int) and value > 0:
+            return value
+        if isinstance(value, float) and value > 0:
+            return int(value)
+    return None
+
+
+def _model_row_payload(row: Any) -> dict[str, Any] | None:
+    model_id = _model_id_from_row(row)
+    if not model_id:
+        return None
+    label: str | None = None
+    owned_by: str | None = None
+    if isinstance(row, dict):
+        raw_label = row.get("display_name") or row.get("label") or row.get("name")
+        if isinstance(raw_label, str) and raw_label.strip() and raw_label.strip() != model_id:
+            label = raw_label.strip()
+        raw_owner = row.get("owned_by") or row.get("owner") or row.get("organization")
+        if isinstance(raw_owner, str) and raw_owner.strip():
+            owned_by = raw_owner.strip()
+    return {
+        "id": model_id,
+        "label": label,
+        "owned_by": owned_by,
+        "context_window": _model_context_window(row),
+    }
+
+
+def _extract_model_rows(body: Any) -> list[dict[str, Any]]:
+    raw_rows = body.get("data") if isinstance(body, dict) else body
+    if not isinstance(raw_rows, list):
+        return []
+    rows: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for raw_row in raw_rows:
+        row = _model_row_payload(raw_row)
+        if row is None or row["id"] in seen:
+            continue
+        seen.add(row["id"])
+        rows.append(row)
+    return rows
+
+
+def provider_models_payload(query: QueryParams) -> dict[str, Any]:
+    """Fetch an OpenAI-compatible provider's model list for Settings.
+
+    The result is advisory only: users can always type a custom model id. This
+    helper deliberately avoids mutating config so probing model lists never
+    changes runtime behavior.
+    """
+    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:
+        raise WebUISettingsError("unknown provider")
+
+    base_payload: dict[str, Any] = {
+        "provider": spec.name,
+        "label": spec.label,
+        "catalog_kind": _model_catalog_kind(spec),
+        "models": [],
+        "model_count": 0,
+        "message": None,
+        "fetched_at": time.time(),
+    }
+    if (
+        spec.backend in _MODEL_LIST_UNSUPPORTED_BACKENDS
+        and spec.name != "minimax_anthropic"
+    ) or spec.is_oauth:
+        return {
+            **base_payload,
+            "status": "unsupported",
+            "catalog_kind": "unsupported",
+            "message": "Model list is not available for this provider. Type a model ID manually.",
+        }
+
+    config = load_config()
+    provider_config = getattr(config.providers, spec.name, None)
+    if provider_config is None:
+        raise WebUISettingsError("unknown provider")
+
+    api_base = _resolve_env_placeholders(provider_config.api_base) or spec.default_api_base
+    if spec.name == "openai" and not api_base:
+        api_base = "https://api.openai.com/v1"
+    if not api_base:
+        return {
+            **base_payload,
+            "status": "missing_api_base",
+            "message": "Configure an API base URL to load models.",
+        }
+
+    api_key = _resolve_env_placeholders(provider_config.api_key)
+    if _provider_requires_api_key(spec) and not api_key:
+        return {
+            **base_payload,
+            "status": "not_configured",
+            "message": "Configure this provider before loading models.",
+        }
+
+    headers = {"Accept": "application/json"}
+    if api_key:
+        if spec.name == "minimax_anthropic":
+            headers["X-Api-Key"] = api_key
+        else:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+    models_url = f"{api_base.rstrip('/')}/models"
+    if spec.name == "minimax_anthropic" and not api_base.rstrip("/").endswith("/v1"):
+        models_url = f"{api_base.rstrip('/')}/v1/models"
+
+    try:
+        response = httpx.get(
+            models_url,
+            headers=headers,
+            timeout=10.0,
+            follow_redirects=False,
+        )
+        response.raise_for_status()
+        rows = _extract_model_rows(response.json())
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code
+        if status in {401, 403}:
+            return {
+                **base_payload,
+                "status": "not_configured",
+                "message": "The provider rejected the configured credential.",
+            }
+        return {
+            **base_payload,
+            "status": "error",
+            "message": f"Model list request failed with HTTP {status}.",
+        }
+    except (httpx.HTTPError, ValueError) as exc:
+        return {
+            **base_payload,
+            "status": "error",
+            "message": f"Could not load models: {exc}",
+        }
+
+    return {
+        **base_payload,
+        "status": "available",
+        "models": rows,
+        "model_count": len(rows),
+    }
+
+
 def _parse_bool(value: str, field: str) -> bool:
     normalized = value.strip().lower()
     if normalized not in {"1", "0", "true", "false", "yes", "no"}:
@@ -100,6 +506,44 @@ def _parse_bool(value: str, field: str) -> bool:
     return normalized in {"1", "true", "yes"}
 
 
+def _parse_context_window_tokens(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        parsed = int(value)
+    except ValueError:
+        raise WebUISettingsError("context_window_tokens must be an integer") from None
+    if parsed not in _CONTEXT_WINDOW_TOKEN_OPTIONS:
+        raise WebUISettingsError("context_window_tokens must be 65536 or 262144")
+    return parsed
+
+
+def _model_configuration_slug(label: str) -> str:
+    normalized = _MODEL_CONFIGURATION_SLUG_RE.sub("-", label.strip().lower())
+    normalized = normalized.strip("-_")
+    if not normalized:
+        raise WebUISettingsError("configuration name is required")
+    if normalized == "default":
+        raise WebUISettingsError("configuration name is reserved")
+    if len(normalized) > 48:
+        normalized = normalized[:48].rstrip("-_")
+    return normalized
+
+
+def _validate_configured_provider(config: Any, provider: str) -> None:
+    if provider == "auto":
+        return
+    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")
+
+
 def _image_generation_provider_rows(config: Any) -> list[dict[str, Any]]:
     rows: list[dict[str, Any]] = []
     for name in image_gen_provider_names():
@@ -115,6 +559,7 @@ def _image_generation_provider_rows(config: Any) -> list[dict[str, Any]]:
                 "name": name,
                 "label": spec.label if spec is not None else name,
                 "configured": configured,
+                "auth_type": "oauth" if spec is not None and spec.is_oauth else "api_key",
                 "api_key_hint": _mask_secret_hint(
                     getattr(provider_config, "api_key", None)
                 ),
@@ -127,7 +572,14 @@ def _image_generation_provider_rows(config: Any) -> list[dict[str, Any]]:
     return rows
 
 
-def settings_payload(*, requires_restart: bool = False) -> dict[str, Any]:
+def settings_payload(
+    *,
+    requires_restart: bool = False,
+    surface: str | None = "browser",
+    runtime_capability_overrides: dict[str, Any] | None = None,
+    restart_required_sections: list[str] | None = None,
+    apply_state: dict[str, Any] | None = None,
+) -> dict[str, Any]:
     config = load_config()
     defaults = config.agents.defaults
     active_preset_name = defaults.model_preset or "default"
@@ -150,19 +602,30 @@ def settings_payload(*, requires_restart: bool = False) -> dict[str, Any]:
     providers = []
     for spec in PROVIDERS:
         provider_config = getattr(config.providers, spec.name, None)
-        if provider_config is None or spec.is_oauth:
+        if provider_config is None:
             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,
-            }
-        )
+        oauth_status = _oauth_provider_status(spec) if spec.is_oauth else None
+        row = {
+            "name": spec.name,
+            "label": spec.label,
+            "configured": (
+                bool(oauth_status["configured"])
+                if oauth_status is not None
+                else _provider_configured_for_settings(spec, provider_config)
+            ),
+            "auth_type": "oauth" if spec.is_oauth else "api_key",
+            "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,
+        }
+        if oauth_status is not None:
+            row["oauth_account"] = oauth_status["account"]
+            row["oauth_expires_at"] = oauth_status["expires_at"]
+            row["oauth_login_supported"] = oauth_status["login_supported"]
+        if spec.name == "openai":
+            row["api_type"] = provider_config.api_type
+        providers.append(row)
 
     search_config = config.tools.web.search
     image_config = config.tools.image_generation
@@ -198,7 +661,7 @@ def settings_payload(*, requires_restart: bool = False) -> dict[str, Any]:
         model_presets.append(
             {
                 "name": name,
-                "label": name,
+                "label": preset.label or name,
                 "active": active_preset_name == name,
                 "is_default": False,
                 "model": preset.model,
@@ -211,7 +674,11 @@ def settings_payload(*, requires_restart: bool = False) -> dict[str, Any]:
         )
 
     exec_config = config.tools.exec
-    return {
+    sandbox_status = workspace_sandbox_status(
+        restrict_to_workspace=config.tools.restrict_to_workspace,
+        workspace=config.workspace_path,
+    )
+    payload = {
         "agent": {
             "model": effective_preset.model,
             "provider": selected_provider,
@@ -282,6 +749,11 @@ def settings_payload(*, requires_restart: bool = False) -> dict[str, Any]:
         },
         "advanced": {
             "restrict_to_workspace": config.tools.restrict_to_workspace,
+            "workspace_sandbox": sandbox_status.as_dict(),
+            "webui_allow_local_service_access": config.tools.webui_allow_local_service_access,
+            "allow_local_preview_access": config.tools.webui_allow_local_service_access,
+            "webui_default_access_mode": read_webui_default_access_mode(),
+            "private_service_protection_enabled": True,
             "ssrf_whitelist_count": len(config.tools.ssrf_whitelist),
             "mcp_server_count": len(config.tools.mcp_servers),
             "exec_enabled": exec_config.enable,
@@ -290,6 +762,13 @@ def settings_payload(*, requires_restart: bool = False) -> dict[str, Any]:
         },
         "requires_restart": requires_restart,
     }
+    return decorate_settings_payload(
+        payload,
+        surface=surface,
+        runtime_capability_overrides=runtime_capability_overrides,
+        restart_required_sections=restart_required_sections,
+        apply_state=apply_state,
+    )
 
 
 def update_agent_settings(query: QueryParams) -> dict[str, Any]:
@@ -321,19 +800,21 @@ def update_agent_settings(query: QueryParams) -> dict[str, Any]:
         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")
+        _validate_configured_provider(config, provider)
         if defaults.provider != provider:
             defaults.provider = provider
             changed = True
 
+    context_window_tokens = _parse_context_window_tokens(
+        _query_first_alias(query, "context_window_tokens", "contextWindowTokens")
+    )
+    if (
+        context_window_tokens is not None
+        and defaults.context_window_tokens != context_window_tokens
+    ):
+        defaults.context_window_tokens = context_window_tokens
+        changed = True
+
     timezone = _query_first(query, "timezone")
     if timezone is not None:
         timezone = timezone.strip()
@@ -388,6 +869,98 @@ def update_agent_settings(query: QueryParams) -> dict[str, Any]:
     return settings_payload(requires_restart=restart_required)
 
 
+def create_model_configuration(query: QueryParams) -> dict[str, Any]:
+    label = (_query_first_alias(query, "label", "displayName") or "").strip()
+    raw_name = (_query_first(query, "name") or label).strip()
+    model = (_query_first(query, "model") or "").strip()
+    provider = (_query_first(query, "provider") or "").strip()
+
+    if not label:
+        label = raw_name
+    if not model:
+        raise WebUISettingsError("model is required")
+    if not provider:
+        raise WebUISettingsError("provider is required")
+
+    name = _model_configuration_slug(raw_name or label)
+    config = load_config()
+    if name in config.model_presets:
+        raise WebUISettingsError("configuration already exists", status=409)
+    _validate_configured_provider(config, provider)
+
+    base = config.resolve_default_preset()
+    config.model_presets[name] = ModelPresetConfig(
+        label=label,
+        model=model,
+        provider=provider,
+        max_tokens=base.max_tokens,
+        context_window_tokens=base.context_window_tokens,
+        temperature=base.temperature,
+        reasoning_effort=base.reasoning_effort,
+    )
+    config.agents.defaults.model_preset = name
+    save_config(config)
+    return settings_payload()
+
+
+def update_model_configuration(query: QueryParams) -> dict[str, Any]:
+    name = (_query_first(query, "name") or "").strip()
+    if not name or name == "default":
+        raise WebUISettingsError("model configuration is required")
+
+    config = load_config()
+    preset = config.model_presets.get(name)
+    if preset is None:
+        raise WebUISettingsError("unknown model configuration")
+
+    changed = False
+    label = _query_first_alias(query, "label", "displayName")
+    if label is not None:
+        label = label.strip()
+        if not label:
+            raise WebUISettingsError("label is required")
+        if preset.label != label:
+            preset.label = label
+            changed = True
+
+    model = _query_first(query, "model")
+    if model is not None:
+        model = model.strip()
+        if not model:
+            raise WebUISettingsError("model is required")
+        if preset.model != model:
+            preset.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")
+        _validate_configured_provider(config, provider)
+        if preset.provider != provider:
+            preset.provider = provider
+            changed = True
+
+    context_window_tokens = _parse_context_window_tokens(
+        _query_first_alias(query, "context_window_tokens", "contextWindowTokens")
+    )
+    if (
+        context_window_tokens is not None
+        and preset.context_window_tokens != context_window_tokens
+    ):
+        preset.context_window_tokens = context_window_tokens
+        changed = True
+
+    if config.agents.defaults.model_preset != name:
+        config.agents.defaults.model_preset = name
+        changed = True
+
+    if changed:
+        save_config(config)
+    return settings_payload()
+
+
 def update_provider_settings(query: QueryParams) -> dict[str, Any]:
     provider_name = (_query_first(query, "provider") or "").strip()
     if not provider_name:
@@ -416,6 +989,17 @@ def update_provider_settings(query: QueryParams) -> dict[str, Any]:
             provider_config.api_base = api_base
             changed = True
 
+    if "api_type" in query:
+        if spec.name == "openai":
+            api_type = (_query_first(query, "api_type") or "").strip()
+            try:
+                parsed_api_type = type(provider_config)(api_type=api_type).api_type
+            except Exception:
+                raise WebUISettingsError("api_type must be auto, chat_completions, or responses") from None
+            if provider_config.api_type != parsed_api_type:
+                provider_config.api_type = parsed_api_type
+                changed = True
+
     if changed:
         save_config(config)
     image_config = config.tools.image_generation
@@ -428,6 +1012,114 @@ def update_provider_settings(query: QueryParams) -> dict[str, Any]:
     return settings_payload(requires_restart=restart_required)
 
 
+def login_oauth_provider(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 not spec.is_oauth:
+        raise WebUISettingsError("unknown OAuth provider")
+
+    if spec.name == "openai_codex":
+        try:
+            from oauth_cli_kit import get_token, login_oauth_interactive
+        except ImportError:
+            raise WebUISettingsError("oauth_cli_kit is not installed", status=500) from None
+
+        token = None
+        with suppress(Exception):
+            token = get_token()
+        if not (token and token.access):
+            messages: list[str] = []
+            token = login_oauth_interactive(
+                print_fn=lambda message: messages.append(str(message)),
+                prompt_fn=lambda _prompt: "",
+            )
+        if not (token and token.access):
+            raise WebUISettingsError("OAuth login failed", status=401)
+        return settings_payload()
+
+    if spec.name == "github_copilot":
+        try:
+            from nanobot.providers.github_copilot_provider import (
+                get_github_copilot_login_status,
+                login_github_copilot,
+            )
+        except ImportError:
+            raise WebUISettingsError("GitHub Copilot OAuth support is unavailable", status=500) from None
+
+        token = get_github_copilot_login_status()
+        if not token:
+            token = login_github_copilot(print_fn=lambda _message: None)
+        if not (token and token.access):
+            raise WebUISettingsError("OAuth login failed", status=401)
+        return settings_payload()
+
+    raise WebUISettingsError("OAuth login is not supported for this provider")
+
+
+def logout_oauth_provider(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 not spec.is_oauth:
+        raise WebUISettingsError("unknown OAuth provider")
+
+    if spec.name == "openai_codex":
+        try:
+            from oauth_cli_kit.providers import OPENAI_CODEX_PROVIDER
+            from oauth_cli_kit.storage import FileTokenStorage
+        except ImportError:
+            raise WebUISettingsError("oauth_cli_kit is not installed", status=500) from None
+        token_path = FileTokenStorage(token_filename=OPENAI_CODEX_PROVIDER.token_filename).get_token_path()
+    elif spec.name == "github_copilot":
+        try:
+            from nanobot.providers.github_copilot_provider import get_storage
+        except ImportError:
+            raise WebUISettingsError("GitHub Copilot OAuth support is unavailable", status=500) from None
+        token_path = get_storage().get_token_path()
+    else:
+        raise WebUISettingsError("OAuth logout is not supported for this provider")
+
+    for path in (token_path, token_path.with_suffix(".lock")):
+        with suppress(FileNotFoundError):
+            path.unlink()
+    return settings_payload()
+
+
+def update_network_safety_settings(query: QueryParams) -> dict[str, Any]:
+    raw_allow = (
+        _query_first_alias(query, "webui_allow_local_service_access", "webuiAllowLocalServiceAccess")
+        or _query_first_alias(query, "allow_local_preview_access", "allowLocalPreviewAccess")
+    )
+    raw_default_access_mode = _query_first_alias(query, "webui_default_access_mode", "webuiDefaultAccessMode")
+    if raw_allow is None and raw_default_access_mode is None:
+        raise WebUISettingsError("webui_allow_local_service_access or webui_default_access_mode is required")
+
+    config = load_config()
+    changed = False
+    if raw_allow is not None:
+        webui_allow_local_service_access = _parse_bool(raw_allow, "webui_allow_local_service_access")
+        if config.tools.webui_allow_local_service_access != webui_allow_local_service_access:
+            config.tools.webui_allow_local_service_access = webui_allow_local_service_access
+            changed = True
+
+    if changed:
+        save_config(config)
+    if raw_default_access_mode is not None:
+        default_access_mode = raw_default_access_mode.strip().lower()
+        if default_access_mode == "restricted":
+            default_access_mode = "default"
+        if default_access_mode not in {"default", "full"}:
+            raise WebUISettingsError("webui_default_access_mode must be default or full")
+        try:
+            write_webui_default_access_mode(default_access_mode)
+        except ValueError as exc:
+            raise WebUISettingsError(str(exc)) from exc
+    return settings_payload(requires_restart=changed)
+
+
 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)

nanobot/webui/settings_routes.py

@@ -0,0 +1,329 @@
+"""HTTP route adapter for WebUI Settings APIs.
+
+Keep WebUI Settings route handlers here, not in ``channels/websocket.py``.
+The websocket channel owns transport concerns; this module owns WebUI Settings
+request mapping and response shaping.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from typing import Any
+
+from websockets.http11 import Request as WsRequest
+from websockets.http11 import Response
+
+from nanobot.agent.tools.mcp import request_mcp_reload
+from nanobot.bus.queue import MessageBus
+from nanobot.webui.cli_apps_api import cli_apps_action, cli_apps_payload
+from nanobot.webui.mcp_presets_api import mcp_presets_settings_action
+from nanobot.webui.settings_api import (
+    WebUISettingsError,
+    create_model_configuration,
+    decorate_settings_payload,
+    login_oauth_provider,
+    logout_oauth_provider,
+    provider_models_payload,
+    settings_payload,
+    update_agent_settings,
+    update_image_generation_settings,
+    update_model_configuration,
+    update_network_safety_settings,
+    update_provider_settings,
+    update_web_search_settings,
+)
+
+QueryParams = dict[str, list[str]]
+
+_MCP_VALUES_HEADER = "X-Nanobot-MCP-Values"
+_MCP_VALUES_HEADER_MAX_BYTES = 64 * 1024
+
+_MCP_PRESET_ACTIONS_BY_PATH = {
+    "/api/settings/mcp-presets/enable": "enable",
+    "/api/settings/mcp-presets/remove": "remove",
+    "/api/settings/mcp-presets/test": "test",
+    "/api/settings/mcp-presets/custom": "custom",
+    "/api/settings/mcp-presets/import": "import",
+    "/api/settings/mcp-presets/import-cursor": "import-cursor",
+    "/api/settings/mcp-presets/tools": "tools",
+}
+
+
+class WebUISettingsRouter:
+    """Route WebUI Settings HTTP requests behind a transport-neutral boundary."""
+
+    def __init__(
+        self,
+        *,
+        bus: MessageBus,
+        logger: Any,
+        check_api_token: Callable[[WsRequest], bool],
+        parse_query: Callable[[str], QueryParams],
+        json_response: Callable[[dict[str, Any]], Response],
+        error_response: Callable[[int, str | None], Response],
+        runtime_surface: str,
+        runtime_capabilities: dict[str, Any],
+    ) -> None:
+        self.bus = bus
+        self.logger = logger
+        self._check_api_token = check_api_token
+        self._parse_query = parse_query
+        self._json_response = json_response
+        self._error_response = error_response
+        self._runtime_surface = runtime_surface
+        self._runtime_capabilities = runtime_capabilities
+        self._restart_sections: set[str] = set()
+
+    async def dispatch(self, request: WsRequest, path: str) -> Response | None:
+        if path == "/api/settings":
+            return self._handle_settings(request)
+        if path == "/api/settings/update":
+            return self._handle_settings_update(request)
+        if path == "/api/settings/model-configurations/create":
+            return self._handle_settings_model_configuration_create(request)
+        if path == "/api/settings/model-configurations/update":
+            return self._handle_settings_model_configuration_update(request)
+        if path == "/api/settings/provider/update":
+            return self._handle_settings_provider_update(request)
+        if path == "/api/settings/provider-models":
+            return await self._handle_settings_provider_models(request)
+        if path == "/api/settings/provider/oauth-login":
+            return await self._handle_settings_provider_oauth(request, "login")
+        if path == "/api/settings/provider/oauth-logout":
+            return await self._handle_settings_provider_oauth(request, "logout")
+        if path == "/api/settings/web-search/update":
+            return self._handle_settings_web_search_update(request)
+        if path == "/api/settings/image-generation/update":
+            return self._handle_settings_image_generation_update(request)
+        if path == "/api/settings/network-safety/update":
+            return self._handle_settings_network_safety_update(request)
+        if path == "/api/settings/cli-apps":
+            return self._handle_settings_cli_apps(request)
+        if path == "/api/settings/cli-apps/install":
+            return await self._handle_settings_cli_apps_action(request, "install")
+        if path == "/api/settings/cli-apps/update":
+            return await self._handle_settings_cli_apps_action(request, "update")
+        if path == "/api/settings/cli-apps/uninstall":
+            return await self._handle_settings_cli_apps_action(request, "uninstall")
+        if path == "/api/settings/cli-apps/test":
+            return await self._handle_settings_cli_apps_action(request, "test")
+        if path == "/api/settings/mcp-presets":
+            return await self._handle_settings_mcp_presets(request)
+        mcp_action = _MCP_PRESET_ACTIONS_BY_PATH.get(path)
+        if mcp_action is not None:
+            return await self._handle_settings_mcp_presets(request, mcp_action)
+        return None
+
+    def _query(self, request: WsRequest) -> QueryParams:
+        return self._parse_query(request.path)
+
+    def _authorized(self, request: WsRequest) -> bool:
+        return self._check_api_token(request)
+
+    def _unauthorized(self) -> Response:
+        return self._error_response(401, "Unauthorized")
+
+    def _with_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._restart_sections.add(section)
+        sections = sorted(self._restart_sections)
+        payload = dict(payload)
+        if sections:
+            payload["requires_restart"] = True
+        return decorate_settings_payload(
+            payload,
+            surface=self._runtime_surface,
+            runtime_capability_overrides=self._runtime_capabilities,
+            restart_required_sections=sections,
+        )
+
+    def _parse_mcp_settings_query(self, request: WsRequest) -> QueryParams:
+        query = self._query(request)
+        raw = request.headers.get(_MCP_VALUES_HEADER)
+        if not raw:
+            return query
+        if len(raw.encode("utf-8")) > _MCP_VALUES_HEADER_MAX_BYTES:
+            raise WebUISettingsError("MCP settings payload is too large")
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise WebUISettingsError("invalid MCP settings payload") from exc
+        if not isinstance(payload, dict):
+            raise WebUISettingsError("MCP settings payload must be a JSON object")
+        merged = {key: list(values) for key, values in query.items()}
+        for key, value in payload.items():
+            if not isinstance(key, str) or not key:
+                raise WebUISettingsError("MCP settings payload contains an invalid key")
+            if value is None:
+                continue
+            if isinstance(value, str):
+                text = value.strip()
+            else:
+                text = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+            if text:
+                merged[key] = [text]
+        return merged
+
+    def _handle_settings(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        return self._json_response(
+            self._with_restart_state(
+                settings_payload(
+                    surface=self._runtime_surface,
+                    runtime_capability_overrides=self._runtime_capabilities,
+                )
+            )
+        )
+
+    def _handle_settings_update(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = update_agent_settings(self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        return self._json_response(self._with_restart_state(payload, section="runtime"))
+
+    def _handle_settings_model_configuration_create(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = create_model_configuration(self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        return self._json_response(self._with_restart_state(payload))
+
+    def _handle_settings_model_configuration_update(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = update_model_configuration(self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        return self._json_response(self._with_restart_state(payload))
+
+    def _handle_settings_provider_update(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = update_provider_settings(self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        return self._json_response(self._with_restart_state(payload, section="image"))
+
+    async def _handle_settings_provider_models(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = await asyncio.to_thread(provider_models_payload, self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        except Exception:
+            self.logger.exception("failed to load provider model list")
+            return self._error_response(500, "failed to load provider model list")
+        return self._json_response(payload)
+
+    async def _handle_settings_provider_oauth(
+        self,
+        request: WsRequest,
+        action: str,
+    ) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        query = self._query(request)
+        try:
+            if action == "login":
+                payload = await asyncio.to_thread(login_oauth_provider, query)
+            else:
+                payload = await asyncio.to_thread(logout_oauth_provider, query)
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        return self._json_response(self._with_restart_state(payload))
+
+    def _handle_settings_web_search_update(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = update_web_search_settings(self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        return self._json_response(self._with_restart_state(payload, section="browser"))
+
+    def _handle_settings_image_generation_update(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = update_image_generation_settings(self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        return self._json_response(self._with_restart_state(payload, section="image"))
+
+    def _handle_settings_network_safety_update(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = update_network_safety_settings(self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        return self._json_response(self._with_restart_state(payload, section="runtime"))
+
+    def _handle_settings_cli_apps(self, request: WsRequest) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = cli_apps_payload()
+        except Exception:
+            self.logger.exception("failed to load CLI Apps payload")
+            return self._error_response(500, "failed to load CLI Apps")
+        return self._json_response(payload)
+
+    async def _handle_settings_cli_apps_action(
+        self,
+        request: WsRequest,
+        action: str,
+    ) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = await asyncio.to_thread(cli_apps_action, action, self._query(request))
+        except WebUISettingsError as e:
+            return self._error_response(e.status, e.message)
+        except Exception as e:
+            status = getattr(e, "status", 500)
+            message = getattr(e, "message", str(e))
+            if status >= 500:
+                self.logger.exception("CLI Apps action '{}' failed", action)
+            return self._error_response(status, message)
+        return self._json_response(payload)
+
+    async def _handle_settings_mcp_presets(
+        self,
+        request: WsRequest,
+        action: str | None = None,
+    ) -> Response:
+        if not self._authorized(request):
+            return self._unauthorized()
+        try:
+            payload = await mcp_presets_settings_action(
+                action,
+                self._parse_mcp_settings_query(request),
+                reload_mcp=lambda: request_mcp_reload(self.bus),
+            )
+        except Exception as e:
+            status = getattr(e, "status", 500)
+            message = getattr(e, "message", str(e))
+            if status >= 500:
+                self.logger.exception("MCP preset action '{}' failed", action or "list")
+            return self._error_response(status, message)
+        if action is None:
+            return self._json_response(payload)
+        return self._json_response(self._with_restart_state(payload, section="runtime"))

nanobot/webui/sidebar_state.py

@@ -38,6 +38,7 @@ def default_webui_sidebar_state() -> dict[str, Any]:
         "pinned_keys": [],
         "archived_keys": [],
         "title_overrides": {},
+        "project_name_overrides": {},
         "tags_by_key": {},
         "collapsed_groups": {},
         "view": {
@@ -136,6 +137,9 @@ def normalize_webui_sidebar_state(raw: Any) -> dict[str, Any]:
     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["project_name_overrides"] = _clean_title_overrides(
+        raw.get("project_name_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"))
@@ -190,4 +194,3 @@ def write_webui_sidebar_state(raw: dict[str, Any]) -> dict[str, Any]:
     finally:
         os.close(dir_fd)
     return state
-

nanobot/webui/transcript.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any, Callable, Mapping
+from urllib.parse import unquote, urlparse
 
 from loguru import logger
 
@@ -16,6 +18,82 @@ from nanobot.session.manager import SessionManager
 
 WEBUI_TRANSCRIPT_SCHEMA_VERSION = 3
 _MAX_TRANSCRIPT_FILE_BYTES = 8 * 1024 * 1024
+_MARKDOWN_LOCAL_IMAGE_RE = re.compile(
+    r"!\[([^\]]*)\]\((<[^>]+>|[^)\s]+)(\s+(?:\"[^\"]*\"|'[^']*'))?\)"
+)
+_INLINE_MARKDOWN_IMAGE_EXTS: frozenset[str] = frozenset({
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".gif",
+    ".svg",
+})
+_INLINE_MARKDOWN_VIDEO_EXTS: frozenset[str] = frozenset({
+    ".mp4",
+    ".mov",
+    ".webm",
+})
+_INLINE_MARKDOWN_MEDIA_EXTS = _INLINE_MARKDOWN_IMAGE_EXTS | _INLINE_MARKDOWN_VIDEO_EXTS
+_FILE_EDIT_TOOL_NAMES: frozenset[str] = frozenset({
+    "write_file",
+    "edit_file",
+    "apply_patch",
+})
+
+
+def rewrite_local_markdown_images(
+    text: str,
+    *,
+    workspace_path: Path,
+    sign_path: Callable[[Path], Mapping[str, Any] | None],
+) -> str:
+    """Rewrite markdown media paths inside the workspace to signed WebUI media URLs."""
+    if "![" not in text:
+        return text
+
+    def resolve_url(raw_url: str) -> str | None:
+        url = raw_url.strip()
+        if url.startswith("<") and url.endswith(">"):
+            url = url[1:-1].strip()
+        if not url or url.startswith(("/api/media/", "#")):
+            return None
+        parsed = urlparse(url)
+        if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment:
+            return None
+        path_text = unquote(url)
+        if Path(path_text).suffix.lower() not in _INLINE_MARKDOWN_MEDIA_EXTS:
+            return None
+        candidate = Path(path_text).expanduser()
+        if not candidate.is_absolute():
+            candidate = workspace_path / candidate
+        try:
+            resolved = candidate.resolve(strict=False)
+            resolved.relative_to(workspace_path)
+        except (OSError, ValueError):
+            return None
+        if not resolved.is_file():
+            return None
+        signed = sign_path(resolved)
+        return str(signed.get("url")) if signed and signed.get("url") else None
+
+    def replace(match: re.Match[str]) -> str:
+        signed_url = resolve_url(match.group(2))
+        if not signed_url:
+            return match.group(0)
+        title = match.group(3) or ""
+        return f"![{match.group(1)}]({signed_url}{title})"
+
+    return _MARKDOWN_LOCAL_IMAGE_RE.sub(replace, text)
+
+
+def _media_kind_from_name(name: str) -> str:
+    ext = Path(name).suffix.lower()
+    if ext in _INLINE_MARKDOWN_IMAGE_EXTS:
+        return "image"
+    if ext in _INLINE_MARKDOWN_VIDEO_EXTS:
+        return "video"
+    return "file"
 
 
 def webui_transcript_path(session_key: str) -> Path:
@@ -143,6 +221,19 @@ def _tool_event_key(event: dict[str, Any]) -> str:
     return _format_tool_call_trace(event) or json.dumps(event, sort_keys=True, ensure_ascii=False)
 
 
+def _tool_event_file_edit_key(event: dict[str, Any]) -> str | None:
+    call_id = event.get("call_id")
+    if not isinstance(call_id, str) or not call_id:
+        return None
+    name = event.get("name")
+    if not isinstance(name, str) or not name:
+        fn = event.get("function")
+        name = fn.get("name") if isinstance(fn, dict) else ""
+    if not isinstance(name, str) or name not in _FILE_EDIT_TOOL_NAMES:
+        return None
+    return f"{call_id}|{name}"
+
+
 def _merge_tool_events(previous: Any, incoming: list[dict[str, Any]]) -> list[dict[str, Any]]:
     if not isinstance(previous, list) or not previous:
         return incoming
@@ -165,6 +256,87 @@ def _merge_tool_events(previous: Any, incoming: list[dict[str, Any]]) -> list[di
     return merged
 
 
+def _file_edit_key(edit: dict[str, Any]) -> str:
+    call_id = str(edit.get("call_id") or "")
+    tool = str(edit.get("tool") or "")
+    if call_id:
+        return f"{call_id}|{tool}"
+    return f"{tool}|{edit.get('path') or ''}"
+
+
+def _message_has_file_edit_for_tool_event(
+    message: dict[str, Any],
+    event: dict[str, Any],
+) -> bool:
+    key = _tool_event_file_edit_key(event)
+    if not key:
+        return False
+    edits = message.get("fileEdits")
+    if not isinstance(edits, list):
+        return False
+    return any(isinstance(edit, dict) and _file_edit_key(edit) == key for edit in edits)
+
+
+def _filter_covered_file_edit_tool_events(
+    messages: list[dict[str, Any]],
+    events: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    if not events:
+        return events
+    return [
+        event
+        for event in events
+        if not any(_message_has_file_edit_for_tool_event(message, event) for message in messages)
+    ]
+
+
+def _strip_covered_file_edit_tool_hints(
+    message: dict[str, Any],
+    edits: list[dict[str, Any]],
+) -> dict[str, Any]:
+    incoming_keys = {
+        _file_edit_key(edit)
+        for edit in edits
+        if isinstance(edit, dict)
+    }
+    events = message.get("toolEvents")
+    if not incoming_keys or not isinstance(events, list):
+        return message
+
+    kept_events: list[dict[str, Any]] = []
+    removed_trace_lines: set[str] = set()
+    changed = False
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        key = _tool_event_file_edit_key(event)
+        if key and key in incoming_keys:
+            changed = True
+            removed_trace_lines.update(tool_trace_lines_from_events([event]))
+            continue
+        kept_events.append(event)
+    if not changed:
+        return message
+
+    raw_traces = message.get("traces")
+    if isinstance(raw_traces, list):
+        previous_traces = [trace for trace in raw_traces if isinstance(trace, str)]
+    else:
+        content = message.get("content")
+        previous_traces = [content] if isinstance(content, str) and content else []
+    next_traces = [trace for trace in previous_traces if trace not in removed_trace_lines]
+    next_message = {
+        **message,
+        "traces": next_traces,
+        "content": next_traces[-1] if next_traces else "",
+    }
+    if kept_events:
+        next_message["toolEvents"] = kept_events
+    else:
+        next_message.pop("toolEvents", None)
+    return next_message
+
+
 def _merge_unique_tool_trace_lines(
     previous_traces: list[str],
     lines: list[str],
@@ -286,6 +458,40 @@ def replay_transcript_to_ui_messages(
             return None
         return str(last.get("id"))
 
+    def demote_interrupted_assistant(segment: str) -> None:
+        nonlocal buffer_message_id, buffer_parts
+        for i in range(len(messages) - 1, -1, -1):
+            candidate = messages[i]
+            if candidate.get("role") == "user":
+                break
+            content = candidate.get("content")
+            if (
+                candidate.get("role") != "assistant"
+                or candidate.get("kind") == "trace"
+                or not candidate.get("isStreaming")
+                or not isinstance(content, str)
+                or not content.strip()
+                or candidate.get("media")
+            ):
+                continue
+            reasoning_parts = [
+                part
+                for part in (candidate.get("reasoning"), content)
+                if isinstance(part, str) and part.strip()
+            ]
+            messages[i] = {
+                **candidate,
+                "content": "",
+                "reasoning": "\n\n".join(reasoning_parts),
+                "reasoningStreaming": False,
+                "isStreaming": False,
+                "activitySegmentId": candidate.get("activitySegmentId") or segment,
+            }
+            if buffer_message_id == candidate.get("id"):
+                buffer_message_id = None
+                buffer_parts = []
+            return
+
     def close_reasoning(prev: list[dict[str, Any]]) -> None:
         for i in range(len(prev) - 1, -1, -1):
             if prev[i].get("reasoningStreaming"):
@@ -347,13 +553,6 @@ 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:
-        call_id = str(edit.get("call_id") or "")
-        tool = str(edit.get("tool") or "")
-        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]],
@@ -363,16 +562,23 @@ def replay_transcript_to_ui_messages(
             candidate = messages[i]
             if candidate.get("role") == "user":
                 break
-            if candidate.get("kind") != "trace" or not candidate.get("fileEdits"):
+            if candidate.get("kind") != "trace":
                 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
+            if isinstance(existing_edits, list):
+                for existing in existing_edits:
+                    if isinstance(existing, dict) and _file_edit_key(existing) in incoming_keys:
+                        return i
+            existing_tool_events = candidate.get("toolEvents")
+            if isinstance(existing_tool_events, list):
+                for event in existing_tool_events:
+                    if not isinstance(event, dict):
+                        continue
+                    key = _tool_event_file_edit_key(event)
+                    if key and key in incoming_keys:
+                        return i
         return None
 
     def upsert_file_edits(edits: list[dict[str, Any]], idx: int) -> None:
@@ -380,11 +586,16 @@ def replay_transcript_to_ui_messages(
         if not edits:
             return
         segment = active_file_edit_segment_id
+        if not segment:
+            segment = _new_activity_segment(activate=False)
+            active_file_edit_segment_id = segment
+        demote_interrupted_assistant(segment)
         target_index = find_file_edit_trace_index(segment, edits)
         if target_index is not None:
             last = messages[target_index]
             segment = str(last.get("activitySegmentId") or segment or _new_activity_segment(activate=False))
             active_file_edit_segment_id = segment
+            last = _strip_covered_file_edit_tool_hints(last, edits)
         else:
             if not segment:
                 segment = _new_activity_segment(activate=False)
@@ -458,6 +669,11 @@ def replay_transcript_to_ui_messages(
             cli_apps = rec.get("cli_apps")
             if isinstance(cli_apps, list) and cli_apps:
                 row["cliApps"] = [dict(app) for app in cli_apps if isinstance(app, dict)]
+            mcp_presets = rec.get("mcp_presets")
+            if isinstance(mcp_presets, list) and mcp_presets:
+                row["mcpPresets"] = [
+                    dict(preset) for preset in mcp_presets if isinstance(preset, dict)
+                ]
             messages.append(row)
             continue
 
@@ -558,12 +774,21 @@ def replay_transcript_to_ui_messages(
                 continue
             if kind in ("tool_hint", "progress"):
                 structured_events = _normalize_tool_events(rec.get("tool_events"))
-                structured = tool_trace_lines_from_events(rec.get("tool_events"))
+                visible_structured_events = _filter_covered_file_edit_tool_events(messages, structured_events)
+                structured = tool_trace_lines_from_events(visible_structured_events)
                 text = rec.get("text")
-                trace_lines = structured if structured else ([text] if isinstance(text, str) and text else [])
+                if structured:
+                    trace_lines = structured
+                elif structured_events:
+                    trace_lines = []
+                elif isinstance(text, str) and text:
+                    trace_lines = [text]
+                else:
+                    trace_lines = []
                 if not trace_lines:
                     continue
                 segment = _ensure_activity_segment()
+                demote_interrupted_assistant(segment)
                 last = messages[-1] if messages else None
                 if (
                     last
@@ -574,7 +799,7 @@ def replay_transcript_to_ui_messages(
                     prev_traces = list(last.get("traces") or [last.get("content")])
                     if structured:
                         merged_traces, added = _merge_unique_tool_trace_lines(prev_traces, structured)
-                        if not added and not structured_events:
+                        if not added and not visible_structured_events:
                             continue
                     else:
                         merged_traces = prev_traces + trace_lines
@@ -582,8 +807,8 @@ def replay_transcript_to_ui_messages(
                         **last,
                         "traces": merged_traces,
                         "content": merged_traces[-1],
-                        "toolEvents": _merge_tool_events(last.get("toolEvents"), structured_events)
-                        if structured_events
+                        "toolEvents": _merge_tool_events(last.get("toolEvents"), visible_structured_events)
+                        if visible_structured_events
                         else last.get("toolEvents"),
                         "activitySegmentId": last.get("activitySegmentId") or segment,
                     }
@@ -596,7 +821,7 @@ def replay_transcript_to_ui_messages(
                             "kind": "trace",
                             "content": trace_lines[-1],
                             "traces": trace_lines,
-                            **({"toolEvents": structured_events} if structured_events else {}),
+                            **({"toolEvents": visible_structured_events} if visible_structured_events else {}),
                             "activitySegmentId": segment,
                             "createdAt": _ts_base + idx,
                         },
@@ -612,11 +837,12 @@ def replay_transcript_to_ui_messages(
             if isinstance(media_urls, list):
                 for m in media_urls:
                     if isinstance(m, dict) and m.get("url"):
+                        name = str(m.get("name") or "")
                         media.append(
                             {
-                                "kind": "image",
+                                "kind": _media_kind_from_name(name),
                                 "url": str(m["url"]),
-                                "name": str(m.get("name") or ""),
+                                "name": name,
                             },
                         )
             extra: dict[str, Any] = {"content": content_s}

nanobot/webui/workspaces.py

@@ -0,0 +1,283 @@
+"""Persisted WebUI project workspace state."""
+
+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
+from nanobot.security.workspace_access import (
+    WORKSPACE_SCOPE_METADATA_KEY,
+    WorkspaceScope,
+    WorkspaceScopeError,
+    build_workspace_scope,
+    default_workspace_scope,
+    validate_workspace_scope_payload,
+)
+
+WEBUI_WORKSPACE_STATE_SCHEMA_VERSION = 1
+_MAX_STATE_FILE_BYTES = 128 * 1024
+_DEFAULT_ACCESS_MODES = {"default", "full"}
+_LEGACY_RESTRICTED_DEFAULT_ACCESS_MODE = "restricted"
+_WEBUI_SCOPE_CHANNEL = "websocket"
+
+
+def webui_workspace_state_path() -> Path:
+    return get_webui_dir() / "workspace-state.json"
+
+
+def default_webui_workspace_state() -> dict[str, Any]:
+    return {
+        "schema_version": WEBUI_WORKSPACE_STATE_SCHEMA_VERSION,
+        "default_access_mode": "default",
+        "updated_at": None,
+    }
+
+
+def normalize_webui_workspace_state(raw: Any) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        raw = {}
+    state = default_webui_workspace_state()
+    updated_at = raw.get("updated_at")
+    state["updated_at"] = updated_at if isinstance(updated_at, str) else None
+    default_access_mode = raw.get("default_access_mode")
+    if default_access_mode in _DEFAULT_ACCESS_MODES:
+        state["default_access_mode"] = default_access_mode
+    return state
+
+
+def read_webui_workspace_state() -> dict[str, Any]:
+    path = webui_workspace_state_path()
+    if not path.is_file():
+        return default_webui_workspace_state()
+    try:
+        if path.stat().st_size > _MAX_STATE_FILE_BYTES:
+            logger.warning("webui workspace state too large, ignoring: {}", path)
+            return default_webui_workspace_state()
+        with open(path, encoding="utf-8") as f:
+            raw = json.load(f)
+    except (OSError, json.JSONDecodeError) as e:
+        logger.warning("read webui workspace state failed {}: {}", path, e)
+        return default_webui_workspace_state()
+    return normalize_webui_workspace_state(raw)
+
+
+def write_webui_workspace_state(raw: dict[str, Any]) -> dict[str, Any]:
+    state = normalize_webui_workspace_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("workspace state is too large")
+
+    path = webui_workspace_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
+
+
+def read_webui_default_access_mode() -> str:
+    state = read_webui_workspace_state()
+    mode = state.get("default_access_mode")
+    return mode if mode in _DEFAULT_ACCESS_MODES else "default"
+
+
+def write_webui_default_access_mode(mode: str) -> bool:
+    if mode == _LEGACY_RESTRICTED_DEFAULT_ACCESS_MODE:
+        mode = "default"
+    if mode not in _DEFAULT_ACCESS_MODES:
+        raise ValueError("default access mode must be default or full")
+    state = read_webui_workspace_state()
+    changed = state.get("default_access_mode") != mode
+    if changed:
+        state["default_access_mode"] = mode
+        write_webui_workspace_state(state)
+    return changed
+
+
+def default_scope_for_webui(
+    default_workspace: Path,
+    default_restrict_to_workspace: bool,
+) -> WorkspaceScope:
+    mode = read_webui_default_access_mode()
+    if mode == "default":
+        return default_workspace_scope(
+            default_workspace,
+            default_restrict_to_workspace,
+            source_channel=_WEBUI_SCOPE_CHANNEL,
+        )
+    return build_workspace_scope(default_workspace, mode, source_channel=_WEBUI_SCOPE_CHANNEL)
+
+
+def workspaces_payload(
+    *,
+    default_workspace: Path,
+    default_restrict_to_workspace: bool,
+    controls_available: bool,
+) -> dict[str, Any]:
+    default_access_mode = read_webui_default_access_mode()
+    default_scope = (
+        default_workspace_scope(
+            default_workspace,
+            default_restrict_to_workspace,
+            source_channel=_WEBUI_SCOPE_CHANNEL,
+        )
+        if default_access_mode == "default"
+        else build_workspace_scope(default_workspace, default_access_mode, source_channel=_WEBUI_SCOPE_CHANNEL)
+    )
+    return {
+        "schema_version": WEBUI_WORKSPACE_STATE_SCHEMA_VERSION,
+        "default_access_mode": default_access_mode,
+        "default_scope": default_scope.payload(),
+        "controls": {
+            "can_change_project": controls_available,
+            "can_use_full_access": controls_available,
+        },
+    }
+
+
+class WebUIWorkspaceController:
+    """Own WebUI project scope persistence and validation."""
+
+    def __init__(
+        self,
+        *,
+        session_manager: Any | None,
+        default_workspace: Path,
+        default_restrict_to_workspace: bool,
+    ) -> None:
+        self._sessions = session_manager
+        self._default_workspace = default_workspace
+        self._default_restrict_to_workspace = default_restrict_to_workspace
+
+    def default_scope(self) -> WorkspaceScope:
+        return default_scope_for_webui(
+            self._default_workspace,
+            self._default_restrict_to_workspace,
+        )
+
+    def scope_for_session_key(self, session_key: str) -> WorkspaceScope:
+        if self._sessions is None:
+            return self.default_scope()
+        data = self._sessions.read_session_file(session_key)
+        metadata = data.get("metadata", {}) if isinstance(data, dict) else {}
+        if not isinstance(metadata, dict) or WORKSPACE_SCOPE_METADATA_KEY not in metadata:
+            return self.default_scope()
+        try:
+            return validate_workspace_scope_payload(
+                metadata.get(WORKSPACE_SCOPE_METADATA_KEY),
+                default_workspace=self._default_workspace,
+                default_restrict_to_workspace=self._default_restrict_to_workspace,
+                source_channel=_WEBUI_SCOPE_CHANNEL,
+            )
+        except WorkspaceScopeError:
+            return self.default_scope()
+
+    def payload(self, *, controls_available: bool) -> dict[str, Any]:
+        return workspaces_payload(
+            default_workspace=self._default_workspace,
+            default_restrict_to_workspace=self._default_restrict_to_workspace,
+            controls_available=controls_available,
+        )
+
+    def scope_from_envelope(
+        self,
+        envelope: dict[str, Any],
+        *,
+        session_key: str | None,
+        controls_available: bool,
+    ) -> WorkspaceScope:
+        raw = envelope.get(WORKSPACE_SCOPE_METADATA_KEY)
+        if raw is None and session_key:
+            scope = self.scope_for_session_key(session_key)
+        elif raw is None:
+            scope = self.default_scope()
+        else:
+            scope = validate_workspace_scope_payload(
+                raw,
+                default_workspace=self._default_workspace,
+                default_restrict_to_workspace=self._default_restrict_to_workspace,
+                source_channel=_WEBUI_SCOPE_CHANNEL,
+            )
+        if not controls_available and scope.metadata() != self.default_scope().metadata():
+            raise WorkspaceScopeError("workspace controls are localhost-only", status=403)
+        return scope
+
+    def scope_for_new_chat(
+        self,
+        envelope: dict[str, Any],
+        *,
+        controls_available: bool,
+    ) -> WorkspaceScope:
+        return self.scope_from_envelope(
+            envelope,
+            session_key=None,
+            controls_available=controls_available,
+        )
+
+    def scope_for_set_request(
+        self,
+        envelope: dict[str, Any],
+        *,
+        chat_id: str,
+        chat_running: bool,
+        controls_available: bool,
+    ) -> WorkspaceScope:
+        if chat_running:
+            raise WorkspaceScopeError("chat_running", status=409)
+        return self.scope_from_envelope(
+            envelope,
+            session_key=f"websocket:{chat_id}",
+            controls_available=controls_available,
+        )
+
+    def scope_for_message(
+        self,
+        envelope: dict[str, Any],
+        *,
+        chat_id: str,
+        chat_running: bool,
+        controls_available: bool,
+    ) -> WorkspaceScope:
+        scope = self.scope_from_envelope(
+            envelope,
+            session_key=f"websocket:{chat_id}",
+            controls_available=controls_available,
+        )
+        if (
+            WORKSPACE_SCOPE_METADATA_KEY in envelope
+            and chat_running
+            and scope.metadata() != self.scope_for_session_key(f"websocket:{chat_id}").metadata()
+        ):
+            raise WorkspaceScopeError("chat_running", status=409)
+        return scope
+
+    def persist_scope(self, chat_id: str, scope: WorkspaceScope) -> None:
+        if self._sessions is not None:
+            session = self._sessions.get_or_create(f"websocket:{chat_id}")
+            session.metadata["webui"] = True
+            session.metadata[WORKSPACE_SCOPE_METADATA_KEY] = scope.metadata()
+            self._sessions.save(session)

pyproject.toml

@@ -37,7 +37,7 @@ dependencies = [
     "rich>=14.0.0,<15.0.0",
     "croniter>=6.0.0,<7.0.0",
     "dingtalk-stream>=0.24.0,<1.0.0",
-    "python-telegram-bot[socks]>=22.6,<23.0",
+    "python-telegram-bot[socks,webhooks]>=22.6,<23.0",
     "lark-oapi>=1.5.0,<2.0.0",
     "socksio>=1.0.0,<2.0.0",
     "python-socketio>=5.16.0,<6.0.0",
@@ -82,6 +82,7 @@ msteams = [
 
 matrix = [
     "matrix-nio[e2e]>=0.25.2; sys_platform != 'win32'",
+    "aiohttp>=3.9.0,<4.0.0",
     "mistune>=3.0.0,<4.0.0",
     "nh3>=0.2.17,<1.0.0",
 ]

tests/agent/test_document_extraction_toggle.py

@@ -0,0 +1,169 @@
+import asyncio
+import base64
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.agent.loop import AgentLoop, TurnContext, TurnState
+from nanobot.bus.events import InboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.config.schema import ChannelsConfig
+from nanobot.providers.base import LLMResponse
+from nanobot.utils.document import reference_non_image_attachments
+
+
+def _make_loop(tmp_path: Path, channels_config: ChannelsConfig | None = None) -> AgentLoop:
+    provider = MagicMock()
+    provider.get_default_model.return_value = "test-model"
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(content="ok"))
+    return AgentLoop(
+        bus=MessageBus(),
+        provider=provider,
+        workspace=tmp_path,
+        model="test-model",
+        channels_config=channels_config,
+    )
+
+
+@pytest.mark.asyncio
+async def test_state_restore_extracts_documents_by_default(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    loop = _make_loop(tmp_path)
+    doc_path = tmp_path / "report.txt"
+    doc_path.write_text("Quarterly revenue is $5M", encoding="utf-8")
+    calls: list[tuple[str, list[str]]] = []
+
+    def fake_extract_documents(content: str, media: list[str]) -> tuple[str, list[str]]:
+        calls.append((content, media))
+        return f"{content}\n\n[File: report.txt]\nQuarterly revenue is $5M", []
+
+    monkeypatch.setattr("nanobot.agent.loop.extract_documents", fake_extract_documents)
+
+    ctx = TurnContext(
+        msg=InboundMessage(
+            channel="cli",
+            sender_id="u",
+            chat_id="c",
+            content="summarize",
+            media=[str(doc_path)],
+        ),
+        session_key="cli:c",
+        state=TurnState.RESTORE,
+        turn_id="turn-1",
+    )
+
+    assert await loop._state_restore(ctx) == "ok"
+
+    assert calls == [("summarize", [str(doc_path)])]
+    assert "Quarterly revenue" in ctx.msg.content
+    assert ctx.msg.media == []
+
+
+@pytest.mark.asyncio
+async def test_state_restore_references_documents_when_extraction_disabled(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    loop = _make_loop(tmp_path, ChannelsConfig(extract_document_text=False))
+    doc_path = tmp_path / "report.txt"
+    doc_path.write_text("Quarterly revenue is $5M", encoding="utf-8")
+
+    def fail_extract_documents(content: str, media: list[str]) -> tuple[str, list[str]]:
+        raise AssertionError("document extraction should be disabled")
+
+    monkeypatch.setattr("nanobot.agent.loop.extract_documents", fail_extract_documents)
+
+    ctx = TurnContext(
+        msg=InboundMessage(
+            channel="cli",
+            sender_id="u",
+            chat_id="c",
+            content="summarize",
+            media=[str(doc_path)],
+        ),
+        session_key="cli:c",
+        state=TurnState.RESTORE,
+        turn_id="turn-1",
+    )
+
+    assert await loop._state_restore(ctx) == "ok"
+
+    assert "Quarterly revenue" not in ctx.msg.content
+    assert f"[Attachment: {doc_path}]" in ctx.msg.content
+    assert ctx.msg.media == []
+
+
+@pytest.mark.asyncio
+async def test_pending_followup_references_documents_when_extraction_disabled(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    doc_path = tmp_path / "followup.txt"
+    doc_path.write_text("Do not inject this file body", encoding="utf-8")
+    captured_messages: list[list[dict]] = []
+    call_count = {"n": 0}
+
+    async def chat_with_retry(*, messages: list[dict], **kwargs: object) -> LLMResponse:
+        call_count["n"] += 1
+        captured_messages.append([dict(message) for message in messages])
+        return LLMResponse(content=f"answer-{call_count['n']}", tool_calls=[], usage={})
+
+    loop = _make_loop(tmp_path, ChannelsConfig(extract_document_text=False))
+    loop.provider.chat_with_retry = chat_with_retry
+    loop.tools.get_definitions = MagicMock(return_value=[])
+
+    def fail_extract_documents(content: str, media: list[str]) -> tuple[str, list[str]]:
+        raise AssertionError("document extraction should be disabled")
+
+    monkeypatch.setattr("nanobot.agent.loop.extract_documents", fail_extract_documents)
+
+    pending_queue: asyncio.Queue[InboundMessage] = asyncio.Queue()
+    await pending_queue.put(
+        InboundMessage(
+            channel="cli",
+            sender_id="u",
+            chat_id="c",
+            content="check this",
+            media=[str(doc_path)],
+        )
+    )
+
+    final_content, _, _, _, had_injections = await loop._run_agent_loop(
+        [{"role": "user", "content": "hello"}],
+        channel="cli",
+        chat_id="c",
+        pending_queue=pending_queue,
+    )
+
+    assert final_content == "answer-2"
+    assert had_injections is True
+    injected_user_content = [
+        message["content"]
+        for message in captured_messages[-1]
+        if message.get("role") == "user" and isinstance(message.get("content"), str)
+    ][-1]
+    assert "check this" in injected_user_content
+    assert f"[Attachment: {doc_path}]" in injected_user_content
+    assert "Do not inject this file body" not in injected_user_content
+
+
+def test_document_extraction_disabled_still_preserves_images(tmp_path: Path) -> None:
+    image_path = tmp_path / "chart.png"
+    image_path.write_bytes(
+        base64.b64decode(
+            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+yF9kAAAAASUVORK5CYII="
+        )
+    )
+    doc_path = tmp_path / "report.txt"
+    doc_path.write_text("manual extraction target", encoding="utf-8")
+
+    content, media = reference_non_image_attachments(
+        "review these",
+        [str(image_path), str(doc_path)],
+    )
+
+    assert media == [str(image_path)]
+    assert f"[Attachment: {doc_path}]" in content

tests/agent/test_evaluator.py

@@ -56,8 +56,38 @@ async def test_fallback_on_error() -> None:
     assert result is True
 
 
+@pytest.mark.asyncio
+async def test_fallback_can_fail_closed() -> None:
+    class FailingProvider(DummyProvider):
+        async def chat(self, *args, **kwargs) -> LLMResponse:
+            raise RuntimeError("provider down")
+
+    provider = FailingProvider([])
+    result = await evaluate_response(
+        "some response",
+        "some task",
+        provider,
+        "m",
+        default_notify=False,
+    )
+    assert result is False
+
+
 @pytest.mark.asyncio
 async def test_no_tool_call_fallback() -> None:
     provider = DummyProvider([LLMResponse(content="I think you should notify", tool_calls=[])])
     result = await evaluate_response("some response", "some task", provider, "m")
     assert result is True
+
+
+@pytest.mark.asyncio
+async def test_no_tool_call_can_fail_closed() -> None:
+    provider = DummyProvider([LLMResponse(content="I think you should notify", tool_calls=[])])
+    result = await evaluate_response(
+        "some response",
+        "some task",
+        provider,
+        "m",
+        default_notify=False,
+    )
+    assert result is False

tests/agent/test_heartbeat_service.py

@@ -1,336 +0,0 @@
-import asyncio
-
-import pytest
-
-from nanobot.heartbeat.service import HeartbeatService
-from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
-from nanobot.utils.llm_runtime import LLMRuntime
-
-
-class DummyProvider(LLMProvider):
-    def __init__(self, responses: list[LLMResponse]):
-        super().__init__()
-        self._responses = list(responses)
-        self.calls = 0
-        self.models: list[str | None] = []
-
-    async def chat(self, *args, **kwargs) -> LLMResponse:
-        self.calls += 1
-        self.models.append(kwargs.get("model"))
-        if self._responses:
-            return self._responses.pop(0)
-        return LLMResponse(content="", tool_calls=[])
-
-    def get_default_model(self) -> str:
-        return "test-model"
-
-
-@pytest.mark.asyncio
-async def test_start_is_idempotent(tmp_path) -> None:
-    provider = DummyProvider([])
-
-    service = HeartbeatService(
-        workspace=tmp_path,
-        provider=provider,
-        model="openai/gpt-4o-mini",
-        interval_s=9999,
-        enabled=True,
-    )
-
-    await service.start()
-    first_task = service._task
-    await service.start()
-
-    assert service._task is first_task
-
-    service.stop()
-    await asyncio.sleep(0)
-
-
-@pytest.mark.asyncio
-async def test_decide_returns_skip_when_no_tool_call(tmp_path) -> None:
-    provider = DummyProvider([LLMResponse(content="no tool call", tool_calls=[])])
-    service = HeartbeatService(
-        workspace=tmp_path,
-        provider=provider,
-        model="openai/gpt-4o-mini",
-    )
-
-    action, tasks = await service._decide("heartbeat content")
-    assert action == "skip"
-    assert tasks == ""
-
-
-@pytest.mark.asyncio
-async def test_trigger_now_executes_when_decision_is_run(tmp_path) -> None:
-    (tmp_path / "HEARTBEAT.md").write_text("- [ ] do thing", encoding="utf-8")
-
-    provider = DummyProvider([
-        LLMResponse(
-            content="",
-            tool_calls=[
-                ToolCallRequest(
-                    id="hb_1",
-                    name="heartbeat",
-                    arguments={"action": "run", "tasks": "check open tasks"},
-                )
-            ],
-        )
-    ])
-
-    called_with: list[str] = []
-
-    async def _on_execute(tasks: str) -> str:
-        called_with.append(tasks)
-        return "done"
-
-    service = HeartbeatService(
-        workspace=tmp_path,
-        provider=provider,
-        model="openai/gpt-4o-mini",
-        on_execute=_on_execute,
-    )
-
-    result = await service.trigger_now()
-    assert result == "done"
-    assert called_with == ["check open tasks"]
-
-
-@pytest.mark.asyncio
-async def test_trigger_now_returns_none_when_decision_is_skip(tmp_path) -> None:
-    (tmp_path / "HEARTBEAT.md").write_text("- [ ] do thing", encoding="utf-8")
-
-    provider = DummyProvider([
-        LLMResponse(
-            content="",
-            tool_calls=[
-                ToolCallRequest(
-                    id="hb_1",
-                    name="heartbeat",
-                    arguments={"action": "skip"},
-                )
-            ],
-        )
-    ])
-
-    async def _on_execute(tasks: str) -> str:
-        return tasks
-
-    service = HeartbeatService(
-        workspace=tmp_path,
-        provider=provider,
-        model="openai/gpt-4o-mini",
-        on_execute=_on_execute,
-    )
-
-    assert await service.trigger_now() is None
-
-
-@pytest.mark.asyncio
-async def test_tick_notifies_when_evaluator_says_yes(tmp_path, monkeypatch) -> None:
-    """Phase 1 run -> Phase 2 execute -> Phase 3 evaluate=notify -> on_notify called."""
-    (tmp_path / "HEARTBEAT.md").write_text("- [ ] check deployments", encoding="utf-8")
-
-    provider = DummyProvider([
-        LLMResponse(
-            content="",
-            tool_calls=[
-                ToolCallRequest(
-                    id="hb_1",
-                    name="heartbeat",
-                    arguments={"action": "run", "tasks": "check deployments"},
-                )
-            ],
-        ),
-    ])
-
-    executed: list[str] = []
-    notified: list[str] = []
-
-    async def _on_execute(tasks: str) -> str:
-        executed.append(tasks)
-        return "deployment failed on staging"
-
-    async def _on_notify(response: str) -> None:
-        notified.append(response)
-
-    service = HeartbeatService(
-        workspace=tmp_path,
-        provider=provider,
-        model="openai/gpt-4o-mini",
-        on_execute=_on_execute,
-        on_notify=_on_notify,
-    )
-
-    async def _eval_notify(*a, **kw):
-        return True
-
-    monkeypatch.setattr("nanobot.utils.evaluator.evaluate_response", _eval_notify)
-
-    await service._tick()
-    assert executed == ["check deployments"]
-    assert notified == ["deployment failed on staging"]
-
-
-@pytest.mark.asyncio
-async def test_tick_suppresses_when_evaluator_says_no(tmp_path, monkeypatch) -> None:
-    """Phase 1 run -> Phase 2 execute -> Phase 3 evaluate=silent -> on_notify NOT called."""
-    (tmp_path / "HEARTBEAT.md").write_text("- [ ] check status", encoding="utf-8")
-
-    provider = DummyProvider([
-        LLMResponse(
-            content="",
-            tool_calls=[
-                ToolCallRequest(
-                    id="hb_1",
-                    name="heartbeat",
-                    arguments={"action": "run", "tasks": "check status"},
-                )
-            ],
-        ),
-    ])
-
-    executed: list[str] = []
-    notified: list[str] = []
-
-    async def _on_execute(tasks: str) -> str:
-        executed.append(tasks)
-        return "everything is fine, no issues"
-
-    async def _on_notify(response: str) -> None:
-        notified.append(response)
-
-    service = HeartbeatService(
-        workspace=tmp_path,
-        provider=provider,
-        model="openai/gpt-4o-mini",
-        on_execute=_on_execute,
-        on_notify=_on_notify,
-    )
-
-    async def _eval_silent(*a, **kw):
-        return False
-
-    monkeypatch.setattr("nanobot.utils.evaluator.evaluate_response", _eval_silent)
-
-    await service._tick()
-    assert executed == ["check status"]
-    assert notified == []
-
-
-def test_tick_uses_runtime_provider_and_model(tmp_path, monkeypatch) -> None:
-    """Preset changes must apply to heartbeat decision and post-run evaluation."""
-    (tmp_path / "HEARTBEAT.md").write_text("- [ ] check runtime model", encoding="utf-8")
-
-    runtime_provider = DummyProvider([
-        LLMResponse(
-            content="",
-            tool_calls=[
-                ToolCallRequest(
-                    id="hb_1",
-                    name="heartbeat",
-                    arguments={"action": "run", "tasks": "check runtime model"},
-                )
-            ],
-        ),
-    ])
-    runtime_model = "openai/gpt-4.1"
-
-    executed: list[str] = []
-    evaluated: list[tuple[LLMProvider, str]] = []
-
-    async def _on_execute(tasks: str) -> str:
-        executed.append(tasks)
-        return "runtime model produced a user-facing update"
-
-    async def _eval_capture(response, tasks, provider, model):
-        evaluated.append((provider, model))
-        return False
-
-    service = HeartbeatService(
-        workspace=tmp_path,
-        llm_runtime=lambda: LLMRuntime(runtime_provider, runtime_model),
-        on_execute=_on_execute,
-    )
-
-    monkeypatch.setattr("nanobot.utils.evaluator.evaluate_response", _eval_capture)
-
-    asyncio.run(service._tick())
-
-    assert runtime_provider.calls == 1
-    assert runtime_provider.models == [runtime_model]
-    assert executed == ["check runtime model"]
-    assert evaluated == [(runtime_provider, runtime_model)]
-
-
-@pytest.mark.asyncio
-async def test_decide_retries_transient_error_then_succeeds(tmp_path, monkeypatch) -> None:
-    provider = DummyProvider([
-        LLMResponse(content="429 rate limit", finish_reason="error"),
-        LLMResponse(
-            content="",
-            tool_calls=[
-                ToolCallRequest(
-                    id="hb_1",
-                    name="heartbeat",
-                    arguments={"action": "run", "tasks": "check open tasks"},
-                )
-            ],
-        ),
-    ])
-
-    delays: list[int] = []
-
-    async def _fake_sleep(delay: int) -> None:
-        delays.append(delay)
-
-    monkeypatch.setattr(asyncio, "sleep", _fake_sleep)
-
-    service = HeartbeatService(
-        workspace=tmp_path,
-        provider=provider,
-        model="openai/gpt-4o-mini",
-    )
-
-    action, tasks = await service._decide("heartbeat content")
-
-    assert action == "run"
-    assert tasks == "check open tasks"
-    assert provider.calls == 2
-    assert delays == [1]
-
-
-@pytest.mark.asyncio
-async def test_decide_prompt_includes_current_time(tmp_path) -> None:
-    """Phase 1 user prompt must contain current time so the LLM can judge task urgency."""
-
-    captured_messages: list[dict] = []
-
-    class CapturingProvider(LLMProvider):
-        async def chat(self, *, messages=None, **kwargs) -> LLMResponse:
-            if messages:
-                captured_messages.extend(messages)
-            return LLMResponse(
-                content="",
-                tool_calls=[
-                    ToolCallRequest(
-                        id="hb_1", name="heartbeat",
-                        arguments={"action": "skip"},
-                    )
-                ],
-            )
-
-        def get_default_model(self) -> str:
-            return "test-model"
-
-    service = HeartbeatService(
-        workspace=tmp_path,
-        provider=CapturingProvider(),
-        model="test-model",
-    )
-
-    await service._decide("- [ ] check servers at 10:00 UTC")
-
-    user_msg = captured_messages[1]
-    assert user_msg["role"] == "user"
-    assert "Current Time:" in user_msg["content"]

tests/agent/test_loop_direct_websocket_status.py

@@ -0,0 +1,91 @@
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.agent.loop import AgentLoop
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.providers.base import GenerationSettings, LLMResponse
+
+
+def _make_loop(tmp_path):
+    bus = MessageBus()
+    provider = MagicMock()
+    provider.get_default_model.return_value = "test-model"
+    provider.generation = GenerationSettings(max_tokens=0)
+    provider.estimate_prompt_tokens.return_value = (0, "test-counter")
+    response = LLMResponse(content="done", tool_calls=[])
+    provider.chat_with_retry = AsyncMock(return_value=response)
+    provider.chat_stream_with_retry = AsyncMock(return_value=response)
+
+    loop = AgentLoop(
+        bus=bus,
+        provider=provider,
+        workspace=tmp_path,
+        model="test-model",
+    )
+    loop.tools.get_definitions = MagicMock(return_value=[])
+    return loop
+
+
+@pytest.mark.asyncio
+async def test_process_direct_websocket_clears_run_status(tmp_path) -> None:
+    loop = _make_loop(tmp_path)
+
+    response = await loop.process_direct(
+        "deliver reminder",
+        session_key="cron:reminder-1",
+        channel="websocket",
+        chat_id="chat-1",
+    )
+
+    assert response is not None
+    assert response.content == "done"
+
+    events = []
+    while loop.bus.outbound_size:
+        events.append(await loop.bus.consume_outbound())
+
+    statuses = [
+        event.metadata
+        for event in events
+        if event.metadata.get("_goal_status") is True
+    ]
+    assert [status["goal_status"] for status in statuses] == ["running", "idle"]
+    assert isinstance(statuses[0].get("started_at"), float)
+    assert "started_at" not in statuses[1]
+
+
+@pytest.mark.asyncio
+async def test_process_direct_reuses_existing_session_lock(tmp_path) -> None:
+    loop = _make_loop(tmp_path)
+    loop._connect_mcp = AsyncMock()
+    session_key = "api:fixed"
+    lock = loop._session_locks.setdefault(session_key, asyncio.Lock())
+    await lock.acquire()
+    entered = asyncio.Event()
+
+    async def _process_message(msg, **_kwargs):
+        entered.set()
+        return OutboundMessage(channel=msg.channel, chat_id=msg.chat_id, content=msg.content)
+
+    loop._process_message = _process_message
+    task = asyncio.create_task(loop.process_direct("direct", session_key=session_key))
+    try:
+        await asyncio.sleep(0)
+        assert not entered.is_set()
+
+        lock.release()
+        response = await asyncio.wait_for(task, timeout=1.0)
+
+        assert entered.is_set()
+        assert response is not None
+        assert response.content == "direct"
+    finally:
+        if lock.locked():
+            lock.release()
+        if not task.done():
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await task

tests/agent/test_loop_save_turn.py

@@ -17,6 +17,7 @@ from nanobot.session.webui_turns import (
     WEBUI_SESSION_METADATA_KEY,
     WEBUI_TITLE_METADATA_KEY,
     WebuiTurnCoordinator,
+    clean_generated_title,
     maybe_generate_webui_title,
 )
 from nanobot.utils.llm_runtime import LLMRuntime
@@ -53,6 +54,11 @@ def test_agent_loop_llm_runtime_reflects_current_provider_and_model(tmp_path: Pa
     assert runtime.model == "next-model"
 
 
+def test_clean_generated_title_strips_reasoning_tags() -> None:
+    assert clean_generated_title("<think>reasoning</think> WebUI polish") == "WebUI polish"
+    assert clean_generated_title("Title: <think> The user said hello") == ""
+
+
 @pytest.mark.asyncio
 async def test_generate_webui_title_only_for_marked_webui_sessions(tmp_path: Path) -> None:
     loop = _make_full_loop(tmp_path)
@@ -602,17 +608,17 @@ async def test_process_message_uses_explicit_session_metadata_for_goal_context(
     chat_session = loop.sessions.get_or_create("websocket:chat-with-goal")
     chat_session.metadata[GOAL_STATE_KEY] = {
         "status": "active",
-        "objective": "This chat goal must not leak into heartbeat.",
+        "objective": "This chat goal must not leak into system.",
     }
     loop.sessions.save(chat_session)
-    system_session = loop.sessions.get_or_create("heartbeat")
+    system_session = loop.sessions.get_or_create("system")
     system_session.metadata = {}
     loop.sessions.save(system_session)
 
     loop.context.build_messages = MagicMock(  # type: ignore[method-assign]
         return_value=[
             {"role": "system", "content": "system"},
-            {"role": "user", "content": "runtime + heartbeat"},
+            {"role": "user", "content": "runtime + system"},
         ]
     )
     loop._run_agent_loop = AsyncMock(return_value=(  # type: ignore[method-assign]
@@ -620,7 +626,7 @@ async def test_process_message_uses_explicit_session_metadata_for_goal_context(
         [],
         [
             {"role": "system", "content": "system"},
-            {"role": "user", "content": "runtime + heartbeat"},
+            {"role": "user", "content": "runtime + system"},
             {"role": "assistant", "content": "ok"},
         ],
         "stop",
@@ -630,11 +636,11 @@ async def test_process_message_uses_explicit_session_metadata_for_goal_context(
     result = await loop._process_message(
         InboundMessage(
             channel="websocket",
-            sender_id="heartbeat",
+            sender_id="system",
             chat_id="chat-with-goal",
-            content="heartbeat work",
+            content="system work",
         ),
-        session_key="heartbeat",
+        session_key="system",
     )
 
     assert result is not None

tests/agent/test_mcp_connection.py

@@ -2,12 +2,39 @@
 
 from __future__ import annotations
 
+import asyncio
+from contextlib import AsyncExitStack
+from typing import Any
 from unittest.mock import MagicMock
 
 import pytest
 
 from nanobot.agent.loop import AgentLoop
+from nanobot.agent.tools import mcp as mcp_runtime
+from nanobot.agent.tools.base import Tool
 from nanobot.bus.queue import MessageBus
+from nanobot.config.loader import load_config, save_config
+from nanobot.config.schema import MCPServerConfig
+
+
+class _FakeMcpTool(Tool):
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str:
+        return "fake MCP tool"
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {"type": "object", "properties": {}}
+
+    async def execute(self, **_kwargs: Any) -> str:
+        return "ok"
 
 
 def _make_loop(tmp_path, *, mcp_servers: dict | None = None) -> AgentLoop:
@@ -42,3 +69,152 @@ async def test_connect_mcp_retries_when_no_servers_connect(tmp_path, monkeypatch
     assert attempts == 2
     assert loop._mcp_connected is False
     assert loop._mcp_stacks == {}
+
+
+@pytest.mark.asyncio
+async def test_reload_mcp_servers_adds_and_removes_tools_without_restart(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)
+    config = load_config()
+    config.tools.mcp_servers["browserbase"] = MCPServerConfig(
+        type="stdio",
+        command="browserbase-mcp",
+    )
+    save_config(config)
+
+    closed: list[str] = []
+
+    async def _mark_closed(name: str) -> None:
+        closed.append(name)
+
+    async def _fake_connect(servers, registry):
+        stacks = {}
+        for name in servers:
+            registry.register(_FakeMcpTool(f"mcp_{name}_navigate"))
+            stack = AsyncExitStack()
+            await stack.__aenter__()
+            stack.push_async_callback(_mark_closed, name)
+            stacks[name] = stack
+        return stacks
+
+    monkeypatch.setattr("nanobot.agent.tools.mcp.connect_mcp_servers", _fake_connect)
+    loop = _make_loop(tmp_path, mcp_servers={})
+
+    added = await mcp_runtime.reload_servers(loop, loop.tools)
+
+    assert added["ok"] is True
+    assert added["added"] == ["browserbase"]
+    assert loop.tools.has("mcp_browserbase_navigate")
+    assert "browserbase" in loop._mcp_stacks
+
+    config = load_config()
+    del config.tools.mcp_servers["browserbase"]
+    save_config(config)
+
+    removed = await mcp_runtime.reload_servers(loop, loop.tools)
+
+    assert removed["ok"] is True
+    assert removed["removed"] == ["browserbase"]
+    assert not loop.tools.has("mcp_browserbase_navigate")
+    assert "browserbase" not in loop._mcp_stacks
+    assert closed == ["browserbase"]
+
+
+@pytest.mark.asyncio
+async def test_request_mcp_reload_reaches_runtime_control_without_restart(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)
+    config = load_config()
+    config.tools.mcp_servers["browserbase"] = MCPServerConfig(
+        type="stdio",
+        command="browserbase-mcp",
+    )
+    save_config(config)
+
+    closed: list[str] = []
+
+    async def _mark_closed(name: str) -> None:
+        closed.append(name)
+
+    async def _fake_connect(servers, registry):
+        stacks = {}
+        for name in servers:
+            registry.register(_FakeMcpTool(f"mcp_{name}_navigate"))
+            stack = AsyncExitStack()
+            await stack.__aenter__()
+            stack.push_async_callback(_mark_closed, name)
+            stacks[name] = stack
+        return stacks
+
+    monkeypatch.setattr("nanobot.agent.tools.mcp.connect_mcp_servers", _fake_connect)
+    loop = _make_loop(tmp_path, mcp_servers={})
+
+    async def _handle_one_runtime_control() -> None:
+        msg = await loop.bus.consume_inbound()
+        handled = await mcp_runtime.handle_runtime_control(loop, msg, loop.tools)
+        assert handled is True
+
+    consumer = asyncio.create_task(_handle_one_runtime_control())
+    result = await mcp_runtime.request_mcp_reload(loop.bus, timeout=2.0)
+    await consumer
+
+    assert result["ok"] is True
+    assert result["added"] == ["browserbase"]
+    assert result["requires_restart"] is False
+    assert loop.tools.has("mcp_browserbase_navigate")
+
+    config = load_config()
+    del config.tools.mcp_servers["browserbase"]
+    save_config(config)
+
+    consumer = asyncio.create_task(_handle_one_runtime_control())
+    result = await mcp_runtime.request_mcp_reload(loop.bus, timeout=2.0)
+    await consumer
+
+    assert result["ok"] is True
+    assert result["removed"] == ["browserbase"]
+    assert result["requires_restart"] is False
+    assert not loop.tools.has("mcp_browserbase_navigate")
+    assert closed == ["browserbase"]
+
+
+@pytest.mark.asyncio
+async def test_reload_mcp_servers_retries_configured_server_without_live_stack(
+    tmp_path,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    config_path = tmp_path / "config.json"
+    monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)
+    config = load_config()
+    config.tools.mcp_servers["browserbase"] = MCPServerConfig(
+        type="stdio",
+        command="browserbase-mcp",
+    )
+    save_config(config)
+
+    async def _fake_connect(servers, registry):
+        stacks = {}
+        for name in servers:
+            registry.register(_FakeMcpTool(f"mcp_{name}_navigate"))
+            stack = AsyncExitStack()
+            await stack.__aenter__()
+            stacks[name] = stack
+        return stacks
+
+    monkeypatch.setattr("nanobot.agent.tools.mcp.connect_mcp_servers", _fake_connect)
+    loop = _make_loop(tmp_path, mcp_servers={"browserbase": config.tools.mcp_servers["browserbase"]})
+
+    result = await mcp_runtime.reload_servers(loop, loop.tools)
+
+    assert result["ok"] is True
+    assert result["added"] == []
+    assert result["changed"] == []
+    assert result["retried"] == ["browserbase"]
+    assert loop.tools.has("mcp_browserbase_navigate")
+    await loop.close_mcp()

tests/agent/test_runner_errors.py

@@ -78,6 +78,31 @@ async def test_llm_error_not_appended_to_session_messages():
     assert assistant_msgs[-1]["content"] == _PERSISTED_MODEL_ERROR_PLACEHOLDER
 
 
+@pytest.mark.asyncio
+async def test_llm_arrearage_error_surfaces_clear_message():
+    """Arrearage errors yield a clear user-facing message, not a raw dump (#3006)."""
+    from nanobot.agent.runner import AgentRunSpec, AgentRunner, _ARREARAGE_ERROR_MESSAGE
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="HTTP 402 insufficient_quota", finish_reason="error", error_status_code=402,
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "hello"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=5,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+    ))
+
+    assert result.stop_reason == "error"
+    assert result.final_content == _ARREARAGE_ERROR_MESSAGE
+
+
 @pytest.mark.asyncio
 async def test_runner_tool_error_sets_final_content():
     from nanobot.agent.runner import AgentRunSpec, AgentRunner

tests/agent/test_runner_fallback.py

@@ -241,7 +241,7 @@ def test_inline_fallback_reasoning_effort_does_not_inherit_primary() -> None:
     signature = provider_signature(config)
     fallback_signatures = signature[-1]
 
-    assert fallback_signatures[0][11] is None
+    assert fallback_signatures[0][12] is None
 
 
 # -- FallbackProvider tests --

tests/agent/test_runner_goal_continue.py

@@ -0,0 +1,211 @@
+"""Tests for sustained-goal continuation in AgentRunner.
+
+When a goal_active_predicate returns True, the runner must not exit with
+stop_reason="completed" after a plain-text final response. Instead it should
+inject a continuation message and keep looping (similar to mid-turn injection).
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.config.schema import AgentDefaults
+from nanobot.providers.base import LLMProvider, LLMResponse
+
+_MAX_TOOL_RESULT_CHARS = AgentDefaults().max_tool_result_chars
+
+
+@pytest.mark.asyncio
+async def test_runner_exits_normally_without_predicate():
+    """Baseline: no predicate, runner exits with completed on final text."""
+    from nanobot.agent.runner import AgentRunner, AgentRunSpec
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="all done", tool_calls=[], usage={},
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=2,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+    ))
+
+    assert result.stop_reason == "completed"
+    assert result.final_content == "all done"
+
+
+@pytest.mark.asyncio
+async def test_runner_exits_normally_with_inactive_goal():
+    """Predicate returns False, runner should exit normally."""
+    from nanobot.agent.runner import AgentRunner, AgentRunSpec
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="all done", tool_calls=[], usage={},
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=2,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        goal_active_predicate=lambda: False,
+    ))
+
+    assert result.stop_reason == "completed"
+    assert result.final_content == "all done"
+
+
+@pytest.mark.asyncio
+async def test_runner_forces_continue_when_goal_active():
+    """Predicate returns True on final text → runner injects continuation and loops.
+
+    We set max_iterations=3 and let the provider return final text every time.
+    Without the fix this would exit on the first iteration with stop_reason
+    "completed". With the fix the runner is forced to continue until
+    max_iterations is hit.
+    """
+    from nanobot.agent.runner import AgentRunner, AgentRunSpec
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="still working", tool_calls=[], usage={},
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=3,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        goal_active_predicate=lambda: True,
+    ))
+
+    # Because the predicate keeps returning True, the runner should never
+    # naturally complete. It loops until max_iterations is exhausted.
+    assert result.stop_reason == "max_iterations"
+    # The injected continuation message should be present in the message list.
+    user_msgs = [m for m in result.messages if m.get("role") == "user"]
+    assert any("active sustained goal" in str(m.get("content", "")) for m in user_msgs)
+
+
+@pytest.mark.asyncio
+async def test_runner_respects_max_iterations_even_with_active_goal():
+    """A single iteration with active goal still hits max_iterations."""
+    from nanobot.agent.runner import AgentRunner, AgentRunSpec
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="still working", tool_calls=[], usage={},
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=1,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        goal_active_predicate=lambda: True,
+    ))
+
+    assert result.stop_reason == "max_iterations"
+
+
+@pytest.mark.asyncio
+async def test_runner_goal_continue_not_limited_by_injection_cycle_cap():
+    """Synthetic goal continuation should be governed by max_iterations."""
+    from nanobot.agent.runner import _MAX_INJECTION_CYCLES, AgentRunner, AgentRunSpec
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="still working", tool_calls=[], usage={},
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+    max_iterations = _MAX_INJECTION_CYCLES + 3
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=max_iterations,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        goal_active_predicate=lambda: True,
+    ))
+
+    assert result.stop_reason == "max_iterations"
+    assert provider.chat_with_retry.await_count == max_iterations
+
+
+@pytest.mark.asyncio
+async def test_runner_does_not_force_continue_on_error():
+    """Even with active goal, an LLM error should exit with stop_reason="error"."""
+    from nanobot.agent.runner import AgentRunner, AgentRunSpec
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content=None, tool_calls=[], usage={},
+        finish_reason="error",
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=2,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        goal_active_predicate=lambda: True,
+    ))
+
+    assert result.stop_reason == "error"
+
+
+@pytest.mark.asyncio
+async def test_runner_uses_custom_goal_continue_message():
+    """Custom goal_continue_message should be injected instead of the default."""
+    from nanobot.agent.runner import AgentRunner, AgentRunSpec
+
+    provider = MagicMock(spec=LLMProvider)
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(
+        content="still working", tool_calls=[], usage={},
+    ))
+    tools = MagicMock()
+    tools.get_definitions.return_value = []
+
+    custom_msg = "CUSTOM_CONTINUE_PLEASE"
+
+    runner = AgentRunner(provider)
+    result = await runner.run(AgentRunSpec(
+        initial_messages=[{"role": "user", "content": "do task"}],
+        tools=tools,
+        model="test-model",
+        max_iterations=2,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        goal_active_predicate=lambda: True,
+        goal_continue_message=custom_msg,
+    ))
+
+    user_msgs = [m for m in result.messages if m.get("role") == "user"]
+    assert any(custom_msg in str(m.get("content", "")) for m in user_msgs)

tests/agent/test_runner_governance.py

@@ -105,6 +105,60 @@ def test_snip_history_drops_orphaned_tool_results_from_trimmed_slice(monkeypatch
     assert trimmed[0]["role"] == "system"
     non_system = [m for m in trimmed if m["role"] != "system"]
     assert non_system[0]["role"] == "user", f"Expected user after system, got {non_system[0]['role']}"
+
+
+def test_snip_history_reserves_budget_for_tool_definitions(monkeypatch):
+    from nanobot.agent.runner import AgentRunSpec, AgentRunner
+
+    provider = MagicMock()
+    tools = MagicMock()
+    tools.get_definitions.return_value = [{"type": "function", "function": {"name": "large_tool"}}]
+    runner = AgentRunner(provider)
+    messages = [
+        {"role": "system", "content": "system"},
+        {"role": "user", "content": "old user"},
+        {"role": "assistant", "content": "old assistant"},
+        {"role": "user", "content": "recent one"},
+        {"role": "assistant", "content": "recent answer"},
+        {"role": "user", "content": "recent two"},
+    ]
+    spec = AgentRunSpec(
+        initial_messages=messages,
+        tools=tools,
+        model="test-model",
+        max_iterations=1,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+        context_window_tokens=2000,
+        context_block_limit=500,
+    )
+
+    def _estimate(_provider, _model, estimate_messages, estimate_tools):
+        if estimate_messages == messages:
+            return 1000, None
+        assert estimate_messages == [{"role": "system", "content": "system"}]
+        assert estimate_tools == tools.get_definitions.return_value
+        return 350, None
+
+    monkeypatch.setattr("nanobot.agent.runner.estimate_prompt_tokens_chain", _estimate)
+    token_sizes = {
+        "system": 50,
+        "old user": 200,
+        "old assistant": 200,
+        "recent one": 200,
+        "recent answer": 200,
+        "recent two": 200,
+    }
+    monkeypatch.setattr(
+        "nanobot.agent.runner.estimate_message_tokens",
+        lambda msg: token_sizes.get(str(msg.get("content")), 40),
+    )
+
+    trimmed = runner._snip_history(spec, messages)
+
+    contents = [message.get("content") for message in trimmed]
+    assert contents == ["system", "recent two"]
+
+
 async def test_backfill_missing_tool_results_inserts_error():
     """Orphaned tool_use (no matching tool_result) should get a synthetic error."""
     from nanobot.agent.runner import AgentRunner, _BACKFILL_CONTENT

tests/agent/test_runner_injections.py

@@ -554,6 +554,42 @@ async def test_pending_queue_cleanup_on_dispatch(tmp_path):
     assert msg.session_key not in loop._pending_queues
 
 
+@pytest.mark.asyncio
+async def test_waiting_dispatch_does_not_replace_active_pending_queue(tmp_path):
+    """A queued dispatch must not steal the active task's injection queue."""
+    from nanobot.bus.events import InboundMessage
+
+    loop = _make_loop(tmp_path)
+    session_key = "cli:c"
+    lock = loop._session_locks.setdefault(session_key, asyncio.Lock())
+    await lock.acquire()
+    active_pending = asyncio.Queue(maxsize=1)
+    loop._pending_queues[session_key] = active_pending
+
+    waiting_at_lock = asyncio.Event()
+    original_acquire = asyncio.Lock.acquire
+
+    async def _patched_acquire(self, *args, **kwargs):
+        if self is lock:
+            waiting_at_lock.set()
+        return await original_acquire(self, *args, **kwargs)
+
+    with patch.object(asyncio.Lock, "acquire", _patched_acquire):
+        waiting = asyncio.create_task(
+            loop._dispatch(
+                InboundMessage(channel="cli", sender_id="u", chat_id="c", content="queued")
+            )
+        )
+        await asyncio.wait_for(waiting_at_lock.wait(), timeout=2.0)
+
+    assert loop._pending_queues[session_key] is active_pending
+
+    waiting.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await waiting
+    lock.release()
+
+
 @pytest.mark.asyncio
 async def test_followup_routed_to_pending_queue(tmp_path):
     """Unified-session follow-ups should route into the active pending queue."""

tests/agent/test_runtime_refresh.py

@@ -4,7 +4,10 @@ from unittest.mock import MagicMock
 
 from nanobot.agent.loop import AgentLoop
 from nanobot.bus.queue import MessageBus
-from nanobot.providers.factory import ProviderSnapshot
+from nanobot.config.loader import save_config
+from nanobot.config.schema import Config
+from nanobot.providers.factory import ProviderSnapshot, load_provider_snapshot
+from nanobot.webui.settings_api import update_agent_settings
 
 
 def _provider(default_model: str, max_tokens: int = 123) -> MagicMock:
@@ -72,3 +75,30 @@ def test_llm_runtime_refreshes_provider_snapshot(tmp_path: Path) -> None:
     assert runtime.model == "new-model"
     assert loop.provider is new_provider
     assert loop.runner.provider is new_provider
+
+
+def test_settings_context_window_refreshes_runtime_state(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    config_path = tmp_path / "config.json"
+    config = Config()
+    config.agents.defaults.workspace = str(tmp_path / "workspace")
+    config.agents.defaults.model = "openai/gpt-4o"
+    config.agents.defaults.provider = "openai"
+    config.agents.defaults.context_window_tokens = 65_536
+    config.providers.openai.api_key = "sk-test"
+    save_config(config, config_path)
+    monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)
+
+    def loader(*, preset_name: str | None = None) -> ProviderSnapshot:
+        return load_provider_snapshot(config_path, preset_name=preset_name)
+
+    loop = AgentLoop.from_config(config, provider_snapshot_loader=loader)
+
+    payload = update_agent_settings({"context_window_tokens": ["262144"]})
+    loop._refresh_provider_snapshot()
+
+    assert payload["requires_restart"] is False
+    assert loop.context_window_tokens == 262_144
+    assert loop.consolidator.context_window_tokens == 262_144

tests/agent/test_session_manager_history.py

@@ -43,6 +43,32 @@ def test_list_sessions_includes_metadata_title(tmp_path):
     assert rows[0]["title"] == "自动生成标题"
 
 
+def test_list_sessions_hides_generated_think_title(tmp_path):
+    manager = SessionManager(tmp_path)
+    session = manager.get_or_create("websocket:chat-think-title")
+    session.metadata["title"] = "<think> The user said hello and assistant replied"
+    session.add_message("user", "hello")
+    manager.save(session)
+
+    rows = manager.list_sessions()
+
+    assert rows[0]["key"] == "websocket:chat-think-title"
+    assert rows[0]["title"] == ""
+    assert rows[0]["preview"] == "hello"
+
+
+def test_list_sessions_keeps_user_edited_think_title(tmp_path):
+    manager = SessionManager(tmp_path)
+    session = manager.get_or_create("websocket:chat-user-title")
+    session.metadata["title"] = "<think> literally discussed"
+    session.metadata["title_user_edited"] = True
+    manager.save(session)
+
+    rows = manager.list_sessions()
+
+    assert rows[0]["title"] == "<think> literally discussed"
+
+
 def test_list_sessions_includes_user_preview(tmp_path):
     manager = SessionManager(tmp_path)
     session = manager.get_or_create("websocket:chat-preview")
@@ -56,6 +82,20 @@ def test_list_sessions_includes_user_preview(tmp_path):
     assert rows[0]["preview"] == "帮我总结一下 OpenAI 的最新硬件计划"
 
 
+def test_list_sessions_bounds_preview_scan(tmp_path):
+    manager = SessionManager(tmp_path)
+    session = manager.get_or_create("websocket:chat-long-preview")
+    for index in range(220):
+        session.add_message("assistant", f"assistant trace {index}")
+    session.add_message("user", "this should not force a full sidebar scan")
+    manager.save(session)
+
+    rows = manager.list_sessions()
+
+    assert rows[0]["key"] == "websocket:chat-long-preview"
+    assert rows[0]["preview"] == "assistant trace 0"
+
+
 # --- Original regression test (from PR 2075) ---
 
 def test_get_history_drops_orphan_tool_results_when_window_cuts_tool_calls():

tests/agent/test_unified_session.py

@@ -474,6 +474,32 @@ class TestStopCommandWithUnifiedSession:
         assert task.cancelled() or task.done()
         assert "Stopped 1 task" in result.content
 
+    @pytest.mark.asyncio
+    async def test_stop_command_uses_effective_key_without_session_override(self, tmp_path: Path):
+        """Priority /stop must cancel the unified session even before dispatch rewrites the message."""
+        from nanobot.agent.loop import UNIFIED_SESSION_KEY
+        from nanobot.command.builtin import cmd_stop
+
+        loop = _make_loop(tmp_path, unified_session=True)
+
+        async def long_running():
+            await asyncio.sleep(10)
+
+        task = asyncio.create_task(long_running())
+        loop._active_tasks[UNIFIED_SESSION_KEY] = [task]
+        msg = InboundMessage(
+            channel="telegram",
+            chat_id="123456",
+            sender_id="user1",
+            content="/stop",
+        )
+        ctx = CommandContext(msg=msg, session=None, key=UNIFIED_SESSION_KEY, raw="/stop", loop=loop)
+
+        result = await cmd_stop(ctx)
+
+        assert task.cancelled() or task.done()
+        assert "Stopped 1 task" in result.content
+
     @pytest.mark.asyncio
     async def test_stop_command_cross_channel_in_unified_mode(self, tmp_path: Path):
         """In unified mode, /stop from one channel cancels tasks from another channel."""
@@ -504,4 +530,4 @@ class TestStopCommandWithUnifiedSession:
         result = await cmd_stop(ctx)
 
         # Both tasks should be cancelled
-        assert "Stopped 2 task" in result.content
+        assert "Stopped 2 task" in result.content

tests/agent/test_workspace_scope.py

@@ -0,0 +1,348 @@
+import json
+import time
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from nanobot.agent.tools.cli_apps import CliAppsTool
+from nanobot.agent.tools.filesystem import ReadFileTool
+from nanobot.agent.tools.image_generation import ImageGenerationError, ImageGenerationTool
+from nanobot.agent.tools.message import MessageTool
+from nanobot.agent.tools.shell import ExecTool
+from nanobot.agent.tools.spawn import SpawnTool
+from nanobot.security.workspace_access import (
+    WORKSPACE_SCOPE_METADATA_KEY,
+    WorkspaceScopeError,
+    bind_workspace_scope,
+    default_workspace_scope,
+    reset_workspace_scope,
+    validate_workspace_scope_payload,
+    workspace_scope_from_metadata,
+)
+from nanobot.apps.cli.service import CliAppManager, CliAppsRuntimeConfig
+from nanobot.config.schema import ImageGenerationToolConfig, ProviderConfig
+
+PNG_BYTES = (
+    b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01"
+    b"\x00\x00\x00\x01\x08\x04\x00\x00\x00\xb5\x1c\x0c\x02"
+    b"\x00\x00\x00\x0bIDATx\xdacd\xfc\xff\x1f\x00\x03\x03"
+    b"\x02\x00\xef\xbf\xa7\xdb\x00\x00\x00\x00IEND\xaeB`\x82"
+)
+
+
+def test_workspace_scope_defaults_match_legacy_config(tmp_path: Path) -> None:
+    unrestricted = default_workspace_scope(tmp_path, restrict_to_workspace=False)
+    restricted = default_workspace_scope(tmp_path, restrict_to_workspace=True)
+
+    assert unrestricted.project_path == tmp_path.resolve()
+    assert unrestricted.access_mode == "full"
+    assert unrestricted.restrict_to_workspace is False
+    assert restricted.access_mode == "restricted"
+    assert restricted.restrict_to_workspace is True
+
+
+def test_workspace_scope_rejects_invalid_project_path(tmp_path: Path) -> None:
+    with pytest.raises(WorkspaceScopeError, match="absolute"):
+        validate_workspace_scope_payload(
+            {"project_path": "relative/project", "access_mode": "restricted"},
+            default_workspace=tmp_path,
+            default_restrict_to_workspace=False,
+        )
+
+    with pytest.raises(WorkspaceScopeError, match="existing directory"):
+        validate_workspace_scope_payload(
+            {"project_path": str(tmp_path / "missing"), "access_mode": "restricted"},
+            default_workspace=tmp_path,
+            default_restrict_to_workspace=False,
+        )
+
+
+def test_workspace_scope_accepts_home_relative_project_path(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    home = tmp_path / "home"
+    project = home / "Desktop" / "Photos"
+    project.mkdir(parents=True)
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
+
+    scope = validate_workspace_scope_payload(
+        {"project_path": "~/Desktop/Photos", "access_mode": "restricted"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=False,
+    )
+
+    assert scope.project_path == project.resolve()
+    assert scope.metadata()["project_path"] == str(project.resolve())
+
+
+def test_workspace_scope_metadata_falls_back_for_stale_session(tmp_path: Path) -> None:
+    scope = workspace_scope_from_metadata(
+        {
+            WORKSPACE_SCOPE_METADATA_KEY: {
+                "project_path": str(tmp_path / "missing"),
+                "access_mode": "restricted",
+            }
+        },
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=False,
+    )
+
+    assert scope.project_path == tmp_path.resolve()
+    assert scope.access_mode == "full"
+
+
+@pytest.mark.asyncio
+async def test_filesystem_tool_uses_current_restricted_workspace_scope(tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    project.mkdir()
+    outside = tmp_path / "outside.txt"
+    outside.write_text("nope")
+    inside = project / "inside.txt"
+    inside.write_text("ok")
+    tool = ReadFileTool(workspace=tmp_path, restrict_to_workspace=False)
+    scope = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "restricted"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=False,
+    )
+    token = bind_workspace_scope(scope)
+    try:
+        assert "ok" in await tool.execute(path="inside.txt")
+        assert "outside allowed directory" in await tool.execute(path=str(outside))
+    finally:
+        reset_workspace_scope(token)
+
+
+@pytest.mark.asyncio
+async def test_exec_tool_uses_scope_project_as_default_cwd(tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    project.mkdir()
+    tool = ExecTool(working_dir=str(tmp_path), restrict_to_workspace=False, timeout=5)
+    scope = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "restricted"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=False,
+    )
+    token = bind_workspace_scope(scope)
+    try:
+        result = await tool.execute(command="printf ok > scoped-marker.txt")
+    finally:
+        reset_workspace_scope(token)
+
+    assert "Exit code: 0" in result
+    assert (project / "scoped-marker.txt").read_text() == "ok"
+
+
+@pytest.mark.asyncio
+async def test_exec_full_scope_allows_explicit_cwd_outside_project(tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    outside = tmp_path / "outside"
+    project.mkdir()
+    outside.mkdir()
+    tool = ExecTool(working_dir=str(tmp_path), restrict_to_workspace=True, timeout=5)
+    scope = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "full"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=True,
+    )
+    token = bind_workspace_scope(scope)
+    try:
+        result = await tool.execute(command="printf ok > outside-marker.txt", working_dir=str(outside))
+    finally:
+        reset_workspace_scope(token)
+
+    assert "Exit code: 0" in result
+    assert (outside / "outside-marker.txt").read_text() == "ok"
+
+
+def test_image_reference_scope_restricted_blocks_outside_and_full_allows(tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    outside = tmp_path / "outside"
+    project.mkdir()
+    outside.mkdir()
+    ref = outside / "ref.png"
+    ref.write_bytes(PNG_BYTES)
+    tool = ImageGenerationTool(
+        workspace=tmp_path,
+        config=ImageGenerationToolConfig(enabled=True),
+        provider_config=ProviderConfig(api_key="sk-test"),
+    )
+
+    restricted = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "restricted"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=False,
+    )
+    token = bind_workspace_scope(restricted)
+    try:
+        with pytest.raises(ImageGenerationError, match="inside the workspace"):
+            tool._resolve_reference_image(str(ref))
+    finally:
+        reset_workspace_scope(token)
+
+    full = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "full"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=True,
+    )
+    token = bind_workspace_scope(full)
+    try:
+        assert tool._resolve_reference_image(str(ref)) == str(ref.resolve())
+    finally:
+        reset_workspace_scope(token)
+
+
+def test_message_media_scope_restricted_blocks_outside_and_full_allows(tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    outside = tmp_path / "outside"
+    project.mkdir()
+    outside.mkdir()
+    media = outside / "shot.png"
+    media.write_bytes(PNG_BYTES)
+    tool = MessageTool(workspace=tmp_path, restrict_to_workspace=True)
+
+    restricted = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "restricted"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=False,
+    )
+    token = bind_workspace_scope(restricted)
+    try:
+        with pytest.raises(PermissionError):
+            tool._resolve_media([str(media)])
+    finally:
+        reset_workspace_scope(token)
+
+    full = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "full"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=True,
+    )
+    token = bind_workspace_scope(full)
+    try:
+        assert tool._resolve_media([str(media)]) == [str(media)]
+    finally:
+        reset_workspace_scope(token)
+
+
+@pytest.mark.asyncio
+async def test_cli_app_scope_controls_working_dir(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    project = tmp_path / "project"
+    outside = tmp_path / "outside"
+    data_dir = tmp_path / "data"
+    project.mkdir()
+    outside.mkdir()
+    registry = {
+        "meta": {},
+        "clis": [
+            {
+                "name": "demo",
+                "display_name": "Demo",
+                "version": "1.0",
+                "description": "demo",
+                "category": "test",
+                "install_cmd": "pip install demo",
+                "entry_point": "demo-cli",
+            }
+        ],
+    }
+    data_dir.mkdir()
+    (data_dir / "harness_registry_cache.json").write_text(
+        json.dumps({"_cached_at": time.time(), "data": registry}),
+        encoding="utf-8",
+    )
+    (data_dir / "public_registry_cache.json").write_text(
+        json.dumps({"_cached_at": time.time(), "data": {"meta": {}, "clis": []}}),
+        encoding="utf-8",
+    )
+    (data_dir / "extensions_registry_cache.json").write_text(
+        json.dumps({"_cached_at": time.time(), "data": {"meta": {}, "clis": []}}),
+        encoding="utf-8",
+    )
+    CliAppManager(workspace=project, data_dir=data_dir)._save_installed(
+        {"demo": {"entry_point": "demo-cli"}}
+    )
+    monkeypatch.setattr("nanobot.apps.cli.service.get_runtime_subdir", lambda _name: data_dir)
+    monkeypatch.setattr(
+        "nanobot.apps.cli.service.shutil.which",
+        lambda entry: "/usr/bin/demo-cli" if entry == "demo-cli" else None,
+    )
+
+    seen: dict[str, str] = {}
+
+    def fake_run(argv, **kwargs):
+        seen["cwd"] = kwargs["cwd"]
+        return SimpleNamespace(returncode=0, stdout="ok", stderr="")
+
+    monkeypatch.setattr("nanobot.apps.cli.service.subprocess.run", fake_run)
+    tool = CliAppsTool(
+        workspace=tmp_path,
+        restrict_to_workspace=True,
+        runtime=CliAppsRuntimeConfig(run_timeout=5),
+    )
+
+    restricted = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "restricted"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=False,
+    )
+    token = bind_workspace_scope(restricted)
+    try:
+        blocked = await tool.execute(name="demo", working_dir=str(outside))
+    finally:
+        reset_workspace_scope(token)
+    assert "outside the configured workspace" in blocked
+
+    full = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "full"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=True,
+    )
+    token = bind_workspace_scope(full)
+    try:
+        result = await tool.execute(name="demo", working_dir=str(outside))
+    finally:
+        reset_workspace_scope(token)
+    assert "CLI app 'demo' exited 0" in result
+    assert seen["cwd"] == str(outside.resolve())
+
+
+@pytest.mark.asyncio
+async def test_spawn_tool_forwards_current_workspace_scope(tmp_path: Path) -> None:
+    project = tmp_path / "project"
+    project.mkdir()
+    scope = validate_workspace_scope_payload(
+        {"project_path": str(project), "access_mode": "restricted"},
+        default_workspace=tmp_path,
+        default_restrict_to_workspace=False,
+    )
+
+    class Manager:
+        max_concurrent_subagents = 4
+
+        def __init__(self) -> None:
+            self.seen = None
+
+        def get_running_count(self) -> int:
+            return 0
+
+        async def spawn(self, **kwargs):
+            self.seen = kwargs
+            return "spawned"
+
+    manager = Manager()
+    tool = SpawnTool(manager)  # type: ignore[arg-type]
+    token = bind_workspace_scope(scope)
+    try:
+        result = await tool.execute(task="inspect")
+    finally:
+        reset_workspace_scope(token)
+
+    assert result == "spawned"
+    assert manager.seen["workspace_scope"] == scope

tests/agent/tools/test_long_task.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
@@ -72,6 +73,49 @@ async def test_complete_goal_closes_active_goal(tmp_path):
     assert blob["recap"] == "Done."
 
 
+@pytest.mark.asyncio
+async def test_goal_tools_keep_request_context_per_task(tmp_path):
+    sm = SessionManager(tmp_path)
+    lt = LongTaskTool(sessions=sm)
+    cg = CompleteGoalTool(sessions=sm)
+    ctx_a = RequestContext(channel="websocket", chat_id="a", session_key="websocket:a")
+    ctx_b = RequestContext(channel="websocket", chat_id="b", session_key="websocket:b")
+
+    lt.set_context(ctx_a)
+    task_a = asyncio.create_task(lt.execute(goal="Goal A"))
+    lt.set_context(ctx_b)
+    task_b = asyncio.create_task(lt.execute(goal="Goal B"))
+    await asyncio.gather(task_a, task_b)
+
+    assert sm.get_or_create("websocket:a").metadata[GOAL_STATE_KEY]["objective"] == "Goal A"
+    assert sm.get_or_create("websocket:b").metadata[GOAL_STATE_KEY]["objective"] == "Goal B"
+
+    cg.set_context(ctx_a)
+    done_a = asyncio.create_task(cg.execute(recap="Done A"))
+    cg.set_context(ctx_b)
+    done_b = asyncio.create_task(cg.execute(recap="Done B"))
+    await asyncio.gather(done_a, done_b)
+
+    assert sm.get_or_create("websocket:a").metadata[GOAL_STATE_KEY]["recap"] == "Done A"
+    assert sm.get_or_create("websocket:b").metadata[GOAL_STATE_KEY]["recap"] == "Done B"
+
+
+@pytest.mark.asyncio
+async def test_goal_tools_context_isolated_across_tool_types(tmp_path):
+    """LongTaskTool and CompleteGoalTool must not share routing context."""
+    sm = SessionManager(tmp_path)
+    lt = LongTaskTool(sessions=sm)
+    cg = CompleteGoalTool(sessions=sm)
+    ctx = RequestContext(channel="websocket", chat_id="a", session_key="websocket:a")
+
+    lt.set_context(ctx)
+    assert cg._request_ctx.get() is None
+
+    cg.set_context(ctx)
+    assert lt._request_ctx.get() is ctx
+    assert cg._request_ctx.get() is ctx
+
+
 @pytest.mark.asyncio
 async def test_long_task_publishes_goal_state_ws_after_save(tmp_path):
     bus = MagicMock()

tests/agent/tools/test_subagent_tools.py

@@ -94,6 +94,39 @@ async def test_subagent_uses_configured_max_iterations(tmp_path):
     mgr.runner.run.assert_awaited_once()
 
 
+@pytest.mark.asyncio
+async def test_spawn_forwards_temperature_to_run_spec(tmp_path):
+    """A temperature passed to spawn() should reach the AgentRunSpec."""
+    from nanobot.agent.subagent import SubagentManager
+    from nanobot.bus.queue import MessageBus
+
+    bus = MessageBus()
+    provider = MagicMock()
+    provider.get_default_model.return_value = "test-model"
+    mgr = SubagentManager(
+        provider=provider,
+        workspace=tmp_path,
+        bus=bus,
+        max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+    )
+    mgr._announce_result = AsyncMock()
+
+    seen = {}
+
+    async def fake_run(spec):
+        seen["temperature"] = spec.temperature
+        return SimpleNamespace(
+            stop_reason="done", final_content="done", error=None, tool_events=[],
+        )
+
+    mgr.runner.run = AsyncMock(side_effect=fake_run)
+
+    await mgr.spawn(task="do task", temperature=0.9)
+    await asyncio.gather(*mgr._running_tasks.values(), return_exceptions=True)
+
+    assert seen["temperature"] == 0.9
+
+
 @pytest.mark.asyncio
 async def test_spawn_tool_rejects_when_at_concurrency_limit(tmp_path):
     """SpawnTool should return an error string when the concurrency limit is reached."""

tests/channels/test_channel_plugins.py

@@ -91,6 +91,13 @@ def test_channels_config_builtin_fields_removed():
     assert not hasattr(cfg, "telegram")
     assert cfg.send_progress is True
     assert cfg.send_tool_hints is False
+    assert cfg.extract_document_text is True
+
+
+def test_channels_config_extract_document_text_accepts_camel_alias():
+    cfg = ChannelsConfig.model_validate({"extractDocumentText": False})
+
+    assert cfg.extract_document_text is False
 
 
 # ---------------------------------------------------------------------------

tests/channels/test_discord_channel.py

@@ -865,7 +865,7 @@ async def test_slash_new_is_blocked_for_disallowed_user() -> None:
     assert handled == []
 
 
-@pytest.mark.parametrize("slash_name", ["stop", "restart", "status", "history"])
+@pytest.mark.parametrize("slash_name", ["stop", "restart", "status", "history", "model"])
 @pytest.mark.asyncio
 async def test_slash_commands_forward_via_handle_message(slash_name: str) -> None:
     channel = DiscordChannel(DiscordConfig(enabled=True, allow_from=["*"]), MessageBus())
@@ -891,6 +891,31 @@ async def test_slash_commands_forward_via_handle_message(slash_name: str) -> Non
     assert handled[0]["metadata"]["is_slash_command"] is True
 
 
+@pytest.mark.asyncio
+async def test_slash_model_forwards_optional_preset() -> None:
+    channel = DiscordChannel(DiscordConfig(enabled=True, allow_from=["*"]), MessageBus())
+    handled: list[dict] = []
+
+    async def capture_handle(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = capture_handle  # type: ignore[method-assign]
+    client = DiscordBotClient(channel, intents=discord.Intents.none())
+    interaction = _make_interaction()
+    interaction.command.qualified_name = "model"
+
+    model_cmd = client.tree.get_command("model")
+    assert model_cmd is not None
+    await model_cmd.callback(interaction, preset="fast")
+
+    assert interaction.response.messages == [
+        {"content": "Processing /model fast...", "ephemeral": True}
+    ]
+    assert len(handled) == 1
+    assert handled[0]["content"] == "/model fast"
+    assert handled[0]["metadata"]["is_slash_command"] is True
+
+
 @pytest.mark.asyncio
 async def test_slash_help_returns_ephemeral_help_text() -> None:
     channel = DiscordChannel(DiscordConfig(enabled=True, allow_from=["*"]), MessageBus())

tests/channels/test_matrix_channel.py

@@ -9,8 +9,6 @@ pytest.importorskip("nh3")
 pytest.importorskip("mistune")
 from nio import RoomSendResponse, SyncError
 
-from nanobot.channels.matrix import _build_matrix_text_content
-
 import nanobot.channels.matrix as matrix_module
 from nanobot.bus.events import OutboundMessage
 from nanobot.bus.queue import MessageBus
@@ -18,8 +16,9 @@ from nanobot.channels.matrix import (
     MATRIX_HTML_FORMAT,
     TYPING_NOTICE_TIMEOUT_MS,
     MatrixChannel,
+    MatrixConfig,
+    _build_matrix_text_content,
 )
-from nanobot.channels.matrix import MatrixConfig
 
 _ROOM_SEND_UNSET = object()
 
@@ -693,6 +692,13 @@ async def test_on_media_message_downloads_attachment_and_sets_metadata(
     client.download_bytes = b"image"
     channel.client = client
 
+    async def _download_media_bytes(mxc_url: str, limit_bytes: int) -> bytes:
+        client.download_calls.append(mxc_url)
+        assert limit_bytes >= len(client.download_bytes)
+        return client.download_bytes
+
+    monkeypatch.setattr(channel, "_download_media_bytes", _download_media_bytes)
+
     handled: list[dict[str, object]] = []
 
     async def _fake_handle_message(**kwargs) -> None:
@@ -857,9 +863,14 @@ async def test_on_media_message_handles_download_error(monkeypatch, tmp_path) ->
 
     channel = MatrixChannel(_make_config(), MessageBus())
     client = _FakeAsyncClient("", "", "", None)
-    client.download_response = matrix_module.DownloadError("download failed")
     channel.client = client
 
+    async def _download_media_bytes(mxc_url: str, _limit_bytes: int):
+        client.download_calls.append(mxc_url)
+        return None
+
+    monkeypatch.setattr(channel, "_download_media_bytes", _download_media_bytes)
+
     handled: list[dict[str, object]] = []
 
     async def _fake_handle_message(**kwargs) -> None:
@@ -873,7 +884,7 @@ async def test_on_media_message_handles_download_error(monkeypatch, tmp_path) ->
         body="photo.png",
         url="mxc://example.org/mediaid",
         event_id="$event3",
-        source={"content": {"msgtype": "m.image"}},
+        source={"content": {"msgtype": "m.image", "info": {"size": 5}}},
     )
 
     await channel._on_media_message(room, event)
@@ -899,6 +910,13 @@ async def test_on_media_message_decrypts_encrypted_media(monkeypatch, tmp_path)
     client.download_bytes = b"cipher"
     channel.client = client
 
+    async def _download_media_bytes(mxc_url: str, limit_bytes: int) -> bytes:
+        client.download_calls.append(mxc_url)
+        assert limit_bytes >= len(client.download_bytes)
+        return client.download_bytes
+
+    monkeypatch.setattr(channel, "_download_media_bytes", _download_media_bytes)
+
     handled: list[dict[str, object]] = []
 
     async def _fake_handle_message(**kwargs) -> None:
@@ -942,6 +960,13 @@ async def test_on_media_message_handles_decrypt_error(monkeypatch, tmp_path) ->
     client.download_bytes = b"cipher"
     channel.client = client
 
+    async def _download_media_bytes(mxc_url: str, limit_bytes: int) -> bytes:
+        client.download_calls.append(mxc_url)
+        assert limit_bytes >= len(client.download_bytes)
+        return client.download_bytes
+
+    monkeypatch.setattr(channel, "_download_media_bytes", _download_media_bytes)
+
     handled: list[dict[str, object]] = []
 
     async def _fake_handle_message(**kwargs) -> None:
@@ -958,7 +983,7 @@ async def test_on_media_message_handles_decrypt_error(monkeypatch, tmp_path) ->
         key={"k": "key"},
         hashes={"sha256": "hash"},
         iv="iv",
-        source={"content": {"msgtype": "m.file"}},
+        source={"content": {"msgtype": "m.file", "info": {"size": 6}}},
     )
 
     await channel._on_media_message(room, event)
@@ -1756,7 +1781,7 @@ async def test_send_delta_on_error_stops_typing(monkeypatch) -> None:
     assert "!room:matrix.org" in channel._stream_bufs
     assert channel._stream_bufs["!room:matrix.org"].text == "Hello"
     assert len(client.room_send_calls) == 1
-    
+
     assert len(client.typing_calls) == 1
 
 
@@ -1773,4 +1798,116 @@ async def test_send_delta_ignores_whitespace_only_delta(monkeypatch) -> None:
 
     assert "!room:matrix.org" in channel._stream_bufs
     assert channel._stream_bufs["!room:matrix.org"].text == "   "
-    assert client.room_send_calls == []
+
+
+@pytest.mark.asyncio
+async def test_fetch_media_rejects_missing_declared_size(monkeypatch, tmp_path) -> None:
+    channel = MatrixChannel(_make_config(max_media_bytes=8), MessageBus())
+    client = _FakeAsyncClient("https://matrix.org", "", "", None)
+    channel.client = client
+    monkeypatch.setattr("nanobot.channels.matrix.get_media_dir", lambda _name: tmp_path)
+
+    async def _download_should_not_run(*_args, **_kwargs):
+        raise AssertionError("download should be rejected before fetching bytes")
+
+    monkeypatch.setattr(channel, "_download_media_bytes", _download_should_not_run)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        event_id="$event1",
+        body="payload.bin",
+        url="mxc://example.org/media",
+        source={"content": {"msgtype": "m.file"}},
+    )
+
+    attachment, marker = await channel._fetch_media_attachment(
+        SimpleNamespace(room_id="!room:matrix.org"),
+        event,
+    )
+
+    assert attachment is None
+    assert marker == "[attachment: payload.bin - too large]"
+
+
+@pytest.mark.asyncio
+async def test_fetch_media_rejects_bool_declared_size(monkeypatch, tmp_path) -> None:
+    channel = MatrixChannel(_make_config(max_media_bytes=8), MessageBus())
+    client = _FakeAsyncClient("https://matrix.org", "", "", None)
+    channel.client = client
+    monkeypatch.setattr("nanobot.channels.matrix.get_media_dir", lambda _name: tmp_path)
+
+    async def _download_should_not_run(*_args, **_kwargs):
+        raise AssertionError("bool size should be rejected before fetching bytes")
+
+    monkeypatch.setattr(channel, "_download_media_bytes", _download_should_not_run)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        event_id="$event1",
+        body="payload.bin",
+        url="mxc://example.org/media",
+        source={"content": {"msgtype": "m.file", "info": {"size": True}}},
+    )
+
+    attachment, marker = await channel._fetch_media_attachment(
+        SimpleNamespace(room_id="!room:matrix.org"),
+        event,
+    )
+
+    assert attachment is None
+    assert marker == "[attachment: payload.bin - too large]"
+
+
+@pytest.mark.asyncio
+async def test_fetch_media_rejects_declared_oversized_before_download(monkeypatch, tmp_path) -> None:
+    channel = MatrixChannel(_make_config(max_media_bytes=8), MessageBus())
+    client = _FakeAsyncClient("https://matrix.org", "", "", None)
+    channel.client = client
+    monkeypatch.setattr("nanobot.channels.matrix.get_media_dir", lambda _name: tmp_path)
+
+    async def _download_should_not_run(*_args, **_kwargs):
+        raise AssertionError("download should be rejected before fetching bytes")
+
+    monkeypatch.setattr(channel, "_download_media_bytes", _download_should_not_run)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        event_id="$event1",
+        body="payload.bin",
+        url="mxc://example.org/media",
+        source={"content": {"msgtype": "m.file", "info": {"size": 9}}},
+    )
+
+    attachment, marker = await channel._fetch_media_attachment(
+        SimpleNamespace(room_id="!room:matrix.org"),
+        event,
+    )
+
+    assert attachment is None
+    assert marker == "[attachment: payload.bin - too large]"
+
+
+@pytest.mark.asyncio
+async def test_fetch_media_maps_streaming_cap_to_too_large(monkeypatch, tmp_path) -> None:
+    channel = MatrixChannel(_make_config(max_media_bytes=8), MessageBus())
+    client = _FakeAsyncClient("https://matrix.org", "", "", None)
+    channel.client = client
+    monkeypatch.setattr("nanobot.channels.matrix.get_media_dir", lambda _name: tmp_path)
+
+    async def _download_too_large(_mxc_url: str, _limit_bytes: int):
+        raise matrix_module._MediaTooLargeError
+
+    monkeypatch.setattr(channel, "_download_media_bytes", _download_too_large)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        event_id="$event1",
+        body="payload.bin",
+        url="mxc://example.org/media",
+        source={"content": {"msgtype": "m.file", "info": {"size": 8}}},
+    )
+
+    attachment, marker = await channel._fetch_media_attachment(
+        SimpleNamespace(room_id="!room:matrix.org"),
+        event,
+    )
+
+    assert attachment is None
+    assert marker == "[attachment: payload.bin - too large]"
+    assert client.room_send_calls == []

tests/channels/test_telegram_channel.py

@@ -1,3 +1,4 @@
+import asyncio
 from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import AsyncMock
@@ -36,11 +37,19 @@ class _FakeUpdater:
     def __init__(self, on_start_polling) -> None:
         self._on_start_polling = on_start_polling
         self.start_polling_kwargs = None
+        self.start_webhook_kwargs = None
 
     async def start_polling(self, **kwargs) -> None:
         self.start_polling_kwargs = kwargs
         self._on_start_polling()
 
+    async def start_webhook(self, **kwargs) -> None:
+        self.start_webhook_kwargs = kwargs
+        self._on_start_polling()
+
+    async def stop(self) -> None:
+        pass
+
 
 class _FakeBot:
     def __init__(self) -> None:
@@ -103,6 +112,12 @@ class _FakeApp:
     async def start(self) -> None:
         pass
 
+    async def stop(self) -> None:
+        pass
+
+    async def shutdown(self) -> None:
+        pass
+
 
 class _FakeBuilder:
     def __init__(self, app: _FakeApp) -> None:
@@ -232,6 +247,98 @@ async def test_start_respects_custom_pool_config(monkeypatch) -> None:
     assert poll_req.kwargs["pool_timeout"] == 10.0
 
 
+def test_webhook_config_requires_https_url_and_secret() -> None:
+    with pytest.raises(ValueError, match="webhook_url is required"):
+        TelegramConfig(enabled=True, token="123:abc", mode="webhook")
+
+    with pytest.raises(ValueError, match="public HTTPS URL"):
+        TelegramConfig(
+            enabled=True,
+            token="123:abc",
+            mode="webhook",
+            webhook_url="http://example.com/telegram",
+            webhook_secret_token="secret",
+        )
+
+    with pytest.raises(ValueError, match="webhook_secret_token is required"):
+        TelegramConfig(
+            enabled=True,
+            token="123:abc",
+            mode="webhook",
+            webhook_url="https://example.com/telegram",
+        )
+
+
+@pytest.mark.asyncio
+async def test_start_webhook_mode(monkeypatch) -> None:
+    _FakeHTTPXRequest.clear()
+    config = TelegramConfig(
+        enabled=True,
+        token="123:abc",
+        allow_from=["*"],
+        mode="webhook",
+        webhook_url="https://example.com/telegram",
+        webhook_listen_host="127.0.0.1",
+        webhook_listen_port=8081,
+        webhook_path="/telegram",
+        webhook_secret_token="secret-token",
+        webhook_max_connections=1,
+    )
+    bus = MessageBus()
+    channel = TelegramChannel(config, bus)
+    app = _FakeApp(lambda: setattr(channel, "_running", False))
+    builder = _FakeBuilder(app)
+
+    monkeypatch.setattr("nanobot.channels.telegram.HTTPXRequest", _FakeHTTPXRequest)
+    monkeypatch.setattr(
+        "nanobot.channels.telegram.Application",
+        SimpleNamespace(builder=lambda: builder),
+    )
+
+    await channel.start()
+
+    assert app.updater.start_polling_kwargs is None
+    assert app.updater.start_webhook_kwargs == {
+        "listen": "127.0.0.1",
+        "port": 8081,
+        "url_path": "telegram",
+        "webhook_url": "https://example.com/telegram",
+        "allowed_updates": ["message"],
+        "drop_pending_updates": False,
+        "secret_token": "secret-token",
+        "max_connections": 1,
+    }
+
+
+@pytest.mark.asyncio
+async def test_running_message_handler_reorders_same_session_updates() -> None:
+    channel = TelegramChannel(
+        TelegramConfig(enabled=True, token="123:abc", allow_from=["*"]),
+        MessageBus(),
+    )
+    seen: list[int] = []
+
+    async def fake_process(update, context) -> None:
+        seen.append(update.message.message_id)
+
+    channel._process_message_update = fake_process
+    channel._running = True
+
+    first = _make_telegram_update(text="first")
+    first.update_id = 100
+    first.message.message_id = 1
+    second = _make_telegram_update(text="second")
+    second.update_id = 101
+    second.message.message_id = 2
+
+    await channel._on_message(second, None)
+    await channel._on_message(first, None)
+    await asyncio.sleep(0.3)
+    channel._running = False
+
+    assert seen == [1, 2]
+
+
 @pytest.mark.asyncio
 async def test_send_text_retries_on_timeout() -> None:
     """_send_text retries on TimedOut before succeeding."""