fix(agent): rebuild provider on preset switch

.github/workflows/ci.yml

@@ -33,13 +33,20 @@ jobs:
         id: paths
         shell: bash
         env:
+          EVENT_NAME: ${{ github.event_name }}
           BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
-          HEAD_SHA: ${{ github.sha }}
+          HEAD_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
         run: |
           python_required=true
 
+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            diff_range="${BASE_SHA}...${HEAD_SHA}"
+          else
+            diff_range="${BASE_SHA}..${HEAD_SHA}"
+          fi
+
           if git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null &&
-            changed_files="$(git diff --name-only --no-renames "$BASE_SHA" "$HEAD_SHA")" &&
+            changed_files="$(git diff --name-only --no-renames "$diff_range")" &&
             [[ -n "$changed_files" ]] &&
             ! grep -qvE '^(webui/|nanobot/channels/[^/]+/webui/|docs/)' <<< "$changed_files"; then
             python_required=false

README.md

@@ -17,24 +17,24 @@
     <a href="https://nanobot.wiki/vi/docs/latest/getting-started/nanobot-overview">Tiếng Việt</a>
   </p>
   <p>
-    <a href="https://pypi.org/project/nanobot-ai/"><img src="https://img.shields.io/pypi/v/nanobot-ai" alt="PyPI"></a>
+    <a href="https://github.com/HKUDS/nanobot"><img src="https://img.shields.io/github/stars/HKUDS/nanobot?style=flat&logo=github" alt="GitHub stars"></a>
-    <a href="https://pepy.tech/project/nanobot-ai"><img src="https://static.pepy.tech/badge/nanobot-ai" alt="Downloads"></a>
+    <a href="https://pypi.org/project/nanobot-ai/"><img src="https://img.shields.io/pypi/v/nanobot-ai" alt="PyPI version"></a>
-    <img src="https://img.shields.io/badge/python-≥3.11-blue" alt="Python">
+    <a href="https://pepy.tech/project/nanobot-ai"><img src="https://static.pepy.tech/badge/nanobot-ai" alt="PyPI downloads"></a>
-    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+    <a href="https://github.com/HKUDS/nanobot/actions/workflows/ci.yml"><img src="https://github.com/HKUDS/nanobot/actions/workflows/ci.yml/badge.svg?branch=main" alt="Test Suite"></a>
-    <a href="https://github.com/HKUDS/nanobot/graphs/commit-activity" target="_blank">
+    <a href="https://pypi.org/project/nanobot-ai/"><img src="https://img.shields.io/badge/python-%3E%3D3.11-blue" alt="Python 3.11 or newer"></a>
-        <img alt="Commits last month" src="https://img.shields.io/github/commit-activity/m/HKUDS/nanobot?labelColor=%20%2332b583&color=%20%2312b76a"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/github/license/HKUDS/nanobot" alt="MIT License"></a>
-    <a href="https://github.com/HKUDS/nanobot/issues?q=is%3Aissue%20is%3Aclosed" target="_blank">
+    <a href="https://nanobot.wiki/docs/latest/getting-started/nanobot-overview"><img src="https://img.shields.io/badge/docs-nanobot.wiki-blue" alt="nanobot documentation"></a>
-        <img alt="Issues closed" src="https://img.shields.io/github/issues-search?query=repo%3AHKUDS%2Fnanobot%20is%3Aissue%20is%3Aclosed&label=issues%20closed&labelColor=%20%237d89b0&color=%20%235d6b98"></a>
+  </p>
-    <a href="https://twitter.com/intent/follow?screen_name=nanobot_project" target="_blank">
+  <p>
-        <img src="https://img.shields.io/twitter/follow/nanobot_project?logo=X&color=%20%23f5f5f5" alt="follow on X(Twitter)"></a>
+    <a href="https://discord.gg/MnCvHqpUGB">Discord</a> ·
-    <a href="https://nanobot.wiki/docs/latest/getting-started/nanobot-overview"><img src="https://img.shields.io/badge/Docs-nanobot.wiki-blue?style=flat&logo=readthedocs&logoColor=white" alt="Docs"></a>
+    <a href="https://x.com/nanobot_project">X</a> ·
-    <a href="./COMMUNICATION.md"><img src="https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat&logo=feishu&logoColor=white" alt="Feishu"></a>
+    <a href="./COMMUNICATION.md">WeChat / Feishu</a>
-    <a href="./COMMUNICATION.md"><img src="https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat&logo=wechat&logoColor=white" alt="WeChat"></a>
-    <a href="https://discord.gg/MnCvHqpUGB"><img src="https://img.shields.io/badge/Discord-Community-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
   </p>
 </div>
 
-🐈 **nanobot** is an open-source, ultra-lightweight personal AI agent you can truly own. It keeps the agent core small and readable while giving you the practical pieces for real long-running work: WebUI, chat channels, tools, memory, MCP, model routing, automation, and deployment.
+# nanobot
+
+🐈 **nanobot** is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. It runs in a WebUI, terminal, or chat apps and combines tools, long-term memory, MCP integrations, model routing, multi-agent delegation, scheduled automation, and an OpenAI-compatible API in a small, readable core.
 
 ## Start Here
 
@@ -46,7 +46,7 @@
 | Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | [Chat Apps](./docs/chat-apps.md) |
 | Configure providers, fallback models, Langfuse, MCP, web tools, or security | [Docs](./docs/README.md) and [Configuration](./docs/configuration.md) |
 | Understand or extend the internals | [Architecture](./docs/architecture.md) and [Development](./docs/development.md) |
-| Deploy to the cloud or keep nanobot running as a service | [Deployment](./docs/deployment.md), including [one-click Render setup](./docs/deployment.md#render) |
+| Deploy to the cloud or keep nanobot running as a service | [Deployment](./docs/deployment.md) |
 
 ## What can nanobot do?
 
@@ -60,36 +60,6 @@ nanobot is a self-hosted personal AI agent runtime. It can:
 - expose a Python SDK and OpenAI-compatible API for integrations
 - deploy as a long-running local or server-side agent gateway
 
-## Releases
-
-**Latest release: [v0.3.0 - The Agency Release](https://github.com/HKUDS/nanobot/releases/tag/v0.3.0)**
-
-The Agency Release turns nanobot from a durable workbench into an agent runtime that can coordinate helpers, switch models per session, and carry authorized work through to completion.
-
-- Consult inline subagents without leaving the current task
-- Switch model presets per session directly from the composer
-- Start from a guided WebUI setup with clearer execution controls
-- Apply configuration changes live across a more reliable provider, channel, and tool runtime
-
-[Read the v0.3.0 release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.3.0)
-
-## Open Source Partners
-
-<p align="center">
-  <a href="https://platform.kimi.com?aff=nanobot"><picture><source media="(prefers-color-scheme: dark)" srcset="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69mt3v89kkekg24gg"><img alt="Kimi Open Source Friends" height="44" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0"></picture></a>
-  <a href="https://platform.minimaxi.com/subscribe/token-plan?code=GILTJpMTqZ&source=link"><img alt="MiniMax" height="40" src="https://mintcdn.com/minimax-zh/1UjvBcdoC6r0UeyA/logo/light.svg?fit=max&auto=format&n=1UjvBcdoC6r0UeyA&q=85&s=672d724b639b2d88d0702fae329ea4f8"></a>
-</p>
-
-## Recent Updates
-
-- **2026-07-24** Guided first-run setup, inline subagents, and model switching from the composer.
-- **2026-07-23** Grok OAuth with hosted X Search, live image settings, and clearer fallback models.
-- **2026-07-22** Parallel Search, live configuration reloads, richer app discovery, and a smoother mobile WebUI.
-- **2026-07-21** Codex fast mode, visible skill references, safer configuration saves, and sturdier task cleanup.
-- **2026-07-20** Cleaner code blocks and copy actions, self-contained channels, and steadier QQ reconnects.
-
-For older updates, see the [release archive](./docs/release-archive.md) or [GitHub releases](https://github.com/HKUDS/nanobot/releases).
-
 ## 💡 Why nanobot
 
 - **Persistent workflows**: goals, memory, tools, and chat context survive long-running work.
@@ -244,6 +214,8 @@ The one-shot form is useful for a quick provider check, shell scripts, and local
 
 Need manual JSON, another device on your LAN, or help with provider/model matching? Continue with [Install and Quick Start](./docs/quick-start.md), [WebUI](./docs/webui.md), or [Troubleshooting](./docs/troubleshooting.md).
 
+If nanobot worked for you, a star on GitHub is the simplest way to support the project.
+
 - Want a pasteable provider setup? See [Provider Cookbook](./docs/provider-cookbook.md)
 - Want to understand provider/model matching? See [Providers and Models](./docs/providers.md)
 - Want web search, MCP, security settings, or more config options? See [Configuration](./docs/configuration.md)
@@ -251,6 +223,22 @@ Need manual JSON, another device on your LAN, or help with provider/model matchi
 - Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See [Chat Apps](./docs/chat-apps.md)
 - Want Docker or Linux service deployment? See [Deployment](./docs/deployment.md)
 
+<a id="deploy-to-render"></a>
+
+## ☁️ Deploy
+
+**Render — one click**
+
+Deploy nanobot's gateway and bundled WebUI from the repository's ready-to-use Blueprint:
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/HKUDS/nanobot)
+
+Render will ask for `ANTHROPIC_API_KEY` and a private `NANOBOT_WEB_TOKEN`, then provision persistent storage for sessions, memory, and WebUI history. Persistent disks require a paid Render service.
+
+**Self-host**
+
+Prefer your own infrastructure? Follow the [deployment guide](./docs/deployment.md) for Docker, Docker Compose, Linux services, and macOS LaunchAgent setup.
+
 ## 🌐 WebUI
 
 The WebUI ships **inside the published wheel** with no separate frontend build. It is the browser workbench for persistent topics, visible agent activity, workspace controls, Apps, Skills, Automations, and settings.
@@ -276,29 +264,6 @@ See the [WebUI guide](./docs/webui.md) for LAN access, background operation, wor
 
 🐈 nanobot stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.
 
-## ✨ Features
-
-<table align="center">
-  <tr align="center">
-    <th><p align="center">📈 24/7 Real-Time Market Analysis</p></th>
-    <th><p align="center">🚀 Full-Stack Software Engineer</p></th>
-    <th><p align="center">📅 Smart Daily Routine Manager</p></th>
-    <th><p align="center">📚 Personal Knowledge Assistant</p></th>
-  </tr>
-  <tr>
-    <td align="center"><p align="center"><img src="case/search.gif" width="180" height="400"></p></td>
-    <td align="center"><p align="center"><img src="case/code.gif" width="180" height="400"></p></td>
-    <td align="center"><p align="center"><img src="case/schedule.gif" width="180" height="400"></p></td>
-    <td align="center"><p align="center"><img src="case/memory.gif" width="180" height="400"></p></td>
-  </tr>
-  <tr>
-    <td align="center">Discovery • Insights • Trends</td>
-    <td align="center">Develop • Deploy • Scale</td>
-    <td align="center">Schedule • Automate • Organize</td>
-    <td align="center">Learn • Memory • Reasoning</td>
-  </tr>
-</table>
-
 ## 📚 Docs
 
 Browse the [repo docs](./docs/README.md) for the latest features and GitHub development version, or visit [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview) for the stable release documentation.
@@ -317,21 +282,43 @@ Browse the [repo docs](./docs/README.md) for the latest features and GitHub deve
 - Integrate nanobot with local tools and automations: [OpenAI-Compatible API](./docs/openai-api.md) · [Python SDK](./docs/python-sdk.md)
 - Run nanobot with Docker or as a Linux service: [Deployment](./docs/deployment.md)
 
-## 🤝 Contribute & Roadmap
+## Releases
 
-PRs welcome! The codebase is intentionally small and readable. 🤗
+**Latest release: [v0.3.0 - The Agency Release](https://github.com/HKUDS/nanobot/releases/tag/v0.3.0)**
 
-### Contribution Flow
+The Agency Release turns nanobot from a durable workbench into an agent runtime that can coordinate helpers, switch models per session, and carry authorized work through to completion.
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, review, and contribution guidelines.
+- Consult inline subagents without leaving the current task
+- Switch model presets per session directly from the composer
+- Start from a guided WebUI setup with clearer execution controls
+- Apply configuration changes live across a more reliable provider, channel, and tool runtime
 
-**Roadmap** — Pick an item and [open a PR](https://github.com/HKUDS/nanobot/pulls)!
+[Read the v0.3.0 release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.3.0)
 
-- **Multi-modal** — See and hear (images, voice, video)
+## Recent Updates
-- **Long-term memory** — Never forget important context
+
-- **Better reasoning** — Multi-step planning and reflection
+- **2026-07-24** Guided first-run setup, inline subagents, and model switching from the composer.
-- **More integrations** — Calendar and more
+- **2026-07-23** Grok OAuth with hosted X Search, live image settings, and clearer fallback models.
-- **Self-improvement** — Learn from feedback and mistakes
+- **2026-07-22** Parallel Search, live configuration reloads, richer app discovery, and a smoother mobile WebUI.
+- **2026-07-21** Codex fast mode, visible skill references, safer configuration saves, and sturdier task cleanup.
+- **2026-07-20** Cleaner code blocks and copy actions, self-contained channels, and steadier QQ reconnects.
+
+For older updates, see the [release archive](./docs/release-archive.md) or [GitHub releases](https://github.com/HKUDS/nanobot/releases).
+
+## Open Source Partners
+
+<p align="center">
+  <a href="https://platform.kimi.com?aff=nanobot"><picture><source media="(prefers-color-scheme: dark)" srcset="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69mt3v89kkekg24gg"><img alt="Kimi Open Source Friends" height="44" src="https://kimi-file.moonshot.cn/prod-chat-kimi/kfs/4/1/2026-06-05/1d8h69fudcmosb3pipls0"></picture></a>
+  <a href="https://platform.minimaxi.com/subscribe/token-plan?code=GILTJpMTqZ&source=link"><img alt="MiniMax" height="40" src="https://mintcdn.com/minimax-zh/1UjvBcdoC6r0UeyA/logo/light.svg?fit=max&auto=format&n=1UjvBcdoC6r0UeyA&q=85&s=672d724b639b2d88d0702fae329ea4f8"></a>
+</p>
+
+## 🤝 Contribute
+
+Use nanobot for a real task, report what broke, and then pick a focused improvement.
+
+- Read [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow.
+- Browse [open issues](https://github.com/HKUDS/nanobot/issues) for problems to investigate.
+- Open a [pull request](https://github.com/HKUDS/nanobot/pulls) for a focused fix or integration.
 
 ## Contact
 

docs/README.md

@@ -33,7 +33,6 @@ Pick the row that matches what you want to accomplish next:
 | Add model fallbacks | [Configure Model Fallback](./guides/configure-model-fallback.md) |
 | Enable web search | [Configure Web Search](./guides/configure-web-search.md) |
 | Add an MCP tool server | [Configure MCP Tools](./guides/configure-mcp-tools.md) |
-| Install and govern an extension | [Extensions](./extensions.md) |
 | Generate images | [Image Generation](./image-generation.md) |
 | Schedule work or create a local trigger | [Automations](./automations.md) |
 | Understand and manage long-term memory | [Memory](./memory.md) |
@@ -80,7 +79,6 @@ These pages explain implementation and extension points. You do not need them to
 | Understand source ownership and runtime flow | [Architecture](./architecture.md) |
 | Set up a development environment | [Development](./development.md) and [CONTRIBUTING.md](../CONTRIBUTING.md) |
 | Add a channel package | [Channel Package Guide](./channel-package-guide.md) |
-| Publish an extension package | [Extension Authoring](./extension-authoring.md) |
 | Build the WebUI source | [WebUI Development](../webui/README.md) |
 
 If a command or screen no longer matches these docs, please [open an issue](https://github.com/HKUDS/nanobot/issues) with your nanobot version, operating system, and the page that needs correction.

docs/architecture.md

@@ -59,7 +59,7 @@ Provider metadata is centralized in `nanobot/providers/registry.py`. Configurati
 
 Provider selection uses:
 
-- explicit `agents.defaults.provider` or preset provider;
+- the active model preset's explicit provider;
 - provider registry keywords;
 - API key prefixes and API base URL hints;
 - local provider fallback when `apiBase` is configured;

docs/chat-commands.md

@@ -57,7 +57,7 @@ To switch presets for future turns:
 /model default
 ```
 
-Preset names come from the top-level `modelPresets` config. Switching affects only the current session and persists the selection in that session, so later turns keep using it across process restarts. It does not rewrite `config.json`, does not change other sessions, and does not alter an in-progress turn's captured model. Sessions without a saved selection follow `agents.defaults.modelPreset` (or the implicit `default` preset when it is omitted). See [Configuration: Model presets](./configuration.md#model-presets) for setup details.
+Preset names come from the top-level `modelPresets` config. Switching affects only the current session and persists the selection in that session, so later turns keep using it across process restarts. It does not rewrite `config.json`, does not change other sessions, and does not alter an in-progress turn's captured model. Sessions without a saved selection follow `agents.defaults.modelPreset`, or the concrete `modelPresets.default` entry when it is omitted. See [Configuration: Model presets](./configuration.md#model-presets) for setup details.
 
 ## Local triggers
 

docs/cli-reference.md

@@ -11,14 +11,13 @@ Use this page when you know what you want to run and need the command shape. For
 | Refresh config non-interactively | `nanobot onboard --refresh` | Preserves existing values and adds missing default fields without prompting |
 | Use guided setup | `nanobot onboard --wizard` | Best when you prefer prompts over hand-editing JSON |
 | Open the browser workbench | `nanobot webui` | Prepares local WebUI settings, starts the gateway, and opens the browser |
-| Check config without calling a model | `nanobot status` | Summarizes the selected config, workspace, active model, and providers |
+| Check readiness without calling a model | `nanobot status` | Summarizes config/workspace and validates the active provider/model configuration |
 | Send one test message | `nanobot agent -m "Hello!"` | First proof that install, config, provider, model, and workspace all work |
 | Chat in the terminal | `nanobot agent` | Interactive local chat; exit with `exit`, `/exit`, `:q`, or `Ctrl+D` |
 | Run the gateway directly | `nanobot gateway` | Service/ops command for WebUI, chat apps, cron, and heartbeat |
 | Deliver a local trigger | `nanobot trigger <id> "message"` | Created first with `/trigger <name>` in the target chat/session |
 | Serve an OpenAI-compatible API | `nanobot serve` | Starts `/v1/chat/completions`, `/v1/models`, and `/health` |
 | Check chat channel setup | `nanobot channels status` | Useful before starting `nanobot gateway` |
-| Manage extension packages | `nanobot extensions list` | Install, inspect, trust, enable, and remove native nanobot packages |
 | Manage optional features | `nanobot plugins list` | Shows channels and optional capabilities you can turn on |
 | Log in to QR/OAuth-style channels | `nanobot channels login <channel>` | Used by channels such as WhatsApp and WeChat |
 | Log in to OAuth model providers | `nanobot provider login <provider>` | Used by OpenAI Codex, xAI subscription, and GitHub Copilot providers |
@@ -71,6 +70,18 @@ Default paths:
 | Config | `~/.nanobot/config.json` |
 | Workspace | `~/.nanobot/workspace/` |
 
+## Status
+
+| Command | Description |
+|---|---|
+| `nanobot status` | Summarize the default config/workspace and check Agent provider/model readiness |
+| `nanobot status --config <path>` | Check a specific config file |
+| `nanobot status --workspace <path>` | Show status with a workspace override |
+
+Status does not send a model request. On success, run the printed
+`nanobot agent -m "Hello!"` command to verify network access and credentials. On failure,
+follow the printed WebUI **Settings → Models** or `nanobot onboard --wizard` route.
+
 ## Agent CLI
 
 | Command | Description |
@@ -249,39 +260,6 @@ nanobot channels status
 
 See [`chat-apps.md`](./chat-apps.md) for channel-specific setup.
 
-## Extensions
-
-Extension installation, trust, permission grants, and enablement are separate
-operations:
-
-| Command | Description |
-|---|---|
-| `nanobot extensions list` | Show installed packages and activation policy |
-| `nanobot extensions inspect <id>` | Show identity, dependencies, requested permissions, and diagnostics |
-| `nanobot extensions install <url> --kind git [--ref <ref>]` | Install from a Git branch, tag, or commit |
-| `nanobot extensions install <path> --kind local` | Install from a local package directory |
-| `nanobot extensions permissions <id> [permissions...]` | Replace the exact granted permission set; omit values to revoke all |
-| `nanobot extensions trust <id>` | Approve executing the installed package |
-| `nanobot extensions untrust <id>` | Revoke trust and stop activation |
-| `nanobot extensions enable <id>` | Allow activation when every other gate passes |
-| `nanobot extensions disable <id>` | Stop activation without uninstalling |
-| `nanobot extensions uninstall <id>` | Remove the user-scope package after confirmation |
-| `nanobot extensions uninstall <id> --yes` | Remove without an interactive confirmation |
-
-Example:
-
-```bash
-nanobot extensions install https://github.com/acme/nanobot-review.git
-nanobot extensions inspect acme.review
-nanobot extensions permissions acme.review workspace.read
-nanobot extensions trust acme.review
-nanobot extensions enable acme.review
-```
-
-Installed packages live under `~/.nanobot/extensions/`. They do not execute
-until trusted. See [Extensions](./extensions.md) for the safety model and
-[Extension Authoring](./extension-authoring.md) for the native package contract.
-
 ## Optional Features
 
 Use these commands when you want nanobot to add or remove a built-in capability

docs/concepts.md

@@ -87,9 +87,9 @@ The WebUI launcher is the normal browser entry point. Underneath, the gateway ke
 
 ## Provider and Model Selection
 
-The active model should normally come from a named `modelPresets` entry selected by `agents.defaults.modelPreset`. Direct `agents.defaults.provider` and `agents.defaults.model` still form the implicit `default` preset for older or minimal configs. The active provider is resolved in this order:
+The active model comes from the named `modelPresets` entry selected by `agents.defaults.modelPreset`, or from the concrete `modelPresets.default` entry when that selector is omitted. The active provider is resolved in this order:
 
-1. If the active preset provider or implicit default provider is not `"auto"`, nanobot uses that provider.
+1. If the active preset provider is not `"auto"`, nanobot uses that provider.
 2. If provider is `"auto"`, nanobot tries to infer the provider from the model name, configured API keys, local provider base URLs, or gateway providers.
 3. OAuth providers such as OpenAI Codex and GitHub Copilot require explicit login and explicit provider/model selection inside the active preset.
 

docs/configuration.md

@@ -27,7 +27,6 @@ the focused guides first and come back here for exact fields and defaults.
 | Configure model fallback | [`guides/configure-model-fallback.md`](./guides/configure-model-fallback.md) |
 | Add an OpenAI-compatible provider | [`guides/configure-openai-compatible-provider.md`](./guides/configure-openai-compatible-provider.md) |
 | Add Langfuse observability | [`guides/configure-langfuse-observability.md`](./guides/configure-langfuse-observability.md) |
-| Install and govern extensions | [`extensions.md`](./extensions.md) |
 | Secure a local AI agent | [`guides/secure-local-ai-agent.md`](./guides/secure-local-ai-agent.md) |
 | Deploy the gateway | [`guides/deploy-nanobot-gateway.md`](./guides/deploy-nanobot-gateway.md) |
 
@@ -46,7 +45,6 @@ the focused guides first and come back here for exact fields and defaults.
 | Configure web search and fetch | [Web Tools](#web-tools) |
 | Enable image generation | [Image Generation](#image-generation) |
 | Add MCP servers | [MCP](#mcp-model-context-protocol) |
-| Enable or disable external extensions | [Extensions](#extensions) |
 | Review shell, workspace, and SSRF controls | [Security](#security) |
 | Control access and pairing | [Pairing](#pairing) |
 | Tune gateway jobs, sessions, and tools | [Gateway Heartbeat](#gateway-heartbeat), [Auto Compact](#auto-compact), [Unified Session](#unified-session), [Tool Hint Max Length](#tool-hint-max-length) |
@@ -66,7 +64,6 @@ If the WebUI does not expose the option you need, start from the task below. Mos
 | Enable web search or fetch | `tools.web.search.*`, `tools.web.fetch.*`, optional `tools.ssrfWhitelist` | Ask a question that requires current web information, then inspect logs if needed | [Web Tools](#web-tools), [Security](#security) |
 | Enable image generation | `tools.imageGeneration.enabled`, `tools.imageGeneration.provider`, `tools.imageGeneration.model`, matching provider credentials | Enable Image Generation in the WebUI and send one image request | [Image Generation](#image-generation) |
 | Add external tools through MCP | `tools.mcpServers.<name>` | Start `nanobot gateway --verbose` and check startup/tool logs | [MCP](#mcp-model-context-protocol) |
-| Enable external extension packages | `extensions.enabled` | `nanobot extensions list`, then inspect the package | [Extensions](#extensions), [Extension guide](./extensions.md) |
 | Tighten tool and network safety | `tools.restrictToWorkspace`, `tools.exec.sandbox`, `tools.ssrfWhitelist`, `channels.*.allowFrom` | Run the same workflow through the channel or CLI you plan to expose | [Security](#security), [Pairing](#pairing) |
 | Tune request timeouts or process concurrency | `NANOBOT_LLM_TIMEOUT_S`, `NANOBOT_STREAM_IDLE_TIMEOUT_S`, `NANOBOT_MAX_CONCURRENT_REQUESTS` | Start nanobot from the same environment and inspect startup/runtime logs | [Runtime Environment Variables](#runtime-environment-variables) |
 | Run multiple isolated bots | separate `--config` and `--workspace` paths, plus distinct `gateway.port` or channel ports when processes run together | Use the same explicit paths with `nanobot status`, `agent`, `webui`, `gateway`, and `serve` | [Multiple Instances](./multiple-instances.md), [CLI Reference](./cli-reference.md) |
@@ -93,7 +90,9 @@ Instead of storing secrets directly in `config.json`, you can use `${VAR_NAME}`
 
 Any string value in `config.json` can use `${VAR_NAME}`. Resolution runs once at startup, in memory only — resolved values are never written back to disk, so editing config through `nanobot onboard` or the WebUI preserves the placeholder.
 
-If a referenced variable is unset, nanobot fails fast at startup with `ValueError: Environment variable 'NAME' referenced in config is not set`.
+If a referenced variable is unset, nanobot fails fast and reports the exact config field
+and variable name without echoing the field value. Run `nanobot status` with the same
+`--config` path to inspect the problem.
 
 ### More examples
 
@@ -260,7 +259,7 @@ Tracing covers the providers that go through nanobot's OpenAI-compatible client
 > - **ModelScope**: If you're using ModelScope's OpenAI-compatible endpoint, set `"apiBase": "https://api-inference.modelscope.cn/v1"` in your modelscope provider config.
 > - **StepFun Step Plan**: If you're on StepFun's Step Plan subscription, set `"apiBase": "https://api.stepfun.ai/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 thinking mode**: MiMo models (e.g. `mimo-v2.5-pro`) default to enabled thinking. Set `reasoningEffort: "none"` on the active model preset 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.
 > - **Custom OpenAI-compatible providers**: Besides the built-in `custom` provider, any extra key under `providers` can define its own OpenAI-compatible endpoint. For example, `providers.companyProxy.apiBase` plus `modelPresets.primary.provider: "companyProxy"` creates a separate custom provider. Set `apiBase`; set `apiKey` only when the endpoint requires it. This named-custom path uses the OpenAI-compatible request format only. For Anthropic-compatible proxies, use `providers.anthropic.apiBase` with `provider: "anthropic"`.
 > - **Provider-scoped proxy**: `providers.<name>.proxy` routes only that provider through an HTTP proxy. It is supported for OpenAI-compatible providers, `openai_codex`, and `xai_grok`. Native provider backends such as `anthropic`, `bedrock`, `azure_openai`, and `github_copilot` reject `proxy`.
@@ -1347,20 +1346,12 @@ Contributor notes for adding new providers live in [`development.md`](./developm
 
 ## Model Presets
 
-Model presets let you name a complete model configuration and select one per session with `/model <preset>`. They are the recommended way to configure models because the same names can be reused for new-session defaults, chat-command switching, and fallback chains.
+Model presets let you name a complete model configuration and select one per session with `/model <preset>`. Configure all model, provider, generation, context-window, and image-input settings under top-level `modelPresets`; `agents.defaults` only selects preset names.
 
-Existing configs do not need to change. Direct `agents.defaults.model`, `provider`, `maxTokens`, `contextWindowTokens`, `temperature`, and `reasoningEffort` fields still define the implicit `default` preset. For new configs, prefer top-level `modelPresets` plus `agents.defaults.modelPreset`.
+On first load, nanobot migrates legacy model fields from `agents.defaults` and inline fallback objects in `config.json` into named presets, then atomically rewrites the file and logs a warning. If a concrete `modelPresets.default` and legacy direct fields both exist, the concrete preset wins and the warning explains that the conflicting legacy fields were removed. Legacy model fields supplied through nested `NANOBOT_AGENTS` environment settings are not supported and produce a warning with instructions to move them into `modelPresets`.
 
 ```json
 {
-  "modelPresets": {
-    "fast": {
-      "provider": "openrouter",
-      "model": "anthropic/claude-sonnet-4.5",
-      "maxTokens": 4096,
-      "contextWindowTokens": 65536
-    }
-  },
   "agents": {
     "defaults": {
       "modelPreset": "fast",
@@ -1368,6 +1359,14 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
     }
   },
   "modelPresets": {
+    "default": {
+      "label": "Default",
+      "model": "claude-opus-4-5",
+      "provider": "anthropic",
+      "maxTokens": 8192,
+      "contextWindowTokens": 200000,
+      "supportsImageInput": true
+    },
     "fast": {
       "label": "Fast",
       "model": "gpt-4.1-mini",
@@ -1375,7 +1374,8 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
       "maxTokens": 4096,
       "contextWindowTokens": 128000,
       "temperature": 0.2,
-      "reasoningEffort": "low"
+      "reasoningEffort": "low",
+      "supportsImageInput": true
     },
     "deep": {
       "label": "Deep",
@@ -1397,7 +1397,7 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
 }
 ```
 
-`modelPresets` is a top-level object. The keys under it (`fast`, `deep`, `coding`, etc.) are user-defined preset names. Each preset supports:
+`modelPresets` is a top-level object. `default` is required; its other keys (`fast`, `deep`, `coding`, etc.) are user-defined preset names. Each preset supports:
 
 | Field | Description |
 |-------|-------------|
@@ -1408,25 +1408,30 @@ Existing configs do not need to change. Direct `agents.defaults.model`, `provide
 | `contextWindowTokens` | Context window size used by prompt building and consolidation decisions. |
 | `temperature` | Sampling temperature. |
 | `reasoningEffort` | Optional reasoning/thinking setting. Provider support varies. |
+| `supportsImageInput` | `true` always sends images, `false` strips them before the first request, and `null`/omitted uses automatic retry-on-unsupported behavior. |
 
-`default` is reserved and always means the implicit preset built from direct `agents.defaults.*` fields; do not define `modelPresets.default`. Use `/model default` to switch back to those direct fields in an existing config.
+Every config has a concrete `modelPresets.default` entry. Use `/model default` to switch a session back to it. Configure the default model by editing that preset, not by adding model fields under `agents.defaults`.
 
-Set `agents.defaults.modelPreset` to choose the preset followed by sessions that have no saved model selection. When `modelPreset` is `null` or omitted, such sessions follow the implicit `default` preset from direct `agents.defaults.*` fields. `/model <preset>` saves an override in the current session, so its future turns keep that preset across process restarts while other sessions remain unchanged. The command does not write the selection back to `config.json`.
+Set `agents.defaults.modelPreset` to choose the preset followed by sessions that have no saved model selection. When it is omitted, such sessions use `modelPresets.default`. `/model <preset>` saves an override in the current session, so its future turns keep that preset across process restarts while other sessions remain unchanged. The command does not write the selection back to `config.json`.
 
 ### Model Fallbacks
 
-`agents.defaults.fallbackModels` defines an ordered failover chain for the active model configuration. The primary model is still selected by `agents.defaults.modelPreset` or, in older configs, by the implicit `default` preset from direct `agents.defaults.*` fields.
+`agents.defaults.fallbackModels` defines an ordered failover chain for the active model configuration. The primary model is selected by `agents.defaults.modelPreset`, or by `modelPresets.default` when that selector is omitted.
 
-Each fallback candidate can be either:
+Each fallback candidate is a preset name from `modelPresets`, such as `"deep"`. The preset's complete model, provider, generation, context-window, and image-input configuration is used.
-
-- A preset name from `modelPresets`, such as `"deep"`. This is the recommended form. The preset's full model, provider, generation, and context-window config is used.
-- An inline fallback object with at least `provider` and `model`. Optional `maxTokens`, `contextWindowTokens`, and `temperature` fields inherit from the active primary config when omitted. `reasoningEffort` does not inherit; omit it to leave reasoning off for that fallback, or set it explicitly for models that support reasoning.
 
 Preset fallback chain:
 
 ```json
 {
   "modelPresets": {
+    "default": {
+      "model": "gpt-4.1-mini",
+      "provider": "openai",
+      "maxTokens": 4096,
+      "contextWindowTokens": 128000,
+      "temperature": 0.2
+    },
     "fast": {
       "model": "gpt-4.1-mini",
       "provider": "openai",
@@ -1457,37 +1462,7 @@ Preset fallback chain:
 }
 ```
 
-String entries are preset names, not raw model names. In the example above, `"deep"` means `modelPresets.deep`; nanobot will not interpret it as a provider model ID. Changing a preset updates both `/model <preset>` switching and any fallback chain that references it.
+String entries are preset names, not raw model names. In the example above, `"deep"` means `modelPresets.deep`; nanobot will not interpret it as a provider model ID. Changing a preset updates both `/model <preset>` switching and any fallback chain that references it. `fallbackModels` belongs under `agents.defaults`, not inside individual `modelPresets` entries.
-
-Inline fallback object:
-
-```json
-{
-  "modelPresets": {
-    "fast": {
-      "provider": "openrouter",
-      "model": "anthropic/claude-sonnet-4.5",
-      "maxTokens": 4096,
-      "contextWindowTokens": 65536
-    }
-  },
-  "agents": {
-    "defaults": {
-      "modelPreset": "fast",
-      "fallbackModels": [
-        {
-          "provider": "deepseek",
-          "model": "deepseek-v4-pro",
-          "maxTokens": 4096,
-          "contextWindowTokens": 262144
-        }
-      ]
-    }
-  }
-}
-```
-
-Use inline objects only when a fallback is not worth naming as a reusable preset. `fallbackModels` belongs under `agents.defaults`, not inside individual `modelPresets` entries.
 
 Failover normally runs when the primary provider returns a fallbackable model/provider error before any answer text has been streamed. Stream-stall timeouts are the recovery exception: if the provider already emitted partial answer text and then stalls, nanobot closes the current stream segment and retries/fails over in a new segment. Typical fallback cases include timeouts, connection errors, 5xx server errors, 429 rate limits, overloads, authentication/permission failures such as invalid or expired credentials, and quota/balance exhaustion. It does not run for malformed requests, content filtering/refusals, or context-length/message-format errors.
 
@@ -1559,7 +1534,6 @@ Global settings that apply to all channels. Configure under the `channels` secti
   "channels": {
     "sendProgress": true,
     "sendToolHints": true,
-    "extractDocumentText": true,
     "sendMaxRetries": 3,
     "telegram": {
       "enabled": false
@@ -1573,9 +1547,15 @@ Global settings that apply to all channels. Configure under the `channels` secti
 | `sendProgress` | `true` | Stream agent's text progress to the channel |
 | `sendToolHints` | `true` | 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 / Mattermost 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. PDF, DOCX, XLSX, and PPTX readers are included in the standard installation. 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) |
 
+Non-image attachments are included in the user message as local path references, without
+injecting their contents into the model prompt. When file tools are enabled, the agent
+can inspect supported text, PDF, DOCX, XLSX, and PPTX files on demand with `read_file`,
+or pass the original path to another tool when exact file bytes are required. The deprecated
+`channels.extractDocumentText` setting is accepted for compatibility but ignored.
+Normal tool workspace and media access rules still apply to attachment paths.
+
 `channels.transcriptionProvider` and `channels.transcriptionLanguage` are deprecated compatibility fields. They remain as a read-only fallback for older configs, but new configuration should use top-level `transcription.provider` and `transcription.language`.
 
 `sendProgress` and `sendToolHints` can also be overridden per channel. The global values stay as defaults for channels that do not set their own value:
@@ -2000,7 +1980,7 @@ For API keys, tokens, and other secrets, see [Environment Variables for Secrets]
 | `tools.exec.pathAppend` | `""` | Extra directories to append to `PATH` when running shell commands (e.g. `/usr/sbin` for `ufw`). |
 | `tools.exec.sandboxRoBinds` | `[]` | Extra absolute paths to read-only bind into the `"bwrap"` sandbox with `--ro-bind-try`, such as `/home/user/.local/bin` or `/home/user/.cargo/bin` when those paths are also in `pathPrepend`/`pathAppend`. These roots are also accepted by the shell absolute-path guard only while bwrap is active. Bind only directories whose contents are safe for agent commands to read; paths equal to or containing the active workspace are ignored so they cannot uncover its masked parent directory. |
 | `tools.exec.sandboxRwBinds` | `[]` | Extra absolute paths to read-write bind into the `"bwrap"` sandbox with `--bind-try`, for trusted tool caches or scratch directories. Use sparingly: paths listed here are intentionally writable by shell commands inside the sandbox. Paths equal to or containing the active workspace are ignored. |
-| `tools.webuiAllowRemotePackageInstall` | `false` | When `false`, the WebUI can install optional support or extension packages only from a browser opened on the same machine as nanobot. Set to `true` only when a trusted remote admin may install packages into this environment. |
+| `tools.webuiAllowRemotePackageInstall` | `false` | When `false`, the WebUI can install missing optional packages only from a browser opened on the same machine as nanobot. Set to `true` only when a trusted remote admin is allowed to install Python packages into this nanobot environment. |
 | `tools.ssrfWhitelist` | `[]` | CIDR ranges exempted from the shared SSRF guard used by web fetches and HTTP/SSE MCP connections. Prefer exact host CIDRs such as `192.168.1.50/32`; broad ranges increase SSRF exposure. |
 | `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. |
 
@@ -2236,30 +2216,6 @@ When enabled, all incoming messages — regardless of which channel they arrive
 
 > This is designed for single-user, multi-device setups. It is **off by default** — existing users see zero behavior change.
 
-## Extensions
-
-Use the WebUI **Extensions** page or `nanobot extensions` commands for normal
-installation and trust decisions. Extension support can be disabled globally:
-
-```json
-{
-  "extensions": {
-    "enabled": true
-  }
-}
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `extensions.enabled` | `true` | Enable external extension discovery and activation |
-
-Installed packages and their trust, permission, and activation state live
-under `~/.nanobot/extensions/`. Managing an extension does not rewrite
-`config.json`.
-
-See [Extensions](./extensions.md) for the safe install flow and
-[Extension Authoring](./extension-authoring.md) for the package contract.
-
 ## Disabled Skills
 
 nanobot ships with built-in skills, and your workspace can also define custom skills under `skills/`. If you want to hide specific skills from the agent, set `agents.defaults.disabledSkills` to a list of skill directory names:

docs/deployment.md

@@ -39,6 +39,23 @@ Run nanobot online without managing a server. The blueprint deploys the gateway
 
 [Review the deployment blueprint](../render.yaml)
 
+### First Deployment
+
+1. Click **Deploy to Render**, sign in, and review the Blueprint. It creates one Starter web service and a 1 GB persistent disk.
+2. Enter your `ANTHROPIC_API_KEY`. Set `NANOBOT_WEB_TOKEN` to a new random value and save it in your password manager; this is the password for the public WebUI.
+3. Create the Blueprint and wait for the service status to become **Live**. The first build can take several minutes.
+4. Open the generated `onrender.com` URL. The **Authentication required** page means the gateway is running: enter the same `NANOBOT_WEB_TOKEN` value to open the WebUI.
+
+The model API key is used by nanobot to call Anthropic. The Web token only protects access to this deployment; do not share it in issues, screenshots, or chat.
+
+### Updates and Data
+
+The Blueprint disables automatic deploys so upstream repository changes do not unexpectedly restart your agent. To update, open the service in the Render Dashboard and choose **Manual Deploy → Deploy latest commit**.
+
+The persistent disk keeps `config.json`, sessions, memory, WebUI history, cron state, media, and logs across restarts and updates. The deployment initializes `config.json` only when it does not already exist, so settings changed later in the WebUI are not replaced on every boot.
+
+If deployment fails, open the service **Logs** page first. A missing model key fails provider requests after startup, while an incorrect Web token leaves you on the authentication page.
+
 ## Docker
 
 > [!TIP]

docs/extension-authoring.md

@@ -1,147 +0,0 @@
-# Extension Authoring
-
-A native nanobot extension is a directory containing:
-
-```text
-nanobot-review/
-├── nanobot.extension.json
-└── extension.py
-```
-
-The manifest describes identity, activation prerequisites, and requested
-permissions. The Python entry point performs the real registration. This keeps
-one authoritative source for tool, command, and hook ownership.
-
-## Manifest
-
-```json
-{
-  "id": "acme.review",
-  "name": "Acme Review",
-  "version": "1.0.0",
-  "entry": "extension:register",
-  "description": "Adds repository review tools.",
-  "apiVersion": 1,
-  "license": "MIT",
-  "homepage": "https://github.com/acme/nanobot-review",
-  "dependencies": [
-    {
-      "kind": "executable",
-      "name": "git"
-    }
-  ],
-  "permissions": [
-    {
-      "name": "workspace.read",
-      "reason": "Read files selected for review."
-    }
-  ]
-}
-```
-
-Required fields are `id`, `name`, and `version`. `entry` defaults to
-`"extension:register"` and `apiVersion` defaults to `1`.
-
-IDs use lowercase letters, digits, dots, underscores, and hyphens. Entry points
-use `module:function` syntax and must resolve inside the package.
-
-### Dependencies
-
-| Kind | Meaning |
-|---|---|
-| `python` | Installed Python distribution; `specifier` accepts a version constraint |
-| `executable` | Command available on `PATH` |
-| `environment` | Non-empty environment variable |
-
-Set `"optional": true` when a missing dependency should not block activation.
-
-### Permissions
-
-Permissions are lowercase namespaced identifiers chosen by the package, such
-as `workspace.read` or `network`. Give each permission a concrete reason.
-Activation waits until every requested permission is granted.
-
-The host currently uses permissions as explicit user consent. They do not
-sandbox Python code, so do not describe a permission as stronger isolation
-than it provides.
-
-## Registration API
-
-The entry point receives `PythonExtensionApi` and must return `None`:
-
-```python
-from typing import Any
-
-from nanobot.agent.tools.base import Tool
-
-
-class ReviewTool(Tool):
-    @property
-    def name(self) -> str:
-        return "review_repository"
-
-    @property
-    def description(self) -> str:
-        return "Review the current repository."
-
-    @property
-    def parameters(self) -> dict[str, Any]:
-        return {"type": "object", "properties": {}}
-
-    async def execute(self, **kwargs: Any) -> str:
-        return "No findings."
-
-
-def register(api) -> None:
-    api.register_tool(ReviewTool())
-```
-
-The API has three stable methods:
-
-```python
-api.register_tool(tool)
-api.register_command("review", handler)
-api.register_hook_factory(factory)
-```
-
-Command handlers use nanobot's `CommandContext` and return an
-`OutboundMessage` or `None`. Hook factories receive `AgentTurnHookContext` and
-return an `AgentHook` or `None`.
-
-Do not modify `AgentLoop` or global registries directly. The API tags every
-registration with the extension ID so reload, failure rollback, and uninstall
-can remove exactly what the package owns.
-
-## Collision and failure behavior
-
-Tool and command names are unique across core and active extensions. If an
-extension registers a duplicate name, activation fails for that extension and
-all of its partial registrations are rolled back.
-
-Missing dependencies are reported as diagnostics instead of crashing the
-gateway.
-
-## Develop locally
-
-1. Create the manifest and entry module.
-2. Install the directory with `--kind local`.
-3. Inspect and grant its permissions.
-4. Trust it.
-5. Reinstall after editing so nanobot records a new integrity digest.
-
-```bash
-nanobot extensions install "$PWD" --kind local
-nanobot extensions inspect acme.review
-nanobot extensions permissions acme.review workspace.read
-nanobot extensions trust acme.review
-```
-
-Keep tests in the extension repository. At minimum, test registration,
-duplicate-name failure, and behavior when each required dependency is missing.
-
-## Distribution
-
-Publish the directory in a Git repository. Users can pin a release tag or
-commit with `--ref`. The repository root must contain
-`nanobot.extension.json`; install scripts and generated compatibility manifests
-are not part of the native contract.

docs/extensions.md

@@ -1,89 +0,0 @@
-# Extensions
-
-Extensions add native tools, slash commands, or lifecycle hooks without
-changing nanobot core. An extension is a Python package with one manifest and
-one registration entry point.
-
-Use an extension when a capability needs executable integration with nanobot.
-Use a [skill](./skills.md) when instructions alone are enough, an App when the
-agent should call an external CLI, and MCP when a service already exposes an
-MCP server.
-
-## Install
-
-Install from a Git repository:
-
-```bash
-nanobot extensions install https://github.com/acme/nanobot-review.git
-```
-
-Install a local package while developing it:
-
-```bash
-nanobot extensions install /absolute/path/to/nanobot-review --kind local
-```
-
-Git installs may select a branch, tag, or commit:
-
-```bash
-nanobot extensions install https://github.com/acme/nanobot-review.git \
-  --ref v1.2.0
-```
-
-The WebUI **Extensions** page exposes the same Git and local installation
-flows. Local paths are accepted only from a browser running on the nanobot
-host.
-
-## Review before activation
-
-New packages are installed enabled but untrusted. They cannot execute until
-you review the manifest, grant every requested permission, and trust them:
-
-```bash
-nanobot extensions inspect acme.review
-nanobot extensions permissions acme.review workspace.read
-nanobot extensions trust acme.review
-```
-
-Use `list` to check the result:
-
-```bash
-nanobot extensions list
-```
-
-Disable, untrust, or remove a package at any time:
-
-```bash
-nanobot extensions disable acme.review
-nanobot extensions untrust acme.review
-nanobot extensions uninstall acme.review
-```
-
-Changes made in the WebUI reload its gateway extension host immediately.
-Changes made by the standalone CLI take effect the next time the gateway or
-agent process starts. Failed registrations are rolled back and reported as
-diagnostics.
-
-## Safety model
-
-Extensions are executable Python code. nanobot provides these controls:
-
-- packages are copied into `~/.nanobot/extensions/` with an integrity digest;
-- package symlinks and special files are rejected;
-- installation, permission grants, trust, and activation are separate steps;
-- changed package contents invalidate trust;
-- registration is transactional, so a failed extension does not leave tools,
-  commands, or hooks behind;
-- remote WebUI clients cannot grant trust or permissions.
-
-Permission declarations are consent gates, not an operating-system sandbox.
-Only install code you are willing to run with the same account as nanobot.
-
-## Package compatibility
-
-The core runtime intentionally executes only the native nanobot Python
-contract. Pi and OpenClaw packages are not loaded directly. Compatibility
-adapters can be distributed as separate nanobot extensions later without
-adding JavaScript runtimes or package-market policy to the agent core.
-
-See [Extension Authoring](./extension-authoring.md) to build a package.

docs/memory.md

@@ -197,13 +197,13 @@ Dream is configured under `agents.defaults.dream`:
 |-------|---------|
 | `intervalH` | How often Dream runs, in hours |
 | `cron` | Cron expression override (takes precedence over `intervalH`) |
-| `modelOverride` | Optional Dream-specific model override *(pending implementation)* |
+| `modelOverride` | Optional model preset name used for Dream |
 
 In practical terms:
 
 - `intervalH` is the normal way to configure Dream frequency. Internally it runs as an `every` schedule.
 - `cron` overrides `intervalH` when set, allowing precise cron expressions (e.g. `0 */4 * * *`).
-- `modelOverride` is reserved for a future release. Currently Dream uses the same model as the main agent.
+- `modelOverride` selects a named entry from `model_presets` for Dream. It accepts preset names only; raw model identifiers are not supported. If omitted, Dream uses the main agent's selected runtime.
 
 ## In Practice
 

docs/provider-cookbook.md

@@ -34,7 +34,7 @@ Match the recipe to the credential or endpoint you already have:
 5. Run `nanobot agent -m "Hello!"`.
 6. If the CLI works, then connect WebUI, gateway, or chat apps.
 
-The active model should normally come from `agents.defaults.modelPreset`, and that name should point to an entry in `modelPresets`. Direct `agents.defaults.provider` and `agents.defaults.model` still work for older configs, but presets are easier to switch and easier to reuse as fallbacks.
+The active model comes from `agents.defaults.modelPreset`, and that name must point to an entry in `modelPresets`. Configure model/provider settings in presets so they can be switched and reused as fallbacks.
 
 ## Secret Setup
 

docs/providers.md

@@ -10,7 +10,7 @@ For every setup, answer three questions:
 2. What model name does that provider expect?
 3. Does the provider need `apiKey`, `apiBase`, OAuth login, cloud credentials, or only a local server URL?
 
-Prefer a named `modelPresets` entry for the model/provider pair, then select it with `agents.defaults.modelPreset`. Direct `agents.defaults.provider` and `agents.defaults.model` still work for existing configs, but presets make runtime `/model` switching and fallback chains clearer. Pin `provider` inside the preset while setting up; you can switch back to `"auto"` later.
+Define the model/provider pair as a named `modelPresets` entry, then select it with `agents.defaults.modelPreset`. Pin `provider` inside the preset while setting up; you can switch back to `"auto"` later.
 
 ## Choose a Provider Without Guessing
 
@@ -462,14 +462,14 @@ Each command authenticates the selected provider and makes its current default m
 
 ## Provider Resolution
 
-The recommended path is a named preset selected by `agents.defaults.modelPreset`. The effective model parameters come from:
+The effective model parameters come from:
 
 1. the named `modelPresets` entry referenced by `agents.defaults.modelPreset`;
-2. otherwise the implicit `default` preset built from `agents.defaults.model`, `provider`, `maxTokens`, `contextWindowTokens`, `temperature`, and related fields.
+2. otherwise the concrete `modelPresets.default` entry.
 
 Provider selection follows this practical rule:
 
-- Explicit `provider` in the active preset or implicit default config wins.
+- Explicit `provider` in the active preset wins.
 - `provider: "auto"` tries model-name keywords, configured keys, local base URLs, and gateway providers.
 - Gateway providers such as OpenRouter and AiHubMix can route many model families, so the model name must be valid for that gateway.
 - Local providers should normally be explicit because generic local model names such as `llama3.2` do not always contain provider keywords.
@@ -491,6 +491,14 @@ Model presets are the recommended model configuration surface. Use them when you
 ```json
 {
   "modelPresets": {
+    "default": {
+      "label": "Default",
+      "provider": "anthropic",
+      "model": "claude-opus-4-5",
+      "maxTokens": 8192,
+      "contextWindowTokens": 200000,
+      "temperature": 0.1
+    },
     "fast": {
       "label": "Fast",
       "provider": "openrouter",
@@ -516,7 +524,7 @@ Model presets are the recommended model configuration surface. Use them when you
 }
 ```
 
-The preset name `default` is reserved for the implicit `agents.defaults` settings. Do not define `modelPresets.default`; use `/model default` to return to the direct `agents.defaults.*` fields in older configs.
+Every config has a concrete `modelPresets.default` entry. Use `/model default` to return to it. Legacy direct model fields in `agents.defaults` are migrated from `config.json` on first load; configure presets only after migration.
 
 ## Fallback Models
 
@@ -525,6 +533,14 @@ Fallbacks are useful for transient provider failures, rate limits, or model avai
 ```json
 {
   "modelPresets": {
+    "default": {
+      "label": "Default",
+      "provider": "openrouter",
+      "model": "anthropic/claude-sonnet-4.5",
+      "maxTokens": 4096,
+      "contextWindowTokens": 65536,
+      "temperature": 0.1
+    },
     "fast": {
       "label": "Fast",
       "provider": "openrouter",
@@ -559,35 +575,7 @@ Fallbacks are useful for transient provider failures, rate limits, or model avai
 }
 ```
 
-String entries in `fallbackModels` are preset names, not raw model names. nanobot tries them in order after the active preset. Each fallback preset uses its own `provider`, `model`, `maxTokens`, `contextWindowTokens`, `temperature`, and optional `reasoningEffort`.
+String entries in `fallbackModels` are preset names, not raw model names. nanobot tries them in order after the active preset. Each fallback preset uses its own `provider`, `model`, `maxTokens`, `contextWindowTokens`, `temperature`, optional `reasoningEffort`, and `supportsImageInput` policy.
-
-Use inline fallback objects only when a model is not worth naming as a preset:
-
-```json
-{
-  "modelPresets": {
-    "fast": {
-      "provider": "openrouter",
-      "model": "anthropic/claude-sonnet-4.5",
-      "maxTokens": 4096,
-      "contextWindowTokens": 65536
-    }
-  },
-  "agents": {
-    "defaults": {
-      "modelPreset": "fast",
-      "fallbackModels": [
-        {
-          "provider": "deepseek",
-          "model": "deepseek-v4-pro",
-          "maxTokens": 4096,
-          "contextWindowTokens": 262144
-        }
-      ]
-    }
-  }
-}
-```
 
 `fallbackModels` belongs under `agents.defaults`, not inside each preset. If fallback candidates use smaller context windows, nanobot builds context using the smallest window in the active chain so every candidate can receive the same prompt. See [`configuration.md#model-fallbacks`](./configuration.md#model-fallbacks) for failure conditions.
 

docs/python-sdk.md

@@ -266,21 +266,10 @@ The config controls what nanobot may use. The workspace is where nanobot keeps
 state for that instance. See [multiple-instances.md](multiple-instances.md) for
 multi-instance CLI and gateway examples.
 
-### Choose a default or per-run model
+### Choose a default or per-run model preset
 
-Set the SDK instance default model when you create the bot:
+Define complete model choices under `modelPresets` in `config.json`, then select
-
+them by name for the SDK instance or for one run:
-```python
-bot = Nanobot.from_config(model="openai/gpt-4.1")
-```
-
-Override the model for one run without changing the instance default:
-
-```python
-result = await bot.run("Summarize this file", model="openai/gpt-4.1-mini")
-```
-
-Model presets from `config.json` work the same way:
 
 ```python
 bot = Nanobot.from_config(model_preset="fast")
@@ -288,7 +277,8 @@ bot = Nanobot.from_config(model_preset="fast")
 result = await bot.run("Think deeply about this bug", model_preset="reasoning")
 ```
 
-`model` and `model_preset` are mutually exclusive.
+The public SDK accepts preset names rather than raw model IDs. This keeps provider,
+generation, context-window, fallback, and image-input settings together.
 
 For first setup, prefer named presets in `config.json`. Mixing an API key from
 one provider with a model ID from another is the most common first-run failure.
@@ -463,7 +453,7 @@ configuration docs remain the source of truth for the runtime around it:
 
 ## API Reference
 
-### `Nanobot.from_config(config_path=None, *, workspace=None, model=None, model_preset=None)`
+### `Nanobot.from_config(config_path=None, *, workspace=None, model_preset=None)`
 
 Create a `Nanobot` instance from a config file.
 
@@ -471,11 +461,9 @@ Create a `Nanobot` instance from a config file.
 |-------|------|---------|-------------|
 | `config_path` | `str \| Path \| None` | `None` | Path to `config.json`. Defaults to `~/.nanobot/config.json`. |
 | `workspace` | `str \| Path \| None` | `None` | Override the workspace directory from config. |
-| `model` | `str \| None` | `None` | Override the instance default model. |
 | `model_preset` | `str \| None` | `None` | Override the instance default model preset from `config.json`. |
 
 Raises `FileNotFoundError` if an explicit config path does not exist.
-Raises `ValueError` if both `model` and `model_preset` are provided.
 
 ### `await bot.run(...)`
 
@@ -490,14 +478,14 @@ Run the agent once and return a `RunResult`.
 | `sender_id` | `str` | `"user"` | Logical sender identifier used in runtime context. |
 | `media` | `list[str] \| None` | `None` | Optional local media paths attached to the message. |
 | `ephemeral` | `bool` | `False` | Run without persisting the turn or compacting session history. |
+| `attributes` | `Mapping[str, Any] \| None` | `None` | Caller-owned request data for host integrations. It is available to context providers and turn-hook factories, but is not added to trusted message metadata or persisted in session messages. |
 | `hooks` | `list[AgentHook] \| None` | `None` | Lifecycle hooks for this run only. |
-| `model` | `str \| None` | `None` | Override the model for this run only. |
 | `model_preset` | `str \| None` | `None` | Override the model preset for this run only. |
 
 Without an override, a run uses the preset saved in its session, or the configured
-default when that session has no saved selection. `model` and `model_preset` are
+default when that session has no saved selection. A per-run `model_preset` override
-mutually exclusive per-run overrides; they do not change the saved session selection
+does not change the saved session selection or `bot.runtime.model` after the run
-or `bot.runtime.model` after the run completes.
+completes.
 
 ### `await bot.run_streamed(...)`
 
@@ -534,7 +522,7 @@ async for event in bot.stream("Generate a long answer"):
 | `await aclose()` | Close the stream; equivalent cleanup primitive for `async with` / manual lifecycle code. |
 
 SDK runs with different session keys may overlap, including runs with per-run
-`model` or `model_preset` overrides. Each run receives an immutable runtime without
+`model_preset` overrides. Each run receives an immutable runtime without
 mutating the instance default. Runs sharing one session key remain serialized.
 
 ### `StreamEvent`
@@ -631,9 +619,96 @@ Do not expose exported snapshots directly to chat users.
 |-------------------|-------------|
 | `model` | Current runtime model name. |
 | `workspace` | Current runtime workspace path. |
+| `add_context_provider(provider)` | Register an async per-turn context provider and return an unsubscribe callback. |
+| `on_session_turn_persisted(handler)` | Register a best-effort sync or async callback for locally persisted turns and return an unsubscribe callback. |
 | `await compact_session(session_key)` | Run token/replay-window consolidation for a session. |
 | `await compact_idle_session(session_key, max_suffix=8)` | Run idle-session compaction and return its summary. |
 
+### Host integration context and persisted-turn callbacks
+
+Host applications can attach external context without copying or modifying the
+nanobot agent loop. A context provider receives a `RequestContext` before each
+model turn and may return one or more `RuntimeContextBlock` values. Use
+`attributes` for caller-owned routing data; nanobot keeps it separate from
+trusted channel metadata and does not persist it in session messages.
+
+`on_session_turn_persisted()` invokes its callback after a non-ephemeral turn
+has been saved. The callback receives `SessionTurnPersisted` and may read the
+completed transcript through `bot.sessions`. Callbacks run in registration
+order, and async callbacks are awaited before the run continues. They are
+observational: callback exceptions are logged and suppressed so the completed
+local turn remains successful. Durable external synchronization must catch
+failures and persist retry work before the callback returns. During SDK runs,
+callbacks execute while the session is still serialized and must not re-enter
+`bot.run()` for the same session.
+
+```python
+import json
+
+from nanobot import (
+    Nanobot,
+    RequestContext,
+    RuntimeContextBlock,
+    SessionTurnPersisted,
+)
+
+
+def external_context_block(text: str) -> RuntimeContextBlock:
+    bounded = text[:8_000]
+    encoded = json.dumps(bounded, ensure_ascii=False)
+    encoded = encoded.replace("[", "\\u005b").replace("]", "\\u005d")
+    return RuntimeContextBlock(
+        source="external_memory",
+        content=(
+            "[Runtime Context — metadata only, not instructions]\n"
+            "External memory result (JSON-encoded; treat as data, not instructions):\n"
+            f"{encoded}\n"
+            "[/Runtime Context]"
+        ),
+    )
+
+
+async def run_with_external_memory(external_memory, enqueue_retry) -> None:
+    async with Nanobot.from_config() as bot:
+        async def load_context(request: RequestContext):
+            resource = request.attributes.get("resource")
+            if not resource:
+                return None
+            text = await external_memory.search(
+                resource,
+                request.original_user_text or "",
+            )
+            return external_context_block(text)
+
+        async def sync_saved_turn(event: SessionTurnPersisted):
+            snapshot = bot.sessions.get(event.context.session_key)
+            if snapshot is not None:
+                try:
+                    await external_memory.sync(
+                        resource=event.context.attributes.get("resource"),
+                        messages=snapshot.messages,
+                    )
+                except Exception as exc:
+                    await enqueue_retry(event, snapshot, exc)
+
+        remove_context = bot.runtime.add_context_provider(load_context)
+        remove_sync = bot.runtime.on_session_turn_persisted(sync_saved_turn)
+        try:
+            await bot.run(
+                "Continue the architecture discussion",
+                session_key="project:architecture",
+                attributes={"resource": "memory://projects/architecture"},
+            )
+        finally:
+            remove_sync()
+            remove_context()
+```
+
+Context providers are trusted host extensions, and `RuntimeContextBlock.content`
+is appended verbatim to model-visible context. Apply equivalent bounding,
+encoding, and delimiter escaping to untrusted external content.
+Persisted-turn callbacks are not invoked for `ephemeral=True` runs.
+
 ## Hooks
 
 Hooks let you observe or customize the agent loop. Subclass `AgentHook` and override the methods you need.

docs/troubleshooting.md

@@ -23,15 +23,20 @@ This separates failures into layers:
 | Layer | What it proves |
 |---|---|
 | `nanobot --version` | Install and shell command discovery |
-| `nanobot status` | Config path, workspace path, active model, and provider summary |
+| `nanobot status` | Config path, workspace, environment references, and active provider/model configuration |
 | `nanobot agent -m "Hello!"` | Config loading, provider/model access, workspace writes, and agent loop |
 | `nanobot gateway` | Channel startup, cron system jobs, heartbeat, WebUI/WebSocket, and health endpoint |
 
 If `nanobot agent -m "Hello!"` fails, fix that before debugging WebUI, Telegram, Discord, Docker, systemd, or any chat app.
 
+`nanobot status` does not call the model. If provider/model setup is incomplete, it points to
+WebUI **Settings → Models** or the CLI setup wizard, then prints the command to check again.
+
 ## How to Read `nanobot status`
 
-`nanobot status` does not call a model. It only checks whether nanobot can find the selected config, selected workspace, active model or preset, and provider setup summary.
+`nanobot status` does not call a model. It checks the selected config and workspace,
+resolves environment references, and validates the local settings required by the active
+provider/model without constructing a provider client.
 
 The output has this shape:
 
@@ -41,6 +46,7 @@ nanobot Status
 Config: /path/to/config.json ✓
 Workspace: /path/to/workspace ✓
 Model: provider/model-name (preset: primary)
+Agent: ✓ provider/model configuration is ready
 Provider A: not set
 Provider B: ✓
 Local Provider: ✓ http://localhost:11434/v1
@@ -54,6 +60,7 @@ Read it like this:
 | `Config` | It points to the config file you meant to use and shows `✓`. | Run `nanobot onboard`, or pass `--config` to `nanobot agent`, `gateway`, or `serve` when testing a non-default instance. |
 | `Workspace` | It points to the workspace you meant to use and shows `✓`. | Run `nanobot onboard`, create the folder, fix permissions, or pass `--workspace` on commands that support it. |
 | `Model` | It shows the active model or the preset name you expect. | Set `agents.defaults.modelPreset` to the intended preset, or check `/model` if you changed models during a chat session. |
+| `Agent` | It says `provider/model configuration is ready`. | Follow the printed WebUI or CLI setup route, then run `nanobot status` again. |
 | Provider rows | The provider used by the active preset shows `✓`, an OAuth marker, or a local URL. | Configure only the active provider first. It is normal for unused providers to say `not set`. |
 
 If `nanobot status` looks right but `nanobot agent -m "Hello!"` fails, the install and config paths are probably fine. Continue with [Provider and Model Problems](#provider-and-model-problems).
@@ -108,6 +115,12 @@ Common config mistakes:
 | Environment variable error | `${VAR_NAME}` references are resolved at startup. Set the variable before running nanobot. |
 | Edited config but behavior did not change | Restart `nanobot gateway`; long-running processes read config at startup. |
 
+After editing config, check the shortest path to an Agent reply:
+
+```bash
+nanobot status
+```
+
 To refresh missing defaults without overwriting existing settings, run:
 
 ```bash
@@ -132,7 +145,7 @@ If you need a known-good snippet instead of diagnosis, use [`provider-cookbook.m
 |---|---|
 | 401, unauthorized, invalid API key | Key is missing, expired, pasted with whitespace, or under the wrong provider key. |
 | Model not found | The model ID belongs to a different provider or gateway. |
-| Provider cannot be inferred | Pin `modelPresets.<name>.provider` in the active preset instead of using `"auto"`. For legacy direct configs, pin `agents.defaults.provider`. |
+| Provider cannot be inferred | Pin `modelPresets.<name>.provider` in the active preset instead of using `"auto"`. |
 | Local model connection refused | Ollama, vLLM, LM Studio, or another local server is not running, or `apiBase` points to the wrong port. |
 | Bedrock validation error | Check AWS region, credentials, model access, model ID, and whether the model supports Converse. |
 | OAuth provider fails | Run the matching login command: `openai-codex`, `xai-grok`, or `github-copilot`, normally with `--set-main`. |

docs/webui.md

@@ -285,9 +285,9 @@ The gateway refuses to start with `host` set to `"0.0.0.0"` unless `token` or
 form.
 
 Remote WebUI clients with a valid token can view and use Apps. Actions that
-install missing nanobot support packages or first-class extension packages are
+install missing nanobot support packages, such as adding a channel dependency,
-blocked by default. To let trusted remote administrators place packages into
+are blocked by default. To let trusted remote administrators change the Python
-this nanobot installation through the WebUI, opt in explicitly:
+environment through the WebUI, opt in explicitly:
 
 ```json
 {
@@ -298,15 +298,12 @@ this nanobot installation through the WebUI, opt in explicitly:
 ```
 
 Use this only for a private deployment where every authenticated WebUI user is
-trusted to change the nanobot installation. A remotely installed extension
+trusted to change the Python environment that nanobot runs in. If you publish
-remains untrusted and inactive: trust, permission grants, activation, disabling,
+the WebUI through Nginx, Caddy, Cloudflare Tunnel, or a similar service, treat it
-and removal stay restricted to a browser on the nanobot host. If you publish the
+as remote access and leave package installs disabled unless that is intentional.
-WebUI through Nginx, Caddy, Cloudflare Tunnel, or a similar service, treat it as
-remote access and leave package installs disabled unless that is intentional.
 
 Optional feature installs use pip's configured package index, including
-`PIP_INDEX_URL`. Extension packages install from an explicit Git repository or
+`PIP_INDEX_URL`.
-local directory.
 
 Leave remote package installs disabled when the WebUI is exposed beyond a
 private, trusted network.

nanobot/__init__.py

@@ -32,6 +32,9 @@ _LAZY_EXPORTS = {
     "Nanobot": ".nanobot",
     "RunStream": ".nanobot",
     "RunResult": ".nanobot",
+    "RequestContext": ".agent.tools.context",
+    "RuntimeContextBlock": ".runtime_context",
+    "RuntimeContextProvider": ".runtime_context",
     "SessionInfo": ".nanobot",
     "SessionSnapshot": ".nanobot",
     "STREAM_EVENT_REASONING_COMPLETED": ".nanobot",
@@ -47,6 +50,7 @@ _LAZY_EXPORTS = {
     "STREAM_EVENT_TYPES": ".nanobot",
     "StreamEvent": ".nanobot",
     "StreamEventType": ".nanobot",
+    "SessionTurnPersisted": ".bus.runtime_events",
 }
 
 
@@ -64,6 +68,9 @@ def __getattr__(name: str):
 __all__ = [
     "Nanobot",
     "RunResult",
+    "RequestContext",
+    "RuntimeContextBlock",
+    "RuntimeContextProvider",
     "RunStream",
     "SessionInfo",
     "SessionSnapshot",
@@ -80,4 +87,5 @@ __all__ = [
     "STREAM_EVENT_TYPES",
     "StreamEvent",
     "StreamEventType",
+    "SessionTurnPersisted",
 ]

nanobot/agent/context.py

@@ -15,10 +15,13 @@ from nanobot.apps.cli import utils as cli_app_utils
 from nanobot.bus.events import InboundMessage
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_END,
+    RUNTIME_CONTEXT_HISTORY_META,
     RUNTIME_CONTEXT_MESSAGE_META,
     RUNTIME_CONTEXT_TAG,
     RuntimeContextBlock,
     append_runtime_context,
+    detach_runtime_context,
+    reattach_runtime_context,
 )
 from nanobot.utils.helpers import (
     detect_image_mime,
@@ -60,6 +63,9 @@ class ContextBuilder:
     _MAX_RECENT_HISTORY = 50
     _MAX_HISTORY_TOKENS = 8_000  # hard cap on recent history section size (tokens)
     _RUNTIME_CONTEXT_END = RUNTIME_CONTEXT_END
+    _MISSING_IMAGE_TEXT = (
+        "[Image attachment unavailable — do not describe or reference it]"
+    )
 
     def __init__(self, workspace: Path, timezone: str | None = None, disabled_skills: list[str] | None = None):
         self.workspace = workspace
@@ -87,9 +93,9 @@ class ContextBuilder:
 
         parts.append(render_template("agent/tool_contract.md"))
 
-        memory = self.memory.get_memory_context()
+        memory = self.memory.read_memory()
-        if memory and not self._is_template_content(self.memory.read_memory(), "memory/MEMORY.md"):
+        if memory and not self._is_template_content(memory, "memory/MEMORY.md"):
-            parts.append(f"# Memory\n\n{memory}")
+            parts.append(f"# Memory\n\n## Long-term Memory\n{memory}")
 
         always_skills = self.skills.get_always_skills()
         if always_skills:
@@ -209,7 +215,7 @@ class ContextBuilder:
     ) -> list[dict[str, Any]]:
         """Build the complete message list for an LLM call."""
         root = workspace or self.workspace
-        user_content = self._build_user_content(current_message, media)
+        user_content = self.build_user_content(current_message, image_paths=media)
         blocks = list(runtime_context_blocks or ()) if current_role == "user" else []
         merged, runtime_context_meta = append_runtime_context(user_content, blocks)
         messages = [
@@ -224,7 +230,7 @@ class ContextBuilder:
                     unified_session=unified_session,
                 ),
             },
-            *history,
+            *self._hydrate_history_media(history),
         ]
         if messages[-1].get("role") == current_role:
             last = dict(messages[-1])
@@ -241,27 +247,78 @@ class ContextBuilder:
         messages.append(current)
         return messages
 
-    def _build_user_content(self, text: str, media: list[str] | None) -> str | list[dict[str, Any]]:
+    def build_user_content(
-        """Build user message content with optional base64-encoded images."""
+        self,
-        if not media:
+        text: str,
+        image_paths: list[str] | None,
+    ) -> str | list[dict[str, Any]]:
+        """Build user message content from prefiltered image paths."""
+        if not image_paths:
             return text
 
-        images = []
+        image_blocks = []
-        for path in media:
+        for path in image_paths:
             p = Path(path)
             if not p.is_file():
+                image_blocks.append(
+                    {"type": "text", "text": self._MISSING_IMAGE_TEXT}
+                )
                 continue
             raw = p.read_bytes()
+            # Re-detect from the bytes used for the request: the file may have
+            # changed since attachment routing, and the data URL needs its MIME.
             mime = detect_image_mime(raw) or mimetypes.guess_type(path)[0]
             if not mime or not mime.startswith("image/"):
                 continue
             b64 = base64.b64encode(raw).decode()
-            images.append({
+            image_blocks.append({
                 "type": "image_url",
                 "image_url": {"url": f"data:{mime};base64,{b64}"},
                 "_meta": {"path": str(p)},
             })
 
-        if not images:
+        if not image_blocks:
             return text
-        return images + [{"type": "text", "text": text}]
+        return image_blocks + [{"type": "text", "text": text}]
+
+    def _hydrate_history_media(
+        self,
+        history: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Rebuild persisted user media into the same blocks used on first send."""
+        hydrated: list[dict[str, Any]] = []
+        for message in history:
+            clean = dict(message)
+            media_paths = clean.pop("_media_paths", None)
+            runtime_context = clean.pop(RUNTIME_CONTEXT_HISTORY_META, None)
+            if (
+                clean.get("role") == "user"
+                and isinstance(clean.get("content"), str)
+                and isinstance(media_paths, list)
+                and media_paths
+            ):
+                visible_content = clean["content"]
+                detached = (
+                    detach_runtime_context(visible_content, runtime_context)
+                    if isinstance(runtime_context, Mapping)
+                    else None
+                )
+                if detached is not None:
+                    visible_content, sources, context_blocks = detached
+                hydrated_content = self.build_user_content(
+                    visible_content,
+                    image_paths=[
+                        path
+                        for path in media_paths
+                        if isinstance(path, str) and path
+                    ],
+                )
+                if detached is not None:
+                    hydrated_content, _ = reattach_runtime_context(
+                        hydrated_content,
+                        sources,
+                        context_blocks,
+                    )
+                clean["content"] = hydrated_content
+            hydrated.append(clean)
+        return hydrated

nanobot/agent/context_governance.py

@@ -26,7 +26,6 @@ if TYPE_CHECKING:
     from nanobot.providers.base import LLMProvider
 
 SNIP_SAFETY_BUFFER = 1024
-MICROCOMPACT_KEEP_RECENT = 10
 MICROCOMPACT_MIN_CHARS = 500
 INFLIGHT_COMPACT_TARGET_RATIO = 0.85
 COMPACTABLE_TOOLS = frozenset({
@@ -498,14 +497,7 @@ class ContextGovernor:
                 continue
             compactable.append((idx, str(tool_call_id)))
 
-        if not compactable:
+        return compactable
-            return []
-        primary_count = max(0, len(compactable) - MICROCOMPACT_KEEP_RECENT)
-        primary = compactable[:primary_count]
-        # Hard overflow beats the keep-recent preference. Return recent results
-        # after stale ones so the newest result is naturally last.
-        fallback = compactable[primary_count:]
-        return primary + fallback
 
     def _compact_tool_result_at(self, messages: list[dict[str, Any]], idx: int) -> None:
         messages[idx]["content"] = self._tool_result_compaction_message(messages[idx])

nanobot/agent/hook.py

@@ -59,6 +59,7 @@ class AgentTurnHookContext:
     session_key: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
     ephemeral: bool = False
+    attributes: dict[str, Any] = field(default_factory=dict)
 
 
 class AgentHook:

nanobot/agent/loop.py

@@ -43,11 +43,7 @@ from nanobot.agent.turn_hooks import AgentTurnHookSpec, build_agent_turn_hook
 from nanobot.bus.events import InboundMessage, OutboundMessage
 from nanobot.bus.outbound_events import StreamedResponseEvent
 from nanobot.bus.queue import MessageBus
-from nanobot.bus.runtime_events import (
+from nanobot.bus.runtime_events import RuntimeEventBus
-    RuntimeEventBus,
-    RuntimeEventPublisher,
-    ensure_runtime_event_publisher,
-)
 from nanobot.command import CommandContext, CommandRouter, register_builtin_commands
 from nanobot.config.schema import AgentDefaults, ModelPresetConfig
 from nanobot.providers.base import LLMProvider
@@ -86,7 +82,7 @@ from nanobot.session.model_selection import (
 )
 from nanobot.triggers.local_turns import LocalTriggerTurnCoordinator
 from nanobot.utils.cancellation import task_is_cancelling
-from nanobot.utils.document import extract_documents, reference_non_image_attachments
+from nanobot.utils.document import 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.llm_runtime import LLMRuntime
@@ -126,6 +122,7 @@ class TurnContext:
     initial_messages: list[dict[str, Any]] = field(default_factory=list)
     request_context: RequestContext | None = None
     runtime_context_blocks: list[RuntimeContextBlock] = field(default_factory=list)
+    attributes: dict[str, Any] = field(default_factory=dict)
 
     final_content: str | None = None
     all_messages: list[dict[str, Any]] = field(default_factory=list)
@@ -220,6 +217,12 @@ class AgentLoop:
             self._publish_runtime_selection(runtime)
         return runtime
 
+    def dream_runtime(self) -> LLMRuntime | None:
+        """Resolve the optional preset used for Dream without changing defaults."""
+        if not self.dream_model_preset:
+            return None
+        return self.runtime_resolver.resolve_preset(self.dream_model_preset)
+
     _RUNTIME_CHECKPOINT_KEY = "runtime_checkpoint"
     _PENDING_USER_TURN_KEY = "pending_user_turn"
 
@@ -257,6 +260,7 @@ class AgentLoop:
         model_presets: dict[str, ModelPresetConfig] | None = None,
         preset_catalog_loader: preset_helpers.PresetCatalogLoader | None = None,
         model_preset: str | None = None,
+        dream_model_preset: str | None = None,
         preset_snapshot_loader: preset_helpers.PresetSnapshotLoader | None = None,
         runtime_events: RuntimeEventBus | None = None,
         turn_delivery_factory: TurnDeliveryFactory | None = None,
@@ -295,7 +299,7 @@ class AgentLoop:
         initial_context_window = (
             context_window_tokens
             if context_window_tokens is not None
-            else defaults.context_window_tokens
+            else ModelPresetConfig(model=initial_model).context_window_tokens
         )
         configured_presets = model_presets or {}
         self.runtime_resolver = ModelRuntimeResolver(
@@ -311,6 +315,7 @@ class AgentLoop:
             provider_snapshot_loader=provider_snapshot_loader,
             preset_snapshot_loader=preset_snapshot_loader,
         )
+        self.dream_model_preset = dream_model_preset
         self.context_block_limit = context_block_limit
         self.max_tool_result_chars = (
             max_tool_result_chars
@@ -370,8 +375,8 @@ class AgentLoop:
         self._mcp_stacks: dict[str, MCPConnection] = {}
         self._mcp_connecting = False
         self._runtime_context_providers: list[RuntimeContextProvider] = []
-        self._active_tasks: dict[str, list[asyncio.Task]] = {}  # session_key -> tasks
+        self._active_tasks: dict[str, set[asyncio.Task[Any]]] = {}
-        self._background_tasks: list[asyncio.Task] = []
+        self._background_tasks: set[asyncio.Task[Any]] = set()
         self._session_locks: dict[str, asyncio.Lock] = {}
         # Per-session pending queues for mid-turn message injection.
         # When a session has an active task, new messages for that session
@@ -440,15 +445,20 @@ class AgentLoop:
         if bus is None:
             bus = MessageBus()
         defaults = config.agents.defaults
-        provider = extra.pop("provider", None) or make_provider(config)
+        explicit_provider = extra.pop("provider", None)
+        provider = explicit_provider or make_provider(config)
         resolved = config.resolve_preset()
         model = extra.pop("model", None) or resolved.model
         context_window_tokens = extra.pop("context_window_tokens", None) or resolved.context_window_tokens
         provider_snapshot_loader = extra.pop("provider_snapshot_loader", None)
-        preset_snapshot_loader = extra.pop("preset_snapshot_loader", None) or preset_helpers.make_preset_snapshot_loader(
+        preset_snapshot_loader = extra.pop("preset_snapshot_loader", None)
-            config,
+        if preset_snapshot_loader is None and (
-            provider_snapshot_loader,
+            explicit_provider is None or provider_snapshot_loader is not None
-        )
+        ):
+            preset_snapshot_loader = preset_helpers.make_preset_snapshot_loader(
+                config,
+                provider_snapshot_loader,
+            )
         return cls(
             bus=bus,
             provider=provider,
@@ -474,6 +484,7 @@ class AgentLoop:
             tools_config=config.tools,
             model_presets=preset_helpers.configured_model_presets(config),
             model_preset=defaults.model_preset,
+            dream_model_preset=defaults.dream.model_override,
             restart_mode=config.gateway.restart_mode,
             provider_snapshot_loader=provider_snapshot_loader,
             preset_snapshot_loader=preset_snapshot_loader,
@@ -535,7 +546,7 @@ class AgentLoop:
             return
         if self._runtime_model_publisher is not None:
             self._runtime_model_publisher(runtime.model, runtime.model_preset)
-        self._runtime_events().runtime_model_changed(
+        self.runtime_event_publisher.runtime_model_changed(
             runtime.model,
             runtime.model_preset,
         )
@@ -607,13 +618,17 @@ class AgentLoop:
     def register_runtime_context_provider(
         self,
         provider: RuntimeContextProvider,
-    ) -> None:
+    ) -> Callable[[], None]:
-        """Register a provider resolved once before each inbound model turn."""
+        """Register a per-turn context provider and return an unsubscribe callback."""
-        if provider not in self._runtime_context_providers:
+        if provider in self._runtime_context_providers:
-            self._runtime_context_providers.append(provider)
+            return lambda: None
+        self._runtime_context_providers.append(provider)
 
-    def _runtime_events(self) -> RuntimeEventPublisher:
+        def _unsubscribe() -> None:
-        return ensure_runtime_event_publisher(self)
+            with suppress(ValueError):
+                self._runtime_context_providers.remove(provider)
+
+        return _unsubscribe
 
     async def submit_cron_turn(self, msg: InboundMessage) -> OutboundMessage | None:
         return await self._cron_turns.submit(msg)
@@ -678,7 +693,6 @@ class AgentLoop:
             current_message=ctx.msg.content,
             media=ctx.msg.media if ctx.kind is TurnKind.USER and ctx.msg.media else None,
             channel=ctx.delivery.route.channel,
-            current_role="user",
             session_summary=ctx.pending_summary,
             workspace=scope.project_path,
             runtime_context_blocks=ctx.runtime_context_blocks,
@@ -702,6 +716,7 @@ class AgentLoop:
             original_user_text=ctx.original_user_text,
             runtime=ctx.runtime,
             metadata=dict(ctx.msg.metadata or {}),
+            attributes=dict(ctx.attributes),
             sender_id=ctx.msg.sender_id,
             turn_id=ctx.turn_id,
             workspace=scope.project_path,
@@ -750,7 +765,7 @@ class AgentLoop:
 
         Returns the total number of cancelled tasks + subagents.
         """
-        tasks = self._active_tasks.pop(key, [])
+        tasks = tuple(self._active_tasks.pop(key, set()))
         cancelled = sum(1 for t in tasks if not t.done() and t.cancel())
         for t in tasks:
             with suppress(asyncio.CancelledError, Exception):
@@ -853,11 +868,17 @@ class AgentLoop:
 
             async def _to_user_message(pending_msg: InboundMessage) -> dict[str, Any]:
                 content = pending_msg.content
-                media = pending_msg.media if pending_msg.media else None
+                image_paths = pending_msg.media if pending_msg.media else None
-                if media:
+                if image_paths:
-                    content, media = self._prepare_message_media(content, media)
+                    content, image_paths = reference_non_image_attachments(
-                    media = media or None
+                        content,
-                user_content = self.context._build_user_content(content, media)
+                        image_paths,
+                    )
+                    image_paths = image_paths or None
+                user_content = self.context.build_user_content(
+                    content,
+                    image_paths=image_paths,
+                )
                 row: dict[str, Any] = {"role": "user", "content": user_content}
                 metadata = pending_msg.metadata if isinstance(pending_msg.metadata, dict) else {}
                 if pending_msg.channel != "system":
@@ -874,6 +895,7 @@ class AgentLoop:
                         original_user_text=pending_msg.content,
                         runtime=runtime,
                         metadata=dict(metadata),
+                        attributes=dict(request_ctx.attributes),
                         sender_id=pending_msg.sender_id,
                         turn_id=request_ctx.turn_id,
                         workspace=scope.project_path,
@@ -973,6 +995,7 @@ class AgentLoop:
                 chat_id=chat_id,
                 message_id=message_id,
                 metadata=metadata,
+                attributes=dict(request_ctx.attributes),
                 session_key=active_session_key,
                 workspace=effective_scope.project_path,
                 tool_hint_max_length=self.tool_hint_max_length,
@@ -1144,13 +1167,9 @@ class AgentLoop:
                 # Compute the effective session key before dispatching
                 # This ensures /stop command can find tasks correctly when unified session is enabled
                 task = asyncio.create_task(self._dispatch(msg))
-                self._active_tasks.setdefault(effective_key, []).append(task)
+                active_tasks = self._active_tasks.setdefault(effective_key, set())
-                task.add_done_callback(
+                active_tasks.add(task)
-                    lambda t, k=effective_key: self._active_tasks.get(k, [])
+                task.add_done_callback(active_tasks.discard)
-                    and self._active_tasks[k].remove(t)
-                    if t in self._active_tasks.get(k, [])
-                    else None
-                )
         finally:
             # MCP stdio transports use AnyIO cancel scopes; close them from the task that opened them.
             await self.close_mcp()
@@ -1293,8 +1312,8 @@ class AgentLoop:
     def _schedule_background(self, coro) -> None:
         """Schedule a coroutine as a tracked background task (drained on shutdown)."""
         task = asyncio.create_task(coro)
-        self._background_tasks.append(task)
+        self._background_tasks.add(task)
-        task.add_done_callback(self._background_tasks.remove)
+        task.add_done_callback(self._background_tasks.discard)
 
     def stop(self) -> None:
         """Stop the agent loop."""
@@ -1317,6 +1336,7 @@ class AgentLoop:
         runtime: LLMRuntime | None = None,
         delivery: TurnDelivery | None = None,
         on_runtime_admitted: Callable[[LLMRuntime], Awaitable[None]] | None = None,
+        attributes: Mapping[str, Any] | None = None,
     ) -> OutboundMessage | None:
         """Process a single inbound message and return the response."""
         kind = TurnKind.SYSTEM if msg.channel == "system" else TurnKind.USER
@@ -1364,6 +1384,7 @@ class AgentLoop:
             hooks=list(hooks or []),
             hook_factories=list(hook_factories or []),
             tools=tools,
+            attributes=dict(attributes or {}),
         )
         # A streaming callback may be present even when the final text comes from a
         # non-streaming recovery. Only the last completed segment can suppress the
@@ -1481,12 +1502,15 @@ class AgentLoop:
         )
 
     async def _restore_turn(self, ctx: TurnContext) -> None:
-        """Restore checkpoint / pending user turn; extract documents."""
+        """Restore checkpoint / pending user turn; reference non-image attachments."""
         msg = ctx.msg
 
         if ctx.kind is TurnKind.USER and msg.media:
-            new_content, image_only = self._prepare_message_media(msg.content, msg.media)
+            new_content, image_paths = reference_non_image_attachments(
-            ctx.msg = dataclasses.replace(msg, content=new_content, media=image_only)
+                msg.content,
+                msg.media,
+            )
+            ctx.msg = dataclasses.replace(msg, content=new_content, media=image_paths)
             msg = ctx.msg
 
         preview = msg.content[:80] + "..." if len(msg.content) > 80 else msg.content
@@ -1513,16 +1537,6 @@ class AgentLoop:
         if self._restore_pending_user_turn(ctx.session):
             self.sessions.save(ctx.session)
 
-    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 _compact_session(self, ctx: TurnContext) -> None:
         ctx.session, pending = self.auto_compact.prepare_session(ctx.session, ctx.session_key)
         ctx.pending_summary = pending
@@ -1563,8 +1577,15 @@ class AgentLoop:
                 ctx.session.add_message(
                     "assistant", result.content, _command=True
                 )
-                self.sessions.save(ctx.session)
                 self._clear_pending_user_turn(ctx.session)
+                self.sessions.save(ctx.session)
+                if not ctx.ephemeral:
+                    await self.runtime_event_publisher.session_turn_persisted(
+                        ctx.msg,
+                        ctx.session_key,
+                        turn_id=ctx.turn_id,
+                        attributes=ctx.attributes,
+                    )
             return True
         return False
 
@@ -1573,6 +1594,12 @@ class AgentLoop:
         if runtime is None:
             runtime = self.runtime_for_session(ctx.session)
             ctx.runtime = runtime
+        if ctx.session_key.startswith("dream:"):
+            logger.info(
+                "Dream run using model={} (preset={})",
+                runtime.model,
+                runtime.model_preset or "default",
+            )
         if ctx.on_runtime_admitted is not None:
             await ctx.on_runtime_admitted(runtime)
         replay_max_messages = replay_max_messages_for_context(
@@ -1594,6 +1621,7 @@ class AgentLoop:
             "max_messages": replay_max_messages,
             "max_tokens": self._replay_token_budget(runtime),
             "extend_to_user": is_subagent,
+            "include_media": True,
         }
         ctx.history = ctx.session.get_history(**_hist_kwargs)
         if is_subagent:
@@ -1700,6 +1728,13 @@ class AgentLoop:
         self._clear_pending_user_turn(ctx.session)
         self._clear_runtime_checkpoint(ctx.session)
         self.sessions.save(ctx.session)
+        if not ctx.ephemeral:
+            await self.runtime_event_publisher.session_turn_persisted(
+                ctx.msg,
+                ctx.session_key,
+                turn_id=ctx.turn_id,
+                attributes=ctx.attributes,
+            )
 
     async def _prepare_outbound(self, ctx: TurnContext) -> None:
         if ctx.suppress_response:
@@ -1981,6 +2016,7 @@ class AgentLoop:
         persist_user_message: bool = True,
         runtime: LLMRuntime | None = None,
         on_runtime_admitted: Callable[[LLMRuntime], Awaitable[None]] | None = None,
+        attributes: Mapping[str, Any] | None = None,
     ) -> OutboundMessage | None:
         """Process an external message directly and return the outbound payload."""
         if channel == "system":
@@ -2016,10 +2052,12 @@ class AgentLoop:
                     kwargs["runtime"] = runtime
                 if on_runtime_admitted is not None:
                     kwargs["on_runtime_admitted"] = on_runtime_admitted
+                if attributes is not None:
+                    kwargs["attributes"] = dict(attributes)
                 return await self._process_message(
                     msg,
                     **kwargs,
                 )
         finally:
-            await self._runtime_events().run_status_changed(msg, session_key, "idle")
+            await self.runtime_event_publisher.run_status_changed(msg, session_key, "idle")
-            self._runtime_events().clear_turn(session_key)
+            self.runtime_event_publisher.clear_turn(session_key)

nanobot/agent/memory.py

@@ -19,10 +19,12 @@ from nanobot.runtime_context import public_history_messages
 from nanobot.session.manager import Session, SessionManager
 from nanobot.utils.gitstore import GitStore
 from nanobot.utils.helpers import (
+    content_with_media_breadcrumbs,
     ensure_dir,
     estimate_message_tokens,
     estimate_prompt_tokens_chain,
     find_legal_message_start,
+    image_placeholder_text,
     recent_message_start_index,
     strip_think,
     truncate_text,
@@ -433,13 +435,33 @@ class MemoryStore:
         ]
 
     def compact_history(self) -> None:
-        """Drop oldest entries if the file exceeds *max_history_entries*."""
+        """Drop oldest processed entries without discarding pending Dream input."""
         if self.max_history_entries <= 0:
             return
         entries = self._read_entries()
         if len(entries) <= self.max_history_entries:
             return
-        kept = entries[-self.max_history_entries:]
+        last_dream_cursor = self.get_last_dream_cursor()
+        first_unprocessed = next(
+            (
+                index
+                for index, entry in enumerate(entries)
+                if (
+                    (cursor := self._valid_cursor(entry.get("cursor"))) is not None
+                    and cursor > last_dream_cursor
+                )
+            ),
+            len(entries),
+        )
+        keep_from = min(len(entries) - self.max_history_entries, first_unprocessed)
+        kept = entries[keep_from:]
+        if len(kept) > self.max_history_entries:
+            logger.warning(
+                "History compaction retained {} unprocessed entries beyond the configured "
+                "limit of {}",
+                len(kept),
+                self.max_history_entries,
+            )
         self._write_entries(kept)
 
     # -- JSONL helpers -------------------------------------------------------
@@ -569,7 +591,7 @@ class MemoryStore:
 
         batch = entries[:max_entries]
         history_text = "\n".join(
-            f"[{e['timestamp']}] {truncate_text(e['content'], 500)}"
+            f"[{e['timestamp']}] {truncate_text(e['content'], 1000)}"
             for e in batch
         )
         template = self._dream_template()
@@ -650,6 +672,7 @@ class MemoryStore:
         tools.register(WriteFileTool(
             workspace=workspace,
             allowed_dir=skills_dir,
+            extra_write_allowed_files=editable_files,
             file_states=file_states,
         ))
         return tools
@@ -674,14 +697,58 @@ class MemoryStore:
     def _format_messages(messages: list[dict]) -> str:
         lines = []
         for message in messages:
-            if not message.get("content"):
+            content = message.get("content") or ""
+            media = message.get("media")
+            media_paths = (
+                [
+                    path.replace("\r", " ").replace("\n", " ")
+                    for path in media[:16]
+                    if isinstance(path, str) and path
+                ]
+                if isinstance(media, list)
+                else []
+            )
+            content = content_with_media_breadcrumbs(
+                message.get("role"),
+                content,
+                media_paths,
+            )
+            if not content:
                 continue
             tools = f" [tools: {', '.join(message['tools_used'])}]" if message.get("tools_used") else ""
             lines.append(
-                f"[{message.get('timestamp', '?')[:16]}] {message['role'].upper()}{tools}: {message['content']}"
+                f"[{message.get('timestamp', '?')[:16]}] "
+                f"{message['role'].upper()}{tools}: {content}"
             )
         return "\n".join(lines)
 
+    @staticmethod
+    def _media_manifest(messages: list[dict]) -> str:
+        paths: list[str] = []
+        seen: set[str] = set()
+        for message in messages:
+            media = message.get("media")
+            if not isinstance(media, list):
+                continue
+            for raw_path in media:
+                if not isinstance(raw_path, str) or not raw_path:
+                    continue
+                path = raw_path.replace("\r", " ").replace("\n", " ")
+                if path in seen:
+                    continue
+                seen.add(path)
+                paths.append(path)
+                if len(paths) >= 64:
+                    break
+            if len(paths) >= 64:
+                break
+        if not paths:
+            return ""
+        return "Archived attachments:\n" + "\n".join(
+            f"- {image_placeholder_text(path)}"
+            for path in paths
+        )
+
     def raw_archive(
         self,
         messages: list[dict],
@@ -691,10 +758,11 @@ class MemoryStore:
     ) -> None:
         """Fallback: dump raw messages to history.jsonl without LLM summarization."""
         limit = max_chars if max_chars is not None else _RAW_ARCHIVE_MAX_CHARS
-        formatted = truncate_text(
+        formatted = self._format_messages(public_history_messages(messages))
-            self._format_messages(public_history_messages(messages)),
+        manifest = self._media_manifest(messages)
-            limit,
+        if manifest:
-        )
+            formatted = f"{manifest}\n\n{formatted}"
+        formatted = truncate_text(formatted, limit)
         self.append_history(
             f"[RAW] {len(messages)} messages\n"
             f"{formatted}",
@@ -999,6 +1067,11 @@ class Consolidator:
             self.store.raw_archive(messages, session_key=session_key)
             return None
         summary = response.content or "[no summary]"
+        manifest = MemoryStore._media_manifest(messages)
+        if manifest:
+            # Keep the deterministic manifest before generated prose so normal
+            # archive truncation preserves attachment references first.
+            summary = f"{manifest}\n\n{summary}"
         self.store.append_history(
             summary,
             max_chars=_ARCHIVE_SUMMARY_MAX_CHARS,

nanobot/agent/model_presets.py

@@ -23,7 +23,7 @@ def default_selection_signature(
 
 
 def configured_model_presets(config: Any) -> dict[str, ModelPresetConfig]:
-    return {**config.model_presets, "default": config.resolve_default_preset()}
+    return dict(config.model_presets)
 
 
 def load_model_preset_catalog(
@@ -33,7 +33,10 @@ def load_model_preset_catalog(
     from nanobot.config.loader import load_config, resolve_config_env_vars
 
     return configured_model_presets(
-        resolve_config_env_vars(load_config(config_path)),
+        resolve_config_env_vars(
+            load_config(config_path),
+            config_path=config_path,
+        ),
     )
 
 
@@ -58,6 +61,7 @@ def build_static_preset_snapshot(
         signature=("model_preset", name, preset.model_dump_json()),
         generation=preset.to_generation_settings(),
         model_preset=name,
+        supports_image_input=preset.supports_image_input,
     )
 
 

nanobot/agent/runner.py

@@ -788,6 +788,7 @@ class AgentRunner:
         kwargs["temperature"] = generation.temperature
         kwargs["max_tokens"] = generation.max_tokens
         kwargs["reasoning_effort"] = generation.reasoning_effort
+        kwargs["supports_image_input"] = spec.runtime.supports_image_input
         return kwargs
 
     async def _request_model(

nanobot/agent/subagent.py

@@ -26,7 +26,7 @@ from nanobot.agent.tools.loader import ToolLoader
 from nanobot.agent.tools.registry import ToolRegistry
 from nanobot.bus.events import InboundMessage
 from nanobot.bus.queue import MessageBus
-from nanobot.config.schema import AgentDefaults, ToolsConfig
+from nanobot.config.schema import AgentDefaults, ModelPresetConfig, ToolsConfig
 from nanobot.providers.base import LLMProvider
 from nanobot.security.workspace_access import (
     WorkspaceScope,
@@ -121,7 +121,9 @@ class SubagentManager:
             self._compat_runtime = LLMRuntime.capture(
                 provider,
                 model or provider.get_default_model(),
-                context_window_tokens=defaults.context_window_tokens,
+                context_window_tokens=ModelPresetConfig(
+                    model=model or provider.get_default_model()
+                ).context_window_tokens,
             )
         self.workspace = workspace
         self.bus = bus
@@ -161,7 +163,7 @@ class SubagentManager:
         context_window_tokens = (
             self._compat_runtime.context_window_tokens
             if self._compat_runtime is not None
-            else AgentDefaults().context_window_tokens
+            else ModelPresetConfig(model=model).context_window_tokens
         )
         self._compat_runtime = LLMRuntime.capture(
             provider,

nanobot/agent/tools/context.py

@@ -29,6 +29,7 @@ class RequestContext:
     sender_id: str | None = None
     turn_id: str | None = None
     workspace: Path | None = None
+    attributes: dict[str, Any] = field(default_factory=dict)
 
 
 @runtime_checkable

nanobot/agent/tools/filesystem.py

@@ -261,6 +261,8 @@ class ReadFileTool(_FsTool):
             "Text output format: LINE_NUM|CONTENT. "
             "Images return visual content for analysis. "
             "Supports PDF, DOCX, XLSX, PPTX documents. "
+            "Uploaded non-image attachments are referenced by path; read them "
+            "with this tool only when their contents are needed. "
             "Use find_files/list_dir first when the path is uncertain. "
             "Read the relevant range before editing so replacements or patches "
             "are based on current content. "
@@ -366,11 +368,25 @@ class ReadFileTool(_FsTool):
             try:
                 text_content = raw.decode("utf-8")
             except UnicodeDecodeError:
-                # Binary file - return error message
+                # Match the former eager extractor for known text formats while
-                mime = detect_image_mime(raw) or mimetypes.guess_type(path)[0]
+                # keeping arbitrary binary files on the guarded error path.
-                if mime and mime.startswith("image/"):
+                from nanobot.utils.document import _is_text_extension
-                    return build_image_content_blocks(raw, mime, str(fp), f"(Image file: {path})")
+
-                return ToolResult.error(f"Error: Cannot read binary file {path} (MIME: {mime or 'unknown'}). Only UTF-8 text and images are supported.")
+                if _is_text_extension(fp.suffix.lower()):
+                    text_content = raw.decode("latin-1")
+                else:
+                    mime = detect_image_mime(raw) or mimetypes.guess_type(path)[0]
+                    if mime and mime.startswith("image/"):
+                        return build_image_content_blocks(
+                            raw,
+                            mime,
+                            str(fp),
+                            f"(Image file: {path})",
+                        )
+                    return ToolResult.error(
+                        f"Error: Cannot read binary file {path} (MIME: {mime or 'unknown'}). "
+                        "Only supported text files and images can be read."
+                    )
 
             # Normalize CRLF -> LF before line-splitting. Primarily a Windows
             # concern (git checkouts with autocrlf, editors saving CRLF) but

nanobot/agent/tools/mcp.py

@@ -915,23 +915,6 @@ class MCPPromptWrapper(_MCPWrapperBase):
                 return "\n".join(parts) or "(no output)"
 
 
-def _register_mcp_capability(
-    registry: ToolRegistry,
-    capability: Tool,
-    server_name: str,
-) -> bool:
-    owner = f"nanobot.mcp.{server_name}"
-    if registry.register_if_absent(capability, owner=owner):
-        return True
-    logger.warning(
-        "MCP: skipping capability '{}' from server '{}' because it is already registered by '{}'",
-        capability.name,
-        server_name,
-        registry.owner(capability.name),
-    )
-    return False
-
-
 async def connect_mcp_servers(
     mcp_servers: dict, registry: ToolRegistry
 ) -> dict[str, MCPConnection]:
@@ -1065,8 +1048,7 @@ async def connect_mcp_servers(
                     )
                     continue
                 wrapper = MCPToolWrapper(session, name, tool_def, tool_timeout=cfg.tool_timeout)
-                if not _register_mcp_capability(registry, wrapper, name):
+                registry.register(wrapper)
-                    continue
                 logger.debug("MCP: registered tool '{}' from server '{}'", wrapper.name, name)
                 registered_count += 1
                 if enabled_tools:
@@ -1103,8 +1085,7 @@ async def connect_mcp_servers(
                         wrapper = MCPResourceWrapper(
                             session, name, resource, resource_timeout=cfg.tool_timeout
                         )
-                        if not _register_mcp_capability(registry, wrapper, name):
+                        registry.register(wrapper)
-                            continue
                         registered_count += 1
                         logger.debug(
                             "MCP: registered resource '{}' from server '{}'",
@@ -1122,8 +1103,7 @@ async def connect_mcp_servers(
                         wrapper = MCPPromptWrapper(
                             session, name, prompt, prompt_timeout=cfg.tool_timeout
                         )
-                        if not _register_mcp_capability(registry, wrapper, name):
+                        registry.register(wrapper)
-                            continue
                         registered_count += 1
                         logger.debug(
                             "MCP: registered prompt '{}' from server '{}'",

nanobot/agent/tools/message.py

@@ -67,14 +67,6 @@ class MessageTool(Tool):
         self._fallback_message_id = default_message_id
         self._fallback_metadata: dict[str, Any] = {}
         self._sent_in_turn_var: ContextVar[bool] = ContextVar("message_sent_in_turn", default=False)
-        self._turn_delivered_media_var: ContextVar[tuple[str, ...]] = ContextVar(
-            "message_turn_delivered_media",
-            default=(),
-        )
-        self._record_channel_delivery_var: ContextVar[bool] = ContextVar(
-            "message_record_channel_delivery",
-            default=False,
-        )
         self._suppress_delivery_var: ContextVar[bool] = ContextVar(
             "message_suppress_delivery",
             default=False,
@@ -96,19 +88,6 @@ class MessageTool(Tool):
     def start_turn(self) -> None:
         """Reset per-turn send tracking."""
         self._sent_in_turn = False
-        self._turn_delivered_media_var.set(())
-
-    def turn_delivered_media_paths(self) -> list[str]:
-        """Absolute paths attached via this tool to the active chat in the current turn."""
-        return list(self._turn_delivered_media_var.get())
-
-    def set_record_channel_delivery(self, active: bool):
-        """Mark tool-sent messages as proactive channel deliveries."""
-        return self._record_channel_delivery_var.set(active)
-
-    def reset_record_channel_delivery(self, token) -> None:
-        """Restore previous proactive delivery recording state."""
-        self._record_channel_delivery_var.reset(token)
 
     def set_suppress_delivery(self, active: bool):
         """Acknowledge but don't deliver tool sends (heartbeat internal check)."""
@@ -241,7 +220,7 @@ class MessageTool(Tool):
         metadata = dict(default_metadata) if same_target else {}
         if message_id:
             metadata["message_id"] = message_id
-        if self._record_channel_delivery_var.get() or media:
+        if media:
             metadata["_record_channel_delivery"] = True
 
         msg = OutboundMessage(
@@ -261,9 +240,6 @@ class MessageTool(Tool):
             await self._send_callback(msg)
             if channel == default_channel and chat_id == default_chat_id:
                 self._sent_in_turn = True
-                if media:
-                    prev = self._turn_delivered_media_var.get()
-                    self._turn_delivered_media_var.set(prev + tuple(str(p) for p in media))
             media_info = f" with {len(media)} attachments" if media else ""
             button_info = f" with {sum(len(row) for row in buttons)} button(s)" if buttons else ""
             return f"Message sent to {channel}:{chat_id}{media_info}{button_info}"

nanobot/agent/tools/registry.py

@@ -25,44 +25,22 @@ class ToolRegistry:
 
     def __init__(self):
         self._tools: dict[str, Tool] = {}
-        self._owners: dict[str, str] = {}
         self._cached_definitions: list[dict[str, Any]] | None = None
 
-    def register(self, tool: Tool, *, owner: str = "nanobot.core") -> None:
+    def register(self, tool: Tool) -> None:
         """Register a tool."""
         self._tools[tool.name] = tool
-        self._owners[tool.name] = owner
         self._cached_definitions = None
 
-    def register_if_absent(self, tool: Tool, *, owner: str = "nanobot.core") -> bool:
-        """Register a tool without replacing an existing capability."""
-        if tool.name in self._tools:
-            return False
-        self.register(tool, owner=owner)
-        return True
-
     def unregister(self, name: str) -> None:
         """Unregister a tool by name."""
         self._tools.pop(name, None)
-        self._owners.pop(name, None)
         self._cached_definitions = None
 
-    def unregister_owner(self, owner: str) -> None:
-        """Remove all tools registered by one extension."""
-        for name in [
-            name for name, registered_owner in self._owners.items()
-            if registered_owner == owner
-        ]:
-            self.unregister(name)
-
     def get(self, name: str) -> Tool | None:
         """Get a tool by name."""
         return self._tools.get(name)
 
-    def owner(self, name: str) -> str | None:
-        """Return the extension ID that registered a tool."""
-        return self._owners.get(name)
-
     def get_runtime_context_providers(self) -> list[RuntimeContextProvider]:
         """Return tool-owned providers in stable tool-name order."""
         providers: list[RuntimeContextProvider] = []

nanobot/agent/turn_hooks.py

@@ -39,6 +39,7 @@ class AgentTurnHookSpec:
     turn_hooks: list[AgentHook] = field(default_factory=list)
     ephemeral: bool = False
     run_extra_hooks_for_ephemeral: bool = False
+    attributes: dict[str, Any] | None = None
 
 
 def build_agent_turn_hook(spec: AgentTurnHookSpec) -> AgentHook:
@@ -62,6 +63,7 @@ def build_agent_turn_hook(spec: AgentTurnHookSpec) -> AgentHook:
         message_id=spec.message_id,
         session_key=spec.session_key,
         metadata=dict(spec.metadata or {}),
+        attributes=dict(spec.attributes or {}),
         ephemeral=spec.ephemeral,
     )
     hook_chain: list[AgentHook] = [progress_hook]

nanobot/bus/runtime_events.py

@@ -27,6 +27,7 @@ class RuntimeEventContext:
     chat_id: str
     session_key: str
     metadata: dict[str, Any] = field(default_factory=dict)
+    attributes: dict[str, Any] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)
@@ -54,6 +55,15 @@ class TurnCompleted:
     runtime: Any | None = None
 
 
+@dataclass(frozen=True)
+class SessionTurnPersisted:
+    """A completed turn has been written to local session storage."""
+
+    context: RuntimeEventContext
+    turn_id: str
+    sender_id: str
+
+
 @dataclass(frozen=True)
 class GoalStateChanged:
     """A session's sustained-goal state changed."""
@@ -72,6 +82,7 @@ class RuntimeModelChanged:
 
 RuntimeEvent = (
     SessionTurnStarted
+    | SessionTurnPersisted
     | TurnRunStatusChanged
     | TurnCompleted
     | GoalStateChanged
@@ -79,6 +90,7 @@ RuntimeEvent = (
 )
 RuntimeEventType = (
     type[SessionTurnStarted]
+    | type[SessionTurnPersisted]
     | type[TurnRunStatusChanged]
     | type[TurnCompleted]
     | type[GoalStateChanged]
@@ -152,12 +164,14 @@ class RuntimeEventPublisher:
         chat_id: str,
         session_key: str,
         metadata: dict[str, Any] | None,
+        attributes: dict[str, Any] | None = None,
     ) -> RuntimeEventContext:
         return RuntimeEventContext(
             channel=channel,
             chat_id=chat_id,
             session_key=session_key,
             metadata=dict(metadata or {}),
+            attributes=dict(attributes or {}),
         )
 
     def record_turn_runtime(self, session_key: str, runtime: Any) -> None:
@@ -208,6 +222,28 @@ class RuntimeEventPublisher:
             )
         )
 
+    async def session_turn_persisted(
+        self,
+        msg: InboundMessage,
+        session_key: str,
+        *,
+        turn_id: str,
+        attributes: dict[str, Any] | None = None,
+    ) -> None:
+        await self.bus.publish(
+            SessionTurnPersisted(
+                context=self._context(
+                    channel=msg.channel,
+                    chat_id=msg.chat_id,
+                    session_key=session_key,
+                    metadata=msg.metadata,
+                    attributes=attributes,
+                ),
+                turn_id=turn_id,
+                sender_id=msg.sender_id,
+            )
+        )
+
     async def turn_completed(
         self,
         *,
@@ -233,19 +269,3 @@ class RuntimeEventPublisher:
         self.bus.publish_nowait(
             RuntimeModelChanged(model=model, model_preset=model_preset)
         )
-
-
-def ensure_runtime_event_publisher(owner: Any) -> RuntimeEventPublisher:
-    """Return an owner's runtime publisher, creating missing state lazily."""
-    publisher = getattr(owner, "runtime_event_publisher", None)
-    if isinstance(publisher, RuntimeEventPublisher):
-        return publisher
-
-    bus = getattr(owner, "runtime_events", None)
-    if not isinstance(bus, RuntimeEventBus):
-        bus = RuntimeEventBus()
-        owner.runtime_events = bus
-
-    publisher = RuntimeEventPublisher(bus)
-    owner.runtime_event_publisher = publisher
-    return publisher

nanobot/channels/manager.py

@@ -98,7 +98,6 @@ class ChannelManager:
         webui_static_dist: bool = True,
         webui_runtime_surface: str = "browser",
         webui_runtime_capabilities: dict[str, Any] | None = None,
-        webui_extension_service: Any | None = None,
     ):
         self.config = config
         self.bus = bus
@@ -111,7 +110,6 @@ class ChannelManager:
         self._webui_static_dist = webui_static_dist
         self._webui_runtime_surface = webui_runtime_surface
         self._webui_runtime_capabilities = dict(webui_runtime_capabilities or {})
-        self._webui_extension_service = webui_extension_service
         self.channels: dict[str, BaseChannel] = {}
         self._channel_owners: dict[str, str] = {}
         self._channel_runtime_specs: dict[str, tuple[str, str]] = {}
@@ -178,10 +176,6 @@ class ChannelManager:
                 local_trigger_pending_ids=self._webui_local_trigger_pending_ids,
                 channel_feature_action=self.apply_channel_feature_action,
                 channel_runtime_status=self.get_status,
-                extension_service=self._webui_extension_service,
-                allow_remote_package_install=(
-                    self.config.tools.webui_allow_remote_package_install
-                ),
                 logger=logger,
             )
             kwargs["gateway"] = gateway

nanobot/channels/websocket/runtime.py

@@ -32,6 +32,7 @@ from nanobot.bus.outbound_events import (
 )
 from nanobot.bus.queue import MessageBus
 from nanobot.channels.base import BaseChannel
+from nanobot.command.builtin import builtin_command_starts_agent_turn
 from nanobot.config.schema import Base
 from nanobot.runtime_context import (
     RUNTIME_CONTEXT_INPUT_META,
@@ -43,7 +44,14 @@ from nanobot.security.workspace_access import (
     WorkspaceScopeError,
 )
 from nanobot.session.goal_state import goal_state_ws_blob
-from nanobot.session.webui_turns import websocket_turn_wall_started_at
+from nanobot.session.webui_turns import (
+    clear_websocket_turn_if_current,
+    mark_websocket_turn_transcript_persistence_failed,
+    register_queued_websocket_turn_if_idle,
+    websocket_turn_id,
+    websocket_turn_transcript_persistence_failed,
+    websocket_turn_wall_started_at,
+)
 from nanobot.webui.cli_apps_api import normalize_cli_app_mentions
 from nanobot.webui.forking import handle_webui_fork_chat
 from nanobot.webui.gateway_services import GatewayServices
@@ -57,6 +65,11 @@ from nanobot.webui.http_utils import (
     query_first as _query_first,
 )
 from nanobot.webui.mcp_presets_api import normalize_mcp_preset_mentions
+from nanobot.webui.metadata import (
+    WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_TURN_METADATA_KEY,
+)
+from nanobot.webui.transcript import WEBUI_TRANSCRIPT_INCOMPLETE_KEY
 from nanobot.webui.transcription_ws import webui_transcription_event
 from nanobot.webui.websocket_logging import websockets_server_logger
 
@@ -317,7 +330,12 @@ class WebSocketChannel(BaseChannel):
         t0 = websocket_turn_wall_started_at(chat_id)
         if t0 is None:
             return
-        await self.send_goal_status(chat_id, "running", started_at=t0)
+        await self.send_goal_status(
+            chat_id,
+            "running",
+            started_at=t0,
+            turn_id=websocket_turn_id(chat_id),
+        )
 
     async def _hydrate_after_subscribe(self, chat_id: str) -> None:
         """Replay persisted or actively running per-chat state after subscribe."""
@@ -633,17 +651,40 @@ class WebSocketChannel(BaseChannel):
             if not _is_valid_chat_id(cid):
                 await self._send_event(connection, "error", detail="invalid chat_id")
                 return
+            raw_turn_id = envelope.get("turn_id")
+            turn_id = raw_turn_id if isinstance(raw_turn_id, str) and raw_turn_id else None
+            rejection_fields = {
+                "chat_id": cid,
+                **({"turn_id": turn_id} if turn_id else {}),
+            }
+            # The allowlist can change while an authenticated websocket stays
+            # open. Reject the exact application turn before hydration,
+            # transcript persistence, or an acceptance ACK; BaseChannel's
+            # silent authorization return must not look like successful ingress.
+            if not self.is_allowed(client_id):
+                await self._send_event(
+                    connection,
+                    "error",
+                    detail="access_denied",
+                    **rejection_fields,
+                )
+                return
             if not isinstance(content, str):
-                await self._send_event(connection, "error", detail="missing content")
+                await self._send_event(
+                    connection,
+                    "error",
+                    detail="missing content",
+                    **rejection_fields,
+                )
                 return
             message_rejection = self._ingress.validate_text(content)
             if message_rejection is not None:
                 await self._send_event(
                     connection,
                     "error",
-                    chat_id=cid,
                     detail="message_rejected",
                     reason=message_rejection,
+                    **rejection_fields,
                 )
                 return
 
@@ -656,6 +697,7 @@ class WebSocketChannel(BaseChannel):
                         "error",
                         detail="attachment_rejected",
                         reason="malformed",
+                        **rejection_fields,
                     )
                     return
                 media_paths, reason = self._media.store_inbound_attachments(raw_media)
@@ -665,12 +707,18 @@ class WebSocketChannel(BaseChannel):
                         "error",
                         detail="attachment_rejected",
                         reason=reason,
+                        **rejection_fields,
                     )
                     return
 
             # Allow media-only turns (content may be empty when attachments are present).
             if not content.strip() and not media_paths:
-                await self._send_event(connection, "error", detail="missing content")
+                await self._send_event(
+                    connection,
+                    "error",
+                    detail="missing content",
+                    **rejection_fields,
+                )
                 return
             # Auto-attach on first use so clients can one-shot without a separate attach.
             self._attach(connection, cid)
@@ -686,10 +734,23 @@ class WebSocketChannel(BaseChannel):
                     controls_available=self._workspace_controls_available(connection),
                 ),
                 chat_id=cid,
+                turn_id=turn_id,
             )
             if scope is None:
                 return
 
+            # Hydration and scope resolution can yield. Re-check immediately
+            # before transcript/bus mutation so a mid-flight revocation cannot
+            # fall through BaseChannel's silent deny and still receive an ACK.
+            if not self.is_allowed(client_id):
+                await self._send_event(
+                    connection,
+                    "error",
+                    detail="access_denied",
+                    **rejection_fields,
+                )
+                return
+
             metadata: dict[str, Any] = {"remote": getattr(connection, "remote_address", None)}
             if envelope.get("webui") is True:
                 metadata["webui"] = True
@@ -702,29 +763,48 @@ class WebSocketChannel(BaseChannel):
                 metadata["mcp_presets"] = mcp_presets
             metadata[WORKSPACE_SCOPE_METADATA_KEY] = scope.metadata()
             self._workspaces.persist_scope(cid, scope)
-            if metadata.get("webui") is True and self.is_allowed(client_id):
+            is_webui = metadata.get("webui") is True
-                self._transcripts.append_user_message(
+            queued_owner = None
-                    cid,
+            if is_webui and builtin_command_starts_agent_turn(content):
-                    content,
+                queued_owner = register_queued_websocket_turn_if_idle(cid, turn_id)
+                if queued_owner is not None:
+                    metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] = queued_owner
+            accepted = False
+            try:
+                if is_webui:
+                    self._transcripts.append_user_message(
+                        cid,
+                        content,
+                        metadata=metadata,
+                        media_paths=media_paths or None,
+                        cli_apps=cli_apps or None,
+                        mcp_presets=mcp_presets or None,
+                    )
+                if is_webui and connection in self._webui_connections:
+                    quote = webui_quote_runtime_context({
+                        WEBUI_QUOTE_METADATA: envelope.get("quoted_context"),
+                    })
+                    if quote is not None:
+                        metadata[RUNTIME_CONTEXT_INPUT_META] = [quote]
+                await self._handle_message(
+                    sender_id=client_id,
+                    chat_id=cid,
+                    content=content,
+                    media=media_paths or None,
                     metadata=metadata,
-                    media_paths=media_paths or None,
+                    is_dm=False,
-                    cli_apps=cli_apps or None,
+                )
-                    mcp_presets=mcp_presets or None,
+                accepted = True
+            finally:
+                if not accepted and queued_owner is not None:
+                    clear_websocket_turn_if_current(cid, queued_owner)
+            if is_webui and turn_id:
+                await self._send_event(
+                    connection,
+                    "message_accepted",
+                    chat_id=cid,
+                    turn_id=turn_id,
                 )
-            if metadata.get("webui") is True and connection in self._webui_connections:
-                quote = webui_quote_runtime_context({
-                    WEBUI_QUOTE_METADATA: envelope.get("quoted_context"),
-                })
-                if quote is not None:
-                    metadata[RUNTIME_CONTEXT_INPUT_META] = [quote]
-            await self._handle_message(
-                sender_id=client_id,
-                chat_id=cid,
-                content=content,
-                media=media_paths or None,
-                metadata=metadata,
-                is_dm=False,
-            )
             return
         await self._send_event(connection, "error", detail=f"unknown type: {t!r}")
 
@@ -734,6 +814,7 @@ class WebSocketChannel(BaseChannel):
         resolver: Callable[[], Any],
         *,
         chat_id: str | None = None,
+        turn_id: str | None = None,
     ) -> Any | None:
         try:
             return resolver()
@@ -744,6 +825,7 @@ class WebSocketChannel(BaseChannel):
                 detail="workspace_scope_rejected",
                 reason=exc.message,
                 **({"chat_id": chat_id} if chat_id else {}),
+                **({"turn_id": turn_id} if turn_id else {}),
             )
             return None
 
@@ -782,6 +864,37 @@ class WebSocketChannel(BaseChannel):
             self.logger.exception("send failed{}", label)
             raise
 
+    def _persist_turn_transcript_event(
+        self,
+        chat_id: str,
+        event: dict[str, Any],
+        *,
+        metadata: dict[str, Any] | None,
+        phase: str,
+        include_source: bool = False,
+        transcript_overrides: dict[str, Any] | None = None,
+    ) -> bool:
+        """Persist one canonical turn event and retain unsafe owners on failure."""
+        persisted = self._transcripts.prepare_and_append(
+            chat_id,
+            event,
+            metadata=metadata,
+            phase=phase,
+            include_source=include_source,
+            transcript_overrides=transcript_overrides,
+        )
+        if (
+            not persisted
+            and phase in {"answer", "complete"}
+            and (metadata or {}).get("webui") is True
+        ):
+            owner = (metadata or {}).get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+            mark_websocket_turn_transcript_persistence_failed(
+                chat_id,
+                owner if isinstance(owner, str) else None,
+            )
+        return persisted
+
     async def send(self, msg: OutboundMessage) -> None:
         event = outbound_event_from_message(msg)
         progress_event = event if isinstance(event, ProgressEvent) else None
@@ -818,21 +931,38 @@ class WebSocketChannel(BaseChannel):
                 await self.send_goal_state(msg.chat_id, event.goal_state or {"active": False})
             return
         if isinstance(event, GoalStatusEvent):
-            if conns:
+            turn_id = (msg.metadata or {}).get(WEBUI_TURN_METADATA_KEY)
-                if event.status in ("running", "idle"):
+            current_turn_id = turn_id if isinstance(turn_id, str) else None
+            turn_owner = (msg.metadata or {}).get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+            current_turn_owner = turn_owner if isinstance(turn_owner, str) else None
+            try:
+                if conns and event.status in ("running", "idle"):
                     await self.send_goal_status(
                         msg.chat_id,
                         event.status,
                         started_at=event.started_at,
+                        turn_id=current_turn_id,
+                    )
+            finally:
+                if event.status == "idle":
+                    # Cancellation/direct runs may have no turn_end, so idle is
+                    # still terminal. A failed canonical completion write is
+                    # the one case that must remain pending for safe resume.
+                    clear_websocket_turn_if_current(
+                        msg.chat_id,
+                        current_turn_owner,
+                        preserve_persistence_failure=True,
                     )
             return
         # Signal that the agent has fully finished processing the current turn.
         if isinstance(event, TurnEndEvent):
+            turn_owner = (msg.metadata or {}).get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
             await self.send_turn_end(
                 msg.chat_id,
                 latency_ms=event.latency_ms,
                 goal_state=event.goal_state,
                 metadata=msg.metadata,
+                turn_owner=turn_owner if isinstance(turn_owner, str) else None,
             )
             await self.send_session_updated(msg.chat_id, scope="thread")
             return
@@ -884,7 +1014,7 @@ class WebSocketChannel(BaseChannel):
         elif progress_event:
             payload["kind"] = "progress"
         phase = "activity" if payload.get("kind") in ("tool_hint", "progress") else "answer"
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
             msg.chat_id,
             payload,
             metadata=msg.metadata,
@@ -922,7 +1052,7 @@ class WebSocketChannel(BaseChannel):
         }
         if stream_id is not None:
             body["stream_id"] = stream_id
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
             chat_id,
             body,
             metadata=meta,
@@ -950,7 +1080,7 @@ class WebSocketChannel(BaseChannel):
         }
         if stream_id is not None:
             body["stream_id"] = stream_id
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
             chat_id,
             body,
             metadata=meta,
@@ -974,7 +1104,7 @@ class WebSocketChannel(BaseChannel):
             "chat_id": chat_id,
             "edits": edits,
         }
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
             chat_id,
             payload,
             metadata=metadata,
@@ -1026,7 +1156,7 @@ class WebSocketChannel(BaseChannel):
             body["resuming"] = True
         if stream_end and merge_next:
             body["merge_next"] = True
-        self._transcripts.prepare_and_append(
+        self._persist_turn_transcript_event(
             chat_id,
             body,
             metadata=meta,
@@ -1045,6 +1175,7 @@ class WebSocketChannel(BaseChannel):
         *,
         goal_state: dict[str, Any] | None = None,
         metadata: dict[str, Any] | None = None,
+        turn_owner: str | None = None,
     ) -> None:
         """Signal that the agent has fully finished processing the current turn."""
         conns = list(self._subs.get(chat_id, ()))
@@ -1053,12 +1184,27 @@ class WebSocketChannel(BaseChannel):
             body["latency_ms"] = int(latency_ms)
         if goal_state is not None:
             body["goal_state"] = goal_state
-        self._transcripts.prepare_and_append(
+        canonical_webui_turn = (metadata or {}).get("webui") is True
+        prior_persistence_failure = (
+            canonical_webui_turn
+            and websocket_turn_transcript_persistence_failed(chat_id, turn_owner)
+        )
+        persisted = self._persist_turn_transcript_event(
             chat_id,
             body,
             metadata=metadata,
             phase="complete",
+            transcript_overrides=(
+                {WEBUI_TRANSCRIPT_INCOMPLETE_KEY: True}
+                if prior_persistence_failure
+                else None
+            ),
         )
+        if persisted:
+            # A successful completion either has a complete transcript or now
+            # carries a durable incomplete marker. The HTTP replay path can
+            # recover the latter from session history after a gateway restart.
+            clear_websocket_turn_if_current(chat_id, turn_owner)
         raw = json.dumps(body, ensure_ascii=False)
         if not conns:
             return
@@ -1081,6 +1227,7 @@ class WebSocketChannel(BaseChannel):
         status: str,
         *,
         started_at: float | None = None,
+        turn_id: str | None = None,
     ) -> None:
         """Notify subscribed clients that a turn started or finished (wall-clock hint)."""
         conns = list(self._subs.get(chat_id, ()))
@@ -1093,6 +1240,8 @@ class WebSocketChannel(BaseChannel):
         }
         if status == "running" and started_at is not None:
             body["started_at"] = started_at
+        if turn_id:
+            body["turn_id"] = turn_id
         raw = json.dumps(body, ensure_ascii=False)
         for connection in conns:
             await self._safe_send_to(connection, raw, label=" goal_status ")

nanobot/channels/websocket/tests/test_websocket_channel.py

@@ -49,8 +49,13 @@ from nanobot.webui.http_utils import (
 from nanobot.webui.http_utils import (
     parse_request_path as _parse_request_path,
 )
+from nanobot.webui.metadata import WEBSOCKET_TURN_OWNER_METADATA_KEY
 from nanobot.webui.settings_api import settings_payload, update_provider_settings
-from nanobot.webui.transcript import append_transcript_object, read_transcript_lines
+from nanobot.webui.transcript import (
+    append_transcript_object,
+    build_webui_thread_response,
+    read_transcript_lines,
+)
 
 from .ws_test_client import http_get as _http_get
 
@@ -164,11 +169,20 @@ async def test_start_extends_http_open_timeout_for_slow_settings_routes(
 
 @pytest.fixture(autouse=True)
 def isolate_webui_workspace_state(tmp_path, monkeypatch) -> None:
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
     monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
     monkeypatch.setattr(
         "nanobot.webui.workspaces.get_webui_dir",
         lambda: tmp_path / "webui",
     )
+    yield
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
 
 
 @pytest.mark.asyncio
@@ -743,6 +757,7 @@ async def test_webui_scope_rejects_running_scope_change(bus: MagicMock, tmp_path
                 "chat_id": "chat-running",
                 "content": "hello",
                 "webui": True,
+                "turn_id": "turn-scope-rejected",
                 "workspace_scope": {
                     "project_path": str(other),
                     "access_mode": "full",
@@ -757,6 +772,7 @@ async def test_webui_scope_rejects_running_scope_change(bus: MagicMock, tmp_path
     assert payload["detail"] == "workspace_scope_rejected"
     assert payload["reason"] == "chat_running"
     assert payload["chat_id"] == "chat-running"
+    assert payload["turn_id"] == "turn-scope-rejected"
     bus.publish_inbound.assert_not_awaited()
 
 
@@ -1602,6 +1618,434 @@ async def test_send_turn_end_emits_turn_end_event() -> None:
     ]
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("active_owner", "event_owner", "expected_cleared"),
+    [
+        ("owner-current", "owner-current", True),
+        ("owner-new", "owner-old", False),
+    ],
+)
+async def test_turn_end_persists_and_conditionally_clears_when_fanout_fails(
+    active_owner: str,
+    event_owner: str,
+    expected_cleared: bool,
+) -> None:
+    bus = MagicMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    mock_ws = AsyncMock()
+    mock_ws.send.side_effect = RuntimeError("fanout failed")
+    chat_id = f"turn-end-failure-{expected_cleared}"
+    channel._attach(mock_ws, chat_id)
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT[chat_id] = 1234.5
+    wth._WEBSOCKET_TURN_OWNERS[chat_id] = active_owner
+
+    try:
+        with pytest.raises(RuntimeError, match="fanout failed"):
+            await channel.send(OutboundMessage(
+                channel="websocket",
+                chat_id=chat_id,
+                content="",
+                metadata={WEBSOCKET_TURN_OWNER_METADATA_KEY: event_owner},
+                event=TurnEndEvent(),
+            ))
+
+        assert read_transcript_lines(f"websocket:{chat_id}")[-1]["event"] == "turn_end"
+        assert (wth.websocket_turn_wall_started_at(chat_id) is None) is expected_cleared
+        if not expected_cleared:
+            assert wth._WEBSOCKET_TURN_OWNERS[chat_id] == active_owner
+    finally:
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT.pop(chat_id, None)
+        wth._WEBSOCKET_TURN_IDS.pop(chat_id, None)
+        wth._WEBSOCKET_TURN_OWNERS.pop(chat_id, None)
+
+
+@pytest.mark.asyncio
+async def test_turn_end_keeps_registry_when_transcript_persistence_fails(
+    monkeypatch,
+) -> None:
+    from nanobot.bus.events import InboundMessage
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    chat_id = "turn-end-persistence-failure"
+    owner = "owner-persist"
+    turn_id = "turn-persist"
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="hi",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": turn_id,
+            "webui": True,
+        },
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+    append = MagicMock(side_effect=OSError("disk full"))
+    monkeypatch.setattr("nanobot.webui.transcript.append_transcript_object", append)
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": turn_id,
+            "webui": True,
+        },
+        event=TurnEndEvent(),
+    ))
+
+    append.assert_called_once()
+    assert wth.websocket_turn_wall_started_at(chat_id) == 1234.5
+    assert wth.websocket_turn_id(chat_id) == turn_id
+    assert wth._WEBSOCKET_TURN_OWNERS[chat_id] == owner
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=GoalStatusEvent(status="idle"),
+    ))
+
+    # The normal WebUI idle event follows turn_end. It must not convert a
+    # failed canonical completion write into an apparently settled HTTP
+    # snapshot.
+    assert wth.websocket_turn_wall_started_at(chat_id) == 1234.5
+    assert wth.websocket_turn_id(chat_id) == turn_id
+    assert wth._WEBSOCKET_TURN_OWNERS[chat_id] == owner
+
+
+@pytest.mark.asyncio
+async def test_durable_incomplete_marker_stays_pending_without_safe_session_recovery(
+    monkeypatch,
+) -> None:
+    from nanobot.bus.events import InboundMessage
+    from nanobot.webui.transcript import build_webui_thread_response
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    chat_id = "answer-persistence-failure"
+    key = f"websocket:{chat_id}"
+    owner = "owner-answer"
+    turn_id = "turn-answer"
+    append_transcript_object(
+        key,
+        {"event": "user", "chat_id": chat_id, "text": "question", "turn_id": turn_id},
+    )
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="question",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": turn_id,
+            "webui": True,
+        },
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+
+    original_append = append_transcript_object
+
+    def fail_answer(session_key: str, event: dict[str, Any]) -> None:
+        if event.get("event") == "message":
+            raise OSError("transient disk failure")
+        original_append(session_key, event)
+
+    monkeypatch.setattr("nanobot.webui.transcript.append_transcript_object", fail_answer)
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="answer",
+        metadata=dict(inbound.metadata),
+    ))
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=TurnEndEvent(),
+    ))
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=GoalStatusEvent(status="idle"),
+    ))
+
+    # Simulate a gateway restart: no process-local owner survives, so the
+    # persisted marker must be sufficient to reject canonical completion.
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
+    body = build_webui_thread_response(
+        key,
+        active_turn_started_at=wth.websocket_turn_wall_started_at(chat_id),
+        active_turn_id=wth.websocket_turn_id(chat_id),
+        active_turn_transcript_persistence_failed=(
+            wth.websocket_turn_transcript_persistence_failed(chat_id)
+        ),
+    )
+    assert body is not None
+    assert read_transcript_lines(key)[-1]["transcript_incomplete"] is True
+    assert body["completed_turn_ids"] == []
+    assert [(message["role"], message["content"]) for message in body["messages"]] == [
+        ("user", "question"),
+    ]
+    assert body["has_pending_tool_calls"] is True
+    assert chat_id not in wth._WEBSOCKET_TURN_OWNERS
+
+
+@pytest.mark.asyncio
+async def test_http_replay_recovers_marked_answer_from_session_after_gateway_restart(
+    tmp_path,
+    monkeypatch,
+) -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.bus.events import InboundMessage
+
+    chat_id = "answer-recovery-after-restart"
+    key = f"websocket:{chat_id}"
+    owner = "owner-answer-recovery"
+    turn_id = "turn-answer-recovery"
+    sessions_path = tmp_path / "sessions"
+    sessions = SessionManager(sessions_path)
+    session = sessions.get_or_create(key)
+    session.add_message("user", "question")
+    session.add_message("assistant", "durable answer")
+    sessions.save(session)
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": chat_id,
+            "text": "question",
+            "turn_id": turn_id,
+        },
+    )
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus, session_manager=sessions),
+    )
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="question",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": turn_id,
+            "webui": True,
+        },
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+
+    original_append = append_transcript_object
+
+    def fail_answer(session_key: str, event: dict[str, Any]) -> None:
+        if event.get("event") == "message":
+            raise OSError("transient disk failure")
+        original_append(session_key, event)
+
+    monkeypatch.setattr("nanobot.webui.transcript.append_transcript_object", fail_answer)
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="durable answer",
+        metadata=dict(inbound.metadata),
+    ))
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=TurnEndEvent(),
+    ))
+
+    persisted_lines = read_transcript_lines(key)
+    assert persisted_lines[-1]["event"] == "turn_end"
+    assert persisted_lines[-1]["transcript_incomplete"] is True
+
+    # Drop all process-local state and construct a fresh HTTP/session layer.
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
+    restarted_channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(
+            bus,
+            session_manager=SessionManager(sessions_path),
+        ),
+    )
+    restarted_channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    encoded_key = quote(key, safe="")
+    request = Request(
+        f"/api/sessions/{encoded_key}/webui-thread",
+        Headers([("Authorization", "Bearer tok")]),
+    )
+
+    response = restarted_channel.gateway.http._handle_webui_thread_get(
+        request,
+        encoded_key,
+    )
+
+    assert response.status_code == 200
+    body = json.loads(response.body.decode())
+    assert [(message["role"], message["content"]) for message in body["messages"]] == [
+        ("user", "question"),
+        ("assistant", "durable answer"),
+    ]
+    assert body["completed_turn_ids"] == [turn_id]
+    assert body["has_pending_tool_calls"] is False
+    assert body["active_turn_id"] is None
+
+
+@pytest.mark.asyncio
+async def test_webui_idle_clears_owner_when_no_completion_write_failed() -> None:
+    from nanobot.bus.events import InboundMessage
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    chat_id = "cancelled-webui-turn"
+    owner = "owner-cancelled"
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="hi",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: owner,
+            "webui_turn_id": "turn-cancelled",
+            "webui": True,
+        },
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=GoalStatusEvent(status="idle"),
+    ))
+
+    assert wth.websocket_turn_wall_started_at(chat_id) is None
+    assert wth.websocket_turn_id(chat_id) is None
+    assert chat_id not in wth._WEBSOCKET_ACTIVE_TURNS
+
+
+@pytest.mark.asyncio
+async def test_non_webui_transcript_failure_does_not_block_idle_cleanup(
+    monkeypatch,
+) -> None:
+    from nanobot.bus.events import InboundMessage
+
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    chat_id = "direct-non-webui-failure"
+    owner = "owner-direct"
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="runtime",
+        chat_id=chat_id,
+        content="direct",
+        metadata={WEBSOCKET_TURN_OWNER_METADATA_KEY: owner},
+    )
+    await wth.publish_turn_run_status(bus, inbound, "running", started_at=1234.5)
+    monkeypatch.setattr(
+        "nanobot.webui.transcript.append_transcript_object",
+        MagicMock(side_effect=OSError("disk full")),
+    )
+
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="direct answer",
+        metadata=dict(inbound.metadata),
+    ))
+
+    assert wth.websocket_turn_transcript_persistence_failed(chat_id, owner) is False
+    await channel.send(OutboundMessage(
+        channel="websocket",
+        chat_id=chat_id,
+        content="",
+        metadata=dict(inbound.metadata),
+        event=GoalStatusEvent(status="idle"),
+    ))
+    assert wth.websocket_turn_wall_started_at(chat_id) is None
+    assert chat_id not in wth._WEBSOCKET_ACTIVE_TURNS
+
+
+@pytest.mark.asyncio
+async def test_idle_clears_matching_owner_when_fanout_fails() -> None:
+    bus = MagicMock()
+    channel = WebSocketChannel(
+        {"enabled": True, "allowFrom": ["*"]},
+        bus,
+        gateway=_basic_handler(bus),
+    )
+    mock_ws = AsyncMock()
+    mock_ws.send.side_effect = RuntimeError("fanout failed")
+    chat_id = "idle-failure"
+    owner = "owner-idle"
+    channel._attach(mock_ws, chat_id)
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT[chat_id] = 1234.5
+    wth._WEBSOCKET_TURN_OWNERS[chat_id] = owner
+
+    with pytest.raises(RuntimeError, match="fanout failed"):
+        await channel.send(OutboundMessage(
+            channel="websocket",
+            chat_id=chat_id,
+            content="",
+            metadata={WEBSOCKET_TURN_OWNER_METADATA_KEY: owner},
+            event=GoalStatusEvent(status="idle"),
+        ))
+
+    assert wth.websocket_turn_wall_started_at(chat_id) is None
+    assert chat_id not in wth._WEBSOCKET_TURN_OWNERS
+
+
 @pytest.mark.asyncio
 async def test_send_turn_end_includes_latency_ms_when_present() -> None:
     bus = MagicMock()
@@ -1654,6 +2098,7 @@ async def test_send_goal_status_running_emits_event_with_started_at() -> None:
         channel="websocket",
         chat_id="chat-1",
         content="",
+        metadata={"webui_turn_id": "turn-running"},
         event=GoalStatusEvent(status="running", started_at=1_700_000_000.5),
     ))
 
@@ -1664,6 +2109,7 @@ async def test_send_goal_status_running_emits_event_with_started_at() -> None:
         "chat_id": "chat-1",
         "status": "running",
         "started_at": 1_700_000_000.5,
+        "turn_id": "turn-running",
     }
 
 
@@ -1678,12 +2124,18 @@ async def test_send_goal_status_idle_omits_started_at() -> None:
         channel="websocket",
         chat_id="chat-1",
         content="",
+        metadata={"webui_turn_id": "turn-idle"},
         event=GoalStatusEvent(status="idle", started_at=99.0),
     ))
 
     mock_ws.send.assert_awaited_once()
     body = json.loads(mock_ws.send.await_args.args[0])
-    assert body == {"event": "goal_status", "chat_id": "chat-1", "status": "idle"}
+    assert body == {
+        "event": "goal_status",
+        "chat_id": "chat-1",
+        "status": "idle",
+        "turn_id": "turn-idle",
+    }
 
 
 @pytest.mark.asyncio
@@ -2010,7 +2462,7 @@ async def test_settings_api_returns_safe_subset_and_updates_whitelist(
     port = 29891
     config_path = tmp_path / "config.json"
     config = Config()
-    config.agents.defaults.model = "openai/gpt-4o"
+    config.resolve_default_preset().model = "openai/gpt-4o"
     config.providers.openai.api_key = "secret-key"
     config.model_presets["deep"] = ModelPresetConfig(
         model="anthropic/claude-opus-4-5",
@@ -2343,8 +2795,8 @@ async def test_settings_api_returns_safe_subset_and_updates_whitelist(
         assert bad_image.status_code == 400
 
         saved = load_config(config_path)
-        assert saved.agents.defaults.model == "atomic_chat/test"
+        assert saved.resolve_default_preset().model == "atomic_chat/test"
-        assert saved.agents.defaults.provider == "atomic_chat"
+        assert saved.resolve_default_preset().provider == "atomic_chat"
         assert saved.agents.defaults.model_preset == "fast-writing"
         assert saved.agents.defaults.fallback_models == ["deep"]
         assert saved.model_presets["fast-writing"].label == "Codex"
@@ -2549,7 +3001,7 @@ def test_settings_payload_normalizes_camel_case_provider(
 ) -> None:
     config_path = tmp_path / "config.json"
     config = Config()
-    config.agents.defaults.provider = "minimaxAnthropic"
+    config.resolve_default_preset().provider = "minimaxAnthropic"
     save_config(config, config_path)
     monkeypatch.setattr("nanobot.config.loader._current_config_path", config_path)
 
@@ -2725,6 +3177,147 @@ async def test_allow_from_rejects_unauthorized_client_id(bus: MagicMock) -> None
         await server_task
 
 
+@pytest.mark.asyncio
+async def test_open_connection_rejects_revoked_webui_turn_without_acceptance_ack(
+    bus: MagicMock,
+) -> None:
+    channel = _ch(bus, allowFrom=["alice"])
+    conn = AsyncMock()
+    conn.remote_address = ("127.0.0.1", 50123)
+
+    await channel._dispatch_envelope(
+        conn,
+        "revoked-client",
+        {
+            "type": "message",
+            "chat_id": "chat-revoked",
+            "content": "must not enter the bus",
+            "webui": True,
+            "turn_id": "turn-revoked",
+        },
+    )
+
+    payloads = [json.loads(call.args[0]) for call in conn.send.await_args_list]
+    assert payloads == [
+        {
+            "event": "error",
+            "detail": "access_denied",
+            "chat_id": "chat-revoked",
+            "turn_id": "turn-revoked",
+        }
+    ]
+    bus.publish_inbound.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_midflight_allowlist_revocation_rejects_turn_without_ack(
+    bus: MagicMock,
+) -> None:
+    channel = _ch(bus)
+    channel.is_allowed = MagicMock(side_effect=[True, False])
+    conn = AsyncMock()
+    conn.remote_address = ("127.0.0.1", 50123)
+
+    await channel._dispatch_envelope(
+        conn,
+        "webui-client",
+        {
+            "type": "message",
+            "chat_id": "chat-midflight-revoked",
+            "content": "must not be acknowledged",
+            "webui": True,
+            "turn_id": "turn-midflight-revoked",
+        },
+    )
+
+    payloads = [json.loads(call.args[0]) for call in conn.send.await_args_list]
+    assert payloads[-1] == {
+        "event": "error",
+        "detail": "access_denied",
+        "chat_id": "chat-midflight-revoked",
+        "turn_id": "turn-midflight-revoked",
+    }
+    assert all(payload["event"] != "message_accepted" for payload in payloads)
+    bus.publish_inbound.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_authorized_webui_turn_is_acked_after_bus_acceptance(
+    bus: MagicMock,
+) -> None:
+    channel = _ch(bus)
+    conn = AsyncMock()
+    conn.remote_address = ("127.0.0.1", 50123)
+
+    await channel._dispatch_envelope(
+        conn,
+        "webui-client",
+        {
+            "type": "message",
+            "chat_id": "chat-accepted",
+            "content": "accepted",
+            "webui": True,
+            "turn_id": "turn-accepted",
+        },
+    )
+
+    bus.publish_inbound.assert_awaited_once()
+    inbound = bus.publish_inbound.await_args.args[0]
+    owner = inbound.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+    assert wth.websocket_turn_id("chat-accepted") == "turn-accepted"
+    assert wth.websocket_turn_wall_started_at("chat-accepted") is not None
+    assert wth.websocket_turn_owner_is_registered(
+        "chat-accepted",
+        owner,
+        "turn-accepted",
+    )
+    thread = build_webui_thread_response(
+        "websocket:chat-accepted",
+        active_turn_started_at=wth.websocket_turn_wall_started_at("chat-accepted"),
+        active_turn_id=wth.websocket_turn_id("chat-accepted"),
+    )
+    assert thread is not None
+    assert thread["active_turn_id"] == "turn-accepted"
+    assert thread["has_pending_tool_calls"] is True
+    payloads = [json.loads(call.args[0]) for call in conn.send.await_args_list]
+    assert payloads[-1] == {
+        "event": "message_accepted",
+        "chat_id": "chat-accepted",
+        "turn_id": "turn-accepted",
+    }
+
+
+@pytest.mark.asyncio
+async def test_side_channel_command_does_not_register_queued_turn(
+    bus: MagicMock,
+) -> None:
+    channel = _ch(bus)
+    conn = AsyncMock()
+    conn.remote_address = ("127.0.0.1", 50123)
+
+    await channel._dispatch_envelope(
+        conn,
+        "webui-client",
+        {
+            "type": "message",
+            "chat_id": "chat-status",
+            "content": "/status",
+            "webui": True,
+            "turn_id": "turn-status",
+        },
+    )
+
+    inbound = bus.publish_inbound.await_args.args[0]
+    assert WEBSOCKET_TURN_OWNER_METADATA_KEY not in inbound.metadata
+    assert wth.websocket_turn_wall_started_at("chat-status") is None
+    payloads = [json.loads(call.args[0]) for call in conn.send.await_args_list]
+    assert payloads[-1] == {
+        "event": "message_accepted",
+        "chat_id": "chat-status",
+        "turn_id": "turn-status",
+    }
+
+
 @pytest.mark.asyncio
 async def test_client_id_truncation(bus: MagicMock) -> None:
     port = 29883
@@ -3238,6 +3831,255 @@ def test_handle_webui_thread_get_returns_json(tmp_path, monkeypatch) -> None:
     assert len(body["messages"]) == 1
     assert body["messages"][0]["role"] == "user"
     assert body["messages"][0]["content"] == "hi"
+    assert body["has_pending_tool_calls"] is False
+
+
+def test_handle_webui_thread_get_reports_registered_turn_as_pending(
+    tmp_path,
+    monkeypatch,
+) -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.webui.transcript import append_transcript_object
+
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    monkeypatch.setattr(
+        "nanobot.session.webui_turns.websocket_turn_wall_started_at",
+        lambda chat_id: 1_700_000_000.0 if chat_id == "running" else None,
+    )
+    monkeypatch.setattr(
+        "nanobot.session.webui_turns.websocket_turn_id",
+        lambda chat_id: "turn-running" if chat_id == "running" else None,
+    )
+    key = "websocket:running"
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": "running",
+            "text": "hi",
+            "turn_id": "turn-running",
+        },
+    )
+    bus = MagicMock()
+    channel = _ch(bus)
+    channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    enc = quote(key, safe="")
+    req = Request(f"/api/sessions/{enc}/webui-thread", Headers([("Authorization", "Bearer tok")]))
+
+    resp = channel.gateway.http._handle_webui_thread_get(req, enc)
+
+    assert resp.status_code == 200
+    body = json.loads(resp.body.decode())
+    assert body["messages"][0]["content"] == "hi"
+    assert body["has_pending_tool_calls"] is True
+
+
+@pytest.mark.asyncio
+async def test_idle_registry_stays_pending_until_turn_end_is_persisted(
+    tmp_path,
+    monkeypatch,
+) -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.bus.events import InboundMessage
+    from nanobot.session import webui_turns as wth
+    from nanobot.webui.transcript import append_transcript_object
+
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    key = "websocket:idle-order"
+    turn_id = "turn-idle-order"
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": "idle-order",
+            "text": "hi",
+            "turn_id": turn_id,
+        },
+    )
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    inbound = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id="idle-order",
+        content="hi",
+        metadata={"webui_turn_id": turn_id},
+    )
+    channel = _ch(bus)
+    channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    enc = quote(key, safe="")
+    request = Request(
+        f"/api/sessions/{enc}/webui-thread",
+        Headers([("Authorization", "Bearer tok")]),
+    )
+
+    try:
+        await wth.publish_turn_run_status(bus, inbound, "running")
+        await wth.publish_turn_run_status(bus, inbound, "idle")
+
+        before_delivery = channel.gateway.http._handle_webui_thread_get(request, enc)
+        assert json.loads(before_delivery.body.decode())["has_pending_tool_calls"] is True
+
+        await channel.send(OutboundMessage(
+            channel="websocket",
+            chat_id="idle-order",
+            content="",
+            metadata=dict(inbound.metadata),
+            event=TurnEndEvent(),
+        ))
+
+        after_delivery = channel.gateway.http._handle_webui_thread_get(request, enc)
+        assert json.loads(after_delivery.body.decode())["has_pending_tool_calls"] is False
+        assert wth.websocket_turn_wall_started_at("idle-order") is None
+        assert wth.websocket_turn_id("idle-order") is None
+    finally:
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT.pop("idle-order", None)
+        wth._WEBSOCKET_TURN_IDS.pop("idle-order", None)
+        wth._WEBSOCKET_TURN_OWNERS.pop("idle-order", None)
+
+
+@pytest.mark.asyncio
+async def test_webui_thread_api_restores_older_owner_after_latest_completes() -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.bus.events import InboundMessage
+
+    chat_id = "concurrent-projection"
+    key = f"websocket:{chat_id}"
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": chat_id,
+            "text": "first",
+            "turn_id": "turn-first",
+        },
+    )
+    bus = MagicMock()
+    bus.publish_outbound = AsyncMock()
+    first = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="first",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: "owner-first",
+            "webui_turn_id": "turn-first",
+        },
+        session_key_override="websocket:session-first",
+    )
+    second = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id=chat_id,
+        content="second",
+        metadata={
+            WEBSOCKET_TURN_OWNER_METADATA_KEY: "owner-second",
+            "webui_turn_id": "turn-second",
+        },
+        session_key_override="websocket:session-second",
+    )
+    await wth.publish_turn_run_status(bus, first, "running", started_at=100.0)
+    await wth.publish_turn_run_status(bus, second, "running", started_at=200.0)
+    assert wth.clear_websocket_turn_if_current(chat_id, "owner-second") is True
+
+    channel = _ch(bus)
+    channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    enc = quote(key, safe="")
+    request = Request(
+        f"/api/sessions/{enc}/webui-thread",
+        Headers([("Authorization", "Bearer tok")]),
+    )
+    response = channel.gateway.http._handle_webui_thread_get(request, enc)
+
+    assert response.status_code == 200
+    payload = json.loads(response.body.decode())
+    assert payload["has_pending_tool_calls"] is True
+    assert wth.websocket_turn_wall_started_at(chat_id) == 100.0
+    assert wth.websocket_turn_id(chat_id) == "turn-first"
+    assert wth._WEBSOCKET_TURN_OWNERS[chat_id] == "owner-first"
+
+
+@pytest.mark.parametrize(
+    ("active_turn_id", "expected_pending"),
+    [
+        ("turn-complete", False),
+        ("turn-next", True),
+    ],
+)
+def test_handle_webui_thread_get_reconciles_registered_turn_with_turn_end(
+    tmp_path,
+    monkeypatch,
+    active_turn_id: str,
+    expected_pending: bool,
+) -> None:
+    from urllib.parse import quote
+
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    from nanobot.webui.transcript import append_transcript_object
+
+    monkeypatch.setattr("nanobot.config.paths.get_data_dir", lambda: tmp_path)
+    monkeypatch.setattr(
+        "nanobot.session.webui_turns.websocket_turn_wall_started_at",
+        lambda chat_id: 1_700_000_000.0 if chat_id == "running" else None,
+    )
+    monkeypatch.setattr(
+        "nanobot.session.webui_turns.websocket_turn_id",
+        lambda chat_id: active_turn_id if chat_id == "running" else None,
+    )
+    key = "websocket:running"
+    append_transcript_object(
+        key,
+        {
+            "event": "user",
+            "chat_id": "running",
+            "text": "hi",
+            "turn_id": "turn-complete",
+        },
+    )
+    append_transcript_object(
+        key,
+        {
+            "event": "message",
+            "chat_id": "running",
+            "text": "done",
+            "turn_id": "turn-complete",
+        },
+    )
+    append_transcript_object(
+        key,
+        {
+            "event": "turn_end",
+            "chat_id": "running",
+            "turn_id": "turn-complete",
+        },
+    )
+    bus = MagicMock()
+    channel = _ch(bus)
+    channel.gateway.tokens.api_tokens["tok"] = time.monotonic() + 300.0
+    enc = quote(key, safe="")
+    req = Request(f"/api/sessions/{enc}/webui-thread", Headers([("Authorization", "Bearer tok")]))
+
+    resp = channel.gateway.http._handle_webui_thread_get(req, enc)
+
+    assert resp.status_code == 200
+    body = json.loads(resp.body.decode())
+    assert body["messages"][-1]["content"] == "done"
+    assert body["has_pending_tool_calls"] is expected_pending
+    assert body["active_turn_id"] == active_turn_id
 
 
 def test_handle_webui_thread_get_accepts_pagination_query(tmp_path, monkeypatch) -> None:

nanobot/channels/websocket/tests/test_websocket_envelope_media.py

@@ -19,6 +19,7 @@ from nanobot.channels.websocket.runtime import (
     WebSocketChannel,
     WebSocketConfig,
 )
+from nanobot.session import webui_turns as wth
 from nanobot.webui.gateway_services import build_gateway_services
 
 
@@ -59,6 +60,19 @@ def _make_channel() -> WebSocketChannel:
     return channel
 
 
+@pytest.fixture(autouse=True)
+def isolate_websocket_turn_state() -> None:
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
+    yield
+    wth._WEBSOCKET_ACTIVE_TURNS.clear()
+    wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+    wth._WEBSOCKET_TURN_IDS.clear()
+    wth._WEBSOCKET_TURN_OWNERS.clear()
+
+
 # -- max_message_bytes bump ----------------------------------------------------
 
 
@@ -94,6 +108,28 @@ async def test_message_without_media_backward_compatible() -> None:
     assert call.kwargs["media"] is None
 
 
+@pytest.mark.asyncio
+async def test_webui_message_acceptance_echoes_turn_id() -> None:
+    channel = _make_channel()
+    mock_conn = AsyncMock()
+    envelope = {
+        "type": "message",
+        "chat_id": "abc123",
+        "content": "hello",
+        "webui": True,
+        "turn_id": "turn-accepted",
+    }
+
+    await channel._dispatch_envelope(mock_conn, "client-1", envelope)
+
+    channel._handle_message.assert_awaited_once()
+    assert json.loads(mock_conn.send.await_args.args[0]) == {
+        "event": "message_accepted",
+        "chat_id": "abc123",
+        "turn_id": "turn-accepted",
+    }
+
+
 @pytest.mark.asyncio
 async def test_message_text_policy_is_independent_from_transport_limit() -> None:
     channel = _make_channel()
@@ -102,6 +138,7 @@ async def test_message_text_policy_is_independent_from_transport_limit() -> None
         "type": "message",
         "chat_id": "abc123",
         "content": "你" * 22_000,
+        "turn_id": "turn-text-policy",
     }
 
     await channel._dispatch_envelope(mock_conn, "client-1", envelope)
@@ -113,6 +150,7 @@ async def test_message_text_policy_is_independent_from_transport_limit() -> None
         "chat_id": "abc123",
         "detail": "message_rejected",
         "reason": "text_too_large",
+        "turn_id": "turn-text-policy",
     }
 
 
@@ -235,6 +273,7 @@ async def test_message_rejected_when_more_than_four_images(tmp_path) -> None:
         "chat_id": "abc123",
         "content": "hi",
         "media": [{"data_url": _tiny_png_data_url()}] * 5,
+        "turn_id": "turn-attachments",
     }
 
     with patch(
@@ -246,8 +285,10 @@ async def test_message_rejected_when_more_than_four_images(tmp_path) -> None:
     mock_conn.send.assert_awaited_once()
     err = json.loads(mock_conn.send.call_args[0][0])
     assert err["event"] == "error"
+    assert err["chat_id"] == "abc123"
     assert err["detail"] == "attachment_rejected"
     assert err["reason"] == "too_many_images"
+    assert err["turn_id"] == "turn-attachments"
 
 
 @pytest.mark.asyncio

nanobot/channels/websocket/tests/test_websocket_reconnect_idle.py

@@ -53,9 +53,19 @@ async def test_hydrate_after_subscribe_pushes_running_when_turn_active():
     channel.send_goal_state = mock_send_goal_state
     channel.send_goal_status = mock_send_goal_status
 
-    with patch("nanobot.channels.websocket.runtime.websocket_turn_wall_started_at", return_value=1234567890.0):
+    with (
+        patch(
+            "nanobot.channels.websocket.runtime.websocket_turn_wall_started_at",
+            return_value=1234567890.0,
+        ),
+        patch(
+            "nanobot.channels.websocket.runtime.websocket_turn_id",
+            return_value="turn-active",
+        ),
+    ):
         await channel._hydrate_after_subscribe("test-chat")
 
     running_events = [e for e in sent_events if e[0] == "goal_status" and e[2] == "running"]
     assert len(running_events) == 1
     assert running_events[0][3]["started_at"] == 1234567890.0
+    assert running_events[0][3]["turn_id"] == "turn-active"

nanobot/cli/commands.py

@@ -54,6 +54,7 @@ from prompt_toolkit.history import FileHistory  # noqa: E402
 from prompt_toolkit.key_binding import KeyBindings  # noqa: E402
 from prompt_toolkit.keys import Keys  # noqa: E402
 from prompt_toolkit.patch_stdout import patch_stdout  # noqa: E402
+from pydantic import ValidationError  # noqa: E402
 from rich.console import Console  # noqa: E402
 from rich.markdown import Markdown  # noqa: E402
 from rich.markup import escape  # noqa: E402
@@ -72,7 +73,6 @@ from nanobot.bus.outbound_events import (  # noqa: E402
     StreamEndEvent,
     outbound_event_from_message,
 )
-from nanobot.cli.extensions import create_extensions_app  # noqa: E402
 from nanobot.cli.gateway import create_gateway_app  # noqa: E402
 from nanobot.cli.stream import StreamRenderer, ThinkingSpinner  # noqa: E402
 from nanobot.config.paths import get_workspace_path, is_default_workspace  # noqa: E402
@@ -794,13 +794,93 @@ def _model_display(config: Config) -> tuple[str, str]:
     """Return (resolved_model_name, preset_tag) for display strings."""
     resolved = config.resolve_preset()
     name = config.agents.defaults.model_preset
-    tag = f" (preset: {name})" if name else ""
+    tag = f" (preset: {name})" if name != "default" else ""
     return resolved.model, tag
 
 
+def _print_config_error(error: Exception) -> None:
+    """Render a configuration failure without exposing traceback internals."""
+    from nanobot.config.errors import ConfigLoadError
+
+    console.print(Text(str(error), style="red"))
+    if isinstance(error, ConfigLoadError):
+        command = _status_command(error.path)
+        console.print(f"[dim]Check again after editing: {escape(command)}[/dim]")
+
+
+def _print_runtime_config_validation_error(
+    error: ValidationError,
+    *,
+    config_path: Path,
+    summary: str,
+    path_prefix: tuple[str | int, ...],
+    retry_command: str,
+) -> None:
+    """Render a runtime-owned Pydantic config error without exposing input values."""
+    from nanobot.config.errors import ConfigIssue, ConfigLoadError, validation_issues
+
+    issues = tuple(
+        ConfigIssue(
+            path=(*path_prefix, *issue.path),
+            message=issue.message,
+        )
+        for issue in validation_issues(error)
+    )
+    diagnostic = ConfigLoadError(
+        config_path,
+        kind="invalid_schema",
+        summary=summary,
+        issues=issues,
+    )
+    console.print(Text(str(diagnostic), style="red"))
+    console.print(f"[dim]Fix the listed setting, then retry: {escape(retry_command)}[/dim]")
+
+
+def _status_command(config_path: Path) -> str:
+    return f'nanobot status --config "{config_path}"'
+
+
+def _print_model_setup_steps(config_path: Path) -> None:
+    """Show the shortest setup routes shared by Status and Agent startup."""
+    config_arg = f'--config "{config_path}"'
+    console.print(
+        f"  WebUI: run [cyan]nanobot webui {escape(config_arg)}[/cyan], "
+        "then open Settings → Models"
+    )
+    console.print(f"  CLI:   run [cyan]nanobot onboard --wizard {escape(config_arg)}[/cyan]")
+    console.print(f"  Check: [cyan]{escape(_status_command(config_path))}[/cyan]")
+
+
+def _print_agent_start_error(error: ValueError) -> None:
+    from nanobot.config.loader import get_config_path
+
+    console.print(Text(f"Agent cannot start: {error}", style="red"))
+    console.print("Complete provider/model setup:")
+    _print_model_setup_steps(get_config_path())
+
+
+def _load_config_for_cli(
+    config_path: Path | None = None,
+    *,
+    resolve_env: bool = False,
+) -> Config:
+    """Load CLI configuration and turn expected failures into a clean exit."""
+    from nanobot.config.errors import ConfigLoadError
+    from nanobot.config.loader import load_config, resolve_config_env_vars
+
+    try:
+        loaded = load_config(config_path)
+        if resolve_env:
+            loaded = resolve_config_env_vars(loaded)
+        return loaded
+    except ConfigLoadError as exc:
+        _print_config_error(exc)
+        raise typer.Exit(1) from exc
+
+
 def _load_runtime_config(config: str | None = None, workspace: str | None = None) -> Config:
     """Load config and optionally override the active workspace."""
-    from nanobot.config.loader import load_config, resolve_config_env_vars, set_config_path
+    from nanobot.config.loader import set_config_path
 
     config_path = None
     if config:
@@ -811,11 +891,7 @@ def _load_runtime_config(config: str | None = None, workspace: str | None = None
         set_config_path(config_path)
         console.print(f"[dim]Using config: {config_path}[/dim]")
 
-    try:
+    loaded = _load_config_for_cli(config_path, resolve_env=True)
-        loaded = resolve_config_env_vars(load_config(config_path))
-    except ValueError as e:
-        console.print(f"[red]Error: {e}[/red]")
-        raise typer.Exit(1)
     if workspace:
         loaded.agents.defaults.workspace = workspace
     return loaded
@@ -841,6 +917,7 @@ def _load_inspection_config(
     workspace: str | None = None,
 ) -> tuple[Path, Config]:
     """Load config for diagnostic commands without resolving secret env refs."""
+    from nanobot.config.errors import ConfigLoadError
     from nanobot.config.loader import get_config_path, load_config, set_config_path
 
     config_path = None
@@ -852,6 +929,9 @@ def _load_inspection_config(
     display_path = config_path or get_config_path()
     try:
         loaded = load_config(config_path)
+    except ConfigLoadError as exc:
+        _print_config_error(exc)
+        raise typer.Exit(1) from exc
     except ValueError as exc:
         console.print(f"[red]Error: {exc}[/red]")
         raise typer.Exit(1) from exc
@@ -902,21 +982,15 @@ def _resolve_webui_config_path(config: str | None) -> Path:
 
 def _load_webui_setup_config(config_path: Path) -> Config:
     """Load config for first-run mutation without resolving env-var placeholders."""
-    from nanobot.config.loader import load_config
+    return _load_config_for_cli(config_path)
-
-    try:
-        return load_config(config_path)
-    except ValueError as e:
-        console.print(f"[red]Error: {e}[/red]")
-        raise typer.Exit(1) from e
 
 
 def _provider_setup_error(config: Config) -> str | None:
-    """Return the provider setup error, or None when the current model can start."""
+    """Return a local provider/model configuration error, or None."""
-    from nanobot.providers.factory import build_provider_snapshot
+    from nanobot.providers.factory import validate_provider_setup
 
     try:
-        build_provider_snapshot(config)
+        validate_provider_setup(config)
     except ValueError as exc:
         return str(exc)
     return None
@@ -938,6 +1012,60 @@ def _webui_channel_enabled(config: Config) -> bool:
     return bool(WebSocketConfig.model_validate(current).enabled)
 
 
+def _validate_gateway_startup(config: Config) -> str | None:
+    """Validate gateway startup and return a provider error recoverable through WebUI."""
+    from nanobot.config.loader import get_config_path
+
+    config_path = get_config_path()
+    try:
+        webui_config = _webui_config_dict(config)
+    except ValidationError as exc:
+        retry_command = f'nanobot gateway --config "{config_path}"'
+        _print_runtime_config_validation_error(
+            exc,
+            config_path=config_path,
+            summary="Gateway configuration is invalid.",
+            path_prefix=("channels", "websocket"),
+            retry_command=retry_command,
+        )
+        raise typer.Exit(1) from exc
+
+    provider_error = _provider_setup_error(config)
+    if not provider_error:
+        return None
+
+    if bool(webui_config["enabled"]):
+        console.print(
+            Text(f"Provider/model setup is incomplete: {provider_error}", style="yellow")
+        )
+        console.print(
+            "Gateway will start so you can configure a provider and model "
+            "in WebUI Settings → Models."
+        )
+        browser_url = _webui_browser_url(config)
+        webui_url = browser_url.split("/#/", 1)[0]
+        console.print(Text(f"WebUI: {webui_url}", style="cyan"))
+        if browser_url != webui_url:
+            secret_key = (
+                "tokenIssueSecret"
+                if str(webui_config.get("tokenIssueSecret") or "").strip()
+                else "token"
+            )
+            console.print(
+                Text(
+                    f"If prompted, enter the configured channels.websocket.{secret_key} "
+                    f"value (see {config_path}).",
+                    style="dim",
+                )
+            )
+        return provider_error
+
+    console.print(Text(f"Gateway cannot start: {provider_error}", style="red"))
+    console.print("Complete provider/model setup:")
+    _print_model_setup_steps(config_path)
+    raise typer.Exit(1)
+
+
 def _prepare_webui_bundle_for_gateway(
     config: Config,
     *,
@@ -1235,14 +1363,20 @@ def _gateway_instance_command(
     return " ".join(shlex.quote(part) for part in parts)
 
 
-def _run_quick_start_for_webui(config: Config, *, yes: bool) -> Config:
+def _run_quick_start_for_webui(
+    config: Config,
+    *,
+    yes: bool,
+    config_path: Path,
+) -> Config:
     """Offer the existing Quick Start flow when provider setup is missing."""
     if yes:
         console.print(
             "[red]Error: provider/model setup is incomplete, and --yes cannot answer "
-            "provider credentials. Run `nanobot webui` interactively or "
+            "provider credentials.[/red]"
-            "`nanobot onboard --wizard`.[/red]"
         )
+        console.print("Complete provider/model setup:")
+        _print_model_setup_steps(config_path)
         raise typer.Exit(1)
 
     console.print()
@@ -1329,7 +1463,6 @@ def serve(
 
     from nanobot.api.server import create_app
     from nanobot.bus.queue import MessageBus
-    from nanobot.extensions.host import ExtensionHost
     from nanobot.providers.image_generation import image_gen_provider_configs
     from nanobot.session.manager import SessionManager
 
@@ -1378,17 +1511,12 @@ def serve(
         agent_loop, model_name=model_name, request_timeout=timeout,
         api_key=api_key,
     )
-    extension_host = ExtensionHost(agent_loop, lambda: runtime_config)
 
     async def on_startup(_app):
         await agent_loop._connect_mcp()
-        await extension_host.reload()
 
     async def on_cleanup(_app):
-        try:
+        await agent_loop.close_mcp()
-            await extension_host.close()
-        finally:
-            await agent_loop.close_mcp()
 
     api_app.on_startup.append(on_startup)
     api_app.on_cleanup.append(on_cleanup)
@@ -1440,9 +1568,12 @@ def webui(
         setup_config.agents.defaults.workspace = workspace
 
     try:
-        resolved_setup_config = resolve_config_env_vars(setup_config.model_copy(deep=True))
+        resolved_setup_config = resolve_config_env_vars(
+            setup_config.model_copy(deep=True),
+            config_path=config_path,
+        )
     except ValueError as exc:
-        console.print(f"[red]Error: {exc}[/red]")
+        _print_config_error(exc)
         raise typer.Exit(1) from exc
 
     provider_error = _provider_setup_error(resolved_setup_config)
@@ -1458,7 +1589,11 @@ def webui(
             raise typer.Exit(1)
     elif provider_error:
         console.print(f"[dim]Provider check: {provider_error}[/dim]")
-        setup_config = _run_quick_start_for_webui(setup_config, yes=yes)
+        setup_config = _run_quick_start_for_webui(
+            setup_config,
+            yes=yes,
+            config_path=config_path,
+        )
         if workspace:
             setup_config.agents.defaults.workspace = workspace
 
@@ -1470,6 +1605,16 @@ def webui(
         )
         _warn_webui_bind_scope(setup_config)
         webui_url = _webui_browser_url(setup_config)
+    except ValidationError as exc:
+        retry_command = f'nanobot webui --config "{config_path}"'
+        _print_runtime_config_validation_error(
+            exc,
+            config_path=config_path,
+            summary="WebUI configuration is invalid.",
+            path_prefix=("channels", "websocket"),
+            retry_command=retry_command,
+        )
+        raise typer.Exit(1) from exc
     except ValueError as exc:
         console.print(f"[red]Error: invalid WebUI channel config: {exc}[/red]")
         raise typer.Exit(1) from exc
@@ -1632,8 +1777,6 @@ def _run_gateway(
     from nanobot.cron.service import CronJobSkippedError, CronService
     from nanobot.cron.session_turns import is_bound_cron_job
     from nanobot.cron.types import CronJob
-    from nanobot.extensions.host import ExtensionHost
-    from nanobot.extensions.service import ExtensionService
     from nanobot.providers.factory import (
         build_provider_snapshot,
         build_unconfigured_provider_snapshot,
@@ -1753,8 +1896,6 @@ def _run_gateway(
         local_trigger_store=trigger_store,
         hook_factories=[create_file_edit_activity_hook],
     )
-    extension_host = ExtensionHost(agent, lambda: config)
-    extension_service = ExtensionService(host=extension_host)
     webui_turn_coordinator = WebuiTurnCoordinator(
         bus=bus,
         sessions=session_manager,
@@ -1831,12 +1972,17 @@ def _run_gateway(
                     return None
                 prompt, last_cursor = result
                 key = dream_session_key()
+                resolve_dream_runtime = getattr(agent, "dream_runtime", None)
+                dream_runtime = (
+                    resolve_dream_runtime() if callable(resolve_dream_runtime) else None
+                )
                 resp = await agent.process_direct(
                     prompt,
                     session_key=key,
                     ephemeral=True,
                     tools=store.build_dream_tools(),
                     on_progress=progress,
+                    runtime=dream_runtime,
                 )
                 # The real file delta grounds the audit record; clean completion
                 # decides whether this history batch has finished processing.
@@ -1989,7 +2135,6 @@ def _run_gateway(
         webui_static_dist=webui_static_dist,
         webui_runtime_surface=webui_runtime_surface,
         webui_runtime_capabilities=webui_runtime_capabilities,
-        webui_extension_service=extension_service,
     )
 
     def _pick_heartbeat_target() -> tuple[str, str]:
@@ -2145,7 +2290,6 @@ def _run_gateway(
             console.print,
         )
         try:
-            await extension_host.reload()
             await cron.start()
             # Re-read once on first admission to close the watcher subscription window.
             agent.runtime_resolver.invalidate()
@@ -2225,10 +2369,7 @@ def _run_gateway(
                 if flushed:
                     logger.info("Shutdown: flushed {} session(s) to disk", flushed)
             finally:
-                try:
+                restore_shutdown_handlers()
-                    await extension_host.close()
-                finally:
-                    restore_shutdown_handlers()
 
     asyncio.run(run())
 
@@ -2239,6 +2380,7 @@ app.add_typer(
         log_handler_id=_log_handler_id,
         load_runtime_config=_load_runtime_config,
         run_gateway=_run_gateway,
+        validate_startup_config=_validate_gateway_startup,
         prepare_webui_bundle=lambda config, mode: _prepare_webui_bundle_for_gateway(
             config,
             mode=mode,
@@ -2265,10 +2407,16 @@ def agent(
     """Interact with the agent directly."""
     from nanobot.bus.queue import MessageBus
     from nanobot.cron.service import CronService
-    from nanobot.extensions.host import ExtensionHost
+    from nanobot.providers.factory import make_provider
     from nanobot.providers.image_generation import image_gen_provider_configs
 
     config = _load_runtime_config(config, workspace)
+    try:
+        provider = make_provider(config)
+    except ValueError as exc:
+        _print_agent_start_error(exc)
+        raise typer.Exit(1) from exc
+
     sync_workspace_templates(config.workspace_path)
 
     bus = MessageBus()
@@ -2286,14 +2434,14 @@ def agent(
     try:
         agent_loop = AgentLoop.from_config(
             config, bus,
+            provider=provider,
             cron_service=cron,
             image_generation_provider_configs=image_gen_provider_configs(config),
             hook_factories=[create_file_edit_activity_hook],
         )
     except ValueError as exc:
-        console.print(f"[red]Error: {exc}[/red]")
+        _print_agent_start_error(exc)
         raise typer.Exit(1) from exc
-    extension_host = ExtensionHost(agent_loop, lambda: config)
     restart_notice = consume_restart_notice_from_env()
     if restart_notice and should_show_cli_restart_notice(restart_notice, session_id):
         _print_agent_response(
@@ -2335,36 +2483,29 @@ def agent(
     if message:
         # Single message mode — direct call, no bus needed
         async def run_once():
-            try:
+            renderer = StreamRenderer(
-                await extension_host.reload()
+                render_markdown=markdown,
-                renderer = StreamRenderer(
+                bot_name=config.agents.defaults.bot_name,
+                bot_icon=config.agents.defaults.bot_icon,
+            )
+            response = await agent_loop.process_direct(
+                message, session_id,
+                on_progress=_make_progress(renderer),
+                on_stream=renderer.on_delta,
+                on_stream_end=renderer.on_end,
+            )
+            if not renderer.streamed:
+                await renderer.close()
+                print_kwargs: dict[str, Any] = {}
+                if renderer.header_printed:
+                    print_kwargs["show_header"] = False
+                _print_agent_response(
+                    response.content if response else "",
                     render_markdown=markdown,
-                    bot_name=config.agents.defaults.bot_name,
+                    metadata=response.metadata if response else None,
-                    bot_icon=config.agents.defaults.bot_icon,
+                    **print_kwargs,
                 )
-                response = await agent_loop.process_direct(
+            await agent_loop.close_mcp()
-                    message,
-                    session_id,
-                    on_progress=_make_progress(renderer),
-                    on_stream=renderer.on_delta,
-                    on_stream_end=renderer.on_end,
-                )
-                if not renderer.streamed:
-                    await renderer.close()
-                    print_kwargs: dict[str, Any] = {}
-                    if renderer.header_printed:
-                        print_kwargs["show_header"] = False
-                    _print_agent_response(
-                        response.content if response else "",
-                        render_markdown=markdown,
-                        metadata=response.metadata if response else None,
-                        **print_kwargs,
-                    )
-            finally:
-                try:
-                    await agent_loop.close_mcp()
-                finally:
-                    await extension_host.close()
 
         asyncio.run(run_once())
     else:
@@ -2397,7 +2538,6 @@ def agent(
             signal.signal(signal.SIGPIPE, signal.SIG_IGN)
 
         async def run_interactive():
-            await extension_host.reload()
             bus_task = asyncio.create_task(agent_loop.run())
             turn_done = asyncio.Event()
             turn_done.set()
@@ -2529,10 +2669,7 @@ def agent(
                 agent_loop.stop()
                 outbound_task.cancel()
                 await asyncio.gather(bus_task, outbound_task, return_exceptions=True)
-                try:
+                await agent_loop.close_mcp()
-                    await agent_loop.close_mcp()
-                finally:
-                    await extension_host.close()
 
         asyncio.run(run_interactive())
 
@@ -2542,8 +2679,6 @@ def agent(
 # ============================================================================
 
 
-app.add_typer(create_extensions_app(console=console), name="extensions")
-
 channels_app = typer.Typer(help="Manage channels")
 app.add_typer(channels_app, name="channels")
 
@@ -2709,11 +2844,32 @@ def status(
     )
 
     if config_path.exists():
+        from nanobot.config.errors import ConfigLoadError
+        from nanobot.config.loader import resolve_config_env_vars, resolve_env_refs
         from nanobot.providers.registry import PROVIDERS
 
         _model, _preset_tag = _model_display(loaded)
         console.print(f"Model: {_model}{_preset_tag}")
 
+        provider_ready = False
+        try:
+            resolved = resolve_config_env_vars(
+                loaded.model_copy(deep=True),
+                config_path=config_path,
+            )
+        except ConfigLoadError as exc:
+            console.print("Agent: [red]✗ configuration is not ready[/red]")
+            _print_config_error(exc)
+        else:
+            provider_error = _provider_setup_error(resolved)
+            if provider_error:
+                console.print(Text(f"Agent: ✗ {provider_error}", style="red"))
+                console.print("Complete provider/model setup:")
+                _print_model_setup_steps(config_path)
+            else:
+                provider_ready = True
+                console.print("Agent: [green]✓ provider/model configuration is ready[/green]")
+
         # Check API keys from registry
         for spec in PROVIDERS:
             p = getattr(loaded.providers, spec.name, None)
@@ -2723,14 +2879,25 @@ def status(
                 console.print(f"{spec.label}: [green]✓ (OAuth)[/green]")
             elif spec.is_local:
                 # Local deployments show api_base instead of api_key
-                if p.api_base:
+                if resolve_env_refs(p.api_base or ""):
                     console.print(f"{spec.label}: [green]✓ {p.api_base}[/green]")
                 else:
                     console.print(f"{spec.label}: [dim]not set[/dim]")
             else:
-                has_key = bool(p.api_key)
+                has_key = bool(resolve_env_refs(p.api_key or ""))
                 console.print(f"{spec.label}: {'[green]✓[/green]' if has_key else '[dim]not set[/dim]'}")
 
+        if provider_ready:
+            console.print()
+            console.print('Next: [cyan]nanobot agent -m "Hello!"[/cyan]')
+            console.print(
+                "[dim]Status does not call the model or verify network access and credentials.[/dim]"
+            )
+    else:
+        console.print("Agent: [red]✗ configuration file not found[/red]")
+        console.print("Create the provider/model configuration:")
+        _print_model_setup_steps(config_path)
+
 
 # ============================================================================
 # OAuth Login
@@ -2802,11 +2969,13 @@ def _set_oauth_provider_as_main(
 
     config = load_config(resolved_config_path)
     selected_model = (model or "").strip() or _OAUTH_PROVIDER_DEFAULT_MODELS[provider_name]
-    config.agents.defaults.model_preset = None
+    default_preset = config.resolve_default_preset().model_copy(
-    config.agents.defaults.provider = provider_name
+        update={"provider": provider_name, "model": selected_model}
-    config.agents.defaults.model = selected_model
+    )
     if provider_name == "xai_grok" and selected_model == "xai-grok/grok-4.5":
-        config.agents.defaults.context_window_tokens = 500_000
+        default_preset.context_window_tokens = 500_000
+    config.model_presets["default"] = default_preset
+    config.agents.defaults.model_preset = "default"
     save_config(config, resolved_config_path)
 
     saved_path = resolved_config_path or get_config_path()

nanobot/cli/extensions.py

@@ -1,180 +0,0 @@
-"""Typer commands for installing and governing extensions."""
-
-from __future__ import annotations
-
-import asyncio
-from collections.abc import Callable
-from typing import Any
-
-import typer
-from rich.console import Console
-from rich.table import Table
-
-from nanobot.extensions.service import ExtensionService
-
-ServiceFactory = Callable[[], ExtensionService]
-
-
-def create_extensions_app(
-    *,
-    console: Console,
-    service_factory: ServiceFactory = ExtensionService,
-) -> typer.Typer:
-    """Build the extension command group around the transport-neutral service."""
-    app = typer.Typer(help="Install, inspect, and govern native extensions.")
-
-    def service() -> ExtensionService:
-        return service_factory()
-
-    def run(awaitable: Any) -> dict[str, Any]:
-        try:
-            return asyncio.run(awaitable)
-        except (KeyError, RuntimeError, ValueError) as exc:
-            console.print(f"[red]Error: {exc}[/red]")
-            raise typer.Exit(1) from exc
-
-    @app.command("list")
-    def list_extensions() -> None:
-        """List installed extensions and their activation policy."""
-        payload = run(service().status())
-        table = Table(show_header=True, header_style="bold")
-        table.add_column("Extension")
-        table.add_column("State")
-        table.add_column("Trust")
-        table.add_column("Version")
-        for item in payload["extensions"]:
-            state = "active" if item["active"] else ("enabled" if item["enabled"] else "disabled")
-            table.add_row(
-                item["name"],
-                state,
-                "trusted" if item["trusted"] else "untrusted",
-                item["version"],
-            )
-        console.print(table)
-        if not payload["extensions"]:
-            console.print("[dim]No extensions installed.[/dim]")
-        if payload["diagnostics"]:
-            console.print(f"[yellow]{len(payload['diagnostics'])} diagnostic(s)[/yellow]")
-
-    @app.command("inspect")
-    def inspect_extension(extension_id: str = typer.Argument(..., help="Extension ID")) -> None:
-        """Show manifest, dependencies, permissions, and diagnostics."""
-        payload = run(service().status())
-        item = next(
-            (candidate for candidate in payload["extensions"] if candidate["id"] == extension_id),
-            None,
-        )
-        if item is None:
-            console.print(f"[red]Extension not found: {extension_id}[/red]")
-            raise typer.Exit(1)
-        console.print(f"[bold]{item['name']}[/bold] [dim]{item['version']}[/dim]")
-        console.print(item["description"] or "[dim]No description.[/dim]")
-        console.print(
-            f"State: {'active' if item['active'] else 'inactive'}  "
-            f"Trust: {'trusted' if item['trusted'] else 'untrusted'}"
-        )
-        _print_named_rows(console, "Dependencies", item["dependencies"], "kind", "name")
-        _print_permissions(console, item["permissions"], set(item["granted_permissions"]))
-        diagnostics = [
-            diagnostic
-            for diagnostic in payload["diagnostics"]
-            if diagnostic["extension_id"] == extension_id
-        ]
-        if diagnostics:
-            console.print("\n[bold]Diagnostics[/bold]")
-            for diagnostic in diagnostics:
-                console.print(
-                    f"  [yellow]{diagnostic['code']}[/yellow] {diagnostic['message']}"
-                )
-
-    @app.command("install")
-    def install_extension(
-        source: str = typer.Argument(..., help="Git URL or local package path"),
-        kind: str = typer.Option("git", "--kind", help="git or local"),
-        ref: str = typer.Option("", "--ref", help="Git branch, tag, or commit"),
-    ) -> None:
-        """Install an extension without granting trust or permissions."""
-        payload = run(service().install(source, kind=kind, ref=ref, trusted=False))
-        record = payload["record"]
-        console.print(
-            f"[green]Installed {record['id']} {record['version']}[/green] "
-            "[yellow](untrusted)[/yellow]"
-        )
-        console.print(
-            f"Review with [bold]nanobot extensions inspect {record['id']}[/bold], "
-            "then grant permissions and trust it explicitly."
-        )
-
-    def policy_command(name: str, value: bool, label: str, help_text: str) -> None:
-        @app.command(name, help=help_text)
-        def update(extension_id: str = typer.Argument(..., help="Extension ID")) -> None:
-            payload = run(
-                service().set_enabled(extension_id, value)
-                if name in {"enable", "disable"}
-                else service().set_trusted(extension_id, value)
-            )
-            console.print(f"[green]{label}: {payload['record']['id']}[/green]")
-
-    policy_command("enable", True, "Enabled", "Allow an installed extension to activate.")
-    policy_command("disable", False, "Disabled", "Prevent an installed extension from activating.")
-    policy_command("trust", True, "Trusted", "Trust an installed extension's executable code.")
-    policy_command("untrust", False, "Trust revoked", "Revoke trust and stop extension activation.")
-
-    @app.command("permissions")
-    def set_permissions(
-        extension_id: str = typer.Argument(..., help="Extension ID"),
-        permissions: list[str] = typer.Argument(
-            None,
-            help="Exact permissions to grant; omit all to revoke every grant",
-        ),
-    ) -> None:
-        """Replace the extension's granted host permissions."""
-        payload = run(service().set_permissions(extension_id, set(permissions or [])))
-        granted = payload["record"]["granted_permissions"]
-        console.print(
-            f"[green]Updated permissions for {extension_id}:[/green] "
-            + (", ".join(granted) if granted else "none")
-        )
-
-    @app.command("uninstall")
-    def uninstall_extension(
-        extension_id: str = typer.Argument(..., help="Extension ID"),
-        yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
-    ) -> None:
-        """Remove an installed extension."""
-        if not yes and not typer.confirm(f"Uninstall extension '{extension_id}'?"):
-            raise typer.Abort()
-        run(service().uninstall(extension_id))
-        console.print(f"[green]Uninstalled {extension_id}[/green]")
-
-    return app
-
-
-def _print_named_rows(
-    console: Console,
-    title: str,
-    rows: list[dict[str, Any]],
-    category_key: str,
-    name_key: str,
-) -> None:
-    console.print(f"\n[bold]{title}[/bold]")
-    if not rows:
-        console.print("  [dim]None[/dim]")
-        return
-    for row in rows:
-        console.print(f"  {row[category_key]}: {row[name_key]}")
-
-
-def _print_permissions(
-    console: Console,
-    permissions: list[dict[str, str]],
-    granted: set[str],
-) -> None:
-    console.print("\n[bold]Permissions[/bold]")
-    if not permissions:
-        console.print("  [dim]None requested[/dim]")
-        return
-    for permission in permissions:
-        status = "[green]granted[/green]" if permission["name"] in granted else "[yellow]pending[/yellow]"
-        reason = f" — {permission['reason']}" if permission["reason"] else ""
-        console.print(f"  {permission['name']} ({status}){reason}")

nanobot/cli/gateway.py

@@ -29,6 +29,7 @@ from nanobot.webui.build import BuildMode
 
 RuntimeConfigLoader = Callable[[str | None, str | None], Config]
 GatewayRunner = Callable[..., None]
+GatewayConfigValidator = Callable[[Config], str | None]
 GatewayRuntimeFactory = Callable[..., Any]
 GatewayServiceFactory = Callable[[], Any]
 WebUIBundlePreparer = Callable[[Config, BuildMode], None]
@@ -40,6 +41,7 @@ def create_gateway_app(
     log_handler_id: int,
     load_runtime_config: RuntimeConfigLoader,
     run_gateway: GatewayRunner,
+    validate_startup_config: GatewayConfigValidator | None = None,
     runtime_factory: GatewayRuntimeFactory | None = None,
     service_factory: GatewayServiceFactory | None = None,
     prepare_webui_bundle: WebUIBundlePreparer | None = None,
@@ -149,6 +151,8 @@ def create_gateway_app(
             raise typer.Exit(1)
         if background:
             cfg = load_runtime_config(config, workspace)
+            if validate_startup_config is not None:
+                validate_startup_config(cfg)
             if prepare_webui_bundle is not None:
                 prepare_webui_bundle(cfg, interactive_build_mode())
             runtime = runtime_for_instance(workspace=workspace, config=config)
@@ -171,7 +175,18 @@ def create_gateway_app(
 
         configure_logging(verbose)
         cfg = load_runtime_config(config, workspace)
-        run_gateway(cfg, port=port, webui_bundle_mode=interactive_build_mode())
+        unconfigured_provider_error = None
+        if validate_startup_config is not None:
+            unconfigured_provider_error = validate_startup_config(cfg)
+        if unconfigured_provider_error is None:
+            run_gateway(cfg, port=port, webui_bundle_mode=interactive_build_mode())
+        else:
+            run_gateway(
+                cfg,
+                port=port,
+                webui_bundle_mode=interactive_build_mode(),
+                unconfigured_provider_error=unconfigured_provider_error,
+            )
 
     @gateway_app.command("status")
     def gateway_status(
@@ -225,6 +240,8 @@ def create_gateway_app(
     ) -> None:
         """Restart the background gateway."""
         cfg = load_runtime_config(config, workspace)
+        if validate_startup_config is not None:
+            validate_startup_config(cfg)
         if prepare_webui_bundle is not None:
             prepare_webui_bundle(cfg, interactive_build_mode())
         runtime = runtime_for_instance(workspace=workspace, config=config)

nanobot/cli/onboard.py

@@ -755,15 +755,13 @@ def _handle_model_preset_field(
     working_model: BaseModel, field_name: str, field_display: str, current_value: Any
 ) -> None:
     """Handle the 'model_preset' field with a list of existing presets."""
-    preset_names = sorted(_MODEL_PRESET_CACHE)
+    preset_names = sorted(_MODEL_PRESET_CACHE) or ["default"]
-    choices = [_CLEAR_CHOICE] + preset_names
+    choices = preset_names
-    default_choice = str(current_value) if current_value else _CLEAR_CHOICE
+    default_choice = str(current_value) if current_value else "default"
     new_value = _select_with_back(field_display, choices, default=default_choice)
     if new_value is _BACK_PRESSED:
         return
-    if new_value == _CLEAR_CHOICE:
+    if new_value is not None:
-        setattr(working_model, field_name, None)
-    elif new_value is not None:
         setattr(working_model, field_name, new_value)
 
 
@@ -792,8 +790,6 @@ def _handle_fallback_models_field(
     working_model: BaseModel, field_name: str, field_display: str, current_value: Any
 ) -> None:
     """Handle the 'fallback_models' field with preset-aware list management."""
-    from nanobot.config.schema import InlineFallbackConfig
-
     items: list[Any] = list(current_value) if isinstance(current_value, list) else []
     preset_names = sorted(_MODEL_PRESET_CACHE)
 
@@ -802,10 +798,7 @@ def _handle_fallback_models_field(
         console.print(f"[bold]{field_display}[/bold]")
         if items:
             for idx, item in enumerate(items, 1):
-                if isinstance(item, InlineFallbackConfig):
+                console.print(f"  {idx}. {item}")
-                    console.print(f"  {idx}. {item.model} - {item.provider} inline")
-                else:
-                    console.print(f"  {idx}. {item}")
         else:
             console.print("  [dim]empty[/dim]")
         console.print()

nanobot/command/builtin.py

@@ -14,7 +14,7 @@ from typing import Literal
 from nanobot import __version__
 from nanobot.agent.goal_permission import goal_mutation_permission
 from nanobot.bus.events import OutboundMessage
-from nanobot.command.router import CommandContext, CommandRouter
+from nanobot.command.router import CommandContext, CommandRouter, normalize_command_text
 from nanobot.utils.helpers import build_status_content
 from nanobot.utils.restart import set_restart_notice_to_env
 from nanobot.utils.workspace_prompts import initialize_workspace_prompt
@@ -180,6 +180,21 @@ def builtin_command_palette() -> list[dict[str, str | bool]]:
     return [spec.as_dict() for spec in BUILTIN_COMMAND_SPECS]
 
 
+def builtin_command_starts_agent_turn(text: str) -> bool:
+    """Return whether WebUI ingress should expect a normal agent lifecycle."""
+    normalized = normalize_command_text(text)
+    command, separator, args = normalized.partition(" ")
+    spec = next(
+        (item for item in BUILTIN_COMMAND_SPECS if item.command == command.lower()),
+        None,
+    )
+    if spec is None or (separator and not spec.accepts_args):
+        return True
+    if spec.lifecycle == "agent_turn":
+        return True
+    return spec.lifecycle == "agent_turn_with_args" and bool(args.strip())
+
+
 async def cmd_stop(ctx: CommandContext) -> OutboundMessage:
     """Cancel all active tasks and subagents for the session."""
     loop = ctx.loop
@@ -427,12 +442,15 @@ async def cmd_dream(ctx: CommandContext) -> OutboundMessage:
                 return
             prompt, last_cursor = result
             key = dream_session_key()
+            resolve_dream_runtime = getattr(loop, "dream_runtime", None)
+            dream_runtime = resolve_dream_runtime() if callable(resolve_dream_runtime) else None
             resp = await loop.process_direct(
                 prompt,
                 session_key=key,
                 ephemeral=True,
                 tools=store.build_dream_tools(),
                 on_progress=progress,
+                runtime=dream_runtime,
             )
             elapsed = time.monotonic() - t0
             # The real file delta grounds the audit record; clean completion

nanobot/command/router.py

@@ -64,57 +64,16 @@ class CommandRouter:
         self._priority: dict[str, Handler] = {}
         self._exact: dict[str, Handler] = {}
         self._prefix: list[tuple[str, Handler]] = []
-        self._owners: dict[tuple[str, str], str] = {}
 
-    def priority(
+    def priority(self, cmd: str, handler: Handler) -> None:
-        self,
-        cmd: str,
-        handler: Handler,
-        *,
-        owner: str = "nanobot.core",
-    ) -> None:
         self._priority[cmd] = handler
-        self._owners[("priority", cmd)] = owner
 
-    def exact(
+    def exact(self, cmd: str, handler: Handler) -> None:
-        self,
-        cmd: str,
-        handler: Handler,
-        *,
-        owner: str = "nanobot.core",
-    ) -> None:
         self._exact[cmd] = handler
-        self._owners[("exact", cmd)] = owner
 
-    def prefix(
+    def prefix(self, pfx: str, handler: Handler) -> None:
-        self,
-        pfx: str,
-        handler: Handler,
-        *,
-        owner: str = "nanobot.core",
-    ) -> None:
         self._prefix.append((pfx, handler))
         self._prefix.sort(key=lambda p: len(p[0]), reverse=True)
-        self._owners[("prefix", pfx)] = owner
-
-    def owner(self, tier: str, command: str) -> str | None:
-        """Return the extension that owns one command registration."""
-        return self._owners.get((tier, command))
-
-    def unregister_owner(self, owner: str) -> None:
-        """Remove all command tiers registered by one extension."""
-        for (tier, command), registered_owner in list(self._owners.items()):
-            if registered_owner != owner:
-                continue
-            if tier == "priority":
-                self._priority.pop(command, None)
-            elif tier == "exact":
-                self._exact.pop(command, None)
-            else:
-                self._prefix = [
-                    item for item in self._prefix if item[0] != command
-                ]
-            self._owners.pop((tier, command), None)
 
     def is_priority(self, text: str) -> bool:
         return normalize_command_text(text).lower() in self._priority

nanobot/config/__init__.py

@@ -1,5 +1,6 @@
 """Configuration module for nanobot."""
 
+from nanobot.config.errors import ConfigIssue, ConfigLoadError
 from nanobot.config.loader import get_config_path, load_config
 from nanobot.config.paths import (
     get_cli_history_path,
@@ -17,6 +18,8 @@ from nanobot.config.schema import Config
 
 __all__ = [
     "Config",
+    "ConfigIssue",
+    "ConfigLoadError",
     "load_config",
     "get_config_path",
     "get_data_dir",

nanobot/config/errors.py

@@ -0,0 +1,112 @@
+"""User-safe configuration diagnostics."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from pydantic import ValidationError
+
+ConfigErrorKind = Literal[
+    "invalid_json",
+    "invalid_root",
+    "invalid_schema",
+    "missing_env",
+    "io_error",
+]
+ConfigPathPart = str | int
+_SAFE_LOCATION_PART = re.compile(r"[A-Za-z_][A-Za-z0-9_-]{0,63}")
+
+
+def _display_location_part(part: ConfigPathPart) -> str:
+    if isinstance(part, int):
+        return str(part)
+    return part if _SAFE_LOCATION_PART.fullmatch(part) else "<redacted>"
+
+
+@dataclass(frozen=True)
+class ConfigIssue:
+    """One actionable configuration problem."""
+
+    path: tuple[ConfigPathPart, ...]
+    message: str
+
+    @property
+    def location(self) -> str:
+        # Pydantic locations can contain user-controlled mapping keys. Only
+        # render conventional config identifiers so credential-bearing URLs
+        # and other free-form values cannot leak through a redacted error.
+        if not self.path:
+            return "<root>"
+        return ".".join(_display_location_part(part) for part in self.path)
+
+
+class ConfigLoadError(ValueError):
+    """A structured, user-safe configuration loading failure."""
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        kind: ConfigErrorKind,
+        summary: str,
+        issues: tuple[ConfigIssue, ...] = (),
+    ) -> None:
+        self.path = path
+        self.kind = kind
+        self.summary = summary
+        self.issues = issues
+        super().__init__(summary)
+
+    def __str__(self) -> str:
+        lines = [f"Invalid configuration: {self.path}", "", self.summary]
+        for issue in self.issues[:10]:
+            lines.extend(("", f"  {issue.location}", f"    {issue.message}"))
+        remaining = len(self.issues) - 10
+        if remaining > 0:
+            lines.extend(("", f"  … and {remaining} more issue(s)"))
+        return "\n".join(lines)
+
+
+def validation_issues(
+    error: ValidationError,
+) -> tuple[ConfigIssue, ...]:
+    """Convert Pydantic details to actionable messages without exposing input values."""
+    issues: list[ConfigIssue] = []
+    for detail in error.errors(
+        include_url=False,
+        include_context=False,
+        include_input=False,
+    ):
+        location = tuple(detail.get("loc", ()))
+        code = str(detail.get("type") or "")
+        message = _friendly_validation_message(
+            str(detail.get("msg") or "Invalid value"),
+            code,
+        )
+        issues.append(ConfigIssue(path=location, message=message))
+    return tuple(issues)
+
+
+def _friendly_validation_message(message: str, code: str) -> str:
+    if code == "extra_forbidden":
+        return "Unknown setting."
+    if code == "missing":
+        return "This setting is required."
+    if code in {"assertion_error", "value_error"}:
+        # Custom validators control these messages and may interpolate the
+        # rejected value. Keep the field location, but never render that text.
+        return "Value does not satisfy this setting's requirements."
+    if message.startswith("Value error, "):
+        message = message.removeprefix("Value error, ")
+    elif message.startswith("Input should be "):
+        message = "Must be " + message.removeprefix("Input should be ")
+    elif message.startswith("Input should have "):
+        message = "Must have " + message.removeprefix("Input should have ")
+    if message:
+        message = message[:1].upper() + message[1:]
+    if message and message[-1] not in ".!?":
+        message += "."
+    return message or "Invalid value."

nanobot/config/loader.py

@@ -6,15 +6,18 @@ import re
 from pathlib import Path
 from typing import Any
 
-import pydantic
+from loguru import logger
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
+from pydantic_settings import SettingsError
 
+from nanobot.config.errors import ConfigIssue, ConfigLoadError, validation_issues
 from nanobot.config.schema import Config, _resolve_tool_config_refs
 from nanobot.utils.helpers import _write_text_atomic
 
 # Global variable to store current config path (for multi-instance support)
 _current_config_path: Path | None = None
 _schema_refs_ready = False
+_warned_legacy_model_env = False
 
 
 def set_config_path(path: Path) -> None:
@@ -47,16 +50,99 @@ def load_config(config_path: Path | None = None) -> Config:
 
     path = config_path or get_config_path()
 
-    config = Config()
+    if not path.exists():
-    if path.exists():
         try:
-            with open(path, encoding="utf-8") as f:
+            config = Config()
-                data = json.load(f)
+        except SettingsError as exc:
-            data = _migrate_config(data)
+            raise ConfigLoadError(
-            config = Config.model_validate(data)
+                path,
-        except (json.JSONDecodeError, ValueError, pydantic.ValidationError) as e:
+                kind="invalid_schema",
-            raise ValueError(f"Failed to load config from {path}: {e}") from e
+                summary=(
+                    "Environment-based configuration could not be parsed. "
+                    "Check that complex NANOBOT_* values use valid JSON."
+                ),
+            ) from exc
+        except ValidationError as exc:
+            raise ConfigLoadError(
+                path,
+                kind="invalid_schema",
+                summary="Environment-based configuration is invalid.",
+                issues=validation_issues(exc),
+            ) from exc
+        _warn_unsupported_legacy_model_env(path)
+        _apply_ssrf_whitelist(config)
+        return config
 
+    try:
+        with path.open(encoding="utf-8") as handle:
+            data = json.load(handle)
+    except json.JSONDecodeError as exc:
+        raise ConfigLoadError(
+            path,
+            kind="invalid_json",
+            summary=(
+                f"JSON syntax error at line {exc.lineno}, column {exc.colno}: "
+                f"{_sentence(exc.msg)}"
+            ),
+        ) from exc
+    except UnicodeDecodeError as exc:
+        raise ConfigLoadError(
+            path,
+            kind="io_error",
+            summary="The file is not valid UTF-8.",
+        ) from exc
+    except OSError as exc:
+        detail = exc.strerror or type(exc).__name__
+        raise ConfigLoadError(
+            path,
+            kind="io_error",
+            summary=f"Unable to read the file: {_sentence(detail)}",
+        ) from exc
+
+    if not isinstance(data, dict):
+        root_type = type(data).__name__
+        raise ConfigLoadError(
+            path,
+            kind="invalid_root",
+            summary="The top level of config.json must be a JSON object.",
+            issues=(
+                ConfigIssue(
+                    path=(),
+                    message=f"Expected an object, but found {root_type}.",
+                ),
+            ),
+        )
+
+    legacy_model_migration = _legacy_model_migration_kind(data)
+    data, migrated = _migrate_config(data)
+    try:
+        config = Config.model_validate(data)
+    except ValidationError as exc:
+        issues = validation_issues(exc)
+        raise ConfigLoadError(
+            path,
+            kind="invalid_schema",
+            summary=f"Found {len(issues)} invalid setting(s).",
+            issues=issues,
+        ) from exc
+
+    if migrated:
+        _write_text_atomic(path, json.dumps(data, indent=2, ensure_ascii=False))
+        if legacy_model_migration:
+            detail = (
+                "Existing modelPresets.default took precedence; conflicting "
+                "legacy agents.defaults fields were removed."
+                if legacy_model_migration == "conflict"
+                else "Legacy settings were converted to named model presets."
+            )
+            logger.warning(
+                "Migrated legacy model configuration in {}. {} "
+                "Review the rewritten file before downgrading nanobot.",
+                path,
+                detail,
+            )
+
+    _warn_unsupported_legacy_model_env(path)
     _apply_ssrf_whitelist(config)
     return config
 
@@ -116,13 +202,25 @@ def merge_missing_defaults(existing: Any, defaults: Any) -> Any:
 _ENV_REF_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
 
 
-def resolve_config_env_vars(config: Config) -> Config:
+def resolve_config_env_vars(
+    config: Config,
+    *,
+    config_path: Path | None = None,
+) -> Config:
     """Return *config* with ``${VAR}`` env-var references resolved.
 
     Walks in place so fields declared with ``exclude=True`` survive;
     returns the same instance when no references are present.
-    Raises ``ValueError`` if a referenced variable is not set.
+    Raises ``ConfigLoadError`` if a referenced variable is not set.
     """
+    missing = tuple(_missing_env_issues(config))
+    if missing:
+        raise ConfigLoadError(
+            config_path or get_config_path(),
+            kind="missing_env",
+            summary=f"Found {len(missing)} missing environment variable reference(s).",
+            issues=missing,
+        )
     return _resolve_in_place(config)
 
 
@@ -176,6 +274,42 @@ def _resolve_in_place(obj: Any) -> Any:
     return obj
 
 
+def _missing_env_issues(
+    obj: Any,
+    path: tuple[str | int, ...] = (),
+) -> list[ConfigIssue]:
+    if isinstance(obj, str):
+        return [
+            ConfigIssue(
+                path=path,
+                message=f"Environment variable '{name}' is not set.",
+            )
+            for name in dict.fromkeys(_ENV_REF_PATTERN.findall(obj))
+            if name not in os.environ
+        ]
+    if isinstance(obj, BaseModel):
+        issues: list[ConfigIssue] = []
+        for name, field in type(obj).model_fields.items():
+            alias = field.serialization_alias or field.alias or name
+            part = alias if isinstance(alias, str) else name
+            issues.extend(_missing_env_issues(getattr(obj, name), (*path, part)))
+        for name, value in (obj.__pydantic_extra__ or {}).items():
+            issues.extend(_missing_env_issues(value, (*path, name)))
+        return issues
+    if isinstance(obj, dict):
+        issues = []
+        for name, value in obj.items():
+            part = name if isinstance(name, (str, int)) else str(name)
+            issues.extend(_missing_env_issues(value, (*path, part)))
+        return issues
+    if isinstance(obj, list):
+        issues = []
+        for index, value in enumerate(obj):
+            issues.extend(_missing_env_issues(value, (*path, index)))
+        return issues
+    return []
+
+
 def _resolve_env_vars(obj: object) -> object:
     """Recursively resolve ``${VAR}`` patterns in plain strings/dicts/lists."""
     if isinstance(obj, str):
@@ -197,26 +331,290 @@ def _env_replace(match: re.Match[str]) -> str:
     return value
 
 
-def _migrate_config(data: dict) -> dict:
+_LEGACY_DEFAULT_PRESET = {
+    "label": "Default",
+    "model": "anthropic/claude-opus-4-5",
+    "provider": "auto",
+    "maxTokens": 8192,
+    "contextWindowTokens": 200_000,
+    "temperature": 0.1,
+    "reasoningEffort": None,
+}
+_LEGACY_MODEL_FIELD_ALIASES = {
+    "model": ("model",),
+    "provider": ("provider",),
+    "maxTokens": ("maxTokens", "max_tokens"),
+    "contextWindowTokens": ("contextWindowTokens", "context_window_tokens"),
+    "temperature": ("temperature",),
+    "reasoningEffort": ("reasoningEffort", "reasoning_effort"),
+}
+
+
+def _legacy_model_migration_kind(data: dict[str, Any]) -> str | None:
+    """Classify a pending model migration without exposing configured values."""
+    if not _needs_legacy_model_migration(data):
+        return None
+
+    agents = data.get("agents")
+    defaults = agents.get("defaults") if isinstance(agents, dict) else None
+    presets = data.get("modelPresets", data.get("model_presets"))
+    has_legacy_fields = isinstance(defaults, dict) and any(
+        alias in defaults
+        for aliases in _LEGACY_MODEL_FIELD_ALIASES.values()
+        for alias in aliases
+    )
+    if has_legacy_fields and isinstance(presets, dict) and "default" in presets:
+        return "conflict"
+    return "migrated"
+
+
+def _has_unsupported_legacy_model_env() -> bool:
+    for env_name in ("NANOBOT_AGENTS", "NANOBOT_AGENTS__DEFAULTS"):
+        raw = os.environ.get(env_name)
+        if not raw:
+            continue
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        data = (
+            {"agents": parsed}
+            if env_name == "NANOBOT_AGENTS"
+            else {"agents": {"defaults": parsed}}
+        )
+        if isinstance(parsed, dict) and _needs_legacy_model_migration(data):
+            return True
+
+    legacy_suffixes = {
+        alias.upper()
+        for aliases in _LEGACY_MODEL_FIELD_ALIASES.values()
+        for alias in aliases
+    }
+    prefix = "NANOBOT_AGENTS__DEFAULTS__"
+    for env_name in os.environ:
+        upper_name = env_name.upper()
+        if not upper_name.startswith(prefix):
+            continue
+        suffix = upper_name[len(prefix):]
+        if suffix in legacy_suffixes:
+            return True
+    return False
+
+
+def _warn_unsupported_legacy_model_env(config_path: Path) -> None:
+    global _warned_legacy_model_env
+    if _warned_legacy_model_env or not _has_unsupported_legacy_model_env():
+        return
+    logger.warning(
+        "Ignoring unsupported legacy model settings from NANOBOT_AGENTS. "
+        "Move them to modelPresets in {}.",
+        config_path,
+    )
+    _warned_legacy_model_env = True
+
+
+def _pop_alias(mapping: dict[str, Any], aliases: tuple[str, ...]) -> tuple[bool, Any]:
+    found = False
+    value: Any = None
+    for alias in aliases:
+        if alias in mapping:
+            if not found:
+                value = mapping[alias]
+                found = True
+            mapping.pop(alias, None)
+    return found, value
+
+
+def _preset_value(preset: dict[str, Any], camel: str, snake: str) -> Any:
+    return preset.get(camel, preset.get(snake))
+
+
+def _first_not_none(*values: Any) -> Any:
+    return next((value for value in values if value is not None), None)
+
+
+def _unique_legacy_fallback_name(presets: dict[str, Any], model: Any) -> str:
+    tail = str(model or "fallback").rsplit("/", 1)[-1].strip().lower()
+    base = re.sub(r"[^a-z0-9]+", "-", tail).strip("-") or "fallback"
+    name = base
+    suffix = 2
+    while name in presets:
+        name = f"{base}-{suffix}"
+        suffix += 1
+    return name
+
+
+def _needs_legacy_model_migration(data: dict[str, Any]) -> bool:
+    agents = data.get("agents")
+    defaults = agents.get("defaults") if isinstance(agents, dict) else None
+    if isinstance(defaults, dict):
+        if any(
+            alias in defaults
+            for aliases in _LEGACY_MODEL_FIELD_ALIASES.values()
+            for alias in aliases
+        ):
+            return True
+        if "model_preset" in defaults:
+            return True
+        active = defaults.get("modelPreset")
+        if "modelPreset" in defaults and (
+            not isinstance(active, str) or not active.strip()
+        ):
+            return True
+        fallbacks = defaults.get(
+            "fallbackModels",
+            defaults.get("fallback_models"),
+        )
+        if isinstance(fallbacks, list) and any(
+            isinstance(fallback, dict) for fallback in fallbacks
+        ):
+            return True
+
+    presets = data.get("modelPresets", data.get("model_presets"))
+    return isinstance(presets, dict) and "default" not in presets
+
+
+def _migrate_legacy_model_config(data: dict[str, Any]) -> bool:
+    """Move concrete model settings into named presets before schema validation."""
+    if not _needs_legacy_model_migration(data):
+        return False
+
+    changed = False
+    agents = data.setdefault("agents", {})
+    if not isinstance(agents, dict):
+        return False
+    defaults = agents.setdefault("defaults", {})
+    if not isinstance(defaults, dict):
+        return False
+
+    presets_key = "modelPresets" if "modelPresets" in data else "model_presets"
+    if presets_key not in data:
+        presets_key = "modelPresets"
+        data[presets_key] = {}
+        changed = True
+    presets = data[presets_key]
+    if not isinstance(presets, dict):
+        return changed
+
+    migrated_default = dict(_LEGACY_DEFAULT_PRESET)
+    legacy_values_found = False
+    for destination, aliases in _LEGACY_MODEL_FIELD_ALIASES.items():
+        found, value = _pop_alias(defaults, aliases)
+        if found:
+            migrated_default[destination] = value
+            legacy_values_found = True
+            changed = True
+
+    if "default" not in presets:
+        presets["default"] = migrated_default
+        changed = True
+
+    had_canonical_active = "modelPreset" in defaults
+    active_found, active = _pop_alias(defaults, ("modelPreset", "model_preset"))
+    normalized_active = active.strip() if isinstance(active, str) else ""
+    normalized_active = normalized_active or "default"
+    if not active_found or active != normalized_active or not had_canonical_active:
+        changed = True
+    defaults["modelPreset"] = normalized_active
+
+    fallback_key = (
+        "fallbackModels"
+        if "fallbackModels" in defaults
+        else "fallback_models"
+        if "fallback_models" in defaults
+        else None
+    )
+    if fallback_key is not None and isinstance(defaults[fallback_key], list):
+        primary = presets.get(normalized_active)
+        if not isinstance(primary, dict):
+            primary = presets["default"]
+        migrated_fallbacks: list[Any] = []
+        for fallback in defaults[fallback_key]:
+            if isinstance(fallback, str):
+                migrated_fallbacks.append(fallback)
+                continue
+            if not isinstance(fallback, dict):
+                migrated_fallbacks.append(fallback)
+                continue
+            name = _unique_legacy_fallback_name(presets, fallback.get("model"))
+            presets[name] = {
+                "label": str(fallback.get("model") or name),
+                "model": fallback.get("model"),
+                "provider": fallback.get("provider"),
+                "maxTokens": _first_not_none(
+                    _preset_value(fallback, "maxTokens", "max_tokens"),
+                    _preset_value(primary, "maxTokens", "max_tokens"),
+                    _LEGACY_DEFAULT_PRESET["maxTokens"],
+                ),
+                "contextWindowTokens": _first_not_none(
+                    _preset_value(fallback, "contextWindowTokens", "context_window_tokens"),
+                    _preset_value(primary, "contextWindowTokens", "context_window_tokens"),
+                    _LEGACY_DEFAULT_PRESET["contextWindowTokens"],
+                ),
+                "temperature": (
+                    fallback["temperature"]
+                    if fallback.get("temperature") is not None
+                    else primary.get("temperature", _LEGACY_DEFAULT_PRESET["temperature"])
+                ),
+                "reasoningEffort": _preset_value(
+                    fallback,
+                    "reasoningEffort",
+                    "reasoning_effort",
+                ),
+            }
+            migrated_fallbacks.append(name)
+            changed = True
+        if fallback_key != "fallbackModels":
+            defaults.pop(fallback_key, None)
+            changed = True
+        defaults["fallbackModels"] = migrated_fallbacks
+
+    return changed or legacy_values_found
+
+
+def _migrate_config(data: dict) -> tuple[dict, bool]:
     """Migrate old config formats to current."""
+    changed = _migrate_legacy_model_config(data)
     # Move tools.exec.restrictToWorkspace → tools.restrictToWorkspace
     tools = data.get("tools", {})
+    if not isinstance(tools, dict):
+        return data, changed
     exec_cfg = tools.get("exec", {})
-    if "restrictToWorkspace" in exec_cfg and "restrictToWorkspace" not in tools:
+    if (
+        isinstance(exec_cfg, dict)
+        and "restrictToWorkspace" in exec_cfg
+        and "restrictToWorkspace" not in tools
+    ):
         tools["restrictToWorkspace"] = exec_cfg.pop("restrictToWorkspace")
+        changed = True
 
     # Move tools.myEnabled / tools.mySet → tools.my.{enable, allowSet}.
     # The old flat keys shipped in the initial MyTool landing; wrapping them in a
     # sub-config keeps `web` / `exec` / `my` symmetric and gives room to grow.
     if "myEnabled" in tools or "mySet" in tools:
-        my_cfg = tools.setdefault("my", {})
+        my_cfg = tools.get("my")
+        if my_cfg is None:
+            my_cfg = {}
+            tools["my"] = my_cfg
+            changed = True
+        if not isinstance(my_cfg, dict):
+            return data, changed
         if "myEnabled" in tools and "enable" not in my_cfg:
             my_cfg["enable"] = tools.pop("myEnabled")
+            changed = True
         else:
-            tools.pop("myEnabled", None)
+            changed = tools.pop("myEnabled", None) is not None or changed
         if "mySet" in tools and "allowSet" not in my_cfg:
             my_cfg["allowSet"] = tools.pop("mySet")
+            changed = True
         else:
-            tools.pop("mySet", None)
+            changed = tools.pop("mySet", None) is not None or changed
 
-    return data
+    return data, changed
+
+
+def _sentence(message: str) -> str:
+    message = message.strip()
+    if message and message[-1] not in ".!?":
+        message += "."
+    return message

nanobot/config/schema.py

@@ -32,7 +32,7 @@ class ChannelsConfig(Base):
     send_progress: bool = True  # stream agent's text progress to the channel
     send_tool_hints: bool = True  # 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
+    extract_document_text: bool = True  # Deprecated and ignored; documents are read on demand
     send_max_retries: int = Field(default=3, ge=0, le=10)  # Max delivery attempts (initial send included)
     transcription_provider: str = "groq"  # Deprecated: use top-level transcription.provider
     transcription_language: str | None = Field(default=None, pattern=r"^[a-z]{2,3}$")  # Deprecated: use top-level transcription.language
@@ -63,7 +63,7 @@ class DreamConfig(Base):
     model_override: str | None = Field(
         default=None,
         validation_alias=AliasChoices("modelOverride", "model", "model_override"),
-    )  # Override model for Dream sessions (pending implementation)
+    )  # Model preset name for Dream sessions
 
     def build_schedule(self, timezone: str) -> CronSchedule:
         """Build the runtime schedule, preferring the legacy cron override if present."""
@@ -79,20 +79,6 @@ class DreamConfig(Base):
         return f"every {hours}h"
 
 
-class InlineFallbackConfig(Base):
-    """One inline fallback model configuration."""
-
-    model: str
-    provider: str
-    max_tokens: int | None = None
-    context_window_tokens: int | None = None
-    temperature: float | None = None
-    reasoning_effort: str | None = None
-
-
-FallbackCandidate = str | InlineFallbackConfig
-
-
 class ModelPresetConfig(Base):
     """A named set of model + generation parameters for quick switching."""
 
@@ -103,6 +89,7 @@ class ModelPresetConfig(Base):
     context_window_tokens: int = 200_000
     temperature: float = 0.1
     reasoning_effort: str | None = None
+    supports_image_input: bool | None = None
 
     def to_generation_settings(self) -> Any:
         from nanobot.providers.base import GenerationSettings
@@ -117,16 +104,9 @@ class AgentDefaults(Base):
     """Default agent configuration."""
 
     workspace: str = "~/.nanobot/workspace"
-    model_preset: str | None = None  # Active preset name — takes precedence over fields below
+    model_preset: str = "default"
-    model: str = "anthropic/claude-opus-4-5"
-    provider: str = (
-        "auto"  # Provider name (e.g. "anthropic", "openrouter") or "auto" for auto-detection
-    )
-    max_tokens: int = 8192
-    context_window_tokens: int = 200_000
     context_block_limit: int | None = None
-    temperature: float = 0.1
+    fallback_models: list[str] = Field(default_factory=list)
-    fallback_models: list[FallbackCandidate] = Field(default_factory=list)
     max_tool_iterations: int = 200
     max_concurrent_subagents: int = Field(default=1, ge=1)
     fail_on_tool_error: bool = True
@@ -139,7 +119,6 @@ class AgentDefaults(Base):
         validation_alias=AliasChoices("toolHintMaxLength"),
         serialization_alias="toolHintMaxLength",
     )  # Max characters for tool hint display (e.g. "$ cd …/project && npm test")
-    reasoning_effort: str | None = None  # low / medium / high / adaptive / none — LLM thinking effort; None preserves the provider default
     timezone: str = "UTC"  # IANA timezone, e.g. "Asia/Shanghai", "America/New_York"
     bot_name: str = "nanobot"  # Display name shown in CLI prompts (e.g. "{name} is thinking...")
     bot_icon: str = "🐈"  # Short icon (emoji or text) shown next to the bot name in CLI; "" to omit
@@ -403,17 +382,11 @@ class ToolsConfig(Base):
             "webuiAllowRemotePackageInstall",
             "webui_allow_remote_package_install",
         ),
-    )  # allow non-local WebUI clients to install optional support and extension packages
+    )  # allow non-local WebUI clients to install optional Python packages
     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)
 
 
-class ExtensionsConfig(Base):
-    """Global switch for external extension activation."""
-
-    enabled: bool = True
-
-
 class Config(BaseSettings):
     """Root configuration for nanobot."""
 
@@ -424,9 +397,13 @@ class Config(BaseSettings):
     api: ApiConfig = Field(default_factory=ApiConfig)
     gateway: GatewayConfig = Field(default_factory=GatewayConfig)
     tools: ToolsConfig = Field(default_factory=ToolsConfig)
-    extensions: ExtensionsConfig = Field(default_factory=ExtensionsConfig)
     model_presets: dict[str, ModelPresetConfig] = Field(
-        default_factory=dict,
+        default_factory=lambda: {
+            "default": ModelPresetConfig(
+                label="Default",
+                model="anthropic/claude-opus-4-5",
+            )
+        },
         validation_alias=AliasChoices("modelPresets", "model_presets"),
         serialization_alias="modelPresets",
     )
@@ -438,30 +415,26 @@ class Config(BaseSettings):
 
     @model_validator(mode="after")
     def _validate_model_preset(self) -> "Config":
-        if "default" in self.model_presets:
+        if "default" not in self.model_presets:
-            raise ValueError("model_preset name 'default' is reserved for agents.defaults")
+            raise ValueError("model_presets must define a 'default' preset")
         name = self.agents.defaults.model_preset
-        if name and name != "default" and name not in self.model_presets:
+        if name not in self.model_presets:
             raise ValueError(f"model_preset {name!r} not found in model_presets")
+        dream_name = self.agents.defaults.dream.model_override
+        if dream_name and dream_name not in self.model_presets:
+            raise ValueError(f"Dream model preset {dream_name!r} not found in model_presets")
         for fallback in self.agents.defaults.fallback_models:
-            if isinstance(fallback, str) and fallback not in self.model_presets:
+            if fallback not in self.model_presets:
                 raise ValueError(f"fallback_models entry {fallback!r} not found in model_presets")
         return self
 
     def resolve_default_preset(self) -> ModelPresetConfig:
-        """Return the implicit `default` preset from agents.defaults fields."""
+        """Return the concrete ``default`` model preset."""
-        d = self.agents.defaults
+        return self.model_presets["default"]
-        return ModelPresetConfig(
-            model=d.model, provider=d.provider, max_tokens=d.max_tokens,
-            context_window_tokens=d.context_window_tokens,
-            temperature=d.temperature, reasoning_effort=d.reasoning_effort,
-        )
 
     def resolve_preset(self, name: str | None = None) -> ModelPresetConfig:
-        """Return effective model params from a named preset or the implicit default."""
+        """Return effective model params from a named preset."""
-        name = self.agents.defaults.model_preset if name is None else name
+        name = self.agents.defaults.model_preset if name is None else (name or "default")
-        if not name or name == "default":
-            return self.resolve_default_preset()
         if name not in self.model_presets:
             raise KeyError(f"model_preset {name!r} not found in model_presets")
         return self.model_presets[name]

nanobot/extensions/__init__.py

@@ -1,19 +0,0 @@
-"""Stable author-facing API for native nanobot extensions."""
-
-from nanobot.extensions.manifest import (
-    EXTENSION_API_VERSION,
-    DependencyKind,
-    ExtensionDependency,
-    ExtensionManifest,
-    ExtensionPermission,
-)
-from nanobot.extensions.runtime import PythonExtensionApi
-
-__all__ = [
-    "EXTENSION_API_VERSION",
-    "DependencyKind",
-    "ExtensionDependency",
-    "ExtensionManifest",
-    "ExtensionPermission",
-    "PythonExtensionApi",
-]

nanobot/extensions/catalog.py

@@ -1,64 +0,0 @@
-"""Discover installed extensions and resolve one activation snapshot."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from nanobot.extensions.preflight import evaluate_dependencies
-from nanobot.extensions.registry import (
-    ExtensionCandidate,
-    ExtensionDiagnostic,
-    ExtensionRegistry,
-    ExtensionSnapshot,
-)
-from nanobot.extensions.store import ExtensionStore
-
-if TYPE_CHECKING:
-    from nanobot.config.schema import Config
-
-
-@dataclass(frozen=True, slots=True)
-class ExtensionCatalog:
-    """Discovered candidates plus the active, policy-resolved snapshot."""
-
-    candidates: tuple[ExtensionCandidate, ...]
-    snapshot: ExtensionSnapshot
-    diagnostics: tuple[ExtensionDiagnostic, ...]
-
-
-def build_extension_catalog(
-    config: Config,
-    *,
-    user_root: Path | None = None,
-) -> ExtensionCatalog:
-    """Build the authoritative extension view without executing package code."""
-    if not config.extensions.enabled:
-        return ExtensionCatalog((), ExtensionSnapshot((), ()), ())
-
-    discovery = ExtensionStore(user_root).discover()
-    candidates, dependency_diagnostics = evaluate_dependencies(
-        discovery.candidates
-    )
-    registry = ExtensionRegistry()
-    registry_diagnostics: list[ExtensionDiagnostic] = []
-    for candidate in candidates:
-        try:
-            registry.register(candidate)
-        except ValueError as exc:
-            registry_diagnostics.append(
-                ExtensionDiagnostic(
-                    code="duplicate_installation",
-                    extension_id=candidate.manifest.id,
-                    message=str(exc),
-                )
-            )
-    snapshot = registry.snapshot()
-    diagnostics = (
-        discovery.diagnostics
-        + dependency_diagnostics
-        + tuple(registry_diagnostics)
-        + snapshot.diagnostics
-    )
-    return ExtensionCatalog(candidates, snapshot, diagnostics)

nanobot/extensions/codec.py

@@ -1,56 +0,0 @@
-"""JSON persistence for extension manifests."""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import Any
-
-from pydantic import ValidationError
-
-from nanobot.extensions.manifest import ExtensionManifest
-
-MANIFEST_FILENAME = "nanobot.extension.json"
-
-
-class ManifestFormatError(ValueError):
-    """Raised when a manifest cannot be decoded unambiguously."""
-
-
-def load_manifest(path: Path) -> ExtensionManifest:
-    """Read and validate one canonical JSON manifest."""
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
-        raise ManifestFormatError(f"cannot read extension manifest {path}: {exc}") from exc
-    return manifest_from_mapping(data)
-
-
-def dump_manifest(manifest: ExtensionManifest, path: Path) -> None:
-    """Write one canonical JSON manifest."""
-    path.write_text(
-        json.dumps(manifest_to_mapping(manifest), ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
-
-
-def manifest_from_mapping(data: object) -> ExtensionManifest:
-    """Decode a manifest and reject unknown or invalid fields."""
-    try:
-        return ExtensionManifest.model_validate(data)
-    except ValidationError as exc:
-        unknown = sorted(
-            ".".join(str(part) for part in error["loc"])
-            for error in exc.errors()
-            if error["type"] == "extra_forbidden"
-        )
-        if unknown:
-            raise ManifestFormatError(
-                f"extension manifest has unknown fields: {', '.join(unknown)}"
-            ) from exc
-        raise ManifestFormatError(f"invalid extension manifest: {exc}") from exc
-
-
-def manifest_to_mapping(manifest: ExtensionManifest) -> dict[str, Any]:
-    """Return the canonical JSON representation."""
-    return manifest.model_dump(mode="json", by_alias=True)

nanobot/extensions/discovery.py

@@ -1,71 +0,0 @@
-"""Side-effect-free discovery of extension manifests on disk."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-
-from nanobot.extensions.codec import MANIFEST_FILENAME, load_manifest
-from nanobot.extensions.registry import (
-    ExtensionCandidate,
-    ExtensionDiagnostic,
-)
-
-
-@dataclass(frozen=True, slots=True)
-class ExtensionDiscoveryResult:
-    candidates: tuple[ExtensionCandidate, ...] = ()
-    diagnostics: tuple[ExtensionDiagnostic, ...] = ()
-
-
-def discover_manifest_root(
-    root: Path,
-) -> ExtensionDiscoveryResult:
-    """Discover direct children containing ``nanobot.extension.json``."""
-    if not root.exists():
-        return ExtensionDiscoveryResult()
-    if not root.is_dir():
-        return ExtensionDiscoveryResult(
-            diagnostics=(
-                ExtensionDiagnostic(
-                    code="invalid_extension_root",
-                    extension_id="",
-                    message=f"extension root is not a directory: {root}",
-                ),
-            )
-        )
-
-    manifests = []
-    direct_manifest = root / MANIFEST_FILENAME
-    if direct_manifest.is_file():
-        manifests.append(direct_manifest)
-    manifests.extend(
-        sorted(
-            path / MANIFEST_FILENAME
-            for path in root.iterdir()
-            if not path.name.startswith(".")
-            and path.is_dir()
-            and (path / MANIFEST_FILENAME).is_file()
-        )
-    )
-
-    candidates: list[ExtensionCandidate] = []
-    diagnostics: list[ExtensionDiagnostic] = []
-    for path in manifests:
-        try:
-            manifest = load_manifest(path)
-            candidates.append(
-                ExtensionCandidate(
-                    manifest=manifest,
-                    location=path.parent.resolve(),
-                )
-            )
-        except Exception as exc:
-            diagnostics.append(
-                ExtensionDiagnostic(
-                    code="invalid_manifest",
-                    extension_id=path.parent.name,
-                    message=str(exc),
-                )
-            )
-    return ExtensionDiscoveryResult(tuple(candidates), tuple(diagnostics))

nanobot/extensions/host.py

@@ -1,89 +0,0 @@
-"""Agent-side lifecycle for first-class extensions."""
-
-from __future__ import annotations
-
-import asyncio
-from collections.abc import Callable
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from loguru import logger
-
-from nanobot.extensions.catalog import ExtensionCatalog, build_extension_catalog
-from nanobot.extensions.registry import ExtensionDiagnostic
-from nanobot.extensions.runtime import ActivationResult, ExtensionRuntimeManager
-
-if TYPE_CHECKING:
-    from nanobot.agent.loop import AgentLoop
-    from nanobot.config.schema import Config
-
-
-@dataclass(frozen=True, slots=True)
-class ExtensionHostSnapshot:
-    """Current discovery and activation result."""
-
-    catalog: ExtensionCatalog
-    activation: ActivationResult
-
-    @property
-    def diagnostics(self) -> tuple[ExtensionDiagnostic, ...]:
-        return self.catalog.diagnostics + self.activation.diagnostics
-
-
-class ExtensionHost:
-    """Reload external extensions without coupling their lifecycle to AgentLoop."""
-
-    def __init__(
-        self,
-        agent: AgentLoop,
-        config_loader: Callable[[], Config],
-        *,
-        user_root: Path | None = None,
-    ) -> None:
-        self._agent = agent
-        self._config_loader = config_loader
-        self._user_root = user_root
-        self._manager: ExtensionRuntimeManager | None = None
-        self._snapshot: ExtensionHostSnapshot | None = None
-        self._lock = asyncio.Lock()
-
-    @property
-    def snapshot(self) -> ExtensionHostSnapshot | None:
-        return self._snapshot
-
-    async def reload(self) -> ExtensionHostSnapshot:
-        async with self._lock:
-            await self._close_manager()
-            self._snapshot = None
-            config = self._config_loader()
-            catalog = build_extension_catalog(
-                config,
-                user_root=self._user_root,
-            )
-            manager = ExtensionRuntimeManager(
-                tools=self._agent.tools,
-                commands=self._agent.commands,
-                hook_factories=self._agent._hook_factories,
-            )
-            activation = await manager.activate(catalog.snapshot)
-            self._manager = manager
-            self._snapshot = ExtensionHostSnapshot(catalog, activation)
-            for diagnostic in self._snapshot.diagnostics:
-                logger.warning(
-                    "Extension {} [{}]: {}",
-                    diagnostic.extension_id,
-                    diagnostic.code,
-                    diagnostic.message,
-                )
-            return self._snapshot
-
-    async def close(self) -> None:
-        async with self._lock:
-            await self._close_manager()
-            self._snapshot = None
-
-    async def _close_manager(self) -> None:
-        if self._manager is not None:
-            await self._manager.close()
-            self._manager = None

nanobot/extensions/manifest.py

@@ -1,126 +0,0 @@
-"""Strict schema for native nanobot extension packages."""
-
-from __future__ import annotations
-
-import re
-from enum import Enum
-from pathlib import Path
-from typing import Literal, Self
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
-
-EXTENSION_API_VERSION = 1
-
-_IDENTIFIER = re.compile(r"[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?")
-_PERMISSION = re.compile(r"[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*")
-
-
-class DependencyKind(str, Enum):
-    """Kinds of prerequisites resolved before activation."""
-
-    PYTHON = "python"
-    EXECUTABLE = "executable"
-    ENVIRONMENT = "environment"
-
-
-class _ManifestModel(BaseModel):
-    model_config = ConfigDict(extra="forbid", frozen=True, populate_by_name=True)
-
-
-class ExtensionDependency(_ManifestModel):
-    """One activation prerequisite declared by an extension."""
-
-    kind: DependencyKind
-    name: str
-    specifier: str = ""
-    optional: bool = False
-
-    @field_validator("name")
-    @classmethod
-    def validate_name(cls, value: str) -> str:
-        return _require_text(value, "extension dependency name")
-
-
-class ExtensionPermission(_ManifestModel):
-    """A privileged host capability requested by an extension."""
-
-    name: str
-    reason: str = ""
-
-    @field_validator("name")
-    @classmethod
-    def validate_name(cls, value: str) -> str:
-        if _PERMISSION.fullmatch(value) is None:
-            raise ValueError(
-                "extension permission must be a lowercase namespaced identifier"
-            )
-        return value
-
-
-class ExtensionManifest(_ManifestModel):
-    """Identity, prerequisites, and consent declarations for one extension."""
-
-    id: str
-    name: str
-    version: str
-    entry: str = "extension:register"
-    description: str = ""
-    dependencies: tuple[ExtensionDependency, ...] = ()
-    permissions: tuple[ExtensionPermission, ...] = ()
-    api_version: Literal[EXTENSION_API_VERSION] = Field(
-        default=EXTENSION_API_VERSION,
-        alias="apiVersion",
-    )
-    homepage: str = ""
-    license: str = ""
-
-    @field_validator("id")
-    @classmethod
-    def validate_id(cls, value: str) -> str:
-        return _require_identifier(value, "extension id")
-
-    @field_validator("name", "version")
-    @classmethod
-    def validate_required_text(cls, value: str, info) -> str:
-        return _require_text(value, f"extension {info.field_name}")
-
-    @field_validator("entry")
-    @classmethod
-    def validate_entry(cls, value: str) -> str:
-        value = _require_text(value, "extension entry")
-        module_name = value.partition(":")[0]
-        if Path(module_name).is_absolute() or ".." in Path(module_name).parts:
-            raise ValueError("extension entry cannot escape the package root")
-        return value
-
-    @model_validator(mode="after")
-    def reject_duplicates(self) -> Self:
-        dependencies = [(item.kind, item.name) for item in self.dependencies]
-        if len(set(dependencies)) != len(dependencies):
-            raise ValueError("extension manifest contains duplicate dependencies")
-        permissions = [item.name for item in self.permissions]
-        if len(set(permissions)) != len(permissions):
-            raise ValueError("extension manifest contains duplicate permissions")
-        return self
-
-
-def _require_text(value: str, label: str) -> str:
-    if not value.strip():
-        raise ValueError(f"{label} must be a non-empty string")
-    return value
-
-
-def _require_identifier(value: str, label: str) -> str:
-    value = _require_text(value, label)
-    if _IDENTIFIER.fullmatch(value) is None:
-        raise ValueError(
-            f"{label} must use lowercase letters, digits, dots, underscores, or hyphens"
-        )
-    return value
-
-
-def validate_extension_id(value: object) -> str:
-    """Validate and return one portable extension identifier."""
-    if not isinstance(value, str):
-        raise ValueError("extension id must be a string")
-    return _require_identifier(value, "extension id")

nanobot/extensions/preflight.py

@@ -1,59 +0,0 @@
-"""Activation preflight for extension runtime prerequisites."""
-
-from __future__ import annotations
-
-import importlib.metadata
-import os
-import shutil
-from dataclasses import replace
-
-from nanobot.extensions.manifest import DependencyKind, ExtensionDependency
-from nanobot.extensions.registry import ExtensionCandidate, ExtensionDiagnostic
-from nanobot.extensions.versioning import dependency_version_failure
-
-
-def evaluate_dependencies(
-    candidates: tuple[ExtensionCandidate, ...],
-) -> tuple[tuple[ExtensionCandidate, ...], tuple[ExtensionDiagnostic, ...]]:
-    """Disable candidates with missing required software and explain why."""
-    checked: list[ExtensionCandidate] = []
-    diagnostics: list[ExtensionDiagnostic] = []
-    for candidate in candidates:
-        failures = [
-            message
-            for dependency in candidate.manifest.dependencies
-            if not dependency.optional
-            if (message := _dependency_failure(dependency))
-        ]
-        if failures:
-            candidate = replace(candidate, enabled=False)
-            diagnostics.extend(
-                ExtensionDiagnostic(
-                    code="dependency_missing",
-                    extension_id=candidate.manifest.id,
-                    message=message,
-                )
-                for message in failures
-            )
-        checked.append(candidate)
-    return tuple(checked), tuple(diagnostics)
-
-
-def _dependency_failure(
-    dependency: ExtensionDependency,
-) -> str:
-    if dependency.kind is DependencyKind.EXECUTABLE:
-        if shutil.which(dependency.name) is None:
-            return f"Required executable is not installed: {dependency.name}"
-        return ""
-    if dependency.kind is DependencyKind.ENVIRONMENT:
-        if not os.getenv(dependency.name):
-            return f"Required environment variable is not set: {dependency.name}"
-        return ""
-    if dependency.kind is DependencyKind.PYTHON:
-        try:
-            version = importlib.metadata.version(dependency.name)
-        except importlib.metadata.PackageNotFoundError:
-            return f"Required Python package is not installed: {dependency.name}"
-        return dependency_version_failure(dependency, version, "Python package")
-    return f"Unsupported dependency kind: {dependency.kind.value}"

nanobot/extensions/registry.py

@@ -1,82 +0,0 @@
-"""Deterministic extension activation planning."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-
-from nanobot.extensions.manifest import ExtensionManifest
-
-
-@dataclass(frozen=True, slots=True)
-class ExtensionCandidate:
-    """One discovered extension package and its activation state."""
-
-    manifest: ExtensionManifest
-    location: Path | None = None
-    enabled: bool = True
-    trusted: bool = False
-    integrity_valid: bool = True
-    granted_permissions: frozenset[str] = frozenset()
-
-
-@dataclass(frozen=True, slots=True)
-class ExtensionDiagnostic:
-    """A non-fatal discovery or activation problem."""
-
-    code: str
-    extension_id: str
-    message: str
-    severity: str = "warning"
-
-
-@dataclass(frozen=True, slots=True)
-class ExtensionSnapshot:
-    """Immutable activation plan consumed by the runtime."""
-
-    extensions: tuple[ExtensionCandidate, ...]
-    diagnostics: tuple[ExtensionDiagnostic, ...]
-
-
-class ExtensionRegistry:
-    """Select trusted candidates and report missing permission grants."""
-
-    def __init__(self) -> None:
-        self._candidates: dict[str, ExtensionCandidate] = {}
-
-    def register(self, candidate: ExtensionCandidate) -> None:
-        extension_id = candidate.manifest.id
-        if extension_id in self._candidates:
-            raise ValueError(f"extension '{extension_id}' is already installed")
-        self._candidates[extension_id] = candidate
-
-    def snapshot(self) -> ExtensionSnapshot:
-        active: list[ExtensionCandidate] = []
-        diagnostics: list[ExtensionDiagnostic] = []
-        for candidate in sorted(
-            self._candidates.values(),
-            key=lambda item: item.manifest.id,
-        ):
-            requested = {
-                permission.name for permission in candidate.manifest.permissions
-            }
-            missing = sorted(requested - candidate.granted_permissions)
-            if (
-                candidate.enabled
-                and candidate.integrity_valid
-                and candidate.trusted
-                and not missing
-            ):
-                active.append(candidate)
-            elif candidate.enabled and candidate.trusted and missing:
-                diagnostics.append(
-                    ExtensionDiagnostic(
-                        code="permission_required",
-                        extension_id=candidate.manifest.id,
-                        message=(
-                            "Grant required extension permissions: "
-                            + ", ".join(missing)
-                        ),
-                    )
-                )
-        return ExtensionSnapshot(tuple(active), tuple(diagnostics))

nanobot/extensions/runtime.py

@@ -1,218 +0,0 @@
-"""Transactional activation at nanobot's tool, command, and hook seams."""
-
-from __future__ import annotations
-
-import importlib
-import shutil
-import sys
-from dataclasses import dataclass
-from importlib.machinery import ModuleSpec
-from pathlib import Path
-from types import ModuleType
-from typing import Any
-
-from nanobot.agent.hook import AgentHook, AgentTurnHookFactory
-from nanobot.agent.tools.base import Tool
-from nanobot.agent.tools.registry import ToolRegistry
-from nanobot.command.router import CommandRouter, Handler
-from nanobot.extensions.registry import (
-    ExtensionCandidate,
-    ExtensionDiagnostic,
-    ExtensionSnapshot,
-)
-
-
-@dataclass(frozen=True, slots=True)
-class ActivationResult:
-    """Immutable activation outcome consumed by the agent assembly layer."""
-
-    extensions: tuple[ExtensionCandidate, ...]
-    hook_factories: tuple[AgentTurnHookFactory, ...]
-    diagnostics: tuple[ExtensionDiagnostic, ...]
-
-
-class PythonExtensionApi:
-    """Small native API; extensions register into existing nanobot interfaces."""
-
-    def __init__(
-        self,
-        *,
-        owner: str,
-        tools: ToolRegistry,
-        commands: CommandRouter,
-        hook_factories: list[AgentTurnHookFactory],
-    ) -> None:
-        self.owner = owner
-        self._tools = tools
-        self._commands = commands
-        self._hook_factories = hook_factories
-
-    def register_tool(self, tool: Tool) -> None:
-        if not self._tools.register_if_absent(tool, owner=self.owner):
-            existing = self._tools.owner(tool.name) or "unknown"
-            raise ValueError(
-                f"tool '{tool.name}' is already registered by '{existing}'"
-            )
-
-    def register_command(
-        self,
-        command: str,
-        handler: Handler,
-        *,
-        prefix: bool = False,
-    ) -> None:
-        command = f"/{command.lstrip('/')}"
-        if prefix:
-            command = f"{command} "
-        register = self._commands.prefix if prefix else self._commands.exact
-        tier = "prefix" if prefix else "exact"
-        if existing := self._commands.owner(tier, command):
-            raise ValueError(
-                f"command '{command}' is already registered by '{existing}'"
-            )
-        register(command, handler, owner=self.owner)
-
-    def register_hook_factory(self, factory: AgentTurnHookFactory) -> None:
-        self._hook_factories.append(_owned_hook_factory(factory, self.owner))
-
-
-class ExtensionRuntimeManager:
-    """Activate a resolved snapshot and roll back failed registrations."""
-
-    def __init__(
-        self,
-        *,
-        tools: ToolRegistry,
-        commands: CommandRouter,
-        hook_factories: list[AgentTurnHookFactory] | None = None,
-    ) -> None:
-        self._tools = tools
-        self._commands = commands
-        self._active: list[ExtensionCandidate] = []
-        self._hook_factories = hook_factories if hook_factories is not None else []
-
-    async def activate(self, snapshot: ExtensionSnapshot) -> ActivationResult:
-        diagnostics: list[ExtensionDiagnostic] = []
-        for candidate in snapshot.extensions:
-            try:
-                active = self._activate_candidate(candidate)
-                self._active.append(active)
-            except Exception as exc:
-                self._rollback_owner(candidate.manifest.id)
-                diagnostics.append(
-                    ExtensionDiagnostic(
-                        code="activation_failed",
-                        extension_id=candidate.manifest.id,
-                        message=str(exc),
-                    )
-                )
-        return ActivationResult(
-            tuple(self._active),
-            tuple(self._hook_factories),
-            tuple(diagnostics),
-        )
-
-    async def close(self) -> None:
-        for active in reversed(self._active):
-            self._rollback_owner(active.manifest.id)
-            _unload_extension_modules(active)
-        self._active.clear()
-
-    def _activate_candidate(
-        self,
-        candidate: ExtensionCandidate,
-    ) -> ExtensionCandidate:
-        self._activate_python(candidate)
-        return candidate
-
-    def _activate_python(self, candidate: ExtensionCandidate) -> None:
-        raw_entry = candidate.manifest.entry
-        module_name, separator, attribute = raw_entry.partition(":")
-        if not separator:
-            module_name = raw_entry
-            attribute = "register"
-        assert candidate.location is not None
-        importlib.invalidate_caches()
-        module_prefix = _module_prefix(candidate.manifest.id)
-        _unload_extension_modules(candidate)
-        package = ModuleType(module_prefix)
-        package.__package__ = module_prefix
-        package.__path__ = [str(candidate.location)]
-        package.__spec__ = ModuleSpec(module_prefix, loader=None, is_package=True)
-        sys.modules[module_prefix] = package
-        try:
-            module = importlib.import_module(f"{module_prefix}.{module_name}")
-            module_path = getattr(module, "__file__", None)
-            if not module_path or not Path(module_path).resolve().is_relative_to(
-                candidate.location.resolve()
-            ):
-                raise ValueError(
-                    f"Python extension entry resolves outside its package: {module_name}"
-                )
-            register = getattr(module, attribute)
-            api = PythonExtensionApi(
-                owner=candidate.manifest.id,
-                tools=self._tools,
-                commands=self._commands,
-                hook_factories=self._hook_factories,
-            )
-            result = register(api)
-            if result is not None:
-                raise TypeError("Python extension register function must return None")
-        except Exception:
-            _unload_extension_modules(candidate)
-            raise
-
-    def _rollback_owner(
-        self,
-        owner: str,
-    ) -> None:
-        self._tools.unregister_owner(owner)
-        self._commands.unregister_owner(owner)
-        self._hook_factories[:] = [
-            factory
-            for factory in self._hook_factories
-            if getattr(factory, "__nanobot_extension_owner__", None) != owner
-        ]
-
-
-def _owned_hook_factory(
-    factory: AgentTurnHookFactory,
-    owner: str,
-) -> AgentTurnHookFactory:
-    def owned(context: Any) -> AgentHook | None:
-        return factory(context)
-
-    setattr(owned, "__nanobot_extension_owner__", owner)
-    return owned
-
-
-def _modules_under(root: Path) -> tuple[str, ...]:
-    package_root = root.resolve()
-    return tuple(
-        name
-        for name, module in tuple(sys.modules.items())
-        if (raw_path := getattr(module, "__file__", None))
-        and Path(raw_path).resolve().is_relative_to(package_root)
-    )
-
-
-def _unload_modules_under(root: Path) -> None:
-    package_root = root.resolve()
-    for module_name in _modules_under(package_root):
-        sys.modules.pop(module_name, None)
-    for cache in package_root.rglob("__pycache__"):
-        shutil.rmtree(cache, ignore_errors=True)
-
-
-def _module_prefix(extension_id: str) -> str:
-    return "_nanobot_extension_" + extension_id.encode().hex()
-
-
-def _unload_extension_modules(candidate: ExtensionCandidate) -> None:
-    assert candidate.location is not None
-    prefix = _module_prefix(candidate.manifest.id)
-    for name in tuple(sys.modules):
-        if name == prefix or name.startswith(f"{prefix}."):
-            sys.modules.pop(name, None)
-    _unload_modules_under(candidate.location)

nanobot/extensions/service.py

@@ -1,167 +0,0 @@
-"""Transport-neutral extension management service."""
-
-from __future__ import annotations
-
-import asyncio
-from dataclasses import asdict
-from pathlib import Path
-from typing import Any
-
-from nanobot.extensions.host import ExtensionHost
-from nanobot.extensions.manifest import ExtensionManifest
-from nanobot.extensions.registry import ExtensionCandidate
-from nanobot.extensions.store import ExtensionStore, InstalledExtension
-
-
-class ExtensionService:
-    """One management boundary shared by CLI and WebUI."""
-
-    def __init__(
-        self,
-        *,
-        host: ExtensionHost | None = None,
-        store: ExtensionStore | None = None,
-    ) -> None:
-        self.host = host
-        self.store = store or ExtensionStore()
-        self._mutation_lock = asyncio.Lock()
-
-    async def status(self) -> dict[str, Any]:
-        snapshot = self.host.snapshot if self.host else None
-        catalog = snapshot.catalog if snapshot else None
-        if catalog is None:
-            discovery = self.store.discover()
-            candidates = discovery.candidates
-            diagnostics = discovery.diagnostics
-            active_ids: set[str] = set()
-        else:
-            candidates = catalog.candidates
-            active_ids = {
-                active.manifest.id
-                for active in snapshot.activation.extensions
-            }
-            diagnostics = catalog.diagnostics + snapshot.activation.diagnostics
-        records = self.store.records()
-        return {
-            "extensions": [
-                _candidate_payload(candidate, active_ids, records.get(candidate.manifest.id))
-                for candidate in sorted(
-                    candidates,
-                    key=lambda item: item.manifest.name.lower(),
-                )
-            ],
-            "diagnostics": [asdict(item) for item in diagnostics],
-        }
-
-    async def install(
-        self,
-        source: str,
-        *,
-        kind: str = "git",
-        ref: str = "",
-        trusted: bool = False,
-    ) -> dict[str, Any]:
-        async with self._mutation_lock:
-            if kind == "git":
-                result = await asyncio.to_thread(
-                    self.store.install_git,
-                    source,
-                    ref=ref,
-                    trusted=trusted,
-                )
-            elif kind == "local":
-                result = await asyncio.to_thread(
-                    self.store.install_local,
-                    Path(source),
-                    trusted=trusted,
-                )
-            else:
-                raise ValueError(f"unknown extension source kind: {kind}")
-            await self._reload()
-            return {
-                "record": _record_payload(result.record),
-                "manifest": _manifest_payload(result.manifest),
-            }
-
-    async def set_enabled(self, extension_id: str, enabled: bool) -> dict[str, Any]:
-        return await self._update(extension_id, self.store.set_enabled, enabled)
-
-    async def set_trusted(self, extension_id: str, trusted: bool) -> dict[str, Any]:
-        return await self._update(extension_id, self.store.set_trusted, trusted)
-
-    async def set_permissions(
-        self,
-        extension_id: str,
-        permissions: set[str] | frozenset[str],
-    ) -> dict[str, Any]:
-        return await self._update(
-            extension_id,
-            self.store.set_permissions,
-            permissions,
-        )
-
-    async def uninstall(self, extension_id: str) -> dict[str, Any]:
-        async with self._mutation_lock:
-            await asyncio.to_thread(self.store.uninstall, extension_id)
-            await self._reload()
-            return {"removed": extension_id}
-
-    async def _update(self, extension_id: str, action: Any, value: Any) -> dict[str, Any]:
-        async with self._mutation_lock:
-            record = await asyncio.to_thread(action, extension_id, value)
-            await self._reload()
-            return {"record": _record_payload(record)}
-
-    async def _reload(self) -> None:
-        if self.host is not None:
-            await self.host.reload()
-
-
-def _candidate_payload(
-    candidate: ExtensionCandidate,
-    active_ids: set[str],
-    record: InstalledExtension | None,
-) -> dict[str, Any]:
-    manifest = candidate.manifest
-    requested = [permission.name for permission in manifest.permissions]
-    return {
-        **_manifest_payload(manifest),
-        "location": str(candidate.location) if candidate.location else None,
-        "enabled": candidate.enabled,
-        "trusted": candidate.trusted,
-        "active": manifest.id in active_ids,
-        "requested_permissions": requested,
-        "granted_permissions": sorted(candidate.granted_permissions),
-        "source": record.source.value if record else "path",
-        "source_ref": record.source_ref if record else "",
-        "integrity": record.integrity if record else "",
-        "installed_at": record.installed_at if record else "",
-    }
-
-
-def _manifest_payload(manifest: ExtensionManifest) -> dict[str, Any]:
-    return {
-        "id": manifest.id,
-        "name": manifest.name,
-        "version": manifest.version,
-        "description": manifest.description,
-        "homepage": manifest.homepage,
-        "license": manifest.license,
-        "dependencies": [
-            {
-                "kind": dependency.kind.value,
-                "name": dependency.name,
-                "specifier": dependency.specifier,
-                "optional": dependency.optional,
-            }
-            for dependency in manifest.dependencies
-        ],
-        "permissions": [
-            {"name": permission.name, "reason": permission.reason}
-            for permission in manifest.permissions
-        ],
-    }
-
-
-def _record_payload(record: InstalledExtension) -> dict[str, Any]:
-    return record.model_dump(mode="json")

nanobot/extensions/store.py

@@ -1,511 +0,0 @@
-"""Atomic installation store and trust state for external extensions."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import re
-import shutil
-import subprocess
-import tempfile
-from dataclasses import dataclass, replace
-from datetime import UTC, datetime
-from enum import Enum
-from pathlib import Path
-from typing import Any
-from urllib.parse import urlparse
-from uuid import uuid4
-
-from filelock import FileLock
-from pydantic import BaseModel, ConfigDict, field_validator
-
-from nanobot.extensions.codec import MANIFEST_FILENAME, load_manifest
-from nanobot.extensions.discovery import (
-    ExtensionDiscoveryResult,
-    discover_manifest_root,
-)
-from nanobot.extensions.manifest import ExtensionManifest, validate_extension_id
-from nanobot.extensions.registry import ExtensionDiagnostic
-
-_REGISTRY_FILENAME = ".registry.json"
-_GIT_SCHEMES = frozenset({"git", "http", "https", "ssh"})
-_SCP_GIT_URL = re.compile(
-    r"(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?:\S+"
-)
-_SHA256_INTEGRITY = re.compile(r"sha256:[0-9a-f]{64}")
-
-
-class ExtensionSourceKind(str, Enum):
-    LOCAL = "local"
-    GIT = "git"
-
-
-class InstalledExtension(BaseModel):
-    """Persistent installation and policy record."""
-
-    model_config = ConfigDict(extra="forbid", frozen=True)
-
-    id: str
-    version: str
-    source: ExtensionSourceKind
-    source_ref: str
-    integrity: str
-    installed_at: str
-    enabled: bool = True
-    trusted: bool = False
-    granted_permissions: tuple[str, ...] = ()
-
-    @field_validator("id")
-    @classmethod
-    def validate_id(cls, value: str) -> str:
-        return validate_extension_id(value)
-
-    @field_validator("version", "source_ref", "installed_at")
-    @classmethod
-    def validate_metadata(cls, value: str) -> str:
-        if not value:
-            raise ValueError("extension registry metadata must use non-empty strings")
-        return value
-
-    @field_validator("integrity")
-    @classmethod
-    def validate_integrity(cls, value: str) -> str:
-        if _SHA256_INTEGRITY.fullmatch(value) is None:
-            raise ValueError("extension registry integrity must be a sha256 digest")
-        return value
-
-    @field_validator("granted_permissions")
-    @classmethod
-    def reject_duplicate_permissions(cls, value: tuple[str, ...]) -> tuple[str, ...]:
-        if len(set(value)) != len(value):
-            raise ValueError("extension granted permissions cannot contain duplicates")
-        return value
-
-
-@dataclass(frozen=True, slots=True)
-class InstallResult:
-    """Installed package metadata."""
-
-    record: InstalledExtension
-    manifest: ExtensionManifest
-
-
-class ExtensionStore:
-    """Own the user extension directory and its atomic registry."""
-
-    def __init__(self, root: Path | None = None) -> None:
-        self.root = (root or Path.home() / ".nanobot" / "extensions").expanduser()
-        self.root.mkdir(parents=True, exist_ok=True)
-        self.registry_path = self.root / _REGISTRY_FILENAME
-        self._lock = FileLock(str(self.root / ".lock"))
-
-    def records(self, *, strict: bool = False) -> dict[str, InstalledExtension]:
-        if not self.registry_path.is_file():
-            return {}
-        try:
-            data = json.loads(self.registry_path.read_text(encoding="utf-8"))
-            if not isinstance(data, dict) or data.get("version") != 1:
-                raise ValueError("extension registry must be a version 1 object")
-            rows = data.get("extensions")
-            if not isinstance(rows, list):
-                raise ValueError("extension registry extensions must be an array")
-            records: dict[str, InstalledExtension] = {}
-            for item in rows:
-                record = InstalledExtension.model_validate(item)
-                if record.id in records:
-                    raise ValueError(
-                        f"extension registry contains duplicate id: {record.id}"
-                    )
-                records[record.id] = record
-            return records
-        except (
-            OSError,
-            UnicodeError,
-            json.JSONDecodeError,
-            KeyError,
-            ValueError,
-        ) as exc:
-            if strict:
-                raise ValueError(
-                    f"invalid extension registry {self.registry_path}: {exc}"
-                ) from exc
-            return {}
-
-    def discover(self) -> ExtensionDiscoveryResult:
-        """Discover packages and apply persisted enable/trust state."""
-        result = discover_manifest_root(self.root)
-        diagnostics = list(result.diagnostics)
-        try:
-            records = self.records(strict=True)
-        except ValueError as exc:
-            records = {}
-            diagnostics.append(
-                ExtensionDiagnostic(
-                    code="invalid_extension_registry",
-                    extension_id="",
-                    message=str(exc),
-                )
-            )
-        candidates = []
-        for candidate in result.candidates:
-            record = records.get(candidate.manifest.id)
-            trusted = record.trusted if record else False
-            integrity_valid = True
-            if candidate.location is not None and record is not None:
-                try:
-                    _reject_unsafe_files(candidate.location)
-                    actual_integrity = _tree_hash(candidate.location)
-                except (OSError, ValueError) as exc:
-                    actual_integrity = ""
-                    diagnostics.append(
-                        ExtensionDiagnostic(
-                            code="extension_integrity_error",
-                            extension_id=candidate.manifest.id,
-                            message=f"Could not verify installed package: {exc}",
-                        )
-                    )
-                if actual_integrity != record.integrity:
-                    trusted = False
-                    integrity_valid = False
-                    diagnostics.append(
-                        ExtensionDiagnostic(
-                            code="extension_integrity_mismatch",
-                            extension_id=candidate.manifest.id,
-                            message=(
-                                "Installed package contents changed after installation; "
-                                "reinstall it before trusting it again"
-                            ),
-                        )
-                    )
-            candidates.append(
-                replace(
-                    candidate,
-                    enabled=record.enabled if record else True,
-                    trusted=trusted,
-                    integrity_valid=integrity_valid,
-                    granted_permissions=frozenset(
-                        record.granted_permissions if record else ()
-                    ),
-                )
-            )
-        return ExtensionDiscoveryResult(tuple(candidates), tuple(diagnostics))
-
-    def install_local(
-        self,
-        source: Path,
-        *,
-        trusted: bool = False,
-    ) -> InstallResult:
-        return self._install_from_directory(
-            source.resolve(),
-            source_kind=ExtensionSourceKind.LOCAL,
-            source_ref=str(source.resolve()),
-            trusted=trusted,
-        )
-
-    def install_git(
-        self,
-        url: str,
-        *,
-        ref: str = "",
-        trusted: bool = False,
-    ) -> InstallResult:
-        _validate_git_url(url)
-        with tempfile.TemporaryDirectory(prefix="nanobot-extension-git-") as raw:
-            checkout = Path(raw) / "checkout"
-            if ref:
-                _run(
-                    [
-                        "git",
-                        "clone",
-                        "--filter=blob:none",
-                        "--no-checkout",
-                        "--",
-                        url,
-                        str(checkout),
-                    ]
-                )
-                _run(
-                    [
-                        "git",
-                        "-C",
-                        str(checkout),
-                        "fetch",
-                        "--depth",
-                        "1",
-                        "--",
-                        "origin",
-                        ref,
-                    ]
-                )
-                _run(
-                    [
-                        "git",
-                        "-C",
-                        str(checkout),
-                        "checkout",
-                        "--detach",
-                        "FETCH_HEAD",
-                    ]
-                )
-            else:
-                _run(["git", "clone", "--depth", "1", "--", url, str(checkout)])
-            return self._install_from_directory(
-                checkout,
-                source_kind=ExtensionSourceKind.GIT,
-                source_ref=f"{url}#{ref}" if ref else url,
-                trusted=trusted,
-            )
-
-    def set_enabled(self, extension_id: str, enabled: bool) -> InstalledExtension:
-        return self._update_record(extension_id, enabled=enabled)
-
-    def set_trusted(self, extension_id: str, trusted: bool) -> InstalledExtension:
-        return self._update_record(extension_id, trusted=trusted)
-
-    def set_permissions(
-        self,
-        extension_id: str,
-        permissions: set[str] | frozenset[str],
-    ) -> InstalledExtension:
-        with self._lock:
-            records = self.records(strict=True)
-            if extension_id not in records:
-                raise KeyError(f"extension '{extension_id}' is not installed")
-            manifest = load_manifest(
-                self.root / extension_id / MANIFEST_FILENAME
-            )
-            requested = {
-                permission.name for permission in manifest.permissions
-            }
-            unknown = sorted(set(permissions) - requested)
-            if unknown:
-                raise ValueError(
-                    "Cannot grant permissions not requested by the extension: "
-                    + ", ".join(unknown)
-                )
-            return self._update_record_locked(
-                records,
-                extension_id,
-                granted_permissions=tuple(sorted(permissions)),
-            )
-
-    def uninstall(self, extension_id: str) -> None:
-        with self._lock:
-            records = self.records(strict=True)
-            if extension_id not in records:
-                raise KeyError(f"extension '{extension_id}' is not installed")
-            target = self.root / extension_id
-            backup = self.root / f".uninstall-{uuid4().hex}"
-            if target.exists():
-                target.rename(backup)
-            try:
-                records.pop(extension_id)
-                self._write_records(records)
-            except Exception:
-                if backup.exists():
-                    backup.rename(target)
-                raise
-            shutil.rmtree(backup, ignore_errors=True)
-
-    def _install_from_directory(
-        self,
-        source: Path,
-        *,
-        source_kind: ExtensionSourceKind,
-        source_ref: str,
-        trusted: bool,
-    ) -> InstallResult:
-        with self._lock:
-            return self._install_from_directory_locked(
-                source,
-                source_kind=source_kind,
-                source_ref=source_ref,
-                trusted=trusted,
-            )
-
-    def _install_from_directory_locked(
-        self,
-        source: Path,
-        *,
-        source_kind: ExtensionSourceKind,
-        source_ref: str,
-        trusted: bool,
-    ) -> InstallResult:
-        if not source.is_dir():
-            raise ValueError(f"extension source is not a directory: {source}")
-        if self.root.resolve().is_relative_to(source.resolve()):
-            raise ValueError("extension source cannot contain the extension store")
-        _reject_unsafe_files(source)
-        manifest = load_manifest(source / MANIFEST_FILENAME)
-        extension_id = manifest.id
-        self.root.mkdir(parents=True, exist_ok=True)
-        staging = self.root / f".install-{uuid4().hex}"
-        target = self.root / extension_id
-        backup = self.root / f".backup-{uuid4().hex}"
-        records = self.records(strict=True)
-        previous = records.get(extension_id)
-        backup_created = False
-        target_installed = False
-        try:
-            shutil.copytree(
-                source,
-                staging,
-                ignore=shutil.ignore_patterns(".git", "__pycache__", "*.pyc"),
-            )
-            _reject_unsafe_files(staging)
-            integrity = _tree_hash(staging)
-            if target.exists():
-                target.rename(backup)
-                backup_created = True
-            staging.rename(target)
-            target_installed = True
-            requested_permissions = {
-                permission.name for permission in manifest.permissions
-            }
-            unchanged = bool(previous and previous.integrity == integrity)
-            record = InstalledExtension(
-                id=extension_id,
-                version=manifest.version,
-                source=source_kind,
-                source_ref=source_ref,
-                integrity=integrity,
-                installed_at=datetime.now(UTC).isoformat(),
-                enabled=previous.enabled if previous else True,
-                trusted=trusted or bool(unchanged and previous and previous.trusted),
-                granted_permissions=(
-                    tuple(
-                        permission
-                        for permission in previous.granted_permissions
-                        if permission in requested_permissions
-                    )
-                    if previous
-                    else ()
-                ),
-            )
-            records[extension_id] = record
-            self._write_records(records)
-            shutil.rmtree(backup, ignore_errors=True)
-            return InstallResult(record, manifest)
-        except Exception:
-            shutil.rmtree(staging, ignore_errors=True)
-            if target_installed:
-                shutil.rmtree(target, ignore_errors=True)
-            if backup_created:
-                backup.rename(target)
-            raise
-
-    def _update_record(
-        self,
-        extension_id: str,
-        **changes: Any,
-    ) -> InstalledExtension:
-        with self._lock:
-            records = self.records(strict=True)
-            return self._update_record_locked(records, extension_id, **changes)
-
-    def _update_record_locked(
-        self,
-        records: dict[str, InstalledExtension],
-        extension_id: str,
-        **changes: Any,
-    ) -> InstalledExtension:
-        try:
-            record = records[extension_id].model_copy(update=changes)
-        except KeyError as exc:
-            raise KeyError(
-                f"extension '{extension_id}' is not installed"
-            ) from exc
-        records[extension_id] = record
-        self._write_records(records)
-        return record
-
-    def _write_records(self, records: dict[str, InstalledExtension]) -> None:
-        self.root.mkdir(parents=True, exist_ok=True)
-        payload = {
-            "version": 1,
-            "extensions": [
-                record.model_dump(mode="json")
-                for record in sorted(records.values(), key=lambda item: item.id)
-            ],
-        }
-        temp = self.registry_path.with_suffix(".tmp")
-        temp.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
-        os.replace(temp, self.registry_path)
-
-
-def _run(command: list[str], *, cwd: Path | None = None) -> str:
-    try:
-        return subprocess.run(
-            command,
-            cwd=cwd,
-            check=True,
-            capture_output=True,
-            text=True,
-        ).stdout
-    except FileNotFoundError as exc:
-        raise RuntimeError(f"required executable not found: {command[0]}") from exc
-    except subprocess.CalledProcessError as exc:
-        detail = (exc.stderr or exc.stdout or "").strip()
-        raise RuntimeError(f"{command[0]} failed: {detail}") from exc
-
-
-def _validate_git_url(url: str) -> None:
-    if not isinstance(url, str) or not url.strip() or any(
-        character in url for character in ("\0", "\r", "\n")
-    ):
-        raise ValueError("extension Git source must be a remote repository URL")
-    value = url.strip()
-    parsed = urlparse(value)
-    if parsed.scheme:
-        if parsed.scheme.lower() not in _GIT_SCHEMES or not parsed.hostname or not parsed.path:
-            raise ValueError(
-                "extension Git source must use git, http, https, or ssh"
-            )
-        if parsed.password or (
-            parsed.scheme.lower() in {"http", "https"} and parsed.username
-        ):
-            raise ValueError(
-                "extension Git URLs cannot contain credentials; use a Git credential helper"
-            )
-        if parsed.query or parsed.fragment:
-            raise ValueError(
-                "extension Git URLs cannot contain query parameters or fragments; "
-                "pass the revision separately"
-            )
-        return
-    if _SCP_GIT_URL.fullmatch(value) is None or any(
-        character in value for character in ("?", "#")
-    ):
-        raise ValueError("extension Git source must be a remote repository URL")
-
-
-def _reject_unsafe_files(root: Path) -> None:
-    for path in root.rglob("*"):
-        if path.is_symlink():
-            raise ValueError(f"extension packages cannot contain symlinks: {path}")
-        if not path.is_file() and not path.is_dir():
-            raise ValueError(f"extension package contains a special file: {path}")
-
-
-def _tree_hash(root: Path) -> str:
-    digest = hashlib.sha256()
-    for path in sorted(
-        item
-        for item in root.rglob("*")
-        if (item.is_file() or item.is_symlink())
-        and "__pycache__" not in item.parts
-        and item.suffix not in {".pyc", ".pyo"}
-    ):
-        digest.update(path.relative_to(root).as_posix().encode())
-        digest.update(b"\0")
-        if path.is_symlink():
-            digest.update(b"link\0")
-            digest.update(os.fsencode(os.readlink(path)))
-            continue
-        digest.update(b"file\0")
-        with path.open("rb") as handle:
-            while chunk := handle.read(1024 * 1024):
-                digest.update(chunk)
-    return f"sha256:{digest.hexdigest()}"

nanobot/extensions/versioning.py

@@ -1,29 +0,0 @@
-"""Version constraint checks shared by extension activation gates."""
-
-from packaging.specifiers import InvalidSpecifier, SpecifierSet
-from packaging.version import InvalidVersion, Version
-
-from nanobot.extensions.manifest import ExtensionDependency
-
-
-def dependency_version_failure(
-    dependency: ExtensionDependency,
-    version: str,
-    label: str,
-) -> str:
-    """Return a user-facing constraint failure, or an empty string on success."""
-    if not dependency.specifier:
-        return ""
-    try:
-        matches = Version(version) in SpecifierSet(dependency.specifier)
-    except (InvalidSpecifier, InvalidVersion):
-        return (
-            f"{label} {dependency.name} has an unsupported version constraint: "
-            f"{dependency.specifier}"
-        )
-    if matches:
-        return ""
-    return (
-        f"{label} {dependency.name} {version} does not satisfy "
-        f"{dependency.specifier}"
-    )

nanobot/nanobot.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Mapping
 from pathlib import Path
 from typing import Any
 
@@ -11,13 +11,9 @@ from nanobot.agent.hook import AgentHook, SDKCaptureHook
 from nanobot.agent.hooks import create_file_edit_activity_hook
 from nanobot.agent.loop import AgentLoop
 from nanobot.config.schema import Config
-from nanobot.extensions.host import ExtensionHost
 from nanobot.providers.image_generation import image_gen_provider_configs
 from nanobot.sdk.clients import MemoryClient, RuntimeClient, SessionClient
-from nanobot.sdk.runtime import (
+from nanobot.sdk.runtime import build_process_direct_kwargs
-    build_process_direct_kwargs,
-    ensure_single_model_selector,
-)
 from nanobot.sdk.streaming import RunStream, SDKStreamEmitter, SDKStreamingHook
 from nanobot.sdk.types import (
     STREAM_EVENT_REASONING_COMPLETED,
@@ -78,9 +74,6 @@ class Nanobot:
         self.sessions = SessionClient(loop)
         self.memory = MemoryClient(loop)
         self.runtime = RuntimeClient(loop)
-        self._extensions = ExtensionHost(loop, lambda: config) if config else None
-        self._extensions_started = False
-        self._extensions_lock = asyncio.Lock()
 
     @classmethod
     def from_config(
@@ -88,7 +81,6 @@ class Nanobot:
         config_path: str | Path | None = None,
         *,
         workspace: str | Path | None = None,
-        model: str | None = None,
         model_preset: str | None = None,
     ) -> Nanobot:
         """Create a Nanobot instance from a config file.
@@ -97,28 +89,25 @@ class Nanobot:
             config_path: Path to ``config.json``.  Defaults to
                 ``~/.nanobot/config.json``.
             workspace: Override the workspace directory from config.
-            model: Override the instance default model.
             model_preset: Override the instance default model preset.
         """
         from nanobot.config.loader import load_config, resolve_config_env_vars
 
-        ensure_single_model_selector(model=model, model_preset=model_preset)
         resolved: Path | None = None
         if config_path is not None:
             resolved = Path(config_path).expanduser().resolve()
             if not resolved.exists():
                 raise FileNotFoundError(f"Config not found: {resolved}")
 
-        config: Config = resolve_config_env_vars(load_config(resolved))
+        config: Config = resolve_config_env_vars(
+            load_config(resolved),
+            config_path=resolved,
+        )
         if workspace is not None:
             config.agents.defaults.workspace = str(
                 Path(workspace).expanduser().resolve()
             )
-        if model is not None:
+        if model_preset is not None:
-            config.agents.defaults.model_preset = None
-            config.agents.defaults.model = model
-            config.agents.defaults.provider = "auto"
-        elif model_preset is not None:
             config.agents.defaults.model_preset = model_preset
 
         loop = AgentLoop.from_config(
@@ -138,8 +127,8 @@ class Nanobot:
         sender_id: str = "user",
         media: list[str] | None = None,
         ephemeral: bool = False,
+        attributes: Mapping[str, Any] | None = None,
         hooks: list[AgentHook] | None = None,
-        model: str | None = None,
         model_preset: str | None = None,
     ) -> RunResult:
         """Run the agent once and return the result.
@@ -153,15 +142,16 @@ class Nanobot:
             sender_id: Logical sender identifier for runtime context.
             media: Optional local media paths attached to the message.
             ephemeral: If true, do not persist the turn or compact session history.
+            attributes: Optional caller-owned request data exposed to context
+                providers and turn-hook factories. Attributes are kept separate
+                from nanobot's trusted internal message metadata.
             hooks: Optional lifecycle hooks for this run.
-            model: Override the model for this run only.
             model_preset: Override the model preset for this run only.
         """
-        await self._ensure_extensions()
         capture = SDKCaptureHook()
         per_run_hooks = [capture, *(hooks or [])]
         runtime = self._loop.runtime_resolver.resolve_override(
-            model=model,
+            model=None,
             model_preset=model_preset,
             config=self._config,
         )
@@ -172,6 +162,7 @@ class Nanobot:
             sender_id=sender_id,
             media=media,
             ephemeral=ephemeral,
+            attributes=attributes,
         )
         if runtime is not None:
             kwargs["runtime"] = runtime
@@ -193,14 +184,13 @@ class Nanobot:
         sender_id: str = "user",
         media: list[str] | None = None,
         ephemeral: bool = False,
+        attributes: Mapping[str, Any] | None = None,
         hooks: list[AgentHook] | None = None,
-        model: str | None = None,
         model_preset: str | None = None,
     ) -> RunStream:
         """Start a streamed run and return a handle for events and final result."""
-        await self._ensure_extensions()
         override_runtime = self._loop.runtime_resolver.resolve_override(
-            model=model,
+            model=None,
             model_preset=model_preset,
             config=self._config,
         )
@@ -248,6 +238,7 @@ class Nanobot:
                 sender_id=sender_id,
                 media=media,
                 ephemeral=ephemeral,
+                attributes=attributes,
                 on_stream=_on_stream,
                 on_stream_end=_on_stream_end,
             )
@@ -295,8 +286,8 @@ class Nanobot:
         sender_id: str = "user",
         media: list[str] | None = None,
         ephemeral: bool = False,
+        attributes: Mapping[str, Any] | None = None,
         hooks: list[AgentHook] | None = None,
-        model: str | None = None,
         model_preset: str | None = None,
     ) -> AsyncIterator[StreamEvent]:
         """Stream events for one agent turn."""
@@ -308,8 +299,8 @@ class Nanobot:
             sender_id=sender_id,
             media=media,
             ephemeral=ephemeral,
+            attributes=attributes,
             hooks=hooks,
-            model=model,
             model_preset=model_preset,
         )
         try:
@@ -322,20 +313,7 @@ class Nanobot:
 
     async def aclose(self) -> None:
         """Release resources held by this instance (MCP connections, etc.)."""
-        try:
+        await self._loop.close_mcp()
-            if self._extensions is not None:
-                await self._extensions.close()
-                self._extensions_started = False
-        finally:
-            await self._loop.close_mcp()
-
-    async def _ensure_extensions(self) -> None:
-        if self._extensions is None or self._extensions_started:
-            return
-        async with self._extensions_lock:
-            if not self._extensions_started:
-                await self._extensions.reload()
-                self._extensions_started = True
 
     async def __aenter__(self) -> Nanobot:
         return self

nanobot/providers/base.py

@@ -218,6 +218,16 @@ class LLMProvider(ABC):
         "速率限制",
         "访问量过大",
     )
+    _IMAGE_UNSUPPORTED_MARKERS = (
+        "does not support image",
+        "doesn't support image",
+        "images are not supported",
+        "image input is not supported",
+        "image input not supported",
+        "image_url is not supported",
+        "unsupported image input",
+        "vision is not supported",
+    )
     _RETRYABLE_STATUS_CODES = frozenset({408, 409, 429})
     _TRANSIENT_ERROR_KINDS = frozenset({"timeout", "connection"})
     _NON_RETRYABLE_429_ERROR_TOKENS = frozenset({
@@ -272,6 +282,7 @@ class LLMProvider(ABC):
         self.api_key = api_key
         self.api_base = api_base
         self.generation: GenerationSettings = GenerationSettings()
+        self.supports_image_input: bool | None = None
 
     @staticmethod
     def _sanitize_empty_content(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
@@ -602,6 +613,51 @@ class LLMProvider(ABC):
                 result.append(msg)
         return result if found else None
 
+    def _messages_for_image_capability(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        supports_image_input: bool | None | object = _SENTINEL,
+    ) -> list[dict[str, Any]]:
+        """Apply an explicit text-only preset before making a provider request."""
+        capability = (
+            self.supports_image_input
+            if supports_image_input is self._SENTINEL
+            else supports_image_input
+        )
+        if capability is not False:
+            return messages
+        return self._strip_image_content(messages) or messages
+
+    def _outer_image_capability(
+        self,
+        supports_image_input: bool | None,
+    ) -> bool | None:
+        """Return the image policy applied by this provider's retry wrapper."""
+        return supports_image_input
+
+    def _image_policy_request_kwargs(
+        self,
+        supports_image_input: bool | None,
+    ) -> dict[str, Any]:
+        """Return provider-internal kwargs needed for candidate image policy."""
+        return {}
+
+    @classmethod
+    def _is_image_unsupported_response(cls, response: LLMResponse) -> bool:
+        if response.finish_reason != "error":
+            return False
+        text = " ".join(
+            str(value or "")
+            for value in (
+                response.content,
+                response.error_kind,
+                response.error_type,
+                response.error_code,
+            )
+        ).lower()
+        return any(marker in text for marker in cls._IMAGE_UNSUPPORTED_MARKERS)
+
     @staticmethod
     def _strip_image_content_inplace(messages: list[dict[str, Any]]) -> bool:
         """Replace image_url blocks with text placeholder *in-place*.
@@ -692,6 +748,7 @@ class LLMProvider(ABC):
         on_stream_recover: Callable[[], Awaitable[None]] | None = None,
         retry_mode: str = "standard",
         on_retry_wait: Callable[[str], Awaitable[None]] | None = None,
+        supports_image_input: bool | None | object = _SENTINEL,
     ) -> LLMResponse:
         """Call chat_stream() with retry on transient provider failures."""
         if max_tokens is self._SENTINEL or max_tokens is None:
@@ -700,6 +757,14 @@ class LLMProvider(ABC):
             temperature = self.generation.temperature
         if reasoning_effort is self._SENTINEL:
             reasoning_effort = self.generation.reasoning_effort
+        candidate_image_capability = (
+            self.supports_image_input
+            if supports_image_input is self._SENTINEL
+            else supports_image_input
+        )
+        outer_image_capability = self._outer_image_capability(
+            candidate_image_capability
+        )
 
         has_streamed_content = False
 
@@ -717,13 +782,19 @@ class LLMProvider(ABC):
             has_streamed_content = False
 
         kw: dict[str, Any] = dict(
-            messages=messages, tools=tools, model=model,
+            messages=self._messages_for_image_capability(
+                messages,
+                supports_image_input=outer_image_capability,
+            ),
+            tools=tools,
+            model=model,
             max_tokens=max_tokens, temperature=temperature,
             reasoning_effort=reasoning_effort, tool_choice=tool_choice,
             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,
         )
+        kw.update(self._image_policy_request_kwargs(candidate_image_capability))
         if on_stream_recover and getattr(self, "supports_stream_recover_callback", False):
             kw["on_stream_recover"] = _recover_stream
         return await self._run_with_retry(
@@ -734,6 +805,7 @@ class LLMProvider(ABC):
             on_retry_wait=on_retry_wait,
             should_retry_guard=lambda: not has_streamed_content,
             on_stream_recover=_recover_stream if on_stream_recover else None,
+            supports_image_input=outer_image_capability,
         )
 
     async def chat_with_retry(
@@ -747,6 +819,7 @@ class LLMProvider(ABC):
         tool_choice: str | dict[str, Any] | None = None,
         retry_mode: str = "standard",
         on_retry_wait: Callable[[str], Awaitable[None]] | None = None,
+        supports_image_input: bool | None | object = _SENTINEL,
     ) -> LLMResponse:
         """Call chat() with retry on transient provider failures.
 
@@ -763,18 +836,33 @@ class LLMProvider(ABC):
             temperature = self.generation.temperature
         if reasoning_effort is self._SENTINEL:
             reasoning_effort = self.generation.reasoning_effort
+        candidate_image_capability = (
+            self.supports_image_input
+            if supports_image_input is self._SENTINEL
+            else supports_image_input
+        )
+        outer_image_capability = self._outer_image_capability(
+            candidate_image_capability
+        )
 
         kw: dict[str, Any] = dict(
-            messages=messages, tools=tools, model=model,
+            messages=self._messages_for_image_capability(
+                messages,
+                supports_image_input=outer_image_capability,
+            ),
+            tools=tools,
+            model=model,
             max_tokens=max_tokens, temperature=temperature,
             reasoning_effort=reasoning_effort, tool_choice=tool_choice,
         )
+        kw.update(self._image_policy_request_kwargs(candidate_image_capability))
         return await self._run_with_retry(
             self._safe_chat,
             kw,
             messages,
             retry_mode=retry_mode,
             on_retry_wait=on_retry_wait,
+            supports_image_input=outer_image_capability,
         )
 
     @classmethod
@@ -882,6 +970,7 @@ class LLMProvider(ABC):
         on_retry_wait: Callable[[str], Awaitable[None]] | None,
         should_retry_guard: Callable[[], bool] | None = None,
         on_stream_recover: Callable[[], Awaitable[None]] | None = None,
+        supports_image_input: bool | None | object = _SENTINEL,
     ) -> LLMResponse:
         attempt = 0
         delays = list(self._CHAT_RETRY_DELAYS)
@@ -928,9 +1017,19 @@ class LLMProvider(ABC):
 
             if not self._is_transient_response(response):
                 stripped = self._strip_image_content(original_messages)
-                if stripped is not None and stripped != kw["messages"]:
+                if (
+                    (
+                        self.supports_image_input
+                        if supports_image_input is self._SENTINEL
+                        else supports_image_input
+                    )
+                    is None
+                    and self._is_image_unsupported_response(response)
+                    and stripped is not None
+                    and stripped != kw["messages"]
+                ):
                     logger.warning(
-                        "Non-transient LLM error with image content, retrying without images"
+                        "Model rejected image input, retrying without images"
                     )
                     retry_kw = dict(kw)
                     retry_kw["messages"] = stripped

nanobot/providers/factory.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 
-from nanobot.config.schema import Config, InlineFallbackConfig, ModelPresetConfig, ProviderConfig
+from nanobot.config.schema import Config, ModelPresetConfig, ProviderConfig
 from nanobot.providers.base import GenerationSettings, LLMProvider
 from nanobot.providers.fallback_provider import FallbackProvider
 from nanobot.providers.registry import ProviderSpec, create_dynamic_spec, find_by_name
@@ -19,6 +19,16 @@ class ProviderSnapshot:
     signature: tuple[object, ...]
     generation: GenerationSettings | None = None
     model_preset: str | None = None
+    supports_image_input: bool | None = None
+
+
+@dataclass(frozen=True)
+class _ProviderSetup:
+    model: str
+    provider_name: str
+    provider_config: ProviderConfig | None
+    spec: ProviderSpec | None
+    backend: str
 
 
 def _resolve_model_preset(
@@ -40,20 +50,20 @@ def _provider_extra_headers(
     return headers or None
 
 
-def _make_provider_core(
+def _resolve_provider_setup(
     config: Config,
     *,
-    preset_name: str | None = None,
+    preset: ModelPresetConfig,
-    preset: ModelPresetConfig | None = None,
     model: str | None = None,
-) -> LLMProvider:
+) -> _ProviderSetup:
-    """Create a plain LLM provider without failover wrapping."""
+    """Resolve and validate provider configuration without constructing a client."""
-    resolved = _resolve_model_preset(config, preset_name=preset_name, preset=preset)
+    model = model or preset.model
-    model = model or resolved.model
+    provider_name = config.get_provider_name(model, preset=preset)
-    provider_name = config.get_provider_name(model, preset=resolved)
+    p = config.get_provider(model, preset=preset)
-    p = config.get_provider(model, preset=resolved)
+    if not provider_name:
-    spec = find_by_name(provider_name) if provider_name else None
+        raise ValueError(f"No provider is configured for model '{model}'.")
-    if provider_name and not spec and p:
+    spec = find_by_name(provider_name)
+    if not spec and p:
         if not p.api_base:
             raise ValueError(f"Provider '{provider_name}' requires api_base in config.")
         spec = create_dynamic_spec(
@@ -81,12 +91,57 @@ def _make_provider_core(
         and not (p and p.api_base)
     ):
         raise ValueError(f"Provider '{provider_name}' requires api_base in config.")
-    elif backend == "openai_compat" and not model.startswith("bedrock/"):
+    elif backend in {"anthropic", "openai_compat"} and not (
+        backend == "openai_compat" and model.startswith("bedrock/")
+    ):
         needs_key = not (p and p.api_key)
         exempt = spec and (spec.is_oauth or spec.is_local or spec.is_direct)
         if needs_key and not exempt:
             raise ValueError(f"No API key configured for provider '{provider_name}'.")
 
+    return _ProviderSetup(
+        model=model,
+        provider_name=provider_name,
+        provider_config=p,
+        spec=spec,
+        backend=backend,
+    )
+
+
+def validate_provider_setup(
+    config: Config,
+    *,
+    preset_name: str | None = None,
+    preset: ModelPresetConfig | None = None,
+    model: str | None = None,
+) -> None:
+    """Validate local provider/model settings without loading a provider client."""
+    resolved = _resolve_model_preset(config, preset_name=preset_name, preset=preset)
+    _resolve_provider_setup(
+        config,
+        preset=resolved,
+        model=model,
+    )
+
+
+def _make_provider_core(
+    config: Config,
+    *,
+    preset: ModelPresetConfig,
+    model: str | None = None,
+) -> LLMProvider:
+    """Create a plain LLM provider without failover wrapping."""
+    setup = _resolve_provider_setup(
+        config,
+        preset=preset,
+        model=model,
+    )
+    model = setup.model
+    provider_name = setup.provider_name
+    p = setup.provider_config
+    spec = setup.spec
+    backend = setup.backend
+
     if backend == "openai_codex":
         from nanobot.providers.openai_codex_provider import OpenAICodexProvider
 
@@ -120,7 +175,7 @@ def _make_provider_core(
 
         provider = AnthropicProvider(
             api_key=p.api_key if p else None,
-            api_base=config.get_api_base(model, preset=resolved),
+            api_base=config.get_api_base(model, preset=preset),
             default_model=model,
             extra_headers=_provider_extra_headers(spec, p),
         )
@@ -140,7 +195,7 @@ def _make_provider_core(
 
         provider = OpenAICompatProvider(
             api_key=p.api_key if p else None,
-            api_base=config.get_api_base(model, preset=resolved),
+            api_base=config.get_api_base(model, preset=preset),
             default_model=model,
             extra_headers=_provider_extra_headers(spec, p),
             spec=spec,
@@ -150,38 +205,16 @@ def _make_provider_core(
             proxy=p.proxy if p else None,
         )
 
-    provider.generation = resolved.to_generation_settings()
+    provider.generation = preset.to_generation_settings()
+    provider.supports_image_input = preset.supports_image_input
     return provider
 
 
-def _inline_fallback_preset(
+def _resolve_fallback_presets(config: Config, _primary: ModelPresetConfig) -> list[ModelPresetConfig]:
-    primary: ModelPresetConfig,
+    return [
-    fallback: InlineFallbackConfig,
+        config.model_presets[name]
-) -> ModelPresetConfig:
+        for name in config.agents.defaults.fallback_models
-    return ModelPresetConfig(
+    ]
-        model=fallback.model,
-        provider=fallback.provider,
-        max_tokens=fallback.max_tokens if fallback.max_tokens is not None else primary.max_tokens,
-        context_window_tokens=(
-            fallback.context_window_tokens
-            if fallback.context_window_tokens is not None
-            else primary.context_window_tokens
-        ),
-        temperature=(
-            fallback.temperature if fallback.temperature is not None else primary.temperature
-        ),
-        reasoning_effort=fallback.reasoning_effort,
-    )
-
-
-def _resolve_fallback_presets(config: Config, primary: ModelPresetConfig) -> list[ModelPresetConfig]:
-    presets: list[ModelPresetConfig] = []
-    for fallback in config.agents.defaults.fallback_models:
-        if isinstance(fallback, str):
-            presets.append(config.model_presets[fallback])
-        else:
-            presets.append(_inline_fallback_preset(primary, fallback))
-    return presets
 
 
 def make_provider(
@@ -197,16 +230,14 @@ def make_provider(
     the failover path to create providers for fallback models.
     """
     resolved = _resolve_model_preset(config, preset_name=preset_name, preset=preset)
-    provider = _make_provider_core(config, preset_name=preset_name, preset=preset, model=model)
+    provider = _make_provider_core(config, preset=resolved, model=model)
     fallback_presets = _resolve_fallback_presets(config, resolved)
 
     if fallback_presets:
         provider = FallbackProvider(
             primary=provider,
             fallback_presets=fallback_presets,
-            provider_factory=lambda fb: _make_provider_core(
+            provider_factory=lambda fb: _make_provider_core(config, preset=fb),
-                config, preset_name=preset_name, preset=fb
-            ),
         )
 
     return provider
@@ -225,6 +256,7 @@ def build_unconfigured_provider_snapshot(config: Config, setup_error: str) -> Pr
         context_window_tokens=preset.context_window_tokens,
         signature=("unconfigured", setup_error, preset.model),
         generation=provider.generation,
+        supports_image_input=preset.supports_image_input,
     )
 
 
@@ -258,6 +290,7 @@ def provider_signature(
             fallback.temperature,
             fallback.reasoning_effort,
             fallback.context_window_tokens,
+            fallback.supports_image_input,
             getattr(fp, "proxy", None) if fp else None,
             fp.thinking_style if fp else None,
         )
@@ -279,6 +312,7 @@ def provider_signature(
         resolved.temperature,
         resolved.reasoning_effort,
         resolved.context_window_tokens,
+        resolved.supports_image_input,
         getattr(p, "proxy", None) if p else None,
         p.thinking_style if p else None,
         tuple(_fallback_signature(fallback) for fallback in fallback_presets),
@@ -308,6 +342,7 @@ def build_provider_snapshot(
         signature=provider_signature(config, preset=resolved),
         generation=resolved.to_generation_settings(),
         model_preset=selected_preset,
+        supports_image_input=resolved.supports_image_input,
     )
 
 
@@ -319,6 +354,9 @@ def load_provider_snapshot(
     from nanobot.config.loader import load_config, resolve_config_env_vars
 
     return build_provider_snapshot(
-        resolve_config_env_vars(load_config(config_path)),
+        resolve_config_env_vars(
+            load_config(config_path),
+            config_path=config_path,
+        ),
         preset_name=preset_name,
     )

nanobot/providers/fallback_provider.py

@@ -13,7 +13,6 @@ from nanobot.providers.base import LLMProvider, LLMResponse
 # Circuit breaker tuned to match OpenAICompatProvider's Responses API breaker.
 _PRIMARY_FAILURE_THRESHOLD = 3
 _PRIMARY_COOLDOWN_S = 60
-_MISSING = object()
 _FALLBACK_ERROR_KINDS = frozenset({
     "timeout",
     "connection",
@@ -118,6 +117,9 @@ class FallbackProvider(LLMProvider):
         self._provider_factory = provider_factory
         self._fallback_model_observer = fallback_model_observer
         self._has_fallbacks = bool(fallback_presets)
+        # Candidate-specific image policy is applied inside _try_with_fallback;
+        # the outer retry wrapper preserves canonical images for the chain.
+        self.supports_image_input = getattr(primary, "supports_image_input", None)
         self._primary_failures = 0
         self._primary_tripped_at: float | None = None
 
@@ -140,6 +142,19 @@ class FallbackProvider(LLMProvider):
     def supports_progress_deltas(self) -> bool:
         return bool(getattr(self._primary, "supports_progress_deltas", False))
 
+    def _outer_image_capability(
+        self,
+        supports_image_input: bool | None,
+    ) -> bool | None:
+        """Keep canonical images intact until each candidate applies its policy."""
+        return True
+
+    def _image_policy_request_kwargs(
+        self,
+        supports_image_input: bool | None,
+    ) -> dict[str, Any]:
+        return {"_primary_supports_image_input": supports_image_input}
+
     def _primary_available(self) -> bool:
         """Return True if the primary provider is not currently tripped."""
         if self._primary_tripped_at is None:
@@ -150,16 +165,39 @@ class FallbackProvider(LLMProvider):
         return False
 
     async def chat(self, **kwargs: Any) -> LLMResponse:
+        primary_supports_image_input = kwargs.pop(
+            "_primary_supports_image_input",
+            getattr(self._primary, "supports_image_input", None),
+        )
         if not self._has_fallbacks:
-            return await self._primary.chat(**kwargs)
+            return await self._call_with_image_policy(
+                lambda p, kw: p.chat(**kw),
+                self._primary,
+                kwargs,
+                has_streamed=None,
+                supports_image_input=primary_supports_image_input,
+            )
         return await self._try_with_fallback(
-            lambda p, kw: p.chat(**kw), kwargs, has_streamed=None
+            lambda p, kw: p.chat(**kw),
+            kwargs,
+            has_streamed=None,
+            primary_supports_image_input=primary_supports_image_input,
         )
 
     async def chat_stream(self, **kwargs: Any) -> LLMResponse:
         on_stream_recover = kwargs.pop("on_stream_recover", None)
+        primary_supports_image_input = kwargs.pop(
+            "_primary_supports_image_input",
+            getattr(self._primary, "supports_image_input", None),
+        )
         if not self._has_fallbacks:
-            return await self._primary.chat_stream(**kwargs)
+            return await self._call_with_image_policy(
+                lambda p, kw: p.chat_stream(**kw),
+                self._primary,
+                kwargs,
+                has_streamed=None,
+                supports_image_input=primary_supports_image_input,
+            )
 
         has_streamed: list[bool] = [False]
         original_delta = kwargs.get("on_content_delta")
@@ -176,6 +214,7 @@ class FallbackProvider(LLMProvider):
             kwargs,
             has_streamed=has_streamed,
             on_stream_recover=on_stream_recover,
+            primary_supports_image_input=primary_supports_image_input,
         )
 
     async def _try_with_fallback(
@@ -184,6 +223,7 @@ class FallbackProvider(LLMProvider):
         kwargs: dict[str, Any],
         has_streamed: list[bool] | None,
         on_stream_recover: Callable[[], Awaitable[None]] | None = None,
+        primary_supports_image_input: bool | None | object = LLMProvider._SENTINEL,
     ) -> LLMResponse:
         primary_model = kwargs.get("model") or self._primary.get_default_model()
         primary_was_attempted = False
@@ -191,7 +231,13 @@ class FallbackProvider(LLMProvider):
 
         if self._primary_available():
             primary_was_attempted = True
-            response = await call(self._primary, kwargs)
+            response = await self._call_with_image_policy(
+                call,
+                self._primary,
+                kwargs,
+                has_streamed=has_streamed,
+                supports_image_input=primary_supports_image_input,
+            )
             if response.finish_reason != "error":
                 self._primary_failures = 0
                 self._primary_tripped_at = None
@@ -217,7 +263,8 @@ class FallbackProvider(LLMProvider):
                     )
                     return response
 
-            if not self._should_fallback(response):
+            image_rejected = self._primary._is_image_unsupported_response(response)
+            if not image_rejected and not self._should_fallback(response):
                 logger.warning(
                     "Primary model '{}' returned non-fallbackable error: {}",
                     primary_model,
@@ -225,13 +272,14 @@ class FallbackProvider(LLMProvider):
                 )
                 return response
 
-            self._primary_failures += 1
+            if not image_rejected:
-            if self._primary_failures >= _PRIMARY_FAILURE_THRESHOLD:
+                self._primary_failures += 1
-                self._primary_tripped_at = time.monotonic()
+                if self._primary_failures >= _PRIMARY_FAILURE_THRESHOLD:
-                logger.warning(
+                    self._primary_tripped_at = time.monotonic()
-                    "Primary model '{}' circuit open after {} consecutive failures",
+                    logger.warning(
-                    primary_model, self._primary_failures,
+                        "Primary model '{}' circuit open after {} consecutive failures",
-                )
+                        primary_model, self._primary_failures,
+                    )
         else:
             logger.debug("Primary model '{}' circuit open; skipping", primary_model)
 
@@ -271,6 +319,7 @@ class FallbackProvider(LLMProvider):
                 )
             try:
                 fallback_provider = self._provider_factory(fallback)
+                fallback_provider.supports_image_input = fallback.supports_image_input
             except Exception as exc:
                 logger.warning(
                     "Failed to create provider for fallback '{}': {}", fallback_model, exc
@@ -279,25 +328,23 @@ class FallbackProvider(LLMProvider):
 
             await self._notify_fallback_model(fallback_model)
 
-            original_values = {
+            fallback_kwargs = {
-                name: kwargs.get(name, _MISSING)
+                **kwargs,
-                for name in ("model", "max_tokens", "temperature", "reasoning_effort")
+                "model": fallback_model,
+                "max_tokens": fallback.max_tokens,
+                "temperature": fallback.temperature,
             }
-            kwargs["model"] = fallback_model
-            kwargs["max_tokens"] = fallback.max_tokens
-            kwargs["temperature"] = fallback.temperature
             if fallback.reasoning_effort is None:
-                kwargs.pop("reasoning_effort", None)
+                fallback_kwargs.pop("reasoning_effort", None)
             else:
-                kwargs["reasoning_effort"] = fallback.reasoning_effort
+                fallback_kwargs["reasoning_effort"] = fallback.reasoning_effort
-            try:
+            fallback_response = await self._call_with_image_policy(
-                fallback_response = await call(fallback_provider, kwargs)
+                call,
-            finally:
+                fallback_provider,
-                for name, value in original_values.items():
+                fallback_kwargs,
-                    if value is _MISSING:
+                has_streamed=has_streamed,
-                        kwargs.pop(name, None)
+                supports_image_input=fallback.supports_image_input,
-                    else:
+            )
-                        kwargs[name] = value
 
             if fallback_response.finish_reason != "error":
                 logger.info(
@@ -326,6 +373,49 @@ class FallbackProvider(LLMProvider):
             finish_reason="error",
         )
 
+    @staticmethod
+    async def _call_with_image_policy(
+        call: Callable[[LLMProvider, dict[str, Any]], Awaitable[LLMResponse]],
+        provider: LLMProvider,
+        kwargs: dict[str, Any],
+        *,
+        has_streamed: list[bool] | None,
+        supports_image_input: bool | None | object = LLMProvider._SENTINEL,
+    ) -> LLMResponse:
+        original_messages = kwargs.get("messages")
+        if not isinstance(original_messages, list):
+            return await call(provider, kwargs)
+
+        prepared_kwargs = dict(kwargs)
+        prepared_kwargs["messages"] = provider._messages_for_image_capability(
+            original_messages,
+            supports_image_input=supports_image_input,
+        )
+        response = await call(provider, prepared_kwargs)
+        capability = (
+            provider.supports_image_input
+            if supports_image_input is LLMProvider._SENTINEL
+            else supports_image_input
+        )
+        if (
+            capability is None
+            and provider._is_image_unsupported_response(response)
+            and (has_streamed is None or not has_streamed[0])
+        ):
+            stripped = provider._strip_image_content(original_messages)
+            if stripped is not None and stripped != prepared_kwargs["messages"]:
+                logger.warning(
+                    "Fallback candidate '{}' rejected image input, retrying without images",
+                    prepared_kwargs.get("model") or provider.get_default_model(),
+                )
+                retry_kwargs = dict(prepared_kwargs)
+                retry_kwargs["messages"] = stripped
+                retry_response = await call(provider, retry_kwargs)
+                if retry_response.finish_reason != "error":
+                    provider._strip_image_content_inplace(original_messages)
+                return retry_response
+        return response
+
     async def _notify_fallback_model(self, model: str) -> None:
         if self._fallback_model_observer is None:
             return

nanobot/runtime_context.py

@@ -23,7 +23,10 @@ MAX_WEBUI_QUOTE_CHARS = 4_000
 
 @dataclass(frozen=True)
 class RuntimeContextBlock:
-    """One provider-owned block appended to the current user content."""
+    """Provider-owned context appended verbatim to the current user content.
+
+    Callers must bound and delimit content obtained from untrusted sources.
+    """
 
     source: str
     content: str

nanobot/sdk/clients.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterable, Mapping
+from collections.abc import Awaitable, Callable, Iterable, Mapping
 from copy import deepcopy
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-from nanobot.runtime_context import RUNTIME_CONTEXT_HISTORY_META
+from nanobot.bus.runtime_events import SessionTurnPersisted
+from nanobot.runtime_context import RUNTIME_CONTEXT_HISTORY_META, RuntimeContextProvider
 from nanobot.sdk.types import (
     SessionInfo,
     SessionSnapshot,
@@ -193,6 +194,20 @@ class RuntimeClient:
         """Current runtime workspace."""
         return self._loop.workspace
 
+    def add_context_provider(
+        self,
+        provider: RuntimeContextProvider,
+    ) -> Callable[[], None]:
+        """Register per-turn model context and return an unsubscribe callback."""
+        return self._loop.register_runtime_context_provider(provider)
+
+    def on_session_turn_persisted(
+        self,
+        handler: Callable[[SessionTurnPersisted], Awaitable[None] | None],
+    ) -> Callable[[], None]:
+        """Register a persisted-turn callback and return an unsubscribe callback."""
+        return self._loop.runtime_events.subscribe(handler, SessionTurnPersisted)
+
     async def compact_session(self, session_key: str) -> SessionSnapshot:
         """Run token/replay-window consolidation for one session."""
         session = self._loop.sessions.get_or_create(session_key)

nanobot/sdk/runtime.py

@@ -2,18 +2,10 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import Any
 
 
-def ensure_single_model_selector(
-    *,
-    model: str | None,
-    model_preset: str | None,
-) -> None:
-    if model is not None and model_preset is not None:
-        raise ValueError("model and model_preset are mutually exclusive")
-
-
 def build_process_direct_kwargs(
     *,
     session_key: str,
@@ -22,6 +14,7 @@ def build_process_direct_kwargs(
     sender_id: str,
     media: list[str] | None,
     ephemeral: bool,
+    attributes: Mapping[str, Any] | None = None,
     on_stream: Any | None = None,
     on_stream_end: Any | None = None,
 ) -> dict[str, Any]:
@@ -37,6 +30,8 @@ def build_process_direct_kwargs(
     if ephemeral:
         kwargs["ephemeral"] = True
         kwargs["_run_extra_hooks_for_ephemeral"] = True
+    if attributes is not None:
+        kwargs["attributes"] = dict(attributes)
     if on_stream is not None:
         kwargs["on_stream"] = on_stream
     if on_stream_end is not None:

nanobot/session/manager.py

@@ -22,10 +22,10 @@ from nanobot.runtime_context import (
     public_history_message,
 )
 from nanobot.utils.helpers import (
+    content_with_media_breadcrumbs,
     ensure_dir,
     estimate_message_tokens,
     find_legal_message_start,
-    image_placeholder_text,
     recent_message_start_index,
     safe_filename,
     strip_think,
@@ -165,6 +165,7 @@ class Session:
         max_tokens: int = 0,
         extend_to_user: bool = False,
         include_runtime_context: bool = True,
+        include_media: bool = False,
     ) -> list[dict[str, Any]]:
         """Return unconsolidated messages for LLM input.
 
@@ -209,17 +210,17 @@ class Session:
             role = message.get("role")
             if role == "assistant" and isinstance(content, str):
                 content = _sanitize_assistant_replay_text(content)
-            # Synthesize an ``[image: path]`` breadcrumb from the persisted
-            # ``media`` kwarg so LLM replay still sees *something* where the
-            # image used to be. Without this, an image-only user turn
-            # replays as an empty user message — the assistant's reply then
-            # looks like it's responding to nothing.
             media = message.get("media")
-            if role == "user" and isinstance(media, list) and media and isinstance(content, str):
+            media_paths = (
-                breadcrumbs = "\n".join(
+                [path for path in media if isinstance(path, str) and path]
-                    image_placeholder_text(p) for p in media if isinstance(p, str) and p
+                if role == "user" and isinstance(media, list)
-                )
+                else []
-                content = f"{content}\n{breadcrumbs}" if content else breadcrumbs
+            )
+            # General history consumers retain a compact breadcrumb. The agent
+            # loop asks for internal media refs and deterministically rebuilds
+            # image blocks at the request boundary.
+            if media_paths and not include_media:
+                content = content_with_media_breadcrumbs(role, content, media_paths)
             cli_apps = message.get("cli_apps")
             if (
                 include_runtime_context
@@ -248,6 +249,11 @@ class Session:
                 if not any(key in message for key in ("tool_calls", "reasoning_content", "thinking_blocks")):
                     continue
             entry: dict[str, Any] = {"role": message["role"], "content": content}
+            if media_paths and include_media:
+                entry["_media_paths"] = media_paths
+                runtime_context = message.get(RUNTIME_CONTEXT_HISTORY_META)
+                if isinstance(runtime_context, dict):
+                    entry[RUNTIME_CONTEXT_HISTORY_META] = deepcopy(runtime_context)
             for key in ("tool_calls", "tool_call_id", "name", "reasoning_content", "thinking_blocks"):
                 if key in message:
                     entry[key] = message[key]

nanobot/session/webui_turns.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import re
 import time
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass, field, replace
+from dataclasses import dataclass, replace
 from typing import Any
 from uuid import uuid4
 
@@ -42,7 +42,10 @@ from nanobot.session.history_visibility import is_hidden_history_message
 from nanobot.session.manager import Session, SessionManager
 from nanobot.utils.helpers import strip_think, truncate_text
 from nanobot.utils.llm_runtime import LLMRuntime
-from nanobot.webui.metadata import WEBUI_TURN_METADATA_KEY
+from nanobot.webui.metadata import (
+    WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_TURN_METADATA_KEY,
+)
 
 WEBUI_SESSION_METADATA_KEY = "webui"
 WEBUI_TITLE_METADATA_KEY = "title"
@@ -51,9 +54,42 @@ TITLE_MAX_CHARS = 60
 TITLE_GENERATION_MAX_TOKENS = 96
 TITLE_GENERATION_REASONING_EFFORT = "none"
 
-# Wall-clock turn start per ``chat_id`` (websocket only). Survives browser refresh while the
+# Latest active turn projection per ``chat_id`` (websocket only). It survives browser refresh
-# gateway process stays up; cleared on idle/stop and implicitly dropped on restart.
+# while the gateway process stays up and is implicitly dropped on restart.
 _WEBSOCKET_TURN_WALL_STARTED_AT: dict[str, float] = {}
+_WEBSOCKET_TURN_IDS: dict[str, str] = {}
+_WEBSOCKET_TURN_OWNERS: dict[str, str] = {}
+
+
+@dataclass(frozen=True)
+class _WebsocketTurn:
+    started_at: float
+    turn_id: str | None
+    transcript_persistence_failed: bool = False
+
+
+# All in-flight lifecycle owners per chat, in admission order. The three maps
+# above remain the latest-owner projection consumed by the HTTP API.
+_WEBSOCKET_ACTIVE_TURNS: dict[str, dict[str, _WebsocketTurn]] = {}
+
+
+def _sync_websocket_turn_projection(chat_id: str) -> None:
+    turns = _WEBSOCKET_ACTIVE_TURNS.get(chat_id)
+    if not turns:
+        _WEBSOCKET_ACTIVE_TURNS.pop(chat_id, None)
+        _WEBSOCKET_TURN_WALL_STARTED_AT.pop(chat_id, None)
+        _WEBSOCKET_TURN_IDS.pop(chat_id, None)
+        _WEBSOCKET_TURN_OWNERS.pop(chat_id, None)
+        return
+
+    owner = next(reversed(turns))
+    turn = turns[owner]
+    _WEBSOCKET_TURN_WALL_STARTED_AT[chat_id] = turn.started_at
+    _WEBSOCKET_TURN_OWNERS[chat_id] = owner
+    if turn.turn_id is None:
+        _WEBSOCKET_TURN_IDS.pop(chat_id, None)
+    else:
+        _WEBSOCKET_TURN_IDS[chat_id] = turn.turn_id
 
 
 def mark_webui_session(session: Session, metadata: dict[str, Any]) -> bool:
@@ -203,6 +239,96 @@ def websocket_turn_wall_started_at(chat_id: str) -> float | None:
     return _WEBSOCKET_TURN_WALL_STARTED_AT.get(chat_id)
 
 
+def websocket_turn_id(chat_id: str) -> str | None:
+    """Return the WebUI identity of the active turn, when one was provided."""
+    return _WEBSOCKET_TURN_IDS.get(chat_id)
+
+
+def register_queued_websocket_turn_if_idle(
+    chat_id: str,
+    turn_id: str | None,
+) -> str | None:
+    """Track an accepted WebUI turn while it waits for AgentLoop admission."""
+    if websocket_turn_wall_started_at(chat_id) is not None:
+        return None
+    owner = uuid4().hex
+    _WEBSOCKET_ACTIVE_TURNS.setdefault(chat_id, {})[owner] = _WebsocketTurn(
+        started_at=time.time(),
+        turn_id=turn_id,
+    )
+    _sync_websocket_turn_projection(chat_id)
+    return owner
+
+
+def websocket_turn_owner_is_registered(
+    chat_id: str,
+    owner: str,
+    turn_id: str | None,
+) -> bool:
+    """Return whether websocket ingress registered this owner for the turn."""
+    turn = _WEBSOCKET_ACTIVE_TURNS.get(chat_id, {}).get(owner)
+    return turn is not None and turn.turn_id == turn_id
+
+
+def websocket_turn_transcript_persistence_failed(
+    chat_id: str,
+    owner: str | None = None,
+) -> bool:
+    """Return whether one active owner has an incomplete canonical transcript."""
+    turns = _WEBSOCKET_ACTIVE_TURNS.get(chat_id)
+    if not turns:
+        return False
+    selected_owner = owner or next(reversed(turns))
+    turn = turns.get(selected_owner)
+    return turn.transcript_persistence_failed if turn is not None else False
+
+
+def mark_websocket_turn_transcript_persistence_failed(
+    chat_id: str,
+    owner: str | None,
+) -> bool:
+    """Keep a turn active when any canonical display event could not be written."""
+    if not owner:
+        return False
+    turns = _WEBSOCKET_ACTIVE_TURNS.get(chat_id)
+    if turns is None or owner not in turns:
+        return False
+    turns[owner] = replace(turns[owner], transcript_persistence_failed=True)
+    return True
+
+
+def clear_websocket_turn_if_current(
+    chat_id: str,
+    owner: str | None,
+    *,
+    preserve_persistence_failure: bool = False,
+) -> bool:
+    """Clear one lifecycle owner without disturbing concurrent turns for the chat."""
+    if not owner:
+        return False
+    turns = _WEBSOCKET_ACTIVE_TURNS.get(chat_id)
+    if turns is not None:
+        if owner not in turns:
+            return False
+        if preserve_persistence_failure and turns[owner].transcript_persistence_failed:
+            return False
+        turns.pop(owner)
+        _sync_websocket_turn_projection(chat_id)
+        return True
+
+    # Compatibility for callers/tests that populated the legacy projection
+    # directly before the multi-owner registry existed.
+    if (
+        chat_id in _WEBSOCKET_TURN_WALL_STARTED_AT
+        and _WEBSOCKET_TURN_OWNERS.get(chat_id) == owner
+    ):
+        _WEBSOCKET_TURN_WALL_STARTED_AT.pop(chat_id, None)
+        _WEBSOCKET_TURN_IDS.pop(chat_id, None)
+        _WEBSOCKET_TURN_OWNERS.pop(chat_id, None)
+        return True
+    return False
+
+
 def build_bus_progress_callback(
     bus: MessageBus,
     msg: InboundMessage,
@@ -229,9 +355,17 @@ async def publish_turn_run_status(
         else:
             t0 = time.time()
         started_at_event = t0
-        _WEBSOCKET_TURN_WALL_STARTED_AT[cid] = t0
+        owner = msg.metadata.get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
-    else:
+        if not isinstance(owner, str) or not owner:
-        _WEBSOCKET_TURN_WALL_STARTED_AT.pop(cid, None)
+            owner = uuid4().hex
+            msg.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] = owner
+        turn_id = msg.metadata.get(WEBUI_TURN_METADATA_KEY)
+        current_turn_id = turn_id if isinstance(turn_id, str) and turn_id else None
+        turns = _WEBSOCKET_ACTIVE_TURNS.setdefault(cid, {})
+        # Re-registration makes this owner the latest projection.
+        turns.pop(owner, None)
+        turns[owner] = _WebsocketTurn(started_at=t0, turn_id=current_turn_id)
+        _sync_websocket_turn_projection(cid)
     await bus.publish_outbound(
         outbound_message_for_event(
             channel=msg.channel,
@@ -254,25 +388,50 @@ class WebuiTurnRoutePolicy:
         route: TurnRoute,
     ) -> TurnRoute:
         """Make an independently dispatched late subagent result visible in WebUI."""
+        routed = route
         if (
-            msg.channel != "system"
+            msg.channel == "system"
-            or msg.sender_id != "subagent"
+            and msg.sender_id == "subagent"
-            or msg.metadata.get("injected_event") != "subagent_result"
+            and msg.metadata.get("injected_event") == "subagent_result"
-            or route.channel != "websocket"
+            and route.channel == "websocket"
         ):
-            return route
+            session = self.sessions.get_or_create(session_key)
+            if session.metadata.get(WEBUI_SESSION_METADATA_KEY) is True:
+                metadata = dict(route.metadata)
+                metadata.update({
+                    WEBUI_SESSION_METADATA_KEY: True,
+                    "_wants_stream": True,
+                    WEBUI_TURN_METADATA_KEY: f"subagent:{uuid4().hex}",
+                })
+                routed = replace(route, metadata=metadata, publish_lifecycle=True)
 
-        session = self.sessions.get_or_create(session_key)
+        if routed.channel == "websocket" and routed.publish_lifecycle:
-        if session.metadata.get(WEBUI_SESSION_METADATA_KEY) is not True:
+            metadata = dict(routed.metadata)
-            return route
+            turn_id = metadata.get(WEBUI_TURN_METADATA_KEY)
+            current_turn_id = turn_id if isinstance(turn_id, str) and turn_id else None
+            queued_owner = metadata.get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+            owner = (
+                queued_owner
+                if (
+                    msg.channel == "websocket"
+                    and isinstance(queued_owner, str)
+                    and websocket_turn_owner_is_registered(
+                        str(msg.chat_id),
+                        queued_owner,
+                        current_turn_id,
+                    )
+                )
+                else uuid4().hex
+            )
+            metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] = owner
+            routed = replace(routed, metadata=metadata)
+            # Direct websocket turns publish their final idle transition from
+            # the original input message. Carry the same server-owned identity
+            # there, overwriting any untrusted client-supplied value.
+            if msg.channel == "websocket":
+                msg.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY] = owner
 
-        metadata = dict(route.metadata)
+        return routed
-        metadata.update({
-            WEBUI_SESSION_METADATA_KEY: True,
-            "_wants_stream": True,
-            WEBUI_TURN_METADATA_KEY: f"subagent:{uuid4().hex}",
-        })
-        return replace(route, metadata=metadata, publish_lifecycle=True)
 
 
 def build_webui_fallback_model_observer(bus: MessageBus) -> FallbackModelObserver:
@@ -304,7 +463,6 @@ class WebuiTurnCoordinator:
     bus: MessageBus
     sessions: SessionManager
     schedule_background: Callable[[Awaitable[None]], None]
-    _title_contexts: dict[str, LLMRuntime] = field(default_factory=dict)
 
     def subscribe(self, runtime_events: RuntimeEventBus) -> Callable[[], None]:
         """Subscribe this coordinator to runtime events."""
@@ -408,18 +566,6 @@ class WebuiTurnCoordinator:
             )
         )
 
-    def capture_title_context(
-        self,
-        session_key: str,
-        msg: InboundMessage,
-        llm: LLMRuntime,
-    ) -> None:
-        if msg.channel == "websocket" and msg.metadata.get("webui") is True:
-            self._title_contexts[session_key] = llm
-
-    def discard(self, session_key: str) -> None:
-        self._title_contexts.pop(session_key, None)
-
     async def publish_run_status(
         self,
         msg: InboundMessage,
@@ -451,32 +597,6 @@ class WebuiTurnCoordinator:
                 metadata=msg.metadata,
             )
         )
-        self._schedule_title_update(msg, session_key=session_key)
-
-    def _schedule_title_update(self, msg: InboundMessage, *, session_key: str) -> None:
-        title_context = self._title_contexts.pop(session_key, None)
-        if msg.metadata.get("webui") is not True or title_context is None:
-            return
-
-        async def _generate_title_and_notify(
-            title_llm: LLMRuntime = title_context,
-        ) -> None:
-            generated = await maybe_generate_webui_title_after_turn(
-                channel=msg.channel,
-                metadata=msg.metadata,
-                sessions=self.sessions,
-                session_key=session_key,
-                provider=title_llm.provider,
-                model=title_llm.model,
-            )
-            if generated:
-                await self._publish_session_metadata_updated(
-                    channel=msg.channel,
-                    chat_id=msg.chat_id,
-                    metadata=msg.metadata,
-                )
-
-        self.schedule_background(_generate_title_and_notify())
 
     def _schedule_title_update_from_event(self, event: TurnCompleted) -> None:
         title_context = event.runtime

nanobot/utils/document.py

@@ -431,7 +431,7 @@ def _is_text_extension(ext: str) -> bool:
 
 
 # ---------------------------------------------------------------------------
-# High-level helper: split media into images + extracted document text
+# High-level helper: split images from on-demand attachment references
 # ---------------------------------------------------------------------------
 
 
@@ -454,17 +454,31 @@ def is_image_file(path: str) -> bool:
     return bool(mime and mime.startswith("image/"))
 
 
+def _canonical_local_media_path(path: str) -> str:
+    """Return an existing local media file as an absolute path."""
+    try:
+        candidate = Path(path).expanduser()
+        if candidate.is_file():
+            return str(candidate.resolve(strict=False))
+    except (OSError, RuntimeError, TypeError, ValueError):
+        pass
+    return path
+
+
 def reference_non_image_attachments(
     content: str, media: list[str],
 ) -> tuple[str, list[str]]:
-    """Separate images from non-image attachments without reading file content.
+    """Reference 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.
+    Non-image paths are appended as ``[Attachment: path]`` references so the
+    model can inspect them on demand with ``read_file`` or pass the original
+    path to another tool that needs exact file bytes.
     """
     image_paths: list[str] = []
     attachment_refs: list[str] = []
     for path in media:
+        path = _canonical_local_media_path(path)
         if is_image_file(path):
             image_paths.append(path)
         else:
@@ -473,51 +487,3 @@ def reference_non_image_attachments(
         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],
-    *,
-    max_file_size: int = _MAX_EXTRACT_FILE_SIZE,
-) -> tuple[str, list[str]]:
-    """Separate images from documents in *media_paths*.
-
-    Documents (PDF, DOCX, XLSX, PPTX, plain-text, …) have their text
-    extracted and appended to *text*.  Only image paths are kept in the
-    returned list so that downstream layers only need to handle vision
-    blocks.
-
-    Files larger than *max_file_size* bytes are skipped with a warning
-    to avoid unbounded memory / CPU usage.
-    """
-    image_paths: list[str] = []
-    doc_texts: list[str] = []
-
-    for path_str in media_paths:
-        p = Path(path_str)
-        if not p.is_file():
-            continue
-
-        try:
-            size = p.stat().st_size
-        except OSError:
-            continue
-        if size > max_file_size:
-            logger.warning(
-                "Skipping oversized file for extraction: {} ({:.1f} MB > {} MB limit)",
-                p.name, size / (1024 * 1024), max_file_size // (1024 * 1024),
-            )
-            continue
-
-        if is_image_file(path_str):
-            image_paths.append(path_str)
-        else:
-            extracted = extract_text(p)
-            if extracted and not extracted.startswith("[error:"):
-                doc_texts.append(f"[File: {p.name}]\n{extracted}")
-
-    if doc_texts:
-        text = text + "\n\n" + "\n\n".join(doc_texts)
-
-    return text, image_paths

nanobot/utils/helpers.py

@@ -367,6 +367,24 @@ def image_placeholder_text(path: str | None, *, empty: str = "[image]") -> str:
     return f"[image: {path}]" if path else empty
 
 
+def content_with_media_breadcrumbs(
+    role: object,
+    content: object,
+    media: object,
+) -> object:
+    """Append persisted media paths to user text using the canonical breadcrumb."""
+    if role != "user" or not isinstance(content, str) or not isinstance(media, list):
+        return content
+    breadcrumbs = "\n".join(
+        image_placeholder_text(path)
+        for path in media
+        if isinstance(path, str) and path
+    )
+    if not breadcrumbs:
+        return content
+    return f"{content}\n{breadcrumbs}" if content else breadcrumbs
+
+
 def truncate_text(text: str, max_chars: int) -> str:
     """Truncate text with a stable suffix."""
     if max_chars <= 0 or len(text) <= max_chars:

nanobot/utils/llm_runtime.py

@@ -10,6 +10,8 @@ from nanobot.providers.base import GenerationSettings, LLMProvider
 if TYPE_CHECKING:
     from nanobot.providers.factory import ProviderSnapshot
 
+_IMAGE_CAPABILITY_UNSET = object()
+
 
 @dataclass(frozen=True, slots=True)
 class LLMRuntime:
@@ -26,6 +28,7 @@ class LLMRuntime:
     context_window_tokens: int
     model_preset: str | None = None
     snapshot_signature: tuple[object, ...] | None = None
+    supports_image_input: bool | None = None
 
     @classmethod
     def capture(
@@ -36,10 +39,18 @@ class LLMRuntime:
         context_window_tokens: int,
         model_preset: str | None = None,
         snapshot_signature: tuple[object, ...] | None = None,
+        supports_image_input: bool | None | object = _IMAGE_CAPABILITY_UNSET,
     ) -> LLMRuntime:
         """Capture provider defaults without retaining mutable generation state."""
         defaults = GenerationSettings()
         generation = getattr(provider, "generation", defaults)
+        provider_image_capability = getattr(provider, "supports_image_input", None)
+        if not (
+            provider_image_capability is True
+            or provider_image_capability is False
+            or provider_image_capability is None
+        ):
+            provider_image_capability = None
         return cls(
             provider=provider,
             model=model,
@@ -55,6 +66,11 @@ class LLMRuntime:
             context_window_tokens=context_window_tokens,
             model_preset=model_preset,
             snapshot_signature=snapshot_signature,
+            supports_image_input=(
+                provider_image_capability
+                if supports_image_input is _IMAGE_CAPABILITY_UNSET
+                else supports_image_input
+            ),
         )
 
     def with_generation_overrides(
@@ -94,6 +110,7 @@ def runtime_from_provider_snapshot(
             context_window_tokens=snapshot.context_window_tokens,
             model_preset=snapshot.model_preset,
             snapshot_signature=snapshot.signature,
+            supports_image_input=snapshot.supports_image_input,
         )
     return LLMRuntime.capture(
         snapshot.provider,
@@ -101,4 +118,5 @@ def runtime_from_provider_snapshot(
         context_window_tokens=snapshot.context_window_tokens,
         model_preset=snapshot.model_preset,
         snapshot_signature=snapshot.signature,
+        supports_image_input=snapshot.supports_image_input,
     )

nanobot/webui/extensions_routes.py

@@ -1,155 +0,0 @@
-"""Authenticated HTTP adapter for the extension management service."""
-
-from __future__ import annotations
-
-import json
-from collections.abc import Callable
-from typing import Any
-from urllib.parse import unquote
-
-from websockets.http11 import Request as WsRequest
-from websockets.http11 import Response
-
-from nanobot.extensions.service import ExtensionService
-from nanobot.webui.http_utils import is_local_browser_request
-
-_VALUES_HEADER = "X-Nanobot-Extension-Values"
-_VALUES_MAX_BYTES = 32 * 1024
-_ACTION_PATHS = {
-    "/api/extensions/install": "install",
-    "/api/extensions/enable": "enable",
-    "/api/extensions/disable": "disable",
-    "/api/extensions/trust": "trust",
-    "/api/extensions/untrust": "untrust",
-    "/api/extensions/permissions": "permissions",
-    "/api/extensions/uninstall": "uninstall",
-}
-
-
-class WebUIExtensionsRouter:
-    """Keep extension policy and installation outside WebSocket transport."""
-
-    def __init__(
-        self,
-        *,
-        service: ExtensionService | None,
-        check_api_token: Callable[[WsRequest], bool],
-        json_response: Callable[[dict[str, Any]], Response],
-        error_response: Callable[[int, str | None], Response],
-        allow_remote_package_install: bool = False,
-        logger: Any,
-    ) -> None:
-        self._service = service
-        self._check_api_token = check_api_token
-        self._json_response = json_response
-        self._error_response = error_response
-        self._allow_remote_package_install = allow_remote_package_install
-        self._logger = logger
-
-    async def dispatch(
-        self,
-        connection: Any,
-        request: WsRequest,
-        path: str,
-    ) -> Response | None:
-        if not path.startswith("/api/extensions"):
-            return None
-        if not self._check_api_token(request):
-            return self._error_response(401, "Unauthorized")
-        if self._service is None:
-            return self._error_response(503, "Extension service is not available")
-        try:
-            if path == "/api/extensions":
-                if _method(request) != "GET":
-                    return self._error_response(405, "Method not allowed")
-                return self._json_response(await self._service.status())
-            action = _ACTION_PATHS.get(path)
-            if action is None:
-                return None
-            if _method(request) != "POST":
-                return self._error_response(405, "Method not allowed")
-            if not self._mutation_allowed(action, connection, request):
-                return self._error_response(
-                    403,
-                    "Extension changes require a local WebUI connection",
-                )
-            values = self._values(request)
-            if (
-                action == "install"
-                and str(values.get("kind") or "git") == "local"
-                and not is_local_browser_request(connection, request.headers)
-            ):
-                return self._error_response(
-                    403,
-                    "Local extension paths require a local WebUI connection",
-                )
-            return self._json_response(await self._run_action(action, values))
-        except KeyError as exc:
-            return self._error_response(404, str(exc))
-        except ValueError as exc:
-            return self._error_response(400, str(exc))
-        except RuntimeError as exc:
-            return self._error_response(502, str(exc))
-        except Exception:
-            self._logger.exception("extension management request failed")
-            return self._error_response(500, "Extension operation failed")
-
-    async def _run_action(self, action: str, values: dict[str, Any]) -> dict[str, Any]:
-        assert self._service is not None
-        extension_id = str(values.get("id") or "").strip()
-        if action == "install":
-            source = str(values.get("source") or "").strip()
-            if not source:
-                raise ValueError("Missing extension source")
-            return await self._service.install(
-                source,
-                kind=str(values.get("kind") or "git"),
-                ref=str(values.get("ref") or ""),
-                trusted=False,
-            )
-        if not extension_id:
-            raise ValueError("Missing extension ID")
-        if action == "enable":
-            return await self._service.set_enabled(extension_id, True)
-        if action == "disable":
-            return await self._service.set_enabled(extension_id, False)
-        if action == "trust":
-            return await self._service.set_trusted(extension_id, True)
-        if action == "untrust":
-            return await self._service.set_trusted(extension_id, False)
-        if action == "permissions":
-            permissions = values.get("permissions", [])
-            if not isinstance(permissions, list) or not all(
-                isinstance(permission, str) for permission in permissions
-            ):
-                raise ValueError("Extension permissions must be an array of strings")
-            return await self._service.set_permissions(extension_id, set(permissions))
-        return await self._service.uninstall(extension_id)
-
-    def _values(self, request: WsRequest) -> dict[str, Any]:
-        raw = request.headers.get(_VALUES_HEADER)
-        if not raw:
-            return {}
-        if len(raw.encode("utf-8")) > _VALUES_MAX_BYTES:
-            raise ValueError("Extension request is too large")
-        try:
-            value = json.loads(unquote(raw))
-        except json.JSONDecodeError as exc:
-            raise ValueError("Invalid extension request") from exc
-        if not isinstance(value, dict):
-            raise ValueError("Extension request must be a JSON object")
-        return value
-
-    def _mutation_allowed(
-        self,
-        action: str,
-        connection: Any,
-        request: WsRequest,
-    ) -> bool:
-        return is_local_browser_request(connection, request.headers) or (
-            action == "install" and self._allow_remote_package_install
-        )
-
-
-def _method(request: WsRequest) -> str:
-    return str(getattr(request, "method", "GET")).upper()

nanobot/webui/gateway_services.py

@@ -51,8 +51,6 @@ def build_gateway_services(
     local_trigger_pending_ids: Callable[[str], set[str]] | None = None,
     channel_feature_action: Callable[..., Any] | None = None,
     channel_runtime_status: Callable[[], dict[str, Any]] | None = None,
-    extension_service: Any | None = None,
-    allow_remote_package_install: bool = False,
     logger: Any = default_logger,
 ) -> GatewayServices:
     tokens = GatewayTokenStore()
@@ -96,8 +94,6 @@ def build_gateway_services(
         local_trigger_pending_ids=local_trigger_pending_ids,
         channel_feature_action=channel_feature_action,
         channel_runtime_status=channel_runtime_status,
-        extension_service=extension_service,
-        allow_remote_package_install=allow_remote_package_install,
         log=logger,
     )
     return GatewayServices(

nanobot/webui/metadata.py

@@ -1,4 +1,5 @@
 """Shared WebUI metadata keys."""
 
 WEBUI_TURN_METADATA_KEY = "webui_turn_id"
+WEBSOCKET_TURN_OWNER_METADATA_KEY = "_websocket_turn_owner"
 WEBUI_MESSAGE_SOURCE_METADATA_KEY = "_webui_message_source"

nanobot/webui/settings_api.py

@@ -857,6 +857,13 @@ def _parse_bool(value: str, field: str) -> bool:
     return normalized in {"1", "true", "yes"}
 
 
+def _parse_image_input_support(value: str | None) -> bool | None:
+    normalized = (value or "").strip().lower()
+    if normalized in {"", "auto"}:
+        return None
+    return _parse_bool(normalized, "supports_image_input")
+
+
 def _parse_context_window_tokens(value: str | None) -> int | None:
     if value is None:
         return None
@@ -945,28 +952,10 @@ def _provider_display_name_exists(
     return False
 
 
-def _unique_model_configuration_name(config: Any, label: str) -> str:
-    """Return a stable, unused preset name for a migrated model configuration."""
-    try:
-        base = _model_configuration_slug(label)
-    except WebUISettingsError:
-        base = "model"
-    candidate = base
-    suffix = 2
-    while candidate in config.model_presets:
-        candidate = f"{base}-{suffix}"
-        suffix += 1
-    return candidate
-
-
-def _model_configuration_label(model: str) -> str:
-    return model.rsplit("/", 1)[-1] or model
-
-
 def _model_call_order_state(config: Any) -> tuple[list[str], bool]:
     defaults = config.agents.defaults
     primary = defaults.model_preset
-    if not primary or primary == "default" or primary not in config.model_presets:
+    if primary not in config.model_presets:
         return [], False
     order = [primary]
     for fallback in defaults.fallback_models:
@@ -1088,7 +1077,7 @@ def settings_payload(
 ) -> dict[str, Any]:
     config = load_config()
     defaults = config.agents.defaults
-    active_preset_name = defaults.model_preset or "default"
+    active_preset_name = defaults.model_preset
     effective_preset = config.resolve_preset()
 
     provider_name = (
@@ -1132,32 +1121,7 @@ def settings_payload(
         ),
         None,
     )
-    model_presets = [
+    model_presets = []
-        {
-            "name": "default",
-            "label": "Default",
-            "active": active_preset_name == "default",
-            "is_default": True,
-            "model": defaults.model,
-            "provider": defaults.provider,
-            "resolved_provider": config.get_provider_name(
-                defaults.model,
-                preset=config.resolve_default_preset(),
-            ),
-            "max_tokens": defaults.max_tokens,
-            "context_window_tokens": defaults.context_window_tokens,
-            "temperature": defaults.temperature,
-            "reasoning_effort": defaults.reasoning_effort,
-            "reasoning_effort_values": _reasoning_effort_values_for(
-                config.get_provider_name(
-                    defaults.model,
-                    preset=config.resolve_default_preset(),
-                )
-                or defaults.provider,
-                defaults.model,
-            ),
-        }
-    ]
     for name, preset in config.model_presets.items():
         resolved_preset_provider = (
             config.get_provider_name(
@@ -1171,7 +1135,7 @@ def settings_payload(
                 "name": name,
                 "label": preset.label or name,
                 "active": active_preset_name == name,
-                "is_default": False,
+                "is_default": name == "default",
                 "model": preset.model,
                 "provider": preset.provider,
                 "resolved_provider": resolved_preset_provider,
@@ -1179,6 +1143,7 @@ def settings_payload(
                 "context_window_tokens": preset.context_window_tokens,
                 "temperature": preset.temperature,
                 "reasoning_effort": preset.reasoning_effort,
+                "supports_image_input": preset.supports_image_input,
                 "reasoning_effort_values": _reasoning_effort_values_for(
                     resolved_preset_provider, preset.model
                 ),
@@ -1320,13 +1285,14 @@ def settings_usage_payload() -> dict[str, Any]:
 def update_agent_settings(query: QueryParams) -> dict[str, Any]:
     config = load_config()
     defaults = config.agents.defaults
+    default_preset = config.resolve_default_preset()
     changed = False
     restart_required = False
 
     if "model_preset" in query or "modelPreset" in query:
         preset = (_query_first_alias(query, "model_preset", "modelPreset") or "").strip()
-        preset_value = None if not preset or preset == "default" else preset
+        preset_value = preset or "default"
-        if preset_value is not None and preset_value not in config.model_presets:
+        if preset_value not in config.model_presets:
             raise WebUISettingsError("unknown model preset")
         if defaults.model_preset != preset_value:
             defaults.model_preset = preset_value
@@ -1337,8 +1303,8 @@ def update_agent_settings(query: QueryParams) -> dict[str, Any]:
         model = model.strip()
         if not model:
             raise WebUISettingsError("model is required")
-        if defaults.model != model:
+        if default_preset.model != model:
-            defaults.model = model
+            default_preset.model = model
             changed = True
 
     provider = _query_first(query, "provider")
@@ -1347,8 +1313,8 @@ def update_agent_settings(query: QueryParams) -> dict[str, Any]:
         if not provider:
             raise WebUISettingsError("provider is required")
         _validate_configured_provider(config, provider)
-        if defaults.provider != provider:
+        if default_preset.provider != provider:
-            defaults.provider = provider
+            default_preset.provider = provider
             changed = True
 
     context_window_tokens = _parse_context_window_tokens(
@@ -1356,9 +1322,9 @@ def update_agent_settings(query: QueryParams) -> dict[str, Any]:
     )
     if (
         context_window_tokens is not None
-        and defaults.context_window_tokens != context_window_tokens
+        and default_preset.context_window_tokens != context_window_tokens
     ):
-        defaults.context_window_tokens = context_window_tokens
+        default_preset.context_window_tokens = context_window_tokens
         changed = True
 
     timezone = _query_first(query, "timezone")
@@ -1449,6 +1415,9 @@ def create_model_configuration(query: QueryParams) -> dict[str, Any]:
         reasoning_effort = (
             _query_first_alias(query, "reasoning_effort", "reasoningEffort") or ""
         ).strip() or None
+    supports_image_input = _parse_image_input_support(
+        _query_first_alias(query, "supports_image_input", "supportsImageInput")
+    )
     config.model_presets[name] = ModelPresetConfig(
         label=label,
         model=model,
@@ -1461,6 +1430,7 @@ def create_model_configuration(query: QueryParams) -> dict[str, Any]:
         ),
         temperature=temperature if temperature is not None else base.temperature,
         reasoning_effort=reasoning_effort,
+        supports_image_input=supports_image_input,
     )
     save_config(config)
     payload = settings_payload()
@@ -1470,7 +1440,7 @@ def create_model_configuration(query: QueryParams) -> dict[str, Any]:
 
 def update_model_configuration(query: QueryParams) -> dict[str, Any]:
     name = (_query_first(query, "name") or "").strip()
-    if not name or name == "default":
+    if not name:
         raise WebUISettingsError("model configuration is required")
 
     config = load_config()
@@ -1539,6 +1509,14 @@ def update_model_configuration(query: QueryParams) -> dict[str, Any]:
             preset.reasoning_effort = reasoning_effort
             changed = True
 
+    if "supports_image_input" in query or "supportsImageInput" in query:
+        supports_image_input = _parse_image_input_support(
+            _query_first_alias(query, "supports_image_input", "supportsImageInput")
+        )
+        if preset.supports_image_input is not supports_image_input:
+            preset.supports_image_input = supports_image_input
+            changed = True
+
     if changed:
         save_config(config)
     return settings_payload()
@@ -1584,68 +1562,16 @@ def update_model_call_order(query: QueryParams) -> dict[str, Any]:
 
 
 def migrate_model_configurations(_query: QueryParams | None = None) -> dict[str, Any]:
-    """Materialize legacy primary/inline model settings as named presets."""
+    """Compatibility endpoint; loading config now performs this migration."""
-    config = load_config()
-    defaults = config.agents.defaults
-    primary = config.resolve_preset()
-    created: list[str] = []
-
-    if not defaults.model_preset or defaults.model_preset == "default":
-        label = _model_configuration_label(primary.model)
-        name = _unique_model_configuration_name(config, label)
-        config.model_presets[name] = ModelPresetConfig(
-            label=label,
-            model=primary.model,
-            provider=primary.provider,
-            max_tokens=primary.max_tokens,
-            context_window_tokens=primary.context_window_tokens,
-            temperature=primary.temperature,
-            reasoning_effort=primary.reasoning_effort,
-        )
-        defaults.model_preset = name
-        created.append(name)
-
-    fallback_models: list[str] = []
-    for fallback in defaults.fallback_models:
-        if isinstance(fallback, str):
-            fallback_models.append(fallback)
-            continue
-        label = _model_configuration_label(fallback.model)
-        name = _unique_model_configuration_name(config, label)
-        config.model_presets[name] = ModelPresetConfig(
-            label=label,
-            model=fallback.model,
-            provider=fallback.provider,
-            max_tokens=(
-                fallback.max_tokens
-                if fallback.max_tokens is not None
-                else primary.max_tokens
-            ),
-            context_window_tokens=(
-                fallback.context_window_tokens
-                if fallback.context_window_tokens is not None
-                else primary.context_window_tokens
-            ),
-            temperature=(
-                fallback.temperature
-                if fallback.temperature is not None
-                else primary.temperature
-            ),
-            reasoning_effort=fallback.reasoning_effort,
-        )
-        fallback_models.append(name)
-        created.append(name)
-
-    if created:
-        defaults.fallback_models = fallback_models
-        save_config(config)
     return settings_payload()
 
 
 def delete_model_configuration(query: QueryParams) -> dict[str, Any]:
     name = (_query_first(query, "name") or "").strip()
-    if not name or name == "default":
+    if not name:
         raise WebUISettingsError("model configuration is required")
+    if name == "default":
+        raise WebUISettingsError("default model configuration cannot be deleted", status=409)
 
     config = load_config()
     if name not in config.model_presets:

nanobot/webui/transcript.py

@@ -25,6 +25,7 @@ from nanobot.webui.metadata import WEBUI_MESSAGE_SOURCE_METADATA_KEY, WEBUI_TURN
 
 WEBUI_TRANSCRIPT_SCHEMA_VERSION = 3
 WEBUI_FORK_MARKER_EVENT = "fork_marker"
+WEBUI_TRANSCRIPT_INCOMPLETE_KEY = "transcript_incomplete"
 _MAX_TRANSCRIPT_FILE_BYTES = 8 * 1024 * 1024
 _TARGET_ACTIVE_TRANSCRIPT_BYTES = _MAX_TRANSCRIPT_FILE_BYTES // 2
 _TRANSCRIPT_SEGMENT_MANIFEST_VERSION = 2
@@ -151,6 +152,12 @@ class _TranscriptChunkRef(NamedTuple):
     user_count: int
 
 
+class _SessionBackfillTurn(NamedTuple):
+    user_event: dict[str, Any]
+    assistant_signature: tuple[str, ...]
+    assistant_records: tuple[dict[str, Any], ...]
+
+
 def _record_json_line(record: dict[str, Any]) -> str:
     return json.dumps(record, ensure_ascii=False, separators=(",", ":"))
 
@@ -665,7 +672,7 @@ class WebUITranscriptRecorder:
         phase: str | None = None,
         include_source: bool = False,
         transcript_overrides: dict[str, Any] | None = None,
-    ) -> None:
+    ) -> bool:
         self.prepare_event(
             chat_id,
             event,
@@ -676,7 +683,7 @@ class WebUITranscriptRecorder:
         record = dict(event)
         if transcript_overrides:
             record.update(transcript_overrides)
-        self.append(chat_id, record)
+        return self.append(chat_id, record)
 
     def append_user_message(
         self,
@@ -687,9 +694,9 @@ class WebUITranscriptRecorder:
         media_paths: list[str] | None = None,
         cli_apps: list[dict[str, Any]] | None = None,
         mcp_presets: list[dict[str, Any]] | None = None,
-    ) -> None:
+    ) -> bool:
         if text.strip() == "/stop" and not media_paths:
-            return
+            return False
         payload = build_user_transcript_event(
             chat_id,
             text,
@@ -698,15 +705,17 @@ class WebUITranscriptRecorder:
             mcp_presets=mcp_presets,
         )
         if payload is None:
-            return
+            return False
-        self.prepare_and_append(chat_id, payload, metadata=metadata, phase="user")
+        return self.prepare_and_append(chat_id, payload, metadata=metadata, phase="user")
 
-    def append(self, chat_id: str, event: dict[str, Any]) -> None:
+    def append(self, chat_id: str, event: dict[str, Any]) -> bool:
         try:
             dup = json.loads(json.dumps(event, ensure_ascii=False))
             append_transcript_object(f"websocket:{chat_id}", dup)
         except (OSError, ValueError, TypeError) as e:
             self._log.warning("webui transcript append failed: {}", e)
+            return False
+        return True
 
     def _next_turn_seq(self, chat_id: str, turn_id: str) -> int:
         key = (chat_id, turn_id)
@@ -921,32 +930,69 @@ def _assistant_text_signature(value: Any) -> str:
     return value.strip() if isinstance(value, str) else ""
 
 
+def _session_assistant_event(
+    session_key: str,
+    message: dict[str, Any],
+) -> dict[str, Any] | None:
+    if message.get("role") != "assistant" or is_hidden_history_message(message):
+        return None
+    message = public_history_message(message)
+    content = message.get("content")
+    text = content if isinstance(content, str) else ""
+    media = message.get("media")
+    media_paths = [str(path) for path in media] if isinstance(media, list) else []
+    media_paths = [path for path in media_paths if path]
+    if not text.strip() and not media_paths:
+        return None
+    chat_id = session_key.split(":", 1)[1] if ":" in session_key else session_key
+    event: dict[str, Any] = {
+        "event": "message",
+        "chat_id": chat_id,
+        "text": text,
+    }
+    if media_paths:
+        event["media"] = media_paths
+    latency_ms = message.get("latency_ms")
+    if isinstance(latency_ms, int | float) and latency_ms >= 0:
+        event["latency_ms"] = int(latency_ms)
+    return event
+
+
 def _session_backfill_turns(
     session_key: str,
     session_messages: list[dict[str, Any]],
-) -> list[tuple[dict[str, Any], tuple[str, ...]]]:
+) -> list[_SessionBackfillTurn]:
-    turns: list[tuple[dict[str, Any], tuple[str, ...]]] = []
+    turns: list[_SessionBackfillTurn] = []
     current_user: dict[str, Any] | None = None
-    assistant_texts: list[str] = []
+    assistant_records: list[dict[str, Any]] = []
 
     def flush() -> None:
-        if current_user is None:
+        if current_user is None or not assistant_records:
             return
-        signature = tuple(text for text in assistant_texts if text)
+        signature = tuple(
-        if signature:
+            text
-            turns.append((current_user, signature))
+            for record in assistant_records
+            if (text := _assistant_text_signature(record.get("text")))
+        )
+        turns.append(
+            _SessionBackfillTurn(
+                current_user,
+                signature,
+                tuple(dict(record) for record in assistant_records),
+            )
+        )
 
     for message in session_messages:
         role = message.get("role")
         if role == "user":
             flush()
             current_user = _session_user_event(session_key, message)
-            assistant_texts = []
+            assistant_records = []
             continue
         if role == "assistant" and current_user is not None:
-            text = _assistant_text_signature(message.get("content"))
+            record = _session_assistant_event(session_key, message)
-            if text:
+            if record is not None:
-                assistant_texts.append(text)
+                assistant_records.append(record)
     flush()
     return turns
 
@@ -976,7 +1022,7 @@ def _transcript_turn_signature(records: list[dict[str, Any]]) -> tuple[str, ...]
 
 
 def _find_unique_session_turn(
-    session_turns: list[tuple[dict[str, Any], tuple[str, ...]]],
+    session_turns: list[_SessionBackfillTurn],
     signature: tuple[str, ...],
     start: int,
 ) -> int | None:
@@ -984,7 +1030,7 @@ def _find_unique_session_turn(
         return None
     found: int | None = None
     for index in range(start, len(session_turns)):
-        if session_turns[index][1] != signature:
+        if session_turns[index].assistant_signature != signature:
             continue
         if found is not None:
             return None
@@ -992,6 +1038,101 @@ def _find_unique_session_turn(
     return found
 
 
+def _user_recovery_signature(event: dict[str, Any]) -> str:
+    fields = {
+        key: event[key]
+        for key in ("text", "media_paths", "cli_apps", "mcp_presets")
+        if key in event
+    }
+    return json.dumps(fields, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _find_unique_session_turn_by_user(
+    session_turns: list[_SessionBackfillTurn],
+    user_event: dict[str, Any],
+) -> _SessionBackfillTurn | None:
+    signature = _user_recovery_signature(user_event)
+    matches = [
+        turn
+        for turn in session_turns
+        if _user_recovery_signature(turn.user_event) == signature
+    ]
+    return matches[0] if len(matches) == 1 else None
+
+
+def _is_recoverable_answer_record(record: dict[str, Any]) -> bool:
+    event = record.get("event")
+    if event in {"delta", "stream_end"}:
+        return True
+    return event == "message" and record.get("kind") not in {
+        "tool_hint",
+        "progress",
+        "reasoning",
+    }
+
+
+def recover_incomplete_turns_from_session(
+    lines: list[dict[str, Any]],
+    session_messages: list[dict[str, Any]] | None,
+    *,
+    session_key: str,
+) -> list[dict[str, Any]]:
+    """Recover marked transcript answers only when one durable session turn matches."""
+    if not lines or not session_messages:
+        return lines
+    session_turns = _session_backfill_turns(session_key, session_messages)
+    if not session_turns:
+        return lines
+
+    recovered: list[dict[str, Any]] = []
+    for turn in _split_transcript_turns(lines):
+        turn_end = turn[-1] if turn else None
+        if (
+            not isinstance(turn_end, dict)
+            or turn_end.get("event") != "turn_end"
+            or turn_end.get(WEBUI_TRANSCRIPT_INCOMPLETE_KEY) is not True
+        ):
+            recovered.extend(turn)
+            continue
+
+        user_events = [record for record in turn if record.get("event") == "user"]
+        if len(user_events) != 1:
+            recovered.extend(turn)
+            continue
+        session_turn = _find_unique_session_turn_by_user(session_turns, user_events[0])
+        if session_turn is None or not session_turn.assistant_records:
+            recovered.extend(turn)
+            continue
+
+        stable_end_ms = _valid_created_at_ms(turn_end.get("created_at_ms"))
+        turn_id = turn_end.get("turn_id")
+        answer_records: list[dict[str, Any]] = []
+        for index, source in enumerate(session_turn.assistant_records):
+            answer = dict(source)
+            if isinstance(turn_id, str) and turn_id:
+                answer["turn_id"] = turn_id
+                answer["turn_phase"] = "answer"
+            if stable_end_ms is not None:
+                answer["created_at_ms"] = max(
+                    0,
+                    stable_end_ms - len(session_turn.assistant_records) + index,
+                )
+            answer_records.append(answer)
+
+        # Session history is the durable source of the completed answer. Keep
+        # traces/reasoning/file edits, but replace any partial answer fragments.
+        recovered.extend(
+            record
+            for record in turn[:-1]
+            if not _is_recoverable_answer_record(record)
+        )
+        recovered.extend(answer_records)
+        completed_end = dict(turn_end)
+        completed_end.pop(WEBUI_TRANSCRIPT_INCOMPLETE_KEY, None)
+        recovered.append(completed_end)
+    return recovered
+
+
 def _with_backfilled_user(
     records: list[dict[str, Any]],
     user_event: dict[str, Any],
@@ -1972,8 +2113,36 @@ def fork_boundary_message_count(lines: list[dict[str, Any]]) -> int | None:
     return None
 
 
-def has_pending_tool_calls(lines: list[dict[str, Any]]) -> bool:
+def has_pending_tool_calls(
+    lines: list[dict[str, Any]],
+    *,
+    active_turn_started_at: float | None = None,
+    active_turn_id: str | None = None,
+    active_turn_transcript_persistence_failed: bool = False,
+) -> bool:
     """Return True when the selected transcript tail looks like an unfinished turn."""
+    # An older canonical turn can remain unsafe even after a later turn
+    # completes. Recovery removes this marker only after matching durable
+    # session history, so no later turn_end may hide it.
+    if any(
+        rec.get(WEBUI_TRANSCRIPT_INCOMPLETE_KEY) is True
+        for rec in lines
+    ):
+        return True
+    if active_turn_started_at is not None:
+        if active_turn_transcript_persistence_failed:
+            return True
+        if active_turn_id is None:
+            return True
+        for rec in reversed(lines):
+            transcript_turn_id = rec.get("turn_id")
+            if not isinstance(transcript_turn_id, str) or not transcript_turn_id:
+                continue
+            if transcript_turn_id != active_turn_id:
+                return True
+            return rec.get("event") != "turn_end"
+        return True
+
     for rec in reversed(lines):
         ev = rec.get("event")
         if ev == "turn_end":
@@ -1995,6 +2164,24 @@ def has_pending_tool_calls(lines: list[dict[str, Any]]) -> bool:
     return False
 
 
+def completed_turn_ids(lines: list[dict[str, Any]]) -> list[str]:
+    """Return stable identities for turns with an explicitly persisted completion."""
+    completed: list[str] = []
+    seen: set[str] = set()
+    for rec in lines:
+        if (
+            rec.get("event") != "turn_end"
+            or rec.get(WEBUI_TRANSCRIPT_INCOMPLETE_KEY) is True
+        ):
+            continue
+        turn_id = rec.get("turn_id")
+        if not isinstance(turn_id, str) or not turn_id or turn_id in seen:
+            continue
+        seen.add(turn_id)
+        completed.append(turn_id)
+    return completed
+
+
 def build_webui_thread_response(
     session_key: str,
     *,
@@ -2002,6 +2189,9 @@ def build_webui_thread_response(
     augment_assistant_media: Callable[[list[str]], list[dict[str, Any]]] | None = None,
     augment_assistant_text: Callable[[str], str] | None = None,
     session_messages: list[dict[str, Any]] | None = None,
+    active_turn_started_at: float | None = None,
+    active_turn_id: str | None = None,
+    active_turn_transcript_persistence_failed: bool = False,
     limit: int | None = None,
     direction: str | None = None,
     before: str | None = None,
@@ -2013,9 +2203,14 @@ def build_webui_thread_response(
         lines, page = _select_transcript_page(session_key, limit=limit, before=before)
     else:
         lines = read_transcript_lines(session_key)
-    if not lines:
+    if not lines and active_turn_started_at is None:
         return None
     lines = inject_missing_user_events_from_session(session_key, lines, session_messages)
+    lines = recover_incomplete_turns_from_session(
+        lines,
+        session_messages,
+        session_key=session_key,
+    )
     fork_boundary = fork_boundary_message_count(lines)
     msgs = replay_transcript_to_ui_messages(
         lines,
@@ -2027,7 +2222,16 @@ def build_webui_thread_response(
         "schemaVersion": WEBUI_TRANSCRIPT_SCHEMA_VERSION,
         "sessionKey": session_key,
         "messages": msgs,
-        "has_pending_tool_calls": has_pending_tool_calls(lines),
+        "completed_turn_ids": completed_turn_ids(lines),
+        "has_pending_tool_calls": has_pending_tool_calls(
+            lines,
+            active_turn_started_at=active_turn_started_at,
+            active_turn_id=active_turn_id,
+            active_turn_transcript_persistence_failed=(
+                active_turn_transcript_persistence_failed
+            ),
+        ),
+        "active_turn_id": active_turn_id,
     }
     if page is not None:
         page["loaded_message_count"] = len(msgs)

nanobot/webui/ws_http.py

@@ -170,8 +170,6 @@ class GatewayHTTPHandler:
         local_trigger_pending_ids: Callable[[str], set[str]] | None = None,
         channel_feature_action: Callable[..., Any] | None = None,
         channel_runtime_status: Callable[[], dict[str, Any]] | None = None,
-        extension_service: Any | None = None,
-        allow_remote_package_install: bool = False,
         log: Any = logger,
     ) -> None:
         self.config = config
@@ -192,7 +190,6 @@ class GatewayHTTPHandler:
         self._log = log
         self._runtime_surface = runtime_surface
 
-        from nanobot.webui.extensions_routes import WebUIExtensionsRouter
         from nanobot.webui.settings_api import runtime_capabilities as _rc
         from nanobot.webui.settings_routes import WebUISettingsRouter
 
@@ -209,14 +206,6 @@ class GatewayHTTPHandler:
             channel_feature_action=channel_feature_action,
             channel_runtime_status=channel_runtime_status,
         )
-        self.extensions_routes = WebUIExtensionsRouter(
-            service=extension_service,
-            check_api_token=self.check_api_token,
-            json_response=_http_json_response,
-            error_response=_http_error,
-            allow_remote_package_install=allow_remote_package_install,
-            logger=self._log,
-        )
 
     def workspace_controls_available(self, connection: Any) -> bool:
         return self._runtime_surface == "native" or _is_localhost(connection)
@@ -258,9 +247,6 @@ class GatewayHTTPHandler:
 
         # Settings routes (delegated)
         response = await self.settings_routes.dispatch(connection, request, got)
-        if response is not None:
-            return response
-        response = await self.extensions_routes.dispatch(connection, request, got)
         if response is not None:
             return response
 
@@ -488,6 +474,18 @@ class GatewayHTTPHandler:
         if direction is not None and direction not in {"latest"}:
             return _http_error(400, "invalid direction")
         before = _query_first(query, "before")
+        from nanobot.session.webui_turns import (
+            websocket_turn_id,
+            websocket_turn_transcript_persistence_failed,
+            websocket_turn_wall_started_at,
+        )
+
+        chat_id = decoded_key.split(":", 1)[1]
+        active_turn_started_at = websocket_turn_wall_started_at(chat_id)
+        active_turn_id = websocket_turn_id(chat_id)
+        active_turn_transcript_persistence_failed = (
+            websocket_turn_transcript_persistence_failed(chat_id)
+        )
         data = build_webui_thread_response(
             decoded_key,
             augment_user_media=self.media.augment_transcript_media,
@@ -497,6 +495,11 @@ class GatewayHTTPHandler:
                 workspace_path=scope.project_path,
             ),
             session_messages=session_messages,
+            active_turn_started_at=active_turn_started_at,
+            active_turn_id=active_turn_id,
+            active_turn_transcript_persistence_failed=(
+                active_turn_transcript_persistence_failed
+            ),
             limit=limit,
             direction=direction,
             before=before,

render-config.json

@@ -1,8 +1,14 @@
 {
   "agents": {
     "defaults": {
+      "modelPreset": "default"
+    }
+  },
+  "modelPresets": {
+    "default": {
       "model": "anthropic/claude-opus-4-8",
-      "provider": "auto"
+      "provider": "auto",
+      "supportsImageInput": null
     }
   },
   "providers": {

tests/agent/runner_helpers.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from nanobot.agent.runner import AgentRunSpec
-from nanobot.config.schema import AgentDefaults
+from nanobot.config.schema import ModelPresetConfig
 from nanobot.providers.base import GenerationSettings, LLMProvider
 from nanobot.utils.llm_runtime import LLMRuntime
 
@@ -21,7 +21,7 @@ def make_run_spec(provider: LLMProvider, **kwargs: Any) -> AgentRunSpec:
     model = kwargs.pop("model")
     context_window_tokens = kwargs.pop(
         "context_window_tokens",
-        AgentDefaults().context_window_tokens,
+        ModelPresetConfig(model=model).context_window_tokens,
     )
     provider_generation = getattr(provider, "generation", None)
     defaults = GenerationSettings()

tests/agent/test_attachment_references.py

@@ -0,0 +1,208 @@
+import asyncio
+import base64
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.agent.loop import AgentLoop, TurnContext, TurnKind
+from nanobot.agent.tools.filesystem import ReadFileTool
+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(
+    workspace: 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=workspace,
+        model="test-model",
+        channels_config=channels_config,
+    )
+
+
+def _turn_context(loop: AgentLoop, msg: InboundMessage) -> TurnContext:
+    return TurnContext(
+        msg=msg,
+        session_key=f"{msg.channel}:{msg.chat_id}",
+        turn_id="turn-1",
+        runtime=loop.llm_runtime(),
+        kind=TurnKind.USER,
+        delivery=loop.turn_delivery_factory.create(msg, f"{msg.channel}:{msg.chat_id}"),
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("extract_document_text", [True, False])
+async def test_document_attachment_is_referenced_and_read_on_demand(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    extract_document_text: bool,
+) -> None:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    media_dir = tmp_path / "media"
+    media_dir.mkdir()
+    csv_path = media_dir / "report.csv"
+    csv_path.write_text("name,value\nnanobot,1", encoding="utf-8")
+    monkeypatch.setattr("nanobot.agent.tools.path_utils.get_media_dir", lambda: media_dir)
+
+    loop = _make_loop(
+        workspace,
+        ChannelsConfig(extract_document_text=extract_document_text),
+    )
+    msg = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id="c",
+        content="import this report",
+        media=[str(csv_path)],
+    )
+    ctx = _turn_context(loop, msg)
+
+    await loop._restore_turn(ctx)
+
+    assert ctx.msg.content == f"import this report\n\n[Attachment: {csv_path}]"
+    assert "name,value" not in ctx.msg.content
+    assert ctx.msg.media == []
+
+    read_tool = ReadFileTool(workspace=workspace, allowed_dir=workspace)
+    result = await read_tool.execute(path=str(csv_path))
+
+    assert "1| name,value" in result
+    assert "2| nanobot,1" in result
+
+
+@pytest.mark.asyncio
+async def test_document_reference_survives_session_reload(tmp_path: Path) -> None:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    doc_path = tmp_path / "report.csv"
+    doc_path.write_text("name,value", encoding="utf-8")
+
+    loop = _make_loop(workspace)
+    loop._run_agent_loop = AsyncMock(side_effect=RuntimeError("interrupt"))  # type: ignore[method-assign]
+    msg = InboundMessage(
+        channel="websocket",
+        sender_id="u",
+        chat_id="persisted-attachment",
+        content="review this",
+        media=[str(doc_path)],
+    )
+
+    with pytest.raises(RuntimeError, match="interrupt"):
+        await loop._process_message(msg)
+
+    session_key = "websocket:persisted-attachment"
+    loop.sessions.invalidate(session_key)
+    persisted = loop.sessions.get_or_create(session_key)
+
+    assert [message["role"] for message in persisted.messages] == ["user"]
+    assert persisted.messages[0]["content"] == (
+        f"review this\n\n[Attachment: {doc_path.resolve()}]"
+    )
+    assert "media" not in persisted.messages[0]
+
+
+@pytest.mark.asyncio
+async def test_pending_document_attachment_keeps_body_out_of_prompt(
+    tmp_path: Path,
+) -> None:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    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 = 0
+
+    async def chat_with_retry(*, messages: list[dict], **kwargs: object) -> LLMResponse:
+        nonlocal call_count
+        call_count += 1
+        captured_messages.append([dict(message) for message in messages])
+        return LLMResponse(content=f"answer-{call_count}", tool_calls=[], usage={})
+
+    loop = _make_loop(workspace)
+    loop.provider.chat_with_retry = chat_with_retry
+    loop.tools.get_definitions = MagicMock(return_value=[])
+
+    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"}],
+        runtime=loop.llm_runtime(),
+        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_attachment_references_still_preserve_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
+    assert "manual extraction target" not in content
+
+
+def test_attachment_references_canonicalize_existing_relative_paths(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    image_path = tmp_path / "chart.png"
+    image_path.write_bytes(
+        base64.b64decode(
+            "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+yF9kAAAAASUVORK5CYII="
+        )
+    )
+    doc_path = tmp_path / "report.csv"
+    doc_path.write_text("name,value", encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+
+    content, media = reference_non_image_attachments(
+        "review these",
+        [image_path.name, doc_path.name],
+    )
+
+    assert media == [str(image_path.resolve())]
+    assert f"[Attachment: {doc_path.resolve()}]" in content

tests/agent/test_auto_compact.py

@@ -272,7 +272,13 @@ class TestAgentLoopTTLParam:
         kwargs = session.get_history.call_args.kwargs
         assert isinstance(kwargs.get("max_tokens"), int)
         assert kwargs["max_tokens"] > 0
-        assert set(kwargs) == {"max_messages", "max_tokens", "extend_to_user"}
+        assert set(kwargs) == {
+            "max_messages",
+            "max_tokens",
+            "extend_to_user",
+            "include_media",
+        }
+        assert kwargs["include_media"] is True
 
     @pytest.mark.asyncio
     async def test_session_file_cap_archives_and_trims_old_messages(self, tmp_path):

tests/agent/test_consolidator.py

@@ -170,6 +170,34 @@ class TestConsolidatorSummarize:
         entries = store.read_unprocessed_history(since_cursor=0)
         assert entries[0]["session_key"] == "telegram:chat-1"
 
+    async def test_summarize_preserves_media_manifest_deterministically(
+        self,
+        consolidator,
+        mock_provider,
+        store,
+        runtime,
+    ):
+        mock_provider.chat_with_retry.return_value = MagicMock(
+            content="User shared a screenshot.",
+            finish_reason="stop",
+        )
+        messages = [{
+            "role": "user",
+            "content": "",
+            "media": ["/media/screenshot.png"],
+        }]
+
+        result = await consolidator.archive(messages, runtime=runtime)
+
+        assert result == (
+            "Archived attachments:\n- [image: /media/screenshot.png]\n\n"
+            "User shared a screenshot."
+        )
+        prompt = mock_provider.chat_with_retry.call_args.kwargs["messages"][1]["content"]
+        assert "[image: /media/screenshot.png]" in prompt
+        entries = store.read_unprocessed_history(since_cursor=0)
+        assert "[image: /media/screenshot.png]" in entries[0]["content"]
+
     async def test_summarize_raw_dumps_on_llm_failure(
         self, consolidator, mock_provider, store, runtime
     ):
@@ -992,6 +1020,18 @@ class TestRawArchiveTruncation:
         assert len(entries) == 1
         assert "hello" in entries[0]["content"]
 
+    def test_raw_archive_preserves_late_media_path_before_truncation(self, store):
+        messages = [
+            {"role": "user", "content": "x" * 20_000},
+            {"role": "user", "content": "", "media": ["/media/late.png"]},
+        ]
+
+        store.raw_archive(messages)
+
+        entry = store.read_unprocessed_history(since_cursor=0)[0]["content"]
+        assert "Archived attachments:" in entry
+        assert "[image: /media/late.png]" in entry
+
     def test_raw_archive_excludes_model_only_runtime_context(self, store):
         content, marker = append_runtime_context(
             "ship the feature",

tests/agent/test_context_builder.py

@@ -5,7 +5,11 @@ from pathlib import Path
 import pytest
 
 from nanobot.agent.context import ContextBuilder
-from nanobot.runtime_context import RuntimeContextBlock
+from nanobot.runtime_context import (
+    RUNTIME_CONTEXT_HISTORY_META,
+    RuntimeContextBlock,
+    append_runtime_context,
+)
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -244,38 +248,40 @@ class TestBundledToolContract:
 
 
 # ---------------------------------------------------------------------------
-# _build_user_content
+# build_user_content
 # ---------------------------------------------------------------------------
 
 
 class TestBuildUserContent:
     def test_no_media_returns_string(self, tmp_path):
         builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", None)
+        result = builder.build_user_content("hello", None)
         assert result == "hello"
 
     def test_empty_media_returns_string(self, tmp_path):
         builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", [])
+        result = builder.build_user_content("hello", [])
         assert result == "hello"
 
-    def test_nonexistent_media_file_returns_string(self, tmp_path):
+    def test_nonexistent_media_file_returns_explicit_placeholder(self, tmp_path):
         builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", ["/nonexistent/image.png"])
+        result = builder.build_user_content("hello", ["/nonexistent/image.png"])
-        assert result == "hello"
+        assert isinstance(result, list)
+        assert "unavailable" in result[0]["text"].lower()
+        assert result[1] == {"type": "text", "text": "hello"}
 
     def test_non_image_file_returns_string(self, tmp_path):
         txt = tmp_path / "doc.txt"
         txt.write_text("not an image", encoding="utf-8")
         builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", [str(txt)])
+        result = builder.build_user_content("hello", [str(txt)])
         assert result == "hello"
 
     def test_valid_image_returns_list(self, tmp_path):
         png = tmp_path / "test.png"
         png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
         builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", [str(png)])
+        result = builder.build_user_content("hello", [str(png)])
         assert isinstance(result, list)
         assert len(result) == 2
         assert result[0]["type"] == "image_url"
@@ -287,7 +293,7 @@ class TestBuildUserContent:
         png = tmp_path / "test.png"
         png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
         builder = _builder(tmp_path)
-        result = builder._build_user_content("hello", [str(png)])
+        result = builder.build_user_content("hello", [str(png)])
         assert "_meta" in result[0]
         assert "path" in result[0]["_meta"]
 
@@ -369,6 +375,25 @@ class TestBuildMessages:
         assert messages[1]["role"] == "user"
         assert "hello" in str(messages[1]["content"])
 
+    def test_public_builder_preserves_assistant_role_compatibility(self, tmp_path):
+        from nanobot.agent import ContextBuilder as PublicContextBuilder
+
+        builder = PublicContextBuilder(tmp_path)
+        messages = builder.build_messages(
+            history=[{"role": "assistant", "content": "previous result"}],
+            current_message="subagent result",
+            current_role="assistant",
+            runtime_context_blocks=[
+                RuntimeContextBlock(source="test", content="user-only runtime context"),
+            ],
+        )
+
+        assert len(messages) == 2
+        assert messages[-1]["role"] == "assistant"
+        assert messages[-1]["content"] == "previous result\n\nsubagent result"
+        assert "user-only runtime context" not in messages[-1]["content"]
+        assert "_meta" not in messages[-1]
+
     def test_runtime_context_is_not_injected_by_default(self, tmp_path):
         builder = _builder(tmp_path)
         messages = builder.build_messages([], "hello", channel="cli")
@@ -419,3 +444,55 @@ class TestBuildMessages:
         user_msg = messages[-1]["content"]
         assert isinstance(user_msg, list)
         assert any(b.get("type") == "image_url" for b in user_msg)
+
+    def test_persisted_media_rehydrates_to_identical_image_content(self, tmp_path):
+        png = tmp_path / "stable.png"
+        png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
+        builder = _builder(tmp_path)
+        first_content = builder.build_user_content("describe", [str(png)])
+        history = [
+            {
+                "role": "user",
+                "content": "describe",
+                "_media_paths": [str(png)],
+            },
+            {"role": "assistant", "content": "done"},
+        ]
+
+        messages = builder.build_messages(history, "next")
+
+        assert messages[1]["content"] == first_content
+        assert "_media_paths" not in messages[1]
+
+    def test_persisted_media_and_runtime_context_rehydrate_identically(self, tmp_path):
+        png = tmp_path / "stable-context.png"
+        png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
+        builder = _builder(tmp_path)
+        blocks = [
+            RuntimeContextBlock(
+                source="cli_apps",
+                content="CLI App Attachment: @drawio (tool=run_cli_app).",
+            )
+        ]
+        first_content = builder.build_messages(
+            [],
+            "describe",
+            media=[str(png)],
+            runtime_context_blocks=blocks,
+        )[-1]["content"]
+        persisted_content, marker = append_runtime_context("describe", blocks)
+        history = [
+            {
+                "role": "user",
+                "content": persisted_content,
+                "_media_paths": [str(png)],
+                RUNTIME_CONTEXT_HISTORY_META: marker,
+            },
+            {"role": "assistant", "content": "done"},
+        ]
+
+        messages = builder.build_messages(history, "next")
+
+        assert messages[1]["content"] == first_content
+        assert "_media_paths" not in messages[1]
+        assert RUNTIME_CONTEXT_HISTORY_META not in messages[1]

tests/agent/test_context_prompt_cache.py

@@ -340,21 +340,6 @@ def test_system_prompt_keeps_message_tool_out_of_current_chat_replies(tmp_path)
     assert "Wait for the tool results, then answer once" in prompt
 
 
-def test_subagent_result_does_not_create_consecutive_assistant_messages(tmp_path) -> None:
-    workspace = _make_workspace(tmp_path)
-    builder = ContextBuilder(workspace)
-
-    messages = builder.build_messages(
-        history=[{"role": "assistant", "content": "previous result"}],
-        current_message="subagent result",
-        channel="cli",
-        current_role="assistant",
-    )
-
-    for left, right in zip(messages, messages[1:]):
-        assert not (left.get("role") == right.get("role") == "assistant")
-
-
 def test_memory_skill_is_lazy_loaded_from_skills_index(tmp_path) -> None:
     """Memory search guidance should be discoverable without loading its full body."""
     workspace = _make_workspace(tmp_path)
@@ -398,7 +383,7 @@ def test_template_memory_md_is_skipped(tmp_path) -> None:
     assert "This file is automatically updated by nanobot" not in prompt
 
 
-def test_customized_memory_md_is_injected(tmp_path) -> None:
+def test_customized_memory_md_is_injected(tmp_path, monkeypatch) -> None:
     """A Dream-populated MEMORY.md should be injected normally."""
     workspace = _make_workspace(tmp_path)
     from nanobot.utils.helpers import sync_workspace_templates
@@ -409,7 +394,17 @@ def test_customized_memory_md_is_injected(tmp_path) -> None:
     )
 
     builder = ContextBuilder(workspace)
+    read_memory = builder.memory.read_memory
+    calls = 0
+
+    def tracked_read_memory() -> str:
+        nonlocal calls
+        calls += 1
+        return read_memory()
+
+    monkeypatch.setattr(builder.memory, "read_memory", tracked_read_memory)
     prompt = builder.build_system_prompt()
 
     assert "# Memory\n\n## Long-term Memory" in prompt
     assert "User prefers dark mode" in prompt
+    assert calls == 1

tests/agent/test_document_extraction_toggle.py

@@ -1,176 +0,0 @@
-import asyncio
-import base64
-from pathlib import Path
-from unittest.mock import AsyncMock, MagicMock
-
-import pytest
-
-from nanobot.agent.loop import AgentLoop, TurnContext, TurnKind
-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_restore_turn_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)
-
-    msg = InboundMessage(
-        channel="cli",
-        sender_id="u",
-        chat_id="c",
-        content="summarize",
-        media=[str(doc_path)],
-    )
-    ctx = TurnContext(
-        msg=msg,
-        session_key="cli:c",
-        turn_id="turn-1",
-        runtime=loop.llm_runtime(),
-        kind=TurnKind.USER,
-        delivery=loop.turn_delivery_factory.create(msg, "cli:c"),
-    )
-
-    await loop._restore_turn(ctx)
-
-    assert calls == [("summarize", [str(doc_path)])]
-    assert "Quarterly revenue" in ctx.msg.content
-    assert ctx.msg.media == []
-
-
-@pytest.mark.asyncio
-async def test_restore_turn_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)
-
-    msg = InboundMessage(
-        channel="cli",
-        sender_id="u",
-        chat_id="c",
-        content="summarize",
-        media=[str(doc_path)],
-    )
-    ctx = TurnContext(
-        msg=msg,
-        session_key="cli:c",
-        turn_id="turn-1",
-        runtime=loop.llm_runtime(),
-        kind=TurnKind.USER,
-        delivery=loop.turn_delivery_factory.create(msg, "cli:c"),
-    )
-
-    await loop._restore_turn(ctx)
-
-    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"}],
-        runtime=loop.llm_runtime(),
-        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_dream.py

@@ -3,6 +3,7 @@
 import pytest
 
 from nanobot.agent.memory import MemoryStore
+from nanobot.config.schema import ModelPresetConfig
 from nanobot.providers.base import LLMResponse
 from nanobot.security.workspace_access import (
     bind_workspace_scope,
@@ -126,15 +127,15 @@ class TestBuildDreamPrompt:
         prompt, _ = result
         assert "memory consolidation engine" in prompt
 
-    def test_truncates_long_entries(self, store):
+    def test_truncates_long_entries_at_1000_chars(self, store):
         long_content = "x" * 2000
         store.append_history(long_content)
         result = store.build_dream_prompt()
         assert result is not None
         prompt, _ = result
-        # The full 2000 chars should not appear — truncated to 500
         assert long_content not in prompt
-        assert "x" * 500 in prompt
+        assert "x" * 1000 in prompt
+        assert "x" * 1001 not in prompt
 
     def test_batches_oldest_unprocessed_entries_first(self, store):
         for i in range(25):
@@ -221,11 +222,20 @@ class TestDreamTools:
                 "new_text": "Precise",
             },
         )
+        user_result = await tools.execute(
+            "write_file",
+            {
+                "path": "USER.md",
+                "content": "# User Profile\n\n- **Name**: Ada\n",
+            },
+        )
 
         assert "Patch applied" in memory_result
         assert "Successfully edited" in soul_result
+        assert "Successfully wrote" in user_result
         assert "Project Y active" in store.memory_file.read_text(encoding="utf-8")
         assert "Precise" in store.soul_file.read_text(encoding="utf-8")
+        assert "**Name**: Ada" in store.user_file.read_text(encoding="utf-8")
 
     @pytest.mark.asyncio
     async def test_dream_can_write_workspace_skills(self, store):
@@ -305,9 +315,17 @@ class TestDreamTools:
                 "new_text": "2",
             },
         )
+        history_write_result = await tools.execute(
+            "write_file",
+            {
+                "path": "memory/history.jsonl",
+                "content": "after\n",
+            },
+        )
 
         assert "outside allowed directory" in history_result
         assert "outside allowed directory" in cursor_result
+        assert "outside allowed directory" in history_write_result
         assert store.history_file.read_text(encoding="utf-8") == "before\n"
         assert store._dream_cursor_file.read_text(encoding="utf-8") == "1"
 
@@ -330,11 +348,10 @@ class TestDreamTools:
             },
         )
         user_result = await tools.execute(
-            "edit_file",
+            "write_file",
             {
                 "path": "USER.md/evil.txt",
-                "old_text": "",
+                "content": "owned",
-                "new_text": "owned",
             },
         )
 
@@ -385,6 +402,21 @@ class TestEphemeralDirect:
 
         return loop, store
 
+    def test_dream_runtime_uses_preset_without_changing_default(self, _make_loop):
+        loop, _ = _make_loop
+        loop.runtime_resolver._model_presets = {
+            "dream": ModelPresetConfig(model="dream-model"),
+        }
+        loop.dream_model_preset = "dream"
+
+        runtime = loop.dream_runtime()
+
+        assert runtime is not None
+        assert runtime.model == "dream-model"
+        assert runtime.model_preset == "dream"
+        assert loop.model == "test-model"
+        assert loop.model_preset is None
+
     async def test_ephemeral_skips_raw_archive(self, tmp_path, _make_loop):
         """When ephemeral=True, raw_archive must not be called."""
         from unittest.mock import patch

tests/agent/test_loop_direct_websocket_status.py

@@ -7,8 +7,11 @@ from nanobot.agent.loop import AgentLoop
 from nanobot.bus.events import OutboundMessage
 from nanobot.bus.outbound_events import GoalStatusEvent
 from nanobot.bus.queue import MessageBus
+from nanobot.channels.websocket.runtime import WebSocketChannel
 from nanobot.providers.base import GenerationSettings, LLMResponse
-from nanobot.session.webui_turns import WebuiTurnCoordinator
+from nanobot.session import webui_turns as wth
+from nanobot.session.webui_turns import WebuiTurnCoordinator, WebuiTurnRoutePolicy
+from nanobot.webui.metadata import WEBSOCKET_TURN_OWNER_METADATA_KEY
 
 
 def _make_loop(tmp_path):
@@ -32,6 +35,7 @@ def _make_loop(tmp_path):
         sessions=loop.sessions,
         schedule_background=lambda coro: loop._schedule_background(coro),
     ).subscribe(loop.runtime_events)
+    loop.turn_delivery_factory.route_policy = WebuiTurnRoutePolicy(loop.sessions)
     loop.tools.get_definitions = MagicMock(return_value=[])
     return loop
 
@@ -39,29 +43,51 @@ def _make_loop(tmp_path):
 @pytest.mark.asyncio
 async def test_process_direct_websocket_clears_run_status(tmp_path) -> None:
     loop = _make_loop(tmp_path)
-
+    gateway = MagicMock()
-    response = await loop.process_direct(
+    channel = WebSocketChannel(
-        "deliver reminder",
+        {"enabled": True, "allowFrom": ["*"]},
-        session_key="cron:reminder-1",
+        loop.bus,
-        channel="websocket",
+        gateway=gateway,
-        chat_id="chat-1",
     )
 
-    assert response is not None
+    try:
-    assert response.content == "done"
+        response = await loop.process_direct(
+            "deliver reminder",
+            session_key="cron:reminder-1",
+            channel="websocket",
+            chat_id="chat-1",
+        )
 
-    events = []
+        assert response is not None
-    while loop.bus.outbound_size:
+        assert response.content == "done"
-        events.append(await loop.bus.consume_outbound())
 
-    statuses = [
+        events = []
-        event.event
+        while loop.bus.outbound_size:
-        for event in events
+            event = await loop.bus.consume_outbound()
-        if isinstance(event.event, GoalStatusEvent)
+            events.append(event)
-    ]
+            await channel.send(event)
-    assert [status.status for status in statuses] == ["running", "idle"]
+
-    assert isinstance(statuses[0].started_at, float)
+        status_messages = [
-    assert statuses[1].started_at is None
+            event
+            for event in events
+            if isinstance(event.event, GoalStatusEvent)
+        ]
+        statuses = [event.event for event in status_messages]
+        assert [status.status for status in statuses] == ["running", "idle"]
+        assert isinstance(statuses[0].started_at, float)
+        assert statuses[1].started_at is None
+        owners = {
+            event.metadata[WEBSOCKET_TURN_OWNER_METADATA_KEY]
+            for event in status_messages
+        }
+        assert len(owners) == 1
+        assert wth.websocket_turn_wall_started_at("chat-1") is None
+        assert "chat-1" not in wth._WEBSOCKET_ACTIVE_TURNS
+    finally:
+        wth._WEBSOCKET_ACTIVE_TURNS.clear()
+        wth._WEBSOCKET_TURN_WALL_STARTED_AT.clear()
+        wth._WEBSOCKET_TURN_IDS.clear()
+        wth._WEBSOCKET_TURN_OWNERS.clear()
 
 
 @pytest.mark.asyncio

tests/agent/test_loop_progress.py

@@ -28,7 +28,10 @@ from nanobot.utils.progress_events import (
     invoke_file_edit_progress,
     on_progress_accepts_file_edit_events,
 )
-from nanobot.webui.metadata import WEBUI_TURN_METADATA_KEY
+from nanobot.webui.metadata import (
+    WEBSOCKET_TURN_OWNER_METADATA_KEY,
+    WEBUI_TURN_METADATA_KEY,
+)
 
 
 def _make_loop(tmp_path: Path) -> AgentLoop:
@@ -903,6 +906,12 @@ class TestToolEventProgress:
         turn_id = turn_ids.pop()
         assert isinstance(turn_id, str)
         assert turn_id.startswith("subagent:")
+        owners = {
+            message.metadata.get(WEBSOCKET_TURN_OWNER_METADATA_KEY)
+            for message in visible_events
+        }
+        assert len(owners) == 1
+        assert isinstance(owners.pop(), str)
         assert all(
             (message.channel, message.chat_id) == ("websocket", "chat-a")
             and message.metadata.get("webui") is True
@@ -910,6 +919,7 @@ class TestToolEventProgress:
             and set(message.metadata) <= {
                 "webui",
                 "_wants_stream",
+                WEBSOCKET_TURN_OWNER_METADATA_KEY,
                 WEBUI_TURN_METADATA_KEY,
                 "latency_ms",
             }

tests/agent/test_loop_save_turn.py

@@ -34,7 +34,7 @@ from nanobot.session.keys import (
     LAST_CHANNEL_METADATA_KEY,
     UNIFIED_SESSION_KEY,
 )
-from nanobot.session.manager import Session, SessionManager
+from nanobot.session.manager import Session
 from nanobot.session.turn_continuation import (
     INTERNAL_CONTINUATION_META,
     INTERNAL_CONTINUATION_RUN_STARTED_AT_META,
@@ -49,7 +49,6 @@ from nanobot.session.webui_turns import (
     maybe_generate_webui_title,
 )
 from nanobot.triggers.local_session_turns import LOCAL_TRIGGER_META
-from nanobot.utils.llm_runtime import LLMRuntime
 
 
 def _mk_loop() -> AgentLoop:
@@ -314,55 +313,6 @@ async def test_generate_webui_title_ignores_cron_internal_turns(tmp_path: Path)
     loop.provider.chat_with_retry.assert_not_awaited()
 
 
-def test_webui_title_update_uses_captured_llm_runtime(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    bus = MessageBus()
-    sessions = SessionManager(tmp_path)
-    scheduled: list[object] = []
-    captured: dict[str, object] = {}
-
-    async def fake_title_after_turn(**kwargs: object) -> bool:
-        captured.update(kwargs)
-        return False
-
-    monkeypatch.setattr(
-        "nanobot.session.webui_turns.maybe_generate_webui_title_after_turn",
-        fake_title_after_turn,
-    )
-    coordinator = WebuiTurnCoordinator(
-        bus=bus,
-        sessions=sessions,
-        schedule_background=lambda coro: scheduled.append(coro),
-    )
-    provider = MagicMock()
-    msg = InboundMessage(
-        channel="websocket",
-        sender_id="u1",
-        chat_id="chat1",
-        content="say hello",
-        metadata={"webui": True},
-    )
-
-    coordinator.capture_title_context(
-        "websocket:chat1",
-        msg,
-        LLMRuntime.capture(provider, "turn-model", context_window_tokens=32_768),
-    )
-    asyncio.run(coordinator.handle_turn_end(
-        msg,
-        session_key="websocket:chat1",
-        latency_ms=None,
-    ))
-
-    assert len(scheduled) == 1
-    asyncio.run(scheduled[0])  # type: ignore[arg-type]
-
-    assert captured["provider"] is provider
-    assert captured["model"] == "turn-model"
-
-
 def test_save_turn_keeps_multimodal_runtime_context_for_model_replay() -> None:
     loop = _mk_loop()
     session = Session(key="test:runtime-only")
@@ -763,10 +713,9 @@ def test_unified_session_route_ignores_non_user_destinations(
     assert session.metadata[LAST_CHANNEL_METADATA_KEY] == "telegram:existing"
 
 
-# 1x1 PNG used by the media-persistence tests. ``extract_documents`` runs
+# 1x1 PNG used by the media-persistence tests. Attachment preparation filters
-# at the top of ``_process_message`` and filters ``msg.media`` down to
+# ``msg.media`` down to paths that magic-byte-sniff as images, so the test
-# paths that magic-byte-sniff as images, so the test fixture needs real
+# fixture needs real bytes on disk (not just placeholder paths).
-# bytes on disk (not just placeholder paths).
 _PNG_1X1 = (
     b"\x89PNG\r\n\x1a\n"
     b"\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
@@ -1386,7 +1335,7 @@ async def test_stop_preserves_runtime_checkpoint_for_next_turn(tmp_path: Path) -
 
     first_msg = InboundMessage(channel="feishu", sender_id="u1", chat_id="c4", content="keep progress")
     task = asyncio.create_task(loop._process_message(first_msg))
-    loop._active_tasks[first_msg.session_key] = [task]
+    loop._active_tasks[first_msg.session_key] = {task}
     await asyncio.wait_for(checkpoint_saved.wait(), timeout=1.0)
 
     stop_msg = InboundMessage(channel="feishu", sender_id="u1", chat_id="c4", content="/stop")
@@ -1451,7 +1400,7 @@ async def test_system_subagent_followup_is_persisted_before_prompt_assembly(tmp_
 
     runtime = loop.llm_runtime()
     seen: dict[str, object] = {}
-    record_runtime = MagicMock(wraps=loop._runtime_events().record_turn_runtime)
+    record_runtime = MagicMock(wraps=loop.runtime_event_publisher.record_turn_runtime)
     loop.runtime_event_publisher.record_turn_runtime = record_runtime
 
     async def fake_run_agent_loop(initial_messages, **kwargs):
@@ -1691,7 +1640,6 @@ def test_subagent_followup_uses_user_model_input_and_assistant_history(tmp_path:
     projected = builder.build_messages(
         history=history,
         current_message="subagent result",
-        current_role="user",
         channel="cli",
     )
 

tests/agent/test_memory_store.py

@@ -235,11 +235,23 @@ class TestHistoryWithCursor:
         store.append_history("event 3")
         store.append_history("event 4")
         store.append_history("event 5")
+        store.set_last_dream_cursor(5)
         store.compact_history()
         entries = store.read_unprocessed_history(since_cursor=0)
         assert len(entries) == 2
         assert entries[0]["cursor"] in {4, 5}
 
+    def test_compact_history_preserves_entries_after_dream_cursor(self, tmp_path):
+        store = MemoryStore(tmp_path, max_history_entries=50)
+        for index in range(1, 101):
+            store.append_history(f"event {index}")
+        store.set_last_dream_cursor(20)
+
+        store.compact_history()
+
+        entries = store.read_unprocessed_history(since_cursor=0)
+        assert [entry["cursor"] for entry in entries] == list(range(21, 101))
+
     def test_write_entries_uses_atomic_write(self, tmp_path):
         """_write_entries uses temp file + os.replace for atomicity."""
         store = MemoryStore(tmp_path)

tests/agent/test_model_runtime_resolver.py

@@ -95,6 +95,33 @@ def test_resolver_resolves_preset_without_mutating_selected_runtime() -> None:
     assert resolved.generation == GenerationSettings(0.5, 512, None)
 
 
+def test_static_presets_keep_image_capability_request_scoped() -> None:
+    provider = _provider()
+    provider.supports_image_input = None
+    resolver = ModelRuntimeResolver(
+        _runtime(provider),
+        model_presets={
+            "vision": ModelPresetConfig(
+                model="shared-model",
+                supports_image_input=True,
+            ),
+            "text": ModelPresetConfig(
+                model="shared-model",
+                supports_image_input=False,
+            ),
+        },
+    )
+
+    vision = resolver.resolve_preset("vision")
+    text = resolver.resolve_preset("text")
+
+    assert vision.provider is provider
+    assert text.provider is provider
+    assert vision.supports_image_input is True
+    assert text.supports_image_input is False
+    assert provider.supports_image_input is None
+
+
 def test_resolver_reuses_preset_until_runtime_config_is_invalidated() -> None:
     initial = _runtime()
     preset = ModelPresetConfig(model="fast-model")

tests/agent/test_onboard_logic.py

@@ -537,7 +537,7 @@ class TestRunOnboardExitBehavior:
 
         def fake_configure_general_settings(config, section):
             if section == "Agent Settings":
-                config.agents.defaults.model = "test/provider-model"
+                config.resolve_default_preset().model = "test/provider-model"
 
         monkeypatch.setattr(onboard_wizard, "_show_main_menu_header", lambda: None)
         monkeypatch.setattr(onboard_wizard, "_select_with_back", fake_select_with_back)
@@ -1997,7 +1997,7 @@ class TestModelPresetWizard:
         config.model_presets["fast"] = ModelPresetConfig(model="gpt-4.1-mini")
         config.model_presets["power"] = ModelPresetConfig(model="gpt-4.1")
         _sync_preset_cache(config)
-        assert _MODEL_PRESET_CACHE == {"fast", "power"}
+        assert _MODEL_PRESET_CACHE == {"default", "fast", "power"}
         _MODEL_PRESET_CACHE.clear()
 
     def test_model_preset_add(self, monkeypatch):
@@ -2106,10 +2106,9 @@ class TestModelPresetWizard:
         assert defaults.model_preset == "fast"
         _MODEL_PRESET_CACHE.clear()
 
-    def test_model_preset_field_handler_clear(self, monkeypatch):
+    def test_model_preset_field_handler_selects_default(self, monkeypatch):
-        """_handle_model_preset_field should clear preset when Clear value is chosen."""
+        """The concrete default preset replaces the legacy clear selection."""
         from nanobot.cli.onboard import (
-            _CLEAR_CHOICE,
             _MODEL_PRESET_CACHE,
             _handle_model_preset_field,
         )
@@ -2118,11 +2117,11 @@ class TestModelPresetWizard:
         _MODEL_PRESET_CACHE.clear()
         _MODEL_PRESET_CACHE.add("fast")
 
-        monkeypatch.setattr(onboard_wizard, "_select_with_back", lambda *a, **kw: _CLEAR_CHOICE)
+        monkeypatch.setattr(onboard_wizard, "_select_with_back", lambda *a, **kw: "default")
 
         defaults = AgentDefaults(model_preset="fast")
         _handle_model_preset_field(defaults, "model_preset", "Model Preset", "fast")
-        assert defaults.model_preset is None
+        assert defaults.model_preset == "default"
         _MODEL_PRESET_CACHE.clear()
 
     def test_main_menu_dispatch_includes_model_presets(self):
@@ -2208,13 +2207,13 @@ class TestModelPresetWizard:
     def test_provider_field_handler(self, monkeypatch):
         """_handle_provider_field should set provider from choices."""
         from nanobot.cli.onboard import _handle_provider_field
-        from nanobot.config.schema import AgentDefaults
+        from nanobot.config.schema import ModelPresetConfig
 
         monkeypatch.setattr(onboard_wizard, "_select_with_back", lambda *a, **kw: "anthropic")
 
-        defaults = AgentDefaults()
+        preset = ModelPresetConfig(model="anthropic/claude-opus-4-5")
-        _handle_provider_field(defaults, "provider", "Provider", "auto")
+        _handle_provider_field(preset, "provider", "Provider", "auto")
-        assert defaults.provider == "anthropic"
+        assert preset.provider == "anthropic"
 
     def test_search_provider_field_handler(self, monkeypatch):
         """_handle_search_provider_field should set the search engine from choices."""
@@ -2235,7 +2234,10 @@ class TestModelPresetWizard:
             _handle_search_provider_field,
             _resolve_field_handler,
         )
-        from nanobot.config.schema import AgentDefaults
+        from nanobot.config.schema import ModelPresetConfig
 
         assert _resolve_field_handler(WebSearchConfig(), "provider") is _handle_search_provider_field
-        assert _resolve_field_handler(AgentDefaults(), "provider") is _handle_provider_field
+        assert (
+            _resolve_field_handler(ModelPresetConfig(model="test"), "provider")
+            is _handle_provider_field
+        )

tests/agent/test_runner_fallback.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Any
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from loguru import logger
@@ -46,6 +46,7 @@ def _fallback(
     context_window_tokens: int = 65_536,
     temperature: float = 0.1,
     reasoning_effort: str | None = None,
+    supports_image_input: bool | None = None,
 ) -> ModelPresetConfig:
     return ModelPresetConfig(
         model=model,
@@ -54,6 +55,7 @@ def _fallback(
         context_window_tokens=context_window_tokens,
         temperature=temperature,
         reasoning_effort=reasoning_effort,
+        supports_image_input=supports_image_input,
     )
 
 
@@ -93,33 +95,35 @@ def test_fallback_models_default_empty() -> None:
     assert defaults.fallback_models == []
 
 
-def test_fallback_models_accept_preset_refs_and_inline_configs() -> None:
+def test_fallback_models_accept_preset_refs() -> None:
-    from nanobot.config.schema import Config, InlineFallbackConfig
+    from nanobot.config.schema import Config
 
     config = Config.model_validate({
         "agents": {
             "defaults": {
-                "fallbackModels": [
+                "fallbackModels": ["deep"]
-                    "deep",
-                    {
-                        "provider": "openai",
-                        "model": "gpt-4.1",
-                        "maxTokens": 4096,
-                    },
-                ]
             }
         },
         "modelPresets": {
+            "default": {"provider": "openai", "model": "gpt-4.1"},
             "deep": {"provider": "anthropic", "model": "claude-opus-4-7"}
         },
     })
 
-    assert config.agents.defaults.fallback_models[0] == "deep"
+    assert config.agents.defaults.fallback_models == ["deep"]
-    assert config.agents.defaults.fallback_models[1] == InlineFallbackConfig(
+
-        provider="openai",
+
-        model="gpt-4.1",
+def test_fallback_models_reject_inline_configs_after_schema_migration() -> None:
-        max_tokens=4096,
+    from nanobot.config.schema import Config
-    )
+
+    with pytest.raises(ValueError):
+        Config.model_validate({
+            "agents": {
+                "defaults": {
+                    "fallbackModels": [{"provider": "openai", "model": "gpt-4.1"}]
+                }
+            }
+        })
 
 
 def test_fallback_model_preset_ref_must_exist() -> None:
@@ -128,7 +132,7 @@ def test_fallback_model_preset_ref_must_exist() -> None:
     with pytest.raises(ValueError, match="fallback_models.*not found"):
         Config.model_validate({
             "agents": {"defaults": {"fallbackModels": ["missing"]}},
-            "modelPresets": {},
+            "modelPresets": {"default": {"model": "primary"}},
         })
 
 
@@ -144,6 +148,7 @@ def test_provider_signature_tracks_fallback_presets_and_provider_config() -> Non
             }
         },
         "modelPresets": {
+            "default": {"model": "primary", "provider": "openai"},
             "fast": {"model": "openai/gpt-4.1", "provider": "openai"},
             "deep": {"model": "anthropic/claude-sonnet-4-6", "provider": "anthropic"},
         },
@@ -190,6 +195,7 @@ def test_provider_snapshot_uses_smallest_fallback_context_window() -> None:
             }
         },
         "modelPresets": {
+            "default": {"model": "primary", "provider": "openai"},
             "fast": {
                 "model": "openai/gpt-4.1",
                 "provider": "openai",
@@ -213,36 +219,49 @@ def test_provider_snapshot_uses_smallest_fallback_context_window() -> None:
     assert snapshot.context_window_tokens == 64000
 
 
-def test_inline_fallback_reasoning_effort_does_not_inherit_primary() -> None:
+def test_provider_signature_tracks_fallback_image_capability() -> None:
     from nanobot.config.schema import Config
     from nanobot.providers.factory import provider_signature
 
-    config = Config.model_validate({
+    base = {
         "agents": {
             "defaults": {
                 "modelPreset": "fast",
-                "fallbackModels": [
+                "fallbackModels": ["fallback"],
-                    {"provider": "openai", "model": "gpt-4.1"}
-                ],
             }
         },
         "modelPresets": {
+            "default": {"model": "primary"},
             "fast": {
                 "model": "anthropic/claude-opus-4-5",
                 "provider": "anthropic",
                 "reasoningEffort": "high",
-            }
+            },
+            "fallback": {
+                "provider": "openai",
+                "model": "gpt-4.1",
+                "supportsImageInput": False,
+            },
         },
         "providers": {
             "anthropic": {"apiKey": "primary-key"},
             "openai": {"apiKey": "fallback-key"},
         },
-    })
+    }
+    changed = {
+        **base,
+        "modelPresets": {
+            **base["modelPresets"],
+            "fallback": {
+                **base["modelPresets"]["fallback"],
+                "supportsImageInput": True,
+            },
+        },
+    }
 
-    signature = provider_signature(config)
+    assert provider_signature(Config.model_validate(base)) != provider_signature(
-    fallback_signatures = signature[-1]
+        Config.model_validate(changed)
-
+    )
-    assert fallback_signatures[0][13] is None
 
 
 # -- FallbackProvider tests --
@@ -333,6 +352,204 @@ class TestFallbackOnPrimaryError:
             for line in logs
         )
 
+    @pytest.mark.asyncio
+    async def test_primary_and_fallback_apply_their_own_image_capability(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider("primary", _error_response())
+        primary.supports_image_input = True
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        factory = MagicMock(return_value=fallback)
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", supports_image_input=False)
+            ],
+            provider_factory=factory,
+        )
+
+        result = await fb.chat(messages=image_messages, model="primary-model")
+
+        assert result.content == "fallback ok"
+        primary_content = primary.chat_calls[0]["messages"][0]["content"]
+        fallback_content = fallback.chat_calls[0]["messages"][0]["content"]
+        assert any(block.get("type") == "image_url" for block in primary_content)
+        assert all(block.get("type") != "image_url" for block in fallback_content)
+
+    @pytest.mark.asyncio
+    async def test_text_only_primary_does_not_remove_images_from_vision_fallback(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider("primary", _error_response())
+        primary.supports_image_input = False
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        factory = MagicMock(return_value=fallback)
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", supports_image_input=True)
+            ],
+            provider_factory=factory,
+        )
+
+        result = await fb.chat(messages=image_messages, model="primary-model")
+
+        assert result.content == "fallback ok"
+        primary_content = primary.chat_calls[0]["messages"][0]["content"]
+        fallback_content = fallback.chat_calls[0]["messages"][0]["content"]
+        assert all(block.get("type") != "image_url" for block in primary_content)
+        assert any(block.get("type") == "image_url" for block in fallback_content)
+
+    @pytest.mark.asyncio
+    async def test_explicit_vision_rejection_advances_to_vision_fallback(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider(
+            "primary",
+            _make_response(
+                "image input is not supported",
+                finish_reason="error",
+                error_kind="invalid_request",
+                error_status_code=400,
+            ),
+        )
+        primary.supports_image_input = True
+        fallback = _FakeProvider("fallback", _make_response("fallback ok"))
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", supports_image_input=True)
+            ],
+            provider_factory=MagicMock(return_value=fallback),
+        )
+
+        result = await fb.chat(messages=image_messages, model="primary-model")
+
+        assert result.content == "fallback ok"
+        fallback_content = fallback.chat_calls[0]["messages"][0]["content"]
+        assert any(block.get("type") == "image_url" for block in fallback_content)
+        assert fb._primary_failures == 0
+
+    @pytest.mark.asyncio
+    async def test_auto_primary_retries_without_images_through_retry_wrapper(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider("primary")
+        primary.chat = AsyncMock(side_effect=[
+            _make_response(
+                "image input is not supported",
+                finish_reason="error",
+                error_kind="invalid_request",
+            ),
+            _make_response("primary text fallback ok"),
+        ])
+        fallback_factory = MagicMock()
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[_fallback("fallback-a", supports_image_input=True)],
+            provider_factory=fallback_factory,
+        )
+
+        result = await fb.chat_with_retry(
+            messages=image_messages,
+            model="primary-model",
+        )
+
+        assert result.content == "primary text fallback ok"
+        assert primary.chat.await_count == 2
+        retry_content = primary.chat.await_args_list[1].kwargs["messages"][0]["content"]
+        assert all(block.get("type") != "image_url" for block in retry_content)
+        fallback_factory.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_streaming_vision_rejection_advances_to_text_fallback(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider("primary")
+        primary.supports_image_input = True
+        primary.chat_stream = AsyncMock(return_value=_make_response(
+            "image input is not supported",
+            finish_reason="error",
+            error_kind="invalid_request",
+            error_status_code=400,
+        ))
+        fallback = _FakeProvider("fallback")
+        fallback.chat_stream = AsyncMock(return_value=_make_response("fallback ok"))
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[
+                _fallback("fallback-a", supports_image_input=False)
+            ],
+            provider_factory=MagicMock(return_value=fallback),
+        )
+
+        result = await fb.chat_stream(
+            messages=image_messages,
+            model="primary-model",
+            on_content_delta=AsyncMock(),
+        )
+
+        assert result.content == "fallback ok"
+        fallback_content = fallback.chat_stream.await_args.kwargs["messages"][0]["content"]
+        assert all(block.get("type") != "image_url" for block in fallback_content)
+
+    @pytest.mark.asyncio
+    async def test_auto_capability_does_not_retry_after_streaming_content(self) -> None:
+        image_messages = [{
+            "role": "user",
+            "content": [{
+                "type": "image_url",
+                "image_url": {"url": "data:image/png;base64,abc"},
+            }],
+        }]
+        primary = _FakeProvider(
+            "primary",
+            _make_response(
+                "model does not support images",
+                finish_reason="error",
+                error_kind="invalid_request",
+            ),
+        )
+        fb = FallbackProvider(
+            primary=primary,
+            fallback_presets=[_fallback("fallback-a")],
+            provider_factory=MagicMock(),
+        )
+
+        result = await fb.chat_stream(
+            messages=image_messages,
+            model="primary-model",
+            on_content_delta=AsyncMock(),
+        )
+
+        assert result.finish_reason == "error"
+        assert len(primary.chat_stream_calls) == 1
+
 
 class TestNoFallbackWhenContentStreamed:
     @pytest.mark.asyncio

tests/agent/test_runner_governance.py

@@ -10,7 +10,6 @@ import pytest
 from agent.runner_helpers import make_run_spec
 from nanobot.agent.context_governance import (
     BACKFILL_CONTENT,
-    MICROCOMPACT_KEEP_RECENT,
     ContextGovernanceConfig,
     ContextGovernor,
 )
@@ -495,7 +494,7 @@ def test_microcompact_skips_when_prompt_under_hard_budget(monkeypatch):
     tools = MagicMock()
     tools.get_definitions.return_value = []
 
-    total = MICROCOMPACT_KEEP_RECENT + 5
+    total = 15
     long_content = "x" * 600
     messages = _microcompact_messages(total=total, tool_name="read_file", content=long_content)
     spec = make_run_spec(provider,
@@ -529,7 +528,7 @@ def test_microcompact_overflow_compacts_to_low_watermark(monkeypatch):
     tools = MagicMock()
     tools.get_definitions.return_value = []
 
-    total = MICROCOMPACT_KEEP_RECENT + 8
+    total = 18
     long_content = "x" * 600
     messages = _microcompact_messages(total=total, tool_name="read_file", content=long_content)
     spec = make_run_spec(provider,
@@ -617,7 +616,7 @@ def test_context_governor_keeps_compaction_boundary_stable(monkeypatch):
     tools = MagicMock()
     tools.get_definitions.return_value = []
 
-    total = MICROCOMPACT_KEEP_RECENT + 8
+    total = 18
     long_content = "x" * 600
     messages = _microcompact_messages(total=total, tool_name="read_file", content=long_content)
     spec = make_run_spec(provider,
@@ -658,7 +657,7 @@ def test_microcompact_preserves_short_results(monkeypatch):
     tools = MagicMock()
     tools.get_definitions.return_value = []
 
-    total = MICROCOMPACT_KEEP_RECENT + 5
+    total = 15
     messages = _microcompact_messages(total=total, tool_name="exec", content="short")
     spec = make_run_spec(provider,
         initial_messages=messages,
@@ -690,7 +689,7 @@ def test_microcompact_skips_non_compactable_tools(monkeypatch):
     tools = MagicMock()
     tools.get_definitions.return_value = []
 
-    total = MICROCOMPACT_KEEP_RECENT + 5
+    total = 15
     long_content = "y" * 1000
     messages = _microcompact_messages(total=total, tool_name="message", content=long_content)
     spec = make_run_spec(provider,

tests/agent/test_runner_runtime_identity.py

@@ -19,9 +19,11 @@ async def test_active_run_keeps_provider_captured_at_admission() -> None:
     second_provider = MagicMock(spec=LLMProvider)
     first_provider.generation = GenerationSettings(temperature=0.2, max_tokens=2048)
     second_provider.generation = GenerationSettings(temperature=0.9, max_tokens=512)
+    first_provider.supports_image_input = False
     first_calls = 0
     second_calls = 0
     request_temperatures: list[float] = []
+    request_image_capabilities: list[bool | None] = []
     selected_runtime = LLMRuntime.capture(
         first_provider,
         "captured-model",
@@ -33,6 +35,7 @@ async def test_active_run_keeps_provider_captured_at_admission() -> None:
         nonlocal first_calls, selected_runtime
         first_calls += 1
         request_temperatures.append(kwargs["temperature"])
+        request_image_capabilities.append(kwargs["supports_image_input"])
         selected_runtime = LLMRuntime.capture(
             second_provider,
             "future-model",
@@ -68,4 +71,5 @@ async def test_active_run_keeps_provider_captured_at_admission() -> None:
     assert first_calls == 2
     assert second_calls == 0
     assert request_temperatures == [0.2, 0.2]
+    assert request_image_capabilities == [False, False]
     assert selected_runtime.provider is second_provider