Merge pull request #2 from dj-oyu/test-ahead

Merge upstream + streaming reasoning display

.gitignore

@@ -10,7 +10,7 @@ build/
 *.out
 /picoclaw
 /picoclaw-test
-cmd/picoclaw/workspace
+cmd/**/workspace
 
 # Picoclaw specific
 

.golangci.yaml

@@ -28,9 +28,7 @@ linters:
     - wsl_v5
 
     # TODO: Disabled, because they are failing at the moment, we should fix them and enable (step by step)
-    - bodyclose
     - contextcheck
-    - dogsled
     - embeddedstructfieldcheck
     - errcheck
     - errchkjson
@@ -45,32 +43,24 @@ linters:
     - gocritic
     - gocyclo
     - godox
-    - goprintffuncname
     - gosec
     - ineffassign
     - lll
     - maintidx
-    - misspell
     - mnd
     - modernize
-    - nakedret
     - nestif
     - nilnil
     - paralleltest
     - perfsprint
-    - prealloc
-    - predeclared
     - revive
     - staticcheck
     - tagalign
     - testifylint
     - thelper
     - unparam
-    - unused
     - usestdlibvars
     - usetesting
-    - wastedassign
-    - whitespace
   settings:
     errcheck:
       check-type-assertions: true
@@ -152,6 +142,9 @@ linters:
           - gocognit
           - gocyclo
         path: _test\.go$
+      - linters:
+          - nolintlint
+        path: 'pkg/tools/(i2c\.go|spi\.go)$'
 
 issues:
   max-issues-per-linter: 0

.goreleaser.yaml

@@ -5,7 +5,7 @@ version: 2
 before:
   hooks:
     - go mod tidy
-    - go generate ./cmd/picoclaw
+    - go generate ./cmd/picoclaw/...
 
 builds:
   - id: picoclaw
@@ -15,10 +15,10 @@ builds:
       - stdjson
     ldflags:
       - -s -w
-      - -X main.version={{ .Version }}
-      - -X main.gitCommit={{ .ShortCommit }}
-      - -X main.buildTime={{ .Date }}
-      - -X main.goVersion={{ .Env.GOVERSION }}
+      - -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.version={{ .Version }}
+      - -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.gitCommit={{ .ShortCommit }}
+      - -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.buildTime={{ .Date }}
+      - -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.goVersion={{ .Env.GOVERSION }}
     goos:
       - linux
       - windows
@@ -28,9 +28,10 @@ builds:
       - amd64
       - arm64
       - riscv64
-      - s390x
-      - mips64
+      - loong64
       - arm
+    goarm:
+      - "7"
     main: ./cmd/picoclaw
     ignore:
       - goos: windows
@@ -38,7 +39,9 @@ builds:
 
 dockers_v2:
   - id: picoclaw
-    dockerfile: Dockerfile.goreleaser
+    dockerfile: docker/Dockerfile.goreleaser
+    extra_files:
+      - docker/entrypoint.sh
     ids:
       - picoclaw
     images:
@@ -67,6 +70,25 @@ archives:
       - goos: windows
         formats: [zip]
 
+nfpms:
+  - id: picoclaw
+    package_name: picoclaw
+    file_name_template: >-
+      {{ .PackageName }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "arm64" }}aarch64
+      {{- else if eq .Arch "arm" }}armv{{ .Arm }}
+      {{- else }}{{ .Arch }}{{ end }}
+    vendor: picoclaw
+    homepage: https://github.com/{{ .Env.GITHUB_REPOSITORY_OWNER }}/picoclaw
+    maintainer: picoclaw contributors
+    description: picoclaw - a tool for managing and running tasks
+    license: MIT
+    formats:
+      - rpm
+      - deb
+    bindir: /usr/bin
+
 changelog:
   sort: asc
   filters:

Makefile

@@ -11,10 +11,11 @@ VERSION?=$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 GIT_COMMIT=$(shell git rev-parse --short=8 HEAD 2>/dev/null || echo "dev")
 BUILD_TIME=$(shell date +%FT%T%z)
 GO_VERSION=$(shell $(GO) version | awk '{print $$3}')
-LDFLAGS=-ldflags "-X main.version=$(VERSION) -X main.gitCommit=$(GIT_COMMIT) -X main.buildTime=$(BUILD_TIME) -X main.goVersion=$(GO_VERSION) -s -w"
+INTERNAL=github.com/sipeed/picoclaw/cmd/picoclaw/internal
+LDFLAGS=-ldflags "-X $(INTERNAL).version=$(VERSION) -X $(INTERNAL).gitCommit=$(GIT_COMMIT) -X $(INTERNAL).buildTime=$(BUILD_TIME) -X $(INTERNAL).goVersion=$(GO_VERSION) -s -w"
 
 # Go variables
-GO?=go
+GO?=CGO_ENABLED=0 go
 GOFLAGS?=-v -tags stdjson
 
 # Golangci-lint
@@ -43,6 +44,8 @@ ifeq ($(UNAME_S),Linux)
 		ARCH=amd64
 	else ifeq ($(UNAME_M),aarch64)
 		ARCH=arm64
+	else ifeq ($(UNAME_M),armv81)
+		ARCH=arm64
 	else ifeq ($(UNAME_M),loongarch64)
 		ARCH=loong64
 	else ifeq ($(UNAME_M),riscv64)
@@ -90,14 +93,50 @@ build: generate
 		echo "Install hint skipped: /usr/local/bin command is for Linux/macOS (current: $(PLATFORM))."; \
 	fi
 
+## build-whatsapp-native: Build with WhatsApp native (whatsmeow) support; larger binary
+build-whatsapp-native: generate
+## @echo "Building $(BINARY_NAME) with WhatsApp native for $(PLATFORM)/$(ARCH)..."
+	@echo "Building for multiple platforms..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=amd64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=loong64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-loong64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=riscv64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
+	GOOS=darwin GOARCH=arm64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./$(CMD_DIR)
+	GOOS=windows GOARCH=amd64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./$(CMD_DIR)
+## @$(GO) build $(GOFLAGS) -tags whatsapp_native $(LDFLAGS) -o $(BINARY_PATH) ./$(CMD_DIR)
+	@echo "Build complete"
+##	@ln -sf $(BINARY_NAME)-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/$(BINARY_NAME)
+
+## build-linux-arm: Build for Linux ARMv7 (e.g. Raspberry Pi Zero 2 W 32-bit)
+build-linux-arm: generate
+	@echo "Building for linux/arm (GOARM=7)..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
+	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm"
+
+## build-linux-arm64: Build for Linux ARM64 (e.g. Raspberry Pi Zero 2 W 64-bit)
+build-linux-arm64: generate
+	@echo "Building for linux/arm64..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
+	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64"
+
+## build-pi-zero: Build for Raspberry Pi Zero 2 W (32-bit and 64-bit)
+build-pi-zero: build-linux-arm build-linux-arm64
+	@echo "Pi Zero 2 W builds: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm (32-bit), $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 (64-bit)"
+
 ## build-all: Build picoclaw for all platforms
 build-all: generate
 	@echo "Building for multiple platforms..."
 	@mkdir -p $(BUILD_DIR)
 	GOOS=linux GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
 	GOOS=linux GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
 	GOOS=linux GOARCH=loong64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-loong64 ./$(CMD_DIR)
 	GOOS=linux GOARCH=riscv64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-armv7 ./$(CMD_DIR)
 	GOOS=darwin GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./$(CMD_DIR)
 	GOOS=windows GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./$(CMD_DIR)
 	@echo "All builds complete"
@@ -150,6 +189,10 @@ fmt:
 lint:
 	@$(GOLANGCI_LINT) run
 
+## fix: Fix linting issues
+fix:
+	@$(GOLANGCI_LINT) run --fix
+
 ## deps: Download dependencies
 deps:
 	@$(GO) mod download
@@ -175,7 +218,7 @@ help:
 	@echo "  make [target]"
 	@echo ""
 	@echo "Targets:"
-	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/## /  /'
+	@grep -E '^## ' $(MAKEFILE_LIST) | sort | awk -F': ' '{printf "  %-16s %s\n", substr($$1, 4), $$2}'
 	@echo ""
 	@echo "Examples:"
 	@echo "  make build              # Build for current platform"

README.fr.md

@@ -164,35 +164,43 @@ Vous pouvez également exécuter PicoClaw avec Docker Compose sans rien installe
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Configurez vos clés API
-cp config/config.example.json config/config.json
-vim config/config.json      # Configurez DISCORD_BOT_TOKEN, clés API, etc.
+# 2. Premier lancement — génère docker/data/config.json puis s'arrête
+docker compose -f docker/docker-compose.yml --profile gateway up
+# Le conteneur affiche "First-run setup complete." puis s'arrête.
 
-# 3. Compiler & Démarrer
-docker compose --profile gateway up -d
+# 3. Configurez vos clés API
+vim docker/data/config.json   # Clés API du fournisseur, tokens de bot, etc.
 
-# 4. Voir les logs
-docker compose logs -f picoclaw-gateway
+# 4. Démarrer
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
-# 5. Arrêter
-docker compose --profile gateway down
+> [!TIP]
+> **Utilisateurs Docker** : Par défaut, le Gateway écoute sur `127.0.0.1`, ce qui n'est pas accessible depuis l'hôte. Si vous avez besoin d'accéder aux endpoints de santé ou d'exposer des ports, définissez `PICOCLAW_GATEWAY_HOST=0.0.0.0` dans votre environnement ou mettez à jour `config.json`.
+
+```bash
+# 5. Voir les logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Arrêter
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Mode Agent (exécution unique)
 
 ```bash
 # Poser une question
-docker compose run --rm picoclaw-agent -m "Combien font 2+2 ?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Combien font 2+2 ?"
 
 # Mode interactif
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Recompiler
+### Mettre à jour
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Démarrage Rapide
@@ -217,12 +225,13 @@ picoclaw onboard
       "model_name": "gpt4",
       "model": "openai/gpt-5.2",
       "api_key": "sk-your-openai-key",
+      "request_timeout": 300,
       "api_base": "https://api.openai.com/v1"
     }
   ],
   "agents": {
     "defaults": {
-      "model": "gpt4"
+      "model_name": "gpt4"
     }
   },
   "channels": {
@@ -248,6 +257,9 @@ picoclaw onboard
 }
 ```
 
+> **Nouveau** : Le format de configuration `model_list` permet d'ajouter des fournisseurs sans modifier le code. Voir [Configuration de Modèle](#configuration-de-modèle-model_list) pour plus de détails.
+> `request_timeout` est optionnel et s'exprime en secondes. S'il est omis ou défini à `<= 0`, PicoClaw utilise le délai d'expiration par défaut (120s).
+
 **3. Obtenir des Clés API**
 
 * **Fournisseur LLM** : [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
@@ -975,6 +987,17 @@ Cette conception permet également le **support multi-agent** avec une sélectio
 ```
 > Exécutez `picoclaw auth login --provider anthropic` pour configurer les identifiants OAuth.
 
+**Proxy/API personnalisée**
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
 #### Équilibrage de Charge
 
 Configurez plusieurs points de terminaison pour le même nom de modèle—PicoClaw utilisera automatiquement le round-robin entre eux :

README.ja.md

@@ -126,35 +126,43 @@ Docker Compose を使えば、ローカルにインストールせずに PicoCla
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. API キーを設定
-cp config/config.example.json config/config.json
-vim config/config.json      # DISCORD_BOT_TOKEN, プロバイダーの API キーを設定
+# 2. 初回起動 — docker/data/config.json を自動生成して終了
+docker compose -f docker/docker-compose.yml --profile gateway up
+# コンテナが "First-run setup complete." を表示して停止します。
 
-# 3. ビルドと起動
-docker compose --profile gateway up -d
+# 3. API キーを設定
+vim docker/data/config.json   # プロバイダー API キー、Bot トークンなどを設定
 
-# 4. ログ確認
-docker compose logs -f picoclaw-gateway
+# 4. 起動
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
-# 5. 停止
-docker compose --profile gateway down
+> [!TIP]
+> **Docker ユーザー**: デフォルトでは、Gateway は `127.0.0.1` でリッスンしており、ホストからアクセスできません。ヘルスチェックエンドポイントにアクセスしたり、ポートを公開したりする必要がある場合は、環境変数で `PICOCLAW_GATEWAY_HOST=0.0.0.0` を設定するか、`config.json` を更新してください。
+
+```bash
+# 5. ログ確認
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. 停止
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Agent モード（ワンショット）
 
 ```bash
 # 質問を投げる
-docker compose run --rm picoclaw-agent -m "What is 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
 
 # インタラクティブモード
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### リビルド
+### アップデート
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 クイックスタート（ネイティブ）
@@ -179,12 +187,13 @@ picoclaw onboard
       "model_name": "gpt4",
       "model": "openai/gpt-5.2",
       "api_key": "sk-your-openai-key",
+      "request_timeout": 300,
       "api_base": "https://api.openai.com/v1"
     }
   ],
   "agents": {
     "defaults": {
-      "model": "gpt4"
+      "model_name": "gpt4"
     }
   },
   "channels": {
@@ -217,6 +226,9 @@ picoclaw onboard
 }
 ```
 
+> **新機能**: `model_list` 形式により、プロバイダーをコード変更なしで追加できます。詳細は [モデル設定](#モデル設定-model_list) を参照してください。
+> `request_timeout` は任意の秒単位設定です。省略または `<= 0` の場合、PicoClaw はデフォルトのタイムアウト（120秒）を使用します。
+
 **3. API キーの取得**
 
 - **LLM プロバイダー**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
@@ -949,6 +961,17 @@ HEARTBEAT_OK 応答         ユーザーが直接結果を受け取る
 ```
 > OAuth認証を設定するには、`picoclaw auth login --provider anthropic` を実行してください。
 
+**カスタムプロキシ/API**
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
 #### ロードバランシング
 
 同じモデル名で複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンで分散します：

README.md

@@ -12,6 +12,9 @@
     <br>
     <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
     <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <br>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
   </p>
 
 [中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **English**
@@ -151,10 +154,15 @@ make build
 # Build for multiple platforms
 make build-all
 
+# Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+make build-pi-zero
+
 # Build And Install
 make install
 ```
 
+**Raspberry Pi Zero 2 W:** Use the binary that matches your OS: 32-bit Raspberry Pi OS → `make build-linux-arm` (output: `build/picoclaw-linux-arm`); 64-bit → `make build-linux-arm64` (output: `build/picoclaw-linux-arm64`). Or run `make build-pi-zero` to build both.
+
 ## 🐳 Docker Compose
 
 You can also run PicoClaw using Docker Compose without installing anything locally.
@@ -164,35 +172,43 @@ You can also run PicoClaw using Docker Compose without installing anything local
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Set your API keys
-cp config/config.example.json config/config.json
-vim config/config.json      # Set DISCORD_BOT_TOKEN, API keys, etc.
+# 2. First run — auto-generates docker/data/config.json then exits
+docker compose -f docker/docker-compose.yml --profile gateway up
+# The container prints "First-run setup complete." and stops.
 
-# 3. Build & Start
-docker compose --profile gateway up -d
+# 3. Set your API keys
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
 
-# 4. Check logs
-docker compose logs -f picoclaw-gateway
+# 4. Start
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
-# 5. Stop
-docker compose --profile gateway down
+> [!TIP]
+> **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`.
+
+```bash
+# 5. Check logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Stop
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Agent Mode (One-shot)
 
 ```bash
 # Ask a question
-docker compose run --rm picoclaw-agent -m "What is 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
 
 # Interactive mode
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Rebuild
+### Update
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Quick Start
@@ -215,7 +231,7 @@ picoclaw onboard
   "agents": {
     "defaults": {
       "workspace": "~/.picoclaw/workspace",
-      "model": "gpt4",
+      "model_name": "gpt4",
       "max_tokens": 8192,
       "temperature": 0.7,
       "max_tool_iterations": 20
@@ -225,7 +241,8 @@ picoclaw onboard
     {
       "model_name": "gpt4",
       "model": "openai/gpt-5.2",
-      "api_key": "your-api-key"
+      "api_key": "your-api-key",
+      "request_timeout": 300
     },
     {
       "model_name": "claude-sonnet-4.6",
@@ -255,6 +272,7 @@ picoclaw onboard
 ```
 
 > **New**: The `model_list` configuration format allows zero-code provider addition. See [Model Configuration](#model-configuration-model_list) for details.
+> `request_timeout` is optional and uses seconds. If omitted or set to `<= 0`, PicoClaw uses the default timeout (120s).
 
 **3. Get API Keys**
 
@@ -275,12 +293,13 @@ That's it! You have a working AI assistant in 2 minutes.
 
 ## 💬 Chat Apps
 
-Talk to your picoclaw through Telegram, Discord, DingTalk, LINE, or WeCom
+Talk to your picoclaw through Telegram, Discord, WhatsApp, DingTalk, LINE, or WeCom
 
 | Channel      | Setup                              |
 | ------------ | ---------------------------------- |
 | **Telegram** | Easy (just a token)                |
 | **Discord**  | Easy (bot token + intents)         |
+| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
 | **QQ**       | Easy (AppID + AppSecret)           |
 | **DingTalk** | Medium (app credentials)           |
 | **LINE**     | Medium (credentials + webhook URL) |
@@ -434,6 +453,33 @@ picoclaw gateway
 
 </details>
 
+<details>
+<summary><b>WhatsApp</b> (native via whatsmeow)</summary>
+
+PicoClaw can connect to WhatsApp in two ways:
+
+- **Native (recommended):** In-process using [whatsmeow](https://github.com/tulir/whatsmeow). No separate bridge. Set `"use_native": true` and leave `bridge_url` empty. On first run, scan the QR code with WhatsApp (Linked Devices). Session is stored under your workspace (e.g. `workspace/whatsapp/`). The native channel is **optional** to keep the default binary small; build with `-tags whatsapp_native` (e.g. `make build-whatsapp-native` or `go build -tags whatsapp_native ./cmd/...`).
+- **Bridge:** Connect to an external WebSocket bridge. Set `bridge_url` (e.g. `ws://localhost:3001`) and keep `use_native` false.
+
+**Configure (native)**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+If `session_store_path` is empty, the session is stored in `&lt;workspace&gt;/whatsapp/`. Run `picoclaw gateway`; on first run, scan the QR code printed in the terminal with WhatsApp → Linked Devices.
+
+</details>
+
 <details>
 <summary><b>QQ</b></summary>
 
@@ -971,7 +1017,8 @@ This design also enables **multi-agent support** with flexible provider selectio
   "model_name": "my-custom-model",
   "model": "openai/custom-model",
   "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-..."
+  "api_key": "sk-...",
+  "request_timeout": 300
 }
 ```
 
@@ -1149,7 +1196,11 @@ picoclaw agent -m "Hello"
       "allow_from": [""]
     },
     "whatsapp": {
-      "enabled": false
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
     },
     "feishu": {
       "enabled": false,
@@ -1253,7 +1304,7 @@ discord: <https://discord.gg/V4sAZ9XWpN>
 
 ## 🐛 Troubleshooting
 
-### Web search says "API 配置问题"
+### Web search says "API key configuration issue"
 
 This is normal if you haven't configured a search API key yet. PicoClaw will provide helpful links for manual searching.
 

README.pt-br.md

@@ -165,35 +165,43 @@ Você tambêm pode rodar o PicoClaw usando Docker Compose sem instalar nada loca
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Configure suas API keys
-cp config/config.example.json config/config.json
-vim config/config.json      # Configure DISCORD_BOT_TOKEN, API keys, etc.
+# 2. Primeiro uso — gera docker/data/config.json automaticamente e para
+docker compose -f docker/docker-compose.yml --profile gateway up
+# O contêiner exibe "First-run setup complete." e para.
 
-# 3. Build & Iniciar
-docker compose --profile gateway up -d
+# 3. Configure suas API keys
+vim docker/data/config.json   # Chaves de API do provedor, tokens de bot, etc.
 
-# 4. Ver logs
-docker compose logs -f picoclaw-gateway
+# 4. Iniciar
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
-# 5. Parar
-docker compose --profile gateway down
+> [!TIP]
+> **Usuários Docker**: Por padrão, o Gateway ouve em `127.0.0.1`, o que não é acessível a partir do host. Se você precisar acessar os endpoints de integridade ou expor portas, defina `PICOCLAW_GATEWAY_HOST=0.0.0.0` em seu ambiente ou atualize o `config.json`.
+
+```bash
+# 5. Ver logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Parar
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Modo Agente (Execução única)
 
 ```bash
 # Fazer uma pergunta
-docker compose run --rm picoclaw-agent -m "Quanto e 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Quanto e 2+2?"
 
 # Modo interativo
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Rebuild
+### Atualizar
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Início Rápido
@@ -218,12 +226,13 @@ picoclaw onboard
       "model_name": "gpt4",
       "model": "openai/gpt-5.2",
       "api_key": "sk-your-openai-key",
+      "request_timeout": 300,
       "api_base": "https://api.openai.com/v1"
     }
   ],
   "agents": {
     "defaults": {
-      "model": "gpt4"
+      "model_name": "gpt4"
     }
   },
   "tools": {
@@ -242,6 +251,9 @@ picoclaw onboard
 }
 ```
 
+> **Novo**: O formato de configuração `model_list` permite adicionar provedores sem alterar código. Veja [Configuração de Modelo](#configuração-de-modelo-model_list) para detalhes.
+> `request_timeout` é opcional e usa segundos. Se omitido ou definido como `<= 0`, o PicoClaw usa o timeout padrão (120s).
+
 **3. Obter API Keys**
 
 * **Provedor de LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
@@ -969,6 +981,17 @@ Este design também possibilita o **suporte multi-agent** com seleção flexíve
 ```
 > Execute `picoclaw auth login --provider anthropic` para configurar credenciais OAuth.
 
+**Proxy/API personalizada**
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
 #### Balanceamento de Carga
 
 Configure vários endpoints para o mesmo nome de modelo—PicoClaw fará round-robin automaticamente entre eles:

README.vi.md

@@ -145,35 +145,43 @@ Bạn cũng có thể chạy PicoClaw bằng Docker Compose mà không cần cà
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Thiết lập API Key
-cp config/config.example.json config/config.json
-vim config/config.json      # Thiết lập DISCORD_BOT_TOKEN, API keys, v.v.
+# 2. Lần chạy đầu tiên — tự tạo docker/data/config.json rồi dừng lại
+docker compose -f docker/docker-compose.yml --profile gateway up
+# Container hiển thị "First-run setup complete." rồi tự dừng.
 
-# 3. Build & Khởi động
-docker compose --profile gateway up -d
+# 3. Thiết lập API Key
+vim docker/data/config.json   # API key của provider, bot token, v.v.
 
-# 4. Xem logs
-docker compose logs -f picoclaw-gateway
+# 4. Khởi động
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
-# 5. Dừng
-docker compose --profile gateway down
+> [!TIP]
+> **Người dùng Docker**: Theo mặc định, Gateway lắng nghe trên `127.0.0.1`, không thể truy cập từ máy chủ. Nếu bạn cần truy cập các endpoint kiểm tra sức khỏe hoặc mở cổng, hãy đặt `PICOCLAW_GATEWAY_HOST=0.0.0.0` trong môi trường của bạn hoặc cập nhật `config.json`.
+
+```bash
+# 5. Xem logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Dừng
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Chế độ Agent (chạy một lần)
 
 ```bash
 # Đặt câu hỏi
-docker compose run --rm picoclaw-agent -m "2+2 bằng mấy?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 bằng mấy?"
 
 # Chế độ tương tác
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Build lại
+### Cập nhật
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Bắt đầu nhanh
@@ -198,12 +206,13 @@ picoclaw onboard
       "model_name": "gpt4",
       "model": "openai/gpt-5.2",
       "api_key": "sk-your-openai-key",
+      "request_timeout": 300,
       "api_base": "https://api.openai.com/v1"
     }
   ],
   "agents": {
     "defaults": {
-      "model": "gpt4"
+      "model_name": "gpt4"
     }
   },
   "channels": {
@@ -216,6 +225,9 @@ picoclaw onboard
 }
 ```
 
+> **Mới**: Định dạng cấu hình `model_list` cho phép thêm nhà cung cấp mà không cần thay đổi mã nguồn. Xem [Cấu hình Mô hình](#cấu-hình-mô-hình-model_list) để biết chi tiết.
+> `request_timeout` là tùy chọn và dùng đơn vị giây. Nếu bỏ qua hoặc đặt `<= 0`, PicoClaw sẽ dùng timeout mặc định (120s).
+
 **3. Lấy API Key**
 
 * **Nhà cung cấp LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
@@ -940,6 +952,17 @@ Thiết kế này cũng cho phép **hỗ trợ đa tác nhân** với lựa ch
 ```
 > Chạy `picoclaw auth login --provider anthropic` để thiết lập thông tin xác thực OAuth.
 
+**Proxy/API tùy chỉnh**
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
 #### Cân bằng Tải tải
 
 Định cấu hình nhiều endpoint cho cùng một tên mô hình—PicoClaw sẽ tự động phân phối round-robin giữa chúng:

README.zh.md

@@ -166,38 +166,43 @@ make install
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. 设置 API Key
-cp config/config.example.json config/config.json
-vim config/config.json      # 设置 DISCORD_BOT_TOKEN, API keys 等
+# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
+docker compose -f docker/docker-compose.yml --profile gateway up
+# 容器打印 "First-run setup complete." 后自动停止
 
-# 3. 构建并启动
-docker compose --profile gateway up -d
+# 3. 填写 API Key 等配置
+vim docker/data/config.json   # 设置 provider API key、Bot Token 等
 
-# 4. 查看日志
-docker compose logs -f picoclaw-gateway
+# 4. 正式启动
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
-# 5. 停止
-docker compose --profile gateway down
+> [!TIP]
+> **Docker 用户**: 默认情况下, Gateway 监听 `127.0.0.1`，该端口不会暴露到容器外。如果需要通过端口映射访问健康检查接口，请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
 
+```bash
+# 5. 查看日志
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. 停止
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Agent 模式 (一次性运行)
 
 ```bash
 # 提问
-docker compose run --rm picoclaw-agent -m "2+2 等于几？"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
 
 # 交互模式
-docker compose run --rm picoclaw-agent
-
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### 重新构建
+### 更新镜像
 
 ```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
-
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 快速开始
@@ -221,7 +226,7 @@ picoclaw onboard
   "agents": {
     "defaults": {
       "workspace": "~/.picoclaw/workspace",
-      "model": "gpt4",
+      "model_name": "gpt4",
       "max_tokens": 8192,
       "temperature": 0.7,
       "max_tool_iterations": 20
@@ -231,7 +236,8 @@ picoclaw onboard
     {
       "model_name": "gpt4",
       "model": "openai/gpt-5.2",
-      "api_key": "your-api-key"
+      "api_key": "your-api-key",
+      "request_timeout": 300
     },
     {
       "model_name": "claude-sonnet-4.6",
@@ -260,6 +266,7 @@ picoclaw onboard
 ```
 
 > **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](#模型配置-model_list)章节。
+> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。
 
 **3. 获取 API Key**
 
@@ -549,7 +556,8 @@ Agent 读取 HEARTBEAT.md
   "model_name": "my-custom-model",
   "model": "openai/custom-model",
   "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-..."
+  "api_key": "sk-...",
+  "request_timeout": 300
 }
 ```
 

cmd/picoclaw/cmd_cron.go

@@ -1,227 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
-
-import (
-	"fmt"
-	"os"
-	"path/filepath"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/cron"
-)
-
-func cronCmd() {
-	if len(os.Args) < 3 {
-		cronHelp()
-		return
-	}
-
-	subcommand := os.Args[2]
-
-	// Load config to get workspace path
-	cfg, err := loadConfig()
-	if err != nil {
-		fmt.Printf("Error loading config: %v\n", err)
-		return
-	}
-
-	cronStorePath := filepath.Join(cfg.WorkspacePath(), "cron", "jobs.json")
-
-	switch subcommand {
-	case "list":
-		cronListCmd(cronStorePath)
-	case "add":
-		cronAddCmd(cronStorePath)
-	case "remove":
-		if len(os.Args) < 4 {
-			fmt.Println("Usage: picoclaw cron remove <job_id>")
-			return
-		}
-		cronRemoveCmd(cronStorePath, os.Args[3])
-	case "enable":
-		cronEnableCmd(cronStorePath, false)
-	case "disable":
-		cronEnableCmd(cronStorePath, true)
-	default:
-		fmt.Printf("Unknown cron command: %s\n", subcommand)
-		cronHelp()
-	}
-}
-
-func cronHelp() {
-	fmt.Println("\nCron commands:")
-	fmt.Println("  list              List all scheduled jobs")
-	fmt.Println("  add              Add a new scheduled job")
-	fmt.Println("  remove <id>       Remove a job by ID")
-	fmt.Println("  enable <id>      Enable a job")
-	fmt.Println("  disable <id>     Disable a job")
-	fmt.Println()
-	fmt.Println("Add options:")
-	fmt.Println("  -n, --name       Job name")
-	fmt.Println("  -m, --message    Message for agent")
-	fmt.Println("  -e, --every      Run every N seconds")
-	fmt.Println("  -c, --cron       Cron expression (e.g. '0 9 * * *')")
-	fmt.Println("  -d, --deliver     Deliver response to channel")
-	fmt.Println("  --to             Recipient for delivery")
-	fmt.Println("  --channel        Channel for delivery")
-}
-
-func cronListCmd(storePath string) {
-	cs := cron.NewCronService(storePath, nil)
-	jobs := cs.ListJobs(true) // Show all jobs, including disabled
-
-	if len(jobs) == 0 {
-		fmt.Println("No scheduled jobs.")
-		return
-	}
-
-	fmt.Println("\nScheduled Jobs:")
-	fmt.Println("----------------")
-	for _, job := range jobs {
-		var schedule string
-		if job.Schedule.Kind == "every" && job.Schedule.EveryMS != nil {
-			schedule = fmt.Sprintf("every %ds", *job.Schedule.EveryMS/1000)
-		} else if job.Schedule.Kind == "cron" {
-			schedule = job.Schedule.Expr
-		} else {
-			schedule = "one-time"
-		}
-
-		nextRun := "scheduled"
-		if job.State.NextRunAtMS != nil {
-			nextTime := time.UnixMilli(*job.State.NextRunAtMS)
-			nextRun = nextTime.Format("2006-01-02 15:04")
-		}
-
-		status := "enabled"
-		if !job.Enabled {
-			status = "disabled"
-		}
-
-		fmt.Printf("  %s (%s)\n", job.Name, job.ID)
-		fmt.Printf("    Schedule: %s\n", schedule)
-		fmt.Printf("    Status: %s\n", status)
-		fmt.Printf("    Next run: %s\n", nextRun)
-	}
-}
-
-func cronAddCmd(storePath string) {
-	name := ""
-	message := ""
-	var everySec *int64
-	cronExpr := ""
-	deliver := false
-	channel := ""
-	to := ""
-
-	args := os.Args[3:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "-n", "--name":
-			if i+1 < len(args) {
-				name = args[i+1]
-				i++
-			}
-		case "-m", "--message":
-			if i+1 < len(args) {
-				message = args[i+1]
-				i++
-			}
-		case "-e", "--every":
-			if i+1 < len(args) {
-				var sec int64
-				fmt.Sscanf(args[i+1], "%d", &sec)
-				everySec = &sec
-				i++
-			}
-		case "-c", "--cron":
-			if i+1 < len(args) {
-				cronExpr = args[i+1]
-				i++
-			}
-		case "-d", "--deliver":
-			deliver = true
-		case "--to":
-			if i+1 < len(args) {
-				to = args[i+1]
-				i++
-			}
-		case "--channel":
-			if i+1 < len(args) {
-				channel = args[i+1]
-				i++
-			}
-		}
-	}
-
-	if name == "" {
-		fmt.Println("Error: --name is required")
-		return
-	}
-
-	if message == "" {
-		fmt.Println("Error: --message is required")
-		return
-	}
-
-	if everySec == nil && cronExpr == "" {
-		fmt.Println("Error: Either --every or --cron must be specified")
-		return
-	}
-
-	var schedule cron.CronSchedule
-	if everySec != nil {
-		everyMS := *everySec * 1000
-		schedule = cron.CronSchedule{
-			Kind:    "every",
-			EveryMS: &everyMS,
-		}
-	} else {
-		schedule = cron.CronSchedule{
-			Kind: "cron",
-			Expr: cronExpr,
-		}
-	}
-
-	cs := cron.NewCronService(storePath, nil)
-	job, err := cs.AddJob(name, schedule, message, deliver, channel, to)
-	if err != nil {
-		fmt.Printf("Error adding job: %v\n", err)
-		return
-	}
-
-	fmt.Printf("✓ Added job '%s' (%s)\n", job.Name, job.ID)
-}
-
-func cronRemoveCmd(storePath, jobID string) {
-	cs := cron.NewCronService(storePath, nil)
-	if cs.RemoveJob(jobID) {
-		fmt.Printf("✓ Removed job %s\n", jobID)
-	} else {
-		fmt.Printf("✗ Job %s not found\n", jobID)
-	}
-}
-
-func cronEnableCmd(storePath string, disable bool) {
-	if len(os.Args) < 4 {
-		fmt.Println("Usage: picoclaw cron enable/disable <job_id>")
-		return
-	}
-
-	jobID := os.Args[3]
-	cs := cron.NewCronService(storePath, nil)
-	enabled := !disable
-
-	job := cs.EnableJob(jobID, enabled)
-	if job != nil {
-		status := "enabled"
-		if disable {
-			status = "disabled"
-		}
-		fmt.Printf("✓ Job '%s' %s\n", job.Name, status)
-	} else {
-		fmt.Printf("✗ Job %s not found\n", jobID)
-	}
-}

cmd/picoclaw/cmd_migrate.go

@@ -1,81 +0,0 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/sipeed/picoclaw/pkg/migrate"
-)
-
-func migrateCmd() {
-	if len(os.Args) > 2 && (os.Args[2] == "--help" || os.Args[2] == "-h") {
-		migrateHelp()
-		return
-	}
-
-	opts := migrate.Options{}
-
-	args := os.Args[2:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--dry-run":
-			opts.DryRun = true
-		case "--config-only":
-			opts.ConfigOnly = true
-		case "--workspace-only":
-			opts.WorkspaceOnly = true
-		case "--force":
-			opts.Force = true
-		case "--refresh":
-			opts.Refresh = true
-		case "--openclaw-home":
-			if i+1 < len(args) {
-				opts.OpenClawHome = args[i+1]
-				i++
-			}
-		case "--picoclaw-home":
-			if i+1 < len(args) {
-				opts.PicoClawHome = args[i+1]
-				i++
-			}
-		default:
-			fmt.Printf("Unknown flag: %s\n", args[i])
-			migrateHelp()
-			os.Exit(1)
-		}
-	}
-
-	result, err := migrate.Run(opts)
-	if err != nil {
-		fmt.Printf("Error: %v\n", err)
-		os.Exit(1)
-	}
-
-	if !opts.DryRun {
-		migrate.PrintSummary(result)
-	}
-}
-
-func migrateHelp() {
-	fmt.Println("\nMigrate from OpenClaw to PicoClaw")
-	fmt.Println()
-	fmt.Println("Usage: picoclaw migrate [options]")
-	fmt.Println()
-	fmt.Println("Options:")
-	fmt.Println("  --dry-run          Show what would be migrated without making changes")
-	fmt.Println("  --refresh          Re-sync workspace files from OpenClaw (repeatable)")
-	fmt.Println("  --config-only      Only migrate config, skip workspace files")
-	fmt.Println("  --workspace-only   Only migrate workspace files, skip config")
-	fmt.Println("  --force            Skip confirmation prompts")
-	fmt.Println("  --openclaw-home    Override OpenClaw home directory (default: ~/.openclaw)")
-	fmt.Println("  --picoclaw-home    Override PicoClaw home directory (default: ~/.picoclaw)")
-	fmt.Println()
-	fmt.Println("Examples:")
-	fmt.Println("  picoclaw migrate              Detect and migrate from OpenClaw")
-	fmt.Println("  picoclaw migrate --dry-run    Show what would be migrated")
-	fmt.Println("  picoclaw migrate --refresh    Re-sync workspace files")
-	fmt.Println("  picoclaw migrate --force      Migrate without confirmation")
-}

cmd/picoclaw/internal/agent/command.go

@@ -0,0 +1,32 @@
+package agent
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewAgentCommand() *cobra.Command {
+	var (
+		message              string
+		sessionKey           string
+		model                string
+		debug                bool
+		orchestrationEnabled bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "agent",
+		Short: "Interact with the agent directly",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return agentCmd(message, sessionKey, model, debug, orchestrationEnabled)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&debug, "debug", "d", false, "Enable debug logging")
+	cmd.Flags().StringVarP(&message, "message", "m", "", "Send a single message (non-interactive mode)")
+	cmd.Flags().StringVarP(&sessionKey, "session", "s", "cli:default", "Session key")
+	cmd.Flags().StringVarP(&model, "model", "", "", "Model to use")
+	cmd.Flags().BoolVar(&orchestrationEnabled, "orchestration", false, "Enable orchestration mode")
+
+	return cmd
+}

cmd/picoclaw/internal/agent/command_test.go

@@ -0,0 +1,33 @@
+package agent
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewAgentCommand(t *testing.T) {
+	cmd := NewAgentCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "agent", cmd.Use)
+	assert.Equal(t, "Interact with the agent directly", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("debug"))
+	assert.NotNil(t, cmd.Flags().Lookup("message"))
+	assert.NotNil(t, cmd.Flags().Lookup("session"))
+	assert.NotNil(t, cmd.Flags().Lookup("model"))
+}

cmd/picoclaw/internal/agent/helpers.go

@@ -1,7 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package agent
 
 import (
 	"bufio"
@@ -14,52 +11,30 @@ import (
 
 	"github.com/chzyer/readline"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/agent"
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
-func agentCmd() {
-	message := ""
-	sessionKey := "cli:default"
-	modelOverride := ""
-	orchestrationEnabled := false
+func agentCmd(message, sessionKey, model string, debug, orchestrationEnabled bool) error {
+	if sessionKey == "" {
+		sessionKey = "cli:default"
+	}
 
-	args := os.Args[2:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--debug", "-d":
+	if debug {
 		logger.SetLevel(logger.DEBUG)
 		fmt.Println("🔍 Debug mode enabled")
-		case "-m", "--message":
-			if i+1 < len(args) {
-				message = args[i+1]
-				i++
-			}
-		case "-s", "--session":
-			if i+1 < len(args) {
-				sessionKey = args[i+1]
-				i++
-			}
-		case "--model", "-model":
-			if i+1 < len(args) {
-				modelOverride = args[i+1]
-				i++
-			}
-		case "--orchestration":
-			orchestrationEnabled = true
-		}
 	}
 
-	cfg, err := loadConfig()
+	cfg, err := internal.LoadConfig()
 	if err != nil {
-		fmt.Printf("Error loading config: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("error loading config: %w", err)
 	}
 
-	if modelOverride != "" {
-		cfg.Agents.Defaults.Model = modelOverride
+	if model != "" {
+		cfg.Agents.Defaults.ModelName = model
 	}
 
 	if orchestrationEnabled {
@@ -68,15 +43,16 @@ func agentCmd() {
 
 	provider, modelID, err := providers.CreateProvider(cfg)
 	if err != nil {
-		fmt.Printf("Error creating provider: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("error creating provider: %w", err)
 	}
+
 	// Use the resolved model ID from provider creation
 	if modelID != "" {
-		cfg.Agents.Defaults.Model = modelID
+		cfg.Agents.Defaults.ModelName = modelID
 	}
 
 	msgBus := bus.NewMessageBus()
+	defer msgBus.Close()
 	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
 
 	// Print agent startup info (only for interactive mode)
@@ -92,18 +68,20 @@ func agentCmd() {
 		ctx := context.Background()
 		response, err := agentLoop.ProcessDirect(ctx, message, sessionKey)
 		if err != nil {
-			fmt.Printf("Error: %v\n", err)
-			os.Exit(1)
+			return fmt.Errorf("error processing message: %w", err)
 		}
-		fmt.Printf("\n%s %s\n", logo, response)
-	} else {
-		fmt.Printf("%s Interactive mode (Ctrl+C to exit)\n\n", logo)
+		fmt.Printf("\n%s %s\n", internal.Logo, response)
+		return nil
+	}
+
+	fmt.Printf("%s Interactive mode (Ctrl+C to exit)\n\n", internal.Logo)
 	interactiveMode(agentLoop, sessionKey)
-	}
+
+	return nil
 }
 
 func interactiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
-	prompt := fmt.Sprintf("%s You: ", logo)
+	prompt := fmt.Sprintf("%s You: ", internal.Logo)
 
 	rl, err := readline.NewEx(&readline.Config{
 		Prompt:          prompt,
@@ -148,14 +126,14 @@ func interactiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
 			continue
 		}
 
-		fmt.Printf("\n%s %s\n\n", logo, response)
+		fmt.Printf("\n%s %s\n\n", internal.Logo, response)
 	}
 }
 
 func simpleInteractiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
 	reader := bufio.NewReader(os.Stdin)
 	for {
-		fmt.Printf("%s You: ", logo)
+		fmt.Print(fmt.Sprintf("%s You: ", internal.Logo))
 		line, err := reader.ReadString('\n')
 		if err != nil {
 			if err == io.EOF {
@@ -183,6 +161,6 @@ func simpleInteractiveMode(agentLoop *agent.AgentLoop, sessionKey string) {
 			continue
 		}
 
-		fmt.Printf("\n%s %s\n\n", logo, response)
+		fmt.Printf("\n%s %s\n\n", internal.Logo, response)
 	}
 }

cmd/picoclaw/internal/auth/command.go

@@ -0,0 +1,22 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func NewAuthCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "auth",
+		Short: "Manage authentication (login, logout, status)",
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+	}
+
+	cmd.AddCommand(
+		newLoginCommand(),
+		newLogoutCommand(),
+		newStatusCommand(),
+		newModelsCommand(),
+	)
+
+	return cmd
+}

cmd/picoclaw/internal/auth/command_test.go

@@ -0,0 +1,55 @@
+package auth
+
+import (
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewAuthCommand(t *testing.T) {
+	cmd := NewAuthCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "auth", cmd.Use)
+	assert.Equal(t, "Manage authentication (login, logout, status)", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.False(t, cmd.HasFlags())
+	assert.True(t, cmd.HasSubCommands())
+
+	allowedCommands := []string{
+		"login",
+		"logout",
+		"status",
+		"models",
+	}
+
+	subcommands := cmd.Commands()
+	assert.Len(t, subcommands, len(allowedCommands))
+
+	for _, subcmd := range subcommands {
+		found := slices.Contains(allowedCommands, subcmd.Name())
+		assert.True(t, found, "unexpected subcommand %q", subcmd.Name())
+
+		assert.Len(t, subcmd.Aliases, 0)
+		assert.False(t, subcmd.Hidden)
+
+		assert.False(t, subcmd.HasSubCommands())
+
+		assert.Nil(t, subcmd.Run)
+		assert.NotNil(t, subcmd.RunE)
+
+		assert.Nil(t, subcmd.PersistentPreRun)
+		assert.Nil(t, subcmd.PersistentPostRun)
+	}
+}

cmd/picoclaw/internal/auth/helpers.go

@@ -1,7 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package auth
 
 import (
 	"encoding/json"
@@ -12,92 +9,28 @@ import (
 	"strings"
 	"time"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/auth"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
-const supportedProvidersMsg = "Supported providers: openai, anthropic, google-antigravity"
-
-func authCmd() {
-	if len(os.Args) < 3 {
-		authHelp()
-		return
-	}
-
-	switch os.Args[2] {
-	case "login":
-		authLoginCmd()
-	case "logout":
-		authLogoutCmd()
-	case "status":
-		authStatusCmd()
-	case "models":
-		authModelsCmd()
-	default:
-		fmt.Printf("Unknown auth command: %s\n", os.Args[2])
-		authHelp()
-	}
-}
-
-func authHelp() {
-	fmt.Println("\nAuth commands:")
-	fmt.Println("  login       Login via OAuth or paste token")
-	fmt.Println("  logout      Remove stored credentials")
-	fmt.Println("  status      Show current auth status")
-	fmt.Println("  models      List available Antigravity models")
-	fmt.Println()
-	fmt.Println("Login options:")
-	fmt.Println("  --provider <name>    Provider to login with (openai, anthropic, google-antigravity)")
-	fmt.Println("  --device-code        Use device code flow (for headless environments)")
-	fmt.Println()
-	fmt.Println("Examples:")
-	fmt.Println("  picoclaw auth login --provider openai")
-	fmt.Println("  picoclaw auth login --provider openai --device-code")
-	fmt.Println("  picoclaw auth login --provider anthropic")
-	fmt.Println("  picoclaw auth login --provider google-antigravity")
-	fmt.Println("  picoclaw auth models")
-	fmt.Println("  picoclaw auth logout --provider openai")
-	fmt.Println("  picoclaw auth status")
-}
-
-func authLoginCmd() {
-	provider := ""
-	useDeviceCode := false
-
-	args := os.Args[3:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--provider", "-p":
-			if i+1 < len(args) {
-				provider = args[i+1]
-				i++
-			}
-		case "--device-code":
-			useDeviceCode = true
-		}
-	}
-
-	if provider == "" {
-		fmt.Println("Error: --provider is required")
-		fmt.Println(supportedProvidersMsg)
-		return
-	}
+const supportedProvidersMsg = "supported providers: openai, anthropic, google-antigravity"
 
+func authLoginCmd(provider string, useDeviceCode bool) error {
 	switch provider {
 	case "openai":
-		authLoginOpenAI(useDeviceCode)
+		return authLoginOpenAI(useDeviceCode)
 	case "anthropic":
-		authLoginPasteToken(provider)
+		return authLoginPasteToken(provider)
 	case "google-antigravity", "antigravity":
-		authLoginGoogleAntigravity()
+		return authLoginGoogleAntigravity()
 	default:
-		fmt.Printf("Unsupported provider: %s\n", provider)
-		fmt.Println(supportedProvidersMsg)
+		return fmt.Errorf("unsupported provider: %s (%s)", provider, supportedProvidersMsg)
 	}
 }
 
-func authLoginOpenAI(useDeviceCode bool) {
+func authLoginOpenAI(useDeviceCode bool) error {
 	cfg := auth.OpenAIOAuthConfig()
 
 	var cred *auth.AuthCredential
@@ -110,16 +43,14 @@ func authLoginOpenAI(useDeviceCode bool) {
 	}
 
 	if err != nil {
-		fmt.Printf("Login failed: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("login failed: %w", err)
 	}
 
 	if err = auth.SetCredential("openai", cred); err != nil {
-		fmt.Printf("Failed to save credentials: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("failed to save credentials: %w", err)
 	}
 
-	appCfg, err := loadConfig()
+	appCfg, err := internal.LoadConfig()
 	if err == nil {
 		// Update Providers (legacy format)
 		appCfg.Providers.OpenAI.AuthMethod = "oauth"
@@ -144,10 +75,10 @@ func authLoginOpenAI(useDeviceCode bool) {
 		}
 
 		// Update default model to use OpenAI
-		appCfg.Agents.Defaults.Model = "gpt-5.2"
+		appCfg.Agents.Defaults.ModelName = "gpt-5.2"
 
-		if err := config.SaveConfig(getConfigPath(), appCfg); err != nil {
-			fmt.Printf("Warning: could not update config: %v\n", err)
+		if err = config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
+			return fmt.Errorf("could not update config: %w", err)
 		}
 	}
 
@@ -156,15 +87,16 @@ func authLoginOpenAI(useDeviceCode bool) {
 		fmt.Printf("Account: %s\n", cred.AccountID)
 	}
 	fmt.Println("Default model set to: gpt-5.2")
+
+	return nil
 }
 
-func authLoginGoogleAntigravity() {
+func authLoginGoogleAntigravity() error {
 	cfg := auth.GoogleAntigravityOAuthConfig()
 
 	cred, err := auth.LoginBrowser(cfg)
 	if err != nil {
-		fmt.Printf("Login failed: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("login failed: %w", err)
 	}
 
 	cred.Provider = "google-antigravity"
@@ -189,11 +121,10 @@ func authLoginGoogleAntigravity() {
 	}
 
 	if err = auth.SetCredential("google-antigravity", cred); err != nil {
-		fmt.Printf("Failed to save credentials: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("failed to save credentials: %w", err)
 	}
 
-	appCfg, err := loadConfig()
+	appCfg, err := internal.LoadConfig()
 	if err == nil {
 		// Update Providers (legacy format, for backward compatibility)
 		appCfg.Providers.Antigravity.AuthMethod = "oauth"
@@ -218,9 +149,9 @@ func authLoginGoogleAntigravity() {
 		}
 
 		// Update default model
-		appCfg.Agents.Defaults.Model = "gemini-flash"
+		appCfg.Agents.Defaults.ModelName = "gemini-flash"
 
-		if err := config.SaveConfig(getConfigPath(), appCfg); err != nil {
+		if err := config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
 			fmt.Printf("Warning: could not update config: %v\n", err)
 		}
 	}
@@ -228,6 +159,8 @@ func authLoginGoogleAntigravity() {
 	fmt.Println("\n✓ Google Antigravity login successful!")
 	fmt.Println("Default model set to: gemini-flash")
 	fmt.Println("Try it: picoclaw agent -m \"Hello world\"")
+
+	return nil
 }
 
 func fetchGoogleUserEmail(accessToken string) (string, error) {
@@ -258,19 +191,17 @@ func fetchGoogleUserEmail(accessToken string) (string, error) {
 	return userInfo.Email, nil
 }
 
-func authLoginPasteToken(provider string) {
+func authLoginPasteToken(provider string) error {
 	cred, err := auth.LoginPasteToken(provider, os.Stdin)
 	if err != nil {
-		fmt.Printf("Login failed: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("login failed: %w", err)
 	}
 
 	if err = auth.SetCredential(provider, cred); err != nil {
-		fmt.Printf("Failed to save credentials: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("failed to save credentials: %w", err)
 	}
 
-	appCfg, err := loadConfig()
+	appCfg, err := internal.LoadConfig()
 	if err == nil {
 		switch provider {
 		case "anthropic":
@@ -292,7 +223,7 @@ func authLoginPasteToken(provider string) {
 				})
 			}
 			// Update default model
-			appCfg.Agents.Defaults.Model = "claude-sonnet-4.6"
+			appCfg.Agents.Defaults.ModelName = "claude-sonnet-4.6"
 		case "openai":
 			appCfg.Providers.OpenAI.AuthMethod = "token"
 			// Update ModelList
@@ -312,38 +243,29 @@ func authLoginPasteToken(provider string) {
 				})
 			}
 			// Update default model
-			appCfg.Agents.Defaults.Model = "gpt-5.2"
+			appCfg.Agents.Defaults.ModelName = "gpt-5.2"
 		}
-		if err := config.SaveConfig(getConfigPath(), appCfg); err != nil {
-			fmt.Printf("Warning: could not update config: %v\n", err)
+		if err := config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
+			return fmt.Errorf("could not update config: %w", err)
 		}
 	}
 
 	fmt.Printf("Token saved for %s!\n", provider)
-	fmt.Printf("Default model set to: %s\n", appCfg.Agents.Defaults.Model)
+
+	if appCfg != nil {
+		fmt.Printf("Default model set to: %s\n", appCfg.Agents.Defaults.GetModelName())
 	}
 
-func authLogoutCmd() {
-	provider := ""
-
-	args := os.Args[3:]
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--provider", "-p":
-			if i+1 < len(args) {
-				provider = args[i+1]
-				i++
-			}
-		}
+	return nil
 }
 
+func authLogoutCmd(provider string) error {
 	if provider != "" {
 		if err := auth.DeleteCredential(provider); err != nil {
-			fmt.Printf("Failed to remove credentials: %v\n", err)
-			os.Exit(1)
+			return fmt.Errorf("failed to remove credentials: %w", err)
 		}
 
-		appCfg, err := loadConfig()
+		appCfg, err := internal.LoadConfig()
 		if err == nil {
 			// Clear AuthMethod in ModelList
 			for i := range appCfg.ModelList {
@@ -371,17 +293,19 @@ func authLogoutCmd() {
 			case "google-antigravity", "antigravity":
 				appCfg.Providers.Antigravity.AuthMethod = ""
 			}
-			config.SaveConfig(getConfigPath(), appCfg)
+			config.SaveConfig(internal.GetConfigPath(), appCfg)
 		}
 
 		fmt.Printf("Logged out from %s\n", provider)
-	} else {
-		if err := auth.DeleteAllCredentials(); err != nil {
-			fmt.Printf("Failed to remove credentials: %v\n", err)
-			os.Exit(1)
+
+		return nil
 	}
 
-		appCfg, err := loadConfig()
+	if err := auth.DeleteAllCredentials(); err != nil {
+		return fmt.Errorf("failed to remove credentials: %w", err)
+	}
+
+	appCfg, err := internal.LoadConfig()
 	if err == nil {
 		// Clear all AuthMethods in ModelList
 		for i := range appCfg.ModelList {
@@ -391,24 +315,24 @@ func authLogoutCmd() {
 		appCfg.Providers.OpenAI.AuthMethod = ""
 		appCfg.Providers.Anthropic.AuthMethod = ""
 		appCfg.Providers.Antigravity.AuthMethod = ""
-			config.SaveConfig(getConfigPath(), appCfg)
+		config.SaveConfig(internal.GetConfigPath(), appCfg)
 	}
 
 	fmt.Println("Logged out from all providers")
-	}
+
+	return nil
 }
 
-func authStatusCmd() {
+func authStatusCmd() error {
 	store, err := auth.LoadStore()
 	if err != nil {
-		fmt.Printf("Error loading auth store: %v\n", err)
-		return
+		return fmt.Errorf("failed to load auth store: %w", err)
 	}
 
 	if len(store.Credentials) == 0 {
 		fmt.Println("No authenticated providers.")
 		fmt.Println("Run: picoclaw auth login --provider <name>")
-		return
+		return nil
 	}
 
 	fmt.Println("\nAuthenticated Providers:")
@@ -437,14 +361,16 @@ func authStatusCmd() {
 			fmt.Printf("    Expires: %s\n", cred.ExpiresAt.Format("2006-01-02 15:04"))
 		}
 	}
+
+	return nil
 }
 
-func authModelsCmd() {
+func authModelsCmd() error {
 	cred, err := auth.GetCredential("google-antigravity")
 	if err != nil || cred == nil {
-		fmt.Println("Not logged in to Google Antigravity.")
-		fmt.Println("Run: picoclaw auth login --provider google-antigravity")
-		return
+		return fmt.Errorf(
+			"not logged in to Google Antigravity.\nrun: picoclaw auth login --provider google-antigravity",
+		)
 	}
 
 	// Refresh token if needed
@@ -459,21 +385,18 @@ func authModelsCmd() {
 
 	projectID := cred.ProjectID
 	if projectID == "" {
-		fmt.Println("No project ID stored. Try logging in again.")
-		return
+		return fmt.Errorf("no project id stored. Try logging in again")
 	}
 
 	fmt.Printf("Fetching models for project: %s\n\n", projectID)
 
 	models, err := providers.FetchAntigravityModels(cred.AccessToken, projectID)
 	if err != nil {
-		fmt.Printf("Error fetching models: %v\n", err)
-		return
+		return fmt.Errorf("error fetching models: %w", err)
 	}
 
 	if len(models) == 0 {
-		fmt.Println("No models available.")
-		return
+		return fmt.Errorf("no models available")
 	}
 
 	fmt.Println("Available Antigravity Models:")
@@ -489,6 +412,8 @@ func authModelsCmd() {
 		}
 		fmt.Printf("  %s %s\n", status, name)
 	}
+
+	return nil
 }
 
 // isAntigravityModel checks if a model string belongs to antigravity provider

cmd/picoclaw/internal/auth/login.go

@@ -0,0 +1,25 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newLoginCommand() *cobra.Command {
+	var (
+		provider      string
+		useDeviceCode bool
+	)
+
+	cmd := &cobra.Command{
+		Use:   "login",
+		Short: "Login via OAuth or paste token",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return authLoginCmd(provider, useDeviceCode)
+		},
+	}
+
+	cmd.Flags().StringVarP(&provider, "provider", "p", "", "Provider to login with (openai, anthropic)")
+	cmd.Flags().BoolVar(&useDeviceCode, "device-code", false, "Use device code flow (for headless environments)")
+	_ = cmd.MarkFlagRequired("provider")
+
+	return cmd
+}

cmd/picoclaw/internal/auth/login_test.go

@@ -0,0 +1,29 @@
+package auth
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewLoginSubCommand(t *testing.T) {
+	cmd := newLoginCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Login via OAuth or paste token", cmd.Short)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("device-code"))
+
+	providerFlag := cmd.Flags().Lookup("provider")
+	require.NotNil(t, providerFlag)
+
+	val, found := providerFlag.Annotations[cobra.BashCompOneRequiredFlag]
+	require.True(t, found)
+	require.NotEmpty(t, val)
+	assert.Equal(t, "true", val[0])
+}

cmd/picoclaw/internal/auth/logout.go

@@ -0,0 +1,20 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newLogoutCommand() *cobra.Command {
+	var provider string
+
+	cmd := &cobra.Command{
+		Use:   "logout",
+		Short: "Remove stored credentials",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return authLogoutCmd(provider)
+		},
+	}
+
+	cmd.Flags().StringVarP(&provider, "provider", "p", "", "Provider to logout from (openai, anthropic); empty = all")
+
+	return cmd
+}

cmd/picoclaw/internal/auth/logout_test.go

@@ -0,0 +1,20 @@
+package auth
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewLogoutSubcommand(t *testing.T) {
+	cmd := newLogoutCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Remove stored credentials", cmd.Short)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("provider"))
+}

cmd/picoclaw/internal/auth/models.go

@@ -0,0 +1,15 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newModelsCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "models",
+		Short: "Show available models",
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return authModelsCmd()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/auth/models_test.go

@@ -0,0 +1,19 @@
+package auth
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewModelsCommand(t *testing.T) {
+	cmd := newModelsCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "models", cmd.Use)
+	assert.Equal(t, "Show available models", cmd.Short)
+
+	assert.False(t, cmd.HasFlags())
+}

cmd/picoclaw/internal/auth/status.go

@@ -0,0 +1,16 @@
+package auth
+
+import "github.com/spf13/cobra"
+
+func newStatusCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "status",
+		Short: "Show current auth status",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return authStatusCmd()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/auth/status_test.go

@@ -0,0 +1,18 @@
+package auth
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewStatusSubcommand(t *testing.T) {
+	cmd := newStatusCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Show current auth status", cmd.Short)
+
+	assert.False(t, cmd.HasFlags())
+}

cmd/picoclaw/internal/cron/add.go

@@ -0,0 +1,64 @@
+package cron
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/cron"
+)
+
+func newAddCommand(storePath func() string) *cobra.Command {
+	var (
+		name    string
+		message string
+		every   int64
+		cronExp string
+		deliver bool
+		channel string
+		to      string
+	)
+
+	cmd := &cobra.Command{
+		Use:   "add",
+		Short: "Add a new scheduled job",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if every <= 0 && cronExp == "" {
+				return fmt.Errorf("either --every or --cron must be specified")
+			}
+
+			var schedule cron.CronSchedule
+			if every > 0 {
+				everyMS := every * 1000
+				schedule = cron.CronSchedule{Kind: "every", EveryMS: &everyMS}
+			} else {
+				schedule = cron.CronSchedule{Kind: "cron", Expr: cronExp}
+			}
+
+			cs := cron.NewCronService(storePath(), nil)
+			job, err := cs.AddJob(name, schedule, message, deliver, channel, to)
+			if err != nil {
+				return fmt.Errorf("error adding job: %w", err)
+			}
+
+			fmt.Printf("✓ Added job '%s' (%s)\n", job.Name, job.ID)
+
+			return nil
+		},
+	}
+
+	cmd.Flags().StringVarP(&name, "name", "n", "", "Job name")
+	cmd.Flags().StringVarP(&message, "message", "m", "", "Message for agent")
+	cmd.Flags().Int64VarP(&every, "every", "e", 0, "Run every N seconds")
+	cmd.Flags().StringVarP(&cronExp, "cron", "c", "", "Cron expression (e.g. '0 9 * * *')")
+	cmd.Flags().BoolVarP(&deliver, "deliver", "d", false, "Deliver response to channel")
+	cmd.Flags().StringVar(&to, "to", "", "Recipient for delivery")
+	cmd.Flags().StringVar(&channel, "channel", "", "Channel for delivery")
+
+	_ = cmd.MarkFlagRequired("name")
+	_ = cmd.MarkFlagRequired("message")
+	cmd.MarkFlagsMutuallyExclusive("every", "cron")
+
+	return cmd
+}

cmd/picoclaw/internal/cron/add_test.go

@@ -0,0 +1,57 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewAddSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newAddCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "add", cmd.Use)
+	assert.Equal(t, "Add a new scheduled job", cmd.Short)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("every"))
+	assert.NotNil(t, cmd.Flags().Lookup("cron"))
+	assert.NotNil(t, cmd.Flags().Lookup("deliver"))
+	assert.NotNil(t, cmd.Flags().Lookup("to"))
+	assert.NotNil(t, cmd.Flags().Lookup("channel"))
+
+	nameFlag := cmd.Flags().Lookup("name")
+	require.NotNil(t, nameFlag)
+
+	messageFlag := cmd.Flags().Lookup("message")
+	require.NotNil(t, messageFlag)
+
+	val, found := nameFlag.Annotations[cobra.BashCompOneRequiredFlag]
+	require.True(t, found)
+	require.NotEmpty(t, val)
+	assert.Equal(t, "true", val[0])
+
+	val, found = messageFlag.Annotations[cobra.BashCompOneRequiredFlag]
+	require.True(t, found)
+	require.NotEmpty(t, val)
+	assert.Equal(t, "true", val[0])
+}
+
+func TestNewAddCommandEveryAndCronMutuallyExclusive(t *testing.T) {
+	cmd := newAddCommand(func() string { return "testing" })
+
+	cmd.SetArgs([]string{
+		"--name", "job",
+		"--message", "hello",
+		"--every", "10",
+		"--cron", "0 9 * * *",
+	})
+
+	err := cmd.Execute()
+	require.Error(t, err)
+}

cmd/picoclaw/internal/cron/command.go

@@ -0,0 +1,44 @@
+package cron
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func NewCronCommand() *cobra.Command {
+	var storePath string
+
+	cmd := &cobra.Command{
+		Use:     "cron",
+		Aliases: []string{"c"},
+		Short:   "Manage scheduled tasks",
+		Args:    cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+		// Resolve storePath at execution time so it reflects the current config
+		// and is shared across all subcommands.
+		PersistentPreRunE: func(_ *cobra.Command, _ []string) error {
+			cfg, err := internal.LoadConfig()
+			if err != nil {
+				return fmt.Errorf("error loading config: %w", err)
+			}
+			storePath = filepath.Join(cfg.WorkspacePath(), "cron", "jobs.json")
+			return nil
+		},
+	}
+
+	cmd.AddCommand(
+		newListCommand(func() string { return storePath }),
+		newAddCommand(func() string { return storePath }),
+		newRemoveCommand(func() string { return storePath }),
+		newEnableCommand(func() string { return storePath }),
+		newDisableCommand(func() string { return storePath }),
+	)
+
+	return cmd
+}

cmd/picoclaw/internal/cron/command_test.go

@@ -0,0 +1,58 @@
+package cron
+
+import (
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewCronCommand(t *testing.T) {
+	cmd := NewCronCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Manage scheduled tasks", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("c"))
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.NotNil(t, cmd.PersistentPreRunE)
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.True(t, cmd.HasSubCommands())
+
+	allowedCommands := []string{
+		"list",
+		"add",
+		"remove",
+		"enable",
+		"disable",
+	}
+
+	subcommands := cmd.Commands()
+	assert.Len(t, subcommands, len(allowedCommands))
+
+	for _, subcmd := range subcommands {
+		found := slices.Contains(allowedCommands, subcmd.Name())
+		assert.True(t, found, "unexpected subcommand %q", subcmd.Name())
+
+		assert.Len(t, subcmd.Aliases, 0)
+		assert.False(t, subcmd.Hidden)
+
+		assert.False(t, subcmd.HasSubCommands())
+
+		assert.Nil(t, subcmd.Run)
+		assert.NotNil(t, subcmd.RunE)
+
+		assert.Nil(t, subcmd.PersistentPreRun)
+		assert.Nil(t, subcmd.PersistentPostRun)
+	}
+}

cmd/picoclaw/internal/cron/disable.go

@@ -0,0 +1,16 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newDisableCommand(storePath func() string) *cobra.Command {
+	return &cobra.Command{
+		Use:     "disable",
+		Short:   "Disable a job",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw cron disable 1`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			cronSetJobEnabled(storePath(), args[0], false)
+			return nil
+		},
+	}
+}

cmd/picoclaw/internal/cron/disable_test.go

@@ -0,0 +1,20 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDisableSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newDisableCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "disable", cmd.Use)
+	assert.Equal(t, "Disable a job", cmd.Short)
+
+	assert.True(t, cmd.HasExample())
+}

cmd/picoclaw/internal/cron/enable.go

@@ -0,0 +1,16 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newEnableCommand(storePath func() string) *cobra.Command {
+	return &cobra.Command{
+		Use:     "enable",
+		Short:   "Enable a job",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw cron enable 1`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			cronSetJobEnabled(storePath(), args[0], true)
+			return nil
+		},
+	}
+}

cmd/picoclaw/internal/cron/enable_test.go

@@ -0,0 +1,20 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestEnableSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newEnableCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "enable", cmd.Use)
+	assert.Equal(t, "Enable a job", cmd.Short)
+
+	assert.True(t, cmd.HasExample())
+}

cmd/picoclaw/internal/cron/helpers.go

@@ -0,0 +1,66 @@
+package cron
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/cron"
+)
+
+func cronListCmd(storePath string) {
+	cs := cron.NewCronService(storePath, nil)
+	jobs := cs.ListJobs(true) // Show all jobs, including disabled
+
+	if len(jobs) == 0 {
+		fmt.Println("No scheduled jobs.")
+		return
+	}
+
+	fmt.Println("\nScheduled Jobs:")
+	fmt.Println("----------------")
+	for _, job := range jobs {
+		var schedule string
+		if job.Schedule.Kind == "every" && job.Schedule.EveryMS != nil {
+			schedule = fmt.Sprintf("every %ds", *job.Schedule.EveryMS/1000)
+		} else if job.Schedule.Kind == "cron" {
+			schedule = job.Schedule.Expr
+		} else {
+			schedule = "one-time"
+		}
+
+		nextRun := "scheduled"
+		if job.State.NextRunAtMS != nil {
+			nextTime := time.UnixMilli(*job.State.NextRunAtMS)
+			nextRun = nextTime.Format("2006-01-02 15:04")
+		}
+
+		status := "enabled"
+		if !job.Enabled {
+			status = "disabled"
+		}
+
+		fmt.Printf("  %s (%s)\n", job.Name, job.ID)
+		fmt.Printf("    Schedule: %s\n", schedule)
+		fmt.Printf("    Status: %s\n", status)
+		fmt.Printf("    Next run: %s\n", nextRun)
+	}
+}
+
+func cronRemoveCmd(storePath, jobID string) {
+	cs := cron.NewCronService(storePath, nil)
+	if cs.RemoveJob(jobID) {
+		fmt.Printf("✓ Removed job %s\n", jobID)
+	} else {
+		fmt.Printf("✗ Job %s not found\n", jobID)
+	}
+}
+
+func cronSetJobEnabled(storePath, jobID string, enabled bool) {
+	cs := cron.NewCronService(storePath, nil)
+	job := cs.EnableJob(jobID, enabled)
+	if job != nil {
+		fmt.Printf("✓ Job '%s' enabled\n", job.Name)
+	} else {
+		fmt.Printf("✗ Job %s not found\n", jobID)
+	}
+}

cmd/picoclaw/internal/cron/list.go

@@ -0,0 +1,17 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newListCommand(storePath func() string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List all scheduled jobs",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			cronListCmd(storePath())
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/cron/list_test.go

@@ -0,0 +1,17 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewListSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newListCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "List all scheduled jobs", cmd.Short)
+}

cmd/picoclaw/internal/cron/remove.go

@@ -0,0 +1,18 @@
+package cron
+
+import "github.com/spf13/cobra"
+
+func newRemoveCommand(storePath func() string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "remove",
+		Short:   "Remove a job by ID",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw cron remove 1`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			cronRemoveCmd(storePath(), args[0])
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/cron/remove_test.go

@@ -0,0 +1,19 @@
+package cron
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewRemoveSubcommand(t *testing.T) {
+	fn := func() string { return "" }
+	cmd := newRemoveCommand(fn)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "Remove a job by ID", cmd.Short)
+
+	assert.True(t, cmd.HasExample())
+}

cmd/picoclaw/internal/gateway/command.go

@@ -0,0 +1,27 @@
+package gateway
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewGatewayCommand() *cobra.Command {
+	var (
+		debug         bool
+		orchestration bool
+	)
+
+	cmd := &cobra.Command{
+		Use:     "gateway",
+		Aliases: []string{"g"},
+		Short:   "Start picoclaw gateway",
+		Args:    cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return gatewayCmd(debug, orchestration)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&debug, "debug", "d", false, "Enable debug logging")
+	cmd.Flags().BoolVar(&orchestration, "orchestration", false, "Enable subagent orchestration")
+
+	return cmd
+}

cmd/picoclaw/internal/gateway/command_test.go

@@ -0,0 +1,31 @@
+package gateway
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewGatewayCommand(t *testing.T) {
+	cmd := NewGatewayCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "gateway", cmd.Use)
+	assert.Equal(t, "Start picoclaw gateway", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("g"))
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.True(t, cmd.HasFlags())
+	assert.NotNil(t, cmd.Flags().Lookup("debug"))
+}

cmd/picoclaw/internal/gateway/helpers.go

@@ -1,28 +1,43 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package gateway
 
 import (
 	"context"
 	"fmt"
+	"log"
+	"net"
 	"net/http"
 	"os"
 	"os/exec"
 	"os/signal"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/agent"
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
+	_ "github.com/sipeed/picoclaw/pkg/channels/dingtalk"
+	_ "github.com/sipeed/picoclaw/pkg/channels/discord"
+	_ "github.com/sipeed/picoclaw/pkg/channels/feishu"
+	_ "github.com/sipeed/picoclaw/pkg/channels/line"
+	_ "github.com/sipeed/picoclaw/pkg/channels/maixcam"
+	_ "github.com/sipeed/picoclaw/pkg/channels/onebot"
+	_ "github.com/sipeed/picoclaw/pkg/channels/pico"
+	_ "github.com/sipeed/picoclaw/pkg/channels/qq"
+	_ "github.com/sipeed/picoclaw/pkg/channels/slack"
+	_ "github.com/sipeed/picoclaw/pkg/channels/telegram"
+	_ "github.com/sipeed/picoclaw/pkg/channels/wecom"
+	_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp"
+	_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp_native"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/cron"
 	"github.com/sipeed/picoclaw/pkg/devices"
 	"github.com/sipeed/picoclaw/pkg/health"
 	"github.com/sipeed/picoclaw/pkg/heartbeat"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/miniapp"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/skills"
@@ -30,49 +45,34 @@ import (
 	"github.com/sipeed/picoclaw/pkg/stats"
 	"github.com/sipeed/picoclaw/pkg/tailscale"
 	"github.com/sipeed/picoclaw/pkg/tools"
-	"github.com/sipeed/picoclaw/pkg/voice"
 )
 
-func gatewayCmd() {
-	// Check for --debug and --stats flags
-	args := os.Args[2:]
-	enableStats := false
-	orchestrationEnabled := false
-	for _, arg := range args {
-		if arg == "--debug" || arg == "-d" {
+func gatewayCmd(debug bool, orchestration bool) error {
+	if debug {
 		logger.SetLevel(logger.DEBUG)
 		fmt.Println("🔍 Debug mode enabled")
 	}
-		if arg == "--stats" {
-			enableStats = true
-		}
-		if arg == "--orchestration" {
-			orchestrationEnabled = true
-		}
-	}
 
-	cfg, err := loadConfig()
+	cfg, err := internal.LoadConfig()
 	if err != nil {
-		fmt.Printf("Error loading config: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("error loading config: %w", err)
 	}
 
 	provider, modelID, err := providers.CreateProvider(cfg)
 	if err != nil {
-		fmt.Printf("Error creating provider: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("error creating provider: %w", err)
 	}
-	if orchestrationEnabled {
+	if orchestration {
 		cfg.Agents.Defaults.Orchestration = true
 	}
 
 	// Use the resolved model ID from provider creation
 	if modelID != "" {
-		cfg.Agents.Defaults.Model = modelID
+		cfg.Agents.Defaults.ModelName = modelID
 	}
 
 	msgBus := bus.NewMessageBus()
-	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider, enableStats)
+	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
 
 	// Print agent startup info
 	fmt.Println("\n📦 Agent Status:")
@@ -134,50 +134,23 @@ func gatewayCmd() {
 	// Reset heartbeat suppression when a real user message arrives
 	agentLoop.OnUserMessage = heartbeatService.ResetSuppression
 
-	channelManager, err := channels.NewManager(cfg, msgBus)
+	// Create media store for file lifecycle management with TTL cleanup
+	mediaStore := media.NewFileMediaStoreWithCleanup(media.MediaCleanerConfig{
+		Enabled:  cfg.Tools.MediaCleanup.Enabled,
+		MaxAge:   time.Duration(cfg.Tools.MediaCleanup.MaxAge) * time.Minute,
+		Interval: time.Duration(cfg.Tools.MediaCleanup.Interval) * time.Minute,
+	})
+	mediaStore.Start()
+
+	channelManager, err := channels.NewManager(cfg, msgBus, mediaStore)
 	if err != nil {
-		fmt.Printf("Error creating channel manager: %v\n", err)
-		os.Exit(1)
+		mediaStore.Stop()
+		return fmt.Errorf("error creating channel manager: %w", err)
 	}
 
-	// Inject channel manager into agent loop for command handling
+	// Inject channel manager and media store into agent loop
 	agentLoop.SetChannelManager(channelManager)
-
-	var transcriber *voice.GroqTranscriber
-	groqAPIKey := cfg.Providers.Groq.APIKey
-	if groqAPIKey == "" {
-		for _, mc := range cfg.ModelList {
-			if strings.HasPrefix(mc.Model, "groq/") && mc.APIKey != "" {
-				groqAPIKey = mc.APIKey
-				break
-			}
-		}
-	}
-	if groqAPIKey != "" {
-		transcriber = voice.NewGroqTranscriber(groqAPIKey)
-		logger.InfoC("voice", "Groq voice transcription enabled")
-	}
-
-	if transcriber != nil {
-		if telegramChannel, ok := channelManager.GetChannel("telegram"); ok {
-			if tc, ok := telegramChannel.(*channels.TelegramChannel); ok {
-				tc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Telegram channel")
-			}
-		}
-		if discordChannel, ok := channelManager.GetChannel("discord"); ok {
-			if dc, ok := discordChannel.(*channels.DiscordChannel); ok {
-				dc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Discord channel")
-			}
-		}
-		if slackChannel, ok := channelManager.GetChannel("slack"); ok {
-			if sc, ok := slackChannel.(*channels.SlackChannel); ok {
-				sc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Slack channel")
-			}
-		}
-	}
+	agentLoop.SetMediaStore(mediaStore)
 
 	enabledChannels := channelManager.GetEnabledChannels()
 	if len(enabledChannels) > 0 {
@@ -214,12 +187,16 @@ func gatewayCmd() {
 		fmt.Println("✓ Device event service started")
 	}
 
+	// Setup shared HTTP server with health endpoints and webhook handlers
+	healthServer := health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
+	addr := fmt.Sprintf("%s:%d", cfg.Gateway.Host, cfg.Gateway.Port)
+	channelManager.SetupHTTPServer(addr, healthServer)
+
 	if err := channelManager.StartAll(ctx); err != nil {
 		fmt.Printf("Error starting channels: %v\n", err)
+		return err
 	}
 
-	healthServer := health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
-
 	// Mini App setup: register routes and determine TLS mode
 	useTLS := false
 	var tlsCert, tlsKey string
@@ -230,14 +207,19 @@ func gatewayCmd() {
 			// Auto-detect Tailscale hostname and fetch TLS cert
 			hostname, tsErr := tailscale.DetectHostname()
 			if tsErr != nil {
-				logger.InfoCF("miniapp", "Tailscale not available, Mini App disabled", map[string]any{"error": tsErr.Error()})
+				logger.InfoCF(
+					"miniapp",
+					"Tailscale not available, Mini App disabled",
+					map[string]any{"error": tsErr.Error()},
+				)
 			} else {
 				certDir := filepath.Join(cfg.WorkspacePath(), "state", "certs")
 				certFile, keyFile, certErr := tailscale.FetchCert(hostname, certDir)
 				if certErr != nil {
 					logger.ErrorCF("miniapp", "Failed to fetch TLS cert", map[string]any{"error": certErr.Error()})
 				} else {
-					webAppURL = fmt.Sprintf("https://%s:%d/miniapp", hostname, cfg.Gateway.Port)
+					hostPort := net.JoinHostPort(hostname, strconv.Itoa(cfg.Gateway.Port))
+					webAppURL = "https://" + hostPort + "/miniapp"
 					cfg.Channels.Telegram.WebAppURL = webAppURL
 					tlsCert, tlsKey = certFile, keyFile
 					useTLS = true
@@ -246,10 +228,17 @@ func gatewayCmd() {
 		}
 
 		if webAppURL != "" {
-			provider := &agentLoopDataProvider{loop: agentLoop, workspace: cfg.WorkspacePath()}
+			dataProvider := &agentLoopDataProvider{loop: agentLoop, workspace: cfg.WorkspacePath()}
 			sender := &telegramCommandSender{bus: msgBus}
 			miniappNotifier = miniapp.NewStateNotifier()
-			handler := miniapp.NewHandler(provider, sender, cfg.Channels.Telegram.Token, miniappNotifier, cfg.Channels.Telegram.AllowFrom, cfg.WorkspacePath())
+			handler := miniapp.NewHandler(
+				dataProvider,
+				sender,
+				cfg.Channels.Telegram.Token,
+				miniappNotifier,
+				cfg.Channels.Telegram.AllowFrom,
+				cfg.WorkspacePath(),
+			)
 			agentLoop.OnStateChange = miniappNotifier.Notify
 			if b := agentLoop.GetOrchBroadcaster(); b != nil {
 				handler.SetOrchBroadcaster(b)
@@ -276,9 +265,16 @@ func gatewayCmd() {
 		}
 	}()
 	if useTLS {
-		fmt.Printf("✓ Health endpoints available at https://%s:%d/health and /ready (TLS)\n", cfg.Gateway.Host, cfg.Gateway.Port)
+		fmt.Printf(
+			"✓ Health endpoints available at https://%s:%d/health and /ready (TLS)\n",
+			cfg.Gateway.Host,
+			cfg.Gateway.Port,
+		)
 	} else {
-		fmt.Printf("✓ Health endpoints available at http://%s:%d/health and /ready\n", cfg.Gateway.Host, cfg.Gateway.Port)
+		fmt.Printf(
+			"✓ Health endpoints available at http://%s:%d/health and /ready\n",
+			cfg.Gateway.Host, cfg.Gateway.Port,
+		)
 	}
 
 	go agentLoop.Run(ctx)
@@ -288,20 +284,31 @@ func gatewayCmd() {
 	<-sigChan
 
 	fmt.Println("\nShutting down...")
+	if cp, ok := provider.(providers.StatefulProvider); ok {
+		cp.Close()
+	}
 	cancel()
 	if miniappNotifier != nil {
 		miniappNotifier.Close()
 	}
-	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 3*time.Second)
+	msgBus.Close()
+
+	// Use a fresh context with timeout for graceful shutdown,
+	// since the original ctx is already canceled.
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 15*time.Second)
 	defer shutdownCancel()
+
+	channelManager.StopAll(shutdownCtx)
 	healthServer.Stop(shutdownCtx)
 	deviceService.Stop()
 	heartbeatService.Stop()
 	cronService.Stop()
+	mediaStore.Stop()
 	agentLoop.Stop()
 	agentLoop.Close()
-	channelManager.StopAll(ctx)
 	fmt.Println("✓ Gateway stopped")
+
+	return nil
 }
 
 func setupCronTool(
@@ -318,7 +325,11 @@ func setupCronTool(
 	cronService := cron.NewCronService(cronStorePath, nil)
 
 	// Create and register CronTool
-	cronTool := tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout, cfg)
+	cronTool, err := tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout, cfg)
+	if err != nil {
+		log.Fatalf("Critical error during CronTool initialization: %v", err)
+	}
+
 	agentLoop.RegisterTool(cronTool)
 
 	// Set the onJob handler
@@ -456,7 +467,8 @@ func (p *agentLoopDataProvider) GetGitRepos() []miniapp.GitRepoSummary {
 			seen[repoDir] = true
 			name := filepath.Base(repoDir)
 			branch := ""
-			if out, err := exec.Command("git", "-C", repoDir, "rev-parse", "--abbrev-ref", "HEAD").Output(); err == nil {
+			out, err := exec.Command("git", "-C", repoDir, "rev-parse", "--abbrev-ref", "HEAD").Output()
+			if err == nil {
 				branch = strings.TrimSpace(string(out))
 			}
 			repos = append(repos, miniapp.GitRepoSummary{Name: name, Branch: branch})
@@ -555,7 +567,7 @@ type telegramCommandSender struct {
 }
 
 func (s *telegramCommandSender) SendCommand(senderID, chatID, command string) {
-	s.bus.PublishInbound(bus.InboundMessage{
+	s.bus.PublishInbound(context.Background(), bus.InboundMessage{
 		Channel:  "telegram",
 		SenderID: senderID,
 		ChatID:   chatID,

cmd/picoclaw/internal/helpers.go

@@ -0,0 +1,52 @@
+package internal
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const Logo = "🦞"
+
+var (
+	version   = "dev"
+	gitCommit string
+	buildTime string
+	goVersion string
+)
+
+func GetConfigPath() string {
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".picoclaw", "config.json")
+}
+
+func LoadConfig() (*config.Config, error) {
+	return config.LoadConfig(GetConfigPath())
+}
+
+// FormatVersion returns the version string with optional git commit
+func FormatVersion() string {
+	v := version
+	if gitCommit != "" {
+		v += fmt.Sprintf(" (git: %s)", gitCommit)
+	}
+	return v
+}
+
+// FormatBuildInfo returns build time and go version info
+func FormatBuildInfo() (string, string) {
+	build := buildTime
+	goVer := goVersion
+	if goVer == "" {
+		goVer = runtime.Version()
+	}
+	return build, goVer
+}
+
+// GetVersion returns the version string
+func GetVersion() string {
+	return version
+}

cmd/picoclaw/internal/helpers_test.go

@@ -0,0 +1,97 @@
+package internal
+
+import (
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGetConfigPath(t *testing.T) {
+	t.Setenv("HOME", "/tmp/home")
+
+	got := GetConfigPath()
+	want := filepath.Join("/tmp/home", ".picoclaw", "config.json")
+
+	assert.Equal(t, want, got)
+}
+
+func TestFormatVersion_NoGitCommit(t *testing.T) {
+	oldVersion, oldGit := version, gitCommit
+	t.Cleanup(func() { version, gitCommit = oldVersion, oldGit })
+
+	version = "1.2.3"
+	gitCommit = ""
+
+	assert.Equal(t, "1.2.3", FormatVersion())
+}
+
+func TestFormatVersion_WithGitCommit(t *testing.T) {
+	oldVersion, oldGit := version, gitCommit
+	t.Cleanup(func() { version, gitCommit = oldVersion, oldGit })
+
+	version = "1.2.3"
+	gitCommit = "abc123"
+
+	assert.Equal(t, "1.2.3 (git: abc123)", FormatVersion())
+}
+
+func TestFormatBuildInfo_UsesBuildTimeAndGoVersion_WhenSet(t *testing.T) {
+	oldBuildTime, oldGoVersion := buildTime, goVersion
+	t.Cleanup(func() { buildTime, goVersion = oldBuildTime, oldGoVersion })
+
+	buildTime = "2026-02-20T00:00:00Z"
+	goVersion = "go1.23.0"
+
+	build, goVer := FormatBuildInfo()
+
+	assert.Equal(t, buildTime, build)
+	assert.Equal(t, goVersion, goVer)
+}
+
+func TestFormatBuildInfo_EmptyBuildTime_ReturnsEmptyBuild(t *testing.T) {
+	oldBuildTime, oldGoVersion := buildTime, goVersion
+	t.Cleanup(func() { buildTime, goVersion = oldBuildTime, oldGoVersion })
+
+	buildTime = ""
+	goVersion = "go1.23.0"
+
+	build, goVer := FormatBuildInfo()
+
+	assert.Empty(t, build)
+	assert.Equal(t, goVersion, goVer)
+}
+
+func TestFormatBuildInfo_EmptyGoVersion_FallsBackToRuntimeVersion(t *testing.T) {
+	oldBuildTime, oldGoVersion := buildTime, goVersion
+	t.Cleanup(func() { buildTime, goVersion = oldBuildTime, oldGoVersion })
+
+	buildTime = "x"
+	goVersion = ""
+
+	build, goVer := FormatBuildInfo()
+
+	assert.Equal(t, "x", build)
+	assert.Equal(t, runtime.Version(), goVer)
+}
+
+func TestGetConfigPath_Windows(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		t.Skip("windows-specific HOME behavior varies; run on windows")
+	}
+
+	testUserProfilePath := `C:\Users\Test`
+	t.Setenv("USERPROFILE", testUserProfilePath)
+
+	got := GetConfigPath()
+	want := filepath.Join(testUserProfilePath, ".picoclaw", "config.json")
+
+	require.True(t, strings.EqualFold(got, want), "GetConfigPath() = %q, want %q", got, want)
+}
+
+func TestGetVersion(t *testing.T) {
+	assert.Equal(t, "dev", GetVersion())
+}

cmd/picoclaw/internal/migrate/command.go

@@ -0,0 +1,48 @@
+package migrate
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/migrate"
+)
+
+func NewMigrateCommand() *cobra.Command {
+	var opts migrate.Options
+
+	cmd := &cobra.Command{
+		Use:   "migrate",
+		Short: "Migrate from OpenClaw to PicoClaw",
+		Args:  cobra.NoArgs,
+		Example: `  picoclaw migrate
+  picoclaw migrate --dry-run
+  picoclaw migrate --refresh
+  picoclaw migrate --force`,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			result, err := migrate.Run(opts)
+			if err != nil {
+				return err
+			}
+			if !opts.DryRun {
+				migrate.PrintSummary(result)
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false,
+		"Show what would be migrated without making changes")
+	cmd.Flags().BoolVar(&opts.Refresh, "refresh", false,
+		"Re-sync workspace files from OpenClaw (repeatable)")
+	cmd.Flags().BoolVar(&opts.ConfigOnly, "config-only", false,
+		"Only migrate config, skip workspace files")
+	cmd.Flags().BoolVar(&opts.WorkspaceOnly, "workspace-only", false,
+		"Only migrate workspace files, skip config")
+	cmd.Flags().BoolVar(&opts.Force, "force", false,
+		"Skip confirmation prompts")
+	cmd.Flags().StringVar(&opts.OpenClawHome, "openclaw-home", "",
+		"Override OpenClaw home directory (default: ~/.openclaw)")
+	cmd.Flags().StringVar(&opts.PicoClawHome, "picoclaw-home", "",
+		"Override PicoClaw home directory (default: ~/.picoclaw)")
+
+	return cmd
+}

cmd/picoclaw/internal/migrate/command_test.go

@@ -0,0 +1,38 @@
+package migrate
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewMigrateCommand(t *testing.T) {
+	cmd := NewMigrateCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "migrate", cmd.Use)
+	assert.Equal(t, "Migrate from OpenClaw to PicoClaw", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.True(t, cmd.HasFlags())
+
+	assert.NotNil(t, cmd.Flags().Lookup("dry-run"))
+	assert.NotNil(t, cmd.Flags().Lookup("refresh"))
+	assert.NotNil(t, cmd.Flags().Lookup("config-only"))
+	assert.NotNil(t, cmd.Flags().Lookup("workspace-only"))
+	assert.NotNil(t, cmd.Flags().Lookup("force"))
+	assert.NotNil(t, cmd.Flags().Lookup("openclaw-home"))
+	assert.NotNil(t, cmd.Flags().Lookup("picoclaw-home"))
+}

cmd/picoclaw/internal/onboard/command.go

@@ -0,0 +1,24 @@
+package onboard
+
+import (
+	"embed"
+
+	"github.com/spf13/cobra"
+)
+
+//go:generate cp -r ../../../../workspace .
+//go:embed workspace
+var embeddedFiles embed.FS
+
+func NewOnboardCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "onboard",
+		Aliases: []string{"o"},
+		Short:   "Initialize picoclaw configuration and workspace",
+		Run: func(cmd *cobra.Command, args []string) {
+			onboard()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/onboard/command_test.go

@@ -0,0 +1,29 @@
+package onboard
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewOnboardCommand(t *testing.T) {
+	cmd := NewOnboardCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "onboard", cmd.Use)
+	assert.Equal(t, "Initialize picoclaw configuration and workspace", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("o"))
+
+	assert.NotNil(t, cmd.Run)
+	assert.Nil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	assert.False(t, cmd.HasFlags())
+	assert.False(t, cmd.HasSubCommands())
+}

cmd/picoclaw/internal/onboard/helpers.go

@@ -1,24 +1,17 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package onboard
 
 import (
-	"embed"
 	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/config"
 )
 
-//go:generate cp -r ../../workspace .
-//go:embed workspace
-var embeddedFiles embed.FS
-
 func onboard() {
-	configPath := getConfigPath()
+	configPath := internal.GetConfigPath()
 
 	if _, err := os.Stat(configPath); err == nil {
 		fmt.Printf("Config already exists at %s\n", configPath)
@@ -40,7 +33,7 @@ func onboard() {
 	workspace := cfg.WorkspacePath()
 	createWorkspaceTemplates(workspace)
 
-	fmt.Printf("%s picoclaw is ready!\n", logo)
+	fmt.Printf("%s picoclaw is ready!\n", internal.Logo)
 	fmt.Println("\nNext steps:")
 	fmt.Println("  1. Add your API key to", configPath)
 	fmt.Println("")
@@ -53,6 +46,13 @@ func onboard() {
 	fmt.Println("  2. Chat: picoclaw agent -m \"Hello!\"")
 }
 
+func createWorkspaceTemplates(workspace string) {
+	err := copyEmbeddedToTarget(workspace)
+	if err != nil {
+		fmt.Printf("Error copying workspace templates: %v\n", err)
+	}
+}
+
 func copyEmbeddedToTarget(targetDir string) error {
 	// Ensure target directory exists
 	if err := os.MkdirAll(targetDir, 0o755); err != nil {
@@ -99,10 +99,3 @@ func copyEmbeddedToTarget(targetDir string) error {
 
 	return err
 }
-
-func createWorkspaceTemplates(workspace string) {
-	err := copyEmbeddedToTarget(workspace)
-	if err != nil {
-		fmt.Printf("Error copying workspace templates: %v\n", err)
-	}
-}

cmd/picoclaw/internal/skills/command.go

@@ -0,0 +1,79 @@
+package skills
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+type deps struct {
+	workspace    string
+	installer    *skills.SkillInstaller
+	skillsLoader *skills.SkillsLoader
+}
+
+func NewSkillsCommand() *cobra.Command {
+	var d deps
+
+	cmd := &cobra.Command{
+		Use:   "skills",
+		Short: "Manage skills",
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := internal.LoadConfig()
+			if err != nil {
+				return fmt.Errorf("error loading config: %w", err)
+			}
+
+			d.workspace = cfg.WorkspacePath()
+			d.installer = skills.NewSkillInstaller(d.workspace)
+
+			// get global config directory and builtin skills directory
+			globalDir := filepath.Dir(internal.GetConfigPath())
+			globalSkillsDir := filepath.Join(globalDir, "skills")
+			builtinSkillsDir := filepath.Join(globalDir, "picoclaw", "skills")
+			d.skillsLoader = skills.NewSkillsLoader(d.workspace, globalSkillsDir, builtinSkillsDir)
+
+			return nil
+		},
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return cmd.Help()
+		},
+	}
+
+	installerFn := func() (*skills.SkillInstaller, error) {
+		if d.installer == nil {
+			return nil, fmt.Errorf("skills installer is not initialized")
+		}
+		return d.installer, nil
+	}
+
+	loaderFn := func() (*skills.SkillsLoader, error) {
+		if d.skillsLoader == nil {
+			return nil, fmt.Errorf("skills loader is not initialized")
+		}
+		return d.skillsLoader, nil
+	}
+
+	workspaceFn := func() (string, error) {
+		if d.workspace == "" {
+			return "", fmt.Errorf("workspace is not initialized")
+		}
+		return d.workspace, nil
+	}
+
+	cmd.AddCommand(
+		newListCommand(loaderFn),
+		newInstallCommand(installerFn),
+		newInstallBuiltinCommand(workspaceFn),
+		newListBuiltinCommand(),
+		newRemoveCommand(installerFn),
+		newSearchCommand(installerFn),
+		newShowCommand(loaderFn),
+	)
+
+	return cmd
+}

cmd/picoclaw/internal/skills/command_test.go

@@ -0,0 +1,28 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewSkillsCommand(t *testing.T) {
+	cmd := NewSkillsCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "skills", cmd.Use)
+	assert.Equal(t, "Manage skills", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.NotNil(t, cmd.PersistentPreRunE)
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+}

cmd/picoclaw/internal/skills/helpers.go

@@ -1,40 +1,20 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package skills
 
 import (
 	"context"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
 	"time"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/skills"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
-func skillsHelp() {
-	fmt.Println("\nSkills commands:")
-	fmt.Println("  list                    List installed skills")
-	fmt.Println("  install <repo>          Install skill from GitHub")
-	fmt.Println("  install-builtin         Install all builtin skills to workspace")
-	fmt.Println("  list-builtin            List available builtin skills")
-	fmt.Println("  remove <name>           Remove installed skill")
-	fmt.Println("  search                  Search available skills")
-	fmt.Println("  show <name>             Show skill details")
-	fmt.Println()
-	fmt.Println("Examples:")
-	fmt.Println("  picoclaw skills list")
-	fmt.Println("  picoclaw skills install sipeed/picoclaw-skills/weather")
-	fmt.Println("  picoclaw skills install-builtin")
-	fmt.Println("  picoclaw skills list-builtin")
-	fmt.Println("  picoclaw skills remove weather")
-	fmt.Println("  picoclaw skills install --registry clawhub github")
-}
-
 func skillsListCmd(loader *skills.SkillsLoader) {
 	allSkills := loader.ListSkills()
 
@@ -53,53 +33,31 @@ func skillsListCmd(loader *skills.SkillsLoader) {
 	}
 }
 
-func skillsInstallCmd(installer *skills.SkillInstaller, cfg *config.Config) {
-	if len(os.Args) < 4 {
-		fmt.Println("Usage: picoclaw skills install <github-repo>")
-		fmt.Println("       picoclaw skills install --registry <name> <slug>")
-		return
-	}
-
-	// Check for --registry flag.
-	if os.Args[3] == "--registry" {
-		if len(os.Args) < 6 {
-			fmt.Println("Usage: picoclaw skills install --registry <name> <slug>")
-			fmt.Println("Example: picoclaw skills install --registry clawhub github")
-			return
-		}
-		registryName := os.Args[4]
-		slug := os.Args[5]
-		skillsInstallFromRegistry(cfg, registryName, slug)
-		return
-	}
-
-	// Default: install from GitHub (backward compatible).
-	repo := os.Args[3]
+func skillsInstallCmd(installer *skills.SkillInstaller, repo string) error {
 	fmt.Printf("Installing skill from %s...\n", repo)
 
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
 
 	if err := installer.InstallFromGitHub(ctx, repo); err != nil {
-		fmt.Printf("\u2717 Failed to install skill: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("failed to install skill: %w", err)
 	}
 
 	fmt.Printf("\u2713 Skill '%s' installed successfully!\n", filepath.Base(repo))
+
+	return nil
 }
 
 // skillsInstallFromRegistry installs a skill from a named registry (e.g. clawhub).
-func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
+func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) error {
 	err := utils.ValidateSkillIdentifier(registryName)
 	if err != nil {
-		fmt.Printf("\u2717 Invalid registry name: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("✗  invalid registry name: %w", err)
 	}
 
 	err = utils.ValidateSkillIdentifier(slug)
 	if err != nil {
-		fmt.Printf("\u2717 Invalid slug: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("✗  invalid slug: %w", err)
 	}
 
 	fmt.Printf("Installing skill '%s' from %s registry...\n", slug, registryName)
@@ -111,24 +69,21 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
 
 	registry := registryMgr.GetRegistry(registryName)
 	if registry == nil {
-		fmt.Printf("\u2717 Registry '%s' not found or not enabled. Check your config.json.\n", registryName)
-		os.Exit(1)
+		return fmt.Errorf("✗  registry '%s' not found or not enabled. check your config.json.", registryName)
 	}
 
 	workspace := cfg.WorkspacePath()
 	targetDir := filepath.Join(workspace, "skills", slug)
 
 	if _, err = os.Stat(targetDir); err == nil {
-		fmt.Printf("\u2717 Skill '%s' already installed at %s\n", slug, targetDir)
-		os.Exit(1)
+		return fmt.Errorf("\u2717 skill '%s' already installed at %s", slug, targetDir)
 	}
 
 	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
 	defer cancel()
 
 	if err = os.MkdirAll(filepath.Join(workspace, "skills"), 0o755); err != nil {
-		fmt.Printf("\u2717 Failed to create skills directory: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("\u2717 failed to create skills directory: %v", err)
 	}
 
 	result, err := registry.DownloadAndInstall(ctx, slug, "", targetDir)
@@ -137,8 +92,7 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
 		if rmErr != nil {
 			fmt.Printf("\u2717 Failed to remove partial install: %v\n", rmErr)
 		}
-		fmt.Printf("\u2717 Failed to install skill: %v\n", err)
-		os.Exit(1)
+		return fmt.Errorf("✗ failed to install skill: %w", err)
 	}
 
 	if result.IsMalwareBlocked {
@@ -146,8 +100,8 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
 		if rmErr != nil {
 			fmt.Printf("\u2717 Failed to remove partial install: %v\n", rmErr)
 		}
-		fmt.Printf("\u2717 Skill '%s' is flagged as malicious and cannot be installed.\n", slug)
-		os.Exit(1)
+
+		return fmt.Errorf("\u2717 Skill '%s' is flagged as malicious and cannot be installed.\n", slug)
 	}
 
 	if result.IsSuspicious {
@@ -158,6 +112,8 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
 	if result.Summary != "" {
 		fmt.Printf("  %s\n", result.Summary)
 	}
+
+	return nil
 }
 
 func skillsRemoveCmd(installer *skills.SkillInstaller, skillName string) {
@@ -208,7 +164,7 @@ func skillsInstallBuiltinCmd(workspace string) {
 }
 
 func skillsListBuiltinCmd() {
-	cfg, err := loadConfig()
+	cfg, err := internal.LoadConfig()
 	if err != nil {
 		fmt.Printf("Error loading config: %v\n", err)
 		return
@@ -303,3 +259,37 @@ func skillsShowCmd(loader *skills.SkillsLoader, skillName string) {
 	fmt.Println("----------------------")
 	fmt.Println(content)
 }
+
+func copyDirectory(src, dst string) error {
+	return filepath.Walk(src, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		relPath, err := filepath.Rel(src, path)
+		if err != nil {
+			return err
+		}
+
+		dstPath := filepath.Join(dst, relPath)
+
+		if info.IsDir() {
+			return os.MkdirAll(dstPath, info.Mode())
+		}
+
+		srcFile, err := os.Open(path)
+		if err != nil {
+			return err
+		}
+		defer srcFile.Close()
+
+		dstFile, err := os.OpenFile(dstPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
+		if err != nil {
+			return err
+		}
+		defer dstFile.Close()
+
+		_, err = io.Copy(dstFile, srcFile)
+		return err
+	})
+}

cmd/picoclaw/internal/skills/install.go

@@ -0,0 +1,58 @@
+package skills
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newInstallCommand(installerFn func() (*skills.SkillInstaller, error)) *cobra.Command {
+	var registry string
+
+	cmd := &cobra.Command{
+		Use:   "install",
+		Short: "Install skill from GitHub",
+		Example: `
+picoclaw skills install sipeed/picoclaw-skills/weather
+picoclaw skills install --registry clawhub github
+`,
+		Args: func(cmd *cobra.Command, args []string) error {
+			if registry != "" {
+				if len(args) != 2 {
+					return fmt.Errorf("when --registry is set, exactly 2 arguments are required: <name> <slug>")
+				}
+				return nil
+			}
+
+			if len(args) != 1 {
+				return fmt.Errorf("exactly 1 argument is required: <github>")
+			}
+
+			return nil
+		},
+		RunE: func(_ *cobra.Command, args []string) error {
+			installer, err := installerFn()
+			if err != nil {
+				return err
+			}
+
+			if registry != "" {
+				cfg, err := internal.LoadConfig()
+				if err != nil {
+					return err
+				}
+
+				return skillsInstallFromRegistry(cfg, args[0], args[1])
+			}
+
+			return skillsInstallCmd(installer, args[0])
+		},
+	}
+
+	cmd.Flags().StringVar(&registry, "registry", "", "Install from registry: --registry <name> <slug>")
+
+	return cmd
+}

cmd/picoclaw/internal/skills/install_test.go

@@ -0,0 +1,28 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewInstallSubcommand(t *testing.T) {
+	cmd := newInstallCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "install", cmd.Use)
+	assert.Equal(t, "Install skill from GitHub", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.True(t, cmd.HasFlags())
+	assert.NotNil(t, cmd.Flags().Lookup("registry"))
+
+	assert.Len(t, cmd.Aliases, 0)
+}

cmd/picoclaw/internal/skills/installbuiltin.go

@@ -0,0 +1,21 @@
+package skills
+
+import "github.com/spf13/cobra"
+
+func newInstallBuiltinCommand(workspaceFn func() (string, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "install-builtin",
+		Short:   "Install all builtin skills to workspace",
+		Example: `picoclaw skills install-builtin`,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			workspace, err := workspaceFn()
+			if err != nil {
+				return err
+			}
+			skillsInstallBuiltinCmd(workspace)
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/installbuiltin_test.go

@@ -0,0 +1,27 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewInstallbuiltinSubcommand(t *testing.T) {
+	cmd := newInstallBuiltinCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "install-builtin", cmd.Use)
+	assert.Equal(t, "Install all builtin skills to workspace", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}

cmd/picoclaw/internal/skills/list.go

@@ -0,0 +1,25 @@
+package skills
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newListCommand(loaderFn func() (*skills.SkillsLoader, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "list",
+		Short:   "List installed skills",
+		Example: `picoclaw skills list`,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			loader, err := loaderFn()
+			if err != nil {
+				return err
+			}
+			skillsListCmd(loader)
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/list_test.go

@@ -0,0 +1,27 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewListSubcommand(t *testing.T) {
+	cmd := newListCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "list", cmd.Use)
+	assert.Equal(t, "List installed skills", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}

cmd/picoclaw/internal/skills/listbuiltin.go

@@ -0,0 +1,16 @@
+package skills
+
+import "github.com/spf13/cobra"
+
+func newListBuiltinCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "list-builtin",
+		Short:   "List available builtin skills",
+		Example: `picoclaw skills list-builtin`,
+		Run: func(_ *cobra.Command, _ []string) {
+			skillsListBuiltinCmd()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/listbuiltin_test.go

@@ -0,0 +1,26 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewListbuiltinSubcommand(t *testing.T) {
+	cmd := newListBuiltinCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "list-builtin", cmd.Use)
+	assert.Equal(t, "List available builtin skills", cmd.Short)
+
+	assert.NotNil(t, cmd.Run)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}

cmd/picoclaw/internal/skills/remove.go

@@ -0,0 +1,27 @@
+package skills
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newRemoveCommand(installerFn func() (*skills.SkillInstaller, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "remove",
+		Aliases: []string{"rm", "uninstall"},
+		Short:   "Remove installed skill",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw skills remove weather`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			installer, err := installerFn()
+			if err != nil {
+				return err
+			}
+			skillsRemoveCmd(installer, args[0])
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/remove_test.go

@@ -0,0 +1,29 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewRemoveSubcommand(t *testing.T) {
+	cmd := newRemoveCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "remove", cmd.Use)
+	assert.Equal(t, "Remove installed skill", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 2)
+	assert.True(t, cmd.HasAlias("rm"))
+	assert.True(t, cmd.HasAlias("uninstall"))
+}

cmd/picoclaw/internal/skills/search.go

@@ -0,0 +1,24 @@
+package skills
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newSearchCommand(installerFn func() (*skills.SkillInstaller, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "search",
+		Short: "Search available skills",
+		RunE: func(_ *cobra.Command, _ []string) error {
+			installer, err := installerFn()
+			if err != nil {
+				return err
+			}
+			skillsSearchCmd(installer)
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/search_test.go

@@ -0,0 +1,25 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewSearchSubcommand(t *testing.T) {
+	cmd := newSearchCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "search", cmd.Use)
+	assert.Equal(t, "Search available skills", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.False(t, cmd.HasSubCommands())
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}

cmd/picoclaw/internal/skills/show.go

@@ -0,0 +1,26 @@
+package skills
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+func newShowCommand(loaderFn func() (*skills.SkillsLoader, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "show",
+		Short:   "Show skill details",
+		Args:    cobra.ExactArgs(1),
+		Example: `picoclaw skills show weather`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			loader, err := loaderFn()
+			if err != nil {
+				return err
+			}
+			skillsShowCmd(loader, args[0])
+			return nil
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/skills/show_test.go

@@ -0,0 +1,27 @@
+package skills
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewShowSubcommand(t *testing.T) {
+	cmd := newShowCommand(nil)
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "show", cmd.Use)
+	assert.Equal(t, "Show skill details", cmd.Short)
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.True(t, cmd.HasExample())
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Len(t, cmd.Aliases, 0)
+}

cmd/picoclaw/internal/status/command.go

@@ -0,0 +1,18 @@
+package status
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewStatusCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "status",
+		Aliases: []string{"s"},
+		Short:   "Show picoclaw status",
+		Run: func(cmd *cobra.Command, args []string) {
+			statusCmd()
+		},
+	}
+
+	return cmd
+}

cmd/picoclaw/internal/status/command_test.go

@@ -0,0 +1,29 @@
+package status
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewStatusCommand(t *testing.T) {
+	cmd := NewStatusCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "status", cmd.Use)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("s"))
+
+	assert.Equal(t, "Show picoclaw status", cmd.Short)
+
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.NotNil(t, cmd.Run)
+	assert.Nil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+}

cmd/picoclaw/internal/status/helpers.go

@@ -1,27 +1,25 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// License: MIT
-
-package main
+package status
 
 import (
 	"fmt"
 	"os"
 
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/auth"
 )
 
 func statusCmd() {
-	cfg, err := loadConfig()
+	cfg, err := internal.LoadConfig()
 	if err != nil {
 		fmt.Printf("Error loading config: %v\n", err)
 		return
 	}
 
-	configPath := getConfigPath()
+	configPath := internal.GetConfigPath()
 
-	fmt.Printf("%s picoclaw Status\n", logo)
-	fmt.Printf("Version: %s\n", formatVersion())
-	build, _ := formatBuildInfo()
+	fmt.Printf("%s picoclaw Status\n", internal.Logo)
+	fmt.Printf("Version: %s\n", internal.FormatVersion())
+	build, _ := internal.FormatBuildInfo()
 	if build != "" {
 		fmt.Printf("Build: %s\n", build)
 	}
@@ -41,7 +39,7 @@ func statusCmd() {
 	}
 
 	if _, err := os.Stat(configPath); err == nil {
-		fmt.Printf("Model: %s\n", cfg.Agents.Defaults.Model)
+		fmt.Printf("Model: %s\n", cfg.Agents.Defaults.GetModelName())
 
 		hasOpenRouter := cfg.Providers.OpenRouter.APIKey != ""
 		hasAnthropic := cfg.Providers.Anthropic.APIKey != ""

cmd/picoclaw/internal/version/command.go

@@ -0,0 +1,33 @@
+package version
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func NewVersionCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "version",
+		Aliases: []string{"v"},
+		Short:   "Show version information",
+		Run: func(_ *cobra.Command, _ []string) {
+			printVersion()
+		},
+	}
+
+	return cmd
+}
+
+func printVersion() {
+	fmt.Printf("%s picoclaw %s\n", internal.Logo, internal.FormatVersion())
+	build, goVer := internal.FormatBuildInfo()
+	if build != "" {
+		fmt.Printf("  Build: %s\n", build)
+	}
+	if goVer != "" {
+		fmt.Printf("  Go: %s\n", goVer)
+	}
+}

cmd/picoclaw/internal/version/command_test.go

@@ -0,0 +1,31 @@
+package version
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewVersionCommand(t *testing.T) {
+	cmd := NewVersionCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "version", cmd.Use)
+
+	assert.Len(t, cmd.Aliases, 1)
+	assert.True(t, cmd.HasAlias("v"))
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Equal(t, "Show version information", cmd.Short)
+
+	assert.False(t, cmd.HasSubCommands())
+
+	assert.NotNil(t, cmd.Run)
+	assert.Nil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+}

cmd/picoclaw/main.go

@@ -8,192 +8,49 @@ package main
 
 import (
 	"fmt"
-	"io"
 	"os"
-	"path/filepath"
-	"runtime"
 
-	"github.com/sipeed/picoclaw/pkg/config"
-	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/agent"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/auth"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cron"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/gateway"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/migrate"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/onboard"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/skills"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/status"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/version"
 )
 
-var (
-	version   = "dev"
-	gitCommit string
-	buildTime string
-	goVersion string
+func NewPicoclawCommand() *cobra.Command {
+	short := fmt.Sprintf("%s picoclaw - Personal AI Assistant v%s\n\n", internal.Logo, internal.GetVersion())
+
+	cmd := &cobra.Command{
+		Use:     "picoclaw",
+		Short:   short,
+		Example: "picoclaw list",
+	}
+
+	cmd.AddCommand(
+		onboard.NewOnboardCommand(),
+		agent.NewAgentCommand(),
+		auth.NewAuthCommand(),
+		gateway.NewGatewayCommand(),
+		status.NewStatusCommand(),
+		cron.NewCronCommand(),
+		migrate.NewMigrateCommand(),
+		skills.NewSkillsCommand(),
+		version.NewVersionCommand(),
 	)
 
-const logo = "🦞"
-
-// formatVersion returns the version string with optional git commit
-func formatVersion() string {
-	v := version
-	if gitCommit != "" {
-		v += fmt.Sprintf(" (git: %s)", gitCommit)
-	}
-	return v
-}
-
-// formatBuildInfo returns build time and go version info
-func formatBuildInfo() (build string, goVer string) {
-	if buildTime != "" {
-		build = buildTime
-	}
-	goVer = goVersion
-	if goVer == "" {
-		goVer = runtime.Version()
-	}
-	return
-}
-
-func printVersion() {
-	fmt.Printf("%s picoclaw %s\n", logo, formatVersion())
-	build, goVer := formatBuildInfo()
-	if build != "" {
-		fmt.Printf("  Build: %s\n", build)
-	}
-	if goVer != "" {
-		fmt.Printf("  Go: %s\n", goVer)
-	}
-}
-
-func copyDirectory(src, dst string) error {
-	return filepath.Walk(src, func(path string, info os.FileInfo, err error) error {
-		if err != nil {
-			return err
-		}
-
-		relPath, err := filepath.Rel(src, path)
-		if err != nil {
-			return err
-		}
-
-		dstPath := filepath.Join(dst, relPath)
-
-		if info.IsDir() {
-			return os.MkdirAll(dstPath, info.Mode())
-		}
-
-		srcFile, err := os.Open(path)
-		if err != nil {
-			return err
-		}
-		defer srcFile.Close()
-
-		dstFile, err := os.OpenFile(dstPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
-		if err != nil {
-			return err
-		}
-		defer dstFile.Close()
-
-		_, err = io.Copy(dstFile, srcFile)
-		return err
-	})
+	return cmd
 }
 
 func main() {
-	if len(os.Args) < 2 {
-		printHelp()
-		os.Exit(1)
-	}
-
-	command := os.Args[1]
-
-	switch command {
-	case "onboard":
-		onboard()
-	case "agent":
-		agentCmd()
-	case "gateway":
-		gatewayCmd()
-	case "status":
-		statusCmd()
-	case "migrate":
-		migrateCmd()
-	case "auth":
-		authCmd()
-	case "cron":
-		cronCmd()
-	case "skills":
-		if len(os.Args) < 3 {
-			skillsHelp()
-			return
-		}
-
-		subcommand := os.Args[2]
-
-		cfg, err := loadConfig()
-		if err != nil {
-			fmt.Printf("Error loading config: %v\n", err)
-			os.Exit(1)
-		}
-
-		workspace := cfg.WorkspacePath()
-		installer := skills.NewSkillInstaller(workspace)
-		// 获取全局配置目录和内置 skills 目录
-		globalDir := filepath.Dir(getConfigPath())
-		globalSkillsDir := filepath.Join(globalDir, "skills")
-		builtinSkillsDir := filepath.Join(globalDir, "picoclaw", "skills")
-		skillsLoader := skills.NewSkillsLoader(workspace, globalSkillsDir, builtinSkillsDir)
-
-		switch subcommand {
-		case "list":
-			skillsListCmd(skillsLoader)
-		case "install":
-			skillsInstallCmd(installer, cfg)
-		case "remove", "uninstall":
-			if len(os.Args) < 4 {
-				fmt.Println("Usage: picoclaw skills remove <skill-name>")
-				return
-			}
-			skillsRemoveCmd(installer, os.Args[3])
-		case "install-builtin":
-			skillsInstallBuiltinCmd(workspace)
-		case "list-builtin":
-			skillsListBuiltinCmd()
-		case "search":
-			skillsSearchCmd(installer)
-		case "show":
-			if len(os.Args) < 4 {
-				fmt.Println("Usage: picoclaw skills show <skill-name>")
-				return
-			}
-			skillsShowCmd(skillsLoader, os.Args[3])
-		default:
-			fmt.Printf("Unknown skills command: %s\n", subcommand)
-			skillsHelp()
-		}
-	case "version", "--version", "-v":
-		printVersion()
-	default:
-		fmt.Printf("Unknown command: %s\n", command)
-		printHelp()
+	cmd := NewPicoclawCommand()
+	if err := cmd.Execute(); err != nil {
 		os.Exit(1)
 	}
 }
-
-func printHelp() {
-	fmt.Printf("%s picoclaw - Personal AI Assistant v%s\n\n", logo, version)
-	fmt.Println("Usage: picoclaw <command>")
-	fmt.Println()
-	fmt.Println("Commands:")
-	fmt.Println("  onboard     Initialize picoclaw configuration and workspace")
-	fmt.Println("  agent       Interact with the agent directly")
-	fmt.Println("  auth        Manage authentication (login, logout, status)")
-	fmt.Println("  gateway     Start picoclaw gateway (--stats to enable usage tracking)")
-	fmt.Println("  status      Show picoclaw status")
-	fmt.Println("  cron        Manage scheduled tasks")
-	fmt.Println("  migrate     Migrate from OpenClaw to PicoClaw")
-	fmt.Println("  skills      Manage skills (install, list, remove)")
-	fmt.Println("  version     Show version information")
-}
-
-func getConfigPath() string {
-	home, _ := os.UserHomeDir()
-	return filepath.Join(home, ".picoclaw", "config.json")
-}
-
-func loadConfig() (*config.Config, error) {
-	return config.LoadConfig(getConfigPath())
-}

cmd/picoclaw/main_test.go

@@ -0,0 +1,56 @@
+package main
+
+import (
+	"fmt"
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+)
+
+func TestNewPicoclawCommand(t *testing.T) {
+	cmd := NewPicoclawCommand()
+
+	require.NotNil(t, cmd)
+
+	short := fmt.Sprintf("%s picoclaw - Personal AI Assistant v%s\n\n", internal.Logo, internal.GetVersion())
+
+	assert.Equal(t, "picoclaw", cmd.Use)
+	assert.Equal(t, short, cmd.Short)
+
+	assert.True(t, cmd.HasSubCommands())
+	assert.True(t, cmd.HasAvailableSubCommands())
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Nil(t, cmd.Run)
+	assert.Nil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+
+	allowedCommands := []string{
+		"agent",
+		"auth",
+		"cron",
+		"gateway",
+		"migrate",
+		"onboard",
+		"skills",
+		"status",
+		"version",
+	}
+
+	subcommands := cmd.Commands()
+	assert.Len(t, subcommands, len(allowedCommands))
+
+	for _, subcmd := range subcommands {
+		found := slices.Contains(allowedCommands, subcmd.Name())
+		assert.True(t, found, "unexpected subcommand %q", subcmd.Name())
+
+		assert.False(t, subcmd.Hidden)
+	}
+}

config/config.example.json

@@ -3,9 +3,9 @@
     "defaults": {
       "workspace": "~/.picoclaw/workspace",
       "restrict_to_workspace": true,
-      "provider": "zhipu",
-      "model": "glm-4.7",
-      "model_fallbacks": ["openai/gpt-4o"],
+      "provider": "openai",
+      "model_name": "gpt4",
+      "model_fallbacks": [],
       "plan_model": "",
       "plan_model_fallbacks": [],
       "max_tokens": 8192,
@@ -64,30 +64,37 @@
       "web_app_url": "",
       "allow_from": [
         "YOUR_USER_ID"
-      ]
+      ],
+      "reasoning_channel_id": ""
     },
     "discord": {
       "enabled": false,
       "token": "YOUR_DISCORD_BOT_TOKEN",
       "allow_from": [],
-      "mention_only": false
+      "mention_only": false,
+      "reasoning_channel_id": ""
     },
     "qq": {
       "enabled": false,
       "app_id": "YOUR_QQ_APP_ID",
       "app_secret": "YOUR_QQ_APP_SECRET",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "maixcam": {
       "enabled": false,
       "host": "0.0.0.0",
       "port": 18790,
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "whatsapp": {
       "enabled": false,
       "bridge_url": "ws://localhost:3001",
-      "allow_from": []
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "feishu": {
       "enabled": false,
@@ -95,19 +102,22 @@
       "app_secret": "",
       "encrypt_key": "",
       "verification_token": "",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "dingtalk": {
       "enabled": false,
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "slack": {
       "enabled": false,
       "bot_token": "xoxb-YOUR-BOT-TOKEN",
       "app_token": "xapp-YOUR-APP-TOKEN",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "line": {
       "enabled": false,
@@ -116,7 +126,8 @@
       "webhook_host": "0.0.0.0",
       "webhook_port": 18791,
       "webhook_path": "/webhook/line",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "onebot": {
       "enabled": false,
@@ -124,7 +135,8 @@
       "access_token": "",
       "reconnect_interval": 5,
       "group_trigger_prefix": [],
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
     },
     "wecom": {
       "_comment": "WeCom Bot (智能机器人) - Easier setup, supports group chats",
@@ -136,7 +148,8 @@
       "webhook_port": 18793,
       "webhook_path": "/webhook/wecom",
       "allow_from": [],
-      "reply_timeout": 5
+      "reply_timeout": 5,
+      "reasoning_channel_id": ""
     },
     "wecom_app": {
       "_comment": "WeCom App (自建应用) - More features, proactive messaging, private chat only. See docs/wecom-app-configuration.md",
@@ -150,7 +163,8 @@
       "webhook_port": 18792,
       "webhook_path": "/webhook/wecom-app",
       "allow_from": [],
-      "reply_timeout": 5
+      "reply_timeout": 5,
+      "reasoning_channel_id": ""
     }
   },
   "providers": {
@@ -229,7 +243,8 @@
         "enabled": false,
         "api_key": "pplx-xxx",
         "max_results": 5
-      }
+      },
+      "proxy": ""
     },
     "cron": {
       "exec_timeout_minutes": 5
@@ -259,7 +274,7 @@
     "monitor_usb": true
   },
   "gateway": {
-    "host": "0.0.0.0",
+    "host": "127.0.0.1",
     "port": 18790
   }
 }

docker/Dockerfile

@@ -1,7 +1,7 @@
 # ============================================================
 # Stage 1: Build the picoclaw binary
 # ============================================================
-FROM golang:1.26.0-alpine AS builder
+FROM golang:1.25-alpine AS builder
 
 RUN apk add --no-cache git make
 

docker/Dockerfile.goreleaser

@@ -5,6 +5,8 @@ ARG TARGETPLATFORM
 RUN apk add --no-cache ca-certificates tzdata
 
 COPY $TARGETPLATFORM/picoclaw /usr/local/bin/picoclaw
+COPY docker/entrypoint.sh /entrypoint.sh
 
-ENTRYPOINT ["picoclaw"]
-CMD ["gateway"]
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]

docker/docker-compose.yml

@@ -1,12 +1,10 @@
 services:
   # ─────────────────────────────────────────────
   # PicoClaw Agent (one-shot query)
-  #   docker compose run --rm picoclaw-agent -m "Hello"
+  #   docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Hello"
   # ─────────────────────────────────────────────
   picoclaw-agent:
-    build:
-      context: .
-      dockerfile: Dockerfile
+    image: docker.io/sipeed/picoclaw:latest
     container_name: picoclaw-agent
     profiles:
       - agent
@@ -14,33 +12,23 @@ services:
     #extra_hosts:
     #  - "host.docker.internal:host-gateway"
     volumes:
-      - ./config/config.json:/home/picoclaw/.picoclaw/config.json:ro
-      - picoclaw-workspace:/home/picoclaw/.picoclaw/workspace
+      - ./data:/root/.picoclaw
     entrypoint: ["picoclaw", "agent"]
     stdin_open: true
     tty: true
 
   # ─────────────────────────────────────────────
   # PicoClaw Gateway (Long-running Bot)
-  #   docker compose up picoclaw-gateway
+  #   docker compose -f docker/docker-compose.yml up picoclaw-gateway
   # ─────────────────────────────────────────────
   picoclaw-gateway:
-    build:
-      context: .
-      dockerfile: Dockerfile
+    image: docker.io/sipeed/picoclaw:latest
     container_name: picoclaw-gateway
-    restart: unless-stopped
+    restart: on-failure
     profiles:
       - gateway
     # Uncomment to access host network; leave commented unless needed.
     #extra_hosts:
     #  - "host.docker.internal:host-gateway"
     volumes:
-      # Configuration file
-      - ./config/config.json:/home/picoclaw/.picoclaw/config.json:ro
-      # Persistent workspace (sessions, memory, logs)
-      - picoclaw-workspace:/home/picoclaw/.picoclaw/workspace
-    command: ["gateway"]
-
-volumes:
-  picoclaw-workspace:
+      - ./data:/root/.picoclaw

docker/entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+set -e
+
+# First-run: neither config nor workspace exists.
+# If config.json is already mounted but workspace is missing we skip onboard to
+# avoid the interactive "Overwrite? (y/n)" prompt hanging in a non-TTY container.
+if [ ! -d "${HOME}/.picoclaw/workspace" ] && [ ! -f "${HOME}/.picoclaw/config.json" ]; then
+    picoclaw onboard
+    echo ""
+    echo "First-run setup complete."
+    echo "Edit ${HOME}/.picoclaw/config.json (add your API key, etc.) then restart the container."
+    exit 0
+fi
+
+exec picoclaw gateway "$@"

docs/design/issue-783-investigation-and-fix-plan.zh.md

@@ -0,0 +1,61 @@
+# Issue #783 调研与修复执行文档
+
+## 1. 问题澄清（已确认）
+
+- 现象：当 `agents.*.model.primary/fallbacks` 使用 `model_name` 别名（如 `step-3.5-flash`）时，fallback 链路将别名当作真实 `provider/model` 解析，导致 `provider` 可能为空、`model` 可能错误。
+- 根因：`ResolveCandidates` 仅对字符串做 `ParseModelRef`，未先通过 `model_list` 将别名映射到真实 `model` 字段。
+- 影响：
+  - fallback 执行可能把别名直接发给 OpenAI-compatible provider，触发 `Unknown Model`。
+  - `defaults.provider` 为空时，日志出现 `provider=` 空值。
+
+## 2. 本次目标
+
+- 修复 fallback 候选解析：优先通过 `model_list` 解析别名。
+- 兼容旧行为：若未命中 `model_list`，继续走原有 `ParseModelRef` 兜底。
+- 补充测试：覆盖别名、嵌套路径模型（如 `openrouter/stepfun/...`）、空默认 provider。
+- 验证代码风格：与当前仓库风格保持一致（命名、错误处理、测试结构）。
+
+## 3. 联网最佳实践调研结论（已完成）
+
+- [x] 查阅 OpenAI-compatible 网关（如 OpenRouter）对 `model` 字段的推荐处理。
+- [x] 查阅多 provider/fallback 设计最佳实践（候选解析、日志可观测性）。
+- [x] 将外部建议映射为本仓库可执行约束。
+
+外部参考要点（来自 OpenRouter/LiteLLM/Cloudflare AI Gateway 等官方文档）：
+
+- 优先显式配置，不依赖字符串切分推断 provider。
+- 对网关模型标识应保留完整路径语义，避免截断导致 Unknown Model。
+- fallback 与 primary 应复用同一解析策略，避免“主路径正确、降级路径错误”。
+
+参考链接：
+
+- OpenRouter Provider Routing: https://openrouter.ai/docs/guides/routing/provider-selection
+- OpenRouter Model Fallbacks: https://openrouter.ai/docs/guides/routing/model-fallbacks
+- OpenRouter Chat Completion API: https://openrouter.ai/docs/api-reference/chat-completion
+- LiteLLM Router Architecture: https://docs.litellm.ai/docs/router_architecture
+- Cloudflare AI Gateway Chat Completion: https://developers.cloudflare.com/ai-gateway/usage/chat-completion/
+
+与本仓库对应的可执行约束：
+
+- 在 fallback candidate 构建阶段先做 `model_name -> model_list.model` 映射。
+- 未命中映射时保留旧解析行为，保证兼容性。
+- 用新增测试锁定“别名 + 嵌套模型路径 + 空默认 provider”场景。
+
+## 4. 实施步骤（顺序执行）
+
+- [x] Step 1: 对齐现有代码模式，定位最小改动点（`pkg/agent` + `pkg/providers`）。
+- [x] Step 2: 实现“基于 model_list 的 fallback 候选解析”。
+- [x] Step 3: 增加/更新单元测试，覆盖 issue 场景。
+- [x] Step 4: 代码风格一致性复核（与现有文件风格对照）。
+- [x] Step 5: 运行质量门禁（LSP + `make check`）。
+
+## 5. 执行记录
+
+- 状态：已完成
+- 已完成改动：
+  - `pkg/providers/fallback.go`：新增 `ResolveCandidatesWithLookup`，并保持 `ResolveCandidates` 向后兼容。
+  - `pkg/agent/instance.go`：在构建 fallback candidates 前，优先通过 `model_list` 解析别名，并对无协议模型补齐默认 `openai/` 前缀后再解析。
+  - `pkg/providers/fallback_test.go`：新增别名解析与去重测试。
+  - `pkg/agent/instance_test.go`：新增 agent 侧别名解析到嵌套模型路径、无协议模型解析测试。
+- 风格对齐检查（完成）：与 `pkg/providers/fallback_test.go`、`pkg/providers/model_ref_test.go` 现有模式一致。
+- 质量验证（完成）：先 `make generate`，后 `make check` 全量通过。

docs/migration/model-list-migration.md

@@ -117,6 +117,7 @@ The `model` field uses a protocol prefix format: `[protocol/]model-identifier`
 | `connect_mode` | No | Connection mode for CLI providers: `stdio`, `grpc` |
 | `rpm` | No | Requests per minute limit |
 | `max_tokens_field` | No | Field name for max tokens |
+| `request_timeout` | No | HTTP request timeout in seconds; `<=0` uses default `120s` |
 
 *`api_key` is required for HTTP-based protocols unless `api_base` points to a local server.
 

docs/troubleshooting.md

@@ -0,0 +1,43 @@
+# Troubleshooting
+
+## "model ... not found in model_list" or OpenRouter "free is not a valid model ID"
+
+**Symptom:** You see either:
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter returns 400: `"free is not a valid model ID"`
+
+**Cause:** The `model` field in your `model_list` entry is what gets sent to the API. For OpenRouter you must use the **full** model ID, not a shorthand.
+
+- **Wrong:** `"model": "free"` → OpenRouter receives `free` and rejects it.
+- **Right:** `"model": "openrouter/free"` → OpenRouter receives `openrouter/free` (auto free-tier routing).
+
+**Fix:** In `~/.picoclaw/config.json` (or your config path):
+
+1. **agents.defaults.model** must match a `model_name` in `model_list` (e.g. `"openrouter-free"`).
+2. That entry’s **model** must be a valid OpenRouter model ID, for example:
+   - `"openrouter/free"` – auto free-tier
+   - `"google/gemini-2.0-flash-exp:free"`
+   - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+Example snippet:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "openrouter-free"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "openrouter-free",
+      "model": "openrouter/free",
+      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  ]
+}
+```
+
+Get your key at [OpenRouter Keys](https://openrouter.ai/keys).

go.mod

@@ -11,19 +11,48 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/larksuite/oapi-sdk-go/v3 v3.5.3
+	github.com/mdp/qrterminal/v3 v3.2.1
 	github.com/mymmrac/telego v1.6.0
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
 	github.com/openai/openai-go/v3 v3.22.0
 	github.com/slack-go/slack v0.17.3
+	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1
 	github.com/tencent-connect/botgo v0.2.1
+	go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4
 	golang.org/x/oauth2 v0.35.0
+	golang.org/x/time v0.14.0
+	google.golang.org/protobuf v1.36.11
+	modernc.org/sqlite v1.46.1
 )
 
 require (
+	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/beeper/argo-go v1.1.2 // indirect
+	github.com/coder/websocket v1.8.14 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/elliotchance/orderedmap/v3 v3.1.0 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/rs/zerolog v1.34.0 // indirect
+	github.com/spf13/pflag v1.0.10 // indirect
+	github.com/vektah/gqlparser/v2 v2.5.27 // indirect
+	go.mau.fi/libsignal v0.2.1 // indirect
+	go.mau.fi/util v0.9.6 // indirect
+	golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a // indirect
+	golang.org/x/term v0.40.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
+	modernc.org/libc v1.67.6 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	rsc.io/qr v0.2.0 // indirect
 )
 
 require (

go.sum

@@ -1,10 +1,20 @@
 cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k=
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+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/adhocore/gronx v1.19.6 h1:5KNVcoR9ACgL9HhEqCm5QXsab/gI4QDIybTAWcXDKDc=
 github.com/adhocore/gronx v1.19.6/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.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
 github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
 github.com/anthropics/anthropic-sdk-go v1.22.1 h1:xbsc3vJKCX/ELDZSpTNfz9wCgrFsamwFewPb1iI0Xh0=
 github.com/anthropics/anthropic-sdk-go v1.22.1/go.mod h1:WTz31rIUHUHqai2UslPpw5CwXrQP3geYBioRV4WOLvE=
+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/bwmarrin/discordgo v0.29.0 h1:FmWeXFaKUwrcL3Cx65c20bTRW+vOb6k8AnaP+EgjDno=
 github.com/bwmarrin/discordgo v0.29.0/go.mod h1:NJZpH+1AfhIcyQsPeuBKsUtYrRnjkyu0kIVMCHkZtRY=
 github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
@@ -25,11 +35,19 @@ github.com/chzyer/test v1.0.0 h1:p3BQDXSxOhOG0P9z6/hGnII4LGiEPOYBhs8asl/fC04=
 github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
 github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
+github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
+github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/elliotchance/orderedmap/v3 v3.1.0 h1:j4DJ5ObEmMBt/lcwIecKcoRxIQUEnw0L804lXYDt/pg=
+github.com/elliotchance/orderedmap/v3 v3.1.0/go.mod h1:G+Hc2RwaZvJMcS4JpGCOyViCnGeKf0bTYCGTO4uhjSo=
 github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
 github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
 github.com/github/copilot-sdk/go v0.1.23 h1:uExtO/inZQndCZMiSAA1hvXINiz9tqo/MZgQzFzurxw=
@@ -41,6 +59,7 @@ github.com/go-resty/resty/v2 v2.17.1/go.mod h1:kCKZ3wWmwJaNc7S29BRtUhJwy7iqmn+2m
 github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE=
 github.com/go-test/deep v1.1.1 h1:0r/53hagsehfO4bzD2Pgr/+RgHqhmf+k1Bpse2cTu1U=
 github.com/go-test/deep v1.1.1/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE=
+github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
@@ -62,6 +81,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
 github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
 github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
@@ -71,7 +92,11 @@ github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aN
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/grbit/go-json v0.11.0 h1:bAbyMdYrYl/OjYsSqLH99N2DyQ291mHy726Mx+sYrnc=
 github.com/grbit/go-json v0.11.0/go.mod h1:IYpHsdybQ386+6g3VE6AXQ3uTGa5mquBme5/ZWmtzek=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 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/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.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
@@ -88,8 +113,21 @@ 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.5.3 h1:xvf8Dv29kBXC5/DNDCLhHkAFW8l/0LlQJimO5Zn+JUk=
 github.com/larksuite/oapi-sdk-go/v3 v3.5.3/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+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.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp6Zk=
+github.com/mattn/go-sqlite3 v1.14.34/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/mdp/qrterminal/v3 v3.2.1 h1:6+yQjiiOsSuXT5n9/m60E54vdgFsw0zhADHhHLrFet4=
+github.com/mdp/qrterminal/v3 v3.2.1/go.mod h1:jOTmXvnBsMy5xqLniO0R++Jmjs2sTm9dFSuQ5kpz/SU=
 github.com/mymmrac/telego v1.6.0 h1:Zc8rgyHozvd/7ZgyrigyHdAF9koHYMfilYfyB6wlFC0=
 github.com/mymmrac/telego v1.6.0/go.mod h1:xt6ZWA8zi8KmuzryE1ImEdl9JSwjHNpM4yhC7D8hU4Y=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
 github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
@@ -102,14 +140,30 @@ github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1 h1:Lb/Uzkiw2Ugt2Xf03J5wmv
 github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
 github.com/openai/openai-go/v3 v3.22.0 h1:6MEoNoV8sbjOVmXdvhmuX3BjVbVdcExbVyGixiyJ8ys=
 github.com/openai/openai-go/v3 v3.22.0/go.mod h1:cdufnVK14cWcT9qA1rRtrXx4FTRsgbDPW7Ia7SS5cZo=
+github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 h1:KPpdlQLZcHfTMQRi6bFQ7ogNO0ltFT4PmtwTLW4W+14=
+github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
 github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
+github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
+github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
+github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
 github.com/slack-go/slack v0.17.3 h1:zV5qO3Q+WJAQ/XwbGfNFrRMaJ5T/naqaonyPV/1TP4g=
 github.com/slack-go/slack v0.17.3/go.mod h1:X+UqOufi3LYQHDnMG1vxf0J8asC6+WllXrVrhl8/Prk=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+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/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=
@@ -144,13 +198,22 @@ github.com/valyala/fasthttp v1.69.0 h1:fNLLESD2SooWeh2cidsuFtOcrEi4uB4m1mPrkJMZy
 github.com/valyala/fasthttp v1.69.0/go.mod h1:4wA4PfAraPlAsJ5jMSqCE2ug5tqUPwKXxVj8oNECGcw=
 github.com/valyala/fastjson v1.6.7 h1:ZE4tRy0CIkh+qDc5McjatheGX2czdn8slQjomexVpBM=
 github.com/valyala/fastjson v1.6.7/go.mod h1:CLCAqky6SMuOcxStkYQvblddUtoRxhYMGLrsQns1aXY=
+github.com/vektah/gqlparser/v2 v2.5.27 h1:RHPD3JOplpk5mP5JGX8RKZkt2/Vwj/PZv0HxTdwFp0s=
+github.com/vektah/gqlparser/v2 v2.5.27/go.mod h1:D1/VCZtV3LPnQrcPBeR/q5jkSQIPti0uYCP/RI0gIeo=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+go.mau.fi/libsignal v0.2.1 h1:vRZG4EzTn70XY6Oh/pVKrQGuMHBkAWlGRC22/85m9L0=
+go.mau.fi/libsignal v0.2.1/go.mod h1:iVvjrHyfQqWajOUaMEsIfo3IqgVMrhWcPiiEzk7NgoU=
+go.mau.fi/util v0.9.6 h1:2nsvxm49KhI3wrFltr0+wSUBlnQ4CMtykuELjpIU+ts=
+go.mau.fi/util v0.9.6/go.mod h1:sIJpRH7Iy5Ad1SBuxQoatxtIeErgzxCtjd/2hCMkYMI=
+go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4 h1:hsmlwsM+VqfF70cpdZEeIUKer2XWCQmQPK0u0tHy3ZQ=
+go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4/go.mod h1:mXCRFyPEPn4jqWz6Afirn8vY7DpHCPnlKq6I2cWwFHM=
 go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
 go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 golang.org/x/arch v0.24.0 h1:qlJ3M9upxvFfwRM51tTg3Yl+8CP9vCC1E7vlFpgv99Y=
 golang.org/x/arch v0.24.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -161,10 +224,14 @@ golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5y
 golang.org/x/crypto v0.16.0/go.mod h1:gCAAfMLgwOJRpTjQ2zCCt2OcSfYMTeZVSRtQlPC7Nq4=
 golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
 golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a h1:ovFr6Z0MNmU7nH8VaX5xqw+05ST2uO1exVfZPVqRC5o=
+golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a/go.mod h1:K79w1Vqn7PoiZn+TkNpx3BUWUQksGO3JcVX6qIjytmA=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
+golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
+golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
@@ -207,8 +274,11 @@ golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/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.0.0-20220811171246-fbc7d0a398ab/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.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
 golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
@@ -217,6 +287,8 @@ golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuX
 golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
 golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
 golang.org/x/term v0.15.0/go.mod h1:BDl952bC7+uMoWR75FIrCDx79TPU9oHkTZ9yRbYOrX0=
+golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg=
+golang.org/x/term v0.40.0/go.mod h1:w2P8uVp06p2iyKKuvXIm7N/y0UCRt3UfJTfZ7oOpglM=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
@@ -224,8 +296,10 @@ golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
 golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
-golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
+golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
@@ -233,6 +307,8 @@ golang.org/x/tools v0.0.0-20201224043029-2b0845dc783e/go.mod h1:emZCQorbCU4vsT4f
 golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
+golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
+golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
@@ -245,6 +321,8 @@ google.golang.org/protobuf v1.21.0/go.mod h1:47Nbq4nVaFHyn7ilMalzfO3qCViNmqZ2kzi
 google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
@@ -259,3 +337,33 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
+modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
+modernc.org/ccgo/v4 v4.30.1 h1:4r4U1J6Fhj98NKfSjnPUN7Ze2c6MnAdL0hWw6+LrJpc=
+modernc.org/ccgo/v4 v4.30.1/go.mod h1:bIOeI1JL54Utlxn+LwrFyjCx2n2RDiYEaJVSrgdrRfM=
+modernc.org/fileutil v1.3.40 h1:ZGMswMNc9JOCrcrakF1HrvmergNLAmxOPjizirpfqBA=
+modernc.org/fileutil v1.3.40/go.mod h1:HxmghZSZVAz/LXcMNwZPA/DRrQZEVP9VX0V4LQGQFOc=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.1 h1:k8T3gkXWY9sEiytKhcgyiZ2L0DTyCQ/nvX+LoCljoRE=
+modernc.org/gc/v3 v3.1.1/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.67.6 h1:eVOQvpModVLKOdT+LvBPjdQqfrZq+pC39BygcT+E7OI=
+modernc.org/libc v1.67.6/go.mod h1:JAhxUVlolfYDErnwiqaLvUqc8nfb2r6S6slAgZOnaiE=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
+modernc.org/opt v0.1.4/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.46.1 h1:eFJ2ShBLIEnUWlLy12raN0Z1plqmFX9Qe3rjQTKt6sU=
+modernc.org/sqlite v1.46.1/go.mod h1:CzbrU2lSB1DKUusvwGz7rqEKIq+NUd8GWuBBZDs9/nA=
+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=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+rsc.io/qr v0.2.0 h1:6vBLea5/NRMVTz8V66gipeLycZMl/+UlFmk8DvqQ6WY=
+rsc.io/qr v0.2.0/go.mod h1:IF+uZjkb9fqyeF/4tlBoynqmQxUoPfWEKh921coOuXs=

pkg/agent/context.go

@@ -1,11 +1,14 @@
 package agent
 
 import (
+	"errors"
 	"fmt"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"runtime"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/logger"
@@ -47,6 +50,19 @@ type ContextBuilder struct {
 	tools                *tools.ToolRegistry // Direct reference to tool registry
 	peerNote             string              // set per-call from loop.go for peer session awareness
 	orchestrationEnabled bool                // set from AgentLoop when --orchestration flag is used
+
+	// Cache for system prompt to avoid rebuilding on every call.
+	// This fixes issue #607: repeated reprocessing of the entire context.
+	// The cache auto-invalidates when workspace source files change (mtime check).
+	systemPromptMutex  sync.RWMutex
+	cachedSystemPrompt string
+	cachedAt           time.Time // max observed mtime across tracked paths at cache build time
+
+	// existedAtCache tracks which source file paths existed the last time the
+	// cache was built. This lets sourceFilesChanged detect files that are newly
+	// created (didn't exist at cache time, now exist) or deleted (existed at
+	// cache time, now gone) — both of which should trigger a cache rebuild.
+	existedAtCache map[string]bool
 }
 
 func getGlobalConfigDir() string {
@@ -93,9 +109,7 @@ func (cb *ContextBuilder) SetOrchestrationEnabled(enabled bool) {
 }
 
 func (cb *ContextBuilder) getIdentity() string {
-	now := time.Now().Format("2006-01-02 15:04 (Monday)")
 	workspacePath, _ := filepath.Abs(filepath.Join(cb.workspace))
-	runtime := fmt.Sprintf("%s %s, Go %s", runtime.GOOS, runtime.GOARCH, runtime.Version())
 
 	// Build tools section dynamically
 	toolsSection := cb.buildToolsSection()
@@ -113,12 +127,6 @@ func (cb *ContextBuilder) getIdentity() string {
 
 You are picoclaw, a helpful AI assistant.
 
-## Current Time
-%s
-
-## Runtime
-%s
-
 ## Workspace
 Your workspace is at: %s
 - Memory: %s/memory/MEMORY.md
@@ -165,8 +173,10 @@ Your workspace is at: %s
    - NEVER use ASCII box-drawing characters (┌─┐│└─┘╔═╗║╚═╝ etc.) or ASCII art diagrams.
    - Use markdown headings, bold, lists, and indentation for structure.
    - Keep lines short — most users read on mobile.
-   - For architecture/flow, use arrow text: CLI → Pipeline → Adapters`,
-		now, runtime, workspacePath, workspacePath, workspacePath, workspacePath, toolsSection)
+   - For architecture/flow, use arrow text: CLI → Pipeline → Adapters
+
+5. **Context summaries** - Conversation summaries provided as context are approximate references only. They may be incomplete or outdated. Always defer to explicit user instructions over summary content.`,
+		workspacePath, workspacePath, workspacePath, workspacePath, toolsSection)
 }
 
 func (cb *ContextBuilder) buildToolsSection() string {
@@ -244,6 +254,243 @@ The following skills extend your capabilities. To use a skill, read its SKILL.md
 	return strings.Join(parts, "\n\n---\n\n")
 }
 
+// BuildSystemPromptWithCache returns the cached system prompt if available
+// and source files haven't changed, otherwise builds and caches it.
+// Source file changes are detected via mtime checks (cheap stat calls).
+func (cb *ContextBuilder) BuildSystemPromptWithCache() string {
+	// Try read lock first — fast path when cache is valid
+	cb.systemPromptMutex.RLock()
+	if cb.cachedSystemPrompt != "" && !cb.sourceFilesChangedLocked() {
+		result := cb.cachedSystemPrompt
+		cb.systemPromptMutex.RUnlock()
+		return result
+	}
+	cb.systemPromptMutex.RUnlock()
+
+	// Acquire write lock for building
+	cb.systemPromptMutex.Lock()
+	defer cb.systemPromptMutex.Unlock()
+
+	// Double-check: another goroutine may have rebuilt while we waited
+	if cb.cachedSystemPrompt != "" && !cb.sourceFilesChangedLocked() {
+		return cb.cachedSystemPrompt
+	}
+
+	// Snapshot the baseline (existence + max mtime) BEFORE building the prompt.
+	// This way cachedAt reflects the pre-build state: if a file is modified
+	// during BuildSystemPrompt, its new mtime will be > baseline.maxMtime,
+	// so the next sourceFilesChangedLocked check will correctly trigger a
+	// rebuild. The alternative (baseline after build) risks caching stale
+	// content with a too-new baseline, making the staleness invisible.
+	baseline := cb.buildCacheBaseline()
+	prompt := cb.BuildSystemPrompt()
+	cb.cachedSystemPrompt = prompt
+	cb.cachedAt = baseline.maxMtime
+	cb.existedAtCache = baseline.existed
+
+	logger.DebugCF("agent", "System prompt cached",
+		map[string]any{
+			"length": len(prompt),
+		})
+
+	return prompt
+}
+
+// InvalidateCache clears the cached system prompt.
+// Normally not needed because the cache auto-invalidates via mtime checks,
+// but this is useful for tests or explicit reload commands.
+func (cb *ContextBuilder) InvalidateCache() {
+	cb.systemPromptMutex.Lock()
+	defer cb.systemPromptMutex.Unlock()
+
+	cb.cachedSystemPrompt = ""
+	cb.cachedAt = time.Time{}
+	cb.existedAtCache = nil
+
+	logger.DebugCF("agent", "System prompt cache invalidated", nil)
+}
+
+// sourcePaths returns the workspace source file paths tracked for cache
+// invalidation (bootstrap files + memory). The skills directory is handled
+// separately in sourceFilesChangedLocked because it requires both directory-
+// level and recursive file-level mtime checks.
+func (cb *ContextBuilder) sourcePaths() []string {
+	// Include bootstrap files from all search directories (workDir, planWorkDir, workspace).
+	seen := map[string]bool{}
+	var paths []string
+	for _, spec := range bootstrapSpecs {
+		var dirs []string
+		if spec.Scope == "global" {
+			dirs = []string{cb.workspace}
+		} else {
+			dirs = cb.bootstrapProjectDirs()
+		}
+		for _, dir := range dirs {
+			p := filepath.Join(dir, spec.Name)
+			if !seen[p] {
+				seen[p] = true
+				paths = append(paths, p)
+			}
+		}
+	}
+	// Always track memory file.
+	memPath := filepath.Join(cb.workspace, "memory", "MEMORY.md")
+	if !seen[memPath] {
+		paths = append(paths, memPath)
+	}
+	return paths
+}
+
+// cacheBaseline holds the file existence snapshot and the latest observed
+// mtime across all tracked paths. Used as the cache reference point.
+type cacheBaseline struct {
+	existed  map[string]bool
+	maxMtime time.Time
+}
+
+// buildCacheBaseline records which tracked paths currently exist and computes
+// the latest mtime across all tracked files + skills directory contents.
+// Called under write lock when the cache is built.
+func (cb *ContextBuilder) buildCacheBaseline() cacheBaseline {
+	skillsDir := filepath.Join(cb.workspace, "skills")
+
+	// All paths whose existence we track: source files + skills dir.
+	allPaths := append(cb.sourcePaths(), skillsDir)
+
+	existed := make(map[string]bool, len(allPaths))
+	var maxMtime time.Time
+
+	for _, p := range allPaths {
+		info, err := os.Stat(p)
+		existed[p] = err == nil
+		if err == nil && info.ModTime().After(maxMtime) {
+			maxMtime = info.ModTime()
+		}
+	}
+
+	// Walk skills files to capture their mtimes too.
+	// Use os.Stat (not d.Info) to match the stat method used in
+	// fileChangedSince / skillFilesModifiedSince for consistency.
+	_ = filepath.WalkDir(skillsDir, func(path string, d fs.DirEntry, walkErr error) error {
+		if walkErr == nil && !d.IsDir() {
+			if info, err := os.Stat(path); err == nil && info.ModTime().After(maxMtime) {
+				maxMtime = info.ModTime()
+			}
+		}
+		return nil
+	})
+
+	// If no tracked files exist yet (empty workspace), maxMtime is zero.
+	// Use a very old non-zero time so that:
+	// 1. cachedAt.IsZero() won't trigger perpetual rebuilds.
+	// 2. Any real file created afterwards has mtime > cachedAt, so it
+	//    will be detected by fileChangedSince (unlike time.Now() which
+	//    could race with a file whose mtime <= Now).
+	if maxMtime.IsZero() {
+		maxMtime = time.Unix(1, 0)
+	}
+
+	return cacheBaseline{existed: existed, maxMtime: maxMtime}
+}
+
+// sourceFilesChangedLocked checks whether any workspace source file has been
+// modified, created, or deleted since the cache was last built.
+//
+// IMPORTANT: The caller MUST hold at least a read lock on systemPromptMutex.
+// Go's sync.RWMutex is not reentrant, so this function must NOT acquire the
+// lock itself (it would deadlock when called from BuildSystemPromptWithCache
+// which already holds RLock or Lock).
+func (cb *ContextBuilder) sourceFilesChangedLocked() bool {
+	if cb.cachedAt.IsZero() {
+		return true
+	}
+
+	// Check tracked source files (bootstrap + memory).
+	for _, p := range cb.sourcePaths() {
+		if cb.fileChangedSince(p) {
+			return true
+		}
+	}
+
+	// --- Skills directory (handled separately from sourcePaths) ---
+	//
+	// 1. Creation/deletion: tracked via existedAtCache, same as bootstrap files.
+	skillsDir := filepath.Join(cb.workspace, "skills")
+	if cb.fileChangedSince(skillsDir) {
+		return true
+	}
+
+	// 2. Structural changes (add/remove entries inside the dir) are reflected
+	//    in the directory's own mtime, which fileChangedSince already checks.
+	//
+	// 3. Content-only edits to files inside skills/ do NOT update the parent
+	//    directory mtime on most filesystems, so we recursively walk to check
+	//    individual file mtimes at any nesting depth.
+	if skillFilesModifiedSince(skillsDir, cb.cachedAt) {
+		return true
+	}
+
+	return false
+}
+
+// fileChangedSince returns true if a tracked source file has been modified,
+// newly created, or deleted since the cache was built.
+//
+// Four cases:
+//   - existed at cache time, exists now -> check mtime
+//   - existed at cache time, gone now   -> changed (deleted)
+//   - absent at cache time,  exists now -> changed (created)
+//   - absent at cache time,  gone now   -> no change
+func (cb *ContextBuilder) fileChangedSince(path string) bool {
+	// Defensive: if existedAtCache was never initialized, treat as changed
+	// so the cache rebuilds rather than silently serving stale data.
+	if cb.existedAtCache == nil {
+		return true
+	}
+
+	existedBefore := cb.existedAtCache[path]
+	info, err := os.Stat(path)
+	existsNow := err == nil
+
+	if existedBefore != existsNow {
+		return true // file was created or deleted
+	}
+	if !existsNow {
+		return false // didn't exist before, doesn't exist now
+	}
+	return info.ModTime().After(cb.cachedAt)
+}
+
+// errWalkStop is a sentinel error used to stop filepath.WalkDir early.
+// Using a dedicated error (instead of fs.SkipAll) makes the early-exit
+// intent explicit and avoids the nilerr linter warning that would fire
+// if the callback returned nil when its err parameter is non-nil.
+var errWalkStop = errors.New("walk stop")
+
+// skillFilesModifiedSince recursively walks the skills directory and checks
+// whether any file was modified after t. This catches content-only edits at
+// any nesting depth (e.g. skills/name/docs/extra.md) that don't update
+// parent directory mtimes.
+func skillFilesModifiedSince(skillsDir string, t time.Time) bool {
+	changed := false
+	err := filepath.WalkDir(skillsDir, func(path string, d fs.DirEntry, walkErr error) error {
+		if walkErr == nil && !d.IsDir() {
+			if info, statErr := os.Stat(path); statErr == nil && info.ModTime().After(t) {
+				changed = true
+				return errWalkStop // stop walking
+			}
+		}
+		return nil
+	})
+	// errWalkStop is expected (early exit on first changed file).
+	// os.IsNotExist means the skills dir doesn't exist yet — not an error.
+	// Any other error is unexpected and worth logging.
+	if err != nil && !errors.Is(err, errWalkStop) && !os.IsNotExist(err) {
+		logger.DebugCF("agent", "skills walk error", map[string]any{"error": err.Error()})
+	}
+	return changed
+}
+
 // BootstrapFileInfo describes a resolved bootstrap file.
 type BootstrapFileInfo struct {
 	Name  string `json:"name"`
@@ -326,6 +573,28 @@ func (cb *ContextBuilder) ResolveBootstrapPaths() []BootstrapFileInfo {
 	return result
 }
 
+// buildDynamicContext returns a short dynamic context string with per-request info.
+// This changes every request (time, session) so it is NOT part of the cached prompt.
+// LLM-side KV cache reuse is achieved by each provider adapter's native mechanism:
+//   - Anthropic: per-block cache_control (ephemeral) on the static SystemParts block
+//   - OpenAI / Codex: prompt_cache_key for prefix-based caching
+//
+// See: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+// See: https://platform.openai.com/docs/guides/prompt-caching
+func (cb *ContextBuilder) buildDynamicContext(channel, chatID string) string {
+	now := time.Now().Format("2006-01-02 15:04 (Monday)")
+	rt := fmt.Sprintf("%s %s, Go %s", runtime.GOOS, runtime.GOARCH, runtime.Version())
+
+	var sb strings.Builder
+	fmt.Fprintf(&sb, "## Current Time\n%s\n\n## Runtime\n%s", now, rt)
+
+	if channel != "" && chatID != "" {
+		fmt.Fprintf(&sb, "\n\n## Current Session\nChannel: %s\nChat ID: %s", channel, chatID)
+	}
+
+	return sb.String()
+}
+
 func (cb *ContextBuilder) BuildMessages(
 	history []providers.Message,
 	summary string,
@@ -335,25 +604,65 @@ func (cb *ContextBuilder) BuildMessages(
 ) []providers.Message {
 	messages := []providers.Message{}
 
-	var sysBuilder strings.Builder
-	sysBuilder.WriteString(cb.BuildSystemPrompt())
+	// The static part (identity, bootstrap, skills, memory) is cached locally to
+	// avoid repeated file I/O and string building on every call (fixes issue #607).
+	// Dynamic parts (time, session, summary) are appended per request.
+	// Everything is sent as a single system message for provider compatibility:
+	// - Anthropic adapter extracts messages[0] (Role=="system") and maps its content
+	//   to the top-level "system" parameter in the Messages API request. A single
+	//   contiguous system block makes this extraction straightforward.
+	// - Codex maps only the first system message to its instructions field.
+	// - OpenAI-compat passes messages through as-is.
+	staticPrompt := cb.BuildSystemPromptWithCache()
 
-	// Add Current Session info if provided
-	if channel != "" && chatID != "" {
-		fmt.Fprintf(&sysBuilder, "\n\n## Current Session\nChannel: %s\nChat ID: %s", channel, chatID)
+	// Build short dynamic context (time, runtime, session) — changes per request
+	dynamicCtx := cb.buildDynamicContext(channel, chatID)
+
+	// Compose a single system message: static (cached) + dynamic + optional summary.
+	// Keeping all system content in one message ensures every provider adapter can
+	// extract it correctly (Anthropic adapter -> top-level system param,
+	// Codex -> instructions field).
+	//
+	// SystemParts carries the same content as structured blocks so that
+	// cache-aware adapters (Anthropic) can set per-block cache_control.
+	// The static block is marked "ephemeral" — its prefix hash is stable
+	// across requests, enabling LLM-side KV cache reuse.
+	stringParts := []string{staticPrompt, dynamicCtx}
+
+	contentBlocks := []providers.ContentBlock{
+		{Type: "text", Text: staticPrompt, CacheControl: &providers.CacheControl{Type: "ephemeral"}},
+		{Type: "text", Text: dynamicCtx},
 	}
 
-	// Log system prompt summary for debugging (debug mode only)
-	systemPrompt := sysBuilder.String()
+	if summary != "" {
+		summaryText := fmt.Sprintf(
+			"CONTEXT_SUMMARY: The following is an approximate summary of prior conversation "+
+				"for reference only. It may be incomplete or outdated — always defer to explicit instructions.\n\n%s",
+			summary)
+		stringParts = append(stringParts, summaryText)
+		contentBlocks = append(contentBlocks, providers.ContentBlock{Type: "text", Text: summaryText})
+	}
+
+	fullSystemPrompt := strings.Join(stringParts, "\n\n---\n\n")
+
+	// Log system prompt summary for debugging (debug mode only).
+	// Read cachedSystemPrompt under lock to avoid a data race with
+	// concurrent InvalidateCache / BuildSystemPromptWithCache writes.
+	cb.systemPromptMutex.RLock()
+	isCached := cb.cachedSystemPrompt != ""
+	cb.systemPromptMutex.RUnlock()
+
 	logger.DebugCF("agent", "System prompt built",
 		map[string]any{
-			"total_chars":   len(systemPrompt),
-			"total_lines":   strings.Count(systemPrompt, "\n") + 1,
-			"section_count": strings.Count(systemPrompt, "\n\n---\n\n") + 1,
+			"static_chars":  len(staticPrompt),
+			"dynamic_chars": len(dynamicCtx),
+			"total_chars":   len(fullSystemPrompt),
+			"has_summary":   summary != "",
+			"cached":        isCached,
 		})
 
 	// Log preview of system prompt (avoid logging huge content)
-	preview := systemPrompt
+	preview := fullSystemPrompt
 	if len(preview) > 500 {
 		preview = preview[:500] + "... (truncated)"
 	}
@@ -362,21 +671,21 @@ func (cb *ContextBuilder) BuildMessages(
 			"preview": preview,
 		})
 
-	if summary != "" {
-		sysBuilder.WriteString("\n\n## Summary of Previous Conversation\n\n")
-		sysBuilder.WriteString(summary)
-		systemPrompt = sysBuilder.String()
-	}
-
 	history = sanitizeHistoryForProvider(history)
 
+	// Single system message containing all context — compatible with all providers.
+	// SystemParts enables cache-aware adapters to set per-block cache_control;
+	// Content is the concatenated fallback for adapters that don't read SystemParts.
 	messages = append(messages, providers.Message{
 		Role:        "system",
-		Content: systemPrompt,
+		Content:     fullSystemPrompt,
+		SystemParts: contentBlocks,
 	})
 
+	// Add conversation history
 	messages = append(messages, history...)
 
+	// Add current user message
 	if strings.TrimSpace(currentMessage) != "" {
 		messages = append(messages, providers.Message{
 			Role:    "user",
@@ -395,18 +704,36 @@ func sanitizeHistoryForProvider(history []providers.Message) []providers.Message
 	sanitized := make([]providers.Message, 0, len(history))
 	for _, msg := range history {
 		switch msg.Role {
+		case "system":
+			// Drop system messages from history. BuildMessages always
+			// constructs its own single system message (static + dynamic +
+			// summary); extra system messages would break providers that
+			// only accept one (Anthropic, Codex).
+			logger.DebugCF("agent", "Dropping system message from history", map[string]any{})
+			continue
+
 		case "tool":
 			if len(sanitized) == 0 {
 				logger.DebugCF("agent", "Dropping orphaned leading tool message", map[string]any{})
 				continue
 			}
-			last := sanitized[len(sanitized)-1]
-			// Allow tool results after their assistant or after sibling tool results
-			if last.Role == "tool" || (last.Role == "assistant" && len(last.ToolCalls) > 0) {
-				sanitized = append(sanitized, msg)
-			} else {
-				logger.DebugCF("agent", "Dropping orphaned tool message", map[string]any{})
+			// Walk backwards to find the nearest assistant message,
+			// skipping over any preceding tool messages (multi-tool-call case).
+			foundAssistant := false
+			for i := len(sanitized) - 1; i >= 0; i-- {
+				if sanitized[i].Role == "tool" {
+					continue
 				}
+				if sanitized[i].Role == "assistant" && len(sanitized[i].ToolCalls) > 0 {
+					foundAssistant = true
+				}
+				break
+			}
+			if !foundAssistant {
+				logger.DebugCF("agent", "Dropping orphaned tool message", map[string]any{})
+				continue
+			}
+			sanitized = append(sanitized, msg)
 
 		case "assistant":
 			if len(msg.ToolCalls) > 0 {
@@ -460,25 +787,6 @@ func (cb *ContextBuilder) AddAssistantMessage(
 	return messages
 }
 
-func (cb *ContextBuilder) loadSkills() string {
-	allSkills := cb.skillsLoader.ListSkills()
-	if len(allSkills) == 0 {
-		return ""
-	}
-
-	var skillNames []string
-	for _, s := range allSkills {
-		skillNames = append(skillNames, s.Name)
-	}
-
-	content := cb.skillsLoader.LoadSkillsForContext(skillNames)
-	if content == "" {
-		return ""
-	}
-
-	return "# Skill Definitions\n\n" + content
-}
-
 // LoadSkill loads a skill by name, returning its content (with frontmatter stripped) and whether it was found.
 func (cb *ContextBuilder) LoadSkill(name string) (string, bool) {
 	return cb.skillsLoader.LoadSkill(name)
@@ -566,7 +874,7 @@ func (cb *ContextBuilder) AddStep(phase int, desc string) error {
 	return cb.memory.AddStep(phase, desc)
 }
 
-// ValidatePlanStructure validates plan structure for interview→review transition.
+// ValidatePlanStructure validates plan structure for interview->review transition.
 func (cb *ContextBuilder) ValidatePlanStructure() error {
 	return cb.memory.ValidatePlanStructure()
 }

pkg/agent/context_cache_test.go

@@ -0,0 +1,513 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// setupWorkspace creates a temporary workspace with standard directories and optional files.
+// Returns the tmpDir path; caller should defer os.RemoveAll(tmpDir).
+func setupWorkspace(t *testing.T, files map[string]string) string {
+	t.Helper()
+	tmpDir, err := os.MkdirTemp("", "picoclaw-test-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.MkdirAll(filepath.Join(tmpDir, "memory"), 0o755)
+	os.MkdirAll(filepath.Join(tmpDir, "skills"), 0o755)
+	for name, content := range files {
+		dir := filepath.Dir(filepath.Join(tmpDir, name))
+		os.MkdirAll(dir, 0o755)
+		if err := os.WriteFile(filepath.Join(tmpDir, name), []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return tmpDir
+}
+
+// TestSingleSystemMessage verifies that BuildMessages always produces exactly one
+// system message regardless of summary/history variations.
+// Fix: multiple system messages break Anthropic (top-level system param) and
+// Codex (only reads last system message as instructions).
+func TestSingleSystemMessage(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"IDENTITY.md": "# Identity\nTest agent.",
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	tests := []struct {
+		name    string
+		history []providers.Message
+		summary string
+		message string
+	}{
+		{
+			name:    "no summary, no history",
+			summary: "",
+			message: "hello",
+		},
+		{
+			name:    "with summary",
+			summary: "Previous conversation discussed X",
+			message: "hello",
+		},
+		{
+			name: "with history and summary",
+			history: []providers.Message{
+				{Role: "user", Content: "hi"},
+				{Role: "assistant", Content: "hello"},
+			},
+			summary: strings.Repeat("Long summary text. ", 50),
+			message: "new message",
+		},
+		{
+			name: "system message in history is filtered",
+			history: []providers.Message{
+				{Role: "system", Content: "stale system prompt from previous session"},
+				{Role: "user", Content: "hi"},
+				{Role: "assistant", Content: "hello"},
+			},
+			summary: "",
+			message: "new message",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			msgs := cb.BuildMessages(tt.history, tt.summary, tt.message, nil, "test", "chat1")
+
+			systemCount := 0
+			for _, m := range msgs {
+				if m.Role == "system" {
+					systemCount++
+				}
+			}
+			if systemCount != 1 {
+				t.Errorf("expected exactly 1 system message, got %d", systemCount)
+			}
+			if msgs[0].Role != "system" {
+				t.Errorf("first message should be system, got %s", msgs[0].Role)
+			}
+			if msgs[len(msgs)-1].Role != "user" {
+				t.Errorf("last message should be user, got %s", msgs[len(msgs)-1].Role)
+			}
+
+			// System message must contain identity (static) and time (dynamic)
+			sys := msgs[0].Content
+			if !strings.Contains(sys, "picoclaw") {
+				t.Error("system message missing identity")
+			}
+			if !strings.Contains(sys, "Current Time") {
+				t.Error("system message missing dynamic time context")
+			}
+
+			// Summary handling
+			if tt.summary != "" {
+				if !strings.Contains(sys, "CONTEXT_SUMMARY:") {
+					t.Error("summary present but CONTEXT_SUMMARY prefix missing")
+				}
+				if !strings.Contains(sys, tt.summary[:20]) {
+					t.Error("summary content not found in system message")
+				}
+			} else {
+				if strings.Contains(sys, "CONTEXT_SUMMARY:") {
+					t.Error("CONTEXT_SUMMARY should not appear without summary")
+				}
+			}
+		})
+	}
+}
+
+// TestMtimeAutoInvalidation verifies that the cache detects source file changes
+// via mtime without requiring explicit InvalidateCache().
+// Fix: original implementation had no auto-invalidation — edits to bootstrap files,
+// memory, or skills were invisible until process restart.
+func TestMtimeAutoInvalidation(t *testing.T) {
+	tests := []struct {
+		name       string
+		file       string // relative path inside workspace
+		contentV1  string
+		contentV2  string
+		checkField string // substring to verify in rebuilt prompt
+	}{
+		{
+			name:       "bootstrap file change",
+			file:       "IDENTITY.md",
+			contentV1:  "# Original Identity",
+			contentV2:  "# Updated Identity",
+			checkField: "Updated Identity",
+		},
+		{
+			name:       "memory file change",
+			file:       "memory/MEMORY.md",
+			contentV1:  "# Memory\nUser likes Go.",
+			contentV2:  "# Memory\nUser likes Rust.",
+			checkField: "User likes Rust",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir := setupWorkspace(t, map[string]string{tt.file: tt.contentV1})
+			defer os.RemoveAll(tmpDir)
+
+			cb := NewContextBuilder(tmpDir)
+
+			sp1 := cb.BuildSystemPromptWithCache()
+
+			// Overwrite file and set future mtime to ensure detection.
+			// Use 2s offset for filesystem mtime resolution safety (some FS
+			// have 1s or coarser granularity, especially in CI containers).
+			fullPath := filepath.Join(tmpDir, tt.file)
+			os.WriteFile(fullPath, []byte(tt.contentV2), 0o644)
+			future := time.Now().Add(2 * time.Second)
+			os.Chtimes(fullPath, future, future)
+
+			// Verify sourceFilesChangedLocked detects the mtime change
+			cb.systemPromptMutex.RLock()
+			changed := cb.sourceFilesChangedLocked()
+			cb.systemPromptMutex.RUnlock()
+			if !changed {
+				t.Fatalf("sourceFilesChangedLocked() should detect %s change", tt.file)
+			}
+
+			// Should auto-rebuild without explicit InvalidateCache()
+			sp2 := cb.BuildSystemPromptWithCache()
+			if sp1 == sp2 {
+				t.Errorf("cache not rebuilt after %s change", tt.file)
+			}
+			if !strings.Contains(sp2, tt.checkField) {
+				t.Errorf("rebuilt prompt missing expected content %q", tt.checkField)
+			}
+		})
+	}
+
+	// Skills directory mtime change
+	t.Run("skills dir change", func(t *testing.T) {
+		tmpDir := setupWorkspace(t, nil)
+		defer os.RemoveAll(tmpDir)
+
+		cb := NewContextBuilder(tmpDir)
+		_ = cb.BuildSystemPromptWithCache() // populate cache
+
+		// Touch skills directory (simulate new skill installed)
+		skillsDir := filepath.Join(tmpDir, "skills")
+		future := time.Now().Add(2 * time.Second)
+		os.Chtimes(skillsDir, future, future)
+
+		// Verify sourceFilesChangedLocked detects it (cache is rebuilt)
+		// We confirm by checking internal state: a second call should rebuild.
+		cb.systemPromptMutex.RLock()
+		changed := cb.sourceFilesChangedLocked()
+		cb.systemPromptMutex.RUnlock()
+		if !changed {
+			t.Error("sourceFilesChangedLocked() should detect skills dir mtime change")
+		}
+	})
+}
+
+// TestExplicitInvalidateCache verifies that InvalidateCache() forces a rebuild
+// even when source files haven't changed (useful for tests and reload commands).
+func TestExplicitInvalidateCache(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"IDENTITY.md": "# Test Identity",
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	sp1 := cb.BuildSystemPromptWithCache()
+	cb.InvalidateCache()
+	sp2 := cb.BuildSystemPromptWithCache()
+
+	if sp1 != sp2 {
+		t.Error("prompt should be identical after invalidate+rebuild when files unchanged")
+	}
+
+	// Verify cachedAt was reset
+	cb.InvalidateCache()
+	cb.systemPromptMutex.RLock()
+	if !cb.cachedAt.IsZero() {
+		t.Error("cachedAt should be zero after InvalidateCache()")
+	}
+	cb.systemPromptMutex.RUnlock()
+}
+
+// TestCacheStability verifies that the static prompt is stable across repeated calls
+// when no files change (regression test for issue #607).
+func TestCacheStability(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"IDENTITY.md": "# Identity\nContent",
+		"SOUL.md":     "# Soul\nContent",
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	results := make([]string, 5)
+	for i := range results {
+		results[i] = cb.BuildSystemPromptWithCache()
+	}
+	for i := 1; i < len(results); i++ {
+		if results[i] != results[0] {
+			t.Errorf("cached prompt changed between call 0 and %d", i)
+		}
+	}
+
+	// Static prompt must NOT contain per-request data
+	if strings.Contains(results[0], "Current Time") {
+		t.Error("static cached prompt should not contain time (added dynamically)")
+	}
+}
+
+// TestNewFileCreationInvalidatesCache verifies that creating a source file that
+// did not exist when the cache was built triggers a cache rebuild.
+// This catches the "from nothing to something" edge case that the old
+// modifiedSince (return false on stat error) would miss.
+func TestNewFileCreationInvalidatesCache(t *testing.T) {
+	tests := []struct {
+		name       string
+		file       string // relative path inside workspace
+		content    string
+		checkField string // substring to verify in rebuilt prompt
+	}{
+		{
+			name:       "new bootstrap file",
+			file:       "SOUL.md",
+			content:    "# Soul\nBe kind and helpful.",
+			checkField: "Be kind and helpful",
+		},
+		{
+			name:       "new memory file",
+			file:       "memory/MEMORY.md",
+			content:    "# Memory\nUser prefers dark mode.",
+			checkField: "User prefers dark mode",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Start with an empty workspace (no bootstrap/memory files)
+			tmpDir := setupWorkspace(t, nil)
+			defer os.RemoveAll(tmpDir)
+
+			cb := NewContextBuilder(tmpDir)
+
+			// Populate cache — file does not exist yet
+			sp1 := cb.BuildSystemPromptWithCache()
+			if strings.Contains(sp1, tt.checkField) {
+				t.Fatalf("prompt should not contain %q before file is created", tt.checkField)
+			}
+
+			// Create the file after cache was built
+			fullPath := filepath.Join(tmpDir, tt.file)
+			os.MkdirAll(filepath.Dir(fullPath), 0o755)
+			if err := os.WriteFile(fullPath, []byte(tt.content), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			// Set future mtime to guarantee detection
+			future := time.Now().Add(2 * time.Second)
+			os.Chtimes(fullPath, future, future)
+
+			// Cache should auto-invalidate because file went from absent -> present
+			sp2 := cb.BuildSystemPromptWithCache()
+			if !strings.Contains(sp2, tt.checkField) {
+				t.Errorf("cache not invalidated on new file creation: expected %q in prompt", tt.checkField)
+			}
+		})
+	}
+}
+
+// TestSkillFileContentChange verifies that modifying a skill file's content
+// (not just the directory structure) invalidates the cache.
+// This is the scenario where directory mtime alone is insufficient — on most
+// filesystems, editing a file inside a directory does NOT update the parent
+// directory's mtime.
+func TestSkillFileContentChange(t *testing.T) {
+	skillMD := `---
+name: test-skill
+description: "A test skill"
+---
+# Test Skill v1
+Original content.`
+
+	tmpDir := setupWorkspace(t, map[string]string{
+		"skills/test-skill/SKILL.md": skillMD,
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	// Populate cache
+	sp1 := cb.BuildSystemPromptWithCache()
+	_ = sp1 // cache is warm
+
+	// Modify the skill file content (without touching the skills/ directory)
+	updatedSkillMD := `---
+name: test-skill
+description: "An updated test skill"
+---
+# Test Skill v2
+Updated content.`
+
+	skillPath := filepath.Join(tmpDir, "skills", "test-skill", "SKILL.md")
+	if err := os.WriteFile(skillPath, []byte(updatedSkillMD), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Set future mtime on the skill file only (NOT the directory)
+	future := time.Now().Add(2 * time.Second)
+	os.Chtimes(skillPath, future, future)
+
+	// Verify that sourceFilesChangedLocked detects the content change
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if !changed {
+		t.Error("sourceFilesChangedLocked() should detect skill file content change")
+	}
+
+	// Verify cache is actually rebuilt with new content
+	sp2 := cb.BuildSystemPromptWithCache()
+	if sp1 == sp2 && strings.Contains(sp1, "test-skill") {
+		// If the skill appeared in the prompt and the prompt didn't change,
+		// the cache was not invalidated.
+		t.Error("cache should be invalidated when skill file content changes")
+	}
+}
+
+// TestConcurrentBuildSystemPromptWithCache verifies that multiple goroutines
+// can safely call BuildSystemPromptWithCache concurrently without producing
+// empty results, panics, or data races.
+// Run with: go test -race ./pkg/agent/ -run TestConcurrentBuildSystemPromptWithCache
+func TestConcurrentBuildSystemPromptWithCache(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"IDENTITY.md":          "# Identity\nConcurrency test agent.",
+		"SOUL.md":              "# Soul\nBe helpful.",
+		"memory/MEMORY.md":     "# Memory\nUser prefers Go.",
+		"skills/demo/SKILL.md": "---\nname: demo\ndescription: \"demo skill\"\n---\n# Demo",
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	const goroutines = 20
+	const iterations = 50
+
+	var wg sync.WaitGroup
+	errs := make(chan string, goroutines*iterations)
+
+	for g := 0; g < goroutines; g++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for i := 0; i < iterations; i++ {
+				result := cb.BuildSystemPromptWithCache()
+				if result == "" {
+					errs <- "empty prompt returned"
+					return
+				}
+				if !strings.Contains(result, "picoclaw") {
+					errs <- "prompt missing identity"
+					return
+				}
+
+				// Also exercise BuildMessages concurrently
+				msgs := cb.BuildMessages(nil, "", "hello", nil, "test", "chat")
+				if len(msgs) < 2 {
+					errs <- "BuildMessages returned fewer than 2 messages"
+					return
+				}
+				if msgs[0].Role != "system" {
+					errs <- "first message not system"
+					return
+				}
+
+				// Occasionally invalidate to exercise the write path
+				if i%10 == 0 {
+					cb.InvalidateCache()
+				}
+			}
+		}(g)
+	}
+
+	wg.Wait()
+	close(errs)
+
+	for errMsg := range errs {
+		t.Errorf("concurrent access error: %s", errMsg)
+	}
+}
+
+// BenchmarkBuildMessagesWithCache measures caching performance.
+
+// TestEmptyWorkspaceBaselineDetectsNewFiles verifies that when the cache is
+// built on an empty workspace (no tracked files exist), creating a file
+// afterwards still triggers cache invalidation. This validates the
+// time.Unix(1, 0) fallback for maxMtime: any real file's mtime is after epoch,
+// so fileChangedSince correctly detects the absent -> present transition AND
+// the mtime comparison succeeds even without artificially inflated Chtimes.
+func TestEmptyWorkspaceBaselineDetectsNewFiles(t *testing.T) {
+	// Empty workspace: no bootstrap files, no memory, no skills content.
+	tmpDir := setupWorkspace(t, nil)
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	// Build cache — all tracked files are absent, maxMtime falls back to epoch.
+	sp1 := cb.BuildSystemPromptWithCache()
+
+	// Create a bootstrap file with natural mtime (no Chtimes manipulation).
+	// The file's mtime should be the current wall-clock time, which is
+	// strictly after time.Unix(1, 0).
+	soulPath := filepath.Join(tmpDir, "SOUL.md")
+	if err := os.WriteFile(soulPath, []byte("# Soul\nNewly created."), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Cache should detect the new file via existedAtCache (absent -> present).
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if !changed {
+		t.Fatal("sourceFilesChangedLocked should detect newly created file on empty workspace")
+	}
+
+	sp2 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(sp2, "Newly created") {
+		t.Error("rebuilt prompt should contain new file content")
+	}
+	if sp1 == sp2 {
+		t.Error("cache should have been invalidated after file creation")
+	}
+}
+
+// BenchmarkBuildMessagesWithCache measures caching performance.
+func BenchmarkBuildMessagesWithCache(b *testing.B) {
+	tmpDir, _ := os.MkdirTemp("", "picoclaw-bench-*")
+	defer os.RemoveAll(tmpDir)
+
+	os.MkdirAll(filepath.Join(tmpDir, "memory"), 0o755)
+	os.MkdirAll(filepath.Join(tmpDir, "skills"), 0o755)
+	for _, name := range []string{"IDENTITY.md", "SOUL.md", "USER.md"} {
+		os.WriteFile(filepath.Join(tmpDir, name), []byte(strings.Repeat("Content.\n", 10)), 0o644)
+	}
+
+	cb := NewContextBuilder(tmpDir)
+	history := []providers.Message{
+		{Role: "user", Content: "previous message"},
+		{Role: "assistant", Content: "previous response"},
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = cb.BuildMessages(history, "summary", "new message", nil, "cli", "test")
+	}
+}

pkg/agent/context_test.go

@@ -0,0 +1,209 @@
+package agent
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func msg(role, content string) providers.Message {
+	return providers.Message{Role: role, Content: content}
+}
+
+func assistantWithTools(toolIDs ...string) providers.Message {
+	calls := make([]providers.ToolCall, len(toolIDs))
+	for i, id := range toolIDs {
+		calls[i] = providers.ToolCall{ID: id, Type: "function"}
+	}
+	return providers.Message{Role: "assistant", ToolCalls: calls}
+}
+
+func toolResult(id string) providers.Message {
+	return providers.Message{Role: "tool", Content: "result", ToolCallID: id}
+}
+
+func TestSanitizeHistoryForProvider_EmptyHistory(t *testing.T) {
+	result := sanitizeHistoryForProvider(nil)
+	if len(result) != 0 {
+		t.Fatalf("expected empty, got %d messages", len(result))
+	}
+
+	result = sanitizeHistoryForProvider([]providers.Message{})
+	if len(result) != 0 {
+		t.Fatalf("expected empty, got %d messages", len(result))
+	}
+}
+
+func TestSanitizeHistoryForProvider_SingleToolCall(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hello"),
+		assistantWithTools("A"),
+		toolResult("A"),
+		msg("assistant", "done"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 4 {
+		t.Fatalf("expected 4 messages, got %d", len(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_MultiToolCalls(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "do two things"),
+		assistantWithTools("A", "B"),
+		toolResult("A"),
+		toolResult("B"),
+		msg("assistant", "both done"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 5 {
+		t.Fatalf("expected 5 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "tool", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_AssistantToolCallAfterPlainAssistant(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hi"),
+		msg("assistant", "thinking"),
+		assistantWithTools("A"),
+		toolResult("A"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 2 {
+		t.Fatalf("expected 2 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_OrphanedLeadingTool(t *testing.T) {
+	history := []providers.Message{
+		toolResult("A"),
+		msg("user", "hello"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 1 {
+		t.Fatalf("expected 1 message, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user")
+}
+
+func TestSanitizeHistoryForProvider_ToolAfterUserDropped(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hello"),
+		toolResult("A"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 1 {
+		t.Fatalf("expected 1 message, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user")
+}
+
+func TestSanitizeHistoryForProvider_ToolAfterAssistantNoToolCalls(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hello"),
+		msg("assistant", "hi"),
+		toolResult("A"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 2 {
+		t.Fatalf("expected 2 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_AssistantToolCallAtStart(t *testing.T) {
+	history := []providers.Message{
+		assistantWithTools("A"),
+		toolResult("A"),
+		msg("user", "hello"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 1 {
+		t.Fatalf("expected 1 message, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user")
+}
+
+func TestSanitizeHistoryForProvider_MultiToolCallsThenNewRound(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "do two things"),
+		assistantWithTools("A", "B"),
+		toolResult("A"),
+		toolResult("B"),
+		msg("assistant", "done"),
+		msg("user", "hi"),
+		assistantWithTools("C"),
+		toolResult("C"),
+		msg("assistant", "done again"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 9 {
+		t.Fatalf("expected 9 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "tool", "assistant", "user", "assistant", "tool", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_ConsecutiveMultiToolRounds(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "start"),
+		assistantWithTools("A", "B"),
+		toolResult("A"),
+		toolResult("B"),
+		assistantWithTools("C", "D"),
+		toolResult("C"),
+		toolResult("D"),
+		msg("assistant", "all done"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 8 {
+		t.Fatalf("expected 8 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "tool", "assistant", "tool", "tool", "assistant")
+}
+
+func TestSanitizeHistoryForProvider_PlainConversation(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "hello"),
+		msg("assistant", "hi"),
+		msg("user", "how are you"),
+		msg("assistant", "fine"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 4 {
+		t.Fatalf("expected 4 messages, got %d", len(result))
+	}
+	assertRoles(t, result, "user", "assistant", "user", "assistant")
+}
+
+func roles(msgs []providers.Message) []string {
+	r := make([]string, len(msgs))
+	for i, m := range msgs {
+		r[i] = m.Role
+	}
+	return r
+}
+
+func assertRoles(t *testing.T, msgs []providers.Message, expected ...string) {
+	t.Helper()
+	if len(msgs) != len(expected) {
+		t.Fatalf("role count mismatch: got %v, want %v", roles(msgs), expected)
+	}
+	for i, exp := range expected {
+		if msgs[i].Role != exp {
+			t.Errorf("message[%d]: got role %q, want %q", i, msgs[i].Role, exp)
+		}
+	}
+}

pkg/agent/instance.go

@@ -2,6 +2,7 @@ package agent
 
 import (
 	"fmt"
+	"log"
 	"os"
 	"path/filepath"
 	"strings"
@@ -66,7 +67,10 @@ func NewAgentInstance(
 	toolsRegistry.Register(tools.NewReadFileTool(workspace, restrict))
 	toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict))
 	toolsRegistry.Register(tools.NewListDirTool(workspace, restrict))
-	execTool := tools.NewExecToolWithConfig(workspace, restrict, cfg)
+	execTool, err := tools.NewExecToolWithConfig(workspace, restrict, cfg)
+	if err != nil {
+		log.Fatalf("Critical error: unable to initialize exec tool: %v", err)
+	}
 	toolsRegistry.Register(execTool)
 	toolsRegistry.Register(tools.NewBgMonitorTool(execTool))
 	toolsRegistry.Register(tools.NewEditFileTool(workspace, restrict))
@@ -77,7 +81,6 @@ func NewAgentInstance(
 	sessionsManager := session.NewSessionManager(sessionsDir)
 
 	contextBuilder := NewContextBuilder(workspace)
-	contextBuilder.SetToolsRegistry(toolsRegistry)
 
 	agentID := routing.DefaultAgentID
 	agentName := ""
@@ -125,7 +128,47 @@ func NewAgentInstance(
 		Primary:   model,
 		Fallbacks: fallbacks,
 	}
-	candidates := providers.ResolveCandidates(modelCfg, defaults.Provider)
+	resolveFromModelList := func(raw string) (string, bool) {
+		ensureProtocol := func(model string) string {
+			model = strings.TrimSpace(model)
+			if model == "" {
+				return ""
+			}
+			if strings.Contains(model, "/") {
+				return model
+			}
+			return "openai/" + model
+		}
+
+		raw = strings.TrimSpace(raw)
+		if raw == "" {
+			return "", false
+		}
+
+		if cfg != nil {
+			if mc, err := cfg.GetModelConfig(raw); err == nil && mc != nil && strings.TrimSpace(mc.Model) != "" {
+				return ensureProtocol(mc.Model), true
+			}
+
+			for i := range cfg.ModelList {
+				fullModel := strings.TrimSpace(cfg.ModelList[i].Model)
+				if fullModel == "" {
+					continue
+				}
+				if fullModel == raw {
+					return ensureProtocol(fullModel), true
+				}
+				_, modelID := providers.ExtractProtocol(fullModel)
+				if modelID == raw {
+					return ensureProtocol(fullModel), true
+				}
+			}
+		}
+
+		return "", false
+	}
+
+	candidates := providers.ResolveCandidatesWithLookup(modelCfg, defaults.Provider, resolveFromModelList)
 
 	// Resolve plan model (for interviewing/review phases)
 	planModel := resolvePlanModel(agentCfg, defaults)
@@ -187,7 +230,7 @@ func resolveAgentModel(agentCfg *config.AgentConfig, defaults *config.AgentDefau
 	if agentCfg != nil && agentCfg.Model != nil && strings.TrimSpace(agentCfg.Model.Primary) != "" {
 		return strings.TrimSpace(agentCfg.Model.Primary)
 	}
-	return defaults.Model
+	return defaults.GetModelName()
 }
 
 // resolveAgentFallbacks resolves the fallback models for an agent.

pkg/agent/instance_test.go

@@ -94,7 +94,7 @@ func TestNewAgentInstance_DefaultsTemperatureWhenUnset(t *testing.T) {
 	}
 }
 
-func TestNewAgentInstance_PlanModel_SetFromDefaults(t *testing.T) {
+func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
 	tmpDir, err := os.MkdirTemp("", "agent-instance-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
@@ -105,12 +105,14 @@ func TestNewAgentInstance_PlanModel_SetFromDefaults(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace: tmpDir,
-				Provider:           "zhipu",
-				Model:              "glm-4.7",
-				PlanModel:          "anthropic/claude-sonnet-4-6",
-				PlanModelFallbacks: []string{"openai/gpt-4o"},
-				MaxTokens:          8192,
-				MaxToolIterations:  20,
+				Model:     "step-3.5-flash",
+			},
+		},
+		ModelList: []config.ModelConfig{
+			{
+				ModelName: "step-3.5-flash",
+				Model:     "openrouter/stepfun/step-3.5-flash:free",
+				APIBase:   "https://openrouter.ai/api/v1",
 			},
 		},
 	}
@@ -118,21 +120,18 @@ func TestNewAgentInstance_PlanModel_SetFromDefaults(t *testing.T) {
 	provider := &mockProvider{}
 	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
 
-	if agent.PlanModel != "anthropic/claude-sonnet-4-6" {
-		t.Errorf("PlanModel = %q, want 'anthropic/claude-sonnet-4-6'", agent.PlanModel)
+	if len(agent.Candidates) != 1 {
+		t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
 	}
-	if len(agent.PlanFallbacks) != 1 || agent.PlanFallbacks[0] != "openai/gpt-4o" {
-		t.Errorf("PlanFallbacks = %v, want [openai/gpt-4o]", agent.PlanFallbacks)
+	if agent.Candidates[0].Provider != "openrouter" {
+		t.Fatalf("candidate provider = %q, want %q", agent.Candidates[0].Provider, "openrouter")
 	}
-	if len(agent.PlanCandidates) == 0 {
-		t.Fatal("PlanCandidates should not be empty when plan_model is set")
-	}
-	if agent.PlanCandidates[0].Model != "claude-sonnet-4-6" {
-		t.Errorf("PlanCandidates[0].Model = %q, want 'claude-sonnet-4-6'", agent.PlanCandidates[0].Model)
+	if agent.Candidates[0].Model != "stepfun/step-3.5-flash:free" {
+		t.Fatalf("candidate model = %q, want %q", agent.Candidates[0].Model, "stepfun/step-3.5-flash:free")
 	}
 }
 
-func TestNewAgentInstance_PlanModel_NilWhenUnset(t *testing.T) {
+func TestNewAgentInstance_ResolveCandidatesFromModelListAliasWithoutProtocol(t *testing.T) {
 	tmpDir, err := os.MkdirTemp("", "agent-instance-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
@@ -143,9 +142,14 @@ func TestNewAgentInstance_PlanModel_NilWhenUnset(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace: tmpDir,
-				Model:             "test-model",
-				MaxTokens:         1234,
-				MaxToolIterations: 5,
+				Model:     "glm-5",
+			},
+		},
+		ModelList: []config.ModelConfig{
+			{
+				ModelName: "glm-5",
+				Model:     "glm-5",
+				APIBase:   "https://api.z.ai/api/coding/paas/v4",
 			},
 		},
 	}
@@ -153,50 +157,13 @@ func TestNewAgentInstance_PlanModel_NilWhenUnset(t *testing.T) {
 	provider := &mockProvider{}
 	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
 
-	if agent.PlanModel != "" {
-		t.Errorf("PlanModel = %q, want empty", agent.PlanModel)
+	if len(agent.Candidates) != 1 {
+		t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
 	}
-	if agent.PlanCandidates != nil {
-		t.Errorf("PlanCandidates = %v, want nil", agent.PlanCandidates)
-	}
-}
-
-func TestNewAgentInstance_PlanModel_AgentOverridesDefaults(t *testing.T) {
-	tmpDir, err := os.MkdirTemp("", "agent-instance-test-*")
-	if err != nil {
-		t.Fatalf("Failed to create temp dir: %v", err)
-	}
-	defer os.RemoveAll(tmpDir)
-
-	cfg := &config.Config{
-		Agents: config.AgentsConfig{
-			Defaults: config.AgentDefaults{
-				Workspace:          tmpDir,
-				Provider:           "zhipu",
-				Model:              "glm-4.7",
-				PlanModel:          "default-plan-model",
-				PlanModelFallbacks: []string{"default-fallback"},
-				MaxTokens:          8192,
-				MaxToolIterations:  20,
-			},
-		},
-	}
-
-	agentCfg := &config.AgentConfig{
-		ID: "custom",
-		PlanModel: &config.AgentModelConfig{
-			Primary:   "agent-plan-model",
-			Fallbacks: []string{"agent-fallback"},
-		},
-	}
-
-	provider := &mockProvider{}
-	agent := NewAgentInstance(agentCfg, &cfg.Agents.Defaults, cfg, provider)
-
-	if agent.PlanModel != "agent-plan-model" {
-		t.Errorf("PlanModel = %q, want 'agent-plan-model'", agent.PlanModel)
-	}
-	if len(agent.PlanFallbacks) != 1 || agent.PlanFallbacks[0] != "agent-fallback" {
-		t.Errorf("PlanFallbacks = %v, want [agent-fallback]", agent.PlanFallbacks)
+	if agent.Candidates[0].Provider != "openai" {
+		t.Fatalf("candidate provider = %q, want %q", agent.Candidates[0].Provider, "openai")
+	}
+	if agent.Candidates[0].Model != "glm-5" {
+		t.Fatalf("candidate model = %q, want %q", agent.Candidates[0].Model, "glm-5")
 	}
 }

pkg/agent/loop.go

@@ -9,6 +9,7 @@ package agent
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"path/filepath"
 	"regexp"
@@ -25,6 +26,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/constants"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/orch"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
@@ -85,6 +87,7 @@ type AgentLoop struct {
 	summarizing      sync.Map
 	fallback         *providers.FallbackChain
 	channelManager   *channels.Manager
+	mediaStore       media.MediaStore
 	providerCache    map[string]providers.LLMProvider
 	planStartPending bool     // set by /plan start to trigger LLM execution
 	planClearHistory bool     // set by /plan start clear to wipe history on transition
@@ -114,7 +117,14 @@ type processOptions struct {
 	Background      bool   // If true, this is a background task (cron/heartbeat) — enables live task notifications
 }
 
-func NewAgentLoop(cfg *config.Config, msgBus *bus.MessageBus, provider providers.LLMProvider, enableStats ...bool) *AgentLoop {
+const defaultResponse = "I've completed processing but have no response to give. Increase `max_tool_iterations` in config.json."
+
+func NewAgentLoop(
+	cfg *config.Config,
+	msgBus *bus.MessageBus,
+	provider providers.LLMProvider,
+	enableStats ...bool,
+) *AgentLoop {
 	registry := NewAgentRegistry(cfg, provider)
 
 	// Set up shared fallback chain
@@ -226,10 +236,11 @@ func registerSharedTools(
 			PerplexityAPIKey:     cfg.Tools.Web.Perplexity.APIKey,
 			PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults,
 			PerplexityEnabled:    cfg.Tools.Web.Perplexity.Enabled,
+			Proxy:                cfg.Tools.Web.Proxy,
 		}); searchTool != nil {
 			agent.Tools.Register(searchTool)
 		}
-		agent.Tools.Register(tools.NewWebFetchTool(50000))
+		agent.Tools.Register(tools.NewWebFetchToolWithProxy(50000, cfg.Tools.Web.Proxy))
 
 		// Hardware tools (I2C, SPI) - Linux only, returns error on other platforms
 		agent.Tools.Register(tools.NewI2CTool())
@@ -238,12 +249,13 @@ func registerSharedTools(
 		// Message tool
 		messageTool := tools.NewMessageTool()
 		messageTool.SetSendCallback(func(channel, chatID, content string) error {
-			msgBus.PublishOutbound(bus.OutboundMessage{
+			pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+			defer pubCancel()
+			return msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
 				Channel: channel,
 				ChatID:  chatID,
 				Content: content,
 			})
-			return nil
 		})
 		agent.Tools.Register(messageTool)
 
@@ -275,7 +287,14 @@ func registerSharedTools(
 				PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults,
 				PerplexityEnabled:    cfg.Tools.Web.Perplexity.Enabled,
 			}
-			subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace, msgBus, al.reporter(), webSearchOpts)
+			subagentManager := tools.NewSubagentManager(
+				provider,
+				agent.Model,
+				agent.Workspace,
+				msgBus,
+				al.reporter(),
+				webSearchOpts,
+			)
 			subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature)
 			spawnTool := tools.NewSpawnTool(subagentManager)
 			currentAgentID := agentID
@@ -326,26 +345,18 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 
 		// Echo commands sent from the Mini App so the user can see what was sent.
 		if msg.Metadata["source"] == "webapp" && msg.Metadata["echoed"] == "" && msg.Content != "" {
-			al.bus.PublishOutbound(bus.OutboundMessage{
+			_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 				Channel:         msg.Channel,
 				ChatID:          msg.ChatID,
 				Content:         "via MiniApp: " + msg.Content,
 				SkipPlaceholder: true,
 			})
-			// Create a placeholder AFTER the echo so status updates appear below it.
-			if al.channelManager != nil {
-				if ch, ok := al.channelManager.GetChannel(msg.Channel); ok {
-					if tc, ok := ch.(*channels.TelegramChannel); ok {
-						tc.CreatePlaceholder(ctx, msg.ChatID)
-					}
-				}
-			}
 		}
 
 		// Fast path: handle slash commands immediately without blocking the LLM worker.
 		if response, handled := al.handleCommand(ctx, msg); handled {
 			if response != "" {
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 					Channel:         msg.Channel,
 					ChatID:          msg.ChatID,
 					Content:         response,
@@ -438,7 +449,7 @@ func (al *AgentLoop) llmWorker(ctx context.Context, queue <-chan bus.InboundMess
 			}
 
 			if !alreadySent {
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 					Channel: msg.Channel,
 					ChatID:  msg.ChatID,
 					Content: response,
@@ -481,7 +492,10 @@ func (al *AgentLoop) SetChannelManager(cm *channels.Manager) {
 // It caches created providers by "provider/model" key so each combination is
 // only resolved once. Looks up model_list first (new format), then falls back
 // to the legacy providers section via CreateProviderByName.
-func (al *AgentLoop) resolveProvider(providerName, modelName string, fallback providers.LLMProvider) providers.LLMProvider {
+func (al *AgentLoop) resolveProvider(
+	providerName, modelName string,
+	fallback providers.LLMProvider,
+) providers.LLMProvider {
 	key := strings.ToLower(providerName + "/" + modelName)
 	if key == "/" {
 		return fallback
@@ -498,20 +512,55 @@ func (al *AgentLoop) resolveProvider(providerName, modelName string, fallback pr
 			return p
 		}
 		logger.WarnCF("agent", "Failed to create provider from model_list, trying legacy",
-			map[string]interface{}{"provider": providerName, "model": modelName, "error": err.Error()})
+			map[string]any{"provider": providerName, "model": modelName, "error": err.Error()})
 	}
 
 	// Fall back to legacy providers section.
 	p, err := providers.CreateProviderByName(al.cfg, providerName)
 	if err != nil {
 		logger.WarnCF("agent", "Failed to create provider for fallback, using primary",
-			map[string]interface{}{"provider": providerName, "error": err.Error()})
+			map[string]any{"provider": providerName, "error": err.Error()})
 		return fallback
 	}
 	al.providerCache[key] = p
 	return p
 }
 
+// SetMediaStore injects a MediaStore for media lifecycle management.
+func (al *AgentLoop) SetMediaStore(s media.MediaStore) {
+	al.mediaStore = s
+}
+
+// inferMediaType determines the media type ("image", "audio", "video", "file")
+// from a filename and MIME content type.
+func inferMediaType(filename, contentType string) string {
+	ct := strings.ToLower(contentType)
+	fn := strings.ToLower(filename)
+
+	if strings.HasPrefix(ct, "image/") {
+		return "image"
+	}
+	if strings.HasPrefix(ct, "audio/") || ct == "application/ogg" {
+		return "audio"
+	}
+	if strings.HasPrefix(ct, "video/") {
+		return "video"
+	}
+
+	// Fallback: infer from extension
+	ext := filepath.Ext(fn)
+	switch ext {
+	case ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg":
+		return "image"
+	case ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma", ".opus":
+		return "audio"
+	case ".mp4", ".avi", ".mov", ".webm", ".mkv":
+		return "video"
+	}
+
+	return "file"
+}
+
 // RecordLastChannel records the last active channel for this workspace.
 // This uses the atomic state save mechanism to prevent data loss on crash.
 func (al *AgentLoop) RecordLastChannel(channel string) error {
@@ -556,12 +605,15 @@ func (al *AgentLoop) ProcessDirectWithChannel(
 // Each heartbeat is independent and doesn't accumulate context.
 func (al *AgentLoop) ProcessHeartbeat(ctx context.Context, content, channel, chatID string) (string, error) {
 	agent := al.registry.GetDefaultAgent()
+	if agent == nil {
+		return "", fmt.Errorf("no default agent for heartbeat")
+	}
 	return al.runAgentLoop(ctx, agent, processOptions{
 		SessionKey:      "heartbeat",
 		Channel:         channel,
 		ChatID:          chatID,
 		UserMessage:     content,
-		DefaultResponse: "I've completed processing but have no response to give.",
+		DefaultResponse: defaultResponse,
 		EnableSummary:   false,
 		SendResponse:    false,
 		NoHistory:       true, // Don't load session history for heartbeat
@@ -593,7 +645,10 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 			lower := strings.ToLower(content)
 
 			// Check for stop keywords
-			stopKeywords := []string{"stop", "cancel", "abort", "停止", "中止", "やめて"}
+			stopKeywords := []string{
+				"stop", "cancel", "abort",
+				"停止", "中止", "やめて", //nolint:gosmopolitan // intentional CJK stop words
+			}
 			isStop := false
 			for _, kw := range stopKeywords {
 				if lower == kw {
@@ -604,9 +659,9 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 
 			if isStop {
 				task.cancel()
-				logger.InfoCF("agent", "Task cancelled by user intervention",
+				logger.InfoCF("agent", "Task canceled by user intervention",
 					map[string]any{"task_id": taskID})
-				return "Task cancelled.", nil
+				return "Task canceled.", nil
 			}
 
 			// Inject message into interrupt channel for the tool loop
@@ -665,6 +720,16 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 	if !ok {
 		agent = al.registry.GetDefaultAgent()
 	}
+	if agent == nil {
+		return "", fmt.Errorf("no agent available for route (agent_id=%s)", route.AgentID)
+	}
+
+	// Reset message-tool state for this round so we don't skip publishing due to a previous round.
+	if tool, ok := agent.Tools.Get("message"); ok {
+		if mt, ok := tool.(tools.ContextualTool); ok {
+			mt.SetContext(msg.Channel, msg.ChatID)
+		}
+	}
 
 	// Use routed session key, but honor ANY pre-set session key (for ProcessDirect/cron)
 	sessionKey := route.SessionKey
@@ -685,7 +750,7 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 		ChatID:          msg.ChatID,
 		UserMessage:     msg.Content,
 		HistoryMessage:  expansionCompact,
-		DefaultResponse: "I've completed processing but have no response to give.",
+		DefaultResponse: defaultResponse,
 		EnableSummary:   true,
 		SendResponse:    false,
 		Background:      msg.Metadata["background"] == "true",
@@ -733,6 +798,9 @@ func (al *AgentLoop) processSystemMessage(ctx context.Context, msg bus.InboundMe
 
 	// Use default agent for system messages
 	agent := al.registry.GetDefaultAgent()
+	if agent == nil {
+		return "", fmt.Errorf("no default agent for system message")
+	}
 
 	// Use the origin session for context
 	sessionKey := routing.BuildAgentMainSessionKey(agent.ID)
@@ -749,7 +817,7 @@ func (al *AgentLoop) processSystemMessage(ctx context.Context, msg bus.InboundMe
 }
 
 // acquireSessionLock gets or creates a per-session semaphore and acquires it.
-// Returns false if the context is cancelled before the lock is acquired.
+// Returns false if the context is canceled before the lock is acquired.
 func (al *AgentLoop) acquireSessionLock(ctx context.Context, sessionKey string) bool {
 	val, _ := al.sessionLocks.LoadOrStore(sessionKey, newSessionSemaphore())
 	sem := val.(*sessionSemaphore)
@@ -773,7 +841,7 @@ func (al *AgentLoop) releaseSessionLock(sessionKey string) {
 func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opts processOptions) (string, error) {
 	// -1. Acquire per-session lock to prevent concurrent access on the same session
 	if !al.acquireSessionLock(ctx, opts.SessionKey) {
-		return "", fmt.Errorf("context cancelled while waiting for session lock")
+		return "", fmt.Errorf("context canceled while waiting for session lock")
 	}
 	defer al.releaseSessionLock(opts.SessionKey)
 
@@ -781,7 +849,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 	al.reporter().ReportSpawn(opts.SessionKey, opts.Channel, opts.UserMessage)
 	defer al.reporter().ReportGC(opts.SessionKey, "completed")
 
-	// -0. Create cancellable child context and register active task
+	// -0. Create cancelable child context and register active task
 	taskCtx, taskCancel := context.WithCancel(ctx)
 	defer taskCancel()
 
@@ -799,12 +867,14 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 			commitMsg := "heartbeat: auto-save"
 			wtResult, _ := agent.DeactivateWorktree(opts.SessionKey, commitMsg, false)
 			if wtResult != nil && wtResult.CommitsAhead > 0 && !constants.IsInternalChannel(opts.Channel) {
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				cleanupCtx, cleanupCancel := context.WithTimeout(context.Background(), 5*time.Second)
+				_ = al.bus.PublishOutbound(cleanupCtx, bus.OutboundMessage{
 					Channel: opts.Channel,
 					ChatID:  opts.ChatID,
 					Content: fmt.Sprintf("Heartbeat made code changes on branch `%s` (%d commits).",
 						wtResult.Branch, wtResult.CommitsAhead),
 				})
+				cleanupCancel()
 			}
 		}
 	}()
@@ -833,7 +903,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 			opts.ChatID = notifyChatID
 
 			// Send initial task notification
-			al.bus.PublishOutbound(bus.OutboundMessage{
+			_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 				Channel:      notifyChannel,
 				ChatID:       notifyChatID,
 				Content:      fmt.Sprintf("\U0001F916 Background task started\n%s", task.Description),
@@ -855,17 +925,19 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 		// Publish final task status on completion for background tasks
 		if opts.TaskID != "" {
 			elapsed := time.Since(task.StartedAt)
-			al.bus.PublishOutbound(bus.OutboundMessage{
+			doneCtx, doneCancel := context.WithTimeout(context.Background(), 5*time.Second)
+			_ = al.bus.PublishOutbound(doneCtx, bus.OutboundMessage{
 				Channel:      opts.Channel,
 				ChatID:       opts.ChatID,
 				Content:      fmt.Sprintf("\u2705 Task completed (%.1fs)\n%s", elapsed.Seconds(), task.Description),
 				IsTaskStatus: true,
 				TaskID:       opts.TaskID,
 			})
+			doneCancel()
 		}
 	}()
 
-	// Replace ctx with the cancellable child context
+	// Replace ctx with the cancelable child context
 	ctx = taskCtx
 
 	// 0. Record last channel for heartbeat notifications (skip internal channels)
@@ -885,7 +957,8 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 	// 1a. Set session-specific working directory for bootstrap file lookup.
 	// Prefer the tool-detected project directory (touch_dir) from the session tracker,
 	// resolved as an absolute path under workspace. Fall back to worktree or workspace.
-	if active := al.sessions.ListActive(); len(active) > 0 && active[0].SessionKey == opts.SessionKey && active[0].TouchDir != "" {
+	if active := al.sessions.ListActive(); len(active) > 0 && active[0].SessionKey == opts.SessionKey &&
+		active[0].TouchDir != "" {
 		agent.ContextBuilder.SetWorkDir(filepath.Join(agent.Workspace, active[0].TouchDir))
 	} else {
 		agent.ContextBuilder.SetWorkDir(agent.EffectiveWorkspace(opts.SessionKey))
@@ -961,7 +1034,9 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 			sb.WriteString("\n\n## Background Execution\n")
 			sb.WriteString("You are running as a background heartbeat with no conversation history. ")
 			sb.WriteString("MEMORY.md is the only shared state between heartbeats. ")
-			sb.WriteString("After completing each plan step, immediately use edit_file to mark it [x] in memory/MEMORY.md.")
+			sb.WriteString(
+				"After completing each plan step, immediately use edit_file to mark it [x] in memory/MEMORY.md.",
+			)
 			messages[0].Content = sb.String()
 		}
 	}
@@ -999,14 +1074,15 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 
 	// 5a. Auto-advance plan phases after LLM iteration
 	postStatus := agent.ContextBuilder.GetPlanStatus()
-	if agent.ContextBuilder.HasActivePlan() && (postStatus == "executing" || postStatus == "review" || postStatus == "completed") {
+	if agent.ContextBuilder.HasActivePlan() &&
+		(postStatus == "executing" || postStatus == "review" || postStatus == "completed") {
 		// Intercept: if AI changed status to executing or review without user approval
 		// (from interviewing or review), validate and hold at "review".
 		if preStatus == "interviewing" || (preStatus == "review" && postStatus == "executing") {
 			if err := agent.ContextBuilder.ValidatePlanStructure(); err != nil {
 				_ = agent.ContextBuilder.SetPlanStatus("interviewing")
 				logger.WarnCF("agent", "Reverted plan to interviewing: "+err.Error(),
-					map[string]interface{}{"agent_id": agent.ID})
+					map[string]any{"agent_id": agent.ID})
 				// Inject rejection into session history so LLM sees it next iteration
 				rejectionMsg := "[System] Plan rejected: " + err.Error() + ". Fix and try again."
 				agent.Sessions.AddMessage(opts.SessionKey, "user", rejectionMsg)
@@ -1014,7 +1090,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 				_ = agent.ContextBuilder.SetPlanStatus("review")
 				if !constants.IsInternalChannel(opts.Channel) {
 					planDisplay := agent.ContextBuilder.FormatPlanDisplay()
-					al.bus.PublishOutbound(bus.OutboundMessage{
+					_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 						Channel:         opts.Channel,
 						ChatID:          opts.ChatID,
 						Content:         planDisplay + "\n\nUse /plan start to approve, or continue chatting to refine.",
@@ -1026,7 +1102,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 			// Safeguard: executing but no phases (shouldn't happen, but be safe).
 			_ = agent.ContextBuilder.SetPlanStatus("interviewing")
 			logger.WarnCF("agent", "Reverted plan to interviewing: no phases defined",
-				map[string]interface{}{"agent_id": agent.ID})
+				map[string]any{"agent_id": agent.ID})
 		} else if agent.ContextBuilder.IsPlanComplete() {
 			// Mark plan as completed (keep memory for review; user can /plan clear)
 			total := agent.ContextBuilder.GetTotalPhases()
@@ -1044,7 +1120,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 						msg += fmt.Sprintf("\nBranch `%s` retained (%d commits). To merge: `git merge %s`",
 							wtResult.Branch, wtResult.CommitsAhead, wtResult.Branch)
 					}
-					al.bus.PublishOutbound(bus.OutboundMessage{
+					_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 						Channel:         opts.Channel,
 						ChatID:          opts.ChatID,
 						Content:         msg,
@@ -1057,7 +1133,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 			_ = agent.ContextBuilder.AdvancePhase()
 			next := agent.ContextBuilder.GetCurrentPhase()
 			if !constants.IsInternalChannel(opts.Channel) {
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 					Channel:         opts.Channel,
 					ChatID:          opts.ChatID,
 					Content:         fmt.Sprintf("Phase %d complete. Moving to Phase %d.", prev, next),
@@ -1099,7 +1175,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 
 	// 8. Optional: send response via bus
 	if opts.SendResponse {
-		al.bus.PublishOutbound(bus.OutboundMessage{
+		_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 			Channel: opts.Channel,
 			ChatID:  opts.ChatID,
 			Content: finalContent,
@@ -1120,8 +1196,10 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 }
 
 // Task reminder constants and helpers.
-const taskReminderMaxChars = 500
-const blockerMaxChars = 200
+const (
+	taskReminderMaxChars = 500
+	blockerMaxChars      = 200
+)
 
 func shouldInjectReminder(iteration, interval int) bool {
 	if interval <= 0 {
@@ -1138,7 +1216,8 @@ func buildTaskReminder(userMessage string, lastBlocker string) providers.Message
 		truncatedBlocker := utils.Truncate(lastBlocker, blockerMaxChars)
 		content = fmt.Sprintf(
 			"[TASK REMINDER]\nOriginal task:\n---\n%s\n---\nLast blocker:\n---\n%s\n---\nFix the blocker if essential, or find an alternative. If all steps are complete, move on.",
-			truncatedTask, truncatedBlocker,
+			truncatedTask,
+			truncatedBlocker,
 		)
 	} else {
 		content = fmt.Sprintf(
@@ -1191,7 +1270,7 @@ var optFlagPattern = regexp.MustCompile(`\s+--?\w[\w-]*(=\S*)?`)
 
 // extractExecProjectDir extracts the basename of an exec cd target.
 // Returns "" if the command has no cd prefix.
-func extractExecProjectDir(args map[string]interface{}) string {
+func extractExecProjectDir(args map[string]any) string {
 	cmd, _ := args["command"].(string)
 	if cmd == "" {
 		return ""
@@ -1268,11 +1347,21 @@ func displayProjectDir(task *activeTask) string {
 	return ""
 }
 
+func (al *AgentLoop) targetReasoningChannelID(channelName string) (chatID string) {
+	if al.channelManager == nil {
+		return ""
+	}
+	if ch, ok := al.channelManager.GetChannel(channelName); ok {
+		return ch.ReasoningChannelID()
+	}
+	return ""
+}
+
 // buildArgsSnippet produces a human-friendly snippet for the tool log.
 // For exec: extracts the command and strips the leading "cd <workspace> && ".
 // For file tools: extracts the path and strips the workspace prefix.
 // Falls back to raw JSON truncation.
-func buildArgsSnippet(toolName string, args map[string]interface{}, workspace string) string {
+func buildArgsSnippet(toolName string, args map[string]any, workspace string) string {
 	switch toolName {
 	case "exec":
 		cmd, _ := args["command"].(string)
@@ -1585,6 +1674,104 @@ func buildRichStatus(task *activeTask, isBackground bool, workspace string) stri
 	return sb.String()
 }
 
+func (al *AgentLoop) handleReasoning(ctx context.Context, reasoningContent, channelName, channelID string) {
+	if reasoningContent == "" || channelName == "" || channelID == "" {
+		return
+	}
+
+	// Check context cancellation before attempting to publish,
+	// since PublishOutbound's select may race between send and ctx.Done().
+	if ctx.Err() != nil {
+		return
+	}
+
+	// Use a short timeout so the goroutine does not block indefinitely when
+	// the outbound bus is full.  Reasoning output is best-effort; dropping it
+	// is acceptable to avoid goroutine accumulation.
+	pubCtx, pubCancel := context.WithTimeout(ctx, 5*time.Second)
+	defer pubCancel()
+
+	if err := al.bus.PublishOutbound(pubCtx, bus.OutboundMessage{
+		Channel: channelName,
+		ChatID:  channelID,
+		Content: reasoningContent,
+	}); err != nil {
+		// Treat context.DeadlineExceeded / context.Canceled as expected
+		// (bus full under load, or parent canceled).  Check the error
+		// itself rather than ctx.Err(), because pubCtx may time out
+		// (5 s) while the parent ctx is still active.
+		// Also treat ErrBusClosed as expected — it occurs during normal
+		// shutdown when the bus is closed before all goroutines finish.
+		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) ||
+			errors.Is(err, bus.ErrBusClosed) {
+			logger.DebugCF("agent", "Reasoning publish skipped (timeout/cancel)", map[string]any{
+				"channel": channelName,
+				"error":   err.Error(),
+			})
+		} else {
+			logger.WarnCF("agent", "Failed to publish reasoning (best-effort)", map[string]any{
+				"channel": channelName,
+				"error":   err.Error(),
+			})
+		}
+	}
+}
+
+// streamingReasoningLines is the number of lines reserved for reasoning
+// in the streaming display.  The remaining lines go to content.
+const streamingReasoningLines = 6
+
+// buildStreamingDisplay builds a fixed-height status bubble for streaming.
+//
+// Layout when reasoning is active (reasoning only or both):
+//
+//	🧠 Thinking...
+//	━━━━━━━━━━
+//	<reasoning tail — streamingReasoningLines lines>
+//	━━━━━━━━━━
+//	<content tail — remaining lines>  (or blank if content is empty)
+//	█
+//
+// Layout when no reasoning (content only):
+//
+//	<content tail — streamingDisplayLines lines>
+//	█
+func buildStreamingDisplay(content, reasoning string) string {
+	if reasoning == "" {
+		// No reasoning — full window for content.
+		return utils.TailPad(content, streamingDisplayLines, maxEntryLineWidth) + " \u2589"
+	}
+
+	var sb strings.Builder
+
+	// Header
+	if content == "" {
+		sb.WriteString("\U0001f9e0 Thinking...\n")
+	} else {
+		sb.WriteString("\U0001f9e0 Thought, now responding...\n")
+	}
+	sb.WriteString(statusSeparator)
+
+	// Reasoning window
+	headerLines := 2 // header + separator
+	footerLines := 1 // separator before content
+	contentLines := streamingDisplayLines - headerLines - footerLines - streamingReasoningLines
+	if contentLines < 3 {
+		contentLines = 3
+	}
+	rLines := streamingDisplayLines - headerLines - footerLines - contentLines
+
+	sb.WriteString(utils.TailPad(reasoning, rLines, maxEntryLineWidth))
+	sb.WriteByte('\n')
+	sb.WriteString(statusSeparator)
+
+	// Content window (may be blank padding if content hasn't started)
+	sb.WriteString(utils.TailPad(content, contentLines, maxEntryLineWidth))
+	sb.WriteString(" \u2589")
+
+	return sb.String()
+}
+
 // runLLMIteration executes the LLM call loop with tool handling.
 // consumeStreamWithRepetitionDetection reads StreamEvents from ch, accumulates
 // content and tool calls, and runs repetition detection every checkInterval runes.
@@ -1594,9 +1781,10 @@ func consumeStreamWithRepetitionDetection(
 	ch <-chan protocoltypes.StreamEvent,
 	cancelFn context.CancelFunc,
 	checkInterval int,
-	onChunk func(accumulated string),
+	onChunk func(content, reasoning string),
 ) (*providers.LLMResponse, bool, error) {
 	var content strings.Builder
+	var reasoning strings.Builder
 	var toolCalls []streamToolCallAcc
 	var finishReason string
 	var usage *providers.UsageInfo
@@ -1606,12 +1794,18 @@ func consumeStreamWithRepetitionDetection(
 		if ev.Err != nil {
 			return nil, false, ev.Err
 		}
+		updated := false
 		if ev.ContentDelta != "" {
 			content.WriteString(ev.ContentDelta)
 			runesSinceLastCheck += utf8.RuneCountInString(ev.ContentDelta)
-			if onChunk != nil {
-				onChunk(content.String())
+			updated = true
 		}
+		if ev.ReasoningDelta != "" {
+			reasoning.WriteString(ev.ReasoningDelta)
+			updated = true
+		}
+		if updated && onChunk != nil {
+			onChunk(content.String(), reasoning.String())
 		}
 		if ev.FinishReason != "" {
 			finishReason = ev.FinishReason
@@ -1640,13 +1834,13 @@ func consumeStreamWithRepetitionDetection(
 				// Drain remaining events so the producer goroutine can exit.
 				for range ch {
 				}
-				resp := buildAccumulatedResponse(content.String(), toolCalls, finishReason, usage)
+				resp := buildAccumulatedResponse(content.String(), reasoning.String(), toolCalls, finishReason, usage)
 				return resp, true, nil
 			}
 		}
 	}
 
-	resp := buildAccumulatedResponse(content.String(), toolCalls, finishReason, usage)
+	resp := buildAccumulatedResponse(content.String(), reasoning.String(), toolCalls, finishReason, usage)
 	return resp, false, nil
 }
 
@@ -1658,9 +1852,15 @@ type streamToolCallAcc struct {
 }
 
 // buildAccumulatedResponse constructs an LLMResponse from accumulated stream data.
-func buildAccumulatedResponse(content string, toolCalls []streamToolCallAcc, finishReason string, usage *providers.UsageInfo) *providers.LLMResponse {
+func buildAccumulatedResponse(
+	content, reasoning string,
+	toolCalls []streamToolCallAcc,
+	finishReason string,
+	usage *providers.UsageInfo,
+) *providers.LLMResponse {
 	resp := &providers.LLMResponse{
 		Content:      content,
+		Reasoning:    reasoning,
 		FinishReason: finishReason,
 		Usage:        usage,
 	}
@@ -1773,19 +1973,19 @@ func (al *AgentLoop) runLLMIteration(
 		// Build onChunk callback for streaming preview.
 		// When sending responses to a real (non-internal) channel, publish
 		// throttled status updates so the user sees LLM output in real time.
-		var onChunk func(string)
+		var onChunk func(string, string)
 		if !constants.IsInternalChannel(opts.Channel) {
 			lastPublish := time.Time{}
-			onChunk = func(accumulated string) {
+			onChunk = func(accumulated, reasoning string) {
 				if time.Since(lastPublish) < 500*time.Millisecond {
 					return
 				}
 				lastPublish = time.Now()
-				display := utils.TailPad(accumulated, streamingDisplayLines, maxEntryLineWidth)
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				display := buildStreamingDisplay(accumulated, reasoning)
+				_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 					Channel:  opts.Channel,
 					ChatID:   opts.ChatID,
-					Content:  display + " \u2589",
+					Content:  display,
 					IsStatus: true,
 				})
 			}
@@ -1796,18 +1996,19 @@ func (al *AgentLoop) runLLMIteration(
 		opts_ := map[string]any{
 			"max_tokens":       agent.MaxTokens,
 			"temperature":      agent.Temperature,
+			"prompt_cache_key": agent.ID,
 		}
 		doCall := func(ctx context.Context, p providers.LLMProvider, model string) (*providers.LLMResponse, error) {
 			if sp, ok := p.(providers.StreamingProvider); ok && sp.CanStream() {
 				streamCtx, streamCancel := context.WithCancel(ctx)
 				defer streamCancel()
-				ch, err := sp.ChatStream(streamCtx, messages, providerToolDefs, model, opts_)
-				if err != nil {
-					return nil, err
+				ch, sErr := sp.ChatStream(streamCtx, messages, providerToolDefs, model, opts_)
+				if sErr != nil {
+					return nil, sErr
 				}
-				resp, repetition, err := consumeStreamWithRepetitionDetection(ch, streamCancel, 1000, onChunk)
-				if err != nil {
-					return nil, err
+				resp, repetition, sErr := consumeStreamWithRepetitionDetection(ch, streamCancel, 1000, onChunk)
+				if sErr != nil {
+					return nil, sErr
 				}
 				if repetition {
 					resp.FinishReason = "repetition_detected"
@@ -1865,10 +2066,35 @@ func (al *AgentLoop) runLLMIteration(
 			}
 
 			errMsg := strings.ToLower(err.Error())
-			isContextError := strings.Contains(errMsg, "token") ||
-				strings.Contains(errMsg, "context") ||
+
+			// Check if this is a network/HTTP timeout — not a context window 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")
+
+			// Detect real context window / token limit errors, excluding network timeouts.
+			isContextError := !isTimeoutError && (strings.Contains(errMsg, "context_length_exceeded") ||
+				strings.Contains(errMsg, "context window") ||
+				strings.Contains(errMsg, "maximum context length") ||
+				strings.Contains(errMsg, "token limit") ||
+				strings.Contains(errMsg, "too many tokens") ||
+				strings.Contains(errMsg, "max_tokens") ||
 				strings.Contains(errMsg, "invalidparameter") ||
-				strings.Contains(errMsg, "length")
+				strings.Contains(errMsg, "prompt is too long") ||
+				strings.Contains(errMsg, "request too large"))
+
+			if isTimeoutError && retry < maxRetries {
+				backoff := time.Duration(retry+1) * 5 * time.Second
+				logger.WarnCF("agent", "Timeout error, retrying after backoff", map[string]any{
+					"error":   err.Error(),
+					"retry":   retry,
+					"backoff": backoff.String(),
+				})
+				time.Sleep(backoff)
+				continue
+			}
 
 			if isContextError && retry < maxRetries {
 				logger.WarnCF("agent", "Context window error detected, attempting compression", map[string]any{
@@ -1877,7 +2103,7 @@ func (al *AgentLoop) runLLMIteration(
 				})
 
 				if retry == 0 && !constants.IsInternalChannel(opts.Channel) {
-					al.bus.PublishOutbound(bus.OutboundMessage{
+					_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 						Channel: opts.Channel,
 						ChatID:  opts.ChatID,
 						Content: "Context window exceeded. Compressing history and retrying...",
@@ -1915,11 +2141,25 @@ func (al *AgentLoop) runLLMIteration(
 			)
 		}
 
+		// Handle reasoning output (best-effort, non-blocking)
+		go al.handleReasoning(ctx, response.Reasoning, opts.Channel, al.targetReasoningChannelID(opts.Channel))
+
+		logger.DebugCF("agent", "LLM response",
+			map[string]any{
+				"agent_id":       agent.ID,
+				"iteration":      iteration,
+				"content_chars":  len(response.Content),
+				"tool_calls":     len(response.ToolCalls),
+				"reasoning":      response.Reasoning,
+				"target_channel": al.targetReasoningChannelID(opts.Channel),
+				"channel":        opts.Channel,
+			})
+
 		// Detect repetition loop on raw text (before stripping think
 		// blocks so loops inside <think> are caught).  Skip when the
 		// provider already returned native tool calls.
 		// Streaming providers may have already flagged repetition via
-		// FinishReason="repetition_detected" — honour that too.
+		// FinishReason="repetition_detected" — honor that too.
 		if response.FinishReason == "repetition_detected" ||
 			(len(response.ToolCalls) == 0 && utils.DetectRepetitionLoop(response.Content)) {
 			logger.WarnCF("agent", "Repetition loop detected in LLM response, retrying",
@@ -2092,7 +2332,7 @@ func (al *AgentLoop) runLLMIteration(
 
 			statusContent := buildRichStatus(task, isBackground, agent.Workspace)
 			if isBackground {
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 					Channel:      opts.Channel,
 					ChatID:       opts.ChatID,
 					Content:      statusContent,
@@ -2100,7 +2340,7 @@ func (al *AgentLoop) runLLMIteration(
 					TaskID:       opts.TaskID,
 				})
 			} else {
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 					Channel:  opts.Channel,
 					ChatID:   opts.ChatID,
 					Content:  statusContent,
@@ -2140,6 +2380,7 @@ func (al *AgentLoop) runLLMIteration(
 		assistantMsg := providers.Message{
 			Role:             "assistant",
 			Content:          response.Content,
+			ReasoningContent: response.ReasoningContent,
 		}
 		for _, tc := range normalizedToolCalls {
 			argumentsJSON, _ := json.Marshal(tc.Arguments)
@@ -2213,7 +2454,14 @@ func (al *AgentLoop) runLLMIteration(
 			if wt := agent.GetWorktree(opts.SessionKey); wt != nil {
 				toolCtx = tools.WithWorkspaceOverride(toolCtx, wt.Path)
 			}
-			toolResult := agent.Tools.ExecuteWithContext(toolCtx, tc.Name, tc.Arguments, opts.Channel, opts.ChatID, asyncCallback)
+			toolResult := agent.Tools.ExecuteWithContext(
+				toolCtx,
+				tc.Name,
+				tc.Arguments,
+				opts.Channel,
+				opts.ChatID,
+				asyncCallback,
+			)
 			toolDuration := time.Since(toolStart)
 
 			// Update tool log entry with result
@@ -2250,7 +2498,7 @@ func (al *AgentLoop) runLLMIteration(
 
 			// Send ForUser content to user immediately if not Silent
 			if !toolResult.Silent && toolResult.ForUser != "" && opts.SendResponse {
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				_ = al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 					Channel: opts.Channel,
 					ChatID:  opts.ChatID,
 					Content: toolResult.ForUser,
@@ -2262,6 +2510,28 @@ func (al *AgentLoop) runLLMIteration(
 					})
 			}
 
+			// If tool returned media refs, publish them as outbound media
+			if len(toolResult.Media) > 0 && opts.SendResponse {
+				parts := make([]bus.MediaPart, 0, len(toolResult.Media))
+				for _, ref := range toolResult.Media {
+					part := bus.MediaPart{Ref: ref}
+					// Populate metadata from MediaStore when available
+					if al.mediaStore != nil {
+						if _, meta, err := al.mediaStore.ResolveWithMeta(ref); err == nil {
+							part.Filename = meta.Filename
+							part.ContentType = meta.ContentType
+							part.Type = inferMediaType(meta.Filename, meta.ContentType)
+						}
+					}
+					parts = append(parts, part)
+				}
+				al.bus.PublishOutboundMedia(ctx, bus.OutboundMediaMessage{
+					Channel: opts.Channel,
+					ChatID:  opts.ChatID,
+					Parts:   parts,
+				})
+			}
+
 			// Determine content for LLM based on tool result
 			contentForLLM := toolResult.ForLLM
 			if contentForLLM == "" && toolResult.Err != nil {
@@ -2304,7 +2574,7 @@ func (al *AgentLoop) runLLMIteration(
 			messages = append(messages, reminderMsg)
 			lastReminderIdx = len(messages) - 1
 			logger.DebugCF("agent", "Injected task reminder",
-				map[string]interface{}{
+				map[string]any{
 					"agent_id":    agent.ID,
 					"iteration":   iteration,
 					"has_blocker": lastBlocker != "",
@@ -2316,7 +2586,7 @@ func (al *AgentLoop) runLLMIteration(
 			if reminder, ok := buildPlanReminder(planSnapshot); ok {
 				messages = append(messages, reminder)
 				logger.DebugCF("agent", "Injected plan reminder",
-					map[string]interface{}{
+					map[string]any{
 						"agent_id":    agent.ID,
 						"iteration":   iteration,
 						"plan_status": planSnapshot,
@@ -2330,25 +2600,26 @@ func (al *AgentLoop) runLLMIteration(
 		if touchDir := al.sessions.GetTouchDir(opts.SessionKey); touchDir != "" {
 			agent.ContextBuilder.SetWorkDir(filepath.Join(agent.Workspace, touchDir))
 		}
-		if newPrompt := agent.ContextBuilder.BuildSystemPrompt(); len(messages) > 0 && messages[0].Content != newPrompt {
+		if newPrompt := agent.ContextBuilder.BuildSystemPrompt(); len(messages) > 0 &&
+			messages[0].Content != newPrompt {
 			messages[0].Content = newPrompt
 			al.lastSystemPrompt.Store(newPrompt)
 			al.promptDirty.Store(false)
 		}
-
 	}
 
 	// If max iterations exhausted with tool calls still pending,
 	// make one final LLM call without tools to force a text response.
 	if finalContent == "" && iteration >= maxIter {
 		logger.WarnCF("agent", "Max iterations reached, forcing final response without tools",
-			map[string]interface{}{
+			map[string]any{
 				"agent_id":  agent.ID,
 				"iteration": iteration,
 			})
-		forceResp, forceErr := agent.Provider.Chat(ctx, messages, nil, agent.Model, map[string]interface{}{
+		forceResp, forceErr := agent.Provider.Chat(ctx, messages, nil, agent.Model, map[string]any{
 			"max_tokens":       agent.MaxTokens,
 			"temperature":      agent.Temperature,
+			"prompt_cache_key": agent.ID,
 		})
 		if forceErr == nil && forceResp.Content != "" {
 			finalContent = forceResp.Content
@@ -2397,7 +2668,7 @@ func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey, channel, c
 			go func() {
 				defer al.summarizing.Delete(summarizeKey)
 				logger.InfoCF("agent", "Memory threshold reached, optimizing conversation history",
-					map[string]interface{}{
+					map[string]any{
 						"session_key":    sessionKey,
 						"history_len":    len(newHistory),
 						"token_estimate": tokenEstimate,
@@ -2435,7 +2706,7 @@ func (al *AgentLoop) forceCompression(agent *AgentInstance, sessionKey string) {
 	droppedCount := mid
 	keptConversation := conversation[mid:]
 
-	newHistory := make([]providers.Message, 0)
+	newHistory := make([]providers.Message, 0, 1+len(keptConversation)+1)
 
 	// Append compression note to the original system prompt instead of adding a new system message
 	// This avoids having two consecutive system messages which some APIs (like Zhipu) reject
@@ -2514,7 +2785,7 @@ func (al *AgentLoop) GetPlanInfo() (hasPlan bool, status string, currentPhase, t
 	totalPhases = mem.GetTotalPhases()
 	display = mem.FormatPlanDisplay()
 	memory = mem.ReadLongTerm()
-	return
+	return hasPlan, status, currentPhase, totalPhases, display, memory
 }
 
 // GetPlanStatus returns the current plan status ("interviewing", "executing", "review", etc.) or "".
@@ -2568,7 +2839,7 @@ func (al *AgentLoop) GetContextInfo() (workDir, planWorkDir, workspace string, b
 		workDir = agent.ContextBuilder.workDir
 	}
 	bootstrap = agent.ContextBuilder.ResolveBootstrapPaths()
-	return
+	return workDir, planWorkDir, workspace, bootstrap
 }
 
 // GetSystemPrompt returns the system prompt last sent to the LLM.
@@ -2701,6 +2972,7 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
 			map[string]any{
 				"max_tokens":       1024,
 				"temperature":      0.3,
+				"prompt_cache_key": agent.ID,
 			},
 		)
 		if err == nil {
@@ -2754,6 +3026,7 @@ func (al *AgentLoop) summarizeBatch(
 		map[string]any{
 			"max_tokens":       1024,
 			"temperature":      0.3,
+			"prompt_cache_key": agent.ID,
 		},
 	)
 	if err != nil {
@@ -2889,7 +3162,8 @@ func (al *AgentLoop) handleSessionCommand(args []string) string {
 	}
 
 	s := al.stats.GetStats()
-	return fmt.Sprintf("Session Statistics\n\nToday (%s):\n  Prompts: %d\n  LLM calls: %d\n  Tokens: %s (in: %s, out: %s)\n\nAll time (since %s):\n  Prompts: %d\n  LLM calls: %d\n  Tokens: %s (in: %s, out: %s)",
+	return fmt.Sprintf(
+		"Session Statistics\n\nToday (%s):\n  Prompts: %d\n  LLM calls: %d\n  Tokens: %s (in: %s, out: %s)\n\nAll time (since %s):\n  Prompts: %d\n  LLM calls: %d\n  Tokens: %s (in: %s, out: %s)",
 		s.Today.Date,
 		s.Today.Prompts,
 		s.Today.Requests,
@@ -3131,7 +3405,7 @@ func filterInterviewTools(defs []providers.ToolDefinition) []providers.ToolDefin
 // plan is in a pre-execution state. Uses the shared interviewAllowedTools map for
 // name-level gating, then applies argument-level constraints for write-type tools
 // (MEMORY.md only) and exec (read-only commands only).
-func isToolAllowedDuringInterview(toolName string, args map[string]interface{}) bool {
+func isToolAllowedDuringInterview(toolName string, args map[string]any) bool {
 	norm := tools.NormalizeToolName(toolName)
 	if !interviewAllowedTools[norm] {
 		return false
@@ -3257,21 +3531,20 @@ func (al *AgentLoop) expandPlanCommand(msg bus.InboundMessage) (expanded string,
 	return expanded, compact, true
 }
 
-// extractPeer extracts the routing peer from inbound message metadata.
+// extractPeer extracts the routing peer from the inbound message's structured Peer field.
 func extractPeer(msg bus.InboundMessage) *routing.RoutePeer {
-	peerKind := msg.Metadata["peer_kind"]
-	if peerKind == "" {
+	if msg.Peer.Kind == "" {
 		return nil
 	}
-	peerID := msg.Metadata["peer_id"]
+	peerID := msg.Peer.ID
 	if peerID == "" {
-		if peerKind == "direct" {
+		if msg.Peer.Kind == "direct" {
 			peerID = msg.SenderID
 		} else {
 			peerID = msg.ChatID
 		}
 	}
-	return &routing.RoutePeer{Kind: peerKind, ID: peerID}
+	return &routing.RoutePeer{Kind: msg.Peer.Kind, ID: peerID}
 }
 
 // extractParentPeer extracts the parent peer (reply-to) from inbound message metadata.

pkg/agent/loop_test.go

@@ -11,12 +11,24 @@ import (
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
 	"github.com/sipeed/picoclaw/pkg/tools"
 )
 
+type fakeChannel struct{ id string }
+
+func (f *fakeChannel) Name() string                                            { return "fake" }
+func (f *fakeChannel) Start(ctx context.Context) error                         { return nil }
+func (f *fakeChannel) Stop(ctx context.Context) error                          { return nil }
+func (f *fakeChannel) Send(ctx context.Context, msg bus.OutboundMessage) error { return nil }
+func (f *fakeChannel) IsRunning() bool                                         { return true }
+func (f *fakeChannel) IsAllowed(string) bool                                   { return true }
+func (f *fakeChannel) IsAllowedSender(sender bus.SenderInfo) bool              { return true }
+func (f *fakeChannel) ReasoningChannelID() string                              { return f.id }
+
 func TestRecordLastChannel(t *testing.T) {
 	// Create temp workspace
 	tmpDir, err := os.MkdirTemp("", "agent-test-*")
@@ -660,6 +672,75 @@ func TestShouldInjectReminder(t *testing.T) {
 	}
 }
 
+func TestTargetReasoningChannelID_AllChannels(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				Model:             "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	al := NewAgentLoop(cfg, bus.NewMessageBus(), &mockProvider{})
+	chManager, err := channels.NewManager(&config.Config{}, bus.NewMessageBus(), nil)
+	if err != nil {
+		t.Fatalf("Failed to create channel manager: %v", err)
+	}
+	for name, id := range map[string]string{
+		"whatsapp":  "rid-whatsapp",
+		"telegram":  "rid-telegram",
+		"feishu":    "rid-feishu",
+		"discord":   "rid-discord",
+		"maixcam":   "rid-maixcam",
+		"qq":        "rid-qq",
+		"dingtalk":  "rid-dingtalk",
+		"slack":     "rid-slack",
+		"line":      "rid-line",
+		"onebot":    "rid-onebot",
+		"wecom":     "rid-wecom",
+		"wecom_app": "rid-wecom-app",
+	} {
+		chManager.RegisterChannel(name, &fakeChannel{id: id})
+	}
+	al.SetChannelManager(chManager)
+	tests := []struct {
+		channel string
+		wantID  string
+	}{
+		{channel: "whatsapp", wantID: "rid-whatsapp"},
+		{channel: "telegram", wantID: "rid-telegram"},
+		{channel: "feishu", wantID: "rid-feishu"},
+		{channel: "discord", wantID: "rid-discord"},
+		{channel: "maixcam", wantID: "rid-maixcam"},
+		{channel: "qq", wantID: "rid-qq"},
+		{channel: "dingtalk", wantID: "rid-dingtalk"},
+		{channel: "slack", wantID: "rid-slack"},
+		{channel: "line", wantID: "rid-line"},
+		{channel: "onebot", wantID: "rid-onebot"},
+		{channel: "wecom", wantID: "rid-wecom"},
+		{channel: "wecom_app", wantID: "rid-wecom-app"},
+		{channel: "unknown", wantID: ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.channel, func(t *testing.T) {
+			got := al.targetReasoningChannelID(tt.channel)
+			if got != tt.wantID {
+				t.Fatalf("targetReasoningChannelID(%q) = %q, want %q", tt.channel, got, tt.wantID)
+			}
+		})
+	}
+}
+
 func TestBuildTaskReminder_WithoutBlocker(t *testing.T) {
 	msg := buildTaskReminder("implement feature X", "")
 	if msg.Role != "user" {
@@ -836,7 +917,7 @@ func TestSlashCommandResponseSkipsPlaceholder(t *testing.T) {
 	}()
 
 	// Send a slash command
-	msgBus.PublishInbound(bus.InboundMessage{
+	msgBus.PublishInbound(context.Background(), bus.InboundMessage{
 		Channel:  "telegram",
 		SenderID: "user1",
 		ChatID:   "chat1",
@@ -1385,7 +1466,7 @@ Test
 func TestIsToolAllowedDuringInterview_FuzzyNames(t *testing.T) {
 	tests := []struct {
 		name string
-		args map[string]interface{}
+		args map[string]any
 		want bool
 	}{
 		// Exact names — read tools allowed
@@ -1403,38 +1484,38 @@ func TestIsToolAllowedDuringInterview_FuzzyNames(t *testing.T) {
 		{"message", nil, true},
 		{"Message", nil, true},
 		// Write to MEMORY.md — allowed
-		{"edit_file", map[string]interface{}{"path": "/ws/memory/MEMORY.md"}, true},
-		{"editfile", map[string]interface{}{"path": "/ws/memory/MEMORY.md"}, true},
-		{"EditFile", map[string]interface{}{"path": "/ws/memory/MEMORY.md"}, true},
+		{"edit_file", map[string]any{"path": "/ws/memory/MEMORY.md"}, true},
+		{"editfile", map[string]any{"path": "/ws/memory/MEMORY.md"}, true},
+		{"EditFile", map[string]any{"path": "/ws/memory/MEMORY.md"}, true},
 		// Write to non-MEMORY.md — blocked
-		{"edit_file", map[string]interface{}{"path": "/ws/main.go"}, false},
-		{"editfile", map[string]interface{}{"path": "/ws/main.go"}, false},
+		{"edit_file", map[string]any{"path": "/ws/main.go"}, false},
+		{"editfile", map[string]any{"path": "/ws/main.go"}, false},
 		// exec — read-only commands allowed
-		{"exec", map[string]interface{}{"command": "find . -name '*.py'"}, true},
-		{"exec", map[string]interface{}{"command": "ls -la"}, true},
-		{"exec", map[string]interface{}{"command": "grep -r TODO ."}, true},
-		{"exec", map[string]interface{}{"command": "cat README.md"}, true},
+		{"exec", map[string]any{"command": "find . -name '*.py'"}, true},
+		{"exec", map[string]any{"command": "ls -la"}, true},
+		{"exec", map[string]any{"command": "grep -r TODO ."}, true},
+		{"exec", map[string]any{"command": "cat README.md"}, true},
 		// exec — cd prefix stripped
-		{"exec", map[string]interface{}{"command": "cd /home/user/project && find . -type f"}, true},
-		{"exec", map[string]interface{}{"command": "cd /tmp && rm -rf *"}, false},
+		{"exec", map[string]any{"command": "cd /home/user/project && find . -type f"}, true},
+		{"exec", map[string]any{"command": "cd /tmp && rm -rf *"}, false},
 		// exec — write operators blocked
-		{"exec", map[string]interface{}{"command": "find . > output.txt"}, false},
-		{"exec", map[string]interface{}{"command": "ls -la >> log.txt"}, false},
-		{"exec", map[string]interface{}{"command": "cat foo | tee bar.txt"}, false},
+		{"exec", map[string]any{"command": "find . > output.txt"}, false},
+		{"exec", map[string]any{"command": "ls -la >> log.txt"}, false},
+		{"exec", map[string]any{"command": "cat foo | tee bar.txt"}, false},
 		// exec — path traversal blocked
-		{"exec", map[string]interface{}{"command": "cat ../../etc/passwd"}, false},
-		{"exec", map[string]interface{}{"command": "find ../../"}, false},
-		{"exec", map[string]interface{}{"command": "ls ../secret"}, false},
+		{"exec", map[string]any{"command": "cat ../../etc/passwd"}, false},
+		{"exec", map[string]any{"command": "find ../../"}, false},
+		{"exec", map[string]any{"command": "ls ../secret"}, false},
 		// exec — absolute paths blocked
-		{"exec", map[string]interface{}{"command": "cat /etc/passwd"}, false},
-		{"exec", map[string]interface{}{"command": "find /etc -name '*.conf'"}, false},
-		{"exec", map[string]interface{}{"command": "ls /root"}, false},
+		{"exec", map[string]any{"command": "cat /etc/passwd"}, false},
+		{"exec", map[string]any{"command": "find /etc -name '*.conf'"}, false},
+		{"exec", map[string]any{"command": "ls /root"}, false},
 		// exec — write commands blocked
-		{"exec", map[string]interface{}{"command": "rm -rf /"}, false},
-		{"exec", map[string]interface{}{"command": "mv a b"}, false},
+		{"exec", map[string]any{"command": "rm -rf /"}, false},
+		{"exec", map[string]any{"command": "mv a b"}, false},
 		// exec — no args / empty command blocked
 		{"exec", nil, false},
-		{"exec", map[string]interface{}{"command": ""}, false},
+		{"exec", map[string]any{"command": ""}, false},
 		{"Exec", nil, false},
 	}
 	for _, tt := range tests {
@@ -1449,56 +1530,60 @@ func TestBuildArgsSnippet_ExecStripsCD(t *testing.T) {
 	tests := []struct {
 		name      string
 		tool      string
-		args      map[string]interface{}
+		args      map[string]any
 		workspace string
 		wantSnip  string
 	}{
 		{
 			name: "exec strips cd prefix",
 			tool: "exec",
-			args:      map[string]interface{}{"command": "cd /home/user/workspace/project/my-projects && pytest tests/test_integration.py"},
+			args: map[string]any{
+				"command": "cd /home/user/workspace/project/my-projects && pytest tests/test_integration.py",
+			},
 			workspace: "/home/user/workspace",
 			wantSnip:  "pytest tests/test_integration.py",
 		},
 		{
 			name:      "exec no cd prefix, flags stripped",
 			tool:      "exec",
-			args:      map[string]interface{}{"command": "ls -la"},
+			args:      map[string]any{"command": "ls -la"},
 			workspace: "/ws",
 			wantSnip:  "ls",
 		},
 		{
 			name:      "exec empty command",
 			tool:      "exec",
-			args:      map[string]interface{}{},
+			args:      map[string]any{},
 			workspace: "/ws",
 			wantSnip:  "{}",
 		},
 		{
 			name:      "read_file strips workspace",
 			tool:      "read_file",
-			args:      map[string]interface{}{"path": "/home/user/workspace/src/main.go"},
+			args:      map[string]any{"path": "/home/user/workspace/src/main.go"},
 			workspace: "/home/user/workspace",
 			wantSnip:  "src/main.go",
 		},
 		{
 			name:      "edit_file shows path",
 			tool:      "edit_file",
-			args:      map[string]interface{}{"path": "/ws/config.json", "old_text": "old value here"},
+			args:      map[string]any{"path": "/ws/config.json", "old_text": "old value here"},
 			workspace: "/ws",
 			wantSnip:  "config.json",
 		},
 		{
 			name: "file tool long path prioritizes filename",
 			tool: "read_file",
-			args:      map[string]interface{}{"path": "/ws/projects/terra-py-form/src/terra_py_form/hot/state/backend.py"},
+			args: map[string]any{
+				"path": "/ws/projects/terra-py-form/src/terra_py_form/hot/state/backend.py",
+			},
 			workspace: "/ws",
 			wantSnip:  "projects/terra-py-form/src/terra_py_form/hot/sta\u2026/backend.py",
 		},
 		{
 			name:      "unknown tool shows raw JSON",
 			tool:      "web_search",
-			args:      map[string]interface{}{"query": "hello"},
+			args:      map[string]any{"query": "hello"},
 			workspace: "/ws",
 			wantSnip:  `{"query":"hello"}`,
 		},
@@ -1529,19 +1614,31 @@ func TestFormatCompactEntry(t *testing.T) {
 		},
 		{
 			name: "exec long entry truncated from end",
-			entry:    toolLogEntry{Name: "[2] exec", ArgsSnip: "pytest tests/integration/test_very_long_name.py", Result: "✗ 3.0s"},
+			entry: toolLogEntry{
+				Name:     "[2] exec",
+				ArgsSnip: "pytest tests/integration/test_very_long_name.py",
+				Result:   "✗ 3.0s",
+			},
 			wantMark: "✗",
 		},
 		{
 			name: "file tool omits duration, shows filename",
-			entry:    toolLogEntry{Name: "[3] edit_file", ArgsSnip: "projects/terra/src/deep/nested/backend.py", Result: "✓ 0.0s"},
+			entry: toolLogEntry{
+				Name:     "[3] edit_file",
+				ArgsSnip: "projects/terra/src/deep/nested/backend.py",
+				Result:   "✓ 0.0s",
+			},
 			wantSub:  "backend.py",
 			wantMark: "✓",
 			noTime:   true,
 		},
 		{
 			name: "file tool path truncates from start",
-			entry:    toolLogEntry{Name: "[4] read_file", ArgsSnip: "projects/terra-py-form/src/terra_py_form/hot/state/backend.py", Result: "✓ 0.1s"},
+			entry: toolLogEntry{
+				Name:     "[4] read_file",
+				ArgsSnip: "projects/terra-py-form/src/terra_py_form/hot/state/backend.py",
+				Result:   "✓ 0.1s",
+			},
 			wantSub:  "backend.py",
 			wantMark: "✓",
 			noTime:   true,
@@ -1664,7 +1761,7 @@ func TestExtractExecProjectDir(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			args := map[string]interface{}{"command": tt.cmd}
+			args := map[string]any{"command": tt.cmd}
 			got := extractExecProjectDir(args)
 			if got != tt.want {
 				t.Errorf("extractExecProjectDir(%q) = %q, want %q", tt.cmd, got, tt.want)
@@ -1752,15 +1849,18 @@ func TestBuildRichStatus_FixedHeight(t *testing.T) {
 	lines0 := countLines(buildRichStatus(task0, true, "/ws/p"))
 
 	// 1 entry
-	task1 := &activeTask{Iteration: 1, MaxIter: 10,
-		toolLog: []toolLogEntry{{Name: "exec", ArgsSnip: "ls", Result: "⏳"}}}
+	task1 := &activeTask{
+		Iteration: 1, MaxIter: 10,
+		toolLog: []toolLogEntry{{Name: "exec", ArgsSnip: "ls", Result: "⏳"}},
+	}
 	lines1 := countLines(buildRichStatus(task1, true, "/ws/p"))
 
 	// 5 entries
 	task5 := &activeTask{Iteration: 5, MaxIter: 10}
 	for i := 0; i < 5; i++ {
 		task5.toolLog = append(task5.toolLog, toolLogEntry{
-			Name: fmt.Sprintf("[%d] exec", i), ArgsSnip: "cmd", Result: "✓ 1.0s"})
+			Name: fmt.Sprintf("[%d] exec", i), ArgsSnip: "cmd", Result: "✓ 1.0s",
+		})
 	}
 	lines5 := countLines(buildRichStatus(task5, true, "/ws/p"))
 
@@ -1768,10 +1868,13 @@ func TestBuildRichStatus_FixedHeight(t *testing.T) {
 	task5err := &activeTask{Iteration: 5, MaxIter: 10}
 	for i := 0; i < 5; i++ {
 		task5err.toolLog = append(task5err.toolLog, toolLogEntry{
-			Name: fmt.Sprintf("[%d] exec", i), ArgsSnip: "cmd", Result: "✓ 1.0s"})
+			Name: fmt.Sprintf("[%d] exec", i), ArgsSnip: "cmd", Result: "✓ 1.0s",
+		})
+	}
+	errEntry := toolLogEntry{
+		Name: "[3] exec", ArgsSnip: "pytest", Result: "✗ 2.0s",
+		ErrDetail: "FAILED test\nExit code: 1",
 	}
-	errEntry := toolLogEntry{Name: "[3] exec", ArgsSnip: "pytest", Result: "✗ 2.0s",
-		ErrDetail: "FAILED test\nExit code: 1"}
 	task5err.lastError = &errEntry
 	lines5err := countLines(buildRichStatus(task5err, true, "/ws/p"))
 
@@ -2278,7 +2381,7 @@ func TestConsumeStream_OnChunkCallback(t *testing.T) {
 	defer cancel()
 
 	var chunks []string
-	onChunk := func(accumulated string) {
+	onChunk := func(accumulated, _ string) {
 		chunks = append(chunks, accumulated)
 	}
 
@@ -2329,7 +2432,7 @@ func TestConsumeStream_OnChunkWithRepetitionDetection(t *testing.T) {
 	}()
 
 	var chunkCount int
-	onChunk := func(accumulated string) {
+	onChunk := func(_, _ string) {
 		chunkCount++
 	}
 
@@ -2410,8 +2513,8 @@ func TestAgentLoop_PlanModel_UsedDuringInterviewing(t *testing.T) {
 	os.MkdirAll(memoryDir, 0o755)
 	memoryPath := filepath.Join(memoryDir, "MEMORY.md")
 	memoryContent := "# Active Plan\n\n> Task: Test plan model\n> Status: interviewing\n> Phase: 1\n"
-	if err := os.WriteFile(memoryPath, []byte(memoryContent), 0o644); err != nil {
-		t.Fatalf("Failed to write MEMORY.md: %v", err)
+	if wErr := os.WriteFile(memoryPath, []byte(memoryContent), 0o644); wErr != nil {
+		t.Fatalf("Failed to write MEMORY.md: %v", wErr)
 	}
 
 	_, err = al.ProcessDirectWithChannel(
@@ -2478,8 +2581,8 @@ func TestAgentLoop_PlanModel_NotUsedDuringExecuting(t *testing.T) {
 ## Phase 1: Build
 - [ ] Run build
 `
-	if err := os.WriteFile(memoryPath, []byte(memoryContent), 0o644); err != nil {
-		t.Fatalf("Failed to write MEMORY.md: %v", err)
+	if wErr := os.WriteFile(memoryPath, []byte(memoryContent), 0o644); wErr != nil {
+		t.Fatalf("Failed to write MEMORY.md: %v", wErr)
 	}
 
 	_, err = al.ProcessDirectWithChannel(
@@ -2539,8 +2642,8 @@ func TestAgentLoop_PlanModel_ResolvesProviderForSingleCandidate(t *testing.T) {
 	os.MkdirAll(memoryDir, 0o755)
 	memoryPath := filepath.Join(memoryDir, "MEMORY.md")
 	memoryContent := "# Active Plan\n\n> Task: Test provider resolution\n> Status: interviewing\n> Phase: 1\n"
-	if err := os.WriteFile(memoryPath, []byte(memoryContent), 0o644); err != nil {
-		t.Fatalf("Failed to write MEMORY.md: %v", err)
+	if wErr := os.WriteFile(memoryPath, []byte(memoryContent), 0o644); wErr != nil {
+		t.Fatalf("Failed to write MEMORY.md: %v", wErr)
 	}
 
 	_, err = al.ProcessDirectWithChannel(
@@ -2709,3 +2812,182 @@ func TestFilterInterviewTools(t *testing.T) {
 		}
 	}
 }
+
+func TestBuildStreamingDisplay_ContentOnly(t *testing.T) {
+	display := buildStreamingDisplay("hello world", "")
+	if !strings.HasSuffix(display, " \u2589") {
+		t.Error("expected cursor suffix")
+	}
+	if strings.Contains(display, "\U0001f9e0") {
+		t.Error("should not contain brain emoji when no reasoning")
+	}
+	lines := strings.Count(display, "\n") + 1
+	if lines != streamingDisplayLines+1 { // TailPad lines + cursor on last line
+		t.Logf("display:\n%s", display)
+	}
+}
+
+func TestBuildStreamingDisplay_ReasoningOnly(t *testing.T) {
+	display := buildStreamingDisplay("", "let me think about this")
+	if !strings.Contains(display, "\U0001f9e0") {
+		t.Error("expected brain emoji for reasoning phase")
+	}
+	if !strings.Contains(display, "Thinking...") {
+		t.Error("expected Thinking... header")
+	}
+	if !strings.HasSuffix(display, " \u2589") {
+		t.Error("expected cursor suffix")
+	}
+}
+
+func TestBuildStreamingDisplay_Both(t *testing.T) {
+	display := buildStreamingDisplay("the answer is 42", "first I considered...")
+	if !strings.Contains(display, "\U0001f9e0") {
+		t.Error("expected brain emoji")
+	}
+	if !strings.Contains(display, "responding") {
+		t.Error("expected responding header when both present")
+	}
+	if !strings.Contains(display, "the answer is 42") {
+		t.Error("expected content in display")
+	}
+}
+
+func TestHandleReasoning(t *testing.T) {
+	newLoop := func(t *testing.T) (*AgentLoop, *bus.MessageBus) {
+		t.Helper()
+		tmpDir, err := os.MkdirTemp("", "agent-test-*")
+		if err != nil {
+			t.Fatalf("Failed to create temp dir: %v", err)
+		}
+		t.Cleanup(func() { _ = os.RemoveAll(tmpDir) })
+		cfg := &config.Config{
+			Agents: config.AgentsConfig{
+				Defaults: config.AgentDefaults{
+					Workspace:         tmpDir,
+					Model:             "test-model",
+					MaxTokens:         4096,
+					MaxToolIterations: 10,
+				},
+			},
+		}
+		msgBus := bus.NewMessageBus()
+		return NewAgentLoop(cfg, msgBus, &mockProvider{}), msgBus
+	}
+
+	t.Run("skips when any required field is empty", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		al.handleReasoning(context.Background(), "reasoning", "telegram", "")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+		defer cancel()
+		if msg, ok := msgBus.SubscribeOutbound(ctx); ok {
+			t.Fatalf("expected no outbound message, got %+v", msg)
+		}
+	})
+
+	t.Run("publishes one message for non telegram", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		al.handleReasoning(context.Background(), "hello reasoning", "slack", "channel-1")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+		defer cancel()
+		msg, ok := msgBus.SubscribeOutbound(ctx)
+		if !ok {
+			t.Fatal("expected an outbound message")
+		}
+		if msg.Channel != "slack" || msg.ChatID != "channel-1" || msg.Content != "hello reasoning" {
+			t.Fatalf("unexpected outbound message: %+v", msg)
+		}
+	})
+
+	t.Run("publishes one message for telegram", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		reasoning := "hello telegram reasoning"
+		al.handleReasoning(context.Background(), reasoning, "telegram", "tg-chat")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+		defer cancel()
+		msg, ok := msgBus.SubscribeOutbound(ctx)
+		if !ok {
+			t.Fatal("expected outbound message")
+		}
+
+		if msg.Channel != "telegram" {
+			t.Fatalf("expected telegram channel message, got %+v", msg)
+		}
+		if msg.ChatID != "tg-chat" {
+			t.Fatalf("expected chatID tg-chat, got %+v", msg)
+		}
+		if msg.Content != reasoning {
+			t.Fatalf("content mismatch: got %q want %q", msg.Content, reasoning)
+		}
+	})
+	t.Run("expired ctx", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		reasoning := "hello telegram reasoning"
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		al.handleReasoning(ctx, reasoning, "telegram", "tg-chat")
+
+		ctx, cancel = context.WithTimeout(context.Background(), 200*time.Millisecond)
+		defer cancel()
+		msg, ok := msgBus.SubscribeOutbound(ctx)
+		if ok {
+			t.Fatalf("expected no outbound message, got %+v", msg)
+		}
+	})
+
+	t.Run("returns promptly when bus is full", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+
+		// Fill the outbound bus buffer until a publish would block.
+		// Use a short timeout to detect when the buffer is full,
+		// rather than hardcoding the buffer size.
+		for i := 0; ; i++ {
+			fillCtx, fillCancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+			err := msgBus.PublishOutbound(fillCtx, bus.OutboundMessage{
+				Channel: "filler",
+				ChatID:  "filler",
+				Content: fmt.Sprintf("filler-%d", i),
+			})
+			fillCancel()
+			if err != nil {
+				// Buffer is full (timed out trying to send).
+				break
+			}
+		}
+
+		// Use a short-deadline parent context to bound the test.
+		ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+		defer cancel()
+
+		start := time.Now()
+		al.handleReasoning(ctx, "should timeout", "slack", "channel-full")
+		elapsed := time.Since(start)
+
+		// handleReasoning uses a 5s internal timeout, but the parent ctx
+		// expires in 500ms. It should return within ~500ms, not 5s.
+		if elapsed > 2*time.Second {
+			t.Fatalf("handleReasoning blocked too long (%v); expected prompt return", elapsed)
+		}
+
+		// Drain the bus and verify the reasoning message was NOT published
+		// (it should have been dropped due to timeout).
+		drainCtx, drainCancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+		defer drainCancel()
+		foundReasoning := false
+		for {
+			msg, ok := msgBus.SubscribeOutbound(drainCtx)
+			if !ok {
+				break
+			}
+			if msg.Content == "should timeout" {
+				foundReasoning = true
+			}
+		}
+		if foundReasoning {
+			t.Fatal("expected reasoning message to be dropped when bus is full, but it was published")
+		}
+	})
+}

pkg/agent/memory.go

@@ -14,6 +14,8 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 )
 
 // MemoryStore manages persistent memory for the agent.
@@ -60,7 +62,9 @@ func (ms *MemoryStore) ReadLongTerm() string {
 
 // WriteLongTerm writes content to the long-term memory file (MEMORY.md).
 func (ms *MemoryStore) WriteLongTerm(content string) error {
-	return os.WriteFile(ms.memoryFile, []byte(content), 0o644)
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	// Using 0o600 (owner read/write only) for secure default permissions.
+	return fileutil.WriteFileAtomic(ms.memoryFile, []byte(content), 0o600)
 }
 
 // ClearLongTerm removes the long-term memory file.
@@ -88,7 +92,9 @@ func (ms *MemoryStore) AppendToday(content string) error {
 
 	// Ensure month directory exists
 	monthDir := filepath.Dir(todayFile)
-	os.MkdirAll(monthDir, 0o755)
+	if err := os.MkdirAll(monthDir, 0o755); err != nil {
+		return err
+	}
 
 	var existingContent string
 	if data, err := os.ReadFile(todayFile); err == nil {
@@ -105,7 +111,8 @@ func (ms *MemoryStore) AppendToday(content string) error {
 		newContent = existingContent + "\n" + content
 	}
 
-	return os.WriteFile(todayFile, []byte(newContent), 0o644)
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	return fileutil.WriteFileAtomic(todayFile, []byte(newContent), 0o600)
 }
 
 // GetRecentDailyNotes returns daily notes from the last N days.
@@ -139,8 +146,6 @@ var (
 	reStatus      = regexp.MustCompile(`(?m)^> Status:\s*(.+)`)
 	rePhase       = regexp.MustCompile(`(?m)^> Phase:\s*(\d+)`)
 	rePhaseHeader = regexp.MustCompile(`(?m)^## Phase (\d+):\s*(.*)`)
-	reStepDone    = regexp.MustCompile(`(?m)^- \[x\] `)
-	reStepTodo    = regexp.MustCompile(`(?m)^- \[ \] `)
 	reWorkDir     = regexp.MustCompile(`(?m)^> WorkDir:\s*(.+)`)
 )
 
@@ -175,16 +180,16 @@ func (ms *MemoryStore) GetCurrentPhase() int {
 func (ms *MemoryStore) GetTotalPhases() int {
 	content := ms.ReadLongTerm()
 	matches := rePhaseHeader.FindAllStringSubmatch(content, -1)
-	max := 0
+	maxN := 0
 	for _, m := range matches {
 		if len(m) >= 2 {
 			n, _ := strconv.Atoi(m[1])
-			if n > max {
-				max = n
+			if n > maxN {
+				maxN = n
 			}
 		}
 	}
-	return max
+	return maxN
 }
 
 // IsPlanComplete returns true if all steps in all phases are [x].
@@ -513,12 +518,22 @@ func (ms *MemoryStore) getInterviewContextFrom(content string) string {
 	sb.WriteString("- Tooling preferences (test framework, linter, formatter, CI)\n")
 	sb.WriteString("- Key commands the user already runs (build, test, deploy)\n")
 	sb.WriteString("\n### Rules\n")
-	sb.WriteString("- NEVER remove or overwrite the header block (`# Active Plan`, `> Task:`, `> Status:`, `> Phase:` lines). The system parses these to track state.\n")
-	sb.WriteString("- After each answer, use edit_file to append findings to the ## Context section of memory/MEMORY.md.\n")
-	sb.WriteString("- When you have enough information, use edit_file to add ## Phase, ## Commands, and ## Context sections BELOW the header block.\n")
-	sb.WriteString("- Each step MUST use checkbox syntax: `- [ ] description`. The system parses checkboxes to track progress.\n")
+	sb.WriteString(
+		"- NEVER remove or overwrite the header block (`# Active Plan`, `> Task:`, `> Status:`, `> Phase:` lines). The system parses these to track state.\n",
+	)
+	sb.WriteString(
+		"- After each answer, use edit_file to append findings to the ## Context section of memory/MEMORY.md.\n",
+	)
+	sb.WriteString(
+		"- When you have enough information, use edit_file to add ## Phase, ## Commands, and ## Context sections BELOW the header block.\n",
+	)
+	sb.WriteString(
+		"- Each step MUST use checkbox syntax: `- [ ] description`. The system parses checkboxes to track progress.\n",
+	)
 	sb.WriteString("- Organize into 2-5 phases with 3-5 steps each.\n")
-	sb.WriteString("- After writing Phases, change `> Status: interviewing` to `> Status: review` via edit_file. The user must approve with /plan start before execution begins.\n")
+	sb.WriteString(
+		"- After writing Phases, change `> Status: interviewing` to `> Status: review` via edit_file. The user must approve with /plan start before execution begins.\n",
+	)
 	sb.WriteString("\n### Target Format (MANDATORY — system parses this exact structure)\n")
 	sb.WriteString("\n")
 	sb.WriteString("# Active Plan\n")
@@ -621,16 +636,16 @@ func (ms *MemoryStore) getPlanContextFrom(content string) string {
 // maxPhaseNumber returns the highest phase number found in content.
 func maxPhaseNumber(content string) int {
 	matches := rePhaseHeader.FindAllStringSubmatch(content, -1)
-	max := 0
+	maxN := 0
 	for _, m := range matches {
 		if len(m) >= 2 {
 			n, _ := strconv.Atoi(m[1])
-			if n > max {
-				max = n
+			if n > maxN {
+				maxN = n
 			}
 		}
 	}
-	return max
+	return maxN
 }
 
 // getPhaseTitle extracts the title of a phase from "## Phase N: Title".

pkg/auth/oauth.go

@@ -156,7 +156,7 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {
 		return exchangeCodeForTokens(cfg, result.code, pkce.CodeVerifier, redirectURI)
 	case manualInput := <-manualCh:
 		if manualInput == "" {
-			return nil, fmt.Errorf("manual input cancelled")
+			return nil, fmt.Errorf("manual input canceled")
 		}
 		// Extract code from URL if it's a full URL
 		code := manualInput

pkg/auth/store.go

@@ -5,6 +5,8 @@ import (
 	"os"
 	"path/filepath"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
 )
 
 type AuthCredential struct {
@@ -63,16 +65,13 @@ func LoadStore() (*AuthStore, error) {
 
 func SaveStore(store *AuthStore) error {
 	path := authFilePath()
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return err
-	}
-
 	data, err := json.MarshalIndent(store, "", "  ")
 	if err != nil {
 		return err
 	}
-	return os.WriteFile(path, data, 0o600)
+
+	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	return fileutil.WriteFileAtomic(path, data, 0o600)
 }
 
 func GetCredential(provider string) (*AuthCredential, error) {

pkg/bus/bus.go

@@ -2,81 +2,156 @@ package bus
 
 import (
 	"context"
-	"sync"
+	"errors"
+	"sync/atomic"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
+// ErrBusClosed is returned when publishing to a closed MessageBus.
+var ErrBusClosed = errors.New("message bus closed")
+
+const defaultBusBufferSize = 64
+
 type MessageBus struct {
 	inbound       chan InboundMessage
 	outbound      chan OutboundMessage
-	handlers map[string]MessageHandler
-	closed   bool
-	mu       sync.RWMutex
+	outboundMedia chan OutboundMediaMessage
+	done          chan struct{}
+	closed        atomic.Bool
 }
 
 func NewMessageBus() *MessageBus {
 	return &MessageBus{
-		inbound:  make(chan InboundMessage, 100),
-		outbound: make(chan OutboundMessage, 100),
-		handlers: make(map[string]MessageHandler),
+		inbound:       make(chan InboundMessage, defaultBusBufferSize),
+		outbound:      make(chan OutboundMessage, defaultBusBufferSize),
+		outboundMedia: make(chan OutboundMediaMessage, defaultBusBufferSize),
+		done:          make(chan struct{}),
 	}
 }
 
-func (mb *MessageBus) PublishInbound(msg InboundMessage) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	if mb.closed {
-		return
+func (mb *MessageBus) PublishInbound(ctx context.Context, msg InboundMessage) error {
+	if mb.closed.Load() {
+		return ErrBusClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case mb.inbound <- msg:
+		return nil
+	case <-mb.done:
+		return ErrBusClosed
+	case <-ctx.Done():
+		return ctx.Err()
 	}
-	mb.inbound <- msg
 }
 
 func (mb *MessageBus) ConsumeInbound(ctx context.Context) (InboundMessage, bool) {
 	select {
-	case msg := <-mb.inbound:
-		return msg, true
+	case msg, ok := <-mb.inbound:
+		return msg, ok
+	case <-mb.done:
+		return InboundMessage{}, false
 	case <-ctx.Done():
 		return InboundMessage{}, false
 	}
 }
 
-func (mb *MessageBus) PublishOutbound(msg OutboundMessage) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	if mb.closed {
-		return
+func (mb *MessageBus) PublishOutbound(ctx context.Context, msg OutboundMessage) error {
+	if mb.closed.Load() {
+		return ErrBusClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case mb.outbound <- msg:
+		return nil
+	case <-mb.done:
+		return ErrBusClosed
+	case <-ctx.Done():
+		return ctx.Err()
 	}
-	mb.outbound <- msg
 }
 
 func (mb *MessageBus) SubscribeOutbound(ctx context.Context) (OutboundMessage, bool) {
 	select {
-	case msg := <-mb.outbound:
-		return msg, true
+	case msg, ok := <-mb.outbound:
+		return msg, ok
+	case <-mb.done:
+		return OutboundMessage{}, false
 	case <-ctx.Done():
 		return OutboundMessage{}, false
 	}
 }
 
-func (mb *MessageBus) RegisterHandler(channel string, handler MessageHandler) {
-	mb.mu.Lock()
-	defer mb.mu.Unlock()
-	mb.handlers[channel] = handler
+func (mb *MessageBus) PublishOutboundMedia(ctx context.Context, msg OutboundMediaMessage) error {
+	if mb.closed.Load() {
+		return ErrBusClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case mb.outboundMedia <- msg:
+		return nil
+	case <-mb.done:
+		return ErrBusClosed
+	case <-ctx.Done():
+		return ctx.Err()
+	}
 }
 
-func (mb *MessageBus) GetHandler(channel string) (MessageHandler, bool) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	handler, ok := mb.handlers[channel]
-	return handler, ok
+func (mb *MessageBus) SubscribeOutboundMedia(ctx context.Context) (OutboundMediaMessage, bool) {
+	select {
+	case msg, ok := <-mb.outboundMedia:
+		return msg, ok
+	case <-mb.done:
+		return OutboundMediaMessage{}, false
+	case <-ctx.Done():
+		return OutboundMediaMessage{}, false
+	}
 }
 
 func (mb *MessageBus) Close() {
-	mb.mu.Lock()
-	defer mb.mu.Unlock()
-	if mb.closed {
-		return
+	if mb.closed.CompareAndSwap(false, true) {
+		close(mb.done)
+
+		// Drain buffered channels so messages aren't silently lost.
+		// Channels are NOT closed to avoid send-on-closed panics from concurrent publishers.
+		drained := 0
+		for {
+			select {
+			case <-mb.inbound:
+				drained++
+			default:
+				goto doneInbound
+			}
+		}
+	doneInbound:
+		for {
+			select {
+			case <-mb.outbound:
+				drained++
+			default:
+				goto doneOutbound
+			}
+		}
+	doneOutbound:
+		for {
+			select {
+			case <-mb.outboundMedia:
+				drained++
+			default:
+				goto doneMedia
+			}
+		}
+	doneMedia:
+		if drained > 0 {
+			logger.DebugCF("bus", "Drained buffered messages during close", map[string]any{
+				"count": drained,
+			})
+		}
 	}
-	mb.closed = true
-	close(mb.inbound)
-	close(mb.outbound)
 }

pkg/bus/bus_test.go

@@ -0,0 +1,229 @@
+package bus
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestPublishConsume(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	msg := InboundMessage{
+		Channel:  "test",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "hello",
+	}
+
+	if err := mb.PublishInbound(ctx, msg); err != nil {
+		t.Fatalf("PublishInbound failed: %v", err)
+	}
+
+	got, ok := mb.ConsumeInbound(ctx)
+	if !ok {
+		t.Fatal("ConsumeInbound returned ok=false")
+	}
+	if got.Content != "hello" {
+		t.Fatalf("expected content 'hello', got %q", got.Content)
+	}
+	if got.Channel != "test" {
+		t.Fatalf("expected channel 'test', got %q", got.Channel)
+	}
+}
+
+func TestPublishOutboundSubscribe(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	msg := OutboundMessage{
+		Channel: "telegram",
+		ChatID:  "123",
+		Content: "world",
+	}
+
+	if err := mb.PublishOutbound(ctx, msg); err != nil {
+		t.Fatalf("PublishOutbound failed: %v", err)
+	}
+
+	got, ok := mb.SubscribeOutbound(ctx)
+	if !ok {
+		t.Fatal("SubscribeOutbound returned ok=false")
+	}
+	if got.Content != "world" {
+		t.Fatalf("expected content 'world', got %q", got.Content)
+	}
+}
+
+func TestPublishInbound_ContextCancel(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	// Fill the buffer
+	ctx := context.Background()
+	for i := 0; i < defaultBusBufferSize; i++ {
+		if err := mb.PublishInbound(ctx, InboundMessage{Content: "fill"}); err != nil {
+			t.Fatalf("fill failed at %d: %v", i, err)
+		}
+	}
+
+	// Now buffer is full; publish with a canceled context
+	cancelCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err := mb.PublishInbound(cancelCtx, InboundMessage{Content: "overflow"})
+	if err == nil {
+		t.Fatal("expected error from canceled context, got nil")
+	}
+	if err != context.Canceled {
+		t.Fatalf("expected context.Canceled, got %v", err)
+	}
+}
+
+func TestPublishInbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	err := mb.PublishInbound(context.Background(), InboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed, got %v", err)
+	}
+}
+
+func TestPublishOutbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	err := mb.PublishOutbound(context.Background(), OutboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed, got %v", err)
+	}
+}
+
+func TestConsumeInbound_ContextCancel(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, ok := mb.ConsumeInbound(ctx)
+	if ok {
+		t.Fatal("expected ok=false when context is canceled")
+	}
+}
+
+func TestConsumeInbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	_, ok := mb.ConsumeInbound(ctx)
+	if ok {
+		t.Fatal("expected ok=false when bus is closed")
+	}
+}
+
+func TestSubscribeOutbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	_, ok := mb.SubscribeOutbound(ctx)
+	if ok {
+		t.Fatal("expected ok=false when bus is closed")
+	}
+}
+
+func TestConcurrentPublishClose(t *testing.T) {
+	mb := NewMessageBus()
+	ctx := context.Background()
+
+	const numGoroutines = 100
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines + 1)
+
+	// Spawn many goroutines trying to publish
+	for i := 0; i < numGoroutines; i++ {
+		go func() {
+			defer wg.Done()
+			// Use a short timeout context so we don't block forever after close
+			publishCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
+			defer cancel()
+			// Errors are expected; we just must not panic or deadlock
+			_ = mb.PublishInbound(publishCtx, InboundMessage{Content: "concurrent"})
+		}()
+	}
+
+	// Close from another goroutine
+	go func() {
+		defer wg.Done()
+		time.Sleep(5 * time.Millisecond)
+		mb.Close()
+	}()
+
+	// Must complete without deadlock
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// success
+	case <-time.After(5 * time.Second):
+		t.Fatal("test timed out - possible deadlock")
+	}
+}
+
+func TestPublishInbound_FullBuffer(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	// Fill the buffer
+	for i := 0; i < defaultBusBufferSize; i++ {
+		if err := mb.PublishInbound(ctx, InboundMessage{Content: "fill"}); err != nil {
+			t.Fatalf("fill failed at %d: %v", i, err)
+		}
+	}
+
+	// Buffer is full; publish with short timeout
+	timeoutCtx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
+	defer cancel()
+
+	err := mb.PublishInbound(timeoutCtx, InboundMessage{Content: "overflow"})
+	if err == nil {
+		t.Fatal("expected error when buffer is full and context times out")
+	}
+	if err != context.DeadlineExceeded {
+		t.Fatalf("expected context.DeadlineExceeded, got %v", err)
+	}
+}
+
+func TestCloseIdempotent(t *testing.T) {
+	mb := NewMessageBus()
+
+	// Multiple Close calls must not panic
+	mb.Close()
+	mb.Close()
+	mb.Close()
+
+	// After close, publish should return ErrBusClosed
+	err := mb.PublishInbound(context.Background(), InboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed after multiple closes, got %v", err)
+	}
+}

pkg/bus/types.go

@@ -1,11 +1,30 @@
 package bus
 
+// Peer identifies the routing peer for a message (direct, group, channel, etc.)
+type Peer struct {
+	Kind string `json:"kind"` // "direct" | "group" | "channel" | ""
+	ID   string `json:"id"`
+}
+
+// SenderInfo provides structured sender identity information.
+type SenderInfo struct {
+	Platform    string `json:"platform,omitempty"`     // "telegram", "discord", "slack", ...
+	PlatformID  string `json:"platform_id,omitempty"`  // raw platform ID, e.g. "123456"
+	CanonicalID string `json:"canonical_id,omitempty"` // "platform:id" format
+	Username    string `json:"username,omitempty"`     // username (e.g. @alice)
+	DisplayName string `json:"display_name,omitempty"` // display name
+}
+
 type InboundMessage struct {
 	Channel    string            `json:"channel"`
 	SenderID   string            `json:"sender_id"`
+	Sender     SenderInfo        `json:"sender"`
 	ChatID     string            `json:"chat_id"`
 	Content    string            `json:"content"`
 	Media      []string          `json:"media,omitempty"`
+	Peer       Peer              `json:"peer"`                  // routing peer
+	MessageID  string            `json:"message_id,omitempty"`  // platform message ID
+	MediaScope string            `json:"media_scope,omitempty"` // media lifecycle scope
 	SessionKey string            `json:"session_key"`
 	Metadata   map[string]string `json:"metadata,omitempty"`
 }
@@ -20,4 +39,18 @@ type OutboundMessage struct {
 	SkipPlaceholder bool   `json:"skip_placeholder,omitempty"`
 }
 
-type MessageHandler func(InboundMessage) error
+// MediaPart describes a single media attachment to send.
+type MediaPart struct {
+	Type        string `json:"type"`                   // "image" | "audio" | "video" | "file"
+	Ref         string `json:"ref"`                    // media store ref, e.g. "media://abc123"
+	Caption     string `json:"caption,omitempty"`      // optional caption text
+	Filename    string `json:"filename,omitempty"`     // original filename hint
+	ContentType string `json:"content_type,omitempty"` // MIME type hint
+}
+
+// OutboundMediaMessage carries media attachments from Agent to channels via the bus.
+type OutboundMediaMessage struct {
+	Channel string      `json:"channel"`
+	ChatID  string      `json:"chat_id"`
+	Parts   []MediaPart `json:"parts"`
+}