chore: remove unused chat send hint translations

Fix agent loop reload and panic cleanup stability

.gitattributes

@@ -1,3 +1,4 @@
 # Ensure shell scripts always use LF line endings regardless of OS.
 *.sh text eol=lf
 docker/entrypoint.sh text eol=lf
+.gitignore text eol=lf

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: [sipeed]

.gitignore

@@ -73,3 +73,4 @@ web/backend/dist/*
 docker/data
 
 .omc/
+.worktrees/

Makefile

@@ -27,7 +27,7 @@ endif
 VERSION?=$(if $(VERSION_RAW),$(VERSION_RAW),dev)
 GIT_COMMIT=$(if $(GIT_COMMIT_RAW),$(GIT_COMMIT_RAW),dev)
 BUILD_TIME=$(if $(BUILD_TIME_RAW),$(BUILD_TIME_RAW),dev)
-GO_VERSION=$(if $(GO_VERSION_RAW),$(GO_VERSION_RAW),unknown)
+GO_VERSION=$(if $(GO_VERSION_RAW),$(firstword $(GO_VERSION_RAW)),unknown)
 CONFIG_PKG=github.com/sipeed/picoclaw/pkg/config
 LDFLAGS=-X $(CONFIG_PKG).Version=$(VERSION) -X $(CONFIG_PKG).GitCommit=$(GIT_COMMIT) -X $(CONFIG_PKG).BuildTime=$(BUILD_TIME) -X $(CONFIG_PKG).GoVersion=$(GO_VERSION) -s -w
 

README.md

@@ -64,6 +64,16 @@
   </a>
 </p>
 
+2026-05-28 🚀 **v0.2.9 Released!** MCP server management in Web UI, configurable Sogou-backed web search, tool feedback animation in channels, `pretty_print` and `disable_escape_html` defaults, and numerous bug fixes across providers and channels.
+
+2026-05-14 🚀 **v0.2.8 Released!** MCP CLI commands (`show`, `add`, `list`, `remove`, `test`, `edit`), empty object instead of null for MCP tool parameters, and build fixes.
+
+2026-05-07 🚀 **v0.2.7 Released!** Configurable Sogou-backed web search, channel tool feedback animation, linter fixes.
+
+2026-04-23 🚀 **v0.2.6 Released!** Hooks with respond action and comprehensive documentation, isolation support, help banner fix.
+
+2026-04-11 🚀 **v0.2.5 Released!** Zoneinfo from TZ/ZONEINFO env, Matrix CommonMark rendering alignment, `read_file` by lines.
+
 2026-03-31 📱 **Android Support!** PicoClaw now runs on Android! Download the APK at [picoclaw.io](https://picoclaw.io/download)
 
 2026-03-25 🚀 **v0.2.4 Released!** Agent architecture overhaul (SubTurn, Hooks, Steering, EventBus), WeChat/WeCom integration, security hardening (.security.yml, sensitive data filtering), new providers (AWS Bedrock, Azure, Xiaomi MiMo), and 35 bug fixes. PicoClaw has reached **26K Stars**!
@@ -321,6 +331,8 @@ Download the APK from [picoclaw.io](https://picoclaw.io/download/) and install d
 
 **Option 2: Termux**
 
+For a full command-line setup checklist, see the [Android Termux Guide](docs/guides/android-termux.md).
+
 <details>
 <summary><b>Terminal Launcher (for resource-constrained environments)</b></summary>
 
@@ -413,12 +425,14 @@ PicoClaw supports 30+ LLM providers through the `model_list` configuration. Use
 | [Ollama](https://ollama.com/) | `ollama/` | Not needed | Local models, self-hosted |
 | [vLLM](https://docs.vllm.ai/) | `vllm/` | Not needed | Local deployment, OpenAI-compatible |
 | [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Varies | Proxy for 100+ providers |
-| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Required | Enterprise Azure deployment |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | API key or Entra ID** | Enterprise Azure deployment |
 | [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Device code login |
 | [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
 | [AWS Bedrock](https://console.aws.amazon.com/bedrock)* | `bedrock/` | AWS credentials | Claude, Llama, Mistral on AWS |
 
 > \* AWS Bedrock requires build tag: `go build -tags bedrock`. Set `api_base` to a region name (e.g., `us-east-1`) for automatic endpoint resolution across all AWS partitions (aws, aws-cn, aws-us-gov). When using a full endpoint URL instead, you must also configure `AWS_REGION` via environment variable or AWS config/profile.
+>
+> \*\* Azure OpenAI uses `api_key` when set. If `api_key` is omitted, the provider falls back to Microsoft Entra ID via `DefaultAzureCredential` (env vars, workload identity, managed identity, Azure CLI, etc.). The Entra ID path requires build tag: `go build -tags azidentity`.
 
 <details>
 <summary><b>Local deployment (Ollama, vLLM, etc.)</b></summary>
@@ -497,6 +511,7 @@ PicoClaw can search the web to provide up-to-date information. Configure in `too
 | [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Required | 1500/month (daily allocation) | AI-powered, China-optimized |
 | [Tavily](https://tavily.com) | Required | 1000 queries/month | Optimized for AI Agents |
 | [Brave Search](https://brave.com/search/api) | Required | 2000 queries/month | Fast and private |
+| [Kagi Search](https://help.kagi.com/kagi/api/search.html) | Required | Paid/limited by API setup | Premium search results |
 | [Perplexity](https://www.perplexity.ai) | Required | Paid | AI-powered search |
 | [SearXNG](https://github.com/searxng/searxng) | Not needed | Self-hosted | Free metasearch engine |
 | [GLM Search](https://open.bigmodel.cn/) | Required | Varies | Zhipu web search |

cmd/picoclaw/internal/agent/helpers.go

@@ -56,12 +56,23 @@ func agentCmd(message, sessionKey, model string, debug bool) error {
 
 	// Print agent startup info (only for interactive mode)
 	startupInfo := agentLoop.GetStartupInfo()
-	logger.InfoCF("agent", "Agent initialized",
-		map[string]any{
-			"tools_count":      startupInfo["tools"].(map[string]any)["count"],
-			"skills_total":     startupInfo["skills"].(map[string]any)["total"],
-			"skills_available": startupInfo["skills"].(map[string]any)["available"],
-		})
+	toolsInfo, ok := startupInfo["tools"].(map[string]any)
+	if !ok {
+		toolsInfo = nil
+	}
+	skillsInfo, ok := startupInfo["skills"].(map[string]any)
+	if !ok {
+		skillsInfo = nil
+	}
+	logFields := map[string]any{}
+	if toolsInfo != nil {
+		logFields["tools_count"] = toolsInfo["count"]
+	}
+	if skillsInfo != nil {
+		logFields["skills_total"] = skillsInfo["total"]
+		logFields["skills_available"] = skillsInfo["available"]
+	}
+	logger.InfoCF("agent", "Agent initialized", logFields)
 
 	if message != "" {
 		ctx := context.Background()

cmd/picoclaw/internal/onboard/command.go

@@ -1,14 +1,12 @@
 package onboard
 
 import (
-	"embed"
-
 	"github.com/spf13/cobra"
+
+	picoclaw "github.com/sipeed/picoclaw"
 )
 
-//go:generate go run ../../../../scripts/copydir.go ../../../../workspace ./workspace
-//go:embed workspace
-var embeddedFiles embed.FS
+var embeddedFiles = picoclaw.OnboardWorkspace
 
 func NewOnboardCommand() *cobra.Command {
 	var encrypt bool

cmd/picoclaw/internal/skills/helpers.go

@@ -79,7 +79,7 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, target string)
 	defer cancel()
 
 	if err = os.MkdirAll(filepath.Join(workspace, "skills"), 0o755); err != nil {
-		return fmt.Errorf("\u2717 failed to create skills directory: %v", err)
+		return fmt.Errorf("\u2717 failed to create skills directory: %w", err)
 	}
 
 	result, err := registry.DownloadAndInstall(ctx, target, "", targetDir)
@@ -345,9 +345,11 @@ func copyDirectory(src, dst string) error {
 		if err != nil {
 			return err
 		}
-		defer dstFile.Close()
 
-		_, err = io.Copy(dstFile, srcFile)
-		return err
+		_, copyErr := io.Copy(dstFile, srcFile)
+		if closeErr := dstFile.Close(); closeErr != nil && copyErr == nil {
+			return fmt.Errorf("close destination file %s: %w", dstPath, closeErr)
+		}
+		return copyErr
 	})
 }

cmd/picoclaw/main.go

@@ -9,6 +9,8 @@ package main
 import (
 	"fmt"
 	"os"
+	"runtime"
+	"strings"
 	"time"
 
 	"github.com/spf13/cobra"
@@ -33,6 +35,49 @@ import (
 
 var rootNoColor bool
 
+// initTermuxSSL detects Termux environment and sets SSL_CERT_FILE if not already set.
+// This fixes X509 certificate errors when running PicoClaw inside Termux or termux-chroot.
+// See: https://github.com/sipeed/picoclaw/issues/2944
+func initTermuxSSL() {
+	// Only applicable on Linux/Android
+	if runtime.GOOS != "linux" && runtime.GOOS != "android" {
+		return
+	}
+
+	// Skip if already set
+	if os.Getenv("SSL_CERT_FILE") != "" {
+		return
+	}
+
+	// Check for Termux prefix in PATH or HOME
+	home := os.Getenv("HOME")
+	path := os.Getenv("PATH")
+
+	isTermux := strings.Contains(home, "com.termux") ||
+		strings.Contains(path, "com.termux") ||
+		strings.Contains(home, "/data/data/com.termux")
+
+	if !isTermux {
+		return
+	}
+
+	// Check common CA bundle locations in Termux
+	caPaths := []string{
+		"$PREFIX/etc/tls/cert.pem",
+		os.Getenv("PREFIX") + "/etc/tls/cert.pem",
+		"/data/data/com.termux/files/usr/etc/tls/cert.pem",
+		"/usr/etc/tls/cert.pem",
+	}
+
+	for _, caPath := range caPaths {
+		expanded := os.ExpandEnv(caPath)
+		if _, err := os.Stat(expanded); err == nil {
+			os.Setenv("SSL_CERT_FILE", expanded)
+			return
+		}
+	}
+}
+
 func syncCliUIColor(root *cobra.Command) {
 	no, _ := root.PersistentFlags().GetBool("no-color")
 	cliui.Init(no || os.Getenv("NO_COLOR") != "" || os.Getenv("TERM") == "dumb")
@@ -123,6 +168,9 @@ const (
 )
 
 func main() {
+	// Initialize Termux SSL certificate detection before anything else
+	initTermuxSSL()
+
 	cliui.Init(earlyColorDisabled())
 
 	if earlyColorDisabled() {

config/config.example.json

@@ -329,6 +329,13 @@
         "base_url": "",
         "max_results": 0
       },
+      "kagi": {
+        "enabled": false,
+        "api_key": "",
+        "api_keys": ["YOUR_KAGI_API_KEY"],
+        "base_url": "https://kagi.com/api/v1/search",
+        "max_results": 5
+      },
       "provider": "auto",
       "sogou": {
         "enabled": true,

docs/guides/README.md

@@ -3,6 +3,7 @@
 Task-oriented guides for setup, configuration, and common PicoClaw workflows.
 
 - [Docker & Quick Start Guide](docker.md): install and run PicoClaw with Docker or the launcher.
+- [Android Termux Guide](android-termux.md): run the PicoClaw terminal binary on an ARM64 Android phone.
 - [Configuration Guide](configuration.md): environment variables, workspace layout, routing, and sandbox settings.
 - [Session Guide](session-guide.md): how session scope affects memory sharing, summaries, and isolation.
 - [Routing Guide](routing-guide.md): agent dispatch, session overrides, and light-model routing.

docs/guides/android-termux.md

@@ -0,0 +1,88 @@
+# Android Termux Guide
+
+> Back to [Guides](README.md)
+
+This guide covers running the PicoClaw terminal binary on an ARM64 Android phone with Termux. Use the APK from [picoclaw.io](https://picoclaw.io/download/) if you want the Android app experience; use Termux when you want a lightweight command-line install on an older or resource-constrained device.
+
+## Requirements
+
+- ARM64 Android device. Run `uname -m` in Termux and use this guide when it prints `aarch64`.
+- Termux installed from [Termux GitHub Releases](https://github.com/termux/termux-app/releases) or F-Droid.
+- Network access for downloading the release and calling your LLM provider.
+- An API key for at least one configured model provider.
+
+## Install PicoClaw
+
+Open Termux and install the packages used by the release archive and chroot wrapper:
+
+```bash
+pkg update
+pkg install -y wget tar proot
+```
+
+Download and unpack the ARM64 Linux release:
+
+```bash
+mkdir -p ~/picoclaw
+cd ~/picoclaw
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+chmod +x ./picoclaw
+```
+
+Start first-run setup through `termux-chroot`, which gives the Linux binary a more standard filesystem layout than a raw Android userspace:
+
+```bash
+termux-chroot ./picoclaw onboard
+```
+
+## Configure
+
+Edit the generated config and add at least one model provider API key:
+
+```bash
+vim ~/.picoclaw/config.json
+```
+
+The default workspace is `~/.picoclaw/workspace`. If you want PicoClaw to read or write Android shared storage, run `termux-setup-storage` first and then point the workspace or any file paths at the mounted storage directory.
+
+See [Configuration Guide](configuration.md) and [Providers & Model Configuration](providers.md) for the available config fields and provider examples.
+
+## Run
+
+Use one-shot agent mode to confirm the installation:
+
+```bash
+termux-chroot ./picoclaw agent -m "Hello from Termux"
+```
+
+For long-running use, start the gateway:
+
+```bash
+termux-chroot ./picoclaw gateway
+```
+
+Keep the Termux session open while PicoClaw is running. Android battery optimization can stop background work, so disable battery optimization for Termux if you expect PicoClaw to keep running after the screen locks.
+
+## Update
+
+Your config and workspace live under `~/.picoclaw`, so updating the binary does not remove them:
+
+```bash
+cd ~/picoclaw
+rm -f picoclaw_Linux_arm64.tar.gz
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+chmod +x ./picoclaw
+termux-chroot ./picoclaw version
+```
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| `permission denied` | Run `chmod +x ./picoclaw` after unpacking the archive. |
+| `not found` after running `./picoclaw` | Confirm `uname -m` prints `aarch64` and that you downloaded `picoclaw_Linux_arm64.tar.gz`. |
+| Files or paths behave differently than Linux | Run PicoClaw through `termux-chroot` instead of calling the binary directly. |
+| Provider requests fail | Check the API key and network access in `~/.picoclaw/config.json`. |
+| PicoClaw stops when the phone sleeps | Disable Android battery optimization for Termux and keep a foreground Termux session active. |

docs/guides/configuration.md

@@ -400,6 +400,7 @@ Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous
 |------------|------|---------|-------------|
 | `tools.allow_read_paths` | string[] | `[]` | Additional paths allowed for reading outside workspace |
 | `tools.allow_write_paths` | string[] | `[]` | Additional paths allowed for writing outside workspace |
+| `tools.message.media_enabled` | bool | `false` | Allows the `message` tool to attach local media files by path. This is separate from `tools.send_file.enabled`; enable it only when unified text/media/caption delivery is intended. |
 
 ### Read File Mode
 
@@ -454,7 +455,7 @@ Use `mode = lines` when:
   "tools": {
     "read_file": {
       "enabled": true,
-       "mode": "lines",
+      "mode": "lines",
       "max_read_file_size": 65536
     }
   }
@@ -837,6 +838,9 @@ Legacy Telegram environment variables remain compatible: `PICOCLAW_CHANNELS_TELE
 
 Failure behavior is intentionally conservative: if streaming fails before any visible chunk is sent, PicoClaw retries once through the normal `Chat()` path. If a chunk has already been shown to the user, PicoClaw does not send a second non-streaming answer, because that would duplicate visible output.
 
+For model-specific TTS request fields such as custom speech `voice` names or
+`response_format: "mp3"`, use `model_list[].extra_body`.
+
 #### Vendor-Specific Examples
 
 > **Tip**: You can omit `api_key` fields and store them in `.security.yml` for better security. See [Security Configuration](#-security-configuration-recommended).
@@ -855,6 +859,35 @@ Failure behavior is intentionally conservative: if streaming fails before any vi
 
 </details>
 
+<details>
+<summary><b>OpenRouter TTS (MAI Voice 2)</b></summary>
+
+```json
+{
+  "model_name": "mai-voice-2",
+  "provider": "openrouter",
+  "model": "microsoft/mai-voice-2",
+  "api_base": "https://openrouter.ai/api/v1",
+  "extra_body": {
+    "voice": "en-US-Harper:MAI-Voice-2",
+    "response_format": "mp3"
+  }
+  // api_key: set in .security.yml
+}
+```
+
+Pair this with:
+
+```json
+{
+  "voice": {
+    "tts_model_name": "mai-voice-2"
+  }
+}
+```
+
+</details>
+
 <details>
 <summary><b>VolcEngine (Doubao)</b></summary>
 

docs/guides/hardware-compatibility.md

@@ -97,7 +97,7 @@ Consumer products, routers, and industrial devices that have been tested with Pi
 
 Any ARM64 Android phone (2015+) with 1GB+ RAM. Install [Termux](https://github.com/termux/termux-app), use `proot` to run PicoClaw.
 
-> See [README: Run on old Android Phones](../../README.md#-run-on-old-android-phones) for setup instructions.
+> See the [Android Termux Guide](android-termux.md) for setup instructions.
 
 ### Desktop / Server / Cloud
 

docs/guides/providers.md

@@ -138,6 +138,9 @@ This design also enables **multi-agent support** with flexible provider selectio
 
 When streaming is disabled, omit the `streaming` block. Writing `"streaming": {"enabled": false}` is optional and not needed in generated or hand-written config.
 
+`extra_body` is especially useful for model-specific TTS fields on OpenAI-compatible
+speech routes, for example custom `voice` names or `response_format: "mp3"`.
+
 #### Tool Schema Compatibility
 
 By default, PicoClaw now forwards tool JSON Schemas unchanged.
@@ -205,6 +208,41 @@ If `voice.model_name` is not configured, PicoClaw will continue to fall back to
 }
 ```
 
+#### Voice Synthesis
+
+You can configure a dedicated text-to-speech model with `voice.tts_model_name`.
+When the provider needs model-specific TTS request fields, put them in
+`model_list[].extra_body`.
+
+Example with OpenRouter `microsoft/mai-voice-2`:
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "mai-voice-2",
+      "provider": "openrouter",
+      "model": "microsoft/mai-voice-2",
+      "api_base": "https://openrouter.ai/api/v1",
+      "extra_body": {
+        "voice": "en-US-Harper:MAI-Voice-2",
+        "response_format": "mp3"
+      },
+      "api_keys": ["sk-or-your-openrouter-key"]
+    }
+  ],
+  "voice": {
+    "tts_model_name": "mai-voice-2"
+  }
+}
+```
+
+Notes that matter:
+
+- PicoClaw still uses the OpenAI-compatible `/audio/speech` route for this setup.
+- The default TTS request uses `voice: alloy` and `response_format: opus`.
+- Override those defaults with `extra_body` when your selected TTS model requires different values.
+
 #### Vendor-Specific Examples
 
 **OpenAI**

docs/reference/cron.md

@@ -26,6 +26,41 @@ picoclaw cron add --name "Daily summary" --message "Summarize today's logs" --cr
 picoclaw cron add --name "Ping" --message "heartbeat" --every 300 --deliver
 ```
 
+## Agent Tool Actions
+
+The agent-facing `cron` tool supports these actions:
+
+- `add`: create a new job.
+- `list`: show accessible job names, ids, and schedules.
+- `get`: fetch one accessible persisted job by `job_id`, including its saved payload.
+- `update`: partially update one accessible job by `job_id`; omitted fields are preserved.
+- `remove`, `enable`, `disable`: existing management actions.
+
+When rescheduling an existing task, use `list -> get -> update`. Do not use
+`remove -> add` just to change the schedule, because recreating a job can drop
+the original prompt, delivery target, or command payload.
+
+Remote channel access is scoped to the current `channel/chat_id`: remote callers
+can only list, get, or update jobs whose saved `payload.channel` and `payload.to`
+match the current conversation. Command jobs include a shell command payload, so
+they can only be listed, inspected, or updated from internal channels.
+
+Example tool calls:
+
+```json
+{"action":"get","job_id":"79095b2f5685a0f2"}
+```
+
+```json
+{"action":"update","job_id":"79095b2f5685a0f2","cron_expr":"30 10 * * *"}
+```
+
+`update` accepts `name`, `message`, `command`, and exactly one schedule field
+(`at_seconds`, `every_seconds`, or `cron_expr`).
+Omit `command` to preserve it, set `command` to a non-empty string to replace
+it, or set `command` to `""` to clear it. Command updates require the same
+internal channel and confirmation gates as command creation.
+
 ## Execution Modes
 
 Jobs are stored with a message payload and can execute in three stable user-facing modes:

docs/reference/tools_configuration.md

@@ -126,6 +126,44 @@ Baidu Search uses the [Qianfan AI Search API](https://cloud.baidu.com/doc/qianfa
 | `api_keys`    | string[] | -       | Multiple API keys for rotation (takes priority over `api_key`) |
 | `max_results` | int      | 5       | Maximum number of results                      |
 
+### Kagi Search
+
+Kagi Search uses the official Kagi OpenAPI client for `POST /search` and returns normal web results from `data.search`.
+
+| Config        | Type     | Default                               | Description                                    |
+|---------------|----------|---------------------------------------|------------------------------------------------|
+| `enabled`     | bool     | false                                 | Enable Kagi Search                             |
+| `api_key`     | string   | -                                     | Kagi API key                                   |
+| `api_keys`    | string[] | -                                     | Multiple API keys for rotation (takes priority over `api_key`) |
+| `base_url`    | string   | `https://kagi.com/api/v1/search`      | Kagi Search API endpoint                       |
+| `max_results` | int      | 5                                     | Maximum number of results                      |
+
+```json
+{
+  "tools": {
+    "web": {
+      "provider": "kagi",
+      "kagi": {
+        "enabled": true,
+        "max_results": 5,
+        "base_url": "https://kagi.com/api/v1/search"
+      }
+    }
+  }
+}
+```
+
+Store Kagi API keys in `.security.yml`:
+
+```yaml
+web:
+  kagi:
+    api_keys:
+      - "YOUR_KAGI_API_KEY"
+```
+
+Kagi API usage may be billed or limited separately from a normal Kagi subscription, depending on your account and API setup.
+
 ### Tavily
 
 | Config        | Type   | Default | Description               |
@@ -171,6 +209,7 @@ At runtime, the `web_search` tool accepts the following parameters:
 | `range` | string | no | Optional time filter: `d` (day), `w` (week), `m` (month), `y` (year) |
 
 If `range` is omitted, PicoClaw performs an unrestricted search.
+For Kagi, `d`, `w`, and `m` map to Kagi lens `time_relative`; `y` maps to a lens `time_after` date one year before the current day.
 
 ### Example `web_search` Call
 

docs/security/security_configuration.md

@@ -248,13 +248,16 @@ channel_list:
 
 ### Web Tools
 
-**Brave, Tavily, Perplexity:**
+**Brave, Tavily, Perplexity, Kagi:**
 ```yaml
 web:
   brave:
     api_keys:
       - "key-1"
       - "key-2"
+  kagi:
+    api_keys:
+      - "your-kagi-api-key"
 ```
 - Use `api_keys` (plural) array format
 
@@ -315,16 +318,19 @@ model_list:
 - **Rate limit management**: Distribute usage across multiple keys
 - **High availability**: Reduce downtime during API provider issues
 
-### Web Tools (Brave/Tavily/Perplexity) - Single key
+### Web Tools (Brave/Tavily/Perplexity/Kagi) - Single key
 
 ```yaml
 web:
   brave:
     api_keys:
       - "BSA-your-key"
+  kagi:
+    api_keys:
+      - "your-kagi-api-key"
 ```
 
-### Web Tools (Brave/Tavily/Perplexity) - Multiple keys
+### Web Tools (Brave/Tavily/Perplexity/Kagi) - Multiple keys
 
 ```yaml
 web:
@@ -332,6 +338,10 @@ web:
     api_keys:
       - "BSA-key-1"
       - "BSA-key-2"
+  kagi:
+    api_keys:
+      - "kagi-key-1"
+      - "kagi-key-2"
 ```
 
 ### Web Tool (GLMSearch/BaiduSearch) - Single key only
@@ -558,7 +568,7 @@ go test ./pkg/config -run TestSecurityConfig
 
 - Ensure you're using `api_keys` (plural) in `.security.yml` for models and web tools (except GLMSearch/BaiduSearch)
 - Check that the array format is correct in YAML (proper indentation with dashes)
-- Remember: Models, Brave, Tavily, Perplexity MUST use `api_keys` (array format)
+- Remember: Models, Brave, Tavily, Perplexity, Kagi MUST use `api_keys` (array format)
 - GLMSearch and BaiduSearch MUST use `api_key` (single string format)
 
 ### Load Balancing/Failover Issues

go.mod

@@ -1,18 +1,20 @@
 module github.com/sipeed/picoclaw
 
-go 1.25.10
+go 1.25.11
 
 require (
 	fyne.io/systray v1.12.1
+	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.1
+	github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.1
 	github.com/SevereCloud/vksdk/v3 v3.3.1
-	github.com/adhocore/gronx v1.19.7
-	github.com/anthropics/anthropic-sdk-go v1.26.0
+	github.com/adhocore/gronx v1.20.0
+	github.com/anthropics/anthropic-sdk-go v1.46.0
 	github.com/atc0005/go-teams-notify/v2 v2.14.0
-	github.com/aws/aws-sdk-go-v2 v1.41.7
-	github.com/aws/aws-sdk-go-v2/config v1.32.17
-	github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.6
+	github.com/aws/aws-sdk-go-v2 v1.42.0
+	github.com/aws/aws-sdk-go-v2/config v1.32.25
+	github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.53.3
 	github.com/bwmarrin/discordgo v0.29.0
-	github.com/caarlos0/env/v11 v11.4.0
+	github.com/caarlos0/env/v11 v11.4.1
 	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/creack/pty v1.1.24
 	github.com/eclipse/paho.mqtt.golang v1.5.1
@@ -22,16 +24,17 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/h2non/filetype v1.1.3
-	github.com/larksuite/oapi-sdk-go/v3 v3.7.5
-	github.com/line/line-bot-sdk-go/v8 v8.19.0
+	github.com/kagisearch/kagi-openapi-golang v0.0.0-20260526215348-96575e864d62
+	github.com/larksuite/oapi-sdk-go/v3 v3.9.4
+	github.com/line/line-bot-sdk-go/v8 v8.20.0
 	github.com/mdp/qrterminal/v3 v3.2.1
 	github.com/minio/selfupdate v0.6.0
-	github.com/modelcontextprotocol/go-sdk v1.5.0
+	github.com/modelcontextprotocol/go-sdk v1.6.1
 	github.com/muesli/termenv v0.16.0
 	github.com/mymmrac/telego v1.9.0
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
 	github.com/openai/openai-go/v3 v3.22.0
-	github.com/pion/rtp v1.10.1
+	github.com/pion/rtp v1.10.2
 	github.com/pion/webrtc/v3 v3.3.6
 	github.com/pmezard/go-difflib v1.0.0
 	github.com/rs/zerolog v1.35.1
@@ -48,28 +51,32 @@ require (
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v3 v3.0.1
 	maunium.net/go/mautrix v0.27.0
-	modernc.org/sqlite v1.50.1
+	modernc.org/sqlite v1.51.0
 	rsc.io/qr v0.2.0
 )
 
 require (
 	aead.dev/minisign v0.2.0 // indirect
 	filippo.io/edwards25519 v1.2.0 // indirect
-	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.16 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23 // indirect
-	github.com/aws/aws-sdk-go-v2/service/signin v1.0.11 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 // indirect
-	github.com/aws/smithy-go v1.25.1 // indirect
+	github.com/Azure/azure-sdk-for-go/sdk/internal v1.12.0 // indirect
+	github.com/AzureAD/microsoft-authentication-library-for-go v1.6.0 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.12 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.24 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.29 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.29 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.29 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.30 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.12 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.29 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.2.0 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.31.3 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.6 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.43.3 // indirect
+	github.com/aws/smithy-go v1.27.1 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/beeper/argo-go v1.1.2 // indirect
+	github.com/buger/jsonparser v1.1.2 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
 	github.com/charmbracelet/x/ansi v0.8.0 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
@@ -82,8 +89,12 @@ require (
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/invopop/jsonschema v0.13.0 // indirect
+	github.com/kylelemons/godebug v1.1.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
@@ -91,13 +102,16 @@ require (
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/petermattis/goid v0.0.0-20260330135022-df67b199bc81 // indirect
 	github.com/pion/randutil v0.1.0 // indirect
+	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/segmentio/asm v1.1.3 // indirect
 	github.com/segmentio/encoding v0.5.4 // indirect
+	github.com/standard-webhooks/standard-webhooks/libraries v0.0.1 // indirect
 	github.com/vektah/gqlparser/v2 v2.5.27 // indirect
 	github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
+	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.mau.fi/libsignal v0.2.1 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
@@ -135,9 +149,9 @@ require (
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	golang.org/x/arch v0.24.0 // indirect
 	golang.org/x/crypto v0.51.0
-	golang.org/x/net v0.54.0
-	golang.org/x/sync v0.20.0
-	golang.org/x/sys v0.44.0
+	golang.org/x/net v0.55.0
+	golang.org/x/sync v0.21.0
+	golang.org/x/sys v0.45.0
 )
 
 replace github.com/bwmarrin/discordgo => github.com/yeongaori/discordgo-fork v0.0.0-20260319072544-e8e546f5d532

go.sum

@@ -5,66 +5,82 @@ filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
 filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
 fyne.io/systray v1.12.1 h1:ygBD6aZXwiOmZoY5N+ukbH9pih0Kq6fYgVeMYbr5skQ=
 fyne.io/systray v1.12.1/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
+github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.1 h1:jHb/wfvRikGdxMXYV3QG/SzUOPYN9KEUUuC0Yd0/vC0=
+github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.1/go.mod h1:pzBXCYn05zvYIrwLgtK8Ap8QcjRg+0i76tMQdWN6wOk=
+github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.1 h1:Hk5QBxZQC1jb2Fwj6mpzme37xbCDdNTxU7O9eb5+LB4=
+github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.1/go.mod h1:IYus9qsFobWIc2YVwe/WPjcnyCkPKtnHAqUYeebc8z0=
+github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache v0.3.2 h1:yz1bePFlP5Vws5+8ez6T3HWXPmwOK7Yvq8QxDBD3SKY=
+github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache v0.3.2/go.mod h1:Pa9ZNPuoNu/GztvBSKk9J1cDJW6vk/n0zLtV4mgd8N8=
+github.com/Azure/azure-sdk-for-go/sdk/internal v1.12.0 h1:fhqpLE3UEXi9lPaBRpQ6XuRW0nU7hgg4zlmZZa+a9q4=
+github.com/Azure/azure-sdk-for-go/sdk/internal v1.12.0/go.mod h1:7dCRMLwisfRH3dBupKeNCioWYUZ4SS09Z14H+7i8ZoY=
+github.com/AzureAD/microsoft-authentication-extensions-for-go/cache v0.1.1 h1:WJTmL004Abzc5wDB5VtZG2PJk5ndYDgVacGqfirKxjM=
+github.com/AzureAD/microsoft-authentication-extensions-for-go/cache v0.1.1/go.mod h1:tCcJZ0uHAmvjsVYzEFivsRTN00oz5BEsRgQHu5JZ9WE=
+github.com/AzureAD/microsoft-authentication-library-for-go v1.6.0 h1:XRzhVemXdgvJqCH0sFfrBUTnUJSBrBf7++ypk+twtRs=
+github.com/AzureAD/microsoft-authentication-library-for-go v1.6.0/go.mod h1:HKpQxkWaGLJ+D/5H8QRpyQXA1eKjxkFlOMwck5+33Jk=
 github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
 github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
 github.com/SevereCloud/vksdk/v3 v3.3.1 h1:O86zsp5LQnHE+O5acvuXM/s6S1LyxzVTkF6+Lup0Jyg=
 github.com/SevereCloud/vksdk/v3 v3.3.1/go.mod h1:c6WaA5aocUYsXfkcUbg2qy45V9M1VDcqHHmHIN14NAw=
-github.com/adhocore/gronx v1.19.7 h1:7hhFwChgDw9eHC3+TQ+OKKBqJnP44oWkDCnnW9nrsuA=
-github.com/adhocore/gronx v1.19.7/go.mod h1:7oUY1WAU8rEJWmAxXR2DN0JaO4gi9khSgKjiRypqteg=
+github.com/adhocore/gronx v1.20.0 h1:PD13Mo0wekkZ7ZZR9yb1TqeqTfybs7/K3ez9DmjQwEs=
+github.com/adhocore/gronx v1.20.0/go.mod h1:7oUY1WAU8rEJWmAxXR2DN0JaO4gi9khSgKjiRypqteg=
 github.com/agnivade/levenshtein v1.2.1 h1:EHBY3UOn1gwdy/VbFwgo4cxecRznFk7fKWN1KOX7eoM=
 github.com/agnivade/levenshtein v1.2.1/go.mod h1:QVVI16kDrtSuwcpd0p1+xMC6Z/VfhtCyDIjcwga4/DU=
 github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883 h1:bvNMNQO63//z+xNgfBlViaCIJKLlCJ6/fmUseuG0wVQ=
 github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883/go.mod h1:rCTlJbsFo29Kk6CurOXKm700vrz8f0KW0JNfpkRJY/8=
 github.com/andybalholm/brotli v1.2.1 h1:R+f5xP285VArJDRgowrfb9DqL18yVK0gKAW/F+eTWro=
 github.com/andybalholm/brotli v1.2.1/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
-github.com/anthropics/anthropic-sdk-go v1.26.0 h1:oUTzFaUpAevfuELAP1sjL6CQJ9HHAfT7CoSYSac11PY=
-github.com/anthropics/anthropic-sdk-go v1.26.0/go.mod h1:qUKmaW+uuPB64iy1l+4kOSvaLqPXnHTTBKH6RVZ7q5Q=
+github.com/anthropics/anthropic-sdk-go v1.46.0 h1:yl3n+el5ZfNgiCtQ7zQ7s/NXxB11YbrKXdc3uLPNWlU=
+github.com/anthropics/anthropic-sdk-go v1.46.0/go.mod h1:bx5vWuHFuGPkELH8Z4KUiNSohFnUwScdpTyr+50myPo=
 github.com/atc0005/go-teams-notify/v2 v2.14.0 h1:7N+xw+COnYANLREaAveQ65rsNQ12nIZJED9nMLyscCo=
 github.com/atc0005/go-teams-notify/v2 v2.14.0/go.mod h1:EECsWM2b0Hvoz7O+QdlsvyN2KCUOFQCGj8bUBXv3A3Q=
-github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8=
-github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10/go.mod h1:qqY157uZoqm5OXq/amuaBJyC9hgBCBQnsaWnPe905GY=
-github.com/aws/aws-sdk-go-v2/config v1.32.17 h1:FpL4/758/diKwqbytU0prpuiu60fgXKUWCpDJtApclU=
-github.com/aws/aws-sdk-go-v2/config v1.32.17/go.mod h1:OXqUMzgXytfoF9JaKkhrOYsyh72t9G+MJH8mMRaexOE=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.16 h1:r3RJBuU7X9ibt8RHbMjWE6y60QbKBiII6wSrXnapxSU=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.16/go.mod h1:6cx7zqDENJDbBIIWX6P8s0h6hqHC8Avbjh9Dseo27ug=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23 h1:UuSfcORqNSz/ey3VPRS8TcVH2Ikf0/sC+Hdj400QI6U=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23/go.mod h1:+G/OSGiOFnSOkYloKj/9M35s74LgVAdJBSD5lsFfqKg=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23 h1:GpT/TrnBYuE5gan2cZbTtvP+JlHsutdmlV2YfEyNde0=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23/go.mod h1:xYWD6BS9ywC5bS3sz9Xh04whO/hzK2plt2Zkyrp4JuA=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23 h1:bpd8vxhlQi2r1hiueOw02f/duEPTMK59Q4QMAoTTtTo=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23/go.mod h1:15DfR2nw+CRHIk0tqNyifu3G1YdAOy68RftkhMDDwYk=
-github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24 h1:OQqn11BtaYv1WLUowvcA30MpzIu8Ti4pcLPIIyoKZrA=
-github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24/go.mod h1:X5ZJyfwVrWA96GzPmUCWFQaEARPR7gCrpq2E92PJwAE=
-github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.6 h1:Wbo1WlWyGaAXlr6C7OGXq9avbdJhIV9cQ4M6E34b5x8=
-github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.6/go.mod h1:uY1fJe6m3I3w/m8UAkQ89Cm/ZAt/um6LW+AOZU33LDI=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9 h1:FLudkZLt5ci0ozzgkVo8BJGwvqNaZbTWb3UcucAateA=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9/go.mod h1:w7wZ/s9qK7c8g4al+UyoF1Sp/Z45UwMGcqIzLWVQHWk=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23 h1:pbrxO/kuIwgEsOPLkaHu0O+m4fNgLU8B3vxQ+72jTPw=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23/go.mod h1:/CMNUqoj46HpS3MNRDEDIwcgEnrtZlKRaHNaHxIFpNA=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.11 h1:TdJ+HdzOBhU8+iVAOGUTU63VXopcumCOF1paFulHWZc=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.11/go.mod h1:R82ZRExE/nheo0N+T8zHPcLRTcH8MGsnR3BiVGX0TwI=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 h1:7byT8HUWrgoRp6sXjxtZwgOKfhss5fW6SkLBtqzgRoE=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.17/go.mod h1:xNWknVi4Ezm1vg1QsB/5EWpAJURq22uqd38U8qKvOJc=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 h1:+1Kl1zx6bWi4X7cKi3VYh29h8BvsCoHQEQ6ST9X8w7w=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21/go.mod h1:4vIRDq+CJB2xFAXZ+YgGUTiEft7oAQlhIs71xcSeuVg=
-github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 h1:F/M5Y9I3nwr2IEpshZgh1GeHpOItExNM9L1euNuh/fk=
-github.com/aws/aws-sdk-go-v2/service/sts v1.42.1/go.mod h1:mTNxImtovCOEEuD65mKW7DCsL+2gjEH+RPEAexAzAio=
-github.com/aws/smithy-go v1.25.1 h1:J8ERsGSU7d+aCmdQur5Txg6bVoYelvQJgtZehD12GkI=
-github.com/aws/smithy-go v1.25.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/aws/aws-sdk-go-v2 v1.42.0 h1:XvXMJTkFQtpBKIWZnmr9ZEOc2InWM2yldjXEJ/bymhA=
+github.com/aws/aws-sdk-go-v2 v1.42.0/go.mod h1:27+ACypSLljLAEKsCYOmrjKh83vuTRkuAe9Uv/3A4bg=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.12 h1:oRtsqWgxbpeXrOlxOoQStx2M9WNbIkPq4C4Xn1or6bc=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.12/go.mod h1:Zg0Oe9qT+9wcezlm1a64wGJp2qZdRElVxo/seJf7jYU=
+github.com/aws/aws-sdk-go-v2/config v1.32.25 h1:ACCejvStYoilgwrfegSt5ZntCbPrk52qfwyNcnl3omM=
+github.com/aws/aws-sdk-go-v2/config v1.32.25/go.mod h1:LJyU8sDRbXUxFn8xMJIGP+v9QYYwveNLI8a/giAOiAs=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.24 h1:2hQqYCV9yqyePQ9o6dCrZc/zO8U3TwPr9mIKlZnPu/I=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.24/go.mod h1:IDwpACtwqHLISdzfwUUNq4P9DsB/h5BLg4FwJPNfqFY=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.29 h1:r6qZHbT+wxgWO/e9vYNUEtg7lv5+UN3pRqKhLXvnArg=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.29/go.mod h1:QRnaRcTVGKPGRy8w78HMQtKUGRYcnMZAANATkeVA6Mo=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.29 h1:f3vKqSo13fhTYb+JEcXwXefZQE26I1FB5eTSniU67ko=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.29/go.mod h1:MzoLFUArKGpGD+ukmPiTPG1X5x4o6M2kq4v2dr1FiEc=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.29 h1:RdwIf/CuUsvJX3RgJagbOyotl/cxoLY4xviKuE7p2GY=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.29/go.mod h1:71wt8W2EgswdZy9Mf9KNnzxZ3TiZlv4caKghPktDOkA=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.30 h1:VTGy885W5DKBxWRUJbym9hytNaYzsyaPkCHGRRMAOhU=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.30/go.mod h1:AS0HycUvJRFvTt613AYDOgO2jzw+00cVSMny8XB3yMY=
+github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.53.3 h1:HTzzFDJiFSNkZX1Al72+insR4dre/vUeT3YZ4b9h0MA=
+github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.53.3/go.mod h1:dFhfMfXoFrnX6XK/gXDh+4azdybtKll2QnP239wm2O8=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.12 h1:ZD2+BSw9vFsNlKYIasSNt3uDbjqqXIBcM13UJv/Lx2k=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.12/go.mod h1:Ms4zlcVBbXbiP7EVLhl+lgjvA/a7YphqQ3Ih3174EmI=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.29 h1:DRebniUGZ2MqiiIVmQJ04vIXr918hubdHMnarSLEWyU=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.29/go.mod h1:LfRkPCD8YHDM2E5eTkos2UpwYeZnBcVarTa8L59bJHA=
+github.com/aws/aws-sdk-go-v2/service/signin v1.2.0 h1:3nXpRcFwRCW8n7HgO2QGy0Dc20eQNfBuUemGQhpF8m8=
+github.com/aws/aws-sdk-go-v2/service/signin v1.2.0/go.mod h1:LxYujSTLPRlp2vTtcUO/+1ilrew8ytt6SvQyOgejzFQ=
+github.com/aws/aws-sdk-go-v2/service/sso v1.31.3 h1:ey1XLTYXb9PcLt4535632o5kCGXNXEhNb620Dqwuylo=
+github.com/aws/aws-sdk-go-v2/service/sso v1.31.3/go.mod h1:Lk7PlmoTYryQmyBG0EXqj5BcUbj3whXdU2s3yGI3EAc=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.6 h1:yLr03zQE/5Eu5l3QU0Si+xMbLMbSDF2YXsigqXngs6g=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.6/go.mod h1:Q5N6icH+KJZDLh+ESNwzdv6cZ6vLFF/egy3IOxWhmz4=
+github.com/aws/aws-sdk-go-v2/service/sts v1.43.3 h1:VrIhKRCSK1umelSgB9RghvA9RTUYeQffyAS5ApXehNI=
+github.com/aws/aws-sdk-go-v2/service/sts v1.43.3/go.mod h1:r8wkDOuLaaMFqFiYAb8dGY2A3gJCOujMc6CFOVC4Zhc=
+github.com/aws/smithy-go v1.27.1 h1:4T340VFndXtADGF52gYa1POyL7s9E4Z1OeZ1hCscIw8=
+github.com/aws/smithy-go v1.27.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
+github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
 github.com/beeper/argo-go v1.1.2 h1:UQI2G8F+NLfGTOmTUI0254pGKx/HUU/etbUGTJv91Fs=
 github.com/beeper/argo-go v1.1.2/go.mod h1:M+LJAnyowKVQ6Rdj6XYGEn+qcVFkb3R/MUpqkGR0hM4=
+github.com/buger/jsonparser v1.1.2 h1:frqHqw7otoVbk5M8LlE/L7HTnIq2v9RX6EJ48i9AxJk=
+github.com/buger/jsonparser v1.1.2/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
 github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
 github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
 github.com/bytedance/sonic v1.15.1 h1:nJD5PmM0vY7J8CT6MxoqbVAAMhkSmV2HgRAUrrpLoOw=
 github.com/bytedance/sonic v1.15.1/go.mod h1:mT2NbXunuaEbnZ+mRIX/vYqKISmgEuHFDI4UzmKx2SA=
 github.com/bytedance/sonic/loader v0.5.1 h1:Ygpfa9zwRCCKSlrp5bBP/b/Xzc3VxsAW+5NIYXrOOpI=
 github.com/bytedance/sonic/loader v0.5.1/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
-github.com/caarlos0/env/v11 v11.4.0 h1:Kcb6t5kIIr4XkoQC9AF2j+8E1Jsrl3Wz/hhm1LtoGAc=
-github.com/caarlos0/env/v11 v11.4.0/go.mod h1:qupehSf/Y0TUTsxKywqRt/vJjN5nz6vauiYEUUr8P4U=
+github.com/caarlos0/env/v11 v11.4.1 h1:fYwH0sWEsBSMPG7t4e/PEfTFzrWrpjyygXyUnWiSwEw=
+github.com/caarlos0/env/v11 v11.4.1/go.mod h1:qupehSf/Y0TUTsxKywqRt/vJjN5nz6vauiYEUUr8P4U=
 github.com/cespare/xxhash/v2 v2.1.2/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc h1:4pZI35227imm7yK2bGPcfpFEmuY1gc2YSTShr4iJBfs=
@@ -164,6 +180,13 @@ github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyf
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
+github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/kagisearch/kagi-openapi-golang v0.0.0-20260526215348-96575e864d62 h1:nyUi7Wel3KlVSa5ArgX/snlizqfaxU48qtvXS/JK5GE=
+github.com/kagisearch/kagi-openapi-golang v0.0.0-20260526215348-96575e864d62/go.mod h1:vONkS+clG730HSKOw3nZVa22TjB21r6csKYzYt0a9zI=
+github.com/keybase/go-keychain v0.0.1 h1:way+bWYa6lDppZoZcgMbYsvC7GxljxrskdNInRtuthU=
+github.com/keybase/go-keychain v0.0.1/go.mod h1:PdEILRW3i9D8JcdM+FmY6RwkHGnhHxXwkPPMeUgOK1k=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
 github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
 github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao=
@@ -179,12 +202,16 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/larksuite/oapi-sdk-go/v3 v3.7.5 h1:dimv+ZAGia01f4xCDGvCiBHKWMf4K1AB7fGsM+lv5Jw=
-github.com/larksuite/oapi-sdk-go/v3 v3.7.5/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
-github.com/line/line-bot-sdk-go/v8 v8.19.0 h1:5FD/1SprRZ8Y0FiUI6syYiBewOs0ak2tuUBMYN0wzE4=
-github.com/line/line-bot-sdk-go/v8 v8.19.0/go.mod h1:AeSRUuu7WGgveGDJb6DyKyFUOst2UB2aF6LO2cQeuXs=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/larksuite/oapi-sdk-go/v3 v3.9.4 h1:oMgcY7NBjJv1QXJqFAfcoN/TbScCkCuRZfbb1mCwZmI=
+github.com/larksuite/oapi-sdk-go/v3 v3.9.4/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/line/line-bot-sdk-go/v8 v8.20.0 h1:Jv22DV3JuQ5qZvniqUbg504bJrVzffXs2CMpyoiuIZU=
+github.com/line/line-bot-sdk-go/v8 v8.20.0/go.mod h1:QMXJwPka2ysSeVQKWXkBp8DzBFs+CFAXFNo75KJtWho=
 github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
 github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
+github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
 github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
@@ -197,8 +224,8 @@ github.com/mdp/qrterminal/v3 v3.2.1 h1:6+yQjiiOsSuXT5n9/m60E54vdgFsw0zhADHhHLrFe
 github.com/mdp/qrterminal/v3 v3.2.1/go.mod h1:jOTmXvnBsMy5xqLniO0R++Jmjs2sTm9dFSuQ5kpz/SU=
 github.com/minio/selfupdate v0.6.0 h1:i76PgT0K5xO9+hjzKcacQtO7+MjJ4JKA8Ak8XQ9DDwU=
 github.com/minio/selfupdate v0.6.0/go.mod h1:bO02GTIPCMQFTEvE5h4DjYB58bCoZ35XLeBf0buTDdM=
-github.com/modelcontextprotocol/go-sdk v1.5.0 h1:CHU0FIX9kpueNkxuYtfYQn1Z0slhFzBZuq+x6IiblIU=
-github.com/modelcontextprotocol/go-sdk v1.5.0/go.mod h1:gggDIhoemhWs3BGkGwd1umzEXCEMMvAnhTrnbXJKKKA=
+github.com/modelcontextprotocol/go-sdk v1.6.1 h1:0zOSupjKUxPKSocPT1Wtago+mUHU2/uZ4xSOY0FGReU=
+github.com/modelcontextprotocol/go-sdk v1.6.1/go.mod h1:kzm3kzFL1/+AziGOE0nUs3gvPoNxMCvkxokMkuFapXQ=
 github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
 github.com/mymmrac/telego v1.9.0 h1:ZUJxZaPx/1IgRvVb5lXnUB8FgW5rNYfRe6Q2EJ4OJ+Y=
@@ -221,10 +248,12 @@ github.com/petermattis/goid v0.0.0-20260330135022-df67b199bc81 h1:WDsQxOJDy0N1VR
 github.com/petermattis/goid v0.0.0-20260330135022-df67b199bc81/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
 github.com/pion/randutil v0.1.0 h1:CFG1UdESneORglEsnimhUjf33Rwjubwj6xfiOXBa3mA=
 github.com/pion/randutil v0.1.0/go.mod h1:XcJrSMMbbMRhASFVOlj/5hQial/Y8oH/HVo7TBZq+j8=
-github.com/pion/rtp v1.10.1 h1:xP1prZcCTUuhO2c83XtxyOHJteISg6o8iPsE2acaMtA=
-github.com/pion/rtp v1.10.1/go.mod h1:rF5nS1GqbR7H/TCpKwylzeq6yDM+MM6k+On5EgeThEM=
+github.com/pion/rtp v1.10.2 h1:l+f6tTDcAH6xwepaAoW791ddhuYsJlqRATOzirO04Mo=
+github.com/pion/rtp v1.10.2/go.mod h1:Au8fc6cEByy8RLTwKTQTEeQqDB/SJDxwL4mZuxYA5Pk=
 github.com/pion/webrtc/v3 v3.3.6 h1:7XAh4RPtlY1Vul6/GmZrv7z+NnxKA6If0KStXBI2ZLE=
 github.com/pion/webrtc/v3 v3.3.6/go.mod h1:zyN7th4mZpV27eXybfR/cnUf3J2DRy8zw/mdjD9JTNM=
+github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ=
+github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
@@ -253,6 +282,8 @@ github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiT
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/standard-webhooks/standard-webhooks/libraries v0.0.1 h1:uOfcYT+3QungH6tIGSVCR/Y3KJmgJiHcojJbMTPDZAI=
+github.com/standard-webhooks/standard-webhooks/libraries v0.0.1/go.mod h1:L1MQhA6x4dn9r007T033lsaZMv9EmBAdXyU/+EF40fo=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
@@ -293,6 +324,8 @@ github.com/vmihailenco/msgpack/v5 v5.4.1 h1:cQriyiUvjTwOHg8QZaPihLWeRAAVoCpE00IU
 github.com/vmihailenco/msgpack/v5 v5.4.1/go.mod h1:GaZTsDaehaPpQVyxrf5mtQlH+pc21PIudVV/E3rRQok=
 github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
 github.com/vmihailenco/tagparser/v2 v2.0.0/go.mod h1:Wri+At7QHww0WTrCBeu4J6bNtoV6mEfg5OIWRZA9qds=
+github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
+github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
@@ -354,8 +387,8 @@ golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug
 golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
 golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
 golang.org/x/net v0.19.0/go.mod h1:CfAk/cbD4CthTvqiEl8NpboMuiuOYsAr/7NOjZJtv1U=
-golang.org/x/net v0.54.0 h1:2zJIZAxAHV/OHCDTCOHAYehQzLfSXuf/5SoL/Dv6w/w=
-golang.org/x/net v0.54.0/go.mod h1:Sj4oj8jK6XmHpBZU/zWHw3BV3abl4Kvi+Ut7cQcY+cQ=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
 golang.org/x/oauth2 v0.23.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
@@ -365,8 +398,8 @@ golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJ
 golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -384,12 +417,13 @@ golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
-golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
@@ -471,8 +505,8 @@ modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
 modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
 modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
 modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
-modernc.org/sqlite v1.50.1 h1:l+cQvn0sd0zJJtfygGHuQJ5AjlrwXmWPw4KP3ZMwr9w=
-modernc.org/sqlite v1.50.1/go.mod h1:tcNzv5p84E0skkmJn038y+hWJbLQXQqEnQfeh5r2JLM=
+modernc.org/sqlite v1.51.0 h1:aH/MMSoayAIhozZ7uJbVTT9QO/VhzBf0J9tymmmuC/U=
+modernc.org/sqlite v1.51.0/go.mod h1:tcNzv5p84E0skkmJn038y+hWJbLQXQqEnQfeh5r2JLM=
 modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
 modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
 modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=

onboard_workspace_embed.go

@@ -0,0 +1,12 @@
+package picoclaw
+
+import "embed"
+
+// OnboardWorkspace embeds the default onboarding workspace template.
+//
+// Keeping this embed at the module root lets us source files directly from the
+// tracked `workspace/` tree, instead of relying on a generated copy inside
+// `cmd/...` that may be absent in clean checkouts and CI lint runs.
+//
+//go:embed workspace
+var OnboardWorkspace embed.FS

pkg/agent/agent.go

@@ -69,8 +69,14 @@ type AgentLoop struct {
 	activeTurnStates sync.Map
 	subTurnCounter   atomic.Int64
 
-	turnSeq        atomic.Uint64
-	activeRequests sync.WaitGroup
+	turnSeq atomic.Uint64
+
+	// activeReqMu/activeReqCond/activeReqCount replace sync.WaitGroup to
+	// avoid the "WaitGroup is reused before previous Wait has returned" panic
+	// that occurs when Add(1) races with a goroutine-launched Wait().
+	activeReqMu    sync.Mutex
+	activeReqCond  *sync.Cond
+	activeReqCount int
 
 	reloadFunc func() error
 
@@ -118,6 +124,7 @@ const (
 	handledToolResponseSummary = "Requested output delivered via tool attachment."
 	sessionKeyAgentPrefix      = "agent:"
 	pendingTurnPrefix          = "pending-"
+	providerReloadGracePeriod  = 30 * time.Second
 	metadataKeyMessageKind     = "message_kind"
 	metadataKeyToolCalls       = "tool_calls"
 	metadataKeyOutboundKind    = "outbound_kind"
@@ -208,7 +215,8 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 			// Session claimed — spawn a worker goroutine that acquires a semaphore
 			// slot. The goroutine is spawned immediately so the main loop keeps
 			// draining the inbound channel. The goroutine blocks on the semaphore.
-			go func(m bus.InboundMessage) {
+			go func(m bus.InboundMessage, ph *turnState) {
+				var releaseSession bool
 				// Acquire semaphore slot (blocks if at capacity)
 				select {
 				case al.workerSem <- struct{}{}:
@@ -216,7 +224,7 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 				case <-ctx.Done():
 					// Context canceled while waiting for a slot — clean up the
 					// placeholder to prevent session-level deadlock.
-					al.activeTurnStates.Delete(sessionKey)
+					al.releaseSessionTurnState(sessionKey, nil)
 					return
 				}
 
@@ -225,16 +233,28 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 				// completes normally, clearActiveTurn deletes the real turnState and
 				// this becomes a no-op (the key is already gone).
 				defer func() {
+					if releaseSession {
+						// Conditional delete: only remove the entry if it still points
+						// to our placeholder. A new message may have claimed the slot
+						// between the panic and this defer.
+						if actual, ok := al.activeTurnStates.Load(sessionKey); ok {
+							if ts, ok := actual.(*turnState); ok && ts == ph {
+								al.releaseSessionTurnState(sessionKey, ts)
+							}
+						}
+						return
+					}
 					if actual, ok := al.activeTurnStates.Load(sessionKey); ok {
 						if ts, ok := actual.(*turnState); ok && strings.HasPrefix(ts.turnID, pendingTurnPrefix) {
 							// Placeholder still present — runTurn never replaced it.
-							al.activeTurnStates.Delete(sessionKey)
+							al.releaseSessionTurnState(sessionKey, ts)
 						}
 					}
 				}()
 
 				defer func() {
 					if r := recover(); r != nil {
+						releaseSession = true
 						logger.RecoverPanicNoExit(r)
 						logger.ErrorCF("agent", "Worker goroutine panicked",
 							map[string]any{
@@ -252,7 +272,7 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 				}
 
 				if al.takePendingStop(sessionKey) {
-					al.activeTurnStates.Delete(sessionKey)
+					al.releaseSessionTurnState(sessionKey, nil)
 					target := &continuationTarget{
 						SessionKey: sessionKey,
 						Channel:    m.Channel,
@@ -270,7 +290,7 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 				}
 
 				al.runTurnWithSteering(ctx, m)
-			}(msg)
+			}(msg, placeholder)
 
 			// TODO: Re-enable media cleanup after inbound media is properly consumed by the agent.
 			// Currently disabled because files are deleted before the LLM can access their content.
@@ -366,37 +386,23 @@ func (al *AgentLoop) ReloadProviderAndConfig(
 		return fmt.Errorf("config cannot be nil")
 	}
 
-	// Create new registry with updated config and provider
-	// Wrap in defer/recover to handle any panics gracefully
 	var registry *AgentRegistry
-	var panicErr error
-	done := make(chan struct{}, 1)
-
-	go func() {
+	func() {
 		defer func() {
 			if r := recover(); r != nil {
 				logger.RecoverPanicNoExit(r)
-				panicErr = fmt.Errorf("panic during registry creation: %v", r)
 				logger.ErrorCF("agent", "Panic during registry creation",
 					map[string]any{"panic": r})
+				registry = nil
 			}
-			close(done)
 		}()
-
 		registry = NewAgentRegistry(cfg, provider)
 	}()
-
-	// Wait for completion or context cancellation
-	select {
-	case <-done:
-		if registry == nil {
-			if panicErr != nil {
-				return fmt.Errorf("registry creation failed: %w", panicErr)
-			}
-			return fmt.Errorf("registry creation failed (nil result)")
+	if registry == nil {
+		if err := ctx.Err(); err != nil {
+			return fmt.Errorf("context canceled during registry creation: %w", err)
 		}
-	case <-ctx.Done():
-		return fmt.Errorf("context canceled during registry creation: %w", ctx.Err())
+		return fmt.Errorf("registry creation failed")
 	}
 
 	// Check context again before proceeding
@@ -472,17 +478,7 @@ func (al *AgentLoop) ReloadProviderAndConfig(
 	// This prevents blocking readers while closing
 	if oldProvider, ok := extractProvider(oldRegistry); ok {
 		if stateful, ok := oldProvider.(providers.StatefulProvider); ok {
-			// Give in-flight requests a moment to complete
-			// Use a reasonable timeout that balances cleanup vs resource usage
-			select {
-			case <-time.After(100 * time.Millisecond):
-				stateful.Close()
-			case <-ctx.Done():
-				// Context canceled, close immediately but log warning
-				logger.WarnCF("agent", "Context canceled during provider cleanup, forcing close",
-					map[string]any{"error": ctx.Err()})
-				stateful.Close()
-			}
+			al.closeReloadedProvider(ctx, stateful)
 		}
 	}
 

pkg/agent/agent_command.go

@@ -350,11 +350,13 @@ func (al *AgentLoop) buildCommandsRuntime(
 			}
 			history := agent.Sessions.GetHistory(opts.SessionKey)
 			return &commands.ContextStats{
-				UsedTokens:       usage.UsedTokens,
-				TotalTokens:      usage.TotalTokens,
-				CompressAtTokens: usage.CompressAtTokens,
-				UsedPercent:      usage.UsedPercent,
-				MessageCount:     len(history),
+				UsedTokens:        usage.UsedTokens,
+				TotalTokens:       usage.TotalTokens,
+				HistoryTokens:     usage.HistoryTokens,
+				CompressAtTokens:  usage.CompressAtTokens,
+				SummarizeAtTokens: usage.SummarizeAtTokens,
+				UsedPercent:       usage.UsedPercent,
+				MessageCount:      len(history),
 			}
 		}
 	}

pkg/agent/agent_init.go

@@ -5,6 +5,7 @@ package agent
 import (
 	"context"
 	"fmt"
+	"sync"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/agent/interfaces"
@@ -91,6 +92,7 @@ func NewAgentLoop(
 			})
 		}
 	}
+	al.activeReqCond = sync.NewCond(&al.activeReqMu)
 	al.refreshRuntimeEventLogger(cfg)
 	al.providerFactory = providers.CreateProviderFromConfig
 	al.hooks = NewHookManager(al.runtimeEvents.Channel())
@@ -161,26 +163,58 @@ func registerSharedTools(
 		// Message tool
 		if cfg.Tools.IsToolEnabled("message") {
 			messageTool := tools.NewMessageTool()
+			if cfg.Tools.Message.MediaEnabled {
+				messageTool.ConfigureLocalMedia(
+					agent.Workspace,
+					cfg.Agents.Defaults.RestrictToWorkspace,
+					cfg.Agents.Defaults.GetMaxMediaSize(),
+					allowReadPaths,
+				)
+			}
 			messageTool.SetSendCallback(func(
 				ctx context.Context,
 				channel, chatID, content, replyToMessageID string,
+				mediaParts []bus.MediaPart,
 			) error {
-				pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
-				defer pubCancel()
 				outboundCtx := bus.NewOutboundContext(channel, chatID, replyToMessageID)
 				outboundAgentID, outboundSessionKey, outboundScope := outboundTurnMetadata(
 					tools.ToolAgentID(ctx),
 					tools.ToolSessionKey(ctx),
 					tools.ToolSessionScope(ctx),
 				)
-				return msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
+				if len(mediaParts) > 0 {
+					outboundMedia := bus.OutboundMediaMessage{
+						Channel:    channel,
+						ChatID:     chatID,
+						Context:    outboundCtx,
+						AgentID:    outboundAgentID,
+						SessionKey: outboundSessionKey,
+						Scope:      outboundScope,
+						Parts:      mediaParts,
+					}
+					if al.channelManager != nil && channel != "" {
+						return al.channelManager.SendMedia(ctx, outboundMedia)
+					}
+					pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+					defer pubCancel()
+					return msgBus.PublishOutboundMedia(pubCtx, outboundMedia)
+				}
+				outboundMessage := bus.OutboundMessage{
+					Channel:          channel,
+					ChatID:           chatID,
 					Context:          outboundCtx,
 					AgentID:          outboundAgentID,
 					SessionKey:       outboundSessionKey,
 					Scope:            outboundScope,
 					Content:          content,
 					ReplyToMessageID: replyToMessageID,
-				})
+				}
+				if al.channelManager != nil && channel != "" {
+					return al.channelManager.SendMessage(ctx, outboundMessage)
+				}
+				pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+				defer pubCancel()
+				return msgBus.PublishOutbound(pubCtx, outboundMessage)
 			})
 			agent.Tools.Register(messageTool)
 		}
@@ -264,7 +298,7 @@ func registerSharedTools(
 			// This keeps subagent vision support working even when the optimized
 			// sub-turn spawner path is unavailable.
 			subagentManager.SetMediaResolver(func(msgs []providers.Message) []providers.Message {
-				return resolveMediaRefs(msgs, al.mediaStore, cfg.Agents.Defaults.GetMaxMediaSize())
+				return resolveMediaRefs(msgs, al.mediaStore, cfg.Agents.Defaults.GetMaxMediaSize(), 0)
 			})
 
 			// Set the spawner that links into AgentLoop's turnState

pkg/agent/agent_media.go

@@ -31,6 +31,21 @@ var (
 	filePlaceholderRegex  = regexp.MustCompile(`\[file(:\s+[^\]]*)?\]`)
 )
 
+func normalizeCurrentTurnStart(messages []providers.Message, currentTurnStart int) int {
+	if currentTurnStart < 0 {
+		return 0
+	}
+	if currentTurnStart > len(messages) {
+		return len(messages)
+	}
+	return currentTurnStart
+}
+
+func currentTurnMessages(messages []providers.Message, currentTurnStart int) []providers.Message {
+	currentTurnStart = normalizeCurrentTurnStart(messages, currentTurnStart)
+	return messages[currentTurnStart:]
+}
+
 // resolveMediaRefs resolves media:// refs in messages.
 // For user messages: images get path tags only ([image:/path]) so the LLM
 // can decide whether to view them via load_image or operate on the file.
@@ -38,12 +53,20 @@ var (
 // user message only after the contiguous tool-message block ends, so we don't
 // break the tool-results-must-immediately-follow-assistant constraint that
 // LLM APIs enforce.
+// Only tool messages from the current turn may emit the synthetic user
+// follow-up; historical tool results stay as plain path-tagged history.
 // Non-image files always get path tags regardless of role.
 // Returns a new slice; original messages are not mutated.
-func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxSize int) []providers.Message {
+func resolveMediaRefs(
+	messages []providers.Message,
+	store media.MediaStore,
+	maxSize int,
+	currentTurnStart int,
+) []providers.Message {
 	if store == nil {
 		return messages
 	}
+	currentTurnStart = normalizeCurrentTurnStart(messages, currentTurnStart)
 
 	result := make([]providers.Message, 0, len(messages))
 	var pendingToolImages []string
@@ -52,22 +75,14 @@ func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxS
 		// When leaving a tool-message block, flush any accumulated images
 		// as a synthetic user message.
 		if m.Role != "tool" && len(pendingToolImages) > 0 {
-			result = append(result, providers.Message{
-				Role:    "user",
-				Content: "[Loaded image from tool result above]",
-				Media:   pendingToolImages,
-			})
+			result = append(result, toolImageFollowUpPromptMessage(pendingToolImages))
 			pendingToolImages = nil
 		}
 
 		if len(m.Media) == 0 {
 			result = append(result, m)
 			if idx == len(messages)-1 && len(pendingToolImages) > 0 {
-				result = append(result, providers.Message{
-					Role:    "user",
-					Content: "[Loaded image from tool result above]",
-					Media:   pendingToolImages,
-				})
+				result = append(result, toolImageFollowUpPromptMessage(pendingToolImages))
 				pendingToolImages = nil
 			}
 			continue
@@ -104,7 +119,7 @@ func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxS
 			mime := detectMIME(localPath, meta)
 			pathTags = append(pathTags, buildPathTag(mime, localPath))
 
-			if m.Role == "tool" && strings.HasPrefix(mime, "image/") {
+			if m.Role == "tool" && idx >= currentTurnStart && strings.HasPrefix(mime, "image/") {
 				dataURL := encodeImageToDataURL(localPath, mime, info, maxSize)
 				if dataURL != "" {
 					pendingToolImages = append(pendingToolImages, dataURL)
@@ -120,11 +135,7 @@ func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxS
 
 		// If this is the last message and we have pending images, flush them.
 		if idx == len(messages)-1 && len(pendingToolImages) > 0 {
-			result = append(result, providers.Message{
-				Role:    "user",
-				Content: "[Loaded image from tool result above]",
-				Media:   pendingToolImages,
-			})
+			result = append(result, toolImageFollowUpPromptMessage(pendingToolImages))
 			pendingToolImages = nil
 		}
 	}

pkg/agent/agent_utils.go

@@ -13,6 +13,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/commands"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/session"
 	"github.com/sipeed/picoclaw/pkg/utils"
@@ -591,6 +592,77 @@ func closeProviderIfStateful(provider providers.LLMProvider) {
 	}
 }
 
+// activeRequestsInc atomically increments the active request count.
+func (al *AgentLoop) activeRequestsInc() {
+	al.activeReqMu.Lock()
+	al.activeReqCount++
+	al.activeReqMu.Unlock()
+}
+
+// activeRequestsDec atomically decrements the active request count
+// and wakes any goroutine blocked in waitForActiveRequests when the
+// count reaches zero.
+func (al *AgentLoop) activeRequestsDec() {
+	al.activeReqMu.Lock()
+	al.activeReqCount--
+	if al.activeReqCount == 0 {
+		al.activeReqCond.Broadcast()
+	}
+	al.activeReqMu.Unlock()
+}
+
+func (al *AgentLoop) waitForActiveRequests(ctx context.Context, timeout time.Duration) bool {
+	al.activeReqMu.Lock()
+	if al.activeReqCount == 0 {
+		al.activeReqMu.Unlock()
+		return true
+	}
+
+	// Wake blocked Wait() callers on timeout or context cancellation.
+	var timedOut bool
+	if timeout > 0 {
+		time.AfterFunc(timeout, func() {
+			al.activeReqMu.Lock()
+			timedOut = true
+			al.activeReqCond.Broadcast()
+			al.activeReqMu.Unlock()
+		})
+	}
+	go func() {
+		<-ctx.Done()
+		al.activeReqMu.Lock()
+		al.activeReqCond.Broadcast()
+		al.activeReqMu.Unlock()
+	}()
+
+	for al.activeReqCount > 0 && !timedOut && ctx.Err() == nil {
+		al.activeReqCond.Wait()
+	}
+	result := al.activeReqCount == 0
+	al.activeReqMu.Unlock()
+	return result
+}
+
+func (al *AgentLoop) closeReloadedProvider(ctx context.Context, provider providers.StatefulProvider) {
+	waitCtx := ctx
+	if waitCtx == nil {
+		waitCtx = context.Background()
+	}
+
+	drained := al.waitForActiveRequests(waitCtx, providerReloadGracePeriod)
+	if !drained {
+		fields := map[string]any{"grace_period": providerReloadGracePeriod.String()}
+		if err := waitCtx.Err(); err != nil {
+			fields["error"] = err.Error()
+			logger.WarnCF("agent", "Provider reload interrupted while waiting for in-flight requests", fields)
+		} else {
+			logger.WarnCF("agent", "Provider reload grace period expired with in-flight requests still running", fields)
+		}
+	}
+
+	provider.Close()
+}
+
 func makePendingTurnID(sessionKey string, seq uint64) string {
 	return pendingTurnPrefix + sessionKey + "-" + fmt.Sprintf("%d", seq)
 }

pkg/agent/context.go

@@ -102,7 +102,13 @@ func NewContextBuilder(workspace string) *ContextBuilder {
 	// Use the skills/ directory under the current working directory
 	builtinSkillsDir := strings.TrimSpace(os.Getenv(config.EnvBuiltinSkills))
 	if builtinSkillsDir == "" {
-		wd, _ := os.Getwd()
+		wd, err := os.Getwd()
+		if err != nil {
+			// os.Getwd failure is extremely rare; fall back to empty
+			// string so that filepath.Join produces a relative "skills"
+			// path, preserving the original lookup behavior.
+			wd = ""
+		}
 		builtinSkillsDir = filepath.Join(wd, "skills")
 	}
 	globalSkillsDir := filepath.Join(getGlobalConfigDir(), "skills")

pkg/agent/context_budget.go

@@ -115,3 +115,55 @@ func isOverContextBudget(
 
 	return total > contextWindow
 }
+
+// trimHistoryToFitContextWindow rebuilds the prompt from progressively newer
+// history slices until it fits within the context window. Oldest complete turns
+// are dropped first so tool-call sequences remain intact.
+func trimHistoryToFitContextWindow(
+	history []providers.Message,
+	build func([]providers.Message) []providers.Message,
+	contextWindow int,
+	toolDefs []providers.ToolDefinition,
+	maxTokens int,
+) ([]providers.Message, []providers.Message, bool) {
+	messages := build(history)
+	if !isOverContextBudget(contextWindow, messages, toolDefs, maxTokens) {
+		return history, messages, true
+	}
+
+	trimmedHistory := append([]providers.Message(nil), history...)
+	for len(trimmedHistory) > 0 {
+		dropUntil := nextHistoryTrimStart(trimmedHistory)
+		if dropUntil <= 0 || dropUntil >= len(trimmedHistory) {
+			trimmedHistory = nil
+		} else {
+			trimmedHistory = append([]providers.Message(nil), trimmedHistory[dropUntil:]...)
+		}
+
+		messages = build(trimmedHistory)
+		if !isOverContextBudget(contextWindow, messages, toolDefs, maxTokens) {
+			return trimmedHistory, messages, true
+		}
+	}
+
+	return nil, messages, false
+}
+
+func nextHistoryTrimStart(history []providers.Message) int {
+	if len(history) == 0 {
+		return 0
+	}
+
+	turns := parseTurnBoundaries(history)
+	if len(turns) >= 2 {
+		return turns[1]
+	}
+	if len(turns) == 1 {
+		if turns[0] > 0 {
+			return turns[0]
+		}
+		return len(history)
+	}
+
+	return len(history)
+}

pkg/agent/context_budget_test.go

@@ -844,3 +844,64 @@ func TestIsOverContextBudget_RealisticSession(t *testing.T) {
 		t.Error("realistic session should exceed 500 context window")
 	}
 }
+
+func TestTrimHistoryToFitContextWindow_DropsOldestTurns(t *testing.T) {
+	history := []providers.Message{
+		msgUser(strings.Repeat("u1 ", 120)),
+		msgAssistant(strings.Repeat("a1 ", 120)),
+		msgUser(strings.Repeat("u2 ", 120)),
+		msgAssistant(strings.Repeat("a2 ", 120)),
+		msgUser(strings.Repeat("u3 ", 120)),
+		msgAssistant(strings.Repeat("a3 ", 120)),
+	}
+
+	build := func(history []providers.Message) []providers.Message {
+		return append([]providers.Message(nil), history...)
+	}
+
+	trimmedHistory, messages, fit := trimHistoryToFitContextWindow(
+		history,
+		build,
+		700,
+		nil,
+		0,
+	)
+	if !fit {
+		t.Fatal("expected trimmed history to fit context window")
+	}
+	if len(trimmedHistory) != 4 {
+		t.Fatalf("trimmed history len = %d, want 4", len(trimmedHistory))
+	}
+	if trimmedHistory[0].Content != history[2].Content {
+		t.Fatalf("first kept message = %q, want second turn start", trimmedHistory[0].Content)
+	}
+	if isOverContextBudget(700, messages, nil, 0) {
+		t.Fatal("trimmed messages should be within budget")
+	}
+}
+
+func TestTrimHistoryToFitContextWindow_ClearsSingleOversizedTurn(t *testing.T) {
+	history := []providers.Message{
+		msgUser(strings.Repeat("oversized ", 200)),
+		msgAssistant(strings.Repeat("oversized ", 200)),
+	}
+
+	trimmedHistory, messages, fit := trimHistoryToFitContextWindow(
+		history,
+		func(history []providers.Message) []providers.Message {
+			return append([]providers.Message(nil), history...)
+		},
+		200,
+		nil,
+		0,
+	)
+	if !fit {
+		t.Fatal("expected empty history rebuild to fit context window")
+	}
+	if len(trimmedHistory) != 0 {
+		t.Fatalf("trimmed history len = %d, want 0", len(trimmedHistory))
+	}
+	if len(messages) != 0 {
+		t.Fatalf("messages len = %d, want 0", len(messages))
+	}
+}

pkg/agent/context_legacy.go

@@ -294,9 +294,9 @@ func (m *legacyContextManager) retryLLMCall(
 	var err error
 
 	for attempt := 0; attempt < maxRetries; attempt++ {
-		m.al.activeRequests.Add(1)
+		m.al.activeRequestsInc()
 		resp, err = func() (*providers.LLMResponse, error) {
-			defer m.al.activeRequests.Done()
+			defer m.al.activeRequestsDec()
 			return agent.Provider.Chat(
 				ctx,
 				[]providers.Message{{Role: "user", Content: prompt}},

pkg/agent/context_seahorse.go

@@ -6,6 +6,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"time"
 
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
@@ -200,6 +201,7 @@ func providerToSeahorseMessage(msg protocoltypes.Message) seahorse.Message {
 		ModelName:        msg.ModelName,
 		ReasoningContent: msg.ReasoningContent,
 		TokenCount:       tokenizer.EstimateMessageTokens(msg),
+		CreatedAt:        normalizeSeahorseMessageCreatedAt(msg.CreatedAt),
 	}
 
 	// Convert ToolCalls → MessageParts
@@ -235,6 +237,13 @@ func providerToSeahorseMessage(msg protocoltypes.Message) seahorse.Message {
 	return result
 }
 
+func normalizeSeahorseMessageCreatedAt(createdAt *time.Time) time.Time {
+	if createdAt == nil || createdAt.IsZero() {
+		return time.Time{}
+	}
+	return createdAt.UTC().Truncate(time.Second)
+}
+
 // seahorseToProviderMessages converts a seahorse.AssembleResult to []providers.Message.
 func seahorseToProviderMessages(result *seahorse.AssembleResult) []protocoltypes.Message {
 	messages := make([]protocoltypes.Message, 0, len(result.Messages))

pkg/agent/context_seahorse_test.go

@@ -171,11 +171,13 @@ func TestProviderToSeahorseMessageWithMedia(t *testing.T) {
 }
 
 func TestProviderToSeahorseMessageWithReasoning(t *testing.T) {
+	createdAt := time.Date(2026, 5, 6, 7, 8, 9, 123000000, time.UTC)
 	msg := protocoltypes.Message{
 		Role:             "assistant",
 		Content:          "response text",
 		ModelName:        "gpt-5.4-mini",
 		ReasoningContent: "I thought about this carefully",
+		CreatedAt:        &createdAt,
 	}
 
 	result := providerToSeahorseMessage(msg)
@@ -185,6 +187,9 @@ func TestProviderToSeahorseMessageWithReasoning(t *testing.T) {
 	if result.ModelName != "gpt-5.4-mini" {
 		t.Errorf("ModelName = %q, want %q", result.ModelName, "gpt-5.4-mini")
 	}
+	if !result.CreatedAt.Equal(time.Date(2026, 5, 6, 7, 8, 9, 0, time.UTC)) {
+		t.Errorf("CreatedAt = %v, want 2026-05-06 07:08:09 UTC", result.CreatedAt)
+	}
 }
 
 func TestSeahorseToProviderMessagesWithReasoning(t *testing.T) {
@@ -288,6 +293,74 @@ func TestSeahorseToProviderMessagesWithToolCalls(t *testing.T) {
 	}
 }
 
+func TestSeahorseAssemblePreservesActiveToolTurnAcrossSanitization(t *testing.T) {
+	engine, err := seahorse.NewEngine(seahorse.Config{
+		DBPath: t.TempDir() + "/seahorse.db",
+	}, nil)
+	if err != nil {
+		t.Fatalf("NewEngine: %v", err)
+	}
+
+	ctx := context.Background()
+	sessionKey := "test:active-tool-turn"
+	_, err = engine.Ingest(ctx, sessionKey, []seahorse.Message{
+		{
+			Role:       "assistant",
+			Content:    "older context",
+			TokenCount: 20,
+		},
+		{
+			Role:       "user",
+			Content:    "inspect the file",
+			TokenCount: 5,
+		},
+		{
+			Role:       "assistant",
+			TokenCount: 5,
+			Parts: []seahorse.MessagePart{{
+				Type:       "tool_use",
+				Name:       "read_file",
+				Arguments:  `{"path":"/tmp/test.txt"}`,
+				ToolCallID: "tc_1",
+			}},
+		},
+		{
+			Role:       "tool",
+			TokenCount: 200,
+			Parts: []seahorse.MessagePart{{
+				Type:       "tool_result",
+				ToolCallID: "tc_1",
+				Text:       "very large tool output",
+			}},
+		},
+		{
+			Role:       "assistant",
+			Content:    "done",
+			TokenCount: 5,
+		},
+	})
+	if err != nil {
+		t.Fatalf("Ingest: %v", err)
+	}
+
+	result, err := engine.Assemble(ctx, sessionKey, seahorse.AssembleInput{Budget: 210})
+	if err != nil {
+		t.Fatalf("Assemble: %v", err)
+	}
+
+	sanitized := sanitizeHistoryForProvider(seahorseToProviderMessages(result))
+	if len(sanitized) != 4 {
+		t.Fatalf("sanitized history len = %d, want 4 protected-turn messages", len(sanitized))
+	}
+	assertRoles(t, sanitized, "user", "assistant", "tool", "assistant")
+	if len(sanitized[1].ToolCalls) != 1 || sanitized[1].ToolCalls[0].ID != "tc_1" {
+		t.Fatalf("assistant tool calls = %+v, want preserved tool call tc_1", sanitized[1].ToolCalls)
+	}
+	if sanitized[2].ToolCallID != "tc_1" {
+		t.Fatalf("tool result id = %q, want tc_1", sanitized[2].ToolCallID)
+	}
+}
+
 func TestSeahorseToProviderMessagesToolResult(t *testing.T) {
 	msg := seahorse.Message{
 		Role:       "tool",

pkg/agent/context_usage.go

@@ -61,6 +61,17 @@ func computeContextUsage(agent *AgentInstance, sessionKey string) *bus.ContextUs
 	// proactive trigger (msgTokens + toolTokens + maxTokens > contextWindow).
 	compressAt := effectiveWindow
 
+	// summarizeAt = soft summarization trigger: matches maybeSummarize's
+	// threshold (contextWindow * SummarizeTokenPercent / 100).
+	//
+	// The engine compares this against history-message tokens ONLY (not
+	// UsedTokens).  HistoryTokens is exposed alongside UsedTokens so the
+	// UI can show both values and avoid user confusion.
+	summarizeAt := contextWindow * agent.SummarizeTokenPercent / 100
+	if summarizeAt <= 0 {
+		summarizeAt = compressAt
+	}
+
 	usedPercent := 0
 	if compressAt > 0 {
 		usedPercent = usedTokens * 100 / compressAt
@@ -70,9 +81,11 @@ func computeContextUsage(agent *AgentInstance, sessionKey string) *bus.ContextUs
 	}
 
 	return &bus.ContextUsage{
-		UsedTokens:       usedTokens,
-		TotalTokens:      contextWindow,
-		CompressAtTokens: compressAt,
-		UsedPercent:      usedPercent,
+		UsedTokens:        usedTokens,
+		TotalTokens:       contextWindow,
+		HistoryTokens:     historyTokens,
+		CompressAtTokens:  compressAt,
+		SummarizeAtTokens: summarizeAt,
+		UsedPercent:       usedPercent,
 	}
 }

pkg/agent/instance.go

@@ -2,7 +2,6 @@ package agent
 
 import (
 	"context"
-	"fmt"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -44,6 +43,7 @@ type AgentInstance struct {
 	SkillsFilter              []string
 	MCPServerAllowlist        map[string]struct{}
 	Candidates                []providers.FallbackCandidate
+	ImageCandidates           []providers.FallbackCandidate
 
 	// Router is non-nil when model routing is configured and the light model
 	// was successfully resolved. It scores each incoming message and decides
@@ -199,9 +199,19 @@ func NewAgentInstance(
 
 	// Resolve fallback candidates
 	candidates := resolveModelCandidates(cfg, defaults.Provider, model, fallbacks)
+	imageCandidates := resolveModelCandidates(
+		cfg,
+		defaults.Provider,
+		defaults.ImageModel,
+		defaults.ImageModelFallbacks,
+	)
 
 	candidateProviders := make(map[string]providers.LLMProvider)
 	populateCandidateProvidersFromNames(cfg, workspace, fallbacks, candidateProviders)
+	if strings.TrimSpace(defaults.ImageModel) != "" {
+		imageNames := append([]string{defaults.ImageModel}, defaults.ImageModelFallbacks...)
+		populateCandidateProvidersFromNames(cfg, workspace, imageNames, candidateProviders)
+	}
 
 	// Model routing setup: pre-resolve light model candidates at creation time
 	// to avoid repeated model_list lookups on every incoming message.
@@ -266,6 +276,7 @@ func NewAgentInstance(
 		SkillsFilter:              skillsFilter,
 		MCPServerAllowlist:        agentMCPServerAllowlist,
 		Candidates:                candidates,
+		ImageCandidates:           imageCandidates,
 		Router:                    router,
 		LightCandidates:           lightCandidates,
 		LightProvider:             lightProvider,
@@ -414,7 +425,10 @@ func compilePatterns(patterns []string) []*regexp.Regexp {
 	for _, p := range patterns {
 		re, err := regexp.Compile(p)
 		if err != nil {
-			fmt.Printf("Warning: invalid path pattern %q: %v\n", p, err)
+			logger.WarnCF("agent", "invalid path pattern in compilePatterns", map[string]any{
+				"pattern": p,
+				"error":   err.Error(),
+			})
 			continue
 		}
 		compiled = append(compiled, re)

pkg/agent/legacy_events.go

@@ -2,11 +2,13 @@ package agent
 
 import (
 	"context"
+	"fmt"
 	"sync"
 	"sync/atomic"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	runtimeevents "github.com/sipeed/picoclaw/pkg/events"
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
 const defaultEventSubscriberBuffer = 16
@@ -88,7 +90,14 @@ func (al *AgentLoop) UnsubscribeEvents(id uint64) {
 	if !ok {
 		return
 	}
-	sub := value.(legacyEventSubscription)
+	sub, ok := value.(legacyEventSubscription)
+	if !ok {
+		logger.WarnCF("agent", "UnsubscribeEvents: unexpected type in subscription map", map[string]any{
+			"id":   id,
+			"type": fmt.Sprintf("%T", value),
+		})
+		return
+	}
 	sub.cancel()
 	if sub.sub != nil {
 		_ = sub.sub.Close()

pkg/agent/llm_media.go

@@ -1,11 +1,16 @@
 package agent
 
 import (
+	"fmt"
+	"regexp"
 	"strings"
 
+	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
+var resolvedImagePathTagRegex = regexp.MustCompile(`\[image:[^\s\]][^\]]*\]`)
+
 func messagesContainMedia(messages []providers.Message) bool {
 	for _, msg := range messages {
 		for _, ref := range msg.Media {
@@ -65,3 +70,125 @@ func isVisionUnsupportedError(err error) bool {
 
 	return false
 }
+
+func visionUnsupportedModelError(modelName string, imageModelConfigured bool) error {
+	modelName = strings.TrimSpace(modelName)
+	if imageModelConfigured {
+		if modelName != "" {
+			return fmt.Errorf(
+				"selected vision model %q does not support image input; update agents.defaults.image_model to a multimodal model",
+				modelName,
+			)
+		}
+		return fmt.Errorf(
+			"selected vision model does not support image input; update agents.defaults.image_model to a multimodal model",
+		)
+	}
+	if modelName != "" {
+		return fmt.Errorf(
+			"active model %q does not support image input; configure agents.defaults.image_model with a multimodal model",
+			modelName,
+		)
+	}
+	return fmt.Errorf(
+		"the active model does not support image input; configure agents.defaults.image_model with a multimodal model",
+	)
+}
+
+func sameCandidateSet(a, b []providers.FallbackCandidate) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i].StableKey() != b[i].StableKey() {
+			return false
+		}
+	}
+	return true
+}
+
+func messagesContainCurrentTurnMediaTurn(messages []providers.Message) bool {
+	for _, msg := range messages {
+		if len(msg.Media) > 0 {
+			return true
+		}
+		if resolvedImagePathTagRegex.MatchString(msg.Content) {
+			return true
+		}
+	}
+	return false
+}
+
+func (p *Pipeline) routeMediaTurn(ts *turnState, exec *turnExecution) error {
+	if p == nil || ts == nil || ts.agent == nil || exec == nil ||
+		!messagesContainCurrentTurnMediaTurn(currentTurnMessages(exec.callMessages, exec.currentTurnStart)) {
+		return nil
+	}
+
+	var targetCandidates []providers.FallbackCandidate
+	var targetModelName string
+	var routeReason string
+
+	switch {
+	case len(ts.agent.ImageCandidates) > 0:
+		targetCandidates = append([]providers.FallbackCandidate(nil), ts.agent.ImageCandidates...)
+		targetModelName = strings.TrimSpace(p.Cfg.Agents.Defaults.ImageModel)
+		routeReason = "configured_image_model"
+	case exec.usedLight && len(ts.agent.Candidates) > 0:
+		targetCandidates = append([]providers.FallbackCandidate(nil), ts.agent.Candidates...)
+		targetModelName = strings.TrimSpace(ts.agent.Model)
+		routeReason = "bypass_light_model_for_media"
+	default:
+		return nil
+	}
+
+	if len(targetCandidates) == 0 {
+		return nil
+	}
+
+	targetModel := resolvedCandidateModel(targetCandidates, targetModelName)
+	targetProvider := exec.activeProvider
+	firstCandidate := targetCandidates[0]
+	if provider, err := providerForFallbackCandidate(
+		ts.agent,
+		ts.agent.Provider,
+		targetCandidates,
+		firstCandidate.Provider,
+		firstCandidate.Model,
+	); err != nil {
+		return err
+	} else if provider != nil {
+		targetProvider = provider
+	}
+
+	resolvedModelName := resolvedCandidateModelName(targetCandidates, targetModelName)
+	if sameCandidateSet(exec.activeCandidates, targetCandidates) &&
+		exec.activeModel == targetModel &&
+		exec.llmModelName == resolvedModelName {
+		return nil
+	}
+
+	exec.activeCandidates = targetCandidates
+	exec.activeModel = targetModel
+	exec.activeProvider = targetProvider
+	exec.activeModelConfig = resolveActiveModelConfig(
+		p.Cfg,
+		ts.agent.Workspace,
+		targetCandidates,
+		targetModel,
+		p.Cfg.Agents.Defaults.Provider,
+	)
+	exec.llmModelName = resolvedModelName
+	exec.usedLight = false
+
+	logger.InfoCF("agent", "Media turn routing selected model", map[string]any{
+		"agent_id":       ts.agent.ID,
+		"reason":         routeReason,
+		"model":          exec.activeModel,
+		"model_name":     exec.llmModelName,
+		"candidates":     len(exec.activeCandidates),
+		"messages_count": len(exec.callMessages),
+	})
+
+	return nil
+}

pkg/agent/pipeline_execute.go

@@ -295,21 +295,16 @@ toolLoop:
 						contentForLLM = al.cfg.FilterSensitiveData(contentForLLM)
 					}
 
-					toolResultMsg := providers.Message{
-						Role:       "tool",
-						Content:    contentForLLM,
-						ToolCallID: tc.ID,
-					}
-
+					var toolResultMedia []string
 					if len(hookResult.Media) > 0 && !hookResult.ResponseHandled {
 						hookResult.ArtifactTags = buildArtifactTags(al.mediaStore, hookResult.Media)
 						contentForLLM = hookResult.ContentForLLM()
 						if al.cfg.Tools.IsFilterSensitiveDataEnabled() {
 							contentForLLM = al.cfg.FilterSensitiveData(contentForLLM)
 						}
-						toolResultMsg.Content = contentForLLM
-						toolResultMsg.Media = append(toolResultMsg.Media, hookResult.Media...)
+						toolResultMedia = append(toolResultMedia, hookResult.Media...)
 					}
+					toolResultMsg := toolResultPromptMessage(contentForLLM, tc.ID, toolResultMedia)
 
 					al.emitEvent(
 						runtimeevents.KindAgentToolExecEnd,
@@ -695,14 +690,11 @@ toolLoop:
 			contentForLLM = al.cfg.FilterSensitiveData(contentForLLM)
 		}
 
-		toolResultMsg := providers.Message{
-			Role:       "tool",
-			Content:    contentForLLM,
-			ToolCallID: toolCallID,
-		}
+		var toolResultMedia []string
 		if len(toolResult.Media) > 0 && !toolResult.ResponseHandled {
-			toolResultMsg.Media = append(toolResultMsg.Media, toolResult.Media...)
+			toolResultMedia = append(toolResultMedia, toolResult.Media...)
 		}
+		toolResultMsg := toolResultPromptMessage(contentForLLM, toolCallID, toolResultMedia)
 		al.emitEvent(
 			runtimeevents.KindAgentToolExecEnd,
 			ts.eventMeta("runTurn", "turn.tool.end"),

pkg/agent/pipeline_llm.go

@@ -31,7 +31,7 @@ func (p *Pipeline) CallLLM(
 
 	// PreLLM: resolve media refs (except on iteration 1 where user media is already resolved)
 	if iteration > 1 {
-		exec.messages = resolveMediaRefs(exec.messages, p.MediaStore, maxMediaSize)
+		exec.messages = resolveMediaRefs(exec.messages, p.MediaStore, maxMediaSize, exec.currentTurnStart)
 	}
 
 	// PreLLM: graceful terminal handling
@@ -64,6 +64,9 @@ func (p *Pipeline) CallLLM(
 		exec.providerToolDefs = nil
 		ts.markGracefulTerminalUsed()
 	}
+	if err := p.routeMediaTurn(ts, exec); err != nil {
+		return ControlBreak, err
+	}
 
 	exec.llmOpts = map[string]any{
 		"max_tokens":       ts.agent.MaxTokens,
@@ -157,8 +160,8 @@ func (p *Pipeline) CallLLM(
 			ts.clearProviderCancel(providerCancel)
 		}()
 
-		al.activeRequests.Add(1)
-		defer al.activeRequests.Done()
+		al.activeRequestsInc()
+		defer al.activeRequestsDec()
 
 		if response, handled, streamErr := p.tryConfiguredStreamingLLM(
 			providerCtx,
@@ -170,36 +173,62 @@ func (p *Pipeline) CallLLM(
 			return response, streamErr
 		}
 
-		if len(exec.activeCandidates) > 1 && p.Fallback != nil {
-			fbResult, fbErr := p.Fallback.ExecuteCandidate(
-				providerCtx,
+		runCandidate := func(
+			ctx context.Context,
+			candidate providers.FallbackCandidate,
+		) (*providers.LLMResponse, error) {
+			candidateProvider, err := providerForFallbackCandidate(
+				ts.agent,
+				exec.activeProvider,
 				exec.activeCandidates,
-				func(ctx context.Context, candidate providers.FallbackCandidate) (*providers.LLMResponse, error) {
-					candidateProvider, err := providerForFallbackCandidate(
-						ts.agent,
-						exec.activeProvider,
-						exec.activeCandidates,
-						candidate.Provider,
-						candidate.Model,
-					)
-					if err != nil {
-						return nil, err
-					}
-					callOpts := shallowCloneLLMOptions(exec.llmOpts)
-					delete(callOpts, "thinking_level")
-					candidateCfg := resolveActiveModelConfig(
-						p.Cfg,
-						ts.agent.Workspace,
-						[]providers.FallbackCandidate{candidate},
-						candidate.Model,
-						p.Cfg.Agents.Defaults.Provider,
-					)
-					candidateThinking := thinkingSettingsFromModelConfig(candidateCfg)
-					applyThinkingOption(callOpts, candidateProvider, candidateThinking, true, ts.agent.ID)
-					exec.suppressReasoning = shouldSuppressReasoningFor(candidateThinking)
-					return candidateProvider.Chat(ctx, messagesForCall, toolDefsForCall, candidate.Model, callOpts)
-				},
+				candidate.Provider,
+				candidate.Model,
 			)
+			if err != nil {
+				return nil, err
+			}
+			callOpts := shallowCloneLLMOptions(exec.llmOpts)
+			delete(callOpts, "thinking_level")
+			candidateCfg := resolveActiveModelConfig(
+				p.Cfg,
+				ts.agent.Workspace,
+				[]providers.FallbackCandidate{candidate},
+				candidate.Model,
+				p.Cfg.Agents.Defaults.Provider,
+			)
+			candidateThinking := thinkingSettingsFromModelConfig(candidateCfg)
+			applyThinkingOption(callOpts, candidateProvider, candidateThinking, true, ts.agent.ID)
+			exec.suppressReasoning = shouldSuppressReasoningFor(candidateThinking)
+			return candidateProvider.Chat(ctx, messagesForCall, toolDefsForCall, candidate.Model, callOpts)
+		}
+
+		if len(exec.activeCandidates) > 1 && p.Fallback != nil {
+			var (
+				fbResult *providers.FallbackResult
+				fbErr    error
+			)
+			if hasMediaRefs(messagesForCall) {
+				fbResult, fbErr = p.Fallback.ExecuteImage(
+					providerCtx,
+					exec.activeCandidates,
+					func(ctx context.Context, provider, model string) (*providers.LLMResponse, error) {
+						candidate := providers.FallbackCandidate{Provider: provider, Model: model}
+						for _, configured := range exec.activeCandidates {
+							if configured.Provider == provider && configured.Model == model {
+								candidate = configured
+								break
+							}
+						}
+						return runCandidate(ctx, candidate)
+					},
+				)
+			} else {
+				fbResult, fbErr = p.Fallback.ExecuteCandidate(
+					providerCtx,
+					exec.activeCandidates,
+					runCandidate,
+				)
+			}
 			if fbErr != nil {
 				return nil, fbErr
 			}
@@ -250,52 +279,16 @@ func (p *Pipeline) CallLLM(
 			break
 		}
 
-		// Retry without media if vision is unsupported
-		if hasMediaRefs(exec.callMessages) && isVisionUnsupportedError(err) && retry < maxRetries {
-			al.emitEvent(
-				runtimeevents.KindAgentLLMRetry,
-				ts.eventMeta("runTurn", "turn.llm.retry"),
-				LLMRetryPayload{
-					Attempt:    retry + 1,
-					MaxRetries: maxRetries,
-					Reason:     "vision_unsupported",
-					Error:      err.Error(),
-					Backoff:    0,
-				},
+		if hasMediaRefs(exec.callMessages) && isVisionUnsupportedError(err) {
+			return ControlBreak, visionUnsupportedModelError(
+				exec.llmModelName,
+				len(ts.agent.ImageCandidates) > 0,
 			)
-			logger.WarnCF("agent", "Vision unsupported, retrying without media", map[string]any{
-				"error": err.Error(),
-				"retry": retry,
-			})
-			exec.callMessages = stripMessageMedia(exec.callMessages)
-			if !ts.opts.NoHistory {
-				exec.history = stripMessageMedia(exec.history)
-				ts.agent.Sessions.SetHistory(ts.sessionKey, exec.history)
-				for i := range ts.persistedMessages {
-					ts.persistedMessages[i].Media = nil
-				}
-				ts.refreshRestorePointFromSession(ts.agent)
-			}
-			continue
 		}
 
 		errMsg := strings.ToLower(err.Error())
-		isTimeoutError := errors.Is(err, context.DeadlineExceeded) ||
-			strings.Contains(errMsg, "deadline exceeded") ||
-			strings.Contains(errMsg, "client.timeout") ||
-			strings.Contains(errMsg, "timed out") ||
-			strings.Contains(errMsg, "timeout exceeded")
-
-		isNetworkError := !isTimeoutError && (strings.Contains(errMsg, "connection reset") ||
-			strings.Contains(errMsg, "connection refused") ||
-			strings.Contains(errMsg, "broken pipe") ||
-			strings.Contains(errMsg, "no such host") ||
-			strings.Contains(errMsg, "network is unreachable") ||
-			strings.Contains(errMsg, "read tcp") ||
-			strings.Contains(errMsg, "write tcp") ||
-			strings.Contains(errMsg, "eof"))
-
-		isContextError := !isTimeoutError && (strings.Contains(errMsg, "context_length_exceeded") ||
+		retryReason, isTransientError := transientLLMRetryReason(err)
+		isContextError := !isTransientError && (strings.Contains(errMsg, "context_length_exceeded") ||
 			strings.Contains(errMsg, "context window") ||
 			strings.Contains(errMsg, "context_window") ||
 			strings.Contains(errMsg, "maximum context length") ||
@@ -306,7 +299,7 @@ func (p *Pipeline) CallLLM(
 			strings.Contains(errMsg, "prompt is too long") ||
 			strings.Contains(errMsg, "request too large"))
 
-		if isTimeoutError && retry < maxRetries {
+		if isTransientError && retry < maxRetries {
 			backoff := time.Duration(retry+1) * time.Duration(backoffSecs) * time.Second
 			al.emitEvent(
 				runtimeevents.KindAgentLLMRetry,
@@ -314,42 +307,14 @@ func (p *Pipeline) CallLLM(
 				LLMRetryPayload{
 					Attempt:    retry + 1,
 					MaxRetries: maxRetries,
-					Reason:     "timeout",
+					Reason:     retryReason,
 					Error:      err.Error(),
 					Backoff:    backoff,
 				},
 			)
-			logger.WarnCF("agent", "Timeout error, retrying after backoff", map[string]any{
-				"error":   err.Error(),
-				"retry":   retry,
-				"backoff": backoff.String(),
-			})
-			if sleepErr := sleepWithContext(turnCtx, backoff); sleepErr != nil {
-				if ts.hardAbortRequested() {
-					_ = ts.requestHardAbort()
-					return ControlBreak, nil
-				}
-				err = sleepErr
-				break
-			}
-			continue
-		}
-
-		if isNetworkError && retry < maxRetries {
-			backoff := time.Duration(retry+1) * time.Duration(backoffSecs) * time.Second
-			al.emitEvent(
-				runtimeevents.KindAgentLLMRetry,
-				ts.eventMeta("runTurn", "turn.llm.retry"),
-				LLMRetryPayload{
-					Attempt:    retry + 1,
-					MaxRetries: maxRetries,
-					Reason:     "network",
-					Error:      err.Error(),
-					Backoff:    backoff,
-				},
-			)
-			logger.WarnCF("agent", "Network error, retrying after backoff", map[string]any{
+			logger.WarnCF("agent", "Transient LLM error, retrying after backoff", map[string]any{
 				"error":   err.Error(),
+				"reason":  retryReason,
 				"retry":   retry,
 				"backoff": backoff.String(),
 			})
@@ -415,14 +380,72 @@ func (p *Pipeline) CallLLM(
 				contextualSkills = ts.agent.ContextBuilder.ResolveActiveSkillsForContext(ts.activeSkills)
 			}
 			ts.recordSkillContextSnapshot(skillContextTriggerContextRetryRebuild, contextualSkills)
-			rebuildPromptReq := promptBuildRequestForTurn(ts, exec.history, exec.summary, "", nil, p.Cfg)
-			rebuildPromptReq.ActiveSkills = append([]string(nil), contextualSkills...)
-			exec.messages = ts.agent.ContextBuilder.BuildMessagesFromPrompt(rebuildPromptReq)
-			exec.callMessages = exec.messages
+			stableHistory, protectedTurnTail := splitHistoryForActiveTurn(
+				exec.history,
+				ts.persistedMessagesSnapshot(),
+			)
+			buildMessages := func(trimmedHistory []providers.Message) []providers.Message {
+				fullHistory := append(append([]providers.Message(nil), trimmedHistory...), protectedTurnTail...)
+				rebuildPromptReq := promptBuildRequestForTurn(ts, fullHistory, exec.summary, "", nil, p.Cfg)
+				rebuildPromptReq.ActiveSkills = append([]string(nil), contextualSkills...)
+				rebuilt := ts.agent.ContextBuilder.BuildMessagesFromPrompt(rebuildPromptReq)
+				return resolveMediaRefs(
+					rebuilt,
+					p.MediaStore,
+					maxMediaSize,
+					len(rebuilt)-len(protectedTurnTail),
+				)
+			}
+			originalHistoryCount := len(exec.history)
+			var fit bool
+			var trimmedStableHistory []providers.Message
+			trimmedStableHistory, exec.callMessages, fit = trimHistoryToFitContextWindow(
+				stableHistory,
+				func(trimmedHistory []providers.Message) []providers.Message {
+					rebuilt := buildMessages(trimmedHistory)
+					if exec.gracefulTerminal {
+						return append(append([]providers.Message(nil), rebuilt...), ts.interruptHintMessage())
+					}
+					return rebuilt
+				},
+				ts.agent.ContextWindow,
+				exec.providerToolDefs,
+				ts.agent.MaxTokens,
+			)
+			exec.history = append(trimmedStableHistory, protectedTurnTail...)
+			exec.messages = buildMessages(trimmedStableHistory)
+			exec.currentTurnStart = len(exec.messages) - len(protectedTurnTail)
 			if exec.gracefulTerminal {
 				msgs := append([]providers.Message(nil), exec.messages...)
 				exec.callMessages = append(msgs, ts.interruptHintMessage())
 			}
+			if dropped := originalHistoryCount - len(exec.history); dropped > 0 {
+				logger.WarnCF("agent", "Trimmed rebuilt history after context retry compaction", map[string]any{
+					"session_key":     ts.sessionKey,
+					"retry":           retry,
+					"dropped_msgs":    dropped,
+					"remaining_msgs":  len(exec.history),
+					"context_window":  ts.agent.ContextWindow,
+					"max_tokens":      ts.agent.MaxTokens,
+					"still_overlimit": !fit,
+				})
+			} else if !fit {
+				logger.WarnCF("agent", "Context still exceeds budget after retry compaction rebuild", map[string]any{
+					"session_key":         ts.sessionKey,
+					"retry":               retry,
+					"history_msgs":        len(exec.history),
+					"protected_turn_msgs": len(protectedTurnTail),
+					"context_window":      ts.agent.ContextWindow,
+					"max_tokens":          ts.agent.MaxTokens,
+				})
+			}
+			if !fit {
+				err = fmt.Errorf(
+					"context window still exceeded after retry compaction; refusing to drop active turn messages: %w",
+					err,
+				)
+				break
+			}
 			continue
 		}
 		break
@@ -684,3 +707,45 @@ func providerForFallbackCandidate(
 	}
 	return activeProvider, nil
 }
+
+func transientLLMRetryReason(err error) (string, bool) {
+	if err == nil {
+		return "", false
+	}
+
+	if failErr := providers.ClassifyError(err, "", ""); failErr != nil {
+		switch failErr.Reason {
+		case providers.FailoverTimeout:
+			if failErr.Status >= 500 {
+				return "server_error", true
+			}
+			return "timeout", true
+		case providers.FailoverNetwork:
+			return "network", true
+		case providers.FailoverRateLimit, providers.FailoverOverloaded:
+			return "rate_limit", true
+		}
+	}
+
+	errMsg := strings.ToLower(err.Error())
+	if errors.Is(err, context.DeadlineExceeded) ||
+		strings.Contains(errMsg, "deadline exceeded") ||
+		strings.Contains(errMsg, "client.timeout") ||
+		strings.Contains(errMsg, "timed out") ||
+		strings.Contains(errMsg, "timeout exceeded") {
+		return "timeout", true
+	}
+
+	if strings.Contains(errMsg, "connection reset") ||
+		strings.Contains(errMsg, "connection refused") ||
+		strings.Contains(errMsg, "broken pipe") ||
+		strings.Contains(errMsg, "no such host") ||
+		strings.Contains(errMsg, "network is unreachable") ||
+		strings.Contains(errMsg, "read tcp") ||
+		strings.Contains(errMsg, "write tcp") ||
+		strings.Contains(errMsg, "eof") {
+		return "network", true
+	}
+
+	return "", false
+}

pkg/agent/pipeline_setup.go

@@ -39,8 +39,12 @@ func (p *Pipeline) SetupTurn(ctx context.Context, ts *turnState) (*turnExecution
 	initialPromptReq := promptBuildRequestForTurn(ts, history, summary, ts.userMessage, ts.media, cfg)
 	initialPromptReq.ActiveSkills = append([]string(nil), contextualSkills...)
 	messages := ts.agent.ContextBuilder.BuildMessagesFromPrompt(initialPromptReq)
+	currentTurnStart := len(messages)
+	if strings.TrimSpace(ts.userMessage) != "" || len(ts.media) > 0 {
+		currentTurnStart = len(messages) - 1
+	}
 
-	messages = resolveMediaRefs(messages, p.MediaStore, maxMediaSize)
+	messages = resolveMediaRefs(messages, p.MediaStore, maxMediaSize, currentTurnStart)
 
 	if !ts.opts.NoHistory {
 		toolDefs := filterToolsByTurnProfile(ts.agent.Tools.ToProviderDefs(), ts.profile)
@@ -66,10 +70,49 @@ func (p *Pipeline) SetupTurn(ctx context.Context, ts *turnState) (*turnExecution
 				history = resp.History
 				summary = resp.Summary
 			}
-			rebuildPromptReq := promptBuildRequestForTurn(ts, history, summary, ts.userMessage, ts.media, cfg)
-			rebuildPromptReq.ActiveSkills = append([]string(nil), contextualSkills...)
-			messages = ts.agent.ContextBuilder.BuildMessagesFromPrompt(rebuildPromptReq)
-			messages = resolveMediaRefs(messages, p.MediaStore, maxMediaSize)
+			originalHistoryCount := len(history)
+			var fit bool
+			history, messages, fit = trimHistoryToFitContextWindow(
+				history,
+				func(trimmedHistory []providers.Message) []providers.Message {
+					rebuildPromptReq := promptBuildRequestForTurn(
+						ts,
+						trimmedHistory,
+						summary,
+						ts.userMessage,
+						ts.media,
+						cfg,
+					)
+					rebuildPromptReq.ActiveSkills = append([]string(nil), contextualSkills...)
+					rebuilt := ts.agent.ContextBuilder.BuildMessagesFromPrompt(rebuildPromptReq)
+					rebuiltCurrentTurnStart := len(rebuilt)
+					if strings.TrimSpace(ts.userMessage) != "" || len(ts.media) > 0 {
+						rebuiltCurrentTurnStart = len(rebuilt) - 1
+					}
+					return resolveMediaRefs(rebuilt, p.MediaStore, maxMediaSize, rebuiltCurrentTurnStart)
+				},
+				ts.agent.ContextWindow,
+				toolDefs,
+				ts.agent.MaxTokens,
+			)
+			if dropped := originalHistoryCount - len(history); dropped > 0 {
+				logger.WarnCF("agent", "Trimmed rebuilt history after proactive compaction", map[string]any{
+					"session_key":     ts.sessionKey,
+					"dropped_msgs":    dropped,
+					"remaining_msgs":  len(history),
+					"context_window":  ts.agent.ContextWindow,
+					"max_tokens":      ts.agent.MaxTokens,
+					"still_overlimit": !fit,
+				})
+			} else if !fit {
+				logger.WarnCF("agent", "Context still exceeds budget "+
+					"after proactive compaction rebuild", map[string]any{
+					"session_key":    ts.sessionKey,
+					"history_msgs":   len(history),
+					"context_window": ts.agent.ContextWindow,
+					"max_tokens":     ts.agent.MaxTokens,
+				})
+			}
 		}
 	}
 
@@ -102,6 +145,7 @@ func (p *Pipeline) SetupTurn(ctx context.Context, ts *turnState) (*turnExecution
 		summary,
 		messages,
 	)
+	exec.currentTurnStart = currentTurnStart
 	exec.activeCandidates = activeCandidates
 	exec.activeModel = activeModel
 	exec.activeModelConfig = resolveActiveModelConfig(

pkg/agent/prompt.go

@@ -37,6 +37,7 @@ const (
 	PromptSlotMessage      PromptSlot = "message"
 	PromptSlotSteering     PromptSlot = "steering"
 	PromptSlotSubTurn      PromptSlot = "subturn"
+	PromptSlotToolResult   PromptSlot = "tool_result"
 	PromptSlotInterrupt    PromptSlot = "interrupt"
 	PromptSlotOutput       PromptSlot = "output"
 )
@@ -60,6 +61,7 @@ const (
 	PromptSourceUserMessage    PromptSourceID = "turn:user_message"
 	PromptSourceSteering       PromptSourceID = "turn:steering"
 	PromptSourceSubTurnResult  PromptSourceID = "turn:subturn_result"
+	PromptSourceToolResult     PromptSourceID = "turn:tool_result"
 	PromptSourceInterrupt      PromptSourceID = "turn:interrupt"
 )
 

pkg/agent/prompt_turn.go

@@ -194,6 +194,29 @@ func userPromptMessage(content string, media []string) providers.Message {
 	return promptMessageWithMetadata(msg, PromptLayerTurn, PromptSlotMessage, PromptSourceUserMessage)
 }
 
+func toolResultPromptMessage(content, toolCallID string, media []string) providers.Message {
+	msg := providers.Message{
+		Role:       "tool",
+		Content:    content,
+		ToolCallID: toolCallID,
+	}
+	if len(media) > 0 {
+		msg.Media = append([]string(nil), media...)
+	}
+	return promptMessageWithMetadata(msg, PromptLayerTurn, PromptSlotToolResult, PromptSourceToolResult)
+}
+
+func toolImageFollowUpPromptMessage(media []string) providers.Message {
+	msg := providers.Message{
+		Role:    "user",
+		Content: "[Loaded image from tool result above]",
+	}
+	if len(media) > 0 {
+		msg.Media = append([]string(nil), media...)
+	}
+	return promptMessageWithMetadata(msg, PromptLayerTurn, PromptSlotToolResult, PromptSourceToolResult)
+}
+
 func steeringPromptMessage(msg providers.Message) providers.Message {
 	return promptMessageWithDefaultMetadata(msg, PromptLayerTurn, PromptSlotSteering, PromptSourceSteering)
 }

pkg/agent/runtime_event_logger_test.go

@@ -2,6 +2,8 @@ package agent
 
 import (
 	"context"
+	"errors"
+	"sync"
 	"sync/atomic"
 	"testing"
 	"time"
@@ -9,6 +11,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/config"
 	runtimeevents "github.com/sipeed/picoclaw/pkg/events"
+	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
 func TestRuntimeEventLoggerFiltering(t *testing.T) {
@@ -191,6 +194,164 @@ func TestReloadProviderAndConfigRefreshesRuntimeEventLogger(t *testing.T) {
 	}
 }
 
+type reloadBlockingProvider struct {
+	chatStarted chan struct{}
+	releaseChat chan struct{}
+	closeCalled chan struct{}
+}
+
+func (p *reloadBlockingProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	options map[string]any,
+) (*providers.LLMResponse, error) {
+	select {
+	case <-p.chatStarted:
+	default:
+		close(p.chatStarted)
+	}
+
+	select {
+	case <-p.releaseChat:
+		return &providers.LLMResponse{Content: "done"}, nil
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	}
+}
+
+func (p *reloadBlockingProvider) GetDefaultModel() string {
+	return "reload-blocking"
+}
+
+func (p *reloadBlockingProvider) Close() {
+	select {
+	case <-p.closeCalled:
+	default:
+		close(p.closeCalled)
+	}
+}
+
+func TestReloadProviderAndConfigWaitsForInFlightRequestsBeforeClosingOldProvider(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.Workspace = t.TempDir()
+
+	oldProvider := &reloadBlockingProvider{
+		chatStarted: make(chan struct{}),
+		releaseChat: make(chan struct{}),
+		closeCalled: make(chan struct{}),
+	}
+	al := NewAgentLoop(cfg, bus.NewMessageBus(), oldProvider)
+	defer al.Close()
+
+	msg := testInboundMessage(bus.InboundMessage{
+		Channel:  "test",
+		ChatID:   "reload-chat",
+		SenderID: "user-1",
+		Content:  "hold request open",
+	})
+
+	reqDone := make(chan error, 1)
+	go func() {
+		_, err := al.processMessage(context.Background(), msg)
+		reqDone <- err
+	}()
+
+	select {
+	case <-oldProvider.chatStarted:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for in-flight provider request")
+	}
+
+	reloadDone := make(chan error, 1)
+	go func() {
+		reloaded := config.DefaultConfig()
+		reloaded.Agents.Defaults.Workspace = cfg.Agents.Defaults.Workspace
+		reloadDone <- al.ReloadProviderAndConfig(context.Background(), &mockProvider{}, reloaded)
+	}()
+
+	select {
+	case <-oldProvider.closeCalled:
+		t.Fatal("old provider closed before in-flight request completed")
+	case err := <-reloadDone:
+		t.Fatalf("reload returned early: %v", err)
+	case <-time.After(150 * time.Millisecond):
+	}
+
+	close(oldProvider.releaseChat)
+
+	select {
+	case err := <-reqDone:
+		if err != nil {
+			t.Fatalf("processMessage() error = %v", err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for in-flight request to complete")
+	}
+
+	select {
+	case err := <-reloadDone:
+		if err != nil {
+			t.Fatalf("ReloadProviderAndConfig() error = %v", err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for reload to finish")
+	}
+
+	select {
+	case <-oldProvider.closeCalled:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for old provider close")
+	}
+}
+
+func TestWaitForActiveRequestsHonorsContextCancellation(t *testing.T) {
+	al := &AgentLoop{}
+	al.activeReqCond = sync.NewCond(&al.activeReqMu)
+	al.activeRequestsInc()
+	defer al.activeRequestsDec()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	if al.waitForActiveRequests(ctx, time.Second) {
+		t.Fatal("waitForActiveRequests() = true, want false on canceled context")
+	}
+}
+
+func TestReloadProviderAndConfigReturnsCanceledErrorWhenRegistryCreationPanics(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.Workspace = t.TempDir()
+
+	al := NewAgentLoop(cfg, bus.NewMessageBus(), &mockProvider{})
+	defer al.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err := al.ReloadProviderAndConfig(ctx, &panicProviderForReloadTest{}, cfg)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("ReloadProviderAndConfig() error = %v, want context canceled", err)
+	}
+}
+
+type panicProviderForReloadTest struct{}
+
+func (p *panicProviderForReloadTest) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	options map[string]any,
+) (*providers.LLMResponse, error) {
+	return &providers.LLMResponse{Content: "unused"}, nil
+}
+
+func (p *panicProviderForReloadTest) GetDefaultModel() string {
+	panic("boom")
+}
+
 func TestCloseRuntimeEventLoggerSubscriptionWaitsForDrain(t *testing.T) {
 	eventBus := runtimeevents.NewBus()
 	defer func() {

pkg/agent/steering_test.go

@@ -1618,6 +1618,8 @@ func TestAgentLoop_InterruptHard_RestoresSession(t *testing.T) {
 	}
 	defaultAgent.Sessions.SetHistory(sessionKey, originalHistory)
 
+	originalHistory = defaultAgent.Sessions.GetHistory(sessionKey)
+
 	runtimeCh, closeRuntimeEvents := subscribeRuntimeEventsForTest(
 		t,
 		al,

pkg/agent/turn_coord.go

@@ -150,7 +150,7 @@ func (al *AgentLoop) runTurn(ctx context.Context, ts *turnState, pipeline *Pipel
 
 		// Inject pending steering messages
 		if len(pendingMessages) > 0 {
-			resolvedPending := resolveMediaRefs(pendingMessages, al.mediaStore, maxMediaSize)
+			resolvedPending := resolveMediaRefs(pendingMessages, al.mediaStore, maxMediaSize, 0)
 			totalContentLen := 0
 			for i, pm := range pendingMessages {
 				messages = append(messages, resolvedPending[i])
@@ -431,7 +431,11 @@ func (al *AgentLoop) askSideQuestion(
 	messages := agent.ContextBuilder.BuildMessagesFromPrompt(promptReq)
 
 	maxMediaSize := al.GetConfig().Agents.Defaults.GetMaxMediaSize()
-	messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize)
+	currentTurnStart := len(messages)
+	if strings.TrimSpace(question) != "" || len(media) > 0 {
+		currentTurnStart = len(messages) - 1
+	}
+	messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize, currentTurnStart)
 
 	activeCandidates, activeModel, usedLight := al.selectCandidates(agent, question, messages)
 	selectedModelName := sideQuestionModelName(agent, usedLight)

pkg/agent/turn_coord_test.go

@@ -193,6 +193,38 @@ func (p *errorProvider) GetDefaultModel() string {
 	return "error-model"
 }
 
+type failOnceLLMProvider struct {
+	err       error
+	response  string
+	callCount int
+	mu        sync.Mutex
+}
+
+func (p *failOnceLLMProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	p.mu.Lock()
+	p.callCount++
+	callCount := p.callCount
+	p.mu.Unlock()
+
+	if callCount == 1 {
+		return nil, p.err
+	}
+	return &providers.LLMResponse{
+		Content:      p.response,
+		FinishReason: "stop",
+	}, nil
+}
+
+func (p *failOnceLLMProvider) GetDefaultModel() string {
+	return "fail-once-model"
+}
+
 // =============================================================================
 // Test Helper Functions
 // =============================================================================
@@ -586,6 +618,59 @@ func TestPipeline_CallLLM_TimeoutRetry(t *testing.T) {
 	}
 }
 
+func TestPipeline_CallLLM_HTTP5xxRetry(t *testing.T) {
+	tmpDir := t.TempDir()
+	provider := &failOnceLLMProvider{
+		err:      errors.New("API request failed:\n  Status: 500\n  Body:   internal server error"),
+		response: "Recovered from server error",
+	}
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:           tmpDir,
+				ModelName:           "test-model",
+				MaxTokens:           4096,
+				MaxToolIterations:   10,
+				MaxLLMRetries:       1,
+				LLMRetryBackoffSecs: 1,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+	defer al.Close()
+	agent := al.registry.GetDefaultAgent()
+	if agent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	pipeline := NewPipeline(al)
+	ts := newTurnState(agent, makeTestProcessOpts("test-session"), turnEventScope{
+		turnID:  "turn-1",
+		context: newTurnContext(nil, nil, nil),
+	})
+
+	exec, err := pipeline.SetupTurn(context.Background(), ts)
+	if err != nil {
+		t.Fatalf("SetupTurn failed: %v", err)
+	}
+
+	ctrl, err := pipeline.CallLLM(context.Background(), context.Background(), ts, exec, 1)
+	if err != nil {
+		t.Fatalf("expected HTTP 500 retry to recover, got error: %v", err)
+	}
+	if ctrl != ControlBreak {
+		t.Fatalf("expected ControlBreak, got %v", ctrl)
+	}
+	if exec.finalContent != "Recovered from server error" {
+		t.Fatalf("finalContent = %q, want recovered response", exec.finalContent)
+	}
+	if provider.callCount != 2 {
+		t.Fatalf("callCount = %d, want 2", provider.callCount)
+	}
+}
+
 func TestPipeline_CallLLM_ContextLengthError(t *testing.T) {
 	errorPrv := &errorProvider{errType: "context_length"}
 	al, agent, cleanup := newTurnCoordTestLoop(t, errorPrv)

pkg/agent/turn_profile_test.go

@@ -105,9 +105,10 @@ func TestTurnProfile_DisabledPreservesDefaultHistoryAndPrompt(t *testing.T) {
 	al := newTurnProfileAgentLoop(t, cfg, provider)
 	agent := al.GetRegistry().GetDefaultAgent()
 	sessionKey := "agent:default:test-default"
+	ts := time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)
 	initialHistory := []providers.Message{
-		{Role: "user", Content: "old user"},
-		{Role: "assistant", Content: "old assistant"},
+		{Role: "user", Content: "old user", CreatedAt: &ts},
+		{Role: "assistant", Content: "old assistant", CreatedAt: &ts},
 	}
 	agent.Sessions.SetHistory(sessionKey, initialHistory)
 	agent.Sessions.SetSummary(sessionKey, "old summary")
@@ -154,9 +155,10 @@ func TestTurnProfile_HistoryOffSuppressesHistoryAndPersistence(t *testing.T) {
 	al := newTurnProfileAgentLoop(t, cfg, provider)
 	agent := al.GetRegistry().GetDefaultAgent()
 	sessionKey := "agent:default:test-history-off"
+	ts := time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)
 	initialHistory := []providers.Message{
-		{Role: "user", Content: "old user"},
-		{Role: "assistant", Content: "old assistant"},
+		{Role: "user", Content: "old user", CreatedAt: &ts},
+		{Role: "assistant", Content: "old assistant", CreatedAt: &ts},
 	}
 	agent.Sessions.SetHistory(sessionKey, initialHistory)
 	agent.Sessions.SetSummary(sessionKey, "old summary")

pkg/agent/turn_state.go

@@ -114,10 +114,11 @@ type ActiveTurnInfo struct {
 
 type turnExecution struct {
 	// Core message state (accumulates throughout the turn)
-	messages        []providers.Message // built from ContextBuilder, grows per-iteration
-	pendingMessages []providers.Message // steering/SubTurn messages awaiting injection
-	history         []providers.Message // from ContextManager.Assemble
-	summary         string
+	messages         []providers.Message // built from ContextBuilder, grows per-iteration
+	pendingMessages  []providers.Message // steering/SubTurn messages awaiting injection
+	history          []providers.Message // from ContextManager.Assemble
+	summary          string
+	currentTurnStart int
 
 	// Turn output
 	finalContent string
@@ -164,12 +165,13 @@ func newTurnExecution(
 	messages []providers.Message,
 ) *turnExecution {
 	return &turnExecution{
-		history:         history,
-		summary:         summary,
-		messages:        messages,
-		pendingMessages: append([]providers.Message(nil), opts.InitialSteeringMessages...),
-		iteration:       0,
-		phase:           LLMPhaseSetup,
+		history:          history,
+		summary:          summary,
+		messages:         messages,
+		pendingMessages:  append([]providers.Message(nil), opts.InitialSteeringMessages...),
+		currentTurnStart: len(messages),
+		iteration:        0,
+		phase:            LLMPhaseSetup,
 	}
 }
 
@@ -288,7 +290,17 @@ func (al *AgentLoop) registerActiveTurn(ts *turnState) {
 }
 
 func (al *AgentLoop) clearActiveTurn(ts *turnState) {
-	al.activeTurnStates.Delete(ts.sessionKey)
+	al.releaseSessionTurnState(ts.sessionKey, ts)
+}
+
+func (al *AgentLoop) releaseSessionTurnState(sessionKey string, expected *turnState) {
+	if expected == nil {
+		al.activeTurnStates.Delete(sessionKey)
+		return
+	}
+	if actual, ok := al.activeTurnStates.Load(sessionKey); ok && actual == expected {
+		al.activeTurnStates.Delete(sessionKey)
+	}
 }
 
 func (al *AgentLoop) getActiveTurnState(sessionKey string) *turnState {
@@ -643,13 +655,17 @@ func (ts *turnState) recordPersistedMessage(msg providers.Message) {
 	ts.persistedMessages = append(ts.persistedMessages, msg)
 }
 
+func (ts *turnState) persistedMessagesSnapshot() []providers.Message {
+	ts.mu.RLock()
+	defer ts.mu.RUnlock()
+	return append([]providers.Message(nil), ts.persistedMessages...)
+}
+
 func (ts *turnState) refreshRestorePointFromSession(agent *AgentInstance) {
 	history := agent.Sessions.GetHistory(ts.sessionKey)
 	summary := agent.Sessions.GetSummary(ts.sessionKey)
 
-	ts.mu.RLock()
-	persisted := append([]providers.Message(nil), ts.persistedMessages...)
-	ts.mu.RUnlock()
+	persisted := ts.persistedMessagesSnapshot()
 
 	if matched := matchingTurnMessageTail(history, persisted); matched > 0 {
 		history = append([]providers.Message(nil), history[:len(history)-matched]...)
@@ -689,13 +705,83 @@ func (ts *turnState) restoreSession(agent *AgentInstance) error {
 func matchingTurnMessageTail(history, persisted []providers.Message) int {
 	maxMatch := min(len(history), len(persisted))
 	for size := maxMatch; size > 0; size-- {
-		if reflect.DeepEqual(history[len(history)-size:], persisted[len(persisted)-size:]) {
+		if messageSlicesEquivalent(history[len(history)-size:], persisted[len(persisted)-size:]) {
 			return size
 		}
 	}
 	return 0
 }
 
+func splitHistoryForActiveTurn(
+	history []providers.Message,
+	persisted []providers.Message,
+) ([]providers.Message, []providers.Message) {
+	matched := matchingTurnMessageTail(history, persisted)
+	if matched <= 0 {
+		return append([]providers.Message(nil), history...), nil
+	}
+
+	stable := append([]providers.Message(nil), history[:len(history)-matched]...)
+	protected := append([]providers.Message(nil), history[len(history)-matched:]...)
+	return stable, protected
+}
+
+func messageSlicesEquivalent(a, b []providers.Message) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if !messagesEquivalent(a[i], b[i]) {
+			return false
+		}
+	}
+	return true
+}
+
+func messagesEquivalent(a, b providers.Message) bool {
+	return reflect.DeepEqual(normalizeMessageForComparison(a), normalizeMessageForComparison(b))
+}
+
+func normalizeMessageForComparison(msg providers.Message) providers.Message {
+	msg.PromptLayer = ""
+	msg.PromptSlot = ""
+	msg.PromptSource = ""
+
+	if len(msg.Media) == 0 {
+		msg.Media = nil
+	}
+	if len(msg.Attachments) == 0 {
+		msg.Attachments = nil
+	}
+	if len(msg.SystemParts) == 0 {
+		msg.SystemParts = nil
+	} else {
+		msg.SystemParts = append([]providers.ContentBlock(nil), msg.SystemParts...)
+		for i := range msg.SystemParts {
+			msg.SystemParts[i].PromptLayer = ""
+			msg.SystemParts[i].PromptSlot = ""
+			msg.SystemParts[i].PromptSource = ""
+		}
+	}
+	if len(msg.ToolCalls) == 0 {
+		msg.ToolCalls = nil
+	} else {
+		msg.ToolCalls = append([]providers.ToolCall(nil), msg.ToolCalls...)
+		for i := range msg.ToolCalls {
+			msg.ToolCalls[i].Name = ""
+			msg.ToolCalls[i].Arguments = nil
+			msg.ToolCalls[i].ThoughtSignature = ""
+			if msg.ToolCalls[i].Function != nil {
+				fn := *msg.ToolCalls[i].Function
+				fn.ThoughtSignature = ""
+				msg.ToolCalls[i].Function = &fn
+			}
+		}
+	}
+
+	return msg
+}
+
 func (ts *turnState) interruptHintMessage() providers.Message {
 	_, hint := ts.gracefulInterruptRequested()
 	content := "Interrupt requested. Stop scheduling tools and provide a short final summary."

pkg/agent/turn_state_test.go

@@ -0,0 +1,112 @@
+package agent
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func TestMatchingTurnMessageTail_IgnoresInternalRuntimeFields(t *testing.T) {
+	history := []providers.Message{
+		{Role: "user", Content: "question"},
+		{
+			Role: "assistant",
+			ToolCalls: []providers.ToolCall{
+				{
+					ID:   "call_1",
+					Type: "function",
+					Function: &providers.FunctionCall{
+						Name:      "read_file",
+						Arguments: `{"path":"/tmp/test"}`,
+					},
+				},
+			},
+		},
+	}
+
+	persisted := []providers.Message{
+		userPromptMessage("question", nil),
+		{
+			Role: "assistant",
+			ToolCalls: []providers.ToolCall{
+				{
+					ID:               "call_1",
+					Type:             "function",
+					Name:             "read_file",
+					Arguments:        map[string]any{"path": "/tmp/test"},
+					ThoughtSignature: "internal-signature",
+					Function: &providers.FunctionCall{
+						Name:             "read_file",
+						Arguments:        `{"path":"/tmp/test"}`,
+						ThoughtSignature: "internal-signature",
+					},
+				},
+			},
+		},
+	}
+
+	if got := matchingTurnMessageTail(history, persisted); got != 2 {
+		t.Fatalf("matchingTurnMessageTail() = %d, want 2", got)
+	}
+}
+
+func TestSplitHistoryForActiveTurn_ProtectsPersistedTail(t *testing.T) {
+	history := []providers.Message{
+		{Role: "user", Content: "old question"},
+		{Role: "assistant", Content: "old answer"},
+		{Role: "user", Content: "current question"},
+		{Role: "tool", Content: "tool output", ToolCallID: "call_1"},
+	}
+
+	persisted := []providers.Message{
+		userPromptMessage("current question", nil),
+		{Role: "tool", Content: "tool output", ToolCallID: "call_1"},
+	}
+
+	stable, protected := splitHistoryForActiveTurn(history, persisted)
+	if len(stable) != 2 {
+		t.Fatalf("stable history len = %d, want 2", len(stable))
+	}
+	if len(protected) != 2 {
+		t.Fatalf("protected tail len = %d, want 2", len(protected))
+	}
+	if protected[0].Content != "current question" {
+		t.Fatalf("protected[0].Content = %q, want current question", protected[0].Content)
+	}
+}
+
+func TestTrimHistoryToFitContextWindow_WithProtectedTurnTailKeepsActiveTurn(t *testing.T) {
+	current := strings.Repeat("current turn ", 80)
+	history := []providers.Message{
+		{Role: "user", Content: strings.Repeat("old turn ", 60)},
+		{Role: "assistant", Content: strings.Repeat("old reply ", 60)},
+		{Role: "user", Content: current},
+	}
+
+	stable, protected := splitHistoryForActiveTurn(history, []providers.Message{
+		userPromptMessage(current, nil),
+	})
+	trimmedStable, messages, fit := trimHistoryToFitContextWindow(
+		stable,
+		func(trimmedHistory []providers.Message) []providers.Message {
+			return append(append([]providers.Message(nil), trimmedHistory...), protected...)
+		},
+		120,
+		nil,
+		0,
+	)
+
+	if fit {
+		t.Fatal("expected protected active turn alone to remain over budget")
+	}
+	if len(trimmedStable) != 0 {
+		t.Fatalf("trimmed stable history len = %d, want 0", len(trimmedStable))
+	}
+	if len(messages) != 1 {
+		t.Fatalf("messages len = %d, want 1 protected active-turn message", len(messages))
+	}
+	if messages[0].Content != current {
+		t.Fatalf("messages[0].Content = %q, want protected current turn", messages[0].Content)
+	}
+}

pkg/audio/tts/README.md

@@ -25,6 +25,8 @@ Instead:
 
 - `voice.tts_model_name` selects a named entry from `model_list`.
 - That `model_list` entry provides the provider, model ID, API base, and proxy settings.
+- For providers that need model-specific TTS parameters, use `model_list[].extra_body`
+  to pass fields such as `voice` and `response_format`.
 - `.security.yml` stores the API key for the same named model entry.
 
 This is the recommended and supported configuration pattern.
@@ -87,6 +89,43 @@ model_list:
 
 If you use a custom MiMo endpoint, you can also set `api_base` explicitly. Otherwise PicoClaw will use the provider default.
 
+### Option C: OpenRouter MAI Voice 2
+
+Some OpenAI-compatible TTS routes require provider-specific request fields.
+OpenRouter's `microsoft/mai-voice-2` is one example: it needs a model-specific
+voice name and works best with `response_format: "mp3"`.
+
+`config.json`
+
+```json
+{
+  "voice": {
+    "tts_model_name": "mai-voice-2"
+  },
+  "model_list": [
+    {
+      "model_name": "mai-voice-2",
+      "provider": "openrouter",
+      "model": "microsoft/mai-voice-2",
+      "api_base": "https://openrouter.ai/api/v1",
+      "extra_body": {
+        "voice": "en-US-Harper:MAI-Voice-2",
+        "response_format": "mp3"
+      }
+    }
+  ]
+}
+```
+
+`.security.yml`
+
+```yaml
+model_list:
+  mai-voice-2:
+    api_keys:
+      - "sk-or-your-openrouter-key"
+```
+
 ## What PicoClaw Sends Today
 
 The current TTS runtime uses an OpenAI-compatible speech request with these defaults:
@@ -96,11 +135,14 @@ The current TTS runtime uses an OpenAI-compatible speech request with these defa
 - Voice: `alloy`
 - Model: taken from the selected `model_list` entry
 
+These defaults can now be overridden per model through `model_list[].extra_body`.
+
 That means:
 
 - `openai/tts-1` works naturally.
 - Other OpenAI-compatible providers can work if they accept the same request format.
-- PicoClaw currently does not expose a user-facing config field for changing the TTS voice from `alloy`.
+- Provider-specific TTS models may need their own `voice` and `response_format` values.
+- If a provider rejects `response_format`, PicoClaw retries once without that field.
 
 ## How PicoClaw Chooses a TTS Provider
 
@@ -124,7 +166,8 @@ PicoClaw normalizes the configured base URL for TTS:
 
 - Setting `voice.tts_model_name` to a name that does not exist in `model_list`.
 - Adding a TTS model but forgetting to put its API key in `.security.yml`.
-- Assuming PicoClaw will automatically use provider-specific custom voices.
+- Assuming PicoClaw will automatically infer provider-specific custom voices.
+- Forgetting to set `model_list[].extra_body.voice` or `model_list[].extra_body.response_format` for TTS models that require them.
 - Using a provider endpoint that is not compatible with the OpenAI `/audio/speech` request format.
 
 ## Minimal Checklist

pkg/audio/tts/openai_tts.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -16,14 +17,49 @@ import (
 )
 
 type OpenAITTSProvider struct {
-	apiKey     string
-	apiBase    string
-	voice      string
-	model      string
-	httpClient *http.Client
+	apiKey         string
+	apiBase        string
+	voice          string
+	model          string
+	responseFormat string
+	httpClient     *http.Client
+}
+
+type OpenAITTSOptions struct {
+	Voice          string
+	ResponseFormat string
+}
+
+type openAITTSAudioStream struct {
+	io.ReadCloser
+	fileExt     string
+	contentType string
+}
+
+func (s *openAITTSAudioStream) AudioFileMeta() (string, string) {
+	return s.fileExt, s.contentType
+}
+
+type openAITTSAPIError struct {
+	statusCode int
+	body       string
+}
+
+func (e *openAITTSAPIError) Error() string {
+	return fmt.Sprintf("API error (status %d): %s", e.statusCode, e.body)
 }
 
 func NewOpenAITTSProvider(apiKey string, apiBase string, proxyURL string, model string) *OpenAITTSProvider {
+	return NewOpenAITTSProviderWithOptions(apiKey, apiBase, proxyURL, model, OpenAITTSOptions{})
+}
+
+func NewOpenAITTSProviderWithOptions(
+	apiKey string,
+	apiBase string,
+	proxyURL string,
+	model string,
+	options OpenAITTSOptions,
+) *OpenAITTSProvider {
 	// Normalize apiBase to avoid malformed endpoints like
 	// "https://api.openai.com/audio/speech" when "/v1" is required.
 	if apiBase == "" {
@@ -75,12 +111,23 @@ func NewOpenAITTSProvider(apiKey string, apiBase string, proxyURL string, model
 		model = "tts-1"
 	}
 
+	voice := strings.TrimSpace(options.Voice)
+	if voice == "" {
+		voice = "alloy"
+	}
+
+	responseFormat := strings.TrimSpace(options.ResponseFormat)
+	if responseFormat == "" {
+		responseFormat = "opus"
+	}
+
 	return &OpenAITTSProvider{
-		apiKey:     apiKey,
-		apiBase:    apiBase,
-		voice:      "alloy",
-		model:      model,
-		httpClient: client,
+		apiKey:         apiKey,
+		apiBase:        apiBase,
+		voice:          voice,
+		model:          model,
+		responseFormat: responseFormat,
+		httpClient:     client,
 	}
 }
 
@@ -91,11 +138,42 @@ func (t *OpenAITTSProvider) Name() string {
 func (t *OpenAITTSProvider) Synthesize(ctx context.Context, text string) (io.ReadCloser, error) {
 	logger.DebugCF("voice-tts", "Starting TTS synthesis", map[string]any{"text_len": len(text)})
 
+	responseFormat := t.responseFormat
+	stream, err := t.doSpeechRequest(ctx, text, responseFormat)
+	if err != nil {
+		var apiErr *openAITTSAPIError
+		if errors.As(err, &apiErr) && shouldRetryWithoutResponseFormat(apiErr.body) {
+			logger.InfoCF("voice-tts", "Retrying TTS without response_format after provider rejection", map[string]any{
+				"model": t.model,
+			})
+			responseFormat = ""
+			stream, err = t.doSpeechRequest(ctx, text, responseFormat)
+		}
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	fileExt, contentType := audioFileMetaForResponseFormat(responseFormat)
+	return &openAITTSAudioStream{
+		ReadCloser:  stream,
+		fileExt:     fileExt,
+		contentType: contentType,
+	}, nil
+}
+
+func (t *OpenAITTSProvider) doSpeechRequest(
+	ctx context.Context,
+	text string,
+	responseFormat string,
+) (io.ReadCloser, error) {
 	reqBody := map[string]any{
-		"model":           t.model,
-		"input":           text,
-		"voice":           t.voice,
-		"response_format": "opus",
+		"model": t.model,
+		"input": text,
+		"voice": t.voice,
+	}
+	if responseFormat != "" {
+		reqBody["response_format"] = responseFormat
 	}
 
 	jsonData, err := json.Marshal(reqBody)
@@ -118,9 +196,34 @@ func (t *OpenAITTSProvider) Synthesize(ctx context.Context, text string) (io.Rea
 
 	if resp.StatusCode != http.StatusOK {
 		defer resp.Body.Close()
-		body, _ := io.ReadAll(resp.Body)
-		return nil, fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(body))
+		body, readErr := io.ReadAll(resp.Body)
+		if readErr != nil {
+			body = []byte(fmt.Sprintf("(failed to read error body: %v)", readErr))
+		}
+		return nil, &openAITTSAPIError{
+			statusCode: resp.StatusCode,
+			body:       string(body),
+		}
 	}
 
 	return resp.Body, nil
 }
+
+func shouldRetryWithoutResponseFormat(body string) bool {
+	lower := strings.ToLower(body)
+	if !strings.Contains(lower, "response_format") {
+		return false
+	}
+	return strings.Contains(lower, "invalid") || strings.Contains(lower, "unsupported")
+}
+
+func audioFileMetaForResponseFormat(responseFormat string) (string, string) {
+	switch strings.ToLower(strings.TrimSpace(responseFormat)) {
+	case "", "mp3":
+		return ".mp3", "audio/mpeg"
+	case "wav":
+		return ".wav", "audio/wav"
+	default:
+		return ".ogg", "audio/ogg"
+	}
+}

pkg/audio/tts/tts.go

@@ -19,6 +19,10 @@ type TTSProvider interface {
 	Synthesize(ctx context.Context, text string) (io.ReadCloser, error)
 }
 
+type ttsAudioMetaProvider interface {
+	AudioFileMeta() (fileExt string, contentType string)
+}
+
 func providerFromModelConfig(mc *config.ModelConfig) TTSProvider {
 	if mc == nil || mc.APIKey() == "" {
 		return nil
@@ -33,10 +37,31 @@ func providerFromModelConfig(mc *config.ModelConfig) TTSProvider {
 	case "mimo":
 		return NewMimoTTSProvider(mc.APIKey(), providers.ResolveAPIBase(mc), modelID, mc.Proxy)
 	default:
-		return NewOpenAITTSProvider(mc.APIKey(), providers.ResolveAPIBase(mc), mc.Proxy, modelID)
+		return NewOpenAITTSProviderWithOptions(
+			mc.APIKey(),
+			providers.ResolveAPIBase(mc),
+			mc.Proxy,
+			modelID,
+			openAITTSOptionsFromModelConfig(mc),
+		)
 	}
 }
 
+func openAITTSOptionsFromModelConfig(mc *config.ModelConfig) OpenAITTSOptions {
+	options := OpenAITTSOptions{}
+	if mc == nil || mc.ExtraBody == nil {
+		return options
+	}
+
+	if voice, ok := mc.ExtraBody["voice"].(string); ok {
+		options.Voice = strings.TrimSpace(voice)
+	}
+	if responseFormat, ok := mc.ExtraBody["response_format"].(string); ok {
+		options.ResponseFormat = strings.TrimSpace(responseFormat)
+	}
+	return options
+}
+
 func DetectTTS(cfg *config.Config) TTSProvider {
 	if cfg == nil {
 		return nil
@@ -100,6 +125,12 @@ func SynthesizeAndStore(
 		fileExt = ".mp3"
 		contentType = "audio/mpeg"
 	}
+	if metaProvider, ok := stream.(ttsAudioMetaProvider); ok {
+		if ext, ct := metaProvider.AudioFileMeta(); ext != "" && ct != "" {
+			fileExt = ext
+			contentType = ct
+		}
+	}
 
 	file, err := os.CreateTemp(media.TempDir(), "tts-*"+fileExt)
 	if err != nil {

pkg/audio/tts/tts_test.go

@@ -132,6 +132,64 @@ func TestOpenAITTSProvider_SynthesizeNon200(t *testing.T) {
 	}
 }
 
+func TestOpenAITTSProvider_SynthesizeRetriesWithoutResponseFormat(t *testing.T) {
+	var requestBodies []map[string]any
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		bodyBytes, _ := io.ReadAll(r.Body)
+		_ = r.Body.Close()
+
+		var body map[string]any
+		_ = json.Unmarshal(bodyBytes, &body)
+		requestBodies = append(requestBodies, body)
+
+		if len(requestBodies) == 1 {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte(`{"error":"response_format is invalid"}`))
+			return
+		}
+
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("audio-bytes"))
+	}))
+	defer server.Close()
+
+	provider := NewOpenAITTSProvider("k123", server.URL, "", "x-ai/grok-voice-tts-1.0")
+	stream, err := provider.Synthesize(context.Background(), "hello")
+	if err != nil {
+		t.Fatalf("Synthesize failed: %v", err)
+	}
+	defer stream.Close()
+
+	data, err := io.ReadAll(stream)
+	if err != nil {
+		t.Fatalf("read stream failed: %v", err)
+	}
+	if string(data) != "audio-bytes" {
+		t.Fatalf("response body mismatch: got %q", string(data))
+	}
+
+	if len(requestBodies) != 2 {
+		t.Fatalf("request count mismatch: got %d, want 2", len(requestBodies))
+	}
+	if requestBodies[0]["response_format"] != "opus" {
+		t.Fatalf("first request should include opus response_format, got %#v", requestBodies[0]["response_format"])
+	}
+	if _, ok := requestBodies[1]["response_format"]; ok {
+		t.Fatalf("second request should omit response_format, got %#v", requestBodies[1]["response_format"])
+	}
+
+	metaStream, ok := stream.(interface {
+		AudioFileMeta() (string, string)
+	})
+	if !ok {
+		t.Fatal("stream does not expose audio metadata")
+	}
+	fileExt, contentType := metaStream.AudioFileMeta()
+	if fileExt != ".mp3" || contentType != "audio/mpeg" {
+		t.Fatalf("audio metadata mismatch: got (%q, %q)", fileExt, contentType)
+	}
+}
+
 func TestNewOpenAITTSProvider_UsesConfiguredModel(t *testing.T) {
 	t.Parallel()
 
@@ -144,6 +202,27 @@ func TestNewOpenAITTSProvider_UsesConfiguredModel(t *testing.T) {
 	}
 }
 
+func TestNewOpenAITTSProvider_UsesConfiguredVoiceAndResponseFormat(t *testing.T) {
+	t.Parallel()
+
+	provider := NewOpenAITTSProviderWithOptions(
+		"key",
+		"https://openrouter.ai/api/v1",
+		"",
+		"microsoft/mai-voice-2",
+		OpenAITTSOptions{
+			Voice:          "en-US-Harper:MAI-Voice-2",
+			ResponseFormat: "mp3",
+		},
+	)
+	if provider.voice != "en-US-Harper:MAI-Voice-2" {
+		t.Fatalf("voice mismatch: got %q", provider.voice)
+	}
+	if provider.responseFormat != "mp3" {
+		t.Fatalf("responseFormat mismatch: got %q", provider.responseFormat)
+	}
+}
+
 func TestDetectTTS_UsesMimoProviderForMimoModels(t *testing.T) {
 	t.Parallel()
 
@@ -170,6 +249,36 @@ func TestDetectTTS_UsesMimoProviderForMimoModels(t *testing.T) {
 	}
 }
 
+func TestDetectTTS_UsesOpenAIExtraBodyVoiceAndResponseFormat(t *testing.T) {
+	t.Parallel()
+
+	provider := DetectTTS(&config.Config{
+		Voice: config.VoiceConfig{TTSModelName: "mai-voice"},
+		ModelList: []*config.ModelConfig{
+			{
+				ModelName: "mai-voice",
+				Model:     "openrouter/microsoft/mai-voice-2",
+				APIKeys:   config.SimpleSecureStrings("sk-openrouter"),
+				ExtraBody: map[string]any{
+					"voice":           "en-US-Harper:MAI-Voice-2",
+					"response_format": "mp3",
+				},
+			},
+		},
+	})
+
+	ttsProvider, ok := provider.(*OpenAITTSProvider)
+	if !ok {
+		t.Fatalf("DetectTTS() type = %T, want *OpenAITTSProvider", provider)
+	}
+	if ttsProvider.voice != "en-US-Harper:MAI-Voice-2" {
+		t.Fatalf("voice mismatch: got %q", ttsProvider.voice)
+	}
+	if ttsProvider.responseFormat != "mp3" {
+		t.Fatalf("responseFormat mismatch: got %q", ttsProvider.responseFormat)
+	}
+}
+
 type stubTTSProvider struct {
 	name string
 }
@@ -245,3 +354,51 @@ func TestSynthesizeAndStore_UsesMp3MetadataForMimo(t *testing.T) {
 		t.Fatalf("filename extension = %q, want %q", filepath.Ext(meta.Filename), ".mp3")
 	}
 }
+
+func TestSynthesizeAndStore_UsesStreamProvidedAudioMetadata(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		bodyBytes, _ := io.ReadAll(r.Body)
+		_ = r.Body.Close()
+
+		var body map[string]any
+		_ = json.Unmarshal(bodyBytes, &body)
+		if body["response_format"] == "opus" {
+			w.WriteHeader(http.StatusBadRequest)
+			_, _ = w.Write([]byte(`{"error":"response_format is invalid"}`))
+			return
+		}
+
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("mp3-audio"))
+	}))
+	defer server.Close()
+
+	store := media.NewFileMediaStore()
+	provider := NewOpenAITTSProvider("k123", server.URL, "", "x-ai/grok-voice-tts-1.0")
+	ref, err := SynthesizeAndStore(
+		context.Background(),
+		provider,
+		store,
+		"hello",
+		"",
+		"telegram",
+		"chat123",
+	)
+	if err != nil {
+		t.Fatalf("SynthesizeAndStore failed: %v", err)
+	}
+
+	path, meta, err := store.ResolveWithMeta(ref)
+	if err != nil {
+		t.Fatalf("ResolveWithMeta failed: %v", err)
+	}
+	if meta.ContentType != "audio/mpeg" {
+		t.Fatalf("ContentType = %q, want %q", meta.ContentType, "audio/mpeg")
+	}
+	if filepath.Ext(path) != ".mp3" {
+		t.Fatalf("stored file extension = %q, want %q", filepath.Ext(path), ".mp3")
+	}
+	if filepath.Ext(meta.Filename) != ".mp3" {
+		t.Fatalf("filename extension = %q, want %q", filepath.Ext(meta.Filename), ".mp3")
+	}
+}

pkg/bus/bus.go

@@ -3,8 +3,10 @@ package bus
 import (
 	"context"
 	"errors"
+	"fmt"
 	"sync"
 	"sync/atomic"
+	"time"
 
 	runtimeevents "github.com/sipeed/picoclaw/pkg/events"
 	"github.com/sipeed/picoclaw/pkg/logger"
@@ -13,6 +15,10 @@ import (
 // ErrBusClosed is returned when publishing to a closed MessageBus.
 var ErrBusClosed = errors.New("message bus closed")
 
+// ErrBusBackpressure is returned when a publish attempt exceeds the configured
+// backpressure wait budget and the message is dropped.
+var ErrBusBackpressure = errors.New("message bus backpressure")
+
 var (
 	ErrMissingInboundContext       = errors.New("inbound message context is required")
 	ErrMissingOutboundContext      = errors.New("outbound message context is required")
@@ -21,6 +27,41 @@ var (
 
 const defaultBusBufferSize = 64
 
+const (
+	defaultAudioPublishTimeout = 150 * time.Millisecond
+)
+
+type publishPolicy struct {
+	stream string
+	// timeout is the backpressure drop budget. When positive, a full channel
+	// causes the message to be dropped after this duration. When zero, the
+	// publish blocks until context cancellation or bus close (no drop).
+	timeout time.Duration
+}
+
+type streamStats struct {
+	dropped       atomic.Uint64
+	lastDropped   atomic.Int64
+	lastWaitNanos atomic.Int64
+}
+
+type MessageBusStats struct {
+	Inbound       StreamStats `json:"inbound"`
+	Outbound      StreamStats `json:"outbound"`
+	OutboundMedia StreamStats `json:"outbound_media"`
+	AudioChunks   StreamStats `json:"audio_chunks"`
+	VoiceControls StreamStats `json:"voice_controls"`
+}
+
+type StreamStats struct {
+	Depth              int       `json:"depth"`
+	Capacity           int       `json:"capacity"`
+	DroppedTotal       uint64    `json:"dropped_total"`
+	LastDroppedAt      time.Time `json:"last_dropped_at,omitempty"`
+	LastDropWait       string    `json:"last_drop_wait,omitempty"`
+	LastDropWaitMillis int64     `json:"last_drop_wait_ms,omitempty"`
+}
+
 // StreamDelegate is implemented by the channel Manager to provide streaming
 // capabilities to the agent loop without tight coupling.
 type StreamDelegate interface {
@@ -62,8 +103,14 @@ type MessageBus struct {
 	done           chan struct{}
 	closed         atomic.Bool
 	wg             sync.WaitGroup
+	publishMu      sync.Mutex
 	streamDelegate atomic.Value // stores StreamDelegate
 	eventPublisher atomic.Value // stores EventPublisher
+	inboundStats   streamStats
+	outboundStats  streamStats
+	mediaStats     streamStats
+	audioStats     streamStats
+	voiceStats     streamStats
 }
 
 // EventPublisher is the minimal runtime event publisher used by MessageBus.
@@ -83,13 +130,13 @@ func NewMessageBus() *MessageBus {
 	}
 }
 
-func publish[T any](ctx context.Context, mb *MessageBus, ch chan T, msg T) error {
-	// check bus closed before acquiring wg, to avoid unnecessary wg.Add and potential deadlock
+func (mb *MessageBus) enterPublish(ctx context.Context) error {
+	mb.publishMu.Lock()
+	defer mb.publishMu.Unlock()
+
 	if mb.closed.Load() {
 		return ErrBusClosed
 	}
-
-	// check again,before sending message, to avoid sending to closed channel
 	select {
 	case <-ctx.Done():
 		return ctx.Err()
@@ -99,8 +146,63 @@ func publish[T any](ctx context.Context, mb *MessageBus, ch chan T, msg T) error
 	}
 
 	mb.wg.Add(1)
+	return nil
+}
+
+func publish[T any](
+	ctx context.Context,
+	mb *MessageBus,
+	ch chan T,
+	msg T,
+	policy publishPolicy,
+	stats *streamStats,
+	scope runtimeevents.Scope,
+) error {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if err := mb.enterPublish(ctx); err != nil {
+		return err
+	}
 	defer mb.wg.Done()
 
+	// timeout == 0 means no backpressure drop budget; block until context
+	// cancellation or bus close. This is the default for critical streams
+	// (inbound, outbound, outboundMedia, voiceControl) where dropping
+	// messages silently is undesirable.
+	if policy.timeout > 0 {
+		timer := time.NewTimer(policy.timeout)
+		defer timer.Stop()
+
+		select {
+		case ch <- msg:
+			return nil
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-timer.C:
+			droppedTotal := stats.dropped.Add(1)
+			now := time.Now()
+			stats.lastDropped.Store(now.UnixNano())
+			stats.lastWaitNanos.Store(policy.timeout.Nanoseconds())
+			queueDepth := len(ch)
+			queueCap := cap(ch)
+			mb.publishDrop(
+				policy.stream, scope, "queue_full_timeout",
+				policy.timeout, queueDepth, queueCap, droppedTotal,
+			)
+			logger.WarnCF("bus", "Dropped bus message due to backpressure", map[string]any{
+				"stream":         policy.stream,
+				"wait_ms":        policy.timeout.Milliseconds(),
+				"queue_depth":    queueDepth,
+				"queue_capacity": queueCap,
+				"dropped_total":  droppedTotal,
+			})
+			return fmt.Errorf("%w: %s queue full after %s", ErrBusBackpressure, policy.stream, policy.timeout)
+		case <-mb.done:
+			return ErrBusClosed
+		}
+	}
+
 	select {
 	case ch <- msg:
 		return nil
@@ -117,8 +219,13 @@ func (mb *MessageBus) PublishInbound(ctx context.Context, msg InboundMessage) er
 		mb.publishFailure("inbound", runtimeScopeFromInboundContext(msg.Context), ErrMissingInboundContext)
 		return ErrMissingInboundContext
 	}
-	if err := publish(ctx, mb, mb.inbound, msg); err != nil {
-		mb.publishFailure("inbound", runtimeScopeFromInboundContext(msg.Context), err)
+	if err := publish(ctx, mb, mb.inbound, msg, publishPolicy{
+		stream: "inbound",
+	}, &mb.inboundStats, runtimeScopeFromInboundContext(msg.Context)); err != nil {
+		scope := runtimeScopeFromInboundContext(msg.Context)
+		if !errors.Is(err, ErrBusBackpressure) {
+			mb.publishFailure("inbound", scope, err)
+		}
 		return err
 	}
 	return nil
@@ -134,8 +241,13 @@ func (mb *MessageBus) PublishOutbound(ctx context.Context, msg OutboundMessage)
 		mb.publishFailure("outbound", runtimeScopeFromInboundContext(msg.Context), ErrMissingOutboundContext)
 		return ErrMissingOutboundContext
 	}
-	if err := publish(ctx, mb, mb.outbound, msg); err != nil {
-		mb.publishFailure("outbound", runtimeScopeFromInboundContext(msg.Context), err)
+	if err := publish(ctx, mb, mb.outbound, msg, publishPolicy{
+		stream: "outbound",
+	}, &mb.outboundStats, runtimeScopeFromInboundContext(msg.Context)); err != nil {
+		scope := runtimeScopeFromInboundContext(msg.Context)
+		if !errors.Is(err, ErrBusBackpressure) {
+			mb.publishFailure("outbound", scope, err)
+		}
 		return err
 	}
 	return nil
@@ -151,8 +263,13 @@ func (mb *MessageBus) PublishOutboundMedia(ctx context.Context, msg OutboundMedi
 		mb.publishFailure("outbound_media", runtimeScopeFromInboundContext(msg.Context), ErrMissingOutboundMediaContext)
 		return ErrMissingOutboundMediaContext
 	}
-	if err := publish(ctx, mb, mb.outboundMedia, msg); err != nil {
-		mb.publishFailure("outbound_media", runtimeScopeFromInboundContext(msg.Context), err)
+	if err := publish(ctx, mb, mb.outboundMedia, msg, publishPolicy{
+		stream: "outbound_media",
+	}, &mb.mediaStats, runtimeScopeFromInboundContext(msg.Context)); err != nil {
+		scope := runtimeScopeFromInboundContext(msg.Context)
+		if !errors.Is(err, ErrBusBackpressure) {
+			mb.publishFailure("outbound_media", scope, err)
+		}
 		return err
 	}
 	return nil
@@ -163,8 +280,14 @@ func (mb *MessageBus) OutboundMediaChan() <-chan OutboundMediaMessage {
 }
 
 func (mb *MessageBus) PublishAudioChunk(ctx context.Context, chunk AudioChunk) error {
-	if err := publish(ctx, mb, mb.audioChunks, chunk); err != nil {
-		mb.publishFailure("audio_chunk", runtimeScopeFromAudioChunk(chunk), err)
+	if err := publish(ctx, mb, mb.audioChunks, chunk, publishPolicy{
+		stream:  "audio_chunk",
+		timeout: defaultAudioPublishTimeout,
+	}, &mb.audioStats, runtimeScopeFromAudioChunk(chunk)); err != nil {
+		scope := runtimeScopeFromAudioChunk(chunk)
+		if !errors.Is(err, ErrBusBackpressure) {
+			mb.publishFailure("audio_chunk", scope, err)
+		}
 		return err
 	}
 	return nil
@@ -175,8 +298,13 @@ func (mb *MessageBus) AudioChunksChan() <-chan AudioChunk {
 }
 
 func (mb *MessageBus) PublishVoiceControl(ctx context.Context, ctrl VoiceControl) error {
-	if err := publish(ctx, mb, mb.voiceControls, ctrl); err != nil {
-		mb.publishFailure("voice_control", runtimeScopeFromVoiceControl(ctrl), err)
+	if err := publish(ctx, mb, mb.voiceControls, ctrl, publishPolicy{
+		stream: "voice_control",
+	}, &mb.voiceStats, runtimeScopeFromVoiceControl(ctrl)); err != nil {
+		scope := runtimeScopeFromVoiceControl(ctrl)
+		if !errors.Is(err, ErrBusBackpressure) {
+			mb.publishFailure("voice_control", scope, err)
+		}
 		return err
 	}
 	return nil
@@ -204,15 +332,76 @@ func (mb *MessageBus) GetStreamer(ctx context.Context, channel, chatID, sessionK
 	return nil, false
 }
 
+func (mb *MessageBus) Stats() MessageBusStats {
+	if mb == nil {
+		return MessageBusStats{}
+	}
+	return MessageBusStats{
+		Inbound:       snapshotStreamStats(mb.inbound, &mb.inboundStats),
+		Outbound:      snapshotStreamStats(mb.outbound, &mb.outboundStats),
+		OutboundMedia: snapshotStreamStats(mb.outboundMedia, &mb.mediaStats),
+		AudioChunks:   snapshotStreamStats(mb.audioChunks, &mb.audioStats),
+		VoiceControls: snapshotStreamStats(mb.voiceControls, &mb.voiceStats),
+	}
+}
+
+// HealthCheck returns a snapshot of queue depths and cumulative drop counts
+// across all streams. It always reports ok=true: backpressure-induced drops are
+// reflected in the message string for telemetry but do not affect the boolean.
+// Callers that need readiness semantics (e.g. returning 503 when drops occur)
+// should inspect Stats() directly and apply their own threshold logic.
+func (mb *MessageBus) HealthCheck() (bool, string) {
+	stats := mb.Stats()
+	totalDropped := stats.Inbound.DroppedTotal +
+		stats.Outbound.DroppedTotal +
+		stats.OutboundMedia.DroppedTotal +
+		stats.AudioChunks.DroppedTotal +
+		stats.VoiceControls.DroppedTotal
+	message := fmt.Sprintf(
+		"in=%d/%d out=%d/%d media=%d/%d audio=%d/%d voice=%d/%d dropped=%d",
+		stats.Inbound.Depth,
+		stats.Inbound.Capacity,
+		stats.Outbound.Depth,
+		stats.Outbound.Capacity,
+		stats.OutboundMedia.Depth,
+		stats.OutboundMedia.Capacity,
+		stats.AudioChunks.Depth,
+		stats.AudioChunks.Capacity,
+		stats.VoiceControls.Depth,
+		stats.VoiceControls.Capacity,
+		totalDropped,
+	)
+
+	return true, message
+}
+
+func snapshotStreamStats[T any](ch chan T, stats *streamStats) StreamStats {
+	snapshot := StreamStats{
+		DroppedTotal: stats.dropped.Load(),
+	}
+	if ch != nil {
+		snapshot.Depth = len(ch)
+		snapshot.Capacity = cap(ch)
+	}
+	if unixNano := stats.lastDropped.Load(); unixNano > 0 {
+		snapshot.LastDroppedAt = time.Unix(0, unixNano)
+	}
+	if waitNanos := stats.lastWaitNanos.Load(); waitNanos > 0 {
+		wait := time.Duration(waitNanos)
+		snapshot.LastDropWait = wait.String()
+		snapshot.LastDropWaitMillis = wait.Milliseconds()
+	}
+	return snapshot
+}
+
 func (mb *MessageBus) Close() {
 	mb.closeOnce.Do(func() {
 		mb.publishCloseEvent(runtimeevents.KindBusCloseStarted, 0)
-		// notify all blocked publishers to exit
-		close(mb.done)
 
-		// because every publisher will check mb.closed before acquiring wg
-		// so we can be sure that new publishers will not be added new messages after this point
+		mb.publishMu.Lock()
 		mb.closed.Store(true)
+		close(mb.done)
+		mb.publishMu.Unlock()
 
 		// wait for all ongoing Publish calls to finish, ensuring all messages have been sent to channels or exited
 		mb.wg.Wait()

pkg/bus/bus_test.go

@@ -2,6 +2,7 @@ package bus
 
 import (
 	"context"
+	"errors"
 	"sync"
 	"testing"
 	"time"
@@ -459,6 +460,84 @@ func TestPublishAudioChunkSubscribe(t *testing.T) {
 	}
 }
 
+func TestPublishAudioChunk_BackpressureDropPublishesRuntimeEvent(t *testing.T) {
+	eventBus := runtimeevents.NewBus()
+	defer func() {
+		if err := eventBus.Close(); err != nil {
+			t.Errorf("event bus close failed: %v", err)
+		}
+	}()
+
+	_, eventsCh, err := eventBus.Channel().OfKind(runtimeevents.KindBusMessageDropped).SubscribeChan(
+		t.Context(),
+		runtimeevents.SubscribeOptions{Name: "bus-drop-events", Buffer: 1},
+	)
+	if err != nil {
+		t.Fatalf("SubscribeChan failed: %v", err)
+	}
+
+	mb := NewMessageBus()
+	defer mb.Close()
+	mb.SetEventPublisher(eventBus)
+
+	for i := range defaultBusBufferSize * 4 {
+		if pubErr := mb.PublishAudioChunk(context.Background(), AudioChunk{
+			SessionID: "voice-1",
+			SpeakerID: "speaker-1",
+			ChatID:    "chat-1",
+			Channel:   "discord",
+			Sequence:  uint64(i),
+			Format:    "opus",
+			Data:      []byte{0x01},
+		}); pubErr != nil {
+			t.Fatalf("fill failed at %d: %v", i, pubErr)
+		}
+	}
+
+	err = mb.PublishAudioChunk(context.Background(), AudioChunk{
+		SessionID: "voice-1",
+		SpeakerID: "speaker-1",
+		ChatID:    "chat-1",
+		Channel:   "discord",
+		Sequence:  999,
+		Format:    "opus",
+		Data:      []byte{0x01},
+	})
+	if !errors.Is(err, ErrBusBackpressure) {
+		t.Fatalf("PublishAudioChunk() error = %v, want %v", err, ErrBusBackpressure)
+	}
+
+	evt := receiveBusRuntimeEvent(t, eventsCh)
+	if evt.Kind != runtimeevents.KindBusMessageDropped ||
+		evt.Source.Name != "audio_chunk" ||
+		evt.Severity != runtimeevents.SeverityWarn {
+		t.Fatalf("drop event = %+v", evt)
+	}
+	if evt.Scope.Channel != "discord" || evt.Scope.ChatID != "chat-1" {
+		t.Fatalf("drop event scope = %+v", evt.Scope)
+	}
+	if evt.Attrs["stream"] != "audio_chunk" ||
+		evt.Attrs["reason"] != "queue_full_timeout" ||
+		evt.Attrs["wait_ms"] != defaultAudioPublishTimeout.Milliseconds() ||
+		evt.Attrs["queue_depth"] != defaultBusBufferSize*4 ||
+		evt.Attrs["queue_capacity"] != defaultBusBufferSize*4 ||
+		evt.Attrs["dropped_total"] != uint64(1) {
+		t.Fatalf("drop event attrs = %#v", evt.Attrs)
+	}
+
+	stats := mb.Stats()
+	if stats.AudioChunks.DroppedTotal != 1 {
+		t.Fatalf("AudioChunks dropped = %d, want 1", stats.AudioChunks.DroppedTotal)
+	}
+	if stats.AudioChunks.Depth != defaultBusBufferSize*4 {
+		t.Fatalf("AudioChunks depth = %d, want %d", stats.AudioChunks.Depth, defaultBusBufferSize*4)
+	}
+	wantWaitMS := defaultAudioPublishTimeout.Milliseconds()
+	if stats.AudioChunks.LastDropWaitMillis != wantWaitMS {
+		t.Fatalf("AudioChunks last wait ms = %d, want %d", stats.AudioChunks.LastDropWaitMillis, wantWaitMS)
+	}
+}
+
 func TestPublishVoiceControlSubscribe(t *testing.T) {
 	mb := NewMessageBus()
 	defer mb.Close()
@@ -728,6 +807,74 @@ func TestPublishInbound_FullBuffer(t *testing.T) {
 	}
 }
 
+// TestPublishInbound_FullBufferUsesBusBackpressureBudget exercises the generic
+// publish() backpressure path directly (with a short 20ms timeout) rather than
+// going through PublishInbound(). This avoids waiting for a long context timeout
+// and keeps the test fast. Context validation and public-API wiring are covered
+// by TestPublishInbound_FullBuffer and TestPublishInbound_ContextCancel.
+func TestPublishInbound_FullBufferUsesBusBackpressureBudget(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ch := make(chan InboundMessage, 1)
+	ch <- InboundMessage{Content: "fill"}
+
+	scope := runtimeevents.Scope{Channel: "test", ChatID: "chat-overflow"}
+	err := publish(context.Background(), mb, ch, InboundMessage{Content: "overflow"}, publishPolicy{
+		stream:  "inbound",
+		timeout: 20 * time.Millisecond,
+	}, &mb.inboundStats, scope)
+	if !errors.Is(err, ErrBusBackpressure) {
+		t.Fatalf("publish() error = %v, want %v", err, ErrBusBackpressure)
+	}
+
+	stats := mb.Stats()
+	if stats.Inbound.DroppedTotal != 1 {
+		t.Fatalf("Inbound dropped = %d, want 1", stats.Inbound.DroppedTotal)
+	}
+	if stats.Inbound.LastDropWaitMillis != 20 {
+		t.Fatalf("Inbound last wait ms = %d, want 20", stats.Inbound.LastDropWaitMillis)
+	}
+}
+
+func TestMessageBusHealthCheckIncludesQueueDepthAndDrops(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ok, msg := mb.HealthCheck()
+	if !ok {
+		t.Fatal("HealthCheck should remain ok for backpressure telemetry")
+	}
+	if msg == "" {
+		t.Fatal("HealthCheck message should not be empty")
+	}
+
+	for i := range cap(mb.audioChunks) {
+		if err := mb.PublishAudioChunk(context.Background(), AudioChunk{
+			Channel:  "discord",
+			ChatID:   "voice-room",
+			Sequence: uint64(i),
+			Data:     []byte("fill"),
+		}); err != nil {
+			t.Fatalf("fill audio buffer at %d: %v", i, err)
+		}
+	}
+	_ = mb.PublishAudioChunk(context.Background(), AudioChunk{
+		Channel:  "discord",
+		ChatID:   "voice-room",
+		Sequence: 999,
+		Data:     []byte("overflow"),
+	})
+
+	stats := mb.Stats()
+	if stats.AudioChunks.Depth != cap(mb.audioChunks) {
+		t.Fatalf("audio depth = %d, want %d", stats.AudioChunks.Depth, cap(mb.audioChunks))
+	}
+	if stats.AudioChunks.DroppedTotal != 1 {
+		t.Fatalf("audio dropped = %d, want 1", stats.AudioChunks.DroppedTotal)
+	}
+}
+
 func TestCloseIdempotent(t *testing.T) {
 	mb := NewMessageBus()
 

pkg/bus/events.go

@@ -1,6 +1,8 @@
 package bus
 
 import (
+	"time"
+
 	runtimeevents "github.com/sipeed/picoclaw/pkg/events"
 )
 
@@ -13,6 +15,15 @@ type busClosePayload struct {
 	Drained int `json:"drained,omitempty"`
 }
 
+type busMessageDroppedPayload struct {
+	Stream       string `json:"stream"`
+	Reason       string `json:"reason"`
+	WaitMS       int64  `json:"wait_ms"`
+	QueueDepth   int    `json:"queue_depth"`
+	QueueCap     int    `json:"queue_capacity"`
+	DroppedTotal uint64 `json:"dropped_total"`
+}
+
 func (mb *MessageBus) publishFailure(stream string, scope runtimeevents.Scope, err error) {
 	if mb == nil || err == nil {
 		return
@@ -38,6 +49,46 @@ func (mb *MessageBus) publishFailure(stream string, scope runtimeevents.Scope, e
 	})
 }
 
+func (mb *MessageBus) publishDrop(
+	stream string,
+	scope runtimeevents.Scope,
+	reason string,
+	wait time.Duration,
+	queueDepth, queueCap int,
+	droppedTotal uint64,
+) {
+	if mb == nil {
+		return
+	}
+	publisher, ok := mb.eventPublisher.Load().(EventPublisher)
+	if !ok || publisher == nil {
+		return
+	}
+
+	publisher.PublishNonBlocking(runtimeevents.Event{
+		Kind:     runtimeevents.KindBusMessageDropped,
+		Source:   runtimeevents.Source{Component: "bus", Name: stream},
+		Scope:    scope,
+		Severity: runtimeevents.SeverityWarn,
+		Payload: busMessageDroppedPayload{
+			Stream:       stream,
+			Reason:       reason,
+			WaitMS:       wait.Milliseconds(),
+			QueueDepth:   queueDepth,
+			QueueCap:     queueCap,
+			DroppedTotal: droppedTotal,
+		},
+		Attrs: map[string]any{
+			"stream":         stream,
+			"reason":         reason,
+			"wait_ms":        wait.Milliseconds(),
+			"queue_depth":    queueDepth,
+			"queue_capacity": queueCap,
+			"dropped_total":  droppedTotal,
+		},
+	})
+}
+
 func (mb *MessageBus) publishCloseEvent(kind runtimeevents.Kind, drained int) {
 	if mb == nil {
 		return

pkg/bus/types.go

@@ -64,10 +64,12 @@ type OutboundScope struct {
 // ContextUsage describes how much of the model's context window the current
 // session consumes, and how far it is from triggering compression.
 type ContextUsage struct {
-	UsedTokens       int `json:"used_tokens"`
-	TotalTokens      int `json:"total_tokens"`       // model context window
-	CompressAtTokens int `json:"compress_at_tokens"` // threshold that triggers compression
-	UsedPercent      int `json:"used_percent"`       // 0-100
+	UsedTokens        int `json:"used_tokens"`
+	TotalTokens       int `json:"total_tokens"`        // model context window
+	HistoryTokens     int `json:"history_tokens"`      // history-message tokens only (what maybeSummarize checks)
+	CompressAtTokens  int `json:"compress_at_tokens"`  // hard budget compression threshold (contextWindow - maxTokens)
+	SummarizeAtTokens int `json:"summarize_at_tokens"` // soft summarization trigger (vs history tokens)
+	UsedPercent       int `json:"used_percent"`        // 0-100, relative to compressAt
 }
 
 type OutboundMessage struct {

pkg/channels/discord/discord.go

@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"net/url"
 	"os"
+	"path/filepath"
 	"regexp"
 	"strings"
 	"sync"
@@ -605,10 +606,11 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 	scope := channels.BuildMediaScope("discord", m.ChannelID, m.ID)
 
 	// Helper to register a local file with the media store
-	storeMedia := func(localPath, filename string) string {
+	storeMedia := func(localPath string, attachment *discordgo.MessageAttachment) string {
 		if store := c.GetMediaStore(); store != nil {
 			ref, err := store.Store(localPath, media.MediaMeta{
-				Filename:      filename,
+				Filename:      attachment.Filename,
+				ContentType:   attachment.ContentType,
 				Source:        "discord",
 				CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
 			}, scope)
@@ -620,22 +622,16 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 	}
 
 	for _, attachment := range m.Attachments {
-		isAudio := utils.IsAudioFile(attachment.Filename, attachment.ContentType)
-
-		if isAudio {
-			localPath := c.downloadAttachment(attachment.URL, attachment.Filename)
-			if localPath != "" {
-				mediaPaths = append(mediaPaths, storeMedia(localPath, attachment.Filename))
-				content = appendContent(content, fmt.Sprintf("[audio: %s]", attachment.Filename))
-			} else {
-				logger.WarnCF("discord", "Failed to download audio attachment", map[string]any{
-					"url":      attachment.URL,
-					"filename": attachment.Filename,
-				})
-				mediaPaths = append(mediaPaths, attachment.URL)
-				content = appendContent(content, fmt.Sprintf("[attachment: %s]", attachment.URL))
-			}
+		localPath := c.downloadAttachment(attachment.URL, attachment.Filename)
+		if localPath != "" {
+			mediaPaths = append(mediaPaths, storeMedia(localPath, attachment))
+			tag := attachmentMediaTag(attachment.Filename, attachment.ContentType)
+			content = appendContent(content, fmt.Sprintf("[%s: %s]", tag, attachment.Filename))
 		} else {
+			logger.WarnCF("discord", "Failed to download attachment", map[string]any{
+				"url":      attachment.URL,
+				"filename": attachment.Filename,
+			})
 			mediaPaths = append(mediaPaths, attachment.URL)
 			content = appendContent(content, fmt.Sprintf("[attachment: %s]", attachment.URL))
 		}
@@ -748,6 +744,30 @@ func (c *DiscordChannel) downloadAttachment(url, filename string) string {
 	})
 }
 
+func attachmentMediaTag(filename, contentType string) string {
+	ct := strings.ToLower(contentType)
+	switch {
+	case strings.HasPrefix(ct, "image/"):
+		return "image"
+	case strings.HasPrefix(ct, "audio/"), ct == "application/ogg", ct == "application/x-ogg":
+		return "audio"
+	case strings.HasPrefix(ct, "video/"):
+		return "video"
+	}
+
+	ext := strings.ToLower(filepath.Ext(filename))
+	switch ext {
+	case ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp":
+		return "image"
+	case ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma":
+		return "audio"
+	case ".mp4", ".avi", ".mov", ".webm", ".mkv":
+		return "video"
+	}
+
+	return "file"
+}
+
 func applyDiscordProxy(session *discordgo.Session, proxyAddr string) error {
 	var proxyFunc func(*http.Request) (*url.URL, error)
 	if proxyAddr != "" {

pkg/channels/discord/voice.go

@@ -298,9 +298,11 @@ func (c *DiscordChannel) receiveVoice(vc *discordgo.VoiceConnection, guildID str
 				Data:       p.Opus,
 			}
 
-			ctx, cancel := context.WithTimeout(c.ctx, 100*time.Millisecond)
-			err := c.bus.PublishAudioChunk(ctx, chunk)
-			cancel()
+			// Pass the parent context directly; the bus applies its own
+			// audio drop budget internally.
+			// A 100ms caller-level timeout would fire before the bus's
+			// backpressure handling, masking drop counters and events.
+			err := c.bus.PublishAudioChunk(c.ctx, chunk)
 			if err != nil {
 				logger.ErrorCF("discord", "Failed to publish audio chunk", map[string]any{
 					"guild":     guildID,

pkg/channels/errutil.go

@@ -11,11 +11,11 @@ import (
 func ClassifySendError(statusCode int, rawErr error) error {
 	switch {
 	case statusCode == http.StatusTooManyRequests:
-		return fmt.Errorf("%w: %v", ErrRateLimit, rawErr)
+		return fmt.Errorf("%w: %w", ErrRateLimit, rawErr)
 	case statusCode >= 500:
-		return fmt.Errorf("%w: %v", ErrTemporary, rawErr)
+		return fmt.Errorf("%w: %w", ErrTemporary, rawErr)
 	case statusCode >= 400:
-		return fmt.Errorf("%w: %v", ErrSendFailed, rawErr)
+		return fmt.Errorf("%w: %w", ErrSendFailed, rawErr)
 	default:
 		return rawErr
 	}
@@ -26,5 +26,5 @@ func ClassifyNetError(err error) error {
 	if err == nil {
 		return nil
 	}
-	return fmt.Errorf("%w: %v", ErrTemporary, err)
+	return fmt.Errorf("%w: %w", ErrTemporary, err)
 }

pkg/channels/feishu/feishu_64.go

@@ -52,6 +52,8 @@ type FeishuChannel struct {
 
 	progress        *channels.ToolFeedbackAnimator
 	deleteMessageFn func(context.Context, string, string) error
+	sendMediaPartFn func(context.Context, string, bus.MediaPart, media.MediaStore) error
+	sendTextFn      func(context.Context, string, string) (string, error)
 }
 
 type cachedMessage struct {
@@ -78,6 +80,8 @@ func NewFeishuChannel(bc *config.Channel, cfg *config.FeishuSettings, bus *bus.M
 		client:      lark.NewClient(cfg.AppID, cfg.AppSecret.String(), opts...),
 	}
 	ch.deleteMessageFn = ch.deleteMessageAPI
+	ch.sendMediaPartFn = ch.sendMediaPart
+	ch.sendTextFn = ch.sendText
 	ch.progress = channels.NewToolFeedbackAnimator(ch.EditMessage)
 	ch.SetOwner(ch)
 	return ch, nil
@@ -304,7 +308,7 @@ func (c *FeishuChannel) SendPlaceholder(ctx context.Context, chatID string) (str
 	}
 
 	req := larkim.NewCreateMessageReqBuilder().
-		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		ReceiveIdType(larkim.CreateMessageV1ReceiveIDTypeChatId).
 		Body(larkim.NewCreateMessageReqBodyBuilder().
 			ReceiveId(chatID).
 			MsgType(larkim.MsgTypeInteractive).
@@ -497,8 +501,16 @@ func (c *FeishuChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMess
 		return nil, fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
 	}
 
+	caption := firstMediaCaption(msg.Parts)
+	sentAny := false
 	for _, part := range msg.Parts {
-		if err := c.sendMediaPart(ctx, msg.ChatID, part, store); err != nil {
+		if err := c.sendMediaPartFn(ctx, msg.ChatID, part, store); err != nil {
+			return nil, err
+		}
+		sentAny = true
+	}
+	if sentAny && caption != "" {
+		if _, err := c.sendTextFn(ctx, msg.ChatID, caption); err != nil {
 			return nil, err
 		}
 	}
@@ -557,6 +569,15 @@ func (c *FeishuChannel) sendMediaPart(
 	return nil
 }
 
+func firstMediaCaption(parts []bus.MediaPart) string {
+	for _, part := range parts {
+		if caption := strings.TrimSpace(part.Caption); caption != "" {
+			return caption
+		}
+	}
+	return ""
+}
+
 // --- Inbound message handling ---
 
 func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim.P2MessageReceiveV1) error {
@@ -725,8 +746,8 @@ func (c *FeishuChannel) isBotMentioned(message *larkim.EventMessage) bool {
 		return false
 	}
 
-	knownID, _ := c.botOpenID.Load().(string)
-	if knownID == "" {
+	knownID, ok := c.botOpenID.Load().(string)
+	if !ok || knownID == "" {
 		logger.DebugCF("feishu", "Bot open_id unknown, cannot detect @mention", nil)
 		return false
 	}
@@ -992,7 +1013,13 @@ func (c *FeishuChannel) storeResourceFile(
 		})
 		return ""
 	}
-	out.Close()
+	if closeErr := out.Close(); closeErr != nil {
+		logger.ErrorCF("feishu", "Failed to close downloaded resource file", map[string]any{
+			"error": closeErr.Error(),
+		})
+		os.Remove(localPath)
+		return ""
+	}
 
 	ref, err := store.Store(localPath, media.MediaMeta{
 		Filename:      filename,
@@ -1047,7 +1074,7 @@ func appendMediaTags(content, messageType string, mediaRefs []string) string {
 // sendCard sends an interactive card message to a chat.
 func (c *FeishuChannel) sendCard(ctx context.Context, chatID, cardContent string) (string, error) {
 	req := larkim.NewCreateMessageReqBuilder().
-		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		ReceiveIdType(larkim.CreateMessageV1ReceiveIDTypeChatId).
 		Body(larkim.NewCreateMessageReqBodyBuilder().
 			ReceiveId(chatID).
 			MsgType(larkim.MsgTypeInteractive).
@@ -1080,7 +1107,7 @@ func (c *FeishuChannel) sendText(ctx context.Context, chatID, text string) (stri
 	content, _ := json.Marshal(map[string]string{"text": text})
 
 	req := larkim.NewCreateMessageReqBuilder().
-		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		ReceiveIdType(larkim.CreateMessageV1ReceiveIDTypeChatId).
 		Body(larkim.NewCreateMessageReqBodyBuilder().
 			ReceiveId(chatID).
 			MsgType(larkim.MsgTypeText).
@@ -1134,7 +1161,7 @@ func (c *FeishuChannel) sendImage(ctx context.Context, chatID string, file *os.F
 	// Send image message
 	content, _ := json.Marshal(map[string]string{"image_key": imageKey})
 	req := larkim.NewCreateMessageReqBuilder().
-		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		ReceiveIdType(larkim.CreateMessageV1ReceiveIDTypeChatId).
 		Body(larkim.NewCreateMessageReqBodyBuilder().
 			ReceiveId(chatID).
 			MsgType(larkim.MsgTypeImage).
@@ -1190,7 +1217,7 @@ func (c *FeishuChannel) sendFile(ctx context.Context, chatID string, file *os.Fi
 	// Send file message
 	content, _ := json.Marshal(map[string]string{"file_key": fileKey})
 	req := larkim.NewCreateMessageReqBuilder().
-		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		ReceiveIdType(larkim.CreateMessageV1ReceiveIDTypeChatId).
 		Body(larkim.NewCreateMessageReqBodyBuilder().
 			ReceiveId(chatID).
 			MsgType(larkim.MsgTypeFile).

pkg/channels/feishu/feishu_64_test.go

@@ -9,7 +9,9 @@ import (
 
 	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
 
+	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/media"
 )
 
 func TestExtractContent(t *testing.T) {
@@ -319,6 +321,43 @@ func TestFinalizeTrackedToolFeedbackMessage_ClearAfterSuccessfulEdit(t *testing.
 	}
 }
 
+func TestSendMedia_SendsCaptionFallbackAfterMedia(t *testing.T) {
+	ch := &FeishuChannel{
+		BaseChannel: channels.NewBaseChannel("feishu", nil, nil, nil),
+		progress:    channels.NewToolFeedbackAnimator(nil),
+	}
+	ch.SetRunning(true)
+	ch.SetMediaStore(media.NewFileMediaStore())
+
+	var mediaOrder []string
+	var textCalls []string
+	ch.sendMediaPartFn = func(ctx context.Context, chatID string, part bus.MediaPart, store media.MediaStore) error {
+		mediaOrder = append(mediaOrder, part.Type)
+		return nil
+	}
+	ch.sendTextFn = func(ctx context.Context, chatID, text string) (string, error) {
+		textCalls = append(textCalls, chatID+"|"+text)
+		return "msg-1", nil
+	}
+
+	_, err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "oc_123",
+		Parts: []bus.MediaPart{
+			{Type: "image", Caption: "shared caption"},
+			{Type: "file"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+	if len(mediaOrder) != 2 {
+		t.Fatalf("media sends = %v, want 2 sends", mediaOrder)
+	}
+	if len(textCalls) != 1 || textCalls[0] != "oc_123|shared caption" {
+		t.Fatalf("textCalls = %v, want [oc_123|shared caption]", textCalls)
+	}
+}
+
 func TestFinalizeTrackedToolFeedbackMessage_StopsTrackingBeforeEdit(t *testing.T) {
 	ch := &FeishuChannel{
 		progress: channels.NewToolFeedbackAnimator(nil),

pkg/channels/manager.go

@@ -169,6 +169,13 @@ func outboundMessageIsToolFeedback(msg bus.OutboundMessage) bool {
 	return strings.EqualFold(strings.TrimSpace(msg.Context.Raw["message_kind"]), "tool_feedback")
 }
 
+func outboundMessageIsToolCalls(msg bus.OutboundMessage) bool {
+	if len(msg.Context.Raw) == 0 {
+		return false
+	}
+	return strings.EqualFold(strings.TrimSpace(msg.Context.Raw["message_kind"]), "tool_calls")
+}
+
 func outboundMessageHasAuxiliaryKind(msg bus.OutboundMessage) bool {
 	if len(msg.Context.Raw) == 0 {
 		return false
@@ -379,6 +386,7 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess
 	}
 
 	isToolFeedback := outboundMessageIsToolFeedback(msg)
+	isToolCalls := outboundMessageIsToolCalls(msg)
 	isAuxiliaryMessage := outboundMessageHasAuxiliaryKind(msg)
 	isFinalMessage := outboundMessageIsFinal(msg)
 	separateToolFeedbackMessages := m.toolFeedbackSeparateMessagesEnabled()
@@ -388,7 +396,9 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess
 	// finalization bypasses the worker queue, so older queued feedback/thoughts
 	// can arrive before the normal final outbound message that cleans up the
 	// marker and placeholder.
-	if isAuxiliaryMessage {
+	// Note: tool_calls messages must NOT be dropped as they represent new tool
+	// invocations for the current turn that must be delivered to the UI.
+	if isAuxiliaryMessage && !isToolCalls {
 		if _, loaded := m.streamActive.Load(streamKey); loaded {
 			return nil, true
 		}

pkg/channels/manager_channel.go

@@ -4,6 +4,7 @@ import (
 	"crypto/md5"
 	"encoding/hex"
 	"encoding/json"
+	"log"
 
 	"github.com/sipeed/picoclaw/pkg/config"
 )
@@ -11,17 +12,27 @@ import (
 func toChannelHashes(cfg *config.Config) map[string]string {
 	result := make(map[string]string)
 	ch := cfg.Channels
-	// should not be error
-	marshal, _ := json.Marshal(ch)
+	marshal, err := json.Marshal(ch)
+	if err != nil {
+		log.Printf("[manager_channel] failed to marshal channels config: %v", err)
+		return result
+	}
 	var channelConfig map[string]map[string]any
-	_ = json.Unmarshal(marshal, &channelConfig)
+	if err := json.Unmarshal(marshal, &channelConfig); err != nil {
+		log.Printf("[manager_channel] failed to unmarshal channels config: %v", err)
+		return result
+	}
 
 	for key, value := range channelConfig {
-		if !value["enabled"].(bool) {
+		if enabled, ok := value["enabled"].(bool); !ok || !enabled {
 			continue
 		}
 		hiddenValues(key, value, ch.Get(key))
-		valueBytes, _ := json.Marshal(value)
+		valueBytes, err := json.Marshal(value)
+		if err != nil {
+			log.Printf("[manager_channel] failed to marshal channel %s config: %v", key, err)
+			continue
+		}
 		hash := md5.Sum(valueBytes)
 		result[key] = hex.EncodeToString(hash[:])
 	}
@@ -94,7 +105,15 @@ func hiddenValues(key string, value map[string]any, ch *config.Channel) {
 		vv := value["webhooks"]
 		webhooks := make(map[string]string)
 		if vv != nil {
-			webhooks = vv.(map[string]string)
+			if m, ok := vv.(map[string]string); ok {
+				webhooks = m
+			} else if m, ok := vv.(map[string]any); ok {
+				for k, w := range m {
+					if s, ok := w.(string); ok {
+						webhooks[k] = s
+					}
+				}
+			}
 		}
 		if settings, ok := v.(*config.TeamsWebhookSettings); ok {
 			for name, target := range settings.Webhooks {

pkg/channels/manager_channel_test.go

@@ -151,3 +151,57 @@ func TestToChannelHashes_RealWorldChannel(t *testing.T) {
 	assert.Equal(t, 1, len(h))
 	assert.Contains(t, h, "telegram")
 }
+
+func TestToChannelHashes_MissingEnabledKey(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Channels["test"] = &config.Channel{
+		Settings: config.RawNode(`{"key":"value"}`),
+	}
+
+	// Should not panic — the ok check safely handles the missing/false case
+	assert.NotPanics(t, func() {
+		_ = toChannelHashes(cfg)
+	})
+	h := toChannelHashes(cfg)
+	assert.Equal(t, 0, len(h), "channel with Enabled=false (default) skipped")
+}
+
+func TestToChannelHashes_EnabledNotBool(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Channels["test"] = &config.Channel{
+		Enabled:  false,
+		Settings: config.RawNode(`{"enabled":"yes","boolField":true}`),
+	}
+
+	// Should not panic — string "enabled" won't match bool assertion, ok=false
+	assert.NotPanics(t, func() {
+		_ = toChannelHashes(cfg)
+	})
+	h := toChannelHashes(cfg)
+	assert.Equal(t, 0, len(h), "string enabled not treated as true")
+}
+
+func TestToChannelHashes_TeamsWebhookWithWebhooks(t *testing.T) {
+	cfg := config.DefaultConfig()
+	// teams_webhook with configured webhooks — this is the real-world
+	// scenario where the map type from JSON unmarshal (map[string]any)
+	// would cause a panic on the old unchecked vv.(map[string]string)
+	settings, _ := json.Marshal(map[string]any{
+		"enabled": true,
+		"webhooks": map[string]any{
+			"hook1": "https://example.com/webhook",
+		},
+	})
+	cfg.Channels["teams_webhook"] = &config.Channel{
+		Enabled:  true,
+		Type:     config.ChannelTeamsWebHook,
+		Settings: config.RawNode(settings),
+	}
+
+	assert.NotPanics(t, func() {
+		_ = toChannelHashes(cfg)
+	})
+	h := toChannelHashes(cfg)
+	assert.Equal(t, 1, len(h))
+	assert.Contains(t, h, "teams_webhook")
+}

pkg/channels/onebot/onebot.go

@@ -995,7 +995,6 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 
 	senderID := strconv.FormatInt(userID, 10)
 	var chatID string
-	var contextChatID string
 	var contextChatType string
 
 	metadata := map[string]string{}
@@ -1007,13 +1006,11 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 	switch raw.MessageType {
 	case "private":
 		chatID = "private:" + senderID
-		contextChatID = senderID
 		contextChatType = "direct"
 
 	case "group":
 		groupIDStr := strconv.FormatInt(groupID, 10)
 		chatID = "group:" + groupIDStr
-		contextChatID = groupIDStr
 		contextChatType = "group"
 		metadata["group_id"] = groupIDStr
 
@@ -1080,7 +1077,7 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 
 	inboundCtx := bus.InboundContext{
 		Channel:          c.Name(),
-		ChatID:           contextChatID,
+		ChatID:           chatID,
 		ChatType:         contextChatType,
 		SenderID:         senderID,
 		MessageID:        messageID,

pkg/channels/pico/pico.go

@@ -1394,10 +1394,12 @@ func setContextUsagePayload(payload map[string]any, u *bus.ContextUsage) {
 		return
 	}
 	payload["context_usage"] = map[string]any{
-		"used_tokens":        u.UsedTokens,
-		"total_tokens":       u.TotalTokens,
-		"compress_at_tokens": u.CompressAtTokens,
-		"used_percent":       u.UsedPercent,
+		"used_tokens":         u.UsedTokens,
+		"total_tokens":        u.TotalTokens,
+		"history_tokens":      u.HistoryTokens,
+		"compress_at_tokens":  u.CompressAtTokens,
+		"summarize_at_tokens": u.SummarizeAtTokens,
+		"used_percent":        u.UsedPercent,
 	}
 }
 

pkg/channels/pico/pico_test.go

@@ -602,10 +602,12 @@ func TestBeginStream_FinalizeIncludesContextUsage(t *testing.T) {
 		t.Fatal("streamer should support FinalizeWithContext")
 	}
 	if err := contextStreamer.FinalizeWithContext(context.Background(), "final", &bus.ContextUsage{
-		UsedTokens:       10,
-		TotalTokens:      100,
-		CompressAtTokens: 80,
-		UsedPercent:      10,
+		UsedTokens:        10,
+		TotalTokens:       100,
+		HistoryTokens:     5,
+		CompressAtTokens:  80,
+		SummarizeAtTokens: 60,
+		UsedPercent:       10,
 	}); err != nil {
 		t.Fatalf("FinalizeWithContext() error = %v", err)
 	}
@@ -627,6 +629,12 @@ func TestBeginStream_FinalizeIncludesContextUsage(t *testing.T) {
 	if got := rawUsage["used_tokens"]; got != float64(10) {
 		t.Fatalf("used_tokens = %#v, want 10", got)
 	}
+	if got := rawUsage["history_tokens"]; got != float64(5) {
+		t.Fatalf("history_tokens = %#v, want 5", got)
+	}
+	if got := rawUsage["summarize_at_tokens"]; got != float64(60) {
+		t.Fatalf("summarize_at_tokens = %#v, want 60", got)
+	}
 }
 
 func TestCreateAndAddConnection_RespectsMaxConnectionsConcurrently(t *testing.T) {
@@ -835,6 +843,75 @@ func TestSendMedia_DismissesTrackedToolFeedbackMessage(t *testing.T) {
 	}
 }
 
+func TestSendMedia_IncludesCaptionAndAttachmentsInSinglePayload(t *testing.T) {
+	ch := newTestPicoChannel(t)
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	if err := ch.Start(context.Background()); err != nil {
+		t.Fatalf("Start() error = %v", err)
+	}
+	defer ch.Stop(context.Background())
+
+	clientConn, received, cleanup := newTestPicoWebSocket(t)
+	defer cleanup()
+	ch.addConnForTest(&picoConn{id: "conn-1", conn: clientConn, sessionID: "sess-1"})
+
+	localPath := filepath.Join(t.TempDir(), "photo.png")
+	if err := os.WriteFile(localPath, []byte("png-body"), 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	ref, err := store.Store(localPath, media.MediaMeta{
+		Filename:    "photo.png",
+		ContentType: "image/png",
+	}, "test-scope")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	_, err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "pico:sess-1",
+		Parts: []bus.MediaPart{{
+			Ref:         ref,
+			Type:        "image",
+			Filename:    "photo.png",
+			ContentType: "image/png",
+			Caption:     "recipe translation",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	select {
+	case msg := <-received:
+		if msg.Type != TypeMessageCreate {
+			t.Fatalf("message type = %q, want %q", msg.Type, TypeMessageCreate)
+		}
+		payload := msg.Payload
+		if got := payload[PayloadKeyContent]; got != "recipe translation" {
+			t.Fatalf("content = %#v, want %q", got, "recipe translation")
+		}
+		rawAttachments, ok := payload["attachments"].([]any)
+		if !ok || len(rawAttachments) != 1 {
+			t.Fatalf("attachments = %#v, want 1 attachment", payload["attachments"])
+		}
+		attachment, ok := rawAttachments[0].(map[string]any)
+		if !ok {
+			t.Fatalf("attachment = %#v, want map", rawAttachments[0])
+		}
+		if got := attachment["type"]; got != "image" {
+			t.Fatalf("attachment type = %#v, want image", got)
+		}
+		if got := attachment["filename"]; got != "photo.png" {
+			t.Fatalf("attachment filename = %#v, want photo.png", got)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("expected media payload to be delivered")
+	}
+}
+
 func TestPicoDownloadURLForRef(t *testing.T) {
 	got, err := picoDownloadURLForRef("media://attachment-1")
 	if err != nil {

pkg/channels/slack/slack.go

@@ -29,6 +29,8 @@ type SlackChannel struct {
 	ctx          context.Context
 	cancel       context.CancelFunc
 	pendingAcks  sync.Map
+	uploadFileFn func(context.Context, slack.UploadFileParameters) error
+	postTextFn   func(context.Context, string, string, string) error
 }
 
 type slackMessageRef struct {
@@ -63,6 +65,18 @@ func NewSlackChannel(
 		config:       cfg,
 		api:          api,
 		socketClient: socketClient,
+		uploadFileFn: func(ctx context.Context, params slack.UploadFileParameters) error {
+			_, err := api.UploadFileContext(ctx, params)
+			return err
+		},
+		postTextFn: func(ctx context.Context, channelID, threadTS, text string) error {
+			opts := []slack.MsgOption{slack.MsgOptionText(text, false)}
+			if threadTS != "" {
+				opts = append(opts, slack.MsgOptionTS(threadTS))
+			}
+			_, _, err := api.PostMessageContext(ctx, channelID, opts...)
+			return err
+		},
 	}, nil
 }
 
@@ -140,7 +154,10 @@ func (c *SlackChannel) Send(ctx context.Context, msg bus.OutboundMessage) ([]str
 	}
 
 	if ref, ok := c.pendingAcks.LoadAndDelete(deliveryChatID); ok {
-		msgRef := ref.(slackMessageRef)
+		msgRef, ok := ref.(slackMessageRef)
+		if !ok {
+			return []string{ts}, nil
+		}
 		c.api.AddReaction("white_check_mark", slack.ItemRef{
 			Channel:   msgRef.ChannelID,
 			Timestamp: msgRef.Timestamp,
@@ -171,6 +188,8 @@ func (c *SlackChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessa
 		return nil, fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
 	}
 
+	caption := slackFirstMediaCaption(msg.Parts)
+	sentAny := false
 	for _, part := range msg.Parts {
 		localPath, err := store.Resolve(part.Ref)
 		if err != nil {
@@ -191,7 +210,7 @@ func (c *SlackChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessa
 			title = filename
 		}
 
-		_, err = c.api.UploadFileContext(ctx, slack.UploadFileParameters{
+		err = c.uploadFileFn(ctx, slack.UploadFileParameters{
 			Channel:         channelID,
 			ThreadTimestamp: threadTS,
 			File:            localPath,
@@ -205,6 +224,13 @@ func (c *SlackChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessa
 			})
 			return nil, fmt.Errorf("slack send media: %w", channels.ErrTemporary)
 		}
+		sentAny = true
+	}
+
+	if sentAny && caption != "" {
+		if err := c.postTextFn(ctx, channelID, threadTS, caption); err != nil {
+			return nil, fmt.Errorf("slack send media caption fallback: %w", channels.ErrTemporary)
+		}
 	}
 
 	// UploadFile does not expose the posted message timestamp in its
@@ -212,6 +238,15 @@ func (c *SlackChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessa
 	return nil, nil
 }
 
+func slackFirstMediaCaption(parts []bus.MediaPart) string {
+	for _, part := range parts {
+		if caption := strings.TrimSpace(part.Caption); caption != "" {
+			return caption
+		}
+	}
+	return ""
+}
+
 // ReactToMessage implements channels.ReactionCapable.
 // It adds an "eyes" (👀) reaction to the inbound message and returns an undo function
 // that removes the reaction.

pkg/channels/slack/slack_test.go

@@ -1,10 +1,17 @@
 package slack
 
 import (
+	"context"
+	"os"
+	"path/filepath"
 	"testing"
 
+	slacksdk "github.com/slack-go/slack"
+
 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
 )
 
 func TestParseSlackChatID(t *testing.T) {
@@ -184,3 +191,74 @@ func TestSlackChannelIsAllowed(t *testing.T) {
 		}
 	})
 }
+
+func TestSendMedia_SendsCaptionFallbackAfterUploads(t *testing.T) {
+	ch := &SlackChannel{
+		BaseChannel: channels.NewBaseChannel("slack", nil, nil, nil),
+	}
+	ch.SetRunning(true)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	tmpDir := t.TempDir()
+	localPath := filepath.Join(tmpDir, "report.txt")
+	if err := os.WriteFile(localPath, []byte("attachment body"), 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	ref, err := store.Store(localPath, media.MediaMeta{
+		Filename:    "report.txt",
+		ContentType: "text/plain",
+	}, "test-scope")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	var uploaded []slackUploadRecord
+	var posted []string
+	ch.uploadFileFn = func(ctx context.Context, params slacksdk.UploadFileParameters) error {
+		uploaded = append(uploaded, slackUploadRecord{
+			Channel: params.Channel,
+			Thread:  params.ThreadTimestamp,
+			File:    params.File,
+			Name:    params.Filename,
+			Title:   params.Title,
+		})
+		return nil
+	}
+	ch.postTextFn = func(ctx context.Context, channelID, threadTS, text string) error {
+		posted = append(posted, channelID+"|"+threadTS+"|"+text)
+		return nil
+	}
+
+	_, err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "C123456/1234567890.123456",
+		Parts: []bus.MediaPart{{
+			Ref:         ref,
+			Type:        "file",
+			Filename:    "report.txt",
+			ContentType: "text/plain",
+			Caption:     "shared caption",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+	if len(uploaded) != 1 {
+		t.Fatalf("uploads = %v, want 1 upload", uploaded)
+	}
+	if uploaded[0].Title != "shared caption" {
+		t.Fatalf("upload title = %q, want shared caption", uploaded[0].Title)
+	}
+	if len(posted) != 1 || posted[0] != "C123456|1234567890.123456|shared caption" {
+		t.Fatalf("posted = %v, want fallback text in same thread", posted)
+	}
+}
+
+type slackUploadRecord struct {
+	Channel string
+	Thread  string
+	File    string
+	Name    string
+	Title   string
+}

pkg/channels/telegram/telegram.go

@@ -44,7 +44,10 @@ var (
 	reInlineCode = regexp.MustCompile("`([^`]+)`")
 )
 
-const defaultMediaGroupDelay = 500 * time.Millisecond
+const (
+	defaultMediaGroupDelay = 500 * time.Millisecond
+	telegramCaptionLimit   = 1024
+)
 
 type TelegramChannel struct {
 	*channels.BaseChannel
@@ -639,6 +642,34 @@ func (c *TelegramChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMe
 	}
 
 	var messageIDs []string
+	leadingCaption := telegramLeadingCaption(msg.Parts)
+	if len([]rune(leadingCaption)) > telegramCaptionLimit {
+		leadingIDs, leadingErr := c.sendCaptionText(ctx, chatID, threadID, leadingCaption)
+		if leadingErr != nil {
+			return nil, leadingErr
+		}
+		messageIDs = append(messageIDs, leadingIDs...)
+		msg = telegramClearMediaCaptions(msg)
+	}
+
+	if len(msg.Parts) > 1 && telegramCanSendMediaGroup(msg.Parts) {
+		groupIDs, err := c.sendImageMediaGroups(ctx, chatID, threadID, store, msg.Parts)
+		if err != nil {
+			logger.ErrorCF("telegram", "Failed to send media group", map[string]any{
+				"count": len(msg.Parts),
+				"error": err.Error(),
+			})
+			return nil, fmt.Errorf("telegram send media group: %w", channels.ErrTemporary)
+		}
+		if len(groupIDs) > 0 {
+			messageIDs = append(messageIDs, groupIDs...)
+			if hasTrackedMsg {
+				c.dismissTrackedToolFeedbackMessage(ctx, trackedChatID, trackedMsgID)
+			}
+			return messageIDs, nil
+		}
+	}
+
 	for _, part := range msg.Parts {
 		localPath, err := store.Resolve(part.Ref)
 		if err != nil {
@@ -742,6 +773,154 @@ func (c *TelegramChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMe
 	return messageIDs, nil
 }
 
+func telegramCanSendMediaGroup(parts []bus.MediaPart) bool {
+	if len(parts) < 2 {
+		return false
+	}
+	for _, part := range parts {
+		if part.Type != "image" {
+			return false
+		}
+	}
+	return true
+}
+
+func (c *TelegramChannel) sendImageMediaGroups(
+	ctx context.Context,
+	chatID int64,
+	threadID int,
+	store media.MediaStore,
+	parts []bus.MediaPart,
+) ([]string, error) {
+	const maxGroupSize = 10
+
+	messageIDs := make([]string, 0, len(parts))
+	for start := 0; start < len(parts); start += maxGroupSize {
+		end := start + maxGroupSize
+		if end > len(parts) {
+			end = len(parts)
+		}
+		groupIDs, err := c.sendSingleImageMediaGroup(ctx, chatID, threadID, store, parts[start:end])
+		if err != nil {
+			return nil, err
+		}
+		messageIDs = append(messageIDs, groupIDs...)
+	}
+	return messageIDs, nil
+}
+
+func (c *TelegramChannel) sendSingleImageMediaGroup(
+	ctx context.Context,
+	chatID int64,
+	threadID int,
+	store media.MediaStore,
+	parts []bus.MediaPart,
+) ([]string, error) {
+	opened := make([]*os.File, 0, len(parts))
+	defer func() {
+		for _, file := range opened {
+			file.Close()
+		}
+	}()
+
+	inputMedia := make([]telego.InputMedia, 0, len(parts))
+	for i, part := range parts {
+		localPath, err := store.Resolve(part.Ref)
+		if err != nil {
+			logger.ErrorCF("telegram", "Failed to resolve media ref for media group", map[string]any{
+				"ref":   part.Ref,
+				"error": err.Error(),
+			})
+			return nil, err
+		}
+
+		file, err := os.Open(localPath)
+		if err != nil {
+			logger.ErrorCF("telegram", "Failed to open media file for media group", map[string]any{
+				"path":  localPath,
+				"error": err.Error(),
+			})
+			return nil, err
+		}
+		opened = append(opened, file)
+
+		mediaItem := &telego.InputMediaPhoto{
+			Type:  telego.MediaTypePhoto,
+			Media: telego.InputFile{File: file},
+		}
+		if i == 0 {
+			mediaItem.Caption = part.Caption
+		}
+		inputMedia = append(inputMedia, mediaItem)
+	}
+
+	results, err := c.bot.SendMediaGroup(ctx, &telego.SendMediaGroupParams{
+		ChatID:          tu.ID(chatID),
+		MessageThreadID: threadID,
+		Media:           inputMedia,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	messageIDs := make([]string, 0, len(results))
+	for _, result := range results {
+		messageIDs = append(messageIDs, strconv.Itoa(result.MessageID))
+	}
+	return messageIDs, nil
+}
+
+func (c *TelegramChannel) sendCaptionText(
+	ctx context.Context,
+	chatID int64,
+	threadID int,
+	text string,
+) ([]string, error) {
+	text = strings.TrimSpace(text)
+	if text == "" {
+		return nil, nil
+	}
+	chunks := channels.SplitMessage(text, c.MaxMessageLength())
+	messageIDs := make([]string, 0, len(chunks))
+	for _, chunk := range chunks {
+		chunk = strings.TrimSpace(chunk)
+		if chunk == "" {
+			continue
+		}
+		msgID, err := c.sendChunk(ctx, sendChunkParams{
+			chatID:        chatID,
+			threadID:      threadID,
+			content:       chunk,
+			mdFallback:    chunk,
+			useMarkdownV2: false,
+		})
+		if err != nil {
+			return nil, err
+		}
+		messageIDs = append(messageIDs, msgID)
+	}
+	return messageIDs, nil
+}
+
+func telegramLeadingCaption(parts []bus.MediaPart) string {
+	if len(parts) == 0 {
+		return ""
+	}
+	return strings.TrimSpace(parts[0].Caption)
+}
+
+func telegramClearMediaCaptions(msg bus.OutboundMediaMessage) bus.OutboundMediaMessage {
+	if len(msg.Parts) == 0 {
+		return msg
+	}
+	cloned := msg
+	cloned.Parts = append([]bus.MediaPart(nil), msg.Parts...)
+	for i := range cloned.Parts {
+		cloned.Parts[i].Caption = ""
+	}
+	return cloned
+}
+
 func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Message) error {
 	if message != nil && strings.TrimSpace(message.MediaGroupID) != "" {
 		return c.bufferMediaGroupMessage(ctx, message)
@@ -1048,6 +1227,13 @@ func (c *TelegramChannel) collectTelegramMessageParts(
 	if caption := strings.TrimSpace(msg.Caption); caption != "" {
 		parts.content = append(parts.content, caption)
 	}
+	if msg.Location != nil {
+		parts.content = append(parts.content, fmt.Sprintf(
+			"[User location: lat=%.6f, lng=%.6f]",
+			msg.Location.Latitude,
+			msg.Location.Longitude,
+		))
+	}
 	if len(msg.Photo) > 0 {
 		photo := msg.Photo[len(msg.Photo)-1]
 		photoPath := c.downloadPhoto(ctx, photo.FileID)

pkg/channels/telegram/telegram_test.go

@@ -110,6 +110,17 @@ func successResponseWithMessageID(t *testing.T, messageID int) *ta.Response {
 	return &ta.Response{Ok: true, Result: b}
 }
 
+func successMediaGroupResponse(t *testing.T, messageIDs ...int) *ta.Response {
+	t.Helper()
+	messages := make([]telego.Message, 0, len(messageIDs))
+	for _, messageID := range messageIDs {
+		messages = append(messages, telego.Message{MessageID: messageID})
+	}
+	b, err := json.Marshal(messages)
+	require.NoError(t, err)
+	return &ta.Response{Ok: true, Result: b}
+}
+
 func successUserResponse(t *testing.T, user *telego.User) *ta.Response {
 	t.Helper()
 	b, err := json.Marshal(user)
@@ -237,6 +248,276 @@ func TestSendMedia_ImageNonDimensionErrorDoesNotFallback(t *testing.T) {
 	assert.NotContains(t, caller.calls[0].URL, "sendDocument")
 }
 
+func TestSendMedia_MultipleImagesUseMediaGroup(t *testing.T) {
+	constructor := &multipartRecordingConstructor{}
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			if strings.Contains(url, "sendMediaGroup") {
+				return successMediaGroupResponse(t, 101, 102), nil
+			}
+			t.Fatalf("unexpected API call: %s", url)
+			return nil, nil
+		},
+	}
+	ch := newTestChannelWithConstructor(t, caller, constructor)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	tmpDir := t.TempDir()
+	firstPath := filepath.Join(tmpDir, "first.png")
+	secondPath := filepath.Join(tmpDir, "second.png")
+	require.NoError(t, os.WriteFile(firstPath, []byte("first-image"), 0o644))
+	require.NoError(t, os.WriteFile(secondPath, []byte("second-image"), 0o644))
+
+	firstRef, err := store.Store(firstPath, media.MediaMeta{Filename: "first.png", ContentType: "image/png"}, "scope-1")
+	require.NoError(t, err)
+	secondRef, err := store.Store(
+		secondPath,
+		media.MediaMeta{Filename: "second.png", ContentType: "image/png"},
+		"scope-1",
+	)
+	require.NoError(t, err)
+
+	ids, err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "12345",
+		Parts: []bus.MediaPart{
+			{Type: "image", Ref: firstRef, Caption: "album caption"},
+			{Type: "image", Ref: secondRef},
+		},
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, []string{"101", "102"}, ids)
+	require.Len(t, caller.calls, 1)
+	assert.Contains(t, caller.calls[0].URL, "sendMediaGroup")
+	require.Len(t, constructor.calls, 1)
+	require.Len(t, constructor.calls[0].FileSizes, 2)
+
+	var mediaPayload []map[string]any
+	require.NoError(t, json.Unmarshal([]byte(constructor.calls[0].Parameters["media"]), &mediaPayload))
+	require.Len(t, mediaPayload, 2)
+	assert.Equal(t, "album caption", mediaPayload[0]["caption"])
+	_, hasSecondCaption := mediaPayload[1]["caption"]
+	assert.False(t, hasSecondCaption)
+}
+
+func TestSendMedia_MoreThanTenImagesSplitIntoMediaGroups(t *testing.T) {
+	constructor := &multipartRecordingConstructor{}
+	callIndex := 0
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			if !strings.Contains(url, "sendMediaGroup") {
+				t.Fatalf("unexpected API call: %s", url)
+			}
+			callIndex++
+			if callIndex == 1 {
+				return successMediaGroupResponse(t, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010), nil
+			}
+			if callIndex == 2 {
+				return successMediaGroupResponse(t, 1011, 1012, 1013, 1014, 1015), nil
+			}
+			t.Fatalf("unexpected sendMediaGroup call #%d", callIndex)
+			return nil, nil
+		},
+	}
+	ch := newTestChannelWithConstructor(t, caller, constructor)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	tmpDir := t.TempDir()
+	parts := make([]bus.MediaPart, 0, 15)
+	for i := 0; i < 15; i++ {
+		path := filepath.Join(tmpDir, "image-"+strconv.Itoa(i)+".png")
+		require.NoError(t, os.WriteFile(path, []byte("img-"+strconv.Itoa(i)), 0o644))
+		ref, err := store.Store(
+			path,
+			media.MediaMeta{Filename: filepath.Base(path), ContentType: "image/png"},
+			"scope-1",
+		)
+		require.NoError(t, err)
+		part := bus.MediaPart{Type: "image", Ref: ref}
+		if i == 0 {
+			part.Caption = "long album caption"
+		}
+		parts = append(parts, part)
+	}
+
+	ids, err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "12345",
+		Parts:  parts,
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, []string{
+		"1001", "1002", "1003", "1004", "1005",
+		"1006", "1007", "1008", "1009", "1010",
+		"1011", "1012", "1013", "1014", "1015",
+	}, ids)
+	require.Len(t, caller.calls, 2)
+	require.Len(t, constructor.calls, 2)
+}
+
+func TestSendMedia_SingleImageLongCaptionSendsTextFirst(t *testing.T) {
+	constructor := &multipartRecordingConstructor{}
+	longCaption := strings.Repeat("a", telegramCaptionLimit) + " tail overflow"
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			switch {
+			case strings.Contains(url, "sendMessage"):
+				return successResponseWithMessageID(t, 201), nil
+			case strings.Contains(url, "sendPhoto"):
+				return successResponseWithMessageID(t, 202), nil
+			default:
+				t.Fatalf("unexpected API call: %s", url)
+				return nil, nil
+			}
+		},
+	}
+	ch := newTestChannelWithConstructor(t, caller, constructor)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	tmpDir := t.TempDir()
+	path := filepath.Join(tmpDir, "image.png")
+	require.NoError(t, os.WriteFile(path, []byte("img"), 0o644))
+	ref, err := store.Store(path, media.MediaMeta{Filename: "image.png", ContentType: "image/png"}, "scope-1")
+	require.NoError(t, err)
+
+	ids, err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "12345",
+		Parts: []bus.MediaPart{{
+			Type:    "image",
+			Ref:     ref,
+			Caption: longCaption,
+		}},
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, []string{"201", "202"}, ids)
+	require.Len(t, caller.calls, 2)
+	assert.Contains(t, caller.calls[0].URL, "sendMessage")
+	assert.Contains(t, caller.calls[1].URL, "sendPhoto")
+	assert.Equal(t, "", constructor.calls[0].Parameters["caption"])
+}
+
+func TestSendMedia_MediaGroupLongCaptionSendsTextFirst(t *testing.T) {
+	constructor := &multipartRecordingConstructor{}
+	longCaption := strings.Repeat("b", telegramCaptionLimit) + " trailing explanation"
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			switch {
+			case strings.Contains(url, "sendMessage"):
+				return successResponseWithMessageID(t, 301), nil
+			case strings.Contains(url, "sendMediaGroup"):
+				return successMediaGroupResponse(t, 302, 303), nil
+			default:
+				t.Fatalf("unexpected API call: %s", url)
+				return nil, nil
+			}
+		},
+	}
+	ch := newTestChannelWithConstructor(t, caller, constructor)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	tmpDir := t.TempDir()
+	firstPath := filepath.Join(tmpDir, "first.png")
+	secondPath := filepath.Join(tmpDir, "second.png")
+	require.NoError(t, os.WriteFile(firstPath, []byte("first-image"), 0o644))
+	require.NoError(t, os.WriteFile(secondPath, []byte("second-image"), 0o644))
+
+	firstRef, err := store.Store(firstPath, media.MediaMeta{Filename: "first.png", ContentType: "image/png"}, "scope-1")
+	require.NoError(t, err)
+	secondRef, err := store.Store(
+		secondPath,
+		media.MediaMeta{Filename: "second.png", ContentType: "image/png"},
+		"scope-1",
+	)
+	require.NoError(t, err)
+
+	ids, err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "12345",
+		Parts: []bus.MediaPart{
+			{Type: "image", Ref: firstRef, Caption: longCaption},
+			{Type: "image", Ref: secondRef},
+		},
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, []string{"301", "302", "303"}, ids)
+	require.Len(t, caller.calls, 2)
+	assert.Contains(t, caller.calls[0].URL, "sendMessage")
+	assert.Contains(t, caller.calls[1].URL, "sendMediaGroup")
+}
+
+func TestSendMedia_MultiGroupLongCaptionSendsTextBeforeGroups(t *testing.T) {
+	constructor := &multipartRecordingConstructor{}
+	longCaption := strings.Repeat("c", telegramCaptionLimit) + " overflow before second album"
+	callOrder := make([]string, 0, 3)
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			switch {
+			case strings.Contains(url, "sendMessage"):
+				callOrder = append(callOrder, "text")
+				return successResponseWithMessageID(t, 499), nil
+			case strings.Contains(url, "sendMediaGroup"):
+				callOrder = append(callOrder, "group")
+				if len(callOrder) == 2 {
+					return successMediaGroupResponse(t, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410), nil
+				}
+				if len(callOrder) == 3 {
+					return successMediaGroupResponse(t, 411, 412, 413, 414, 415), nil
+				}
+				t.Fatalf("unexpected sendMediaGroup order: %v", callOrder)
+				return nil, nil
+			default:
+				t.Fatalf("unexpected API call: %s", url)
+				return nil, nil
+			}
+		},
+	}
+	ch := newTestChannelWithConstructor(t, caller, constructor)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	tmpDir := t.TempDir()
+	parts := make([]bus.MediaPart, 0, 15)
+	for i := 0; i < 15; i++ {
+		path := filepath.Join(tmpDir, "image-"+strconv.Itoa(i)+".png")
+		require.NoError(t, os.WriteFile(path, []byte("img-"+strconv.Itoa(i)), 0o644))
+		ref, err := store.Store(
+			path,
+			media.MediaMeta{Filename: filepath.Base(path), ContentType: "image/png"},
+			"scope-1",
+		)
+		require.NoError(t, err)
+		part := bus.MediaPart{Type: "image", Ref: ref}
+		if i == 0 {
+			part.Caption = longCaption
+		}
+		parts = append(parts, part)
+	}
+
+	ids, err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "12345",
+		Parts:  parts,
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, []string{
+		"499",
+		"401", "402", "403", "404", "405",
+		"406", "407", "408", "409", "410",
+		"411", "412", "413", "414", "415",
+	}, ids)
+	assert.Equal(t, []string{"text", "group", "group"}, callOrder)
+}
+
 func TestSend_EmptyContent(t *testing.T) {
 	caller := &stubCaller{
 		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
@@ -1216,6 +1497,42 @@ func TestHandleMessage_EmptyContent_Ignored(t *testing.T) {
 	}
 }
 
+func TestHandleMessage_LocationForwardedAsText(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &TelegramChannel{
+		BaseChannel: channels.NewBaseChannel("telegram", nil, messageBus, nil),
+		chatIDs:     make(map[string]int64),
+		ctx:         context.Background(),
+	}
+
+	msg := &telego.Message{
+		MessageID: 3049,
+		Location: &telego.Location{
+			Latitude:  35.197713,
+			Longitude: 136.885705,
+		},
+		Chat: telego.Chat{
+			ID:   456,
+			Type: "private",
+		},
+		From: &telego.User{
+			ID:        789,
+			FirstName: "User",
+		},
+	}
+
+	err := ch.handleMessage(context.Background(), msg)
+	require.NoError(t, err)
+
+	select {
+	case inbound := <-messageBus.InboundChan():
+		assert.Equal(t, "[User location: lat=35.197713, lng=136.885705]", inbound.Content)
+		assert.Equal(t, "3049", inbound.Context.MessageID)
+	case <-time.After(time.Second):
+		t.Fatal("timed out waiting for location message")
+	}
+}
+
 func TestHandleMessage_MediaGroupCombinesCaptionMessages(t *testing.T) {
 	messageBus, ch := newMediaGroupTestChannel(10 * time.Millisecond)
 	base := testMediaGroupMessage("album-1")

pkg/channels/wecom/media.go

@@ -334,7 +334,7 @@ func (c *WeComChannel) storeRemoteMedia(
 	}
 	tmpPath := tmpFile.Name()
 	if _, writeErr := tmpFile.Write(data); writeErr != nil {
-		tmpFile.Close()
+		_ = tmpFile.Close()
 		_ = os.Remove(tmpPath)
 		return "", fmt.Errorf("write temp file: %w", writeErr)
 	}

pkg/channels/weixin/weixin_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/base64"
+	"encoding/json"
 	"errors"
 	"io"
 	"net/http"
@@ -319,3 +320,61 @@ func TestSelectInboundMediaItemFallsBackToRefMessage(t *testing.T) {
 		t.Fatalf("selectInboundMediaItem().Type = %d, want %d", item.Type, MessageItemTypeImage)
 	}
 }
+
+func TestSendUploadedMedia_SendsCaptionAsSeparateTextBeforeMedia(t *testing.T) {
+	var requests []SendMessageReq
+	ch := &WeixinChannel{
+		api: &ApiClient{
+			BaseURL: "https://ilinkai.weixin.qq.com/",
+			HttpClient: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+				if r.URL.Path != "/ilink/bot/sendmessage" {
+					t.Fatalf("sendmessage path = %q, want /ilink/bot/sendmessage", r.URL.Path)
+				}
+				var req SendMessageReq
+				if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+					t.Fatalf("decode sendmessage req: %v", err)
+				}
+				requests = append(requests, req)
+				return &http.Response{
+					StatusCode: http.StatusOK,
+					Body:       io.NopCloser(bytes.NewReader([]byte(`{"ret":0,"errcode":0}`))),
+					Header:     make(http.Header),
+				}, nil
+			})},
+		},
+		typingCache: make(map[string]typingTicketCacheEntry),
+	}
+
+	err := ch.sendUploadedMedia(
+		context.Background(),
+		"user-1",
+		"ctx-1",
+		"recipe translation",
+		UploadMediaTypeImage,
+		&uploadedFileInfo{
+			downloadParam: "download-token",
+			aesKeyHex:     "31323334353637383930616263646566",
+			fileSize:      11,
+			cipherSize:    16,
+			filename:      "photo.png",
+		},
+	)
+	if err != nil {
+		t.Fatalf("sendUploadedMedia() error = %v", err)
+	}
+	if len(requests) != 2 {
+		t.Fatalf("sendUploadedMedia() sent %d requests, want 2", len(requests))
+	}
+	if len(requests[0].Msg.ItemList) != 1 || requests[0].Msg.ItemList[0].Type != MessageItemTypeText {
+		t.Fatalf("first request item = %+v, want text item", requests[0].Msg.ItemList)
+	}
+	if got := requests[0].Msg.ItemList[0].TextItem.Text; got != "recipe translation" {
+		t.Fatalf("first request text = %q, want recipe translation", got)
+	}
+	if len(requests[1].Msg.ItemList) != 1 || requests[1].Msg.ItemList[0].Type != MessageItemTypeImage {
+		t.Fatalf("second request item = %+v, want image item", requests[1].Msg.ItemList)
+	}
+	if requests[1].Msg.ItemList[0].ImageItem == nil || requests[1].Msg.ItemList[0].ImageItem.Media == nil {
+		t.Fatalf("second request image media = %+v, want media ref", requests[1].Msg.ItemList[0].ImageItem)
+	}
+}

pkg/channels/whatsapp_native/whatsapp_native.go

@@ -269,9 +269,9 @@ func (c *WhatsAppNativeChannel) Stop(ctx context.Context) error {
 }
 
 func (c *WhatsAppNativeChannel) eventHandler(evt any) {
-	switch evt.(type) {
+	switch v := evt.(type) {
 	case *events.Message:
-		c.handleIncoming(evt.(*events.Message))
+		c.handleIncoming(v)
 	case *events.Disconnected:
 		logger.InfoCF("whatsapp", "WhatsApp disconnected, will attempt reconnection", nil)
 		c.reconnectMu.Lock()

pkg/commands/cmd_context.go

@@ -29,14 +29,17 @@ func formatContextStats(s *ContextStats) string {
 		remaining = 0
 	}
 	usedWindowPercent := s.UsedTokens * 100 / max(s.TotalTokens, 1)
-	return fmt.Sprintf(
-		"Context usage  \nMessages: %d  \nUsed: ~%d / %d tokens (%d%%)  \nCompress at: %d tokens  \nCompression progress: %d%%  \nRemaining: ~%d tokens",
+	msg := fmt.Sprintf(
+		"Context usage  \nMessages: %d  \nUsed: ~%d / %d tokens (%d%%)  \nHistory: ~%d tokens  \nCompress at: %d tokens  \nSummarize at: %d tokens  \nCompression progress: %d%%  \nRemaining: ~%d tokens",
 		s.MessageCount,
 		s.UsedTokens,
 		s.TotalTokens,
 		usedWindowPercent,
+		s.HistoryTokens,
 		s.CompressAtTokens,
+		s.SummarizeAtTokens,
 		s.UsedPercent,
 		remaining,
 	)
+	return msg
 }

pkg/commands/runtime.go

@@ -29,11 +29,13 @@ type MCPToolInfo struct {
 
 // ContextStats describes current session context window usage.
 type ContextStats struct {
-	UsedTokens       int
-	TotalTokens      int // model context window
-	CompressAtTokens int // compression threshold
-	UsedPercent      int // 0-100
-	MessageCount     int
+	UsedTokens        int
+	TotalTokens       int // model context window
+	HistoryTokens     int // history-only tokens (what maybeSummarize checks)
+	CompressAtTokens  int // hard budget compression threshold
+	SummarizeAtTokens int // soft summarization trigger
+	UsedPercent       int // 0-100
+	MessageCount      int
 }
 
 // StopResult describes the outcome of a stop request for the current session.

pkg/config/config.go

@@ -7,6 +7,7 @@ import (
 	"math/rand"
 	"os"
 	"path/filepath"
+	"slices"
 	"strconv"
 	"strings"
 	"sync/atomic"
@@ -194,6 +195,9 @@ type ExposePath struct {
 // Uses strings.Replacer for O(n+m) performance (computed once per SecurityConfig).
 // Short content (below FilterMinLength) is returned unchanged for performance.
 func (c *Config) FilterSensitiveData(content string) string {
+	if c == nil {
+		return content
+	}
 	// Check if filtering is enabled (default: true)
 	if !c.Tools.IsFilterSensitiveDataEnabled() {
 		return content
@@ -254,7 +258,7 @@ func (c *Config) MarshalJSON() ([]byte, error) {
 		Alias: (*Alias)(c),
 	}
 
-	if len(c.Session.Dimensions) > 0 || len(c.Session.IdentityLinks) > 0 {
+	if len(c.Session.Dimensions) > 0 || len(c.Session.IdentityLinks) > 0 || c.Session.DmScope != "" {
 		sessionCfg := c.Session
 		aux.Session = &sessionCfg
 	}
@@ -346,6 +350,47 @@ type DispatchSelector struct {
 type SessionConfig struct {
 	Dimensions    []string            `json:"dimensions,omitempty"`
 	IdentityLinks map[string][]string `json:"identity_links,omitempty"`
+	DmScope       string              `json:"dm_scope,omitempty"`
+}
+
+// ApplyDmScope translates the user-facing dm_scope value into the internal
+// dimensions array that the routing layer consumes. It is a no-op when
+// DmScope is empty or when Dimensions is already set (explicit Dimensions
+// take precedence over the derived value).
+func (s *SessionConfig) ApplyDmScope() {
+	if s.DmScope == "" || len(s.Dimensions) > 0 {
+		return
+	}
+	switch s.DmScope {
+	case "per-channel-peer":
+		s.Dimensions = []string{"chat", "sender"}
+	case "per-channel":
+		s.Dimensions = []string{"chat"}
+	case "per-peer":
+		s.Dimensions = []string{"sender"}
+	case "global":
+		s.Dimensions = nil
+	}
+}
+
+// DeriveDmScope sets DmScope based on Dimensions when DmScope is empty.
+// This handles legacy/fresh configs that only have explicit Dimensions
+// without a corresponding DmScope value, ensuring the API response always
+// includes a dm_scope that matches the actual runtime dimensions.
+func (s *SessionConfig) DeriveDmScope() {
+	if s.DmScope != "" || len(s.Dimensions) == 0 {
+		return
+	}
+	switch {
+	case slices.Equal(s.Dimensions, []string{"chat", "sender"}):
+		s.DmScope = "per-channel-peer"
+	case slices.Equal(s.Dimensions, []string{"chat"}):
+		s.DmScope = "per-channel"
+	case slices.Equal(s.Dimensions, []string{"sender"}):
+		s.DmScope = "per-peer"
+	}
+	// Dimensions not matching any known scope mapping (custom array)
+	// is fine — DmScope stays empty and the UI can handle it.
 }
 
 // RoutingConfig controls the intelligent model routing feature.
@@ -814,6 +859,12 @@ type ToolConfig struct {
 	Enabled bool `json:"enabled" yaml:"-" env:"ENABLED"`
 }
 
+type MessageToolsConfig struct {
+	ToolConfig `yaml:"-" envPrefix:"PICOCLAW_TOOLS_MESSAGE_"`
+
+	MediaEnabled bool `json:"media_enabled" yaml:"-" env:"PICOCLAW_TOOLS_MESSAGE_MEDIA_ENABLED"`
+}
+
 type BraveConfig struct {
 	Enabled    bool          `json:"enabled"           yaml:"-"                  env:"PICOCLAW_TOOLS_WEB_BRAVE_ENABLED"`
 	APIKeys    SecureStrings `json:"api_keys,omitzero" yaml:"api_keys,omitempty" env:"PICOCLAW_TOOLS_WEB_BRAVE_API_KEYS"`
@@ -865,6 +916,31 @@ func (c *TavilyConfig) SetAPIKeys(keys []string) {
 	}
 }
 
+type KagiConfig struct {
+	Enabled    bool          `json:"enabled"           yaml:"-"                  env:"PICOCLAW_TOOLS_WEB_KAGI_ENABLED"`
+	APIKeys    SecureStrings `json:"api_keys,omitzero" yaml:"api_keys,omitempty" env:"PICOCLAW_TOOLS_WEB_KAGI_API_KEYS"`
+	BaseURL    string        `json:"base_url"          yaml:"-"                  env:"PICOCLAW_TOOLS_WEB_KAGI_BASE_URL"`
+	MaxResults int           `json:"max_results"       yaml:"-"                  env:"PICOCLAW_TOOLS_WEB_KAGI_MAX_RESULTS"`
+}
+
+// APIKey returns the Kagi API key
+func (c *KagiConfig) APIKey() string {
+	if len(c.APIKeys) == 0 {
+		return ""
+	}
+	return c.APIKeys[0].String()
+}
+
+// SetAPIKey sets the Kagi API key
+func (c *KagiConfig) SetAPIKey(key string) {
+	c.APIKeys = SimpleSecureStrings(key)
+}
+
+// SetAPIKeys sets the Kagi API keys
+func (c *KagiConfig) SetAPIKeys(keys []string) {
+	c.APIKeys = SimpleSecureStrings(keys...)
+}
+
 type DuckDuckGoConfig struct {
 	Enabled    bool `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_DUCKDUCKGO_ENABLED"`
 	MaxResults int  `json:"max_results" env:"PICOCLAW_TOOLS_WEB_DUCKDUCKGO_MAX_RESULTS"`
@@ -928,6 +1004,7 @@ type WebToolsConfig struct {
 	ToolConfig  `                   yaml:"-"                      envPrefix:"PICOCLAW_TOOLS_WEB_"`
 	Brave       BraveConfig        `yaml:"brave,omitempty"                                        json:"brave"`
 	Tavily      TavilyConfig       `yaml:"tavily,omitempty"                                       json:"tavily"`
+	Kagi        KagiConfig         `yaml:"kagi,omitempty"                                         json:"kagi"`
 	Sogou       SogouConfig        `yaml:"-"                                                      json:"sogou"`
 	DuckDuckGo  DuckDuckGoConfig   `yaml:"-"                                                      json:"duckduckgo"`
 	Gemini      GeminiSearchConfig `yaml:"gemini,omitempty"                                       json:"gemini"`
@@ -1026,7 +1103,7 @@ type ToolsConfig struct {
 	InstallSkill    ToolConfig         `json:"install_skill"     yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_INSTALL_SKILL_"`
 	ListDir         ToolConfig         `json:"list_dir"          yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_LIST_DIR_"`
 	LoadImage       ToolConfig         `json:"load_image"        yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_LOAD_IMAGE_"`
-	Message         ToolConfig         `json:"message"           yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_MESSAGE_"`
+	Message         MessageToolsConfig `json:"message"           yaml:"-"`
 	ReadFile        ReadFileToolConfig `json:"read_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_READ_FILE_"`
 	Serial          ToolConfig         `json:"serial"            yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SERIAL_"`
 	SendFile        ToolConfig         `json:"send_file"         yaml:"-"                                                       envPrefix:"PICOCLAW_TOOLS_SEND_FILE_"`
@@ -1441,6 +1518,9 @@ func LoadConfig(path string) (*Config, error) {
 		cfg.Agents.Defaults.Workspace = filepath.Join(homePath, pkg.WorkspaceName)
 	}
 
+	cfg.Session.ApplyDmScope()
+	cfg.Session.DeriveDmScope()
+
 	return cfg, nil
 }
 
@@ -1662,6 +1742,8 @@ func ResetToDefaults(configPath string) error {
 		return fmt.Errorf("backup before reset: %w", err)
 	}
 	cfg := DefaultConfig()
+	cfg.Session.ApplyDmScope()
+	cfg.Session.DeriveDmScope()
 	if err := cfg.SecurityCopyFrom(configPath); err != nil {
 		logger.WarnF("could not preserve security config", map[string]any{"error": err})
 	}

pkg/config/config_test.go

@@ -907,6 +907,29 @@ func TestDefaultConfig_WorkspacePath(t *testing.T) {
 	}
 }
 
+// TestDefaultConfig_AnthropicModelsUseClaudeAPIIDs verifies that first-party
+// Anthropic defaults use Claude API model IDs, not dotted display names or
+// Bedrock-style provider prefixes. See:
+// https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions
+func TestDefaultConfig_AnthropicModelsUseClaudeAPIIDs(t *testing.T) {
+	cfg := DefaultConfig()
+
+	checked := 0
+	for _, model := range cfg.ModelList {
+		if model.Provider != "anthropic" {
+			continue
+		}
+		checked++
+		if strings.Contains(model.Model, ".") {
+			t.Fatalf("Anthropic default model %q uses dotted ID %q", model.ModelName, model.Model)
+		}
+	}
+
+	if checked == 0 {
+		t.Fatal("DefaultConfig() missing Anthropic models")
+	}
+}
+
 // TestDefaultConfig_MaxTokens verifies max tokens has default value
 func TestDefaultConfig_MaxTokens(t *testing.T) {
 	cfg := DefaultConfig()
@@ -1480,6 +1503,16 @@ func TestLoadConfig_LoadImageCanBeDisabled(t *testing.T) {
 	}
 }
 
+func TestDefaultConfig_MessageMediaDisabled(t *testing.T) {
+	cfg := DefaultConfig()
+	if !cfg.Tools.Message.Enabled {
+		t.Fatal("DefaultConfig().Tools.Message.Enabled should be true")
+	}
+	if cfg.Tools.Message.MediaEnabled {
+		t.Fatal("DefaultConfig().Tools.Message.MediaEnabled should be false")
+	}
+}
+
 func TestToolsConfig_GetFilterMinLength(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -1695,6 +1728,166 @@ func TestDefaultConfig_SessionDimensions(t *testing.T) {
 	}
 }
 
+func TestSessionConfig_ApplyDmScope(t *testing.T) {
+	tests := []struct {
+		name       string
+		dmScope    string
+		dimensions []string
+		want       []string
+	}{
+		{
+			name:    "per-channel-peer",
+			dmScope: "per-channel-peer",
+			want:    []string{"chat", "sender"},
+		},
+		{
+			name:    "per-channel",
+			dmScope: "per-channel",
+			want:    []string{"chat"},
+		},
+		{
+			name:    "per-peer",
+			dmScope: "per-peer",
+			want:    []string{"sender"},
+		},
+		{
+			name:    "global",
+			dmScope: "global",
+			want:    nil,
+		},
+		{
+			name:       "explicit dimensions take precedence",
+			dmScope:    "per-channel-peer",
+			dimensions: []string{"sender"},
+			want:       []string{"sender"},
+		},
+		{
+			name:    "empty dm_scope is no-op",
+			dmScope: "",
+			want:    nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			s := &SessionConfig{
+				DmScope:    tt.dmScope,
+				Dimensions: tt.dimensions,
+			}
+			s.ApplyDmScope()
+			if len(s.Dimensions) != len(tt.want) {
+				t.Fatalf("Dimensions = %v, want %v", s.Dimensions, tt.want)
+			}
+			for i, v := range tt.want {
+				if s.Dimensions[i] != v {
+					t.Errorf("Dimensions[%d] = %q, want %q", i, s.Dimensions[i], v)
+				}
+			}
+		})
+	}
+}
+
+func TestSessionConfig_DeriveDmScope(t *testing.T) {
+	tests := []struct {
+		name       string
+		dimensions []string
+		dmScope    string
+		wantScope  string
+	}{
+		{
+			name:       "per-channel-peer from dimensions",
+			dimensions: []string{"chat", "sender"},
+			wantScope:  "per-channel-peer",
+		},
+		{
+			name:       "per-channel from dimensions",
+			dimensions: []string{"chat"},
+			wantScope:  "per-channel",
+		},
+		{
+			name:       "per-peer from dimensions",
+			dimensions: []string{"sender"},
+			wantScope:  "per-peer",
+		},
+		{
+			name:       "custom dimensions does not set scope",
+			dimensions: []string{"chat", "extra"},
+			wantScope:  "",
+		},
+		{
+			name:       "empty dimensions does not set scope",
+			dimensions: nil,
+			wantScope:  "",
+		},
+		{
+			name:       "existing dm_scope is not overwritten",
+			dimensions: []string{"chat", "sender"},
+			dmScope:    "per-channel",
+			wantScope:  "per-channel",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			s := &SessionConfig{
+				DmScope:    tt.dmScope,
+				Dimensions: tt.dimensions,
+			}
+			s.DeriveDmScope()
+			if s.DmScope != tt.wantScope {
+				t.Errorf("DmScope = %q, want %q", s.DmScope, tt.wantScope)
+			}
+		})
+	}
+}
+
+func TestSessionConfig_ApplyDmScope_ClearsStaleDimensions(t *testing.T) {
+	// Simulates the PATCH handler scenario: dm_scope changed but stale
+	// dimensions remain from the old scope. After clearing dimensions,
+	// ApplyDmScope should re-derive from the new dm_scope.
+	tests := []struct {
+		name    string
+		dmScope string
+		want    []string
+	}{
+		{
+			name:    "per-channel-peer to per-channel",
+			dmScope: "per-channel",
+			want:    []string{"chat"},
+		},
+		{
+			name:    "per-channel-peer to per-peer",
+			dmScope: "per-peer",
+			want:    []string{"sender"},
+		},
+		{
+			name:    "per-channel-peer to global",
+			dmScope: "global",
+			want:    nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			s := &SessionConfig{
+				DmScope:    tt.dmScope,
+				Dimensions: []string{"chat", "sender"}, // stale from per-channel-peer
+			}
+			// Simulate what the PATCH handler does: clear dimensions when dm_scope changes
+			s.Dimensions = nil
+			s.ApplyDmScope()
+			if len(s.Dimensions) != len(tt.want) {
+				t.Fatalf("Dimensions = %v, want %v", s.Dimensions, tt.want)
+			}
+			for i, v := range tt.want {
+				if s.Dimensions[i] != v {
+					t.Errorf("Dimensions[%d] = %q, want %q", i, s.Dimensions[i], v)
+				}
+			}
+		})
+	}
+}
+
 func TestDefaultConfig_WorkspacePath_Default(t *testing.T) {
 	t.Setenv("PICOCLAW_HOME", "")
 

pkg/config/defaults.go

@@ -88,7 +88,7 @@ func DefaultConfig() *Config {
 			{
 				ModelName: "claude-sonnet-4.6",
 				Provider:  "anthropic",
-				Model:     "claude-sonnet-4.6",
+				Model:     "claude-sonnet-4-6",
 				APIBase:   "https://api.anthropic.com/v1",
 			},
 
@@ -333,6 +333,11 @@ func DefaultConfig() *Config {
 					Enabled:    false,
 					MaxResults: 5,
 				},
+				Kagi: KagiConfig{
+					Enabled:    false,
+					BaseURL:    "https://kagi.com/api/v1/search",
+					MaxResults: 5,
+				},
 				Sogou: SogouConfig{
 					Enabled:    true,
 					MaxResults: 5,
@@ -447,8 +452,11 @@ func DefaultConfig() *Config {
 			LoadImage: ToolConfig{
 				Enabled: true,
 			},
-			Message: ToolConfig{
-				Enabled: true,
+			Message: MessageToolsConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
+				MediaEnabled: false,
 			},
 			ReadFile: ReadFileToolConfig{
 				Enabled:         true,

pkg/config/example_security_usage.go

@@ -51,7 +51,7 @@ channels:
 	  token: "your-discord-bot-token"
 
 # Web Tool Keys
-# Brave, Tavily, Perplexity: Use 'api_keys' array
+# Brave, Tavily, Perplexity, Kagi: Use 'api_keys' array
 # GLMSearch, BaiduSearch: Use 'api_key' single string
 web:
 
@@ -65,6 +65,9 @@ web:
 	perplexity:
 	  api_keys:
 	    - "pplx-your-perplexity-api-key"  # Single key in array format
+	kagi:
+	  api_keys:
+	    - "your-kagi-api-key"  # Single key in array format
 	glm_search:
 	  api_key: "your-glm-search-api-key"  # Single key (not array)
 	baidu_search:
@@ -239,7 +242,7 @@ channels:
 
 ## Web Tool API Keys
 
-**Brave, Tavily, Perplexity:**
+**Brave, Tavily, Perplexity, Kagi:**
 ```yaml
 web:
 
@@ -253,6 +256,9 @@ web:
 	perplexity:
 	  api_keys:
 	    - "pplx-key"
+	kagi:
+	  api_keys:
+	    - "kagi-key"
 
 ```
 Use `api_keys` (plural) array format.
@@ -443,7 +449,7 @@ web:
 
 ## Single Key Format
 
-**Models, Brave, Tavily, Perplexity:**
+**Models, Brave, Tavily, Perplexity, Kagi:**
 ```yaml
 model_list:
 
@@ -565,7 +571,7 @@ and .security.yml values.
 ## Multiple API Keys Not Working
 - Ensure you're using `api_keys` (plural) in .security.yml for models and web tools (except GLMSearch/BaiduSearch)
 - Check that the array format is correct in YAML (proper indentation with dashes)
-- Remember: Models, Brave, Tavily, Perplexity MUST use `api_keys` (array format)
+- Remember: Models, Brave, Tavily, Perplexity, Kagi MUST use `api_keys` (array format)
 - GLMSearch and BaiduSearch MUST use `api_key` (single string format)
 
 ## Keys Not Being Applied

pkg/config/gateway.go

@@ -88,7 +88,12 @@ func ResolveGatewayLogLevel(path string) string {
 
 	data, err := os.ReadFile(path)
 	if err == nil {
-		_ = json.Unmarshal(data, &cfg)
+		if err := json.Unmarshal(data, &cfg); err != nil {
+			logger.WarnCF("config", "failed to parse gateway config, using defaults", map[string]any{
+				"path":  path,
+				"error": err.Error(),
+			})
+		}
 	}
 
 	if envLevel := os.Getenv("PICOCLAW_LOG_LEVEL"); envLevel != "" {

pkg/config/migration.go

@@ -501,7 +501,10 @@ func mergeModelListsWithMap(mainML []any, secML map[string]any) error {
 	for i, m := range mainML {
 		if mVal, ok := m.(map[string]any); ok {
 			if name, hasName := mVal["model_name"]; hasName {
-				nameStr := name.(string)
+				nameStr, ok := name.(string)
+				if !ok {
+					return fmt.Errorf("model_name must be a string, got %T", name)
+				}
 				index := countMap[nameStr]
 				indexedKeys[fmt.Sprintf("%s:%d", nameStr, index)] = i
 				if _, ok := indexedKeys[nameStr]; !ok {

pkg/config/security_integration_test.go

@@ -191,6 +191,10 @@ func TestAllSecurityKeysAccessible(t *testing.T) {
 		err = os.WriteFile(perplexityAPIKeyFile, []byte("pplx-perplexity-from-file-22222"), 0o600)
 		require.NoError(t, err)
 
+		kagiAPIKeyFile := filepath.Join(tmpDir, "kagi_api_key.txt")
+		err = os.WriteFile(kagiAPIKeyFile, []byte("kagi-from-file-33333"), 0o600)
+		require.NoError(t, err)
+
 		githubTokenFile := filepath.Join(tmpDir, "github_token.txt")
 		err = os.WriteFile(githubTokenFile, []byte("ghp-github-from-file-abc123"), 0o600)
 		require.NoError(t, err)
@@ -270,6 +274,9 @@ func TestAllSecurityKeysAccessible(t *testing.T) {
       "perplexity": {
         "enabled": true
       },
+      "kagi": {
+        "enabled": true
+      },
       "glm_search": {
         "enabled": true
       }
@@ -331,6 +338,9 @@ web:
   perplexity:
     api_keys:
       - "file://perplexity_api_key.txt"
+  kagi:
+    api_keys:
+      - "file://kagi_api_key.txt"
   glm_search:
     api_key: "glm-test-glm-search-key"
 
@@ -456,6 +466,9 @@ skills:
 		assert.Equal(t, "pplx-perplexity-from-file-22222", cfg.Tools.Web.Perplexity.APIKey())
 		t.Logf("Perplexity APIKey(): %s", cfg.Tools.Web.Perplexity.APIKey())
 
+		assert.Equal(t, "kagi-from-file-33333", cfg.Tools.Web.Kagi.APIKey())
+		t.Logf("Kagi APIKey(): %s", cfg.Tools.Web.Kagi.APIKey())
+
 		// GLM Search - Note: GLM uses SetAPIKey (lowercase) internally
 		t.Logf("GLMSearch APIKey(): %s", cfg.Tools.Web.GLMSearch.APIKey.String())
 		assert.Equal(t, "glm-test-glm-search-key", cfg.Tools.Web.GLMSearch.APIKey.String())

pkg/cron/service.go

@@ -447,14 +447,37 @@ func (cs *CronService) AddJob(
 	return &job, nil
 }
 
+func (cs *CronService) GetJob(jobID string) (*CronJob, bool) {
+	cs.mu.RLock()
+	defer cs.mu.RUnlock()
+
+	for i := range cs.store.Jobs {
+		if cs.store.Jobs[i].ID == jobID {
+			jobCopy := cloneCronJob(cs.store.Jobs[i])
+			return &jobCopy, true
+		}
+	}
+	return nil, false
+}
+
 func (cs *CronService) UpdateJob(job *CronJob) error {
 	cs.mu.Lock()
 	defer cs.mu.Unlock()
 
 	for i := range cs.store.Jobs {
 		if cs.store.Jobs[i].ID == job.ID {
-			cs.store.Jobs[i] = *job
-			cs.store.Jobs[i].UpdatedAtMS = time.Now().UnixMilli()
+			previous := cs.store.Jobs[i]
+			updated := cloneCronJob(*job)
+			now := time.Now().UnixMilli()
+			updated.UpdatedAtMS = now
+			if updated.Enabled {
+				if previous.Enabled != updated.Enabled || !sameSchedule(previous.Schedule, updated.Schedule) {
+					updated.State.NextRunAtMS = cs.computeNextRun(&updated.Schedule, now)
+				}
+			} else {
+				updated.State.NextRunAtMS = nil
+			}
+			cs.store.Jobs[i] = updated
 
 			cs.notify()
 
@@ -464,6 +487,42 @@ func (cs *CronService) UpdateJob(job *CronJob) error {
 	return fmt.Errorf("job not found")
 }
 
+func cloneCronJob(job CronJob) CronJob {
+	clone := job
+	if job.Schedule.AtMS != nil {
+		atMS := *job.Schedule.AtMS
+		clone.Schedule.AtMS = &atMS
+	}
+	if job.Schedule.EveryMS != nil {
+		everyMS := *job.Schedule.EveryMS
+		clone.Schedule.EveryMS = &everyMS
+	}
+	if job.State.NextRunAtMS != nil {
+		nextRunAtMS := *job.State.NextRunAtMS
+		clone.State.NextRunAtMS = &nextRunAtMS
+	}
+	if job.State.LastRunAtMS != nil {
+		lastRunAtMS := *job.State.LastRunAtMS
+		clone.State.LastRunAtMS = &lastRunAtMS
+	}
+	return clone
+}
+
+func sameSchedule(a, b CronSchedule) bool {
+	return a.Kind == b.Kind &&
+		sameInt64(a.AtMS, b.AtMS) &&
+		sameInt64(a.EveryMS, b.EveryMS) &&
+		a.Expr == b.Expr &&
+		a.TZ == b.TZ
+}
+
+func sameInt64(a, b *int64) bool {
+	if a == nil || b == nil {
+		return a == b
+	}
+	return *a == *b
+}
+
 func (cs *CronService) RemoveJob(jobID string) bool {
 	cs.mu.Lock()
 	defer cs.mu.Unlock()

pkg/cron/service_test.go

@@ -82,6 +82,136 @@ func TestCronService_CRUD(t *testing.T) {
 	}
 }
 
+func TestCronService_GetJobReturnsCopy(t *testing.T) {
+	cs, path := setupService(nil)
+	defer os.Remove(path)
+
+	everyMS := int64(60_000)
+	job, err := cs.AddJob("Task1", CronSchedule{Kind: "every", EveryMS: &everyMS}, "msg", "ch", "to")
+	if err != nil {
+		t.Fatalf("AddJob failed: %v", err)
+	}
+	if job.State.NextRunAtMS == nil {
+		t.Fatal("expected initial next run")
+	}
+	nextRun := *job.State.NextRunAtMS
+
+	got, ok := cs.GetJob(job.ID)
+	if !ok {
+		t.Fatal("GetJob should find job")
+	}
+	got.Name = "mutated"
+	got.Payload.Message = "changed"
+	if got.Schedule.EveryMS != nil {
+		*got.Schedule.EveryMS = 120_000
+	}
+	if got.State.NextRunAtMS != nil {
+		*got.State.NextRunAtMS = time.Now().Add(3 * time.Hour).UnixMilli()
+	}
+
+	again, ok := cs.GetJob(job.ID)
+	if !ok {
+		t.Fatal("GetJob should still find job")
+	}
+	if again.Name != "Task1" || again.Payload.Message != "msg" {
+		t.Fatalf("GetJob should return a copy, got %+v", again)
+	}
+	if again.Schedule.EveryMS == nil || *again.Schedule.EveryMS != everyMS {
+		t.Fatalf("GetJob should not alias schedule pointers, got %+v", again.Schedule)
+	}
+	if again.State.NextRunAtMS == nil || *again.State.NextRunAtMS != nextRun {
+		t.Fatalf("GetJob should not alias state pointers, got %+v", again.State)
+	}
+}
+
+func TestCronService_UpdateJobRecomputesNextRunOnScheduleOrEnabledChange(t *testing.T) {
+	cs, path := setupService(nil)
+	defer os.Remove(path)
+
+	at := time.Now().Add(time.Hour).UnixMilli()
+	job, err := cs.AddJob("Task1", CronSchedule{Kind: "at", AtMS: &at}, "msg", "ch", "to")
+	if err != nil {
+		t.Fatalf("AddJob failed: %v", err)
+	}
+	if job.State.NextRunAtMS == nil {
+		t.Fatal("expected initial next run")
+	}
+	initialNextRun := *job.State.NextRunAtMS
+
+	everyMS := int64(30_000)
+	job.Schedule = CronSchedule{Kind: "every", EveryMS: &everyMS}
+	if err := cs.UpdateJob(job); err != nil {
+		t.Fatalf("UpdateJob schedule failed: %v", err)
+	}
+	updated, ok := cs.GetJob(job.ID)
+	if !ok {
+		t.Fatal("updated job not found")
+	}
+	if updated.State.NextRunAtMS == nil {
+		t.Fatal("expected recomputed next run after schedule change")
+	}
+	if *updated.State.NextRunAtMS == initialNextRun {
+		t.Fatalf("next run should be recomputed, still %d", initialNextRun)
+	}
+
+	if disabled := cs.EnableJob(job.ID, false); disabled == nil {
+		t.Fatal("EnableJob(false) returned nil")
+	}
+	disabled, ok := cs.GetJob(job.ID)
+	if !ok {
+		t.Fatal("disabled job not found")
+	}
+	disabled.Enabled = true
+	if err := cs.UpdateJob(disabled); err != nil {
+		t.Fatalf("UpdateJob enabled failed: %v", err)
+	}
+	reenabled, ok := cs.GetJob(job.ID)
+	if !ok {
+		t.Fatal("reenabled job not found")
+	}
+	if !reenabled.Enabled || reenabled.State.NextRunAtMS == nil {
+		t.Fatalf("expected enabled job with next run, got %+v", reenabled)
+	}
+}
+
+func TestCronService_UpdateJobPreservesRunStateOnPayloadOnlyChange(t *testing.T) {
+	cs, path := setupService(nil)
+	defer os.Remove(path)
+
+	everyMS := int64(60_000)
+	job, err := cs.AddJob("Task1", CronSchedule{Kind: "every", EveryMS: &everyMS}, "msg", "ch", "to")
+	if err != nil {
+		t.Fatalf("AddJob failed: %v", err)
+	}
+	lastRun := time.Now().Add(-time.Minute).UnixMilli()
+	job.State.LastRunAtMS = &lastRun
+	job.State.LastStatus = "ok"
+	job.State.LastError = "previous"
+	if job.State.NextRunAtMS == nil {
+		t.Fatal("expected next run before update")
+	}
+	nextRun := *job.State.NextRunAtMS
+
+	job.Payload.Message = "updated msg"
+	if err := cs.UpdateJob(job); err != nil {
+		t.Fatalf("UpdateJob failed: %v", err)
+	}
+
+	updated, ok := cs.GetJob(job.ID)
+	if !ok {
+		t.Fatal("updated job not found")
+	}
+	if updated.State.LastRunAtMS == nil || *updated.State.LastRunAtMS != lastRun {
+		t.Fatalf("last run changed: %+v", updated.State)
+	}
+	if updated.State.LastStatus != "ok" || updated.State.LastError != "previous" {
+		t.Fatalf("last status changed: %+v", updated.State)
+	}
+	if updated.State.NextRunAtMS == nil || *updated.State.NextRunAtMS != nextRun {
+		t.Fatalf("next run should be preserved: before=%d after=%+v", nextRun, updated.State.NextRunAtMS)
+	}
+}
+
 // 2. Test Cron Expression Calculation Logic
 func TestCronService_ComputeNextRun(t *testing.T) {
 	cs, path := setupService(nil)

pkg/events/kind.go

@@ -68,6 +68,9 @@ const (
 
 	// KindBusPublishFailed is emitted when message bus publish fails.
 	KindBusPublishFailed Kind = "bus.publish.failed"
+	// KindBusMessageDropped is emitted when a message is dropped due to
+	// backpressure (channel full for longer than the drop budget).
+	KindBusMessageDropped Kind = "bus.message.dropped"
 	// KindBusCloseStarted is emitted when message bus close starts.
 	KindBusCloseStarted Kind = "bus.close.started"
 	// KindBusCloseCompleted is emitted when message bus close completes.
@@ -133,6 +136,7 @@ var knownKinds = []Kind{
 	KindChannelMessageOutboundFailed,
 	KindChannelRateLimited,
 	KindBusPublishFailed,
+	KindBusMessageDropped,
 	KindBusCloseStarted,
 	KindBusCloseCompleted,
 	KindBusCloseDrained,

pkg/evolution/drafts.go

@@ -67,7 +67,10 @@ type DefaultDraftGenerator struct {
 func NewDefaultDraftGenerator(workspace string) *DefaultDraftGenerator {
 	builtinSkillsDir := strings.TrimSpace(os.Getenv(config.EnvBuiltinSkills))
 	if builtinSkillsDir == "" {
-		wd, _ := os.Getwd()
+		wd, err := os.Getwd()
+		if err != nil {
+			wd = config.GetHome()
+		}
 		builtinSkillsDir = filepath.Join(wd, "skills")
 	}
 

pkg/evolution/skills_recall.go

@@ -18,7 +18,10 @@ type SkillsRecaller struct {
 func NewSkillsRecaller(workspace string) *SkillsRecaller {
 	builtinSkillsDir := strings.TrimSpace(os.Getenv(config.EnvBuiltinSkills))
 	if builtinSkillsDir == "" {
-		wd, _ := os.Getwd()
+		wd, err := os.Getwd()
+		if err != nil {
+			wd = config.GetHome()
+		}
 		builtinSkillsDir = filepath.Join(wd, "skills")
 	}
 

pkg/evolution/store.go

@@ -88,7 +88,11 @@ func (s *Store) appendJSONLRecords(ctx context.Context, path string, records []L
 	if err != nil {
 		return err
 	}
-	defer f.Close()
+	defer func() {
+		if closeErr := f.Close(); closeErr != nil && err == nil {
+			err = closeErr
+		}
+	}()
 
 	enc := json.NewEncoder(f)
 	for _, record := range records {

pkg/gateway/gateway.go

@@ -222,6 +222,11 @@ func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) (runEr
 	if err != nil {
 		return err
 	}
+	// All services (channels + shared HTTP server) are up; mark the health
+	// server ready so GET /ready reports "ready". The health endpoints are
+	// mounted on the shared gateway mux, so Health.Server.Start() (which would
+	// otherwise set this) is never called — we flip the flag explicitly here.
+	runningServices.HealthServer.SetReady(true)
 	publishGatewayEvent(agentLoop, runtimeevents.KindGatewayReady, startedAt, nil)
 	closeListeners = false
 

pkg/isolation/platform_windows.go

@@ -62,7 +62,10 @@ func postStartPlatformIsolation(cmd *exec.Cmd, isolation config.IsolationConfig,
 	if !isolation.Enabled || cmd == nil || cmd.Process == nil {
 		return nil
 	}
-	resourcesAny, _ := windowsPendingResources.LoadAndDelete(cmd)
+	resourcesAny, loaded := windowsPendingResources.LoadAndDelete(cmd)
+	if !loaded {
+		return nil
+	}
 	resources, _ := resourcesAny.(windowsProcessResources)
 	// Job objects can only be attached after the process exists, so the Windows
 	// backend finishes isolation in this post-start hook.

pkg/mcp/isolated_command_transport.go

@@ -62,7 +62,7 @@ func (s *isolatedPipeRWC) Write(p []byte) (n int, err error) {
 
 func (s *isolatedPipeRWC) Close() error {
 	if err := s.stdin.Close(); err != nil {
-		return fmt.Errorf("closing stdin: %v", err)
+		return fmt.Errorf("closing stdin: %w", err)
 	}
 	resChan := make(chan error, 1)
 	go func() {
@@ -205,7 +205,7 @@ func (c *isolatedIOConn) Write(ctx context.Context, msg jsonrpc.Message) error {
 	defer c.writeMu.Unlock()
 	data, err := jsonrpc.EncodeMessage(msg)
 	if err != nil {
-		return fmt.Errorf("marshaling message: %v", err)
+		return fmt.Errorf("marshaling message: %w", err)
 	}
 	data = append(data, '\n')
 	_, err = c.rwc.Write(data)

pkg/memory/jsonl.go

@@ -4,6 +4,8 @@ import (
 	"bufio"
 	"bytes"
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"hash/fnv"
@@ -227,6 +229,11 @@ func (s *JSONLStore) UpsertSessionMeta(
 
 // PromoteAliasHistory atomically promotes the first non-empty alias session
 // into the canonical session when the canonical session is still empty.
+//
+// Main-session aliases (e.g. "agent:main:main" or its opaque form) are
+// skipped during promotion.  The main session is a shared global fallback
+// and promoting its history into individual sessions would attach stale
+// messages to every new Web UI session (issue #2972).
 func (s *JSONLStore) PromoteAliasHistory(
 	_ context.Context,
 	sessionKey string,
@@ -240,6 +247,9 @@ func (s *JSONLStore) PromoteAliasHistory(
 
 	aliases = normalizeAliases(sessionKey, aliases)
 	for _, alias := range aliases {
+		if isMainSessionAlias(alias) {
+			continue
+		}
 		unlock := s.lockSessionPair(sessionKey, alias)
 		promoted, err := s.promoteAliasHistoryLocked(sessionKey, alias, scope, aliases)
 		unlock()
@@ -251,6 +261,34 @@ func (s *JSONLStore) PromoteAliasHistory(
 	return false, nil
 }
 
+// isMainSessionAlias reports whether alias is the legacy or opaque main-session
+// key.  The main session ("agent:<agent>:main") is a shared fallback and should
+// not have its history promoted into individual per-channel sessions.
+func isMainSessionAlias(alias string) bool {
+	if alias == "" {
+		return false
+	}
+	// Legacy form: "agent:main:main" (exactly 3 colon-separated parts)
+	// Must not match "agent:sales:direct:main" etc.
+	if strings.HasPrefix(alias, "agent:") && strings.HasSuffix(alias, ":main") {
+		parts := strings.SplitN(alias, ":", 4)
+		if len(parts) == 3 {
+			return true
+		}
+	}
+	// Opaque form: "sk_v1_" + SHA256("agent:main:main")
+	if strings.HasPrefix(alias, "sk_v1_") {
+		for _, agentID := range []string{"main", "Main", "MAIN"} {
+			legacy := "agent:" + agentID + ":main"
+			hash := sha256.Sum256([]byte(legacy))
+			if "sk_v1_"+hex.EncodeToString(hash[:]) == alias {
+				return true
+			}
+		}
+	}
+	return false
+}
+
 // ResolveSessionKey returns the canonical session key for a candidate key.
 // It short-circuits direct canonical keys when possible, then scans metadata
 // once to resolve aliases or canonical metadata keys.
@@ -561,6 +599,12 @@ func (s *JSONLStore) addMsg(sessionKey string, msg providers.Message) error {
 	l.Lock()
 	defer l.Unlock()
 
+	now := time.Now()
+
+	if msg.CreatedAt == nil {
+		msg.CreatedAt = &now
+	}
+
 	// Append the message as a single JSON line.
 	line, err := json.Marshal(msg)
 	if err != nil {
@@ -598,7 +642,6 @@ func (s *JSONLStore) addMsg(sessionKey string, msg providers.Message) error {
 	if err != nil {
 		return err
 	}
-	now := time.Now()
 	if meta.Count == 0 && meta.CreatedAt.IsZero() {
 		meta.CreatedAt = now
 	}
@@ -726,6 +769,12 @@ func (s *JSONLStore) SetHistory(
 	meta.Count = len(history)
 	meta.UpdatedAt = now
 
+	for i := range history {
+		if history[i].CreatedAt == nil {
+			history[i].CreatedAt = &now
+		}
+	}
+
 	// Write meta BEFORE rewriting the JSONL file. If we crash between
 	// the two writes, meta has Skip=0 and the old file is still intact,
 	// so GetHistory reads from line 1 — returning "too many" messages

pkg/memory/jsonl_test.go

@@ -1058,6 +1058,143 @@ func TestMultipleSessions_Isolation(t *testing.T) {
 	}
 }
 
+func TestStore_SetsCreatedAtWhenNil(t *testing.T) {
+	type writeOp struct {
+		name string
+		fn   func(store *JSONLStore, key string) (expectedCount int)
+	}
+
+	ops := []writeOp{
+		{
+			name: "AddMessage",
+			fn: func(store *JSONLStore, key string) int {
+				if err := store.AddMessage(context.Background(), key, "user", "hello"); err != nil {
+					t.Fatalf("AddMessage: %v", err)
+				}
+				return 1
+			},
+		},
+		{
+			name: "AddFullMessage",
+			fn: func(store *JSONLStore, key string) int {
+				if err := store.AddFullMessage(context.Background(), key, providers.Message{
+					Role:    "user",
+					Content: "hello from full",
+				}); err != nil {
+					t.Fatalf("AddFullMessage: %v", err)
+				}
+				return 1
+			},
+		},
+		{
+			name: "SetHistory",
+			fn: func(store *JSONLStore, key string) int {
+				if err := store.SetHistory(context.Background(), key, []providers.Message{
+					{Role: "user", Content: "msg1"},
+					{Role: "assistant", Content: "msg2"},
+				}); err != nil {
+					t.Fatalf("SetHistory: %v", err)
+				}
+				return 2
+			},
+		},
+	}
+
+	for _, op := range ops {
+		t.Run(op.name, func(t *testing.T) {
+			store := newTestStore(t)
+			key := "s1"
+
+			before := time.Now().Add(-time.Second)
+			expectedCount := op.fn(store, key)
+			after := time.Now().Add(time.Second)
+
+			history, err := store.GetHistory(context.Background(), key)
+			if err != nil {
+				t.Fatalf("GetHistory: %v", err)
+			}
+			if len(history) != expectedCount {
+				t.Fatalf("expected %d messages, got %d", expectedCount, len(history))
+			}
+			for i := range history {
+				if history[i].CreatedAt == nil || history[i].CreatedAt.IsZero() {
+					t.Errorf("message %d CreatedAt is zero — not set by %s", i, op.name)
+				}
+				if history[i].CreatedAt.Before(before) || history[i].CreatedAt.After(after) {
+					t.Errorf(
+						"message %d CreatedAt %v outside expected window [%v, %v]",
+						i, history[i].CreatedAt, before, after,
+					)
+				}
+			}
+		})
+	}
+}
+
+func TestStore_PreservesExistingCreatedAt(t *testing.T) {
+	t1 := time.Date(2026, 1, 1, 10, 0, 0, 0, time.UTC)
+	t2 := time.Date(2026, 1, 1, 11, 0, 0, 0, time.UTC)
+
+	type writeOp struct {
+		name      string
+		fn        func(store *JSONLStore, key string)
+		wantTimes []time.Time
+	}
+
+	ops := []writeOp{
+		{
+			name: "AddFullMessage",
+			fn: func(store *JSONLStore, key string) {
+				if err := store.AddFullMessage(context.Background(), key, providers.Message{
+					Role:      "user",
+					Content:   "custom time",
+					CreatedAt: &t1,
+				}); err != nil {
+					t.Fatalf("AddFullMessage: %v", err)
+				}
+			},
+			wantTimes: []time.Time{t1},
+		},
+		{
+			name: "SetHistory",
+			fn: func(store *JSONLStore, key string) {
+				if err := store.SetHistory(context.Background(), key, []providers.Message{
+					{Role: "user", Content: "msg1", CreatedAt: &t1},
+					{Role: "assistant", Content: "msg2", CreatedAt: &t2},
+				}); err != nil {
+					t.Fatalf("SetHistory: %v", err)
+				}
+			},
+			wantTimes: []time.Time{t1, t2},
+		},
+	}
+
+	for _, op := range ops {
+		t.Run(op.name, func(t *testing.T) {
+			store := newTestStore(t)
+			key := "s1"
+
+			op.fn(store, key)
+
+			history, err := store.GetHistory(context.Background(), key)
+			if err != nil {
+				t.Fatalf("GetHistory: %v", err)
+			}
+			if len(history) != len(op.wantTimes) {
+				t.Fatalf("expected %d messages, got %d", len(op.wantTimes), len(history))
+			}
+			for i, want := range op.wantTimes {
+				if history[i].CreatedAt == nil || !history[i].CreatedAt.Equal(want) {
+					t.Errorf(
+						"message %d CreatedAt = %v, want %v (should preserve caller-provided time)",
+						i, history[i].CreatedAt, want,
+					)
+				}
+			}
+		})
+	}
+}
+
 func BenchmarkAddMessage(b *testing.B) {
 	dir := b.TempDir()
 	store, err := NewJSONLStore(dir)

pkg/migrate/internal/common.go

@@ -1,6 +1,7 @@
 package internal
 
 import (
+	"fmt"
 	"io"
 	"os"
 	"path/filepath"
@@ -149,8 +150,10 @@ func CopyFile(src, dst string) error {
 	if err != nil {
 		return err
 	}
-	defer dstFile.Close()
 
-	_, err = io.Copy(dstFile, srcFile)
-	return err
+	_, copyErr := io.Copy(dstFile, srcFile)
+	if closeErr := dstFile.Close(); closeErr != nil && copyErr == nil {
+		return fmt.Errorf("close destination file %s: %w", dst, closeErr)
+	}
+	return copyErr
 }

pkg/pid/pidfile.go

@@ -64,7 +64,14 @@ func WritePidFile(homePath, host string, port int) (*PidFileData, error) {
 			// pass the isProcessRunning check, blocking new gateway starts.
 			// Treat recorded PID 1 as always stale.
 			if data.PID != 1 && isProcessRunning(data.PID) {
-				return nil, fmt.Errorf("gateway is already running (PID: %d, version: %s)", data.PID, data.Version)
+				// Verify the process is actually a picoclaw instance.
+				// If the PID was reused by an unrelated process
+				// (e.g. systemd-resolved after a kill -9), treat
+				// the PID file as stale and proceed with startup.
+				if isPicoclawProcess(data.PID) {
+					return nil, fmt.Errorf("gateway is already running (PID: %d, version: %s)", data.PID, data.Version)
+				}
+				logger.Warnf("found pid file (PID: %d) but process is not picoclaw", data.PID)
 			}
 			logger.Warnf("not running (PID: %d) so will remove the pid file: %s", data.PID, pidPath)
 		}

pkg/pid/pidfile_unix.go

@@ -4,7 +4,9 @@ package pid
 
 import (
 	"errors"
+	"fmt"
 	"os"
+	"strings"
 	"syscall"
 )
 
@@ -18,7 +20,7 @@ func isProcessRunning(pid int) bool {
 	if err != nil {
 		return false
 	}
-	// Signal(nil) does not kill the process but checks existence on Unix.
+	// Signal(0) does not kill the process but checks existence on Unix.
 	err = p.Signal(syscall.Signal(0))
 	if err == nil {
 		return true
@@ -27,3 +29,16 @@ func isProcessRunning(pid int) bool {
 	// EPERM means the process exists but we are not allowed to signal it.
 	return errors.As(err, &errno) && errno == syscall.EPERM
 }
+
+// isPicoclawProcess reads /proc/<pid>/comm to confirm the process name
+// contains "picoclaw". Returns false when the comm file can be read and
+// the name does not match (e.g., PID was reused by an unrelated process).
+// Returns true if /proc/<pid>/comm is unreadable so the call site falls
+// back to trusting the liveness check alone.
+func isPicoclawProcess(pid int) bool {
+	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/comm", pid))
+	if err != nil {
+		return true // cannot verify — trust liveness check
+	}
+	return strings.Contains(strings.TrimSpace(string(data)), "picoclaw")
+}

pkg/pid/pidfile_windows.go

@@ -3,6 +3,7 @@
 package pid
 
 import (
+	"strings"
 	"syscall"
 	"unsafe"
 )
@@ -12,6 +13,7 @@ var (
 	procOpenProcess                = kernel32.NewProc("OpenProcess")
 	procGetExitCodeProcess         = kernel32.NewProc("GetExitCodeProcess")
 	procCloseHandle                = kernel32.NewProc("CloseHandle")
+	procQueryFullProcessImageNameW = kernel32.NewProc("QueryFullProcessImageNameW")
 	processQueryLimitedInformation = uint32(0x1000)
 	stillActive                    = uint32(259)
 )
@@ -40,3 +42,33 @@ func isProcessRunning(pid int) bool {
 	}
 	return exitCode == stillActive
 }
+
+// isPicoclawProcess uses QueryFullProcessImageNameW to confirm the
+// process image name contains "picoclaw". Returns false when the name
+// clearly does not match. Returns true if the query fails, falling
+// back to trusting the liveness check alone.
+func isPicoclawProcess(pid int) bool {
+	handle, _, _ := procOpenProcess.Call(
+		uintptr(processQueryLimitedInformation),
+		0,
+		uintptr(pid),
+	)
+	if handle == 0 {
+		return true // cannot open — trust liveness check
+	}
+	defer procCloseHandle.Call(handle)
+
+	var buf [260]uint16
+	var size uint32 = 260
+	ret, _, _ := procQueryFullProcessImageNameW.Call(
+		uintptr(handle),
+		0, // WIN32_NAME_FORMAT
+		uintptr(unsafe.Pointer(&buf[0])),
+		uintptr(unsafe.Pointer(&size)),
+	)
+	if ret == 0 {
+		return true // cannot verify — trust liveness check
+	}
+	name := strings.ToLower(syscall.UTF16ToString(buf[:size]))
+	return strings.Contains(name, "picoclaw")
+}