-
+
-
PicoClaw: Asisten AI Super Ringan berbasis Go
+
PicoClaw: Asisten AI Super Ringan berbasis Go
-
Perangkat Keras $10 · RAM <10MB · Boot <1 Detik · Ayo, Berangkat!
+
Perangkat Keras $10 · RAM 10MB · Boot ms · Let's Go, PicoClaw!
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
> [!CAUTION]
-> **🚨 KEAMANAN & SALURAN RESMI**
->
-> * **TANPA KRIPTO:** PicoClaw **TIDAK** memiliki token/koin resmi. Semua klaim di `pump.fun` atau platform trading lainnya adalah **PENIPUAN**.
+> **Peringatan Keamanan**
>
+> * **TANPA KRIPTO:** PicoClaw **tidak** menerbitkan token atau cryptocurrency resmi apa pun. Semua klaim di `pump.fun` atau platform trading lainnya adalah **penipuan**.
> * **DOMAIN RESMI:** Satu-satunya website resmi adalah **[picoclaw.io](https://picoclaw.io)**, dan website perusahaan adalah **[sipeed.com](https://sipeed.com)**
-> * **Peringatan:** Banyak domain `.ai/.org/.com/.net/...` yang didaftarkan oleh pihak ketiga.
-> * **Peringatan:** PicoClaw masih dalam tahap pengembangan awal dan mungkin memiliki masalah keamanan jaringan yang belum teratasi. Jangan deploy ke lingkungan produksi sebelum rilis v1.0.
-> * **Catatan:** PicoClaw baru-baru ini menggabungkan banyak PR, yang mungkin mengakibatkan penggunaan memori lebih besar (10–20MB) pada versi terbaru. Kami berencana untuk memprioritaskan optimasi sumber daya segera setelah fitur saat ini mencapai kondisi stabil.
+> * **WASPADA:** Banyak domain `.ai/.org/.com/.net/...` telah didaftarkan oleh pihak ketiga. Jangan percaya mereka.
+> * **CATATAN:** PicoClaw masih dalam tahap pengembangan awal yang cepat. Mungkin ada masalah keamanan yang belum terselesaikan. Jangan deploy ke produksi sebelum v1.0.
+> * **CATATAN:** PicoClaw baru-baru ini menggabungkan banyak PR. Build terbaru mungkin menggunakan RAM 10-20MB. Optimasi sumber daya direncanakan setelah fitur stabil.
## 📢 Berita
-2026-03-17 🚀 **v0.2.3 Dirilis!** UI system tray (Windows & Linux), pelacakan status sub-agent (`spawn_status`), eksperimental gateway hot-reload, gerbang keamanan cron, dan 2 perbaikan keamanan. PicoClaw kini di **25K ⭐**!
+2026-03-17 🚀 **v0.2.3 Dirilis!** UI system tray (Windows & Linux), pelacakan status sub-agent (`spawn_status`), eksperimental Gateway hot-reload, gerbang keamanan Cron, dan 2 perbaikan keamanan. PicoClaw telah mencapai **25K Stars**!
-2026-03-09 🎉 **v0.2.1 — Update terbesar!** Dukungan protokol MCP, 4 channel baru (Matrix/IRC/WeCom/Discord Proxy), 3 provider baru (Kimi/Minimax/Avian), pipeline vision, penyimpanan memori JSONL, dan routing model.
+2026-03-09 🎉 **v0.2.1 — Update terbesar sejauh ini!** Dukungan protokol MCP, 4 channel baru (Matrix/IRC/WeCom/Discord Proxy), 3 provider baru (Kimi/Minimax/Avian), pipeline vision, penyimpanan memori JSONL, routing model.
-2026-02-28 📦 **v0.2.0** dirilis dengan dukungan Docker Compose dan launcher Web UI.
+2026-02-28 📦 **v0.2.0** dirilis dengan dukungan Docker Compose dan Web UI Launcher.
-2026-02-26 🎉 PicoClaw mencapai **20K bintang** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas diluncurkan.
+2026-02-26 🎉 PicoClaw mencapai **20K Stars** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas kini aktif.
-Berita lama...
+Berita sebelumnya...
-2026-02-16 🎉 PicoClaw mencapai 12K bintang dalam satu minggu! Peran maintainer komunitas dan [roadmap](ROADMAP.md) resmi diposting.
+2026-02-16 🎉 PicoClaw menembus 12K Stars dalam satu minggu! Peran maintainer komunitas dan [Roadmap](ROADMAP.md) resmi diluncurkan.
-2026-02-13 🎉 PicoClaw mencapai 5000 bintang dalam 4 hari! Roadmap Proyek dan pengaturan Grup Pengembang sedang berjalan.
+2026-02-13 🎉 PicoClaw menembus 5000 Stars dalam 4 hari! Roadmap proyek dan grup pengembang sedang dalam proses.
-2026-02-09 🎉 **PicoClaw Diluncurkan!** Dibangun dalam 1 hari untuk menghadirkan AI Agent ke perangkat keras $10 dengan RAM <10MB. 🦐 PicoClaw, Ayo Berangkat!
+2026-02-09 🎉 **PicoClaw Diluncurkan!** Dibangun dalam 1 hari untuk menghadirkan AI Agent ke perangkat keras $10 dengan RAM <10MB. Let's Go, PicoClaw!
## ✨ Fitur
-🪶 **Super Ringan**: Penggunaan memori <10MB — 99% lebih kecil dari fungsionalitas inti OpenClaw.*
+🪶 **Super Ringan**: Penggunaan memori inti <10MB — 99% lebih kecil dari OpenClaw.*
💰 **Biaya Minimal**: Cukup efisien untuk berjalan di perangkat keras $10 — 98% lebih murah dari Mac mini.
-⚡️ **Secepat Kilat**: Waktu startup 400X lebih cepat, boot dalam <1 detik bahkan di prosesor single core 0,6GHz.
+⚡️ **Boot Secepat Kilat**: Startup 400x lebih cepat. Boot dalam <1 detik bahkan di prosesor single-core 0,6GHz.
-🌍 **Portabilitas Sejati**: Satu binary mandiri untuk RISC-V, ARM, MIPS, dan x86, Satu Klik Langsung Jalan!
+🌍 **Portabilitas Sejati**: Satu binary untuk RISC-V, ARM, MIPS, dan x86. Satu binary, jalan di mana saja!
-🤖 **AI-Bootstrapped**: Implementasi Go-native secara otonom — 95% kode inti dihasilkan oleh Agent dengan penyempurnaan human-in-the-loop.
+🤖 **AI-Bootstrapped**: Implementasi Go native murni — 95% kode inti dihasilkan oleh Agent dengan penyempurnaan human-in-the-loop.
-🔌 **Dukungan MCP**: Integrasi [Model Context Protocol](https://modelcontextprotocol.io/) native — hubungkan server MCP mana pun untuk memperluas kapabilitas agent.
+🔌 **Dukungan MCP**: Integrasi [Model Context Protocol](https://modelcontextprotocol.io/) native — hubungkan server MCP mana pun untuk memperluas kapabilitas Agent.
-👁️ **Pipeline Vision**: Kirim gambar dan file langsung ke agent — encoding base64 otomatis untuk LLM multimodal.
+👁️ **Pipeline Vision**: Kirim gambar dan file langsung ke Agent — encoding base64 otomatis untuk LLM multimodal.
🧠 **Routing Cerdas**: Routing model berbasis aturan — kueri sederhana diarahkan ke model ringan, menghemat biaya API.
-_*Versi terbaru mungkin menggunakan 10–20MB karena penggabungan fitur yang cepat. Optimasi sumber daya direncanakan. Perbandingan startup berdasarkan benchmark prosesor single-core 0,8GHz (lihat tabel di bawah)._
+_*Build terbaru mungkin menggunakan 10-20MB karena penggabungan PR yang cepat. Optimasi sumber daya direncanakan. Perbandingan kecepatan boot berdasarkan benchmark single-core 0,8GHz (lihat tabel di bawah)._
-| | OpenClaw | NanoBot | **PicoClaw** |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Bahasa** | TypeScript | Python | **Go** |
-| **RAM** | >1GB | >100MB | **< 10MB*** |
-| **Startup**(0,8GHz core) | >500d | >30d | **<1d** |
-| **Biaya** | Mac Mini $599 | Kebanyakan Linux SBC ~$50 | **Semua Board Linux****Mulai dari $10** |
+
+
+| | OpenClaw | NanoBot | **PicoClaw** |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Bahasa** | TypeScript | Python | **Go** |
+| **RAM** | >1GB | >100MB | **< 10MB*** |
+| **Waktu Boot**(core 0,8GHz) | >500d | >30d | **<1d** |
+| **Biaya** | Mac Mini $599 | Kebanyakan board Linux ~$50 | **Board Linux mana pun****mulai $10** |
+
+
+> **[Daftar Kompatibilitas Hardware](docs/hardware-compatibility.md)** — Lihat semua board yang telah diuji, dari RISC-V $5 hingga Raspberry Pi hingga ponsel Android. Board Anda belum terdaftar? Kirim PR!
+
+
+
+
## 🦾 Demonstrasi
### 🛠️ Alur Kerja Asisten Standar
-
- 🧩 Full-Stack Engineer
🗂️ Pencatatan & Manajemen Perencanaan
🔎 Pencarian Web & Pembelajaran
-
-
-
- Develop • Deploy • Scale
- Jadwal • Otomasi • Memori
- Penemuan • Wawasan • Tren
-
+
+Mode Full-Stack Engineer
Pencatatan & Perencanaan
Pencarian Web & Pembelajaran
+
+
+
+Develop · Deploy · Scale
+Jadwal · Otomasi · Ingat
+Temukan · Wawasan · Tren
+
-### 📱 Jalankan di HP Android Lama
-
-Berikan kehidupan kedua untuk HP lama Anda! Ubah menjadi Asisten AI pintar dengan PicoClaw. Panduan Cepat:
-
-1. **Instal [Termux](https://github.com/termux/termux-app)** (Unduh dari [GitHub Releases](https://github.com/termux/termux-app/releases), atau cari di F-Droid / Google Play).
-2. **Jalankan perintah**
-
-```bash
-# Unduh rilis terbaru dari https://github.com/sipeed/picoclaw/releases
-wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
-tar xzf picoclaw_Linux_arm64.tar.gz
-pkg install proot
-termux-chroot ./picoclaw onboard
-```
-
-Kemudian ikuti instruksi di bagian "Panduan Cepat" untuk menyelesaikan konfigurasi!
-
-
-
### 🐜 Deploy Inovatif dengan Footprint Rendah
PicoClaw dapat di-deploy di hampir semua perangkat Linux!
-- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versi E(Ethernet) atau W(WiFi6), untuk Home Assistant Minimal
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), atau $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) untuk Pemeliharaan Server Otomatis
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) atau $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) untuk Pemantauan Cerdas
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versi E(Ethernet) atau W(WiFi6), untuk home assistant minimal
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), atau $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), untuk operasi server otomatis
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) atau $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), untuk pengawasan cerdas
@@ -160,11 +150,15 @@ PicoClaw dapat di-deploy di hampir semua perangkat Linux!
## 📦 Instalasi
-### Instal dengan binary yang sudah dikompilasi
+### Unduh dari picoclaw.io (Direkomendasikan)
-Unduh binary untuk platform Anda dari halaman [Releases](https://github.com/sipeed/picoclaw/releases).
+Kunjungi **[picoclaw.io](https://picoclaw.io)** — website resmi mendeteksi platform Anda secara otomatis dan menyediakan unduhan satu klik. Tidak perlu memilih arsitektur secara manual.
-### Instal dari source (fitur terbaru, disarankan untuk pengembangan)
+### Unduh binary yang sudah dikompilasi
+
+Atau, unduh binary untuk platform Anda dari halaman [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Build dari source (untuk pengembangan)
```bash
git clone https://github.com/sipeed/picoclaw.git
@@ -172,78 +166,414 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
-# Build, tidak perlu instal
+# Build binary inti
make build
+# Build Web UI Launcher (diperlukan untuk mode WebUI)
+make build-launcher
+
# Build untuk berbagai platform
make build-all
# Build untuk Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
make build-pi-zero
-# Build dan Instal
+# Build dan instal
make install
```
-**Raspberry Pi Zero 2 W:** Gunakan binary yang sesuai dengan OS Anda: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Atau jalankan `make build-pi-zero` untuk build keduanya.
+**Raspberry Pi Zero 2 W:** Gunakan binary yang sesuai dengan OS Anda: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Atau jalankan `make build-pi-zero` untuk build keduanya.
-## 📚 Dokumentasi
+## 🚀 Panduan Memulai Cepat
-Untuk panduan lengkap, lihat dokumen di bawah. README ini hanya berisi panduan cepat.
+### 🌐 WebUI Launcher (Direkomendasikan untuk Desktop)
-| Topik | Deskripsi |
-|-------|-----------|
-| 🐳 [Docker & Panduan Cepat](docs/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent, konfigurasi Panduan Cepat |
-| 💬 [Aplikasi Chat](docs/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom, dan lainnya |
-| ⚙️ [Konfigurasi](docs/configuration.md) | Variabel environment, tata letak workspace, sumber skill, sandbox keamanan, heartbeat |
-| 🔌 [Provider & Model](docs/providers.md) | 20+ provider LLM, routing model, konfigurasi model_list, arsitektur provider |
-| 🔄 [Spawn & Tugas Async](docs/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async |
-| 🐛 [Pemecahan Masalah](docs/troubleshooting.md) | Masalah umum dan solusinya |
-| 🔧 [Konfigurasi Tools](docs/tools_configuration.md) | Aktifkan/nonaktifkan tool, kebijakan exec |
+WebUI Launcher menyediakan antarmuka berbasis browser untuk konfigurasi dan chat. Ini adalah cara termudah untuk memulai — tidak perlu pengetahuan command-line.
+
+**Opsi 1: Klik dua kali (Desktop)**
+
+Setelah mengunduh dari [picoclaw.io](https://picoclaw.io), klik dua kali `picoclaw-launcher` (atau `picoclaw-launcher.exe` di Windows). Browser Anda akan terbuka otomatis di `http://localhost:18800`.
+
+**Opsi 2: Command line**
+
+```bash
+picoclaw-launcher
+# Buka http://localhost:18800 di browser Anda
+```
+
+> [!TIP]
+> **Akses jarak jauh / Docker / VM:** Tambahkan flag `-public` untuk mendengarkan di semua antarmuka:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+
+
+
+**Memulai:**
+
+Buka WebUI, lalu: **1)** Konfigurasi Provider (tambahkan API key LLM Anda) -> **2)** Konfigurasi Channel (mis. Telegram) -> **3)** Mulai Gateway -> **4)** Chat!
+
+Untuk dokumentasi WebUI lengkap, lihat [docs.picoclaw.io](https://docs.picoclaw.io).
+
+
+Docker (alternatif)
+
+### 💻 TUI Launcher (Direkomendasikan untuk Headless / SSH)
+
+TUI (Terminal UI) Launcher menyediakan antarmuka terminal lengkap untuk konfigurasi dan manajemen. Ideal untuk server, Raspberry Pi, dan lingkungan headless lainnya.
+
+```bash
+picoclaw-launcher-tui
+```
+
+
+
+
+**Memulai:**
+
+Gunakan menu TUI untuk: **1)** Konfigurasi Provider -> **2)** Konfigurasi Channel -> **3)** Mulai Gateway -> **4)** Chat!
+
+Untuk dokumentasi TUI lengkap, lihat [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Berikan kehidupan kedua untuk ponsel lama Anda! Ubah menjadi Asisten AI pintar dengan PicoClaw.
+
+**Opsi 1: Termux (tersedia sekarang)**
+
+1. Instal [Termux](https://github.com/termux/termux-app) (unduh dari [GitHub Releases](https://github.com/termux/termux-app/releases), atau cari di F-Droid / Google Play)
+2. Jalankan perintah berikut:
+
+```bash
+# Unduh rilis terbaru
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard # chroot menyediakan tata letak filesystem Linux standar
+```
+
+Kemudian ikuti bagian Terminal Launcher di bawah untuk menyelesaikan konfigurasi.
+
+
+Terminal Launcher (untuk lingkungan dengan sumber daya terbatas)
+
+## 🔌 Providers (LLM)
+
+PicoClaw mendukung 30+ provider LLM melalui konfigurasi `model_list`. Gunakan format `protocol/model`:
+
+| Provider | Protocol | API Key | Catatan |
+|----------|----------|---------|---------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Diperlukan | GPT-5.4, GPT-4o, o3, dll. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Diperlukan | Claude Opus 4.6, Sonnet 4.6, dll. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Diperlukan | Gemini 3 Flash, 2.5 Pro, dll. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Diperlukan | 200+ model, API terpadu |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Diperlukan | GLM-4.7, GLM-5, dll. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Diperlukan | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Diperlukan | Doubao, model Ark |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Diperlukan | Qwen3, Qwen-Max, dll. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Diperlukan | Inferensi cepat (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Diperlukan | Model Kimi |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Diperlukan | Model MiniMax |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Diperlukan | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Diperlukan | Model yang di-host NVIDIA |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Diperlukan | Inferensi cepat |
+| [Novita AI](https://novita.ai/) | `novita/` | Diperlukan | Berbagai model open |
+| [Ollama](https://ollama.com/) | `ollama/` | Tidak perlu | Model lokal, self-hosted |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Tidak perlu | Deploy lokal, kompatibel OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Bervariasi | Proxy untuk 100+ provider |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Diperlukan | Deploy Azure enterprise |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login dengan device code |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+
+Deploy lokal (Ollama, vLLM, dll.)
+
+## 💬 Channels (Aplikasi Chat)
+
+Bicara dengan PicoClaw Anda melalui 17+ platform pesan:
+
+| Channel | Pengaturan | Protocol | Dokumentasi |
+|---------|------------|----------|-------------|
+| **Telegram** | Mudah (bot token) | Long polling | [Panduan](docs/channels/telegram/README.md) |
+| **Discord** | Mudah (bot token + intents) | WebSocket | [Panduan](docs/channels/discord/README.md) |
+| **WhatsApp** | Mudah (scan QR atau bridge URL) | Native / Bridge | [Panduan](docs/chat-apps.md#whatsapp) |
+| **Weixin** | Mudah (scan QR native) | iLink API | [Panduan](docs/chat-apps.md#weixin) |
+| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](docs/channels/qq/README.md) |
+| **Slack** | Mudah (bot + app token) | Socket Mode | [Panduan](docs/channels/slack/README.md) |
+| **Matrix** | Sedang (homeserver + token) | Sync API | [Panduan](docs/channels/matrix/README.md) |
+| **DingTalk** | Sedang (client credentials) | Stream | [Panduan](docs/channels/dingtalk/README.md) |
+| **Feishu / Lark** | Sedang (App ID + Secret) | WebSocket/SDK | [Panduan](docs/channels/feishu/README.md) |
+| **LINE** | Sedang (credentials + webhook) | Webhook | [Panduan](docs/channels/line/README.md) |
+| **WeCom Bot** | Sedang (webhook URL) | Webhook | [Panduan](docs/channels/wecom/wecom_bot/README.md) |
+| **WeCom App** | Sedang (corp credentials) | Webhook | [Panduan](docs/channels/wecom/wecom_app/README.md) |
+| **WeCom AI Bot** | Sedang (token + AES key) | WebSocket / Webhook | [Panduan](docs/channels/wecom/wecom_aibot/README.md) |
+| **IRC** | Sedang (server + nick) | IRC protocol | [Panduan](docs/chat-apps.md#irc) |
+| **OneBot** | Sedang (WebSocket URL) | OneBot v11 | [Panduan](docs/channels/onebot/README.md) |
+| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](docs/channels/maixcam/README.md) |
+| **Pico** | Mudah (aktifkan) | Native protocol | Bawaan |
+| **Pico Client** | Mudah (WebSocket URL) | WebSocket | Bawaan |
+
+> Semua channel berbasis webhook berbagi satu server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu menggunakan mode WebSocket/SDK dan tidak menggunakan server HTTP bersama.
+
+Untuk instruksi pengaturan channel lengkap, lihat [Konfigurasi Aplikasi Chat](docs/chat-apps.md).
+
+## 🔧 Tools
+
+### 🔍 Pencarian Web
+
+PicoClaw dapat mencari web untuk memberikan informasi terkini. Konfigurasi di `tools.web`:
+
+| Mesin Pencari | API Key | Tier Gratis | Tautan |
+|--------------|---------|-------------|--------|
+| DuckDuckGo | Tidak perlu | Tidak terbatas | Fallback bawaan |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Diperlukan | 1000 kueri/hari | Bertenaga AI, dioptimalkan untuk bahasa Mandarin |
+| [Tavily](https://tavily.com) | Diperlukan | 1000 kueri/bulan | Dioptimalkan untuk AI Agent |
+| [Brave Search](https://brave.com/search/api) | Diperlukan | 2000 kueri/bulan | Cepat dan privat |
+| [Perplexity](https://www.perplexity.ai) | Diperlukan | Berbayar | Pencarian bertenaga AI |
+| [SearXNG](https://github.com/searxng/searxng) | Tidak perlu | Self-hosted | Mesin metasearch gratis |
+| [GLM Search](https://open.bigmodel.cn/) | Diperlukan | Bervariasi | Pencarian web Zhipu |
+
+### ⚙️ Tools Lainnya
+
+PicoClaw menyertakan tools bawaan untuk operasi file, eksekusi kode, penjadwalan, dan lainnya. Lihat [Konfigurasi Tools](docs/tools_configuration.md) untuk detail.
+
+## 🎯 Skills
+
+Skills adalah kapabilitas modular yang memperluas Agent Anda. Dimuat dari file `SKILL.md` di workspace Anda.
+
+**Instal skills dari ClawHub:**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install
+```
+
+**Konfigurasi token ClawHub** (opsional, untuk rate limit lebih tinggi):
+
+Tambahkan ke `config.json` Anda:
+```json
+{
+ "tools": {
+ "skills": {
+ "registries": {
+ "clawhub": {
+ "auth_token": "your-clawhub-token"
+ }
+ }
+ }
+ }
+}
+```
+
+Untuk detail lebih lanjut, lihat [Konfigurasi Tools - Skills](docs/tools_configuration.md#skills-tool).
+
+## 🔗 MCP (Model Context Protocol)
+
+PicoClaw mendukung [MCP](https://modelcontextprotocol.io/) secara native — hubungkan server MCP mana pun untuk memperluas kapabilitas Agent Anda dengan tools dan sumber data eksternal.
+
+```json
+{
+ "tools": {
+ "mcp": {
+ "enabled": true,
+ "servers": {
+ "filesystem": {
+ "enabled": true,
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+ }
+ }
+ }
+ }
+}
+```
+
+Untuk konfigurasi MCP lengkap (transport stdio, SSE, HTTP, Tool Discovery), lihat [Konfigurasi Tools - MCP](docs/tools_configuration.md#mcp-tool).
##
+Discord:
+
+WeChat:
+
-
+
-
PicoClaw: Assistente IA Ultra-Efficiente in Go
+
PicoClaw: Assistente IA Ultra-Efficiente in Go
-
Hardware da $10 · <10MB RAM · Boot in <1s · 皮皮虾，我们走！
+
Hardware da $10 · 10MB di RAM · Avvio in ms · Let's Go, PicoClaw!
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
> [!CAUTION]
-> **🚨 SICUREZZA & CANALI UFFICIALI**
+> **Avviso di Sicurezza**
>
-> * **NESSUNA CRYPTO:** PicoClaw non ha **NESSUN** token/coin ufficiale. Qualsiasi annuncio su `pump.fun` o altre piattaforme di trading è una **TRUFFA**.
->
-> * **DOMINIO UFFICIALE:** L'**UNICO** sito ufficiale è **[picoclaw.io](https://picoclaw.io)**, e il sito aziendale è **[sipeed.com](https://sipeed.com)**.
-> * **Attenzione:** Molti domini `.ai/.org/.com/.net/...` sono registrati da terze parti.
-> * **Attenzione:** PicoClaw è in fase di sviluppo iniziale e potrebbe avere problemi di sicurezza di rete non risolti. Non distribuire in ambienti di produzione prima della release v1.0.
-> * **Nota:** PicoClaw ha recentemente unito molte PR, il che potrebbe comportare un'impronta di memoria maggiore (10–20MB) nelle ultime versioni. Prevediamo di dare priorità all'ottimizzazione delle risorse non appena il set di funzionalità corrente raggiungerà uno stato stabile.
+> * **NESSUNA CRYPTO:** PicoClaw **non** ha emesso token o criptovalute ufficiali. Qualsiasi annuncio su `pump.fun` o altre piattaforme di trading è una **truffa**.
+> * **DOMINIO UFFICIALE:** L'**UNICO** sito ufficiale è **[picoclaw.io](https://picoclaw.io)**, e il sito aziendale è **[sipeed.com](https://sipeed.com)**
+> * **ATTENZIONE:** Molti domini `.ai/.org/.com/.net/...` sono stati registrati da terze parti. Non fidarti di essi.
+> * **NOTA:** PicoClaw è in fase di sviluppo iniziale rapido. Potrebbero esserci problemi di sicurezza non risolti. Non distribuire in produzione prima della v1.0.
+> * **NOTA:** PicoClaw ha recentemente unito molte PR. Le build recenti potrebbero usare 10-20MB di RAM. L'ottimizzazione delle risorse è pianificata dopo la stabilizzazione delle funzionalità.
## 📢 Novità
-2026-03-17 🚀 **v0.2.3 rilasciata!** Interfaccia system tray (Windows & Linux), tracciamento dello stato dei sub-agent (`spawn_status`), hot-reload sperimentale del gateway, gate di sicurezza per cron e 2 correzioni di sicurezza. PicoClaw raggiunge **25K ⭐**!
+2026-03-17 🚀 **v0.2.3 rilasciata!** Interfaccia system tray (Windows & Linux), query sullo stato dei sub-agent (`spawn_status`), hot-reload sperimentale del Gateway, gate di sicurezza per Cron e 2 correzioni di sicurezza. PicoClaw raggiunge **25K Stars**!
2026-03-09 🎉 **v0.2.1 — Il più grande aggiornamento di sempre!** Supporto al protocollo MCP, 4 nuovi canali (Matrix/IRC/WeCom/Discord Proxy), 3 nuovi provider (Kimi/Minimax/Avian), pipeline di visione, store di memoria JSONL e routing dei modelli.
-2026-02-28 📦 **v0.2.0** rilasciata con supporto Docker Compose e launcher Web UI.
+2026-02-28 📦 **v0.2.0** rilasciata con supporto Docker Compose e Web UI Launcher.
-2026-02-26 🎉 PicoClaw ha raggiunto **20K stelle** in soli 17 giorni! Arrivate l'orchestrazione automatica dei canali e le interfacce di capacità.
+2026-02-26 🎉 PicoClaw raggiunge **20K stelle** in soli 17 giorni! Orchestrazione automatica dei canali e interfacce di capacità sono attive.
Notizie precedenti...
-2026-02-16 🎉 PicoClaw ha raggiunto 12K stelle in una settimana! Ruoli di maintainer della community e [roadmap](ROADMAP.md) pubblicati ufficialmente.
+2026-02-16 🎉 PicoClaw supera 12K stelle in una settimana! Ruoli di maintainer della community e [Roadmap](ROADMAP.md) pubblicati ufficialmente.
-2026-02-13 🎉 PicoClaw ha raggiunto 5000 stelle in 4 giorni! Roadmap del progetto e gruppo sviluppatori in fase di avvio.
+2026-02-13 🎉 PicoClaw supera 5000 stelle in 4 giorni! Roadmap del progetto e gruppi sviluppatori in fase di avvio.
-2026-02-09 🎉 **PicoClaw lanciato!** Costruito in 1 giorno per portare gli agenti IA su hardware da $10 con <10MB di RAM. 🦐 PicoClaw, andiamo!
+2026-02-09 🎉 **PicoClaw lanciato!** Costruito in 1 giorno per portare gli AI Agent su hardware da $10 con <10MB di RAM. Let's Go, PicoClaw!
## ✨ Caratteristiche
-🪶 **Ultra-Leggero**: Impronta di memoria <10MB — il 99% più piccolo delle funzionalità principali di OpenClaw.*
+🪶 **Ultra-Leggero**: Impronta di memoria <10MB — il 99% più piccolo rispetto a OpenClaw.*
💰 **Costo Minimo**: Abbastanza efficiente da girare su hardware da $10 — il 98% più economico di un Mac mini.
-⚡️ **Avvio Fulmineo**: Tempo di avvio 400 volte più veloce, boot in meno di 1 secondo anche su un singolo core a 0,6 GHz.
+⚡️ **Avvio Fulmineo**: Avvio 400 volte più veloce. Boot in meno di 1 secondo anche su un singolo core a 0,6 GHz.
-🌍 **Vera Portabilità**: Singolo binario autonomo per RISC-V, ARM, MIPS e x86. Un click e si parte!
+🌍 **Vera Portabilità**: Singolo binario per RISC-V, ARM, MIPS e x86. Un binario, funziona ovunque!
-🤖 **Auto-Costruito dall'IA**: Implementazione nativa in Go in modo autonomo — 95% del core generato dall'Agent con perfezionamento umano nel ciclo.
+🤖 **Auto-Costruito dall'IA**: Implementazione nativa in Go — il 95% del codice core è stato generato da un Agent e perfezionato tramite revisione umana nel ciclo.
-🔌 **Supporto MCP**: Integrazione nativa del [Model Context Protocol](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità dell'agent.
+🔌 **Supporto MCP**: Integrazione nativa del [Model Context Protocol](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità dell'Agent.
-👁️ **Pipeline di Visione**: Invia immagini e file direttamente all'agent — codifica base64 automatica per LLM multimodali.
+👁️ **Pipeline di Visione**: Invia immagini e file direttamente all'Agent — codifica base64 automatica per LLM multimodali.
🧠 **Routing Intelligente**: Routing dei modelli basato su regole — le query semplici vanno verso modelli leggeri, risparmiando sui costi API.
-_*Le versioni recenti potrebbero usare 10–20MB a causa delle fusioni rapide di funzionalità. L'ottimizzazione delle risorse è pianificata. Il confronto dell'avvio è basato su benchmark con singolo core a 0,8 GHz (vedi tabella sotto)._
+_*Le build recenti potrebbero usare 10-20MB a causa delle fusioni rapide di PR. L'ottimizzazione delle risorse è pianificata. Il confronto dell'avvio è basato su benchmark con singolo core a 0,8 GHz (vedi tabella sotto)._
-| | OpenClaw | NanoBot | **PicoClaw** |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Linguaggio** | TypeScript | Python | **Go** |
-| **RAM** | >1GB | >100MB | **< 10MB*** |
-| **Avvio**(core 0,8 GHz) | >500s | >30s | **<1s** |
-| **Costo** | Mac Mini $599 | La maggior parte degli SBC Linux ~$50 | **Qualsiasi scheda Linux****A partire da $10** |
+
+
+| | OpenClaw | NanoBot | **PicoClaw** |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Linguaggio** | TypeScript | Python | **Go** |
+| **RAM** | >1GB | >100MB | **< 10MB*** |
+| **Avvio**(core 0,8 GHz) | >500s | >30s | **<1s** |
+| **Costo** | Mac Mini $599 | La maggior parte degli SBC Linux ~$50 | **Qualsiasi scheda Linux****a partire da $10** |
+
+
+> **[Lista di Compatibilità Hardware](docs/hardware-compatibility.md)** — Vedi tutte le schede testate, dai $5 RISC-V al Raspberry Pi ai telefoni Android. La tua scheda non è elencata? Invia una PR!
+
+
+
+
## 🦾 Dimostrazione
### 🛠️ Flussi di Lavoro Standard dell'Assistente
-
- 🧩 Ingegnere Full-Stack
🗂️ Gestione Log & Pianificazione
🔎 Ricerca Web & Apprendimento
-
-
-
- Sviluppa • Distribuisci • Scala
- Pianifica • Automatizza • Memorizza
- Scopri • Analizza • Tendenze
-
+
+Modalità Ingegnere Full-Stack
Log & Pianificazione
Ricerca Web & Apprendimento
+
+
+
+Sviluppa · Distribuisci · Scala
+Pianifica · Automatizza · Memorizza
+Scopri · Analizza · Tendenze
+
-### 📱 Usa su vecchi telefoni Android
-
-Dai una seconda vita al tuo telefono di dieci anni fa! Trasformalo in un assistente IA intelligente con PicoClaw. Avvio rapido:
-
-1. **Installa [Termux](https://github.com/termux/termux-app)** (Scarica da [GitHub Releases](https://github.com/termux/termux-app/releases), o cerca su F-Droid / Google Play).
-2. **Esegui i comandi**
-
-```bash
-# Scarica l'ultima release da https://github.com/sipeed/picoclaw/releases
-wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
-tar xzf picoclaw_Linux_arm64.tar.gz
-pkg install proot
-termux-chroot ./picoclaw onboard
-```
-
-Poi segui le istruzioni nella sezione "Avvio Rapido" per completare la configurazione!
-
-
-
### 🐜 Deploy Innovativo a Bassa Impronta
PicoClaw può essere distribuito su quasi qualsiasi dispositivo Linux!
-- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versione E (Ethernet) o W (WiFi6), per un Assistente Domotico Minimale
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), o $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) per la Manutenzione Automatizzata dei Server
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) o $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) per il Monitoraggio Intelligente
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versione E (Ethernet) o W (WiFi6), per un assistente domotico minimale
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), o $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), per la manutenzione automatizzata dei server
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) o $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), per la sorveglianza intelligente
@@ -160,11 +150,15 @@ PicoClaw può essere distribuito su quasi qualsiasi dispositivo Linux!
## 📦 Installazione
-### Installa con binario precompilato
+### Scarica da picoclaw.io (Consigliato)
-Scarica il binario per la tua piattaforma dalla pagina delle [Releases](https://github.com/sipeed/picoclaw/releases).
+Visita **[picoclaw.io](https://picoclaw.io)** — il sito ufficiale rileva automaticamente la tua piattaforma e fornisce il download con un clic. Non è necessario scegliere manualmente l'architettura.
-### Installa dai sorgenti (ultime funzionalità, consigliato per lo sviluppo)
+### Scarica il binario precompilato
+
+In alternativa, scarica il binario per la tua piattaforma dalla pagina delle [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Compila dai sorgenti (per lo sviluppo)
```bash
git clone https://github.com/sipeed/picoclaw.git
@@ -172,34 +166,348 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
-# Compila, senza installare
+# Compila il binario core
make build
+# Compila il Web UI Launcher (necessario per la modalità WebUI)
+make build-launcher
+
# Compila per più piattaforme
make build-all
# Compila per Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
make build-pi-zero
-# Compila e Installa
+# Compila e installa
make install
```
-**Raspberry Pi Zero 2 W:** Usa il binario che corrisponde al tuo OS: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Oppure esegui `make build-pi-zero` per compilare entrambi.
+**Raspberry Pi Zero 2 W:** Usa il binario che corrisponde al tuo OS: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Oppure esegui `make build-pi-zero` per compilare entrambi.
-## 📚 Documentazione
+## 🚀 Guida Rapida
-Per guide dettagliate, consulta la documentazione qui sotto. Il README copre solo l'avvio rapido.
+### 🌐 WebUI Launcher (Consigliato per Desktop)
-| Argomento | Descrizione |
-|-----------|-------------|
-| 🐳 [Docker & Avvio Rapido](docs/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent, configurazione rapida |
-| 💬 [App di Chat](docs/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom e altro |
-| ⚙️ [Configurazione](docs/it/configuration.md) | Variabili d'ambiente, struttura del workspace, sorgenti delle skill, sandbox di sicurezza, heartbeat |
-| 🔌 [Provider & Modelli](docs/providers.md) | 20+ provider LLM, routing dei modelli, configurazione model_list, architettura dei provider |
-| 🔄 [Spawn & Task Asincroni](docs/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
-| 🐛 [Risoluzione Problemi](docs/troubleshooting.md) | Problemi comuni e soluzioni |
-| 🔧 [Configurazione degli Strumenti](docs/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec |
+Il WebUI Launcher fornisce un'interfaccia basata su browser per la configurazione e la chat. È il modo più semplice per iniziare — non è richiesta alcuna conoscenza della riga di comando.
+
+**Opzione 1: Doppio clic (Desktop)**
+
+Dopo aver scaricato da [picoclaw.io](https://picoclaw.io), fai doppio clic su `picoclaw-launcher` (o `picoclaw-launcher.exe` su Windows). Il browser si aprirà automaticamente su `http://localhost:18800`.
+
+**Opzione 2: Riga di comando**
+
+```bash
+picoclaw-launcher
+# Apri http://localhost:18800 nel browser
+```
+
+> [!TIP]
+> **Accesso remoto / Docker / VM:** Aggiungi il flag `-public` per ascoltare su tutte le interfacce:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+
+
+
+**Per iniziare:**
+
+Apri il WebUI, poi: **1)** Configura un Provider (aggiungi la tua API key LLM) -> **2)** Configura un Channel (es. Telegram) -> **3)** Avvia il Gateway -> **4)** Chatta!
+
+Per la documentazione dettagliata del WebUI, vedi [docs.picoclaw.io](https://docs.picoclaw.io).
+
+
+Docker (alternativa)
+
+### 💻 TUI Launcher (Consigliato per Headless / SSH)
+
+Il TUI (Terminal UI) Launcher fornisce un'interfaccia terminale completa per la configurazione e la gestione. Ideale per server, Raspberry Pi e altri ambienti headless.
+
+```bash
+picoclaw-launcher-tui
+```
+
+
+
+
+**Per iniziare:**
+
+Usa i menu TUI per: **1)** Configurare un Provider -> **2)** Configurare un Channel -> **3)** Avviare il Gateway -> **4)** Chattare!
+
+Per la documentazione dettagliata del TUI, vedi [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Dai una seconda vita al tuo telefono di dieci anni fa! Trasformalo in un assistente IA intelligente con PicoClaw.
+
+**Opzione 1: Termux (disponibile ora)**
+
+1. Installa [Termux](https://github.com/termux/termux-app) (scarica da [GitHub Releases](https://github.com/termux/termux-app/releases), o cerca su F-Droid / Google Play)
+2. Esegui i seguenti comandi:
+
+```bash
+# Scarica l'ultima release
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard # chroot fornisce un layout standard del filesystem Linux
+```
+
+Poi segui la sezione Terminal Launcher qui sotto per completare la configurazione.
+
+
+Terminal Launcher (per ambienti con risorse limitate)
+
+## 🔌 Provider (LLM)
+
+PicoClaw supporta 30+ provider LLM tramite la configurazione `model_list`. Usa il formato `protocollo/modello`:
+
+| Provider | Protocollo | API Key | Note |
+|----------|------------|---------|------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Richiesta | GPT-5.4, GPT-4o, o3, ecc. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Richiesta | Claude Opus 4.6, Sonnet 4.6, ecc. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Richiesta | Gemini 3 Flash, 2.5 Pro, ecc. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Richiesta | 200+ modelli, API unificata |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Richiesta | GLM-4.7, GLM-5, ecc. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Richiesta | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Richiesta | Doubao, modelli Ark |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Richiesta | Qwen3, Qwen-Max, ecc. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Richiesta | Inferenza veloce (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Richiesta | Modelli Kimi |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Richiesta | Modelli MiniMax |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Richiesta | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Richiesta | Modelli ospitati NVIDIA |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Richiesta | Inferenza veloce |
+| [Novita AI](https://novita.ai/) | `novita/` | Richiesta | Vari modelli open |
+| [Ollama](https://ollama.com/) | `ollama/` | Non necessaria | Modelli locali, self-hosted |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Non necessaria | Deploy locale, compatibile OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Variabile | Proxy per 100+ provider |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Richiesta | Deploy Azure enterprise |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login con device code |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+
+Deploy locale (Ollama, vLLM, ecc.)
+
+## 💬 Channel (App di Chat)
+
+Parla con il tuo PicoClaw attraverso 17+ piattaforme di messaggistica:
+
+| Channel | Configurazione | Protocollo | Docs |
+|---------|----------------|------------|------|
+| **Telegram** | Facile (bot token) | Long polling | [Guida](docs/channels/telegram/README.md) |
+| **Discord** | Facile (bot token + intents) | WebSocket | [Guida](docs/channels/discord/README.md) |
+| **WhatsApp** | Facile (QR scan o bridge URL) | Nativo / Bridge | [Guida](docs/chat-apps.md#whatsapp) |
+| **Weixin** | Facile (scan QR nativo) | iLink API | [Guida](docs/chat-apps.md#weixin) |
+| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guida](docs/channels/qq/README.md) |
+| **Slack** | Facile (bot + app token) | Socket Mode | [Guida](docs/channels/slack/README.md) |
+| **Matrix** | Medio (homeserver + token) | Sync API | [Guida](docs/channels/matrix/README.md) |
+| **DingTalk** | Medio (credenziali client) | Stream | [Guida](docs/channels/dingtalk/README.md) |
+| **Feishu / Lark** | Medio (App ID + Secret) | WebSocket/SDK | [Guida](docs/channels/feishu/README.md) |
+| **LINE** | Medio (credenziali + webhook) | Webhook | [Guida](docs/channels/line/README.md) |
+| **WeCom Bot** | Medio (webhook URL) | Webhook | [Guida](docs/channels/wecom/wecom_bot/README.md) |
+| **WeCom App** | Medio (credenziali aziendali) | Webhook | [Guida](docs/channels/wecom/wecom_app/README.md) |
+| **WeCom AI Bot** | Medio (token + AES key) | WebSocket / Webhook | [Guida](docs/channels/wecom/wecom_aibot/README.md) |
+| **IRC** | Medio (server + nick) | Protocollo IRC | [Guida](docs/chat-apps.md#irc) |
+| **OneBot** | Medio (WebSocket URL) | OneBot v11 | [Guida](docs/channels/onebot/README.md) |
+| **MaixCam** | Facile (abilita) | TCP socket | [Guida](docs/channels/maixcam/README.md) |
+| **Pico** | Facile (abilita) | Protocollo nativo | Integrato |
+| **Pico Client** | Facile (WebSocket URL) | WebSocket | Integrato |
+
+> Tutti i channel basati su webhook condividono un singolo server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu usa la modalità WebSocket/SDK e non usa il server HTTP condiviso.
+
+Per istruzioni dettagliate sulla configurazione dei channel, vedi [Configurazione App di Chat](docs/chat-apps.md).
+
+## 🔧 Strumenti
+
+### 🔍 Ricerca Web
+
+PicoClaw può cercare sul web per fornire informazioni aggiornate. Configura in `tools.web`:
+
+| Motore di Ricerca | API Key | Piano Gratuito | Link |
+|-------------------|---------|----------------|------|
+| DuckDuckGo | Non necessaria | Illimitato | Fallback integrato |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Richiesta | 1000 query/giorno | IA, ottimizzato per il cinese |
+| [Tavily](https://tavily.com) | Richiesta | 1000 query/mese | Ottimizzato per AI Agent |
+| [Brave Search](https://brave.com/search/api) | Richiesta | 2000 query/mese | Veloce e privato |
+| [Perplexity](https://www.perplexity.ai) | Richiesta | A pagamento | Ricerca potenziata dall'IA |
+| [SearXNG](https://github.com/searxng/searxng) | Non necessaria | Self-hosted | Metasearch engine gratuito |
+| [GLM Search](https://open.bigmodel.cn/) | Richiesta | Variabile | Ricerca web Zhipu |
+
+### ⚙️ Altri Strumenti
+
+PicoClaw include strumenti integrati per operazioni su file, esecuzione di codice, pianificazione e altro. Vedi [Configurazione degli Strumenti](docs/tools_configuration.md) per i dettagli.
+
+## 🎯 Skill
+
+Le Skill sono capacità modulari che estendono il tuo Agent. Vengono caricate dai file `SKILL.md` nel tuo workspace.
+
+**Installa skill da ClawHub:**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install
+```
+
+**Configura il token ClawHub** (opzionale, per limiti di frequenza più alti):
+
+Aggiungi al tuo `config.json`:
+```json
+{
+ "tools": {
+ "skills": {
+ "registries": {
+ "clawhub": {
+ "auth_token": "your-clawhub-token"
+ }
+ }
+ }
+ }
+}
+```
+
+Per maggiori dettagli, vedi [Configurazione degli Strumenti - Skill](docs/tools_configuration.md#skills-tool).
+
+## 🔗 MCP (Model Context Protocol)
+
+PicoClaw supporta nativamente [MCP](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità del tuo Agent con strumenti e sorgenti di dati esterni.
+
+```json
+{
+ "tools": {
+ "mcp": {
+ "enabled": true,
+ "servers": {
+ "filesystem": {
+ "enabled": true,
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+ }
+ }
+ }
+ }
+}
+```
+
+Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](docs/tools_configuration.md#mcp-tool).
##
+Discord:
-PicoClaw: Go で書かれた超効率 AI アシスタント
- $10 ハードウェア · <10MB RAM · <1秒起動 · 行くぜ、シャコ！
+ $10 ハードウェア · 10MB RAM · ms 起動 · Let's Go, PicoClaw!
> [!CAUTION]
-> **🚨 セキュリティ＆公式チャンネル**
+> **セキュリティに関する注意**
>
> * **暗号通貨なし:** PicoClaw には公式トークン/コインは**一切ありません**。`pump.fun` やその他の取引プラットフォームでの主張はすべて**詐欺**です。
->
> * **公式ドメイン:** **唯一**の公式サイトは **[picoclaw.io](https://picoclaw.io)**、企業サイトは **[sipeed.com](https://sipeed.com)** です。
-> * **注意:** 多くの `.ai/.org/.com/.net/...` ドメインは第三者によって登録されています。
-> * **注意:** PicoClaw は初期開発段階にあり、未解決のネットワークセキュリティ問題がある可能性があります。v1.0 リリース前に本番環境へのデプロイは避けてください。
+> * **注意:** 多くの `.ai/.org/.com/.net/...` ドメインは第三者によって登録されています。信頼しないでください。
+> * **注記:** PicoClaw は初期開発段階にあり、未解決のネットワークセキュリティ問題がある可能性があります。v1.0 リリース前に本番環境へのデプロイは避けてください。
> * **注記:** PicoClaw は最近多くの PR をマージしており、最新バージョンではメモリフットプリントが大きくなる場合があります（10〜20MB）。機能セットが安定次第、リソース最適化を優先する予定です。
## 📢 ニュース
-2026-03-17 🚀 **v0.2.3 リリース！** システムトレイ UI（Windows & Linux）、サブエージェントステータス追跡（`spawn_status`）、実験的ゲートウェイホットリロード、cron セキュリティゲート、セキュリティ修正 2 件。PicoClaw **25K ⭐** 達成！
+2026-03-17 🚀 **v0.2.3 リリース！** システムトレイ UI（Windows & Linux）、サブエージェントステータス追跡（`spawn_status`）、実験的 Gateway ホットリロード、cron セキュリティゲート、セキュリティ修正 2 件。PicoClaw **25K ⭐** 達成！
-2026-03-09 🎉 **v0.2.1 — 史上最大のアップデート！** MCP プロトコル対応、4 つの新チャネル（Matrix/IRC/WeCom/Discord Proxy）、3 つの新プロバイダー（Kimi/Minimax/Avian）、ビジョンパイプライン、JSONL メモリストア、モデルルーティング。
+2026-03-09 🎉 **v0.2.1 — 史上最大のアップデート！** MCP プロトコル対応、4 つの新 Channel（Matrix/IRC/WeCom/Discord Proxy）、3 つの新 Provider（Kimi/Minimax/Avian）、ビジョンパイプライン、JSONL メモリストア、モデルルーティング。
-2026-02-28 📦 **v0.2.0** リリース — Docker Compose 対応と Web UI ランチャー。
+2026-02-28 📦 **v0.2.0** リリース — Docker Compose 対応と Web UI Launcher。
-2026-02-26 🎉 PicoClaw がわずか 17 日で **20K スター** 達成！チャネル自動オーケストレーションとケイパビリティインターフェースが実装されました。
+2026-02-26 🎉 PicoClaw がわずか 17 日で **20K スター** 達成！Channel 自動オーケストレーションとケイパビリティインターフェースが実装されました。
過去のニュース...
@@ -72,80 +71,71 @@
2026-02-13 🎉 PicoClaw が 4 日間で 5000 スター達成！プロジェクトロードマップと開発者グループの準備が進行中。
-2026-02-09 🎉 **PicoClaw リリース！** $10 ハードウェアで 10MB 未満の RAM で動く AI エージェントを 1 日で構築。🦐 行くぜ、シャコ！
+2026-02-09 🎉 **PicoClaw リリース！** $10 ハードウェアで 10MB 未満の RAM で動く AI Agent を 1 日で構築。Let's Go, PicoClaw!
## ✨ 特徴
-🪶 **超軽量**: メモリフットプリント 10MB 未満 — OpenClaw のコア機能より 99% 小さい。*
+🪶 **超軽量**: コアメモリフットプリント 10MB 未満 — OpenClaw より 99% 小さい。*
💰 **最小コスト**: $10 ハードウェアで動作 — Mac mini より 98% 安い。
-⚡️ **超高速**: 起動時間 400 倍高速、0.6GHz シングルコアでも 1 秒未満で起動。
+⚡️ **超高速起動**: 起動時間 400 倍高速。0.6GHz シングルコアでも 1 秒未満で起動。
-🌍 **真のポータビリティ**: RISC-V、ARM、MIPS、x86 対応の単一バイナリ。ワンクリックで Go！
+🌍 **真のポータビリティ**: RISC-V、ARM、MIPS、x86 対応の単一バイナリ。どこでも動く！
-🤖 **AI ブートストラップ**: 自律的な Go ネイティブ実装 — コアの 95% が AI 生成、人間によるレビュー付き。
+🤖 **AI ブートストラップ**: 純粋な Go ネイティブ実装 — コアコードの 95% が Agent によって生成され、人間によるレビューで調整。
-🔌 **MCP 対応**: ネイティブ [Model Context Protocol](https://modelcontextprotocol.io/) 統合 — 任意の MCP サーバーに接続してエージェント機能を拡張。
+🔌 **MCP 対応**: ネイティブ [Model Context Protocol](https://modelcontextprotocol.io/) 統合 — 任意の MCP サーバーに接続して Agent 機能を拡張。
-👁️ **ビジョンパイプライン**: 画像やファイルをエージェントに直接送信 — マルチモーダル LLM 向けの自動 base64 エンコーディング。
+👁️ **ビジョンパイプライン**: 画像やファイルを Agent に直接送信 — マルチモーダル LLM 向けの自動 base64 エンコーディング。
🧠 **スマートルーティング**: ルールベースのモデルルーティング — 簡単なクエリは軽量モデルへ、API コストを節約。
-_*最近のバージョンでは急速な機能マージにより 10〜20MB になる場合があります。リソース最適化は計画中です。起動時間の比較は 0.8GHz シングルコアベンチマークに基づいています（下表参照）。_
+_*最近のバージョンでは急速な PR マージにより 10〜20MB になる場合があります。リソース最適化は計画中です。起動時間の比較は 0.8GHz シングルコアベンチマークに基づいています（下表参照）。_
-| | OpenClaw | NanoBot | **PicoClaw** |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **言語** | TypeScript | Python | **Go** |
-| **RAM** | >1GB | >100MB | **< 10MB*** |
-| **起動時間**(0.8GHz コア) | >500秒 | >30秒 | **<1秒** |
-| **コスト** | Mac Mini $599 | 大半の Linux SBC ~$50 | **あらゆる Linux ボード****最安 $10** |
+
+
+| | OpenClaw | NanoBot | **PicoClaw** |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **言語** | TypeScript | Python | **Go** |
+| **RAM** | >1GB | >100MB | **< 10MB*** |
+| **起動時間**(0.8GHz コア) | >500秒 | >30秒 | **<1秒** |
+| **コスト** | Mac Mini $599 | 大半の Linux ボード ~$50 | **あらゆる Linux ボード****最安 $10** |
+
+
+
## 🦾 デモンストレーション
### 🛠️ スタンダードアシスタントワークフロー
-
- 🧩 フルスタックエンジニア
🗂️ ログ＆計画管理
🔎 Web 検索＆学習
-
-
-
- 開発 · デプロイ · スケール
- スケジュール · 自動化 · メモリ
- 発見 · インサイト · トレンド
-
+
+フルスタックエンジニアモード
ログ＆計画管理
Web 検索＆学習
+
+
+
+開発 · デプロイ · スケール
+スケジュール · 自動化 · メモリ
+発見 · インサイト · トレンド
+
-### 📱 古い Android スマホで動かす
-
-10 年前のスマホに第二の人生を！PicoClaw でスマート AI アシスタントに変身させましょう。クイックスタート：
-
-1. **[Termux](https://github.com/termux/termux-app) をインストール**（[GitHub Releases](https://github.com/termux/termux-app/releases) からダウンロード、または F-Droid / Google Play で検索）。
-2. **コマンドを実行**
-
-```bash
-# https://github.com/sipeed/picoclaw/releases から最新リリースをダウンロード
-wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
-tar xzf picoclaw_Linux_arm64.tar.gz
-pkg install proot
-termux-chroot ./picoclaw onboard
-```
-
-その後「クイックスタート」セクションの手順に従って設定を完了してください！
-
-
+
+
+**始め方:**
+
+WebUI を開いたら：**1)** Provider を設定（LLM API キーを追加）→ **2)** Channel を設定（例：Telegram）→ **3)** Gateway を起動 → **4)** チャット！
+
+WebUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。
+
+
+Docker（代替手段）
+
+### 💻 TUI Launcher（ヘッドレス / SSH 向け推奨）
+
+TUI（Terminal UI）Launcher は設定と管理のためのフル機能ターミナルインターフェースを提供します。サーバー、Raspberry Pi、その他のヘッドレス環境に最適です。
+
+```bash
+picoclaw-launcher-tui
+```
+
+
+
+
+**始め方:**
+
+TUI メニューを使って：**1)** Provider を設定 → **2)** Channel を設定 → **3)** Gateway を起動 → **4)** チャット！
+
+TUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。
+
+### 📱 Android
+
+10 年前のスマホに第二の人生を！PicoClaw でスマート AI アシスタントに変身させましょう。
+
+**オプション 1: Termux（現在利用可能）**
+
+1. [Termux](https://github.com/termux/termux-app) をインストール（[GitHub Releases](https://github.com/termux/termux-app/releases) からダウンロード、または F-Droid / Google Play で検索）
+2. 以下のコマンドを実行：
+
+```bash
+# 最新リリースをダウンロード
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard # chroot で標準的な Linux ファイルシステムレイアウトを提供
+```
+
+その後、下記の Terminal Launcher セクションの手順に従って設定を完了してください。
+
+
+Terminal Launcher（リソース制約環境向け）
+
+## 🔌 Provider（LLM）
+
+PicoClaw は `model_list` 設定を通じて 30 以上の LLM Provider をサポートしています。`protocol/model` 形式を使用してください：
+
+| Provider | Protocol | API キー | 備考 |
+|----------|----------|---------|------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | 必須 | GPT-5.4、GPT-4o、o3 など |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | 必須 | Claude Opus 4.6、Sonnet 4.6 など |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | 必須 | Gemini 3 Flash、2.5 Pro など |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | 必須 | 200 以上のモデル、統合 API |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | 必須 | GLM-4.7、GLM-5 など |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | 必須 | DeepSeek-V3、DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | 必須 | Doubao、Ark モデル |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | 必須 | Qwen3、Qwen-Max など |
+| [Groq](https://console.groq.com/keys) | `groq/` | 必須 | 高速推論（Llama、Mixtral） |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | 必須 | Kimi モデル |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | 必須 | MiniMax モデル |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | 必須 | Mistral Large、Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | 必須 | NVIDIA ホスティングモデル |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | 必須 | 高速推論 |
+| [Novita AI](https://novita.ai/) | `novita/` | 必須 | 各種オープンモデル |
+| [Ollama](https://ollama.com/) | `ollama/` | 不要 | ローカルモデル、セルフホスト |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | 不要 | ローカルデプロイ、OpenAI 互換 |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | 場合による | 100 以上の Provider のプロキシ |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | 必須 | エンタープライズ Azure デプロイ |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | デバイスコードログイン |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+
+ローカルデプロイ（Ollama、vLLM など）
+
+## 💬 Channel（チャットアプリ）
+
+17 以上のメッセージングプラットフォームで PicoClaw と会話できます：
+
+| Channel | セットアップ | Protocol | ドキュメント |
+|---------|------------|----------|------------|
+| **Telegram** | 簡単（bot トークン） | Long polling | [ガイド](docs/channels/telegram/README.ja.md) |
+| **Discord** | 簡単（bot トークン + intents） | WebSocket | [ガイド](docs/channels/discord/README.ja.md) |
+| **WhatsApp** | 簡単（QR スキャンまたは bridge URL） | Native / Bridge | [ガイド](docs/ja/chat-apps.md#whatsapp) |
+| **微信 (Weixin)** | 簡単（QR スキャン） | iLink API | [ガイド](docs/ja/chat-apps.md#weixin) |
+| **QQ** | 簡単（AppID + AppSecret） | WebSocket | [ガイド](docs/channels/qq/README.ja.md) |
+| **Slack** | 簡単（bot + app トークン） | Socket Mode | [ガイド](docs/channels/slack/README.ja.md) |
+| **Matrix** | 中級（homeserver + トークン） | Sync API | [ガイド](docs/channels/matrix/README.ja.md) |
+| **DingTalk** | 中級（クライアント認証情報） | Stream | [ガイド](docs/channels/dingtalk/README.ja.md) |
+| **Feishu / Lark** | 中級（App ID + Secret） | WebSocket/SDK | [ガイド](docs/channels/feishu/README.ja.md) |
+| **LINE** | 中級（認証情報 + webhook） | Webhook | [ガイド](docs/channels/line/README.ja.md) |
+| **WeCom Bot** | 中級（webhook URL） | Webhook | [ガイド](docs/channels/wecom/wecom_bot/README.ja.md) |
+| **WeCom App** | 中級（corp 認証情報） | Webhook | [ガイド](docs/channels/wecom/wecom_app/README.ja.md) |
+| **WeCom AI Bot** | 中級（トークン + AES キー） | WebSocket / Webhook | [ガイド](docs/channels/wecom/wecom_aibot/README.ja.md) |
+| **IRC** | 中級（サーバー + nick） | IRC protocol | [ガイド](docs/ja/chat-apps.md#irc) |
+| **OneBot** | 中級（WebSocket URL） | OneBot v11 | [ガイド](docs/channels/onebot/README.ja.md) |
+| **MaixCam** | 簡単（有効化） | TCP socket | [ガイド](docs/channels/maixcam/README.ja.md) |
+| **Pico** | 簡単（有効化） | Native protocol | 内蔵 |
+| **Pico Client** | 簡単（WebSocket URL） | WebSocket | 内蔵 |
+
+> webhook ベースのすべての Channel は単一の Gateway HTTP サーバー（`gateway.host`:`gateway.port`、デフォルト `127.0.0.1:18790`）を共有します。Feishu は WebSocket/SDK モードを使用し、共有 HTTP サーバーを使用しません。
+
+Channel の詳細なセットアップ手順は [チャットアプリ設定](docs/ja/chat-apps.md) を参照してください。
+
+## 🔧 ツール
+
+### 🔍 Web 検索
+
+PicoClaw は最新情報を提供するために Web を検索できます。`tools.web` で設定してください：
+
+| 検索エンジン | API キー | 無料枠 | リンク |
+|------------|---------|--------|-------|
+| DuckDuckGo | 不要 | 無制限 | 内蔵フォールバック |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | 必須 | 1000 クエリ/日 | AI 搭載、中国語に最適化 |
+| [Tavily](https://tavily.com) | 必須 | 1000 クエリ/月 | AI Agent 向けに最適化 |
+| [Brave Search](https://brave.com/search/api) | 必須 | 2000 クエリ/月 | 高速でプライベート |
+| [Perplexity](https://www.perplexity.ai) | 必須 | 有料 | AI 搭載検索 |
+| [SearXNG](https://github.com/searxng/searxng) | 不要 | セルフホスト | 無料メタ検索エンジン |
+| [GLM Search](https://open.bigmodel.cn/) | 必須 | 場合による | Zhipu Web 検索 |
+
+### ⚙️ その他のツール
+
+PicoClaw にはファイル操作、コード実行、スケジューリングなどの組み込みツールが含まれています。詳細は [ツール設定](docs/ja/tools_configuration.md) を参照してください。
+
+## 🎯 Skill
+
+Skill は Agent を拡張するモジュール型の機能です。ワークスペース内の `SKILL.md` ファイルから読み込まれます。
+
+**ClawHub から Skill をインストール：**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install
+```
+
+**ClawHub トークンを設定**（オプション、レート制限を上げるため）：
+
+`config.json` に追加：
+```json
+{
+ "tools": {
+ "skills": {
+ "registries": {
+ "clawhub": {
+ "auth_token": "your-clawhub-token"
+ }
+ }
+ }
+ }
+}
+```
+
+詳細は [ツール設定 - Skill](docs/ja/tools_configuration.md#skills-tool) を参照してください。
+
+## 🔗 MCP（Model Context Protocol）
+
+PicoClaw は [MCP](https://modelcontextprotocol.io/) をネイティブサポートしています — 任意の MCP サーバーに接続して、外部ツールやデータソースで Agent の機能を拡張できます。
+
+```json
+{
+ "tools": {
+ "mcp": {
+ "enabled": true,
+ "servers": {
+ "filesystem": {
+ "enabled": true,
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+ }
+ }
+ }
+ }
+}
+```
+
+MCP の完全な設定（stdio、SSE、HTTP トランスポート、Tool Discovery）は [ツール設定 - MCP](docs/ja/tools_configuration.md#mcp-tool) を参照してください。
##
+Discord:
-
-
+
-
PicoClaw: Ultra-Efficient AI Assistant in Go
+
PicoClaw: Ultra-Efficient AI Assistant in Go
-
$10 Hardware · <10MB RAM · <1s Boot · 皮皮虾，我们走！
+
$10 Hardware · 10MB RAM · ms Boot · Let's Go, PicoClaw!
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
> [!CAUTION]
-> **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明**
->
-> * **NO CRYPTO:** PicoClaw has **NO** official token/coin. All claims on `pump.fun` or other trading platforms are **SCAMS**.
+> **Security Notice**
>
+> * **NO CRYPTO:** PicoClaw has **not** issued any official tokens or cryptocurrency. All claims on `pump.fun` or other trading platforms are **scams**.
> * **OFFICIAL DOMAIN:** The **ONLY** official website is **[picoclaw.io](https://picoclaw.io)**, and company website is **[sipeed.com](https://sipeed.com)**
-> * **Warning:** Many `.ai/.org/.com/.net/...` domains are registered by third parties.
-> * **Warning:** picoclaw is in early development now and may have unresolved network security issues. Do not deploy to production environments before the v1.0 release.
-> * **Note:** picoclaw has recently merged a lot of PRs, which may result in a larger memory footprint (10–20MB) in the latest versions. We plan to prioritize resource optimization as soon as the current feature set reaches a stable state.
+> * **BEWARE:** Many `.ai/.org/.com/.net/...` domains have been registered by third parties. Do not trust them.
+> * **NOTE:** PicoClaw is in early rapid development. There may be unresolved security issues. Do not deploy to production before v1.0.
+> * **NOTE:** PicoClaw has recently merged many PRs. Recent builds may use 10-20MB RAM. Resource optimization is planned after feature stabilization.
## 📢 News
-2026-03-17 🚀 **v0.2.3 Released!** System tray UI (Windows & Linux), sub-agent status tracking (`spawn_status`), experimental gateway hot-reload, cron security gates, and 2 security fixes. PicoClaw now at **25K ⭐**!
+2026-03-17 🚀 **v0.2.3 Released!** System tray UI (Windows & Linux), sub-agent status query (`spawn_status`), experimental Gateway hot-reload, Cron security gating, and 2 security fixes. PicoClaw has reached **25K Stars**!
-2026-03-09 🎉 **v0.2.1 — Biggest update yet!** MCP protocol support, 4 new channels (Matrix/IRC/WeCom/Discord Proxy), 3 new providers (Kimi/Minimax/Avian), vision pipeline, JSONL memory store, and model routing.
+2026-03-09 🎉 **v0.2.1 — Biggest update yet!** MCP protocol support, 4 new channels (Matrix/IRC/WeCom/Discord Proxy), 3 new providers (Kimi/Minimax/Avian), vision pipeline, JSONL memory store, model routing.
-2026-02-28 📦 **v0.2.0** released with Docker Compose support and Web UI launcher.
+2026-02-28 📦 **v0.2.0** released with Docker Compose and Web UI Launcher support.
-2026-02-26 🎉 PicoClaw hit **20K stars** in just 17 days! Channel auto-orchestration and capability interfaces landed.
+2026-02-26 🎉 PicoClaw hits **20K Stars** in just 17 days! Channel auto-orchestration and capability interfaces are live.
-Older news...
+Earlier news...
-2026-02-16 🎉 PicoClaw hit 12K stars in one week! Community maintainer roles and [roadmap](ROADMAP.md) officially posted.
+2026-02-16 🎉 PicoClaw breaks 12K Stars in one week! Community maintainer roles and [Roadmap](ROADMAP.md) officially launched.
-2026-02-13 🎉 PicoClaw hit 5000 stars in 4 days! Project Roadmap and Developer Group setup underway.
+2026-02-13 🎉 PicoClaw breaks 5000 Stars in 4 days! Project roadmap and developer groups in progress.
-2026-02-09 🎉 **PicoClaw Launched!** Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw，Let's Go！
+2026-02-09 🎉 **PicoClaw Released!** Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. Let's Go, PicoClaw!
## ✨ Features
-🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than OpenClaw core functionality.*
+🪶 **Ultra-lightweight**: Core memory footprint <10MB — 99% smaller than OpenClaw.*
-💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini.
+💰 **Minimal cost**: Efficient enough to run on $10 hardware — 98% cheaper than a Mac mini.
-⚡️ **Lightning Fast**: 400X Faster startup time, boot in <1 second even on 0.6GHz single core.
+⚡️ **Lightning-fast boot**: 400x faster startup. Boots in <1s even on a 0.6GHz single-core processor.
-🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, MIPS, and x86, One-click to Go!
+🌍 **Truly portable**: Single binary across RISC-V, ARM, MIPS, and x86 architectures. One binary, runs everywhere!
-🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement.
+🤖 **AI-bootstrapped**: Pure Go native implementation — 95% of core code was generated by an Agent and fine-tuned through human-in-the-loop review.
-🔌 **MCP Support**: Native [Model Context Protocol](https://modelcontextprotocol.io/) integration — connect any MCP server to extend agent capabilities.
+🔌 **MCP support**: Native [Model Context Protocol](https://modelcontextprotocol.io/) integration — connect any MCP server to extend Agent capabilities.
-👁️ **Vision Pipeline**: Send images and files directly to the agent — automatic base64 encoding for multimodal LLMs.
+👁️ **Vision pipeline**: Send images and files directly to the Agent — automatic base64 encoding for multimodal LLMs.
-🧠 **Smart Routing**: Rule-based model routing — simple queries go to lightweight models, saving API costs.
+🧠 **Smart routing**: Rule-based model routing — simple queries go to lightweight models, saving API costs.
-_*Recent versions may use 10–20MB due to rapid feature merges. Resource optimization is planned. Startup comparison based on 0.8GHz single-core benchmarks (see table below)._
+_*Recent builds may use 10-20MB due to rapid PR merges. Resource optimization is planned. Boot speed comparison based on 0.8GHz single-core benchmarks (see table below)._
-| | OpenClaw | NanoBot | **PicoClaw** |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Language** | TypeScript | Python | **Go** |
-| **RAM** | >1GB | >100MB | **< 10MB*** |
-| **Startup**(0.8GHz core) | >500s | >30s | **<1s** |
-| **Cost** | Mac Mini $599 | Most Linux SBC ~$50 | **Any Linux Board****As low as $10** |
+
+
+| | OpenClaw | NanoBot | **PicoClaw** |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Language** | TypeScript | Python | **Go** |
+| **RAM** | >1GB | >100MB | **< 10MB*** |
+| **Boot time**(0.8GHz core) | >500s | >30s | **<1s** |
+| **Cost** | Mac Mini $599 | Most Linux boards ~$50 | **Any Linux board****from $10** |
+
+
+> **[Hardware Compatibility List](docs/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR!
+
+
+
+
## 🦾 Demonstration
### 🛠️ Standard Assistant Workflows
-
- 🧩 Full-Stack Engineer
🗂️ Logging & Planning Management
🔎 Web Search & Learning
-
-
-
- Develop • Deploy • Scale
- Schedule • Automate • Memory
- Discovery • Insights • Trends
-
+
+Full-Stack Engineer Mode
Logging & Planning
Web Search & Learning
+
+
+
+Develop · Deploy · Scale
+Schedule · Automate · Remember
+Discover · Insights · Trends
+
-### 📱 Run on old Android Phones
+### 🐜 Innovative Low-Footprint Deployment
-Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw. Quick Start:
+PicoClaw can be deployed on virtually any Linux device!
-1. **Install [Termux](https://github.com/termux/termux-app)** (Download from [GitHub Releases](https://github.com/termux/termux-app/releases), or search in F-Droid / Google Play).
-2. **Execute cmds**
-
-```bash
-# Download the latest release from https://github.com/sipeed/picoclaw/releases
-wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
-tar xzf picoclaw_Linux_arm64.tar.gz
-pkg install proot
-termux-chroot ./picoclaw onboard
-```
-
-And then follow the instructions in the "Quick Start" section to complete the configuration!
-
-
-
-### 🐜 Innovative Low-Footprint Deploy
-
-PicoClaw can be deployed on almost any Linux device!
-
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) for Automated Server Maintenance
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) for Smart Monitoring
+- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) edition, for a minimal home assistant
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), for automated server operations
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), for smart surveillance
-🌟 More Deployment Cases Await！
+🌟 More Deployment Cases Await!
## 📦 Install
-### Install with precompiled binary
+### Download from picoclaw.io (Recommended)
-Download the binary for your platform from the [Releases](https://github.com/sipeed/picoclaw/releases) page.
+Visit **[picoclaw.io](https://picoclaw.io)** — the official website auto-detects your platform and provides one-click download. No need to manually pick an architecture.
-### Install from source (latest features, recommended for development)
+### Download precompiled binary
+
+Alternatively, download the binary for your platform from the [GitHub Releases](https://github.com/sipeed/picoclaw/releases) page.
+
+### Build from source (for development)
```bash
git clone https://github.com/sipeed/picoclaw.git
@@ -172,24 +166,59 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
-# Build, no need to install
+# Build core binary
make build
+# Build Web UI Launcher (required for WebUI mode)
+make build-launcher
+
# 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
+# 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`; 64-bit → `make build-linux-arm64`. Or run `make build-pi-zero` to build both.
+**Raspberry Pi Zero 2 W:** Use the binary that matches your OS: 32-bit Raspberry Pi OS -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Or run `make build-pi-zero` to build both.
-## 📚 Documentation
+## 🚀 Quick Start Guide
-For detailed guides, see the docs below. The README covers quick start only.
+### 🌐 WebUI Launcher (Recommended for Desktop)
+
+The WebUI Launcher provides a browser-based interface for configuration and chat. This is the easiest way to get started — no command-line knowledge required.
+
+**Option 1: Double-click (Desktop)**
+
+After downloading from [picoclaw.io](https://picoclaw.io), double-click `picoclaw-launcher` (or `picoclaw-launcher.exe` on Windows). Your browser will open automatically at `http://localhost:18800`.
+
+**Option 2: Command line**
+
+```bash
+picoclaw-launcher
+# Open http://localhost:18800 in your browser
+```
+
+> [!TIP]
+> **Remote access / Docker / VM:** Add the `-public` flag to listen on all interfaces:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+
+
+
+**Getting started:**
+
+Open the WebUI, then: **1)** Configure a Provider (add your LLM API key) -> **2)** Configure a Channel (e.g., Telegram) -> **3)** Start the Gateway -> **4)** Chat!
+
+For detailed WebUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io).
+
+
+Docker (alternative)
-> [!WARNING]
-> The web console does not yet support authentication. Avoid exposing it to the public internet.
+### 💻 TUI Launcher (Recommended for Headless / SSH)
-### Agent Mode (One-shot)
+The TUI (Terminal UI) Launcher provides a full-featured terminal interface for configuration and management. Ideal for servers, Raspberry Pi, and other headless environments.
```bash
-# Ask a question
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
-
-# Interactive mode
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+picoclaw-launcher-tui
```
-### Update
+
+
+
+**Getting started:**
+
+Use the TUI menus to: **1)** Configure a Provider -> **2)** Configure a Channel -> **3)** Start the Gateway -> **4)** Chat!
+
+For detailed TUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw.
+
+**Option 1: Termux (available now)**
+
+1. Install [Termux](https://github.com/termux/termux-app) (download from [GitHub Releases](https://github.com/termux/termux-app/releases), or search in F-Droid / Google Play)
+2. Run the following commands:
```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+# Download the latest release
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard # chroot provides a standard Linux filesystem layout
```
-### 🚀 Quick Start
+Then follow the Terminal Launcher section below to complete configuration.
-> [!TIP]
-> Set your API Key in `~/.picoclaw/config.json`. Get API Keys: [Volcengine (CodingPlan)](https://console.volcengine.com) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Web search is optional — get a free [Tavily API](https://tavily.com) (1000 free queries/month) or [Brave Search API](https://brave.com/search/api) (2000 free queries/month).
+
+Terminal Launcher (for resource-constrained environments)
+
+## 🔌 Providers (LLM)
+
+PicoClaw supports 30+ LLM providers through the `model_list` configuration. Use the `protocol/model` format:
+
+| Provider | Protocol | API Key | Notes |
+|----------|----------|---------|-------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Required | GPT-5.4, GPT-4o, o3, etc. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Required | Claude Opus 4.6, Sonnet 4.6, etc. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Required | Gemini 3 Flash, 2.5 Pro, etc. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Required | 200+ models, unified API |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Required | GLM-4.7, GLM-5, etc. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Required | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Required | Doubao, Ark models |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Required | Qwen3, Qwen-Max, etc. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Required | Fast inference (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Required | Kimi models |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Required | MiniMax models |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Required | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Required | NVIDIA hosted models |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Required | Fast inference |
+| [Novita AI](https://novita.ai/) | `novita/` | Required | Various open models |
+| [Ollama](https://ollama.com/) | `ollama/` | Not needed | Local models, self-hosted |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Not needed | Local deployment, OpenAI-compatible |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Varies | Proxy for 100+ providers |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Required | Enterprise Azure deployment |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Device code login |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+
+Local deployment (Ollama, vLLM, etc.)
+
+## 💬 Channels (Chat Apps)
+
+Talk to your PicoClaw through 17+ messaging platforms:
+
+| Channel | Setup | Protocol | Docs |
+|---------|-------|----------|------|
+| **Telegram** | Easy (bot token) | Long polling | [Guide](docs/channels/telegram/README.md) |
+| **Discord** | Easy (bot token + intents) | WebSocket | [Guide](docs/channels/discord/README.md) |
+| **WhatsApp** | Easy (QR scan or bridge URL) | Native / Bridge | [Guide](docs/chat-apps.md#whatsapp) |
+| **Weixin** | Easy (Native QR scan) | iLink API | [Guide](docs/chat-apps.md#weixin) |
+| **QQ** | Easy (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.md) |
+| **Slack** | Easy (bot + app token) | Socket Mode | [Guide](docs/channels/slack/README.md) |
+| **Matrix** | Medium (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.md) |
+| **DingTalk** | Medium (client credentials) | Stream | [Guide](docs/channels/dingtalk/README.md) |
+| **Feishu / Lark** | Medium (App ID + Secret) | WebSocket/SDK | [Guide](docs/channels/feishu/README.md) |
+| **LINE** | Medium (credentials + webhook) | Webhook | [Guide](docs/channels/line/README.md) |
+| **WeCom Bot** | Medium (webhook URL) | Webhook | [Guide](docs/channels/wecom/wecom_bot/README.md) |
+| **WeCom App** | Medium (corp credentials) | Webhook | [Guide](docs/channels/wecom/wecom_app/README.md) |
+| **WeCom AI Bot** | Medium (token + AES key) | WebSocket / Webhook | [Guide](docs/channels/wecom/wecom_aibot/README.md) |
+| **IRC** | Medium (server + nick) | IRC protocol | [Guide](docs/chat-apps.md#irc) |
+| **OneBot** | Medium (WebSocket URL) | OneBot v11 | [Guide](docs/channels/onebot/README.md) |
+| **MaixCam** | Easy (enable) | TCP socket | [Guide](docs/channels/maixcam/README.md) |
+| **Pico** | Easy (enable) | Native protocol | Built-in |
+| **Pico Client** | Easy (WebSocket URL) | WebSocket | Built-in |
+
+> All webhook-based channels share a single Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu uses WebSocket/SDK mode and does not use the shared HTTP server.
+
+For detailed channel setup instructions, see [Chat Apps Configuration](docs/chat-apps.md).
+
+## 🔧 Tools
+
+### 🔍 Web Search
+
+PicoClaw can search the web to provide up-to-date information. Configure in `tools.web`:
+
+| Search Engine | API Key | Free Tier | Link |
+|--------------|---------|-----------|------|
+| DuckDuckGo | Not needed | Unlimited | Built-in fallback |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Required | 1000 queries/day | AI-powered, China-optimized |
+| [Tavily](https://tavily.com) | Required | 1000 queries/month | Optimized for AI Agents |
+| [Brave Search](https://brave.com/search/api) | Required | 2000 queries/month | Fast and private |
+| [Perplexity](https://www.perplexity.ai) | Required | Paid | AI-powered search |
+| [SearXNG](https://github.com/searxng/searxng) | Not needed | Self-hosted | Free metasearch engine |
+| [GLM Search](https://open.bigmodel.cn/) | Required | Varies | Zhipu web search |
+
+### ⚙️ Other Tools
+
+PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See [Tools Configuration](docs/tools_configuration.md) for details.
+
+## 🎯 Skills
+
+Skills are modular capabilities that extend your Agent. They are loaded from `SKILL.md` files in your workspace.
+
+**Install skills from ClawHub:**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install
+```
+
+**Configure ClawHub token** (optional, for higher rate limits):
+
+Add to your `config.json`:
+```json
+{
"tools": {
- "web": {
- "brave": {
- "enabled": false,
- "api_key": "YOUR_BRAVE_API_KEY",
- "max_results": 5
- },
- "tavily": {
- "enabled": false,
- "api_key": "YOUR_TAVILY_API_KEY",
- "max_results": 5
- },
- "duckduckgo": {
- "enabled": true,
- "max_results": 5
- },
- "perplexity": {
- "enabled": false,
- "api_key": "YOUR_PERPLEXITY_API_KEY",
- "max_results": 5
- },
- "searxng": {
- "enabled": false,
- "base_url": "http://your-searxng-instance:8888",
- "max_results": 5
+ "skills": {
+ "registries": {
+ "clawhub": {
+ "auth_token": "your-clawhub-token"
+ }
}
}
}
}
```
-> **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).
+For more details, see [Tools Configuration - Skills](docs/tools_configuration.md#skills-tool).
-**3. Get API Keys**
+## 🔗 MCP (Model Context Protocol)
-* **LLM Provider**: [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)
-* **Web Search** (optional):
- * [Brave Search](https://brave.com/search/api) - Paid ($5/1000 queries, ~$5-6/month)
- * [Perplexity](https://www.perplexity.ai) - AI-powered search with chat interface
- * [SearXNG](https://github.com/searxng/searxng) - Self-hosted metasearch engine (free, no API key needed)
- * [Tavily](https://tavily.com) - Optimized for AI Agents (1000 requests/month)
- * DuckDuckGo - Built-in fallback (no API key required)
-
-> **Note**: See `config.example.json` for a complete configuration template.
-
-**4. Chat**
-
-```bash
-picoclaw agent -m "What is 2+2?"
-```
-
-That's it! You have a working AI assistant in 2 minutes.
-
----
-
-## 💬 Chat Apps
-
-Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, or WeCom
-
-> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.
-
-| Channel | Setup |
-| ------------ | ---------------------------------- |
-| **Telegram** | Easy (just a token) |
-| **Discord** | Easy (bot token + intents) |
-| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
-| **Matrix** | Medium (homeserver + bot access token) |
-| **QQ** | Easy (AppID + AppSecret) |
-| **DingTalk** | Medium (app credentials) |
-| **LINE** | Medium (credentials + webhook URL) |
-| **WeCom AI Bot** | Medium (Token + AES key) |
-
-
-Telegram (Recommended)
-
-
-Discord
-* Create an application → Bot → Add Bot
-* Copy the bot token
-
-**2. Enable intents**
-
-* In the Bot settings, enable **MESSAGE CONTENT INTENT**
-* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
-
-**3. Get your User ID**
-* Discord Settings → Advanced → enable **Developer Mode**
-* Right-click your avatar → **Copy User ID**
-
-**4. Configure**
-
-```json
-{
- "channels": {
- "discord": {
- "enabled": true,
- "token": "YOUR_BOT_TOKEN",
- "allow_from": ["YOUR_USER_ID"]
- }
- }
-}
-```
-
-**5. Invite the bot**
-
-* OAuth2 → URL Generator
-* Scopes: `bot`
-* Bot Permissions: `Send Messages`, `Read Message History`
-* Open the generated invite URL and add the bot to your server
-
-**Optional: Group trigger mode**
-
-By default the bot responds to all messages in a server channel. To restrict responses to @-mentions only, add:
-
-```json
-{
- "channels": {
- "discord": {
- "group_trigger": { "mention_only": true }
- }
- }
-}
-```
-
-You can also trigger by keyword prefixes (e.g. `!bot`):
-
-```json
-{
- "channels": {
- "discord": {
- "group_trigger": { "prefixes": ["!bot"] }
- }
- }
-}
-```
-
-**6. Run**
-
-```bash
-picoclaw gateway
-```
-
-
-
-
-WhatsApp (native via whatsmeow)
-
-
-QQ
-
-
-DingTalk
-
-
-Matrix
-
-
-LINE
-
-
-WeCom (企业微信)
+For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/tools_configuration.md#mcp-tool).
##
+Discord:
-
-
+
-
PicoClaw: Assistente de IA Ultra-Eficiente em Go
+
PicoClaw: Assistente de IA Ultra-Eficiente em Go
-
Hardware de $10 · <10MB de RAM · Boot em <1s · 皮皮虾，我们走！
+
Hardware de $10 · 10MB de RAM · Boot em ms · Let's Go, PicoClaw!
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
> [!CAUTION]
-> **🚨 DECLARAÇÃO DE SEGURANÇA & CANAIS OFICIAIS**
+> **Aviso de Segurança**
>
-> * **SEM CRIPTOMOEDAS:** O PicoClaw **NÃO** possui nenhum token/moeda oficial. Todas as alegações no `pump.fun` ou outras plataformas de negociação são **GOLPES**.
->
-> * **DOMÍNIO OFICIAL:** O **ÚNICO** site oficial é o **[picoclaw.io](https://picoclaw.io)**, e o site da empresa é o **[sipeed.com](https://sipeed.com)**
-> * **Aviso:** Muitos domínios `.ai/.org/.com/.net/...` foram registrados por terceiros.
-> * **Aviso:** O PicoClaw está em fase inicial de desenvolvimento e pode ter problemas de segurança de rede não resolvidos. Não implante em ambientes de produção antes da versão v1.0.
-> * **Nota:** O PicoClaw recentemente fez merge de muitos PRs, o que pode resultar em maior consumo de memória (10–20MB) nas versões mais recentes. Planejamos priorizar a otimização de recursos assim que o conjunto de funcionalidades estiver estável.
+> * **SEM CRIPTO:** O PicoClaw **não** emitiu nenhum token oficial ou criptomoeda. Todas as alegações no `pump.fun` ou outras plataformas de negociação são **golpes**.
+> * **DOMÍNIO OFICIAL:** O **ÚNICO** site oficial é **[picoclaw.io](https://picoclaw.io)**, e o site da empresa é **[sipeed.com](https://sipeed.com)**
+> * **ATENÇÃO:** Muitos domínios `.ai/.org/.com/.net/...` foram registrados por terceiros. Não confie neles.
+> * **NOTA:** O PicoClaw está em desenvolvimento rápido inicial. Podem existir problemas de segurança não resolvidos. Não implante em produção antes da v1.0.
+> * **NOTA:** O PicoClaw mesclou muitos PRs recentemente. Builds recentes podem usar 10-20MB de RAM. A otimização de recursos está planejada após a estabilização de funcionalidades.
## 📢 Novidades
-2026-03-17 🚀 **v0.2.3 Lançado!** Interface de bandeja do sistema (Windows & Linux), rastreamento de status de sub-agentes (`spawn_status`), hot-reload experimental do gateway, portões de segurança para cron e 2 correções de segurança. PicoClaw agora com **25K ⭐**!
+2026-03-17 🚀 **v0.2.3 Lançada!** UI na bandeja do sistema (Windows e Linux), consulta de status de sub-agent (`spawn_status`), hot-reload experimental do Gateway, controle de segurança do Cron e 2 correções de segurança. O PicoClaw atingiu **25K Stars**!
-2026-03-09 🎉 **v0.2.1 — Maior atualização até agora!** Suporte ao protocolo MCP, 4 novos canais (Matrix/IRC/WeCom/Discord Proxy), 3 novos provedores (Kimi/Minimax/Avian), pipeline de visão, armazenamento de memória JSONL e roteamento de modelos.
+2026-03-09 🎉 **v0.2.1 — Maior atualização até agora!** Suporte ao protocolo MCP, 4 novos channels (Matrix/IRC/WeCom/Discord Proxy), 3 novos providers (Kimi/Minimax/Avian), pipeline de visão, armazenamento de memória JSONL, roteamento de modelos.
-2026-02-28 📦 **v0.2.0** lançado com suporte a Docker Compose e launcher Web UI.
+2026-02-28 📦 **v0.2.0** lançada com suporte a Docker Compose e Web UI Launcher.
-2026-02-26 🎉 PicoClaw atingiu **20K stars** em apenas 17 dias! Orquestração automática de canais e interfaces de capacidade implementadas.
+2026-02-26 🎉 O PicoClaw atinge **20K Stars** em apenas 17 dias! Orquestração automática de channels e interfaces de capacidade estão disponíveis.
-Novidades anteriores...
+Notícias anteriores...
-2026-02-16 🎉 PicoClaw atingiu 12K stars em uma semana! Papéis de maintainers da comunidade e [roadmap](ROADMAP.md) publicados oficialmente.
+2026-02-16 🎉 O PicoClaw ultrapassa 12K Stars em uma semana! Funções de mantenedor da comunidade e [Roadmap](ROADMAP.md) lançados oficialmente.
-2026-02-13 🎉 PicoClaw atingiu 5000 stars em 4 dias! Roadmap do Projeto e Grupo de Desenvolvedores em preparação.
+2026-02-13 🎉 O PicoClaw ultrapassa 5000 Stars em 4 dias! Roadmap do projeto e grupos de desenvolvedores em andamento.
-2026-02-09 🎉 **PicoClaw Lançado!** Construído em 1 dia para trazer Agentes de IA para hardware de $10 com <10MB de RAM. 🦐 PicoClaw, Partiu!
+2026-02-09 🎉 **PicoClaw Lançado!** Construído em 1 dia para levar AI Agents a hardware de $10 com menos de 10MB de RAM. Let's Go, PicoClaw!
## ✨ Funcionalidades
-🪶 **Ultra-Leve**: Consumo de memória <10MB — 99% menor que o OpenClaw para funcionalidades essenciais.*
+🪶 **Ultra-leve**: Footprint de memória do núcleo <10MB — 99% menor que o OpenClaw.*
-💰 **Custo Mínimo**: Eficiente o suficiente para rodar em hardware de $10 — 98% mais barato que um Mac mini.
+💰 **Custo mínimo**: Eficiente o suficiente para rodar em hardware de $10 — 98% mais barato que um Mac mini.
-⚡️ **Inicialização Relâmpago**: Tempo de inicialização 400X mais rápido, boot em <1 segundo mesmo em CPU single-core de 0.6GHz.
+⚡️ **Boot ultrarrápido**: Inicialização 400x mais rápida. Boot em menos de 1s mesmo em um processador single-core de 0,6GHz.
-🌍 **Portabilidade Real**: Um único binário auto-contido para RISC-V, ARM, MIPS e x86. Um clique e já era!
+🌍 **Verdadeiramente portátil**: Binário único para arquiteturas RISC-V, ARM, MIPS e x86. Um binário, roda em qualquer lugar!
-🤖 **Auto-Construído por IA**: Implementação nativa em Go de forma autônoma — 95% do núcleo gerado pelo Agente com refinamento humano no loop.
+🤖 **Bootstrapped por IA**: Implementação nativa pura em Go — 95% do código principal foi gerado por um Agent e refinado por revisão humana.
-🔌 **Suporte MCP**: Integração nativa com o [Model Context Protocol](https://modelcontextprotocol.io/) — conecte qualquer servidor MCP para estender as capacidades do agente.
+🔌 **Suporte a MCP**: Integração nativa com o [Model Context Protocol](https://modelcontextprotocol.io/) — conecte qualquer servidor MCP para estender as capacidades do Agent.
-👁️ **Pipeline de Visão**: Envie imagens e arquivos diretamente ao agente — codificação base64 automática para LLMs multimodais.
+👁️ **Pipeline de visão**: Envie imagens e arquivos diretamente ao Agent — codificação base64 automática para LLMs multimodais.
-🧠 **Roteamento Inteligente**: Roteamento de modelos baseado em regras — consultas simples vão para modelos leves, economizando custos de API.
+🧠 **Roteamento inteligente**: Roteamento de modelos baseado em regras — consultas simples vão para modelos leves, economizando custos de API.
-_*Versões recentes podem usar 10–20MB devido a merges rápidos de funcionalidades. Otimização de recursos está planejada. Comparação de inicialização baseada em benchmarks de single-core a 0.8GHz (veja tabela abaixo)._
+_*Builds recentes podem usar 10-20MB devido a merges rápidos de PRs. Otimização de recursos está planejada. Comparação de velocidade de boot baseada em benchmarks de single-core a 0,8GHz (veja tabela abaixo)._
-| | OpenClaw | NanoBot | **PicoClaw** |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Linguagem** | TypeScript | Python | **Go** |
-| **RAM** | >1GB | >100MB | **< 10MB*** |
-| **Inicialização**(CPU 0.8GHz) | >500s | >30s | **<1s** |
-| **Custo** | Mac Mini $599 | Maioria dos SBC Linux ~$50 | **Qualquer placa Linux****A partir de $10** |
+
+
+| | OpenClaw | NanoBot | **PicoClaw** |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Linguagem** | TypeScript | Python | **Go** |
+| **RAM** | >1GB | >100MB | **< 10MB*** |
+| **Tempo de boot**(core 0,8GHz) | >500s | >30s | **<1s** |
+| **Custo** | Mac Mini $599 | Maioria das placas Linux ~$50 | **Qualquer placa Linux****a partir de $10** |
+
+
+> **[Lista de Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md)** — Veja todas as placas testadas, de RISC-V de $5 ao Raspberry Pi e celulares Android. Sua placa não está listada? Envie um PR!
+
+
+
+
## 🦾 Demonstração
### 🛠️ Fluxos de Trabalho Padrão do Assistente
-
- 🧩 Engenharia Full-Stack
🗂️ Gerenciamento de Logs & Planejamento
🔎 Busca Web & Aprendizado
-
-
-
- Desenvolver • Implantar • Escalar
- Agendar • Automatizar • Memorizar
- Descobrir • Analisar • Tendências
-
+
+Modo Engenheiro Full-Stack
Registro e Planejamento
Busca na Web e Aprendizado
+
+
+
+Desenvolver · Implantar · Escalar
+Agendar · Automatizar · Lembrar
+Descobrir · Insights · Tendências
+
-### 📱 Rode em celulares Android antigos
-
-Dê uma segunda vida ao seu celular de dez anos atrás! Transforme-o em um assistente de IA inteligente com o PicoClaw. Início rápido:
-
-1. **Instale o [Termux](https://github.com/termux/termux-app)** (Baixe em [GitHub Releases](https://github.com/termux/termux-app/releases), ou busque no F-Droid / Google Play).
-2. **Execute os comandos**
-
-```bash
-# Baixe a versão mais recente em https://github.com/sipeed/picoclaw/releases
-wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
-tar xzf picoclaw_Linux_arm64.tar.gz
-pkg install proot
-termux-chroot ./picoclaw onboard
-```
-
-Depois siga as instruções na seção "Início Rápido" para completar a configuração!
-
-
-
-### 🐜 Implantação Inovadora com Baixo Consumo
+### 🐜 Implantação Inovadora de Baixo Consumo
O PicoClaw pode ser implantado em praticamente qualquer dispositivo Linux!
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versão E(Ethernet) ou W(WiFi6), para Assistente Doméstico Minimalista
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) para Manutenção Automatizada de Servidores
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) para Monitoramento Inteligente
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) edição E(Ethernet) ou W(WiFi6), para um assistente doméstico mínimo
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), para operações automatizadas de servidor
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), para vigilância inteligente
-🌟 Mais cenários de implantação aguardam você!
+🌟 Mais Casos de Implantação Aguardam!
## 📦 Instalação
-### Instalar com binário pré-compilado
+### Download pelo picoclaw.io (Recomendado)
-Baixe o binário para sua plataforma na página de [Releases](https://github.com/sipeed/picoclaw/releases).
+Acesse **[picoclaw.io](https://picoclaw.io)** — o site oficial detecta automaticamente sua plataforma e fornece download com um clique. Não é necessário selecionar a arquitetura manualmente.
-### Instalar a partir do código-fonte (funcionalidades mais recentes, recomendado para desenvolvimento)
+### Download do binário pré-compilado
+
+Alternativamente, baixe o binário para sua plataforma na página de [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Compilar a partir do código-fonte (para desenvolvimento)
```bash
git clone https://github.com/sipeed/picoclaw.git
@@ -172,78 +166,413 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
-# Build, sem necessidade de instalar
+# Compilar o binário principal
make build
-# Build para múltiplas plataformas
+# Compilar o Web UI Launcher (necessário para o modo WebUI)
+make build-launcher
+
+# Compilar para múltiplas plataformas
make build-all
-# Build para Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+# Compilar para Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
make build-pi-zero
-# Build e Instalar
+# Compilar e instalar
make install
```
-**Raspberry Pi Zero 2 W:** Use o binário correspondente ao seu SO: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Ou execute `make build-pi-zero` para compilar ambos.
+**Raspberry Pi Zero 2 W:** Use o binário que corresponde ao seu SO: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Ou execute `make build-pi-zero` para compilar ambos.
-## 📚 Documentação
+## 🚀 Guia de Início Rápido
-Para guias detalhados, consulte a documentação abaixo. Este README cobre apenas o início rápido.
+### 🌐 WebUI Launcher (Recomendado para Desktop)
-| Tópico | Descrição |
-|--------|-----------|
-| 🐳 [Docker & Início Rápido](docs/pt-br/docker.md) | Configuração Docker Compose, modos Launcher/Agent, configuração de Início Rápido |
-| 💬 [Apps de Chat](docs/pt-br/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom e mais |
-| ⚙️ [Configuração](docs/pt-br/configuration.md) | Variáveis de ambiente, estrutura do workspace, fontes de skills, sandbox de segurança, heartbeat |
-| 🔌 [Provedores & Modelos](docs/pt-br/providers.md) | 20+ provedores LLM, roteamento de modelos, configuração model_list, arquitetura de provedores |
-| 🔄 [Spawn & Tarefas Assíncronas](docs/pt-br/spawn-tasks.md) | Tarefas rápidas, tarefas longas com spawn, orquestração assíncrona de sub-agentes |
-| 🐛 [Solução de Problemas](docs/pt-br/troubleshooting.md) | Problemas comuns e soluções |
-| 🔧 [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) | Habilitar/desabilitar por ferramenta, políticas de execução |
+O WebUI Launcher fornece uma interface baseada em navegador para configuração e chat. Esta é a maneira mais fácil de começar — sem necessidade de conhecimento de linha de comando.
-##
+
+
+**Primeiros passos:**
+
+Abra o WebUI e então: **1)** Configure um Provider (adicione sua API key de LLM) -> **2)** Configure um Channel (ex.: Telegram) -> **3)** Inicie o Gateway -> **4)** Converse!
+
+Para documentação detalhada do WebUI, veja [docs.picoclaw.io](https://docs.picoclaw.io).
+
+
+Docker (alternativa)
+
+### 💻 TUI Launcher (Recomendado para Headless / SSH)
+
+O TUI (Terminal UI) Launcher fornece uma interface de terminal completa para configuração e gerenciamento. Ideal para servidores, Raspberry Pi e outros ambientes headless.
+
+```bash
+picoclaw-launcher-tui
+```
+
+
+
+
+**Primeiros passos:**
+
+Use os menus do TUI para: **1)** Configurar um Provider -> **2)** Configurar um Channel -> **3)** Iniciar o Gateway -> **4)** Conversar!
+
+Para documentação detalhada do TUI, veja [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Dê uma segunda vida ao seu celular de uma década! Transforme-o em um Assistente de IA inteligente com o PicoClaw.
+
+**Opção 1: Termux (disponível agora)**
+
+1. Instale o [Termux](https://github.com/termux/termux-app) (baixe nas [GitHub Releases](https://github.com/termux/termux-app/releases), ou pesquise no F-Droid / Google Play)
+2. Execute os seguintes comandos:
+
+```bash
+# Baixar a versão mais recente
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard # chroot fornece um layout padrão de sistema de arquivos Linux
+```
+
+Em seguida, siga a seção Terminal Launcher abaixo para concluir a configuração.
+
+
+Terminal Launcher (para ambientes com recursos limitados)
+
+## 🔌 Providers (LLM)
+
+O PicoClaw suporta mais de 30 providers de LLM através da configuração `model_list`. Use o formato `protocolo/modelo`:
+
+| Provider | Protocolo | API Key | Notas |
+|----------|-----------|---------|-------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Obrigatória | GPT-5.4, GPT-4o, o3, etc. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Obrigatória | Claude Opus 4.6, Sonnet 4.6, etc. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Obrigatória | Gemini 3 Flash, 2.5 Pro, etc. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Obrigatória | 200+ modelos, API unificada |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Obrigatória | GLM-4.7, GLM-5, etc. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Obrigatória | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Obrigatória | Modelos Doubao, Ark |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Obrigatória | Qwen3, Qwen-Max, etc. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Obrigatória | Inferência rápida (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Obrigatória | Modelos Kimi |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Obrigatória | Modelos MiniMax |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Obrigatória | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Obrigatória | Modelos hospedados pela NVIDIA |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Obrigatória | Inferência rápida |
+| [Novita AI](https://novita.ai/) | `novita/` | Obrigatória | Vários modelos abertos |
+| [Ollama](https://ollama.com/) | `ollama/` | Não necessária | Modelos locais, self-hosted |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Não necessária | Implantação local, compatível com OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Varia | Proxy para 100+ providers |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Obrigatória | Implantação Azure Enterprise |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login por código de dispositivo |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+
+Implantação local (Ollama, vLLM, etc.)
+
+## 💬 Channels (Apps de Chat)
+
+Converse com seu PicoClaw por meio de mais de 17 plataformas de mensagens:
+
+| Channel | Configuração | Protocolo | Docs |
+|---------|--------------|-----------|------|
+| **Telegram** | Fácil (bot token) | Long polling | [Guia](docs/channels/telegram/README.pt-br.md) |
+| **Discord** | Fácil (bot token + intents) | WebSocket | [Guia](docs/channels/discord/README.pt-br.md) |
+| **WhatsApp** | Fácil (QR scan ou bridge URL) | Nativo / Bridge | [Guia](docs/pt-br/chat-apps.md#whatsapp) |
+| **Weixin** | Fácil (scan QR nativo) | iLink API | [Guia](docs/pt-br/chat-apps.md#weixin) |
+| **QQ** | Fácil (AppID + AppSecret) | WebSocket | [Guia](docs/channels/qq/README.pt-br.md) |
+| **Slack** | Fácil (bot + app token) | Socket Mode | [Guia](docs/channels/slack/README.pt-br.md) |
+| **Matrix** | Médio (homeserver + token) | Sync API | [Guia](docs/channels/matrix/README.pt-br.md) |
+| **DingTalk** | Médio (credenciais do cliente) | Stream | [Guia](docs/channels/dingtalk/README.pt-br.md) |
+| **Feishu / Lark** | Médio (App ID + Secret) | WebSocket/SDK | [Guia](docs/channels/feishu/README.pt-br.md) |
+| **LINE** | Médio (credenciais + webhook) | Webhook | [Guia](docs/channels/line/README.pt-br.md) |
+| **WeCom Bot** | Médio (webhook URL) | Webhook | [Guia](docs/channels/wecom/wecom_bot/README.pt-br.md) |
+| **WeCom App** | Médio (credenciais corporativas) | Webhook | [Guia](docs/channels/wecom/wecom_app/README.pt-br.md) |
+| **WeCom AI Bot** | Médio (token + chave AES) | WebSocket / Webhook | [Guia](docs/channels/wecom/wecom_aibot/README.pt-br.md) |
+| **IRC** | Médio (servidor + nick) | Protocolo IRC | [Guia](docs/pt-br/chat-apps.md#irc) |
+| **OneBot** | Médio (WebSocket URL) | OneBot v11 | [Guia](docs/channels/onebot/README.pt-br.md) |
+| **MaixCam** | Fácil (habilitar) | TCP socket | [Guia](docs/channels/maixcam/README.pt-br.md) |
+| **Pico** | Fácil (habilitar) | Protocolo nativo | Integrado |
+| **Pico Client** | Fácil (WebSocket URL) | WebSocket | Integrado |
+
+> Todos os channels baseados em webhook compartilham um único servidor HTTP do Gateway (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`). O Feishu usa modo WebSocket/SDK e não utiliza o servidor HTTP compartilhado.
+
+Para instruções detalhadas de configuração de channels, veja [Configuração de Apps de Chat](docs/pt-br/chat-apps.md).
+
+## 🔧 Ferramentas
+
+### 🔍 Busca na Web
+
+O PicoClaw pode pesquisar na web para fornecer informações atualizadas. Configure em `tools.web`:
+
+| Motor de Busca | API Key | Nível Gratuito | Link |
+|----------------|---------|----------------|------|
+| DuckDuckGo | Não necessária | Ilimitado | Fallback integrado |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Obrigatória | 1000 consultas/dia | IA, otimizado para chinês |
+| [Tavily](https://tavily.com) | Obrigatória | 1000 consultas/mês | Otimizado para AI Agents |
+| [Brave Search](https://brave.com/search/api) | Obrigatória | 2000 consultas/mês | Rápido e privado |
+| [Perplexity](https://www.perplexity.ai) | Obrigatória | Pago | Busca com IA |
+| [SearXNG](https://github.com/searxng/searxng) | Não necessária | Self-hosted | Metabuscador gratuito |
+| [GLM Search](https://open.bigmodel.cn/) | Obrigatória | Varia | Busca web Zhipu |
+
+### ⚙️ Outras Ferramentas
+
+O PicoClaw inclui ferramentas integradas para operações de arquivo, execução de código, agendamento e mais. Veja [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) para detalhes.
+
+## 🎯 Skills
+
+Skills são capacidades modulares que estendem seu Agent. Elas são carregadas a partir de arquivos `SKILL.md` no seu workspace.
+
+**Instalar skills do ClawHub:**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install
+```
+
+**Configurar token do ClawHub** (opcional, para limites de taxa mais altos):
+
+Adicione ao seu `config.json`:
+```json
+{
+ "tools": {
+ "skills": {
+ "registries": {
+ "clawhub": {
+ "auth_token": "your-clawhub-token"
+ }
+ }
+ }
+ }
+}
+```
+
+Para mais detalhes, veja [Configuração de Ferramentas - Skills](docs/pt-br/tools_configuration.md#skills-tool).
+
+## 🔗 MCP (Model Context Protocol)
+
+O PicoClaw suporta nativamente o [MCP](https://modelcontextprotocol.io/) — conecte qualquer servidor MCP para estender as capacidades do seu Agent com ferramentas externas e fontes de dados.
+
+```json
+{
+ "tools": {
+ "mcp": {
+ "enabled": true,
+ "servers": {
+ "filesystem": {
+ "enabled": true,
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+ }
+ }
+ }
+ }
+}
+```
+
+Para configuração completa de MCP (transportes stdio, SSE, HTTP, Tool Discovery), veja [Configuração de Ferramentas - MCP](docs/pt-br/tools_configuration.md#mcp-tool).
+
+##
+Discord:
-
-
+
-
PicoClaw: Trợ lý AI Siêu Nhẹ viết bằng Go
+
PicoClaw: Trợ lý AI Siêu Nhẹ viết bằng Go
-
Phần cứng $10 · <10MB RAM · Khởi động <1 giây · Nào, xuất phát!
+
Phần cứng $10 · RAM 10MB · Khởi động ms · Let's Go, PicoClaw!
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
> [!CAUTION]
-> **🚨 TUYÊN BỐ BẢO MẬT & KÊNH CHÍNH THỨC**
+> **Thông báo Bảo mật**
>
-> * **KHÔNG CÓ CRYPTO:** PicoClaw **KHÔNG** có bất kỳ token/coin chính thức nào. Mọi thông tin trên `pump.fun` hoặc các sàn giao dịch khác đều là **LỪA ĐẢO**.
->
-> * **DOMAIN CHÍNH THỨC:** Website chính thức **DUY NHẤT** là **[picoclaw.io](https://picoclaw.io)**, website công ty là **[sipeed.com](https://sipeed.com)**
-> * **Cảnh báo:** Nhiều tên miền `.ai/.org/.com/.net/...` đã bị bên thứ ba đăng ký.
-> * **Cảnh báo:** PicoClaw đang trong giai đoạn phát triển sớm và có thể còn các vấn đề bảo mật mạng chưa được giải quyết. Không nên triển khai lên môi trường production trước phiên bản v1.0.
-> * **Lưu ý:** PicoClaw gần đây đã merge nhiều PR, dẫn đến bộ nhớ sử dụng có thể lớn hơn (10–20MB) ở các phiên bản mới nhất. Chúng tôi sẽ ưu tiên tối ưu tài nguyên khi bộ tính năng đã ổn định.
+> * **KHÔNG CÓ CRYPTO:** PicoClaw **chưa** phát hành bất kỳ token hay tiền điện tử chính thức nào. Mọi thông tin trên `pump.fun` hoặc các nền tảng giao dịch khác đều là **lừa đảo**.
+> * **DOMAIN CHÍNH THỨC:** Website chính thức **DUY NHẤT** là **[picoclaw.io](https://picoclaw.io)**, và website công ty là **[sipeed.com](https://sipeed.com)**
+> * **CẢNH BÁO:** Nhiều domain `.ai/.org/.com/.net/...` đã bị bên thứ ba đăng ký. Đừng tin tưởng chúng.
+> * **LƯU Ý:** PicoClaw đang trong giai đoạn phát triển nhanh. Có thể còn các vấn đề bảo mật chưa được giải quyết. Không triển khai lên môi trường production trước v1.0.
+> * **LƯU Ý:** PicoClaw gần đây đã merge nhiều PR. Các bản build gần đây có thể dùng 10-20MB RAM. Tối ưu hóa tài nguyên được lên kế hoạch sau khi tính năng ổn định.
## 📢 Tin tức
-2026-03-17 🚀 **v0.2.3 Phát hành!** Giao diện khay hệ thống (Windows & Linux), theo dõi trạng thái sub-agent (`spawn_status`), hot-reload gateway thử nghiệm, cổng bảo mật cron và 2 bản vá bảo mật. PicoClaw đạt **25K ⭐**!
+2026-03-17 🚀 **v0.2.3 đã phát hành!** Giao diện system tray (Windows & Linux), truy vấn trạng thái sub-agent (`spawn_status`), thử nghiệm Gateway hot-reload, bảo mật Cron, và 2 bản vá bảo mật. PicoClaw đã đạt **25K Stars**!
-2026-03-09 🎉 **v0.2.1 — Bản cập nhật lớn nhất!** Hỗ trợ giao thức MCP, 4 kênh mới (Matrix/IRC/WeCom/Discord Proxy), 3 nhà cung cấp mới (Kimi/Minimax/Avian), pipeline xử lý hình ảnh, bộ nhớ JSONL và định tuyến mô hình.
+2026-03-09 🎉 **v0.2.1 — Bản cập nhật lớn nhất từ trước đến nay!** Hỗ trợ giao thức MCP, 4 Channel mới (Matrix/IRC/WeCom/Discord Proxy), 3 Provider mới (Kimi/Minimax/Avian), pipeline thị giác, bộ nhớ JSONL, định tuyến mô hình.
-2026-02-28 📦 **v0.2.0** phát hành với hỗ trợ Docker Compose và launcher Web UI.
+2026-02-28 📦 **v0.2.0** phát hành với hỗ trợ Docker Compose và Web UI Launcher.
-2026-02-26 🎉 PicoClaw đạt **20K stars** chỉ trong 17 ngày! Tự động điều phối kênh và giao diện năng lực đã được triển khai.
+2026-02-26 🎉 PicoClaw đạt **20K Stars** chỉ trong 17 ngày! Tự động điều phối Channel và giao diện khả năng đã hoạt động.
-Tin tức cũ hơn...
+Tin tức trước đó...
-2026-02-16 🎉 PicoClaw đạt 12K stars chỉ trong một tuần! Vai trò maintainer cộng đồng và [roadmap](ROADMAP.md) đã được công bố chính thức.
+2026-02-16 🎉 PicoClaw vượt 12K Stars trong một tuần! Vai trò người duy trì cộng đồng và [Lộ trình](ROADMAP.md) chính thức ra mắt.
-2026-02-13 🎉 PicoClaw đạt 5000 stars trong 4 ngày! Lộ trình dự án và Nhóm phát triển đang được thiết lập.
+2026-02-13 🎉 PicoClaw vượt 5000 Stars trong 4 ngày! Lộ trình dự án và nhóm nhà phát triển đang được xây dựng.
-2026-02-09 🎉 **PicoClaw chính thức ra mắt!** Được xây dựng trong 1 ngày để mang AI Agent đến phần cứng $10 với RAM <10MB. 🦐 PicoClaw, Lên Đường!
+2026-02-09 🎉 **PicoClaw ra mắt!** Được xây dựng trong 1 ngày để đưa AI Agent lên phần cứng $10 với <10MB RAM. Let's Go, PicoClaw!
-## ✨ Tính năng nổi bật
+## ✨ Tính năng
-🪶 **Siêu nhẹ**: Bộ nhớ sử dụng <10MB — nhỏ hơn 99% so với OpenClaw (chức năng cốt lõi).*
+🪶 **Siêu nhẹ**: Bộ nhớ lõi <10MB — nhỏ hơn 99% so với OpenClaw.*
💰 **Chi phí tối thiểu**: Đủ hiệu quả để chạy trên phần cứng $10 — rẻ hơn 98% so với Mac mini.
-⚡️ **Khởi động siêu nhanh**: Nhanh gấp 400 lần, khởi động trong <1 giây ngay cả trên CPU đơn nhân 0.6GHz.
+⚡️ **Khởi động cực nhanh**: Khởi động nhanh hơn 400 lần. Khởi động trong <1 giây ngay cả trên bộ xử lý đơn nhân 0.6GHz.
-🌍 **Di động thực sự**: Một file binary duy nhất chạy trên RISC-V, ARM, MIPS và x86. Một click là chạy!
+🌍 **Thực sự di động**: Một binary duy nhất cho các kiến trúc RISC-V, ARM, MIPS và x86. Một binary, chạy mọi nơi!
-🤖 **AI tự xây dựng**: Triển khai Go-native tự động — 95% mã nguồn cốt lõi được Agent tạo ra, với sự tinh chỉnh của con người.
+🤖 **Được AI khởi động**: Triển khai Go thuần túy — 95% mã lõi được tạo bởi Agent và tinh chỉnh qua quy trình human-in-the-loop.
-🔌 **Hỗ trợ MCP**: Tích hợp [Model Context Protocol](https://modelcontextprotocol.io/) gốc — kết nối bất kỳ máy chủ MCP nào để mở rộng khả năng của agent.
+🔌 **Hỗ trợ MCP**: Tích hợp [Model Context Protocol](https://modelcontextprotocol.io/) gốc — kết nối bất kỳ MCP server nào để mở rộng khả năng Agent.
-👁️ **Pipeline Xử lý Hình ảnh**: Gửi hình ảnh và tệp trực tiếp cho agent — tự động mã hóa base64 cho các LLM đa phương thức.
+👁️ **Pipeline thị giác**: Gửi hình ảnh và tệp trực tiếp đến Agent — tự động mã hóa base64 cho LLM đa phương thức.
-🧠 **Định tuyến Thông minh**: Định tuyến mô hình dựa trên quy tắc — truy vấn đơn giản chuyển đến mô hình nhẹ, tiết kiệm chi phí API.
+🧠 **Định tuyến thông minh**: Định tuyến mô hình dựa trên quy tắc — các truy vấn đơn giản đến mô hình nhẹ, tiết kiệm chi phí API.
-_*Các phiên bản gần đây có thể sử dụng 10–20MB do merge tính năng nhanh chóng. Tối ưu tài nguyên đang được lên kế hoạch. So sánh thời gian khởi động dựa trên benchmark đơn nhân 0.8GHz (xem bảng bên dưới)._
+_*Các bản build gần đây có thể dùng 10-20MB do merge PR nhanh. Tối ưu hóa tài nguyên đang được lên kế hoạch. So sánh tốc độ khởi động dựa trên benchmark lõi đơn 0.8GHz (xem bảng bên dưới)._
-| | OpenClaw | NanoBot | **PicoClaw** |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Ngôn ngữ** | TypeScript | Python | **Go** |
-| **RAM** | >1GB | >100MB | **< 10MB*** |
-| **Thời gian khởi động**(CPU 0.8GHz) | >500s | >30s | **<1s** |
-| **Chi phí** | Mac Mini $599 | Hầu hết SBC Linux ~$50 | **Mọi bo mạch Linux****Chỉ từ $10** |
+
+
+| | OpenClaw | NanoBot | **PicoClaw** |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Ngôn ngữ** | TypeScript | Python | **Go** |
+| **RAM** | >1GB | >100MB | **< 10MB*** |
+| **Thời gian khởi động**(lõi 0.8GHz) | >500s | >30s | **<1s** |
+| **Chi phí** | Mac Mini $599 | Hầu hết board Linux ~$50 | **Bất kỳ board Linux****từ $10** |
-## 🦾 Demo
+
-### 🛠️ Quy trình trợ lý tiêu chuẩn
+> **[Danh sách Tương thích Phần cứng](docs/vi/hardware-compatibility.md)** — Xem tất cả các board đã được kiểm tra, từ RISC-V $5 đến Raspberry Pi đến điện thoại Android. Board của bạn chưa có trong danh sách? Gửi PR!
+
+
+
+
+## 🦾 Minh họa
+
+### 🛠️ Quy trình Trợ lý Tiêu chuẩn
-
- 🧩 Lập trình Full-Stack
🗂️ Quản lý Nhật ký & Kế hoạch
🔎 Tìm kiếm Web & Học hỏi
-
-
-
- Phát triển • Triển khai • Mở rộng
- Lên lịch • Tự động hóa • Ghi nhớ
- Khám phá • Phân tích • Xu hướng
-
+
+Chế độ Kỹ sư Full-Stack
Ghi nhật ký & Lập kế hoạch
Tìm kiếm Web & Học tập
+
+
+
+Phát triển · Triển khai · Mở rộng
+Lên lịch · Tự động hóa · Ghi nhớ
+Khám phá · Thông tin · Xu hướng
+
-### 📱 Chạy trên điện thoại Android cũ
+### 🐜 Triển khai Sáng tạo với Dấu chân Nhỏ
-Hãy cho chiếc điện thoại cũ một cuộc sống mới! Biến nó thành trợ lý AI thông minh với PicoClaw. Bắt đầu nhanh:
+PicoClaw có thể được triển khai trên hầu hết mọi thiết bị Linux!
-1. **Cài đặt [Termux](https://github.com/termux/termux-app)** (Tải từ [GitHub Releases](https://github.com/termux/termux-app/releases), hoặc tìm trên F-Droid / Google Play).
-2. **Chạy các lệnh**
-
-```bash
-# Tải phiên bản mới nhất từ https://github.com/sipeed/picoclaw/releases
-wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
-tar xzf picoclaw_Linux_arm64.tar.gz
-pkg install proot
-termux-chroot ./picoclaw onboard
-```
-
-Sau đó làm theo hướng dẫn trong phần "Bắt đầu nhanh" để hoàn tất cấu hình!
-
-
-
-### 🐜 Triển khai sáng tạo trên phần cứng tối thiểu
-
-PicoClaw có thể triển khai trên hầu hết mọi thiết bị Linux!
-
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) phiên bản E(Ethernet) hoặc W(WiFi6), dùng làm Trợ lý Gia đình tối giản
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), hoặc $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) dùng cho quản trị Server tự động
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) hoặc $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) dùng cho Giám sát thông minh
+- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) phiên bản E(Ethernet) hoặc W(WiFi6), cho trợ lý gia đình tối giản
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), hoặc $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), cho vận hành máy chủ tự động
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) hoặc $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), cho giám sát thông minh
-🌟 Nhiều hình thức triển khai hơn đang chờ bạn khám phá!
+🌟 Còn nhiều trường hợp triển khai đang chờ đón!
## 📦 Cài đặt
-### Cài đặt bằng binary biên dịch sẵn
+### Tải xuống từ picoclaw.io (Khuyến nghị)
-Tải file binary cho nền tảng của bạn từ [trang Releases](https://github.com/sipeed/picoclaw/releases).
+Truy cập **[picoclaw.io](https://picoclaw.io)** — website chính thức tự động phát hiện nền tảng của bạn và cung cấp tải xuống một cú nhấp. Không cần chọn kiến trúc thủ công.
-### Cài đặt từ mã nguồn (có tính năng mới nhất, khuyên dùng cho phát triển)
+### Tải xuống binary đã biên dịch sẵn
+
+Ngoài ra, tải binary cho nền tảng của bạn từ trang [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Xây dựng từ mã nguồn (để phát triển)
```bash
git clone https://github.com/sipeed/picoclaw.git
@@ -172,78 +166,413 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
-# Build (không cần cài đặt)
+# Build core binary
make build
-# Build cho nhiều nền tảng
+# Build Web UI Launcher (required for WebUI mode)
+make build-launcher
+
+# Build for multiple platforms
make build-all
-# Build cho Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+# Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
make build-pi-zero
-# Build và cài đặt
+# Build and install
make install
```
-**Raspberry Pi Zero 2 W:** Sử dụng binary phù hợp với hệ điều hành: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Hoặc chạy `make build-pi-zero` để build cả hai.
+**Raspberry Pi Zero 2 W:** Sử dụng binary phù hợp với hệ điều hành của bạn: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Hoặc chạy `make build-pi-zero` để xây dựng cả hai.
-## 📚 Tài liệu
+## 🚀 Hướng dẫn Khởi động Nhanh
-Để xem hướng dẫn chi tiết, tham khảo tài liệu bên dưới. README này chỉ bao gồm phần bắt đầu nhanh.
+### 🌐 WebUI Launcher (Khuyến nghị cho Desktop)
-| Chủ đề | Mô tả |
-|--------|-------|
-| 🐳 [Docker & Bắt đầu nhanh](docs/vi/docker.md) | Thiết lập Docker Compose, chế độ Launcher/Agent, cấu hình Bắt đầu nhanh |
-| 💬 [Ứng dụng Chat](docs/vi/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom và nhiều hơn |
-| ⚙️ [Cấu hình](docs/vi/configuration.md) | Biến môi trường, cấu trúc workspace, nguồn skill, sandbox bảo mật, heartbeat |
-| 🔌 [Nhà cung cấp & Mô hình](docs/vi/providers.md) | 20+ nhà cung cấp LLM, định tuyến mô hình, cấu hình model_list, kiến trúc nhà cung cấp |
-| 🔄 [Spawn & Tác vụ bất đồng bộ](docs/vi/spawn-tasks.md) | Tác vụ nhanh, tác vụ dài với spawn, điều phối sub-agent bất đồng bộ |
-| 🐛 [Xử lý sự cố](docs/vi/troubleshooting.md) | Các vấn đề thường gặp và giải pháp |
-| 🔧 [Cấu hình Công cụ](docs/vi/tools_configuration.md) | Bật/tắt từng công cụ, chính sách thực thi |
+WebUI Launcher cung cấp giao diện dựa trên trình duyệt để cấu hình và trò chuyện. Đây là cách dễ nhất để bắt đầu — không cần kiến thức dòng lệnh.
+
+**Tùy chọn 1: Nhấp đúp (Desktop)**
+
+Sau khi tải xuống từ [picoclaw.io](https://picoclaw.io), nhấp đúp vào `picoclaw-launcher` (hoặc `picoclaw-launcher.exe` trên Windows). Trình duyệt của bạn sẽ tự động mở tại `http://localhost:18800`.
+
+**Tùy chọn 2: Dòng lệnh**
+
+```bash
+picoclaw-launcher
+# Mở http://localhost:18800 trong trình duyệt của bạn
+```
+
+> [!TIP]
+> **Truy cập từ xa / Docker / VM:** Thêm cờ `-public` để lắng nghe trên tất cả giao diện:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+
+
+
+**Bắt đầu:**
+
+Mở WebUI, sau đó: **1)** Cấu hình Provider (thêm API key LLM của bạn) -> **2)** Cấu hình Channel (ví dụ: Telegram) -> **3)** Khởi động Gateway -> **4)** Trò chuyện!
+
+Để biết tài liệu WebUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io).
+
+
+Docker (thay thế)
+
+### 💻 TUI Launcher (Khuyến nghị cho Headless / SSH)
+
+TUI (Terminal UI) Launcher cung cấp giao diện terminal đầy đủ tính năng để cấu hình và quản lý. Lý tưởng cho máy chủ, Raspberry Pi và các môi trường headless khác.
+
+```bash
+picoclaw-launcher-tui
+```
+
+
+
+
+**Bắt đầu:**
+
+Sử dụng menu TUI để: **1)** Cấu hình Provider -> **2)** Cấu hình Channel -> **3)** Khởi động Gateway -> **4)** Trò chuyện!
+
+Để biết tài liệu TUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Hãy cho chiếc điện thoại cũ của bạn một cuộc sống mới! Biến nó thành Trợ lý AI thông minh với PicoClaw.
+
+**Tùy chọn 1: Termux (có sẵn ngay)**
+
+1. Cài đặt [Termux](https://github.com/termux/termux-app) (tải từ [GitHub Releases](https://github.com/termux/termux-app/releases), hoặc tìm kiếm trong F-Droid / Google Play)
+2. Chạy các lệnh sau:
+
+```bash
+# Download the latest release
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard # chroot provides a standard Linux filesystem layout
+```
+
+Sau đó làm theo phần Terminal Launcher bên dưới để hoàn tất cấu hình.
+
+
+Terminal Launcher (cho môi trường hạn chế tài nguyên)
+
+## 🔌 Providers (LLM)
+
+PicoClaw hỗ trợ 30+ Provider LLM thông qua cấu hình `model_list`. Sử dụng định dạng `protocol/model`:
+
+| Provider | Protocol | API Key | Ghi chú |
+|----------|----------|---------|---------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Bắt buộc | GPT-5.4, GPT-4o, o3, v.v. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Bắt buộc | Claude Opus 4.6, Sonnet 4.6, v.v. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Bắt buộc | Gemini 3 Flash, 2.5 Pro, v.v. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Bắt buộc | 200+ mô hình, API thống nhất |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Bắt buộc | GLM-4.7, GLM-5, v.v. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Bắt buộc | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Bắt buộc | Doubao, Ark models |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Bắt buộc | Qwen3, Qwen-Max, v.v. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Bắt buộc | Suy luận nhanh (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Bắt buộc | Kimi models |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Bắt buộc | MiniMax models |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Bắt buộc | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Bắt buộc | Mô hình do NVIDIA lưu trữ |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Bắt buộc | Suy luận nhanh |
+| [Novita AI](https://novita.ai/) | `novita/` | Bắt buộc | Nhiều mô hình mở |
+| [Ollama](https://ollama.com/) | `ollama/` | Không cần | Mô hình cục bộ, tự lưu trữ |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Không cần | Triển khai cục bộ, tương thích OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Tùy | Proxy cho 100+ provider |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Bắt buộc | Triển khai Azure doanh nghiệp |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Đăng nhập bằng device code |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+
+Triển khai cục bộ (Ollama, vLLM, v.v.)
+
+## 💬 Channels (Ứng dụng Chat)
+
+Trò chuyện với PicoClaw của bạn qua 17+ nền tảng nhắn tin:
+
+| Channel | Thiết lập | Protocol | Tài liệu |
+|---------|-----------|----------|----------|
+| **Telegram** | Dễ (bot token) | Long polling | [Hướng dẫn](docs/channels/telegram/README.vi.md) |
+| **Discord** | Dễ (bot token + intents) | WebSocket | [Hướng dẫn](docs/channels/discord/README.vi.md) |
+| **WhatsApp** | Dễ (quét QR hoặc bridge URL) | Native / Bridge | [Hướng dẫn](docs/vi/chat-apps.md#whatsapp) |
+| **Weixin** | Dễ (quét QR gốc) | iLink API | [Hướng dẫn](docs/vi/chat-apps.md#weixin) |
+| **QQ** | Dễ (AppID + AppSecret) | WebSocket | [Hướng dẫn](docs/channels/qq/README.vi.md) |
+| **Slack** | Dễ (bot + app token) | Socket Mode | [Hướng dẫn](docs/channels/slack/README.vi.md) |
+| **Matrix** | Trung bình (homeserver + token) | Sync API | [Hướng dẫn](docs/channels/matrix/README.vi.md) |
+| **DingTalk** | Trung bình (client credentials) | Stream | [Hướng dẫn](docs/channels/dingtalk/README.vi.md) |
+| **Feishu / Lark** | Trung bình (App ID + Secret) | WebSocket/SDK | [Hướng dẫn](docs/channels/feishu/README.vi.md) |
+| **LINE** | Trung bình (credentials + webhook) | Webhook | [Hướng dẫn](docs/channels/line/README.vi.md) |
+| **WeCom Bot** | Trung bình (webhook URL) | Webhook | [Hướng dẫn](docs/channels/wecom/wecom_bot/README.vi.md) |
+| **WeCom App** | Trung bình (corp credentials) | Webhook | [Hướng dẫn](docs/channels/wecom/wecom_app/README.vi.md) |
+| **WeCom AI Bot** | Trung bình (token + AES key) | WebSocket / Webhook | [Hướng dẫn](docs/channels/wecom/wecom_aibot/README.vi.md) |
+| **IRC** | Trung bình (server + nick) | IRC protocol | [Hướng dẫn](docs/vi/chat-apps.md#irc) |
+| **OneBot** | Trung bình (WebSocket URL) | OneBot v11 | [Hướng dẫn](docs/channels/onebot/README.vi.md) |
+| **MaixCam** | Dễ (bật) | TCP socket | [Hướng dẫn](docs/channels/maixcam/README.vi.md) |
+| **Pico** | Dễ (bật) | Native protocol | Tích hợp sẵn |
+| **Pico Client** | Dễ (WebSocket URL) | WebSocket | Tích hợp sẵn |
+
+> Tất cả các Channel dựa trên webhook dùng chung một Gateway HTTP server (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`). Feishu sử dụng chế độ WebSocket/SDK và không dùng HTTP server chung.
+
+Để biết hướng dẫn thiết lập Channel chi tiết, xem [Cấu hình Ứng dụng Chat](docs/vi/chat-apps.md).
+
+## 🔧 Tools
+
+### 🔍 Tìm kiếm Web
+
+PicoClaw có thể tìm kiếm web để cung cấp thông tin cập nhật. Cấu hình trong `tools.web`:
+
+| Công cụ Tìm kiếm | API Key | Gói miễn phí | Liên kết |
+|------------------|---------|--------------|----------|
+| DuckDuckGo | Không cần | Không giới hạn | Dự phòng tích hợp sẵn |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Bắt buộc | 1000 truy vấn/ngày | AI, tối ưu cho tiếng Trung |
+| [Tavily](https://tavily.com) | Bắt buộc | 1000 truy vấn/tháng | Tối ưu cho AI Agent |
+| [Brave Search](https://brave.com/search/api) | Bắt buộc | 2000 truy vấn/tháng | Nhanh và riêng tư |
+| [Perplexity](https://www.perplexity.ai) | Bắt buộc | Trả phí | Tìm kiếm hỗ trợ AI |
+| [SearXNG](https://github.com/searxng/searxng) | Không cần | Tự lưu trữ | Metasearch engine miễn phí |
+| [GLM Search](https://open.bigmodel.cn/) | Bắt buộc | Tùy | Tìm kiếm web Zhipu |
+
+### ⚙️ Các Tools Khác
+
+PicoClaw bao gồm các tool tích hợp sẵn cho thao tác tệp, thực thi mã, lên lịch và nhiều hơn nữa. Xem [Cấu hình Tools](docs/vi/tools_configuration.md) để biết chi tiết.
+
+## 🎯 Skills
+
+Skills là các khả năng mô-đun mở rộng Agent của bạn. Chúng được tải từ các tệp `SKILL.md` trong workspace của bạn.
+
+**Cài đặt Skills từ ClawHub:**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install
+```
+
+**Cấu hình token ClawHub** (tùy chọn, để có giới hạn tốc độ cao hơn):
+
+Thêm vào `config.json` của bạn:
+```json
+{
+ "tools": {
+ "skills": {
+ "registries": {
+ "clawhub": {
+ "auth_token": "your-clawhub-token"
+ }
+ }
+ }
+ }
+}
+```
+
+Để biết thêm chi tiết, xem [Cấu hình Tools - Skills](docs/vi/tools_configuration.md#skills-tool).
+
+## 🔗 MCP (Model Context Protocol)
+
+PicoClaw hỗ trợ [MCP](https://modelcontextprotocol.io/) gốc — kết nối bất kỳ MCP server nào để mở rộng khả năng Agent của bạn với các tool và nguồn dữ liệu bên ngoài.
+
+```json
+{
+ "tools": {
+ "mcp": {
+ "enabled": true,
+ "servers": {
+ "filesystem": {
+ "enabled": true,
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+ }
+ }
+ }
+ }
+}
+```
+
+Để biết cấu hình MCP đầy đủ (stdio, SSE, HTTP transports, Tool Discovery), xem [Cấu hình Tools - MCP](docs/vi/tools_configuration.md#mcp-tool).
##
+Discord:
-PicoClaw: 基于Go语言的超高效 AI 助手
-$10 硬件 · <10MB 内存 · <1s 启动 · 皮皮虾，我们走！
+$10 硬件 · 10MB 内存 · 毫秒启动 · 皮皮虾，我们走！
+
| | OpenClaw | NanoBot | **PicoClaw** |
| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
| **语言** | TypeScript | Python | **Go** |
@@ -104,6 +106,14 @@ _*近期版本因快速合并 PR 可能占用 10–20MB，资源优化已列入
+
+
+
## 🦾 演示
### 🛠️ 标准助手工作流
@@ -126,25 +136,6 @@ _*近期版本因快速合并 PR 可能占用 10–20MB，资源优化已列入
-### 📱 在手机上轻松运行
-
-PicoClaw 可以将你 10 年前的老旧手机废物利用，变身成为你的 AI 助理！快速指南：
-
-1. 安装 [Termux](https://github.com/termux/termux-app)（可从 [GitHub Releases](https://github.com/termux/termux-app/releases) 下载，或在 F-Droid 等应用商店搜索）
-2. 打开后执行指令
-
-```bash
-# 从 Release 页面下载最新版本
-wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
-tar xzf picoclaw_Linux_arm64.tar.gz
-pkg install proot
-termux-chroot ./picoclaw onboard
-```
-
-然后跟随下面的"快速开始"章节继续配置 PicoClaw 即可使用！
-
-
+
+
+**开始使用：**
+
+打开 WebUI，然后：**1)** 配置 Provider（填入 LLM API Key）-> **2)** 配置 Channel（如 Telegram）-> **3)** 启动 Gateway -> **4)** 开始聊天！
+
+详细 WebUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。
+
+
+Docker（备选方案）
+
+### 💻 TUI Launcher（推荐无头环境 / SSH）
+
+TUI（终端 UI）Launcher 提供功能完整的终端配置与管理界面，适合服务器、树莓派等无显示器环境。
+
+```bash
+picoclaw-launcher-tui
+```
+
+
+
+
+**开始使用：**
+
+通过 TUI 菜单：**1)** 配置 Provider -> **2)** 配置 Channel -> **3)** 启动 Gateway -> **4)** 开始聊天！
+
+详细 TUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。
+
+### 📱 Android
+
+让你十年前的旧手机焕发新生！将它变成你的 AI 助手。
+
+**方式一：Termux（现已可用）**
+
+1. 安装 [Termux](https://github.com/termux/termux-app)（可从 [GitHub Releases](https://github.com/termux/termux-app/releases) 下载，或在 F-Droid / Google Play 中搜索）
+2. 执行以下命令：
+
+```bash
+# 从 Release 页面下载最新版本
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard # chroot 提供标准 Linux 文件系统布局
+```
+
+然后跟随下面的"Terminal Launcher"章节继续配置。
+
+
+Terminal Launcher（适用于资源受限环境）
+
+## 🔌 Providers (LLM)
+
+PicoClaw 通过 `model_list` 配置支持 30+ LLM Provider，使用 `协议/模型` 格式：
+
+| Provider | 协议 | API Key | 备注 |
+|----------|------|---------|------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | 必填 | GPT-5.4、GPT-4o、o3 等 |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | 必填 | Claude Opus 4.6、Sonnet 4.6 等 |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | 必填 | Gemini 3 Flash、2.5 Pro 等 |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | 必填 | 200+ 模型，统一 API |
+| [智谱 (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | 必填 | GLM-4.7、GLM-5 等 |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | 必填 | DeepSeek-V3、DeepSeek-R1 |
+| [火山引擎](https://console.volcengine.com) | `volcengine/` | 必填 | 豆包、Ark 系列模型 |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | 必填 | Qwen3、Qwen-Max 等 |
+| [Groq](https://console.groq.com/keys) | `groq/` | 必填 | 快速推理（Llama、Mixtral） |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | 必填 | Kimi 系列模型 |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | 必填 | MiniMax 系列模型 |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | 必填 | Mistral Large、Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | 必填 | NVIDIA 托管模型 |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | 必填 | 快速推理 |
+| [Novita AI](https://novita.ai/) | `novita/` | 必填 | 多种开源模型 |
+| [Ollama](https://ollama.com/) | `ollama/` | 无需 | 本地模型，自托管 |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | 无需 | 本地部署，兼容 OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | 视情况 | 100+ Provider 代理 |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | 必填 | 企业级 Azure 部署 |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | 设备码登录 |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+
+本地部署（Ollama、vLLM 等）
+
+## 💬 Channels（聊天应用）
+
+通过 17+ 消息平台与你的 PicoClaw 对话：
+
+| Channel | 配置难度 | 协议 | 文档 |
+|---------|----------|------|------|
+| **Telegram** | 简单（bot token） | 长轮询 | [指南](docs/channels/telegram/README.zh.md) |
+| **Discord** | 简单（bot token + intents） | WebSocket | [指南](docs/channels/discord/README.zh.md) |
+| **WhatsApp** | 简单（扫码或 bridge URL） | 原生 / Bridge | [指南](docs/zh/chat-apps.md#whatsapp) |
+| **微信 (Weixin)** | 简单（扫码登录） | iLink API | [指南](docs/zh/chat-apps.md#weixin) |
+| **QQ** | 简单（AppID + AppSecret） | WebSocket | [指南](docs/channels/qq/README.zh.md) |
+| **Slack** | 简单（bot + app token） | Socket Mode | [指南](docs/channels/slack/README.zh.md) |
+| **Matrix** | 中等（homeserver + token） | Sync API | [指南](docs/channels/matrix/README.zh.md) |
+| **钉钉** | 中等（client credentials） | Stream | [指南](docs/channels/dingtalk/README.zh.md) |
+| **飞书 / Lark** | 中等（App ID + Secret） | WebSocket/SDK | [指南](docs/channels/feishu/README.zh.md) |
+| **LINE** | 中等（credentials + webhook） | Webhook | [指南](docs/channels/line/README.zh.md) |
+| **企业微信机器人** | 中等（webhook URL） | Webhook | [指南](docs/channels/wecom/wecom_bot/README.zh.md) |
+| **企业微信应用** | 中等（corp credentials） | Webhook | [指南](docs/channels/wecom/wecom_app/README.zh.md) |
+| **企业微信 AI 机器人** | 中等（token + AES key） | WebSocket / Webhook | [指南](docs/channels/wecom/wecom_aibot/README.zh.md) |
+| **IRC** | 中等（server + nick） | IRC 协议 | [指南](docs/zh/chat-apps.md#irc) |
+| **OneBot** | 中等（WebSocket URL） | OneBot v11 | [指南](docs/channels/onebot/README.zh.md) |
+| **MaixCam** | 简单（启用即可） | TCP socket | [指南](docs/channels/maixcam/README.zh.md) |
+| **Pico** | 简单（启用即可） | 原生协议 | 内置 |
+| **Pico Client** | 简单（WebSocket URL） | WebSocket | 内置 |
+
+> 所有基于 Webhook 的 Channel 共用同一个 Gateway HTTP 服务器（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`）。飞书使用 WebSocket/SDK 模式，不使用共享 HTTP 服务器。
+
+详细 Channel 配置说明请参阅 [聊天应用配置](docs/zh/chat-apps.md)。
+
+## 🔧 Tools
+
+### 🔍 网络搜索
+
+PicoClaw 可以搜索网络以提供最新信息。在 `tools.web` 中配置：
+
+| 搜索引擎 | API Key | 免费额度 | 链接 |
+|---------|---------|---------|------|
+| [百度搜索](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | 必填 | 1000 次/天 | AI 搜索，国内首选 |
+| [Tavily](https://tavily.com) | 必填 | 1000 次/月 | 专为 AI Agent 优化 |
+| [GLM Search](https://open.bigmodel.cn/) | 必填 | 视情况 | 智谱网络搜索 |
+| DuckDuckGo | 无需 | 无限制 | 内置备用（国内访问困难） |
+| [Perplexity](https://www.perplexity.ai) | 必填 | 付费 | AI 驱动搜索（国内访问困难） |
+| [Brave Search](https://brave.com/search/api) | 必填 | 2000 次/月 | 快速且注重隐私（国内访问困难） |
+| [SearXNG](https://github.com/searxng/searxng) | 无需 | 自托管 | 免费元搜索引擎 |
+
+### ⚙️ 其他工具
+
+PicoClaw 内置文件操作、代码执行、定时任务等工具。详情请参阅 [工具配置](docs/zh/tools_configuration.md)。
+
+## 🎯 Skills
+
+Skills 是扩展 Agent 能力的模块化插件，从工作区的 `SKILL.md` 文件加载。
+
+**从 ClawHub 安装 Skills：**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install
+```
+
+**配置 ClawHub token**（可选，用于提高速率限制）：
+
+在 `config.json` 中添加：
+```json
+{
+ "tools": {
+ "skills": {
+ "registries": {
+ "clawhub": {
+ "auth_token": "your-clawhub-token"
+ }
+ }
+ }
+ }
+}
+```
+
+更多详情请参阅 [工具配置 - Skills](docs/zh/tools_configuration.md#skills-tool)。
+
+## 🔗 MCP (Model Context Protocol)
+
+PicoClaw 原生支持 [MCP](https://modelcontextprotocol.io/) — 连接任意 MCP 服务器，通过外部工具和数据源扩展 Agent 能力。
+
+```json
+{
+ "tools": {
+ "mcp": {
+ "enabled": true,
+ "servers": {
+ "filesystem": {
+ "enabled": true,
+ "command": "npx",
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+ }
+ }
+ }
+ }
+}
+```
+
+完整 MCP 配置（stdio、SSE、HTTP 传输、Tool Discovery）请参阅 [工具配置 - MCP](docs/zh/tools_configuration.md#mcp-tool)。
##
-/models
+}
+
+// DefaultConfig returns a minimal valid TUIConfig.
+func DefaultConfig() *TUIConfig {
+ return &TUIConfig{
+ Version: "1.0",
+ Model: Model{Type: "provider"},
+ Provider: Provider{
+ Schemes: []Scheme{},
+ Users: []User{},
+ Current: ProviderCurrent{},
+ },
+ }
+}
+
+// Load reads the TUI config from path. Returns a default config if the file does not exist.
+func Load(path string) (*TUIConfig, error) {
+ data, err := os.ReadFile(path)
+ if os.IsNotExist(err) {
+ return DefaultConfig(), nil
+ }
+ if err != nil {
+ return nil, fmt.Errorf("failed to read config file %q: %w", path, err)
+ }
+
+ cfg := DefaultConfig()
+ if _, err := toml.Decode(string(data), cfg); err != nil {
+ return nil, fmt.Errorf("failed to parse config file %q: %w", path, err)
+ }
+
+ applyDefaults(cfg)
+ return cfg, nil
+}
+
+// Save writes cfg to path atomically (safe for flash / SD storage).
+func Save(path string, cfg *TUIConfig) error {
+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+ return fmt.Errorf("failed to create config directory: %w", err)
+ }
+ var buf bytes.Buffer
+ enc := toml.NewEncoder(&buf)
+ if err := enc.Encode(cfg); err != nil {
+ return fmt.Errorf("failed to encode config: %w", err)
+ }
+ if err := fileutil.WriteFileAtomic(path, buf.Bytes(), 0o600); err != nil {
+ return fmt.Errorf("failed to write config file %q: %w", path, err)
+ }
+ return nil
+}
+
+func applyDefaults(cfg *TUIConfig) {
+ if cfg.Version == "" {
+ cfg.Version = "1.0"
+ }
+ if cfg.Model.Type == "" {
+ cfg.Model.Type = "provider"
+ }
+ for i := range cfg.Provider.Schemes {
+ if cfg.Provider.Schemes[i].Type == "" {
+ cfg.Provider.Schemes[i].Type = "openai-compatible"
+ }
+ }
+ for i := range cfg.Provider.Users {
+ if cfg.Provider.Users[i].Type == "" {
+ cfg.Provider.Users[i].Type = "key"
+ }
+ }
+}
+
+// SchemeByName returns the first Scheme whose Name matches, or nil.
+func (p *Provider) SchemeByName(name string) *Scheme {
+ for i := range p.Schemes {
+ if p.Schemes[i].Name == name {
+ return &p.Schemes[i]
+ }
+ }
+ return nil
+}
+
+// UsersForScheme returns all users whose Scheme field matches schemeName.
+func (p *Provider) UsersForScheme(schemeName string) []User {
+ var out []User
+ for _, u := range p.Users {
+ if u.Scheme == schemeName {
+ out = append(out, u)
+ }
+ }
+ return out
+}
+
+// SyncSelectedModelToMainConfig syncs the currently selected model to ~/.picoclaw/config.json
+// Adds/replaces a "tui-prefer" model entry and sets it as the default model.
+// Preserves all other existing fields in the config file unchanged.
+func SyncSelectedModelToMainConfig(scheme Scheme, user User, modelID string) error {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ home = "."
+ }
+ mainConfigPath := filepath.Join(home, ".picoclaw", "config.json")
+
+ var cfg map[string]any
+ if data, readErr := os.ReadFile(mainConfigPath); readErr == nil {
+ if unmarshalErr := json.Unmarshal(data, &cfg); unmarshalErr != nil {
+ cfg = make(map[string]any)
+ }
+ } else {
+ cfg = make(map[string]any)
+ }
+
+ if _, ok := cfg["agents"]; !ok {
+ cfg["agents"] = make(map[string]any)
+ }
+ agents, ok := cfg["agents"].(map[string]any)
+ if ok {
+ if _, ok := agents["defaults"]; !ok {
+ agents["defaults"] = make(map[string]any)
+ }
+ defaults, ok := agents["defaults"].(map[string]any)
+ if ok {
+ defaults["model"] = "tui-prefer"
+ }
+ }
+
+ tuiModel := map[string]any{
+ "model_name": "tui-prefer",
+ "model": modelID,
+ "api_key": user.Key,
+ "api_base": scheme.BaseURL,
+ }
+
+ modelList := []any{}
+ if ml, ok := cfg["model_list"].([]any); ok {
+ modelList = ml
+ }
+
+ found := false
+ for i, m := range modelList {
+ if entry, ok := m.(map[string]any); ok {
+ if name, ok := entry["model_name"].(string); ok && name == "tui-prefer" {
+ modelList[i] = tuiModel
+ found = true
+ break
+ }
+ }
+ }
+ if !found {
+ modelList = append(modelList, tuiModel)
+ }
+ cfg["model_list"] = modelList
+
+ data, err := json.MarshalIndent(cfg, "", " ")
+ if err != nil {
+ return err
+ }
+
+ if err := os.MkdirAll(filepath.Dir(mainConfigPath), 0o700); err != nil {
+ return err
+ }
+
+ return os.WriteFile(mainConfigPath, data, 0o600)
+}
+
+func (cfg *TUIConfig) CurrentModelLabel() string {
+ cur := cfg.Provider.Current
+ if cur.Model == "" {
+ return "(not configured)"
+ }
+ label := cur.Scheme
+ if label != "" {
+ label += " / "
+ }
+ return label + cur.Model
+}
diff --git a/cmd/picoclaw-launcher-tui/internal/config/store.go b/cmd/picoclaw-launcher-tui/internal/config/store.go
deleted file mode 100644
index 0236de19f..000000000
--- a/cmd/picoclaw-launcher-tui/internal/config/store.go
+++ /dev/null
@@ -1,49 +0,0 @@
-package configstore
-
-import (
- "errors"
- "os"
- "path/filepath"
-
- picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
-)
-
-const (
- configDirName = ".picoclaw"
- configFileName = "config.json"
-)
-
-func ConfigPath() (string, error) {
- dir, err := ConfigDir()
- if err != nil {
- return "", err
- }
- return filepath.Join(dir, configFileName), nil
-}
-
-func ConfigDir() (string, error) {
- home, err := os.UserHomeDir()
- if err != nil {
- return "", err
- }
- return filepath.Join(home, configDirName), nil
-}
-
-func Load() (*picoclawconfig.Config, error) {
- path, err := ConfigPath()
- if err != nil {
- return nil, err
- }
- return picoclawconfig.LoadConfig(path)
-}
-
-func Save(cfg *picoclawconfig.Config) error {
- if cfg == nil {
- return errors.New("config is nil")
- }
- path, err := ConfigPath()
- if err != nil {
- return err
- }
- return picoclawconfig.SaveConfig(path, cfg)
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/app.go b/cmd/picoclaw-launcher-tui/internal/ui/app.go
deleted file mode 100644
index a2ccddf70..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/app.go
+++ /dev/null
@@ -1,522 +0,0 @@
-package ui
-
-import (
- "fmt"
- "os"
- "os/exec"
- "path/filepath"
- "strings"
-
- "github.com/gdamore/tcell/v2"
- "github.com/rivo/tview"
-
- configstore "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/internal/config"
- picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
-)
-
-type appState struct {
- app *tview.Application
- pages *tview.Pages
- stack []string
- config *picoclawconfig.Config
- configPath string
- gatewayCmd *exec.Cmd
- menus map[string]*Menu
- original []byte
- hasOriginal bool
- backupPath string
- dirty bool
- logPath string
-}
-
-func Run() error {
- applyStyles()
- cfg, err := configstore.Load()
- if err != nil {
- return err
- }
- path, err := configstore.ConfigPath()
- if err != nil {
- return err
- }
-
- if cfg == nil {
- cfg = picoclawconfig.DefaultConfig()
- }
-
- originalData, hasOriginal := loadOriginalConfig(path)
- backupPath := path + ".bak"
- if hasOriginal {
- _ = writeBackupConfig(backupPath, originalData)
- }
-
- logPath := filepath.Join(filepath.Dir(path), "gateway.log")
- state := &appState{
- app: tview.NewApplication(),
- pages: tview.NewPages(),
- config: cfg,
- configPath: path,
- menus: map[string]*Menu{},
- original: originalData,
- hasOriginal: hasOriginal,
- backupPath: backupPath,
- logPath: logPath,
- }
-
- state.push("main", state.mainMenu())
-
- root := tview.NewFlex().SetDirection(tview.FlexRow)
- root.AddItem(bannerView(), 6, 0, false)
- root.AddItem(state.pages, 0, 1, true)
- root.AddItem(footerView(), 1, 0, false)
-
- if err := state.app.SetRoot(root, true).EnableMouse(false).Run(); err != nil {
- return err
- }
- return nil
-}
-
-func (s *appState) push(name string, primitive tview.Primitive) {
- s.pages.AddPage(name, primitive, true, true)
- s.stack = append(s.stack, name)
- s.pages.SwitchToPage(name)
- if menu, ok := primitive.(*Menu); ok {
- s.menus[name] = menu
- }
-}
-
-func (s *appState) pop() {
- if len(s.stack) == 0 {
- return
- }
- last := s.stack[len(s.stack)-1]
- s.pages.RemovePage(last)
- s.stack = s.stack[:len(s.stack)-1]
- if len(s.stack) == 0 {
- s.app.Stop()
- return
- }
- current := s.stack[len(s.stack)-1]
- s.pages.SwitchToPage(current)
- if menu, ok := s.menus[current]; ok {
- s.refreshMenu(current, menu)
- }
-}
-
-func (s *appState) mainMenu() tview.Primitive {
- menu := NewMenu("Menu", nil)
- refreshMainMenu(menu, s)
- menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
- switch event.Key() {
- case tcell.KeyEsc:
- s.requestExit()
- return nil
- }
-
- return event
- })
-
- return menu
-}
-
-func (s *appState) refreshMenu(name string, menu *Menu) {
- switch name {
- case "main":
- refreshMainMenu(menu, s)
- case "model":
- refreshModelMenuFromState(menu, s)
- case "channel":
- refreshChannelMenuFromState(menu, s)
- }
-}
-
-func (s *appState) countChannels() (enabled int, total int) {
- c := s.config.Channels
- entries := []bool{
- c.Telegram.Enabled,
- c.Discord.Enabled,
- c.QQ.Enabled,
- c.MaixCam.Enabled,
- c.WhatsApp.Enabled,
- c.Feishu.Enabled,
- c.DingTalk.Enabled,
- c.Slack.Enabled,
- c.Matrix.Enabled,
- c.LINE.Enabled,
- c.OneBot.Enabled,
- c.WeCom.Enabled,
- c.WeComApp.Enabled,
- }
- total = len(entries)
- for _, v := range entries {
- if v {
- enabled++
- }
- }
- return enabled, total
-}
-
-func refreshMainMenuIfPresent(s *appState) {
- if menu, ok := s.menus["main"]; ok {
- refreshMainMenu(menu, s)
- }
-}
-
-func refreshMainMenu(menu *Menu, s *appState) {
- selectedModel := s.selectedModelName()
- modelReady := selectedModel != ""
- channelReady := s.hasEnabledChannel()
- enabledCount, totalChannels := s.countChannels()
- gatewayRunning := s.gatewayCmd != nil || s.isGatewayRunning()
-
- gatewayLabel := "Start Gateway"
- gatewayDescription := "Launch gateway for channels"
- if gatewayRunning {
- gatewayLabel = "Stop Gateway"
- gatewayDescription = "Gateway running"
- }
-
- items := []MenuItem{
- {
- Label: rootModelLabel(selectedModel),
- Description: rootModelDescription(),
- Action: func() {
- s.push("model", s.modelMenu())
- },
- MainColor: func() *tcell.Color {
- if modelReady {
- return nil
- }
- color := tcell.ColorGray
- return &color
- }(),
- },
- {
- Label: rootChannelLabel(channelReady),
- Description: fmt.Sprintf("%d/%d enabled", enabledCount, totalChannels),
- Action: func() {
- s.push("channel", s.channelMenu())
- },
- MainColor: func() *tcell.Color {
- if channelReady {
- return nil
- }
- color := tcell.ColorGray
- return &color
- }(),
- },
- {
- Label: "Start Talk",
- Description: "Open picoclaw agent in terminal",
- Action: func() {
- s.requestStartTalk()
- },
- Disabled: !modelReady,
- },
- {
- Label: gatewayLabel,
- Description: gatewayDescription,
- Action: func() {
- if gatewayRunning {
- s.stopGateway()
- } else {
- s.requestStartGateway()
- }
- refreshMainMenu(menu, s)
- },
- Disabled: !gatewayRunning && (!modelReady || !channelReady),
- },
- {
- Label: "View Gateway Log",
- Description: "Open gateway.log",
- Action: func() {
- s.viewGatewayLog()
- },
- },
- {
- Label: "Exit",
- Description: "Exit the TUI",
- Action: func() {
- s.requestExit()
- },
- },
- }
- menu.applyItems(items)
-}
-
-func (s *appState) applyChangesValidated() bool {
- if err := s.config.ValidateModelList(); err != nil {
- s.showMessage("Validation failed", err.Error())
- return false
- }
- if err := s.validateAgentModel(); err != nil {
- s.showMessage("Validation failed", err.Error())
- return false
- }
- if err := configstore.Save(s.config); err != nil {
- s.showMessage("Save failed", err.Error())
- return false
- }
- if data, err := os.ReadFile(s.configPath); err == nil {
- s.original = data
- s.hasOriginal = true
- _ = writeBackupConfig(s.backupPath, data)
- }
- return true
-}
-
-func (s *appState) requestExit() {
- if s.dirty {
- s.confirmApplyOrDiscard(func() {
- s.app.Stop()
- }, func() {
- s.discardChanges()
- s.app.Stop()
- })
- return
- }
- s.app.Stop()
-}
-
-func (s *appState) requestStartTalk() {
- if s.dirty {
- s.confirmApplyOrDiscard(func() {
- s.startTalk()
- }, func() {
- s.startTalk()
- })
- return
- }
- s.startTalk()
-}
-
-func (s *appState) requestStartGateway() {
- if s.dirty {
- s.confirmApplyOrDiscard(func() {
- s.startGateway()
- }, func() {
- s.startGateway()
- })
- return
- }
- s.startGateway()
-}
-
-func (s *appState) viewGatewayLog() {
- data, err := os.ReadFile(s.logPath)
- if err != nil {
- s.showMessage("Log not found", "gateway.log not found")
- return
- }
- text := tview.NewTextView()
- text.SetBorder(true).SetTitle("Gateway Log")
- text.SetText(string(data))
- text.SetDoneFunc(func(key tcell.Key) {
- s.pages.RemovePage("log")
- })
- text.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
- if event.Key() == tcell.KeyEsc {
- s.pages.RemovePage("log")
- return nil
- }
- return event
- })
- s.pages.AddPage("log", text, true, true)
-}
-
-func (s *appState) selectedModelName() string {
- modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
- if modelName == "" {
- return ""
- }
- if !s.isActiveModelValid() {
- return ""
- }
- return modelName
-}
-
-func rootModelLabel(selected string) string {
- if selected == "" {
- return "Model (None)"
- }
- return "Model (" + selected + ")"
-}
-
-func rootModelDescription() string {
- return "Using SPACE to choose your model"
-}
-
-func rootChannelLabel(valid bool) string {
- if !valid {
- return "Channel (no channel enabled)"
- }
- return "Channel"
-}
-
-func (s *appState) startTalk() {
- if !s.isActiveModelValid() {
- s.showMessage("Model required", "Select a valid model before starting talk")
- return
- }
- if !s.applyChangesValidated() {
- return
- }
- s.app.Suspend(func() {
- cmd := exec.Command("picoclaw", "agent")
- cmd.Stdin = os.Stdin
- cmd.Stdout = os.Stdout
- cmd.Stderr = os.Stderr
- _ = cmd.Run()
- })
-}
-
-func (s *appState) startGateway() {
- if !s.isActiveModelValid() {
- s.showMessage("Model required", "Select a valid model before starting gateway")
- return
- }
- if !s.hasEnabledChannel() {
- s.showMessage("Channel required", "Enable at least one channel before starting gateway")
- return
- }
- if !s.applyChangesValidated() {
- return
- }
- _ = stopGatewayProcess()
- cmd := exec.Command("picoclaw", "gateway")
- logFile, err := os.OpenFile(s.logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
- if err != nil {
- s.showMessage("Gateway failed", err.Error())
- return
- }
- cmd.Stdout = logFile
- cmd.Stderr = logFile
- if err := cmd.Start(); err != nil {
- s.showMessage("Gateway failed", err.Error())
- _ = logFile.Close()
- return
- }
- _ = logFile.Close()
- s.gatewayCmd = cmd
-}
-
-func (s *appState) stopGateway() {
- _ = stopGatewayProcess()
- if s.gatewayCmd != nil && s.gatewayCmd.Process != nil {
- _ = s.gatewayCmd.Process.Kill()
- }
- s.gatewayCmd = nil
-}
-
-func (s *appState) isGatewayRunning() bool {
- return isGatewayProcessRunning()
-}
-
-func (s *appState) validateAgentModel() error {
- modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
- if modelName == "" {
- return nil
- }
- _, err := s.config.GetModelConfig(modelName)
- return err
-}
-
-func (s *appState) isActiveModelValid() bool {
- modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
- if modelName == "" {
- return false
- }
- cfg, err := s.config.GetModelConfig(modelName)
- if err != nil {
- return false
- }
- hasKey := strings.TrimSpace(cfg.APIKey) != "" || strings.TrimSpace(cfg.AuthMethod) == "oauth"
- hasModel := strings.TrimSpace(cfg.Model) != ""
- return hasKey && hasModel
-}
-
-func (s *appState) hasEnabledChannel() bool {
- c := s.config.Channels
- return c.Telegram.Enabled || c.Discord.Enabled || c.QQ.Enabled || c.MaixCam.Enabled ||
- c.WhatsApp.Enabled || c.Feishu.Enabled || c.DingTalk.Enabled || c.Slack.Enabled ||
- c.Matrix.Enabled || c.LINE.Enabled || c.OneBot.Enabled || c.WeCom.Enabled || c.WeComApp.Enabled
-}
-
-func (s *appState) confirmApplyOrDiscard(onApply func(), onDiscard func()) {
- if s.pages.HasPage("apply") {
- return
- }
- modal := tview.NewModal().
- SetText("Apply changes or discard before continuing?").
- AddButtons([]string{"Cancel", "Discard", "Apply"}).
- SetDoneFunc(func(buttonIndex int, buttonLabel string) {
- s.pages.RemovePage("apply")
- switch buttonLabel {
- case "Discard":
- s.discardChanges()
- if onDiscard != nil {
- onDiscard()
- }
- case "Apply":
- if s.applyChangesValidated() {
- s.dirty = false
- if onApply != nil {
- onApply()
- }
- }
- }
- })
- modal.SetBorder(true)
- s.pages.AddPage("apply", modal, true, true)
-}
-
-func (s *appState) discardChanges() {
- if s.hasOriginal {
- _ = writeOriginalConfig(s.configPath, s.original)
- } else {
- _ = os.Remove(s.configPath)
- }
- _ = os.Remove(s.backupPath)
- if cfg, err := configstore.Load(); err == nil && cfg != nil {
- s.config = cfg
- }
- s.dirty = false
- refreshMainMenuIfPresent(s)
-}
-
-func (s *appState) showMessage(title, message string) {
- if s.pages.HasPage("message") {
- return
- }
- modal := tview.NewModal().
- SetText(strings.TrimSpace(message)).
- AddButtons([]string{"OK"}).
- SetDoneFunc(func(_ int, _ string) {
- s.pages.RemovePage("message")
- })
- modal.SetTitle(title).SetBorder(true)
- modal.SetBackgroundColor(tview.Styles.ContrastBackgroundColor)
- modal.SetTextColor(tview.Styles.PrimaryTextColor)
- modal.SetButtonBackgroundColor(tcell.NewRGBColor(112, 102, 255))
- modal.SetButtonTextColor(tview.Styles.PrimaryTextColor)
- s.pages.AddPage("message", modal, true, true)
-}
-
-func loadOriginalConfig(path string) ([]byte, bool) {
- data, err := os.ReadFile(path)
- if err != nil {
- if os.IsNotExist(err) {
- return nil, false
- }
- return nil, false
- }
- return data, true
-}
-
-func writeOriginalConfig(path string, data []byte) error {
- return os.WriteFile(path, data, 0o600)
-}
-
-func writeBackupConfig(path string, data []byte) error {
- return os.WriteFile(path, data, 0o600)
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/channel.go b/cmd/picoclaw-launcher-tui/internal/ui/channel.go
deleted file mode 100644
index 2f28af123..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/channel.go
+++ /dev/null
@@ -1,433 +0,0 @@
-package ui
-
-import (
- "fmt"
- "strings"
-
- "github.com/gdamore/tcell/v2"
- "github.com/rivo/tview"
-
- picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
-)
-
-func (s *appState) buildChannelMenuItems() []MenuItem {
- return []MenuItem{
- channelItem(
- "Telegram",
- "Telegram bot settings",
- s.config.Channels.Telegram.Enabled,
- func() { s.push("channel-telegram", s.telegramForm()) },
- ),
- channelItem(
- "Discord",
- "Discord bot settings",
- s.config.Channels.Discord.Enabled,
- func() { s.push("channel-discord", s.discordForm()) },
- ),
- channelItem(
- "QQ",
- "QQ bot settings",
- s.config.Channels.QQ.Enabled,
- func() { s.push("channel-qq", s.qqForm()) },
- ),
- channelItem(
- "MaixCam",
- "MaixCam gateway",
- s.config.Channels.MaixCam.Enabled,
- func() { s.push("channel-maixcam", s.maixcamForm()) },
- ),
- channelItem(
- "WhatsApp",
- "WhatsApp bridge",
- s.config.Channels.WhatsApp.Enabled,
- func() { s.push("channel-whatsapp", s.whatsappForm()) },
- ),
- channelItem(
- "Feishu",
- "Feishu bot settings",
- s.config.Channels.Feishu.Enabled,
- func() { s.push("channel-feishu", s.feishuForm()) },
- ),
- channelItem(
- "DingTalk",
- "DingTalk bot settings",
- s.config.Channels.DingTalk.Enabled,
- func() { s.push("channel-dingtalk", s.dingtalkForm()) },
- ),
- channelItem(
- "Slack",
- "Slack bot settings",
- s.config.Channels.Slack.Enabled,
- func() { s.push("channel-slack", s.slackForm()) },
- ),
- channelItem(
- "Matrix",
- "Matrix bot settings",
- s.config.Channels.Matrix.Enabled,
- func() { s.push("channel-matrix", s.matrixForm()) },
- ),
- channelItem(
- "LINE",
- "LINE bot settings",
- s.config.Channels.LINE.Enabled,
- func() { s.push("channel-line", s.lineForm()) },
- ),
- channelItem(
- "OneBot",
- "OneBot settings",
- s.config.Channels.OneBot.Enabled,
- func() { s.push("channel-onebot", s.onebotForm()) },
- ),
- channelItem(
- "WeCom",
- "WeCom bot settings",
- s.config.Channels.WeCom.Enabled,
- func() { s.push("channel-wecom", s.wecomForm()) },
- ),
- channelItem(
- "WeCom App",
- "WeCom App settings",
- s.config.Channels.WeComApp.Enabled,
- func() { s.push("channel-wecomapp", s.wecomAppForm()) },
- ),
- }
-}
-
-func (s *appState) channelMenu() tview.Primitive {
- menu := NewMenu("Channels", s.buildChannelMenuItems())
- menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
- if event.Key() == tcell.KeyEsc {
- s.pop()
- return nil
- }
- return event
- })
- return menu
-}
-
-func refreshChannelMenuFromState(menu *Menu, s *appState) {
- menu.applyItems(s.buildChannelMenuItems())
-}
-
-func (s *appState) telegramForm() tview.Primitive {
- cfg := &s.config.Channels.Telegram
- form := baseChannelForm("Telegram", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
- cfg.Token = strings.TrimSpace(text)
- })
- form.AddInputField("Proxy", cfg.Proxy, 128, nil, func(text string) {
- cfg.Proxy = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) discordForm() tview.Primitive {
- cfg := &s.config.Channels.Discord
- form := baseChannelForm("Discord", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
- cfg.Token = strings.TrimSpace(text)
- })
- form.AddCheckbox("Mention Only", cfg.MentionOnly, func(checked bool) {
- cfg.MentionOnly = checked
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) qqForm() tview.Primitive {
- cfg := &s.config.Channels.QQ
- form := baseChannelForm("QQ", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("App ID", cfg.AppID, 64, nil, func(text string) {
- cfg.AppID = strings.TrimSpace(text)
- })
- form.AddInputField("App Secret", cfg.AppSecret, 128, nil, func(text string) {
- cfg.AppSecret = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) maixcamForm() tview.Primitive {
- cfg := &s.config.Channels.MaixCam
- form := baseChannelForm("MaixCam", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Host", cfg.Host, 64, nil, func(text string) {
- cfg.Host = strings.TrimSpace(text)
- })
- addIntField(form, "Port", cfg.Port, func(value int) { cfg.Port = value })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) whatsappForm() tview.Primitive {
- cfg := &s.config.Channels.WhatsApp
- form := baseChannelForm("WhatsApp", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Bridge URL", cfg.BridgeURL, 128, nil, func(text string) {
- cfg.BridgeURL = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) feishuForm() tview.Primitive {
- cfg := &s.config.Channels.Feishu
- form := baseChannelForm("Feishu", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("App ID", cfg.AppID, 64, nil, func(text string) {
- cfg.AppID = strings.TrimSpace(text)
- })
- form.AddInputField("App Secret", cfg.AppSecret, 128, nil, func(text string) {
- cfg.AppSecret = strings.TrimSpace(text)
- })
- form.AddInputField("Encrypt Key", cfg.EncryptKey, 128, nil, func(text string) {
- cfg.EncryptKey = strings.TrimSpace(text)
- })
- form.AddInputField("Verification Token", cfg.VerificationToken, 128, nil, func(text string) {
- cfg.VerificationToken = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) dingtalkForm() tview.Primitive {
- cfg := &s.config.Channels.DingTalk
- form := baseChannelForm("DingTalk", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Client ID", cfg.ClientID, 64, nil, func(text string) {
- cfg.ClientID = strings.TrimSpace(text)
- })
- form.AddInputField("Client Secret", cfg.ClientSecret, 128, nil, func(text string) {
- cfg.ClientSecret = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) slackForm() tview.Primitive {
- cfg := &s.config.Channels.Slack
- form := baseChannelForm("Slack", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Bot Token", cfg.BotToken, 128, nil, func(text string) {
- cfg.BotToken = strings.TrimSpace(text)
- })
- form.AddInputField("App Token", cfg.AppToken, 128, nil, func(text string) {
- cfg.AppToken = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) lineForm() tview.Primitive {
- cfg := &s.config.Channels.LINE
- form := baseChannelForm("LINE", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Channel Secret", cfg.ChannelSecret, 128, nil, func(text string) {
- cfg.ChannelSecret = strings.TrimSpace(text)
- })
- form.AddInputField("Channel Access Token", cfg.ChannelAccessToken, 128, nil, func(text string) {
- cfg.ChannelAccessToken = strings.TrimSpace(text)
- })
- form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
- cfg.WebhookHost = strings.TrimSpace(text)
- })
- addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
- form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
- cfg.WebhookPath = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) matrixForm() tview.Primitive {
- cfg := &s.config.Channels.Matrix
- form := baseChannelForm("Matrix", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Homeserver", cfg.Homeserver, 128, nil, func(text string) {
- cfg.Homeserver = strings.TrimSpace(text)
- })
- form.AddInputField("User ID", cfg.UserID, 128, nil, func(text string) {
- cfg.UserID = strings.TrimSpace(text)
- })
- form.AddInputField("Access Token", cfg.AccessToken, 128, nil, func(text string) {
- cfg.AccessToken = strings.TrimSpace(text)
- })
- form.AddInputField("Device ID", cfg.DeviceID, 128, nil, func(text string) {
- cfg.DeviceID = strings.TrimSpace(text)
- })
- form.AddCheckbox("Join On Invite", cfg.JoinOnInvite, func(checked bool) {
- cfg.JoinOnInvite = checked
- })
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) onebotForm() tview.Primitive {
- cfg := &s.config.Channels.OneBot
- form := baseChannelForm("OneBot", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("WS URL", cfg.WSUrl, 128, nil, func(text string) {
- cfg.WSUrl = strings.TrimSpace(text)
- })
- form.AddInputField("Access Token", cfg.AccessToken, 128, nil, func(text string) {
- cfg.AccessToken = strings.TrimSpace(text)
- })
- addIntField(
- form,
- "Reconnect Interval",
- cfg.ReconnectInterval,
- func(value int) { cfg.ReconnectInterval = value },
- )
- form.AddInputField(
- "Group Trigger Prefix",
- strings.Join(cfg.GroupTriggerPrefix, ","),
- 128,
- nil,
- func(text string) {
- cfg.GroupTriggerPrefix = splitCSV(text)
- },
- )
- addAllowFromField(form, &cfg.AllowFrom)
- return wrapWithBack(form, s)
-}
-
-func (s *appState) wecomForm() tview.Primitive {
- cfg := &s.config.Channels.WeCom
- form := baseChannelForm("WeCom", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
- cfg.Token = strings.TrimSpace(text)
- })
- form.AddInputField("Encoding AES Key", cfg.EncodingAESKey, 128, nil, func(text string) {
- cfg.EncodingAESKey = strings.TrimSpace(text)
- })
- form.AddInputField("Webhook URL", cfg.WebhookURL, 128, nil, func(text string) {
- cfg.WebhookURL = strings.TrimSpace(text)
- })
- form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
- cfg.WebhookHost = strings.TrimSpace(text)
- })
- addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
- form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
- cfg.WebhookPath = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- addIntField(
- form,
- "Reply Timeout",
- cfg.ReplyTimeout,
- func(value int) { cfg.ReplyTimeout = value },
- )
- return wrapWithBack(form, s)
-}
-
-func (s *appState) wecomAppForm() tview.Primitive {
- cfg := &s.config.Channels.WeComApp
- form := baseChannelForm("WeCom App", cfg.Enabled, s.makeChannelOnEnabled(&cfg.Enabled))
- form.AddInputField("Corp ID", cfg.CorpID, 64, nil, func(text string) {
- cfg.CorpID = strings.TrimSpace(text)
- })
- form.AddInputField("Corp Secret", cfg.CorpSecret, 128, nil, func(text string) {
- cfg.CorpSecret = strings.TrimSpace(text)
- })
- addInt64Field(form, "Agent ID", cfg.AgentID, func(value int64) { cfg.AgentID = value })
- form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
- cfg.Token = strings.TrimSpace(text)
- })
- form.AddInputField("Encoding AES Key", cfg.EncodingAESKey, 128, nil, func(text string) {
- cfg.EncodingAESKey = strings.TrimSpace(text)
- })
- form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
- cfg.WebhookHost = strings.TrimSpace(text)
- })
- addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
- form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
- cfg.WebhookPath = strings.TrimSpace(text)
- })
- addAllowFromField(form, &cfg.AllowFrom)
- addIntField(
- form,
- "Reply Timeout",
- cfg.ReplyTimeout,
- func(value int) { cfg.ReplyTimeout = value },
- )
- return wrapWithBack(form, s)
-}
-
-func (s *appState) makeChannelOnEnabled(enabledPtr *bool) func(bool) {
- return func(v bool) {
- *enabledPtr = v
- s.dirty = true
- refreshMainMenuIfPresent(s)
- if menu, ok := s.menus["channel"]; ok {
- refreshChannelMenuFromState(menu, s)
- }
- }
-}
-
-func addAllowFromField(form *tview.Form, allowFrom *picoclawconfig.FlexibleStringSlice) {
- form.AddInputField("Allow From", strings.Join(*allowFrom, ","), 128, nil, func(text string) {
- *allowFrom = splitCSV(text)
- })
-}
-
-func baseChannelForm(title string, enabled bool, onEnabled func(bool)) *tview.Form {
- form := tview.NewForm()
- form.SetBorder(true).SetTitle(fmt.Sprintf("Channel: %s", title))
- form.SetButtonBackgroundColor(tcell.NewRGBColor(80, 250, 123))
- form.SetButtonTextColor(tcell.NewRGBColor(12, 13, 22))
- form.AddCheckbox("Enabled", enabled, func(checked bool) {
- onEnabled(checked)
- })
- return form
-}
-
-func wrapWithBack(form *tview.Form, s *appState) tview.Primitive {
- form.AddButton("Back", func() {
- s.pop()
- })
- form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
- if event.Key() == tcell.KeyEsc {
- s.pop()
- return nil
- }
- return event
- })
- return form
-}
-
-func splitCSV(input string) picoclawconfig.FlexibleStringSlice {
- parts := strings.Split(strings.TrimSpace(input), ",")
- cleaned := make([]string, 0, len(parts))
- for _, part := range parts {
- value := strings.TrimSpace(part)
- if value == "" {
- continue
- }
- cleaned = append(cleaned, value)
- }
- return cleaned
-}
-
-func addIntField(form *tview.Form, label string, value int, onChange func(int)) {
- form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
- var parsed int
- if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
- onChange(parsed)
- }
- })
-}
-
-func addInt64Field(form *tview.Form, label string, value int64, onChange func(int64)) {
- form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
- var parsed int64
- if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
- onChange(parsed)
- }
- })
-}
-
-func channelItem(label, description string, enabled bool, action MenuAction) MenuItem {
- item := MenuItem{
- Label: label,
- Description: description,
- Action: action,
- }
- if !enabled {
- color := tcell.ColorGray
- item.MainColor = &color
- }
- return item
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/gateway_posix.go b/cmd/picoclaw-launcher-tui/internal/ui/gateway_posix.go
deleted file mode 100644
index bc874f7f2..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/gateway_posix.go
+++ /dev/null
@@ -1,16 +0,0 @@
-//go:build !windows
-// +build !windows
-
-package ui
-
-import "os/exec"
-
-func isGatewayProcessRunning() bool {
- cmd := exec.Command("sh", "-c", "pgrep -f 'picoclaw\\s+gateway' >/dev/null 2>&1")
- return cmd.Run() == nil
-}
-
-func stopGatewayProcess() error {
- cmd := exec.Command("sh", "-c", "pkill -f 'picoclaw\\s+gateway' >/dev/null 2>&1")
- return cmd.Run()
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/gateway_windows.go b/cmd/picoclaw-launcher-tui/internal/ui/gateway_windows.go
deleted file mode 100644
index 7067a5c13..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/gateway_windows.go
+++ /dev/null
@@ -1,16 +0,0 @@
-//go:build windows
-// +build windows
-
-package ui
-
-import "os/exec"
-
-func isGatewayProcessRunning() bool {
- cmd := exec.Command("tasklist", "/FI", "IMAGENAME eq picoclaw.exe")
- return cmd.Run() == nil
-}
-
-func stopGatewayProcess() error {
- cmd := exec.Command("taskkill", "/F", "/IM", "picoclaw.exe")
- return cmd.Run()
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/menu.go b/cmd/picoclaw-launcher-tui/internal/ui/menu.go
deleted file mode 100644
index 9f2132c5a..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/menu.go
+++ /dev/null
@@ -1,72 +0,0 @@
-package ui
-
-import (
- "github.com/gdamore/tcell/v2"
- "github.com/rivo/tview"
-)
-
-type MenuAction func()
-
-type MenuItem struct {
- Label string
- Description string
- Action MenuAction
- Disabled bool
- MainColor *tcell.Color
- DescColor *tcell.Color
-}
-
-type Menu struct {
- *tview.Table
- items []MenuItem
-}
-
-func NewMenu(title string, items []MenuItem) *Menu {
- table := tview.NewTable().SetSelectable(true, false)
- table.SetBorder(true).SetTitle(title)
- table.SetBorders(false)
- menu := &Menu{Table: table, items: items}
- menu.applyItems(items)
- menu.SetSelectedFunc(func(row, _ int) {
- if row < 0 || row >= len(menu.items) {
- return
- }
- item := menu.items[row]
- if item.Disabled || item.Action == nil {
- return
- }
- item.Action()
- })
- menu.SetSelectedStyle(
- tcell.StyleDefault.Foreground(tview.Styles.InverseTextColor).
- Background(tcell.NewRGBColor(189, 147, 249)),
- )
- return menu
-}
-
-func (m *Menu) applyItems(items []MenuItem) {
- m.items = items
- m.Clear()
- for row, item := range items {
- label := item.Label
- if item.Disabled && label != "" {
- label = label + " (disabled)"
- }
- left := tview.NewTableCell(label)
- right := tview.NewTableCell(item.Description).SetAlign(tview.AlignRight)
- if item.MainColor != nil {
- left.SetTextColor(*item.MainColor)
- }
- if item.DescColor != nil {
- right.SetTextColor(*item.DescColor)
- } else {
- right.SetTextColor(tview.Styles.TertiaryTextColor)
- }
- if item.Disabled {
- left.SetTextColor(tcell.ColorGray)
- right.SetTextColor(tcell.ColorGray)
- }
- m.SetCell(row, 0, left)
- m.SetCell(row, 1, right)
- }
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/model.go b/cmd/picoclaw-launcher-tui/internal/ui/model.go
deleted file mode 100644
index 698502058..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/model.go
+++ /dev/null
@@ -1,399 +0,0 @@
-package ui
-
-import (
- "fmt"
- "io"
- "net/http"
- "strings"
- "time"
-
- "github.com/gdamore/tcell/v2"
- "github.com/rivo/tview"
-
- picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
-)
-
-func (s *appState) modelMenu() tview.Primitive {
- items := make([]MenuItem, 0, 1+len(s.config.ModelList))
- currentModel := strings.TrimSpace(s.config.Agents.Defaults.Model)
- for i := range s.config.ModelList {
- index := i
- model := s.config.ModelList[i]
- isValid := isModelValid(model)
- desc := model.APIBase
- if desc == "" {
- desc = model.AuthMethod
- }
- if desc == "" {
- desc = "api_key required"
- }
- label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
- if model.ModelName == currentModel && currentModel != "" {
- label = "* " + label
- }
- isSelected := model.ModelName == currentModel && currentModel != ""
- items = append(items, MenuItem{
- Label: label,
- Description: desc,
- MainColor: modelStatusColor(isValid, isSelected),
- Action: func() {
- s.push(fmt.Sprintf("model-%d", index), s.modelForm(index))
- },
- })
- }
- // Add model entry appended at the end so the models map to rows 1..N
- items = append(items,
- MenuItem{
- Label: "**Add model**",
- Description: "Append a new model entry",
- Action: func() {
- newName := s.nextAvailableModelName("new-model")
- s.addModel(
- picoclawconfig.ModelConfig{ModelName: newName, Model: "openai/gpt-5.4"},
- )
- s.push(
- fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
- s.modelForm(len(s.config.ModelList)-1),
- )
- },
- },
- )
-
- menu := NewMenu("Models", items)
- menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
- if event.Key() == tcell.KeyEsc {
- s.pop()
- return nil
- }
-
- if event.Rune() == ' ' {
- row, _ := menu.GetSelection()
- if row >= 0 && row < len(s.config.ModelList) {
- model := s.config.ModelList[row]
- if !isModelValid(model) {
- s.showMessage(
- "Invalid model",
- "Select a model with api_key or oauth auth_method",
- )
- return nil
- }
- s.config.Agents.Defaults.Model = model.ModelName
- s.dirty = true
- refreshModelMenu(menu, s.config.Agents.Defaults.Model, s.config.ModelList)
- refreshMainMenuIfPresent(s)
- }
- return nil
- }
- return event
- })
- return menu
-}
-
-func (s *appState) modelForm(index int) tview.Primitive {
- model := &s.config.ModelList[index]
- form := tview.NewForm()
- form.SetBorder(true).SetTitle(fmt.Sprintf("Model: %s", model.ModelName))
-
- addInput(form, "Model Name", model.ModelName, func(value string) {
- if value == "" {
- s.showMessage("Invalid model name", "Model Name cannot be empty")
- return
- }
- if s.modelNameExists(value, index) {
- s.showMessage("Duplicate model name", fmt.Sprintf("Model Name '%s' already exists", value))
- return
- }
- oldName := model.ModelName
- model.ModelName = value
- if s.config.Agents.Defaults.Model == oldName {
- s.config.Agents.Defaults.Model = value
- }
- s.dirty = true
- form.SetTitle(fmt.Sprintf("Model: %s", model.ModelName))
- refreshMainMenuIfPresent(s)
- if menu, ok := s.menus["model"]; ok {
- refreshModelMenuFromState(menu, s)
- }
- })
- addInput(form, "Model", model.Model, func(value string) {
- model.Model = value
- s.dirty = true
- refreshMainMenuIfPresent(s)
- if menu, ok := s.menus["model"]; ok {
- refreshModelMenuFromState(menu, s)
- }
- })
- addInput(form, "API Base", model.APIBase, func(value string) {
- model.APIBase = value
- s.dirty = true
- refreshMainMenuIfPresent(s)
- if menu, ok := s.menus["model"]; ok {
- refreshModelMenuFromState(menu, s)
- }
- })
- addInput(form, "API Key", model.APIKey, func(value string) {
- model.APIKey = value
- s.dirty = true
- refreshMainMenuIfPresent(s)
- if menu, ok := s.menus["model"]; ok {
- refreshModelMenuFromState(menu, s)
- }
- })
- addInput(form, "Proxy", model.Proxy, func(value string) {
- model.Proxy = value
- })
- addInput(form, "Auth Method", model.AuthMethod, func(value string) {
- model.AuthMethod = value
- s.dirty = true
- refreshMainMenuIfPresent(s)
- if menu, ok := s.menus["model"]; ok {
- refreshModelMenuFromState(menu, s)
- }
- })
- addInput(form, "Connect Mode", model.ConnectMode, func(value string) {
- model.ConnectMode = value
- })
- addInput(form, "Workspace", model.Workspace, func(value string) {
- model.Workspace = value
- })
- addInput(form, "Max Tokens Field", model.MaxTokensField, func(value string) {
- model.MaxTokensField = value
- })
- addIntInput(form, "RPM", model.RPM, func(value int) {
- model.RPM = value
- })
- addIntInput(form, "Request Timeout", model.RequestTimeout, func(value int) {
- model.RequestTimeout = value
- })
-
- form.AddButton("Delete", func() {
- pageName := "confirm-delete-model"
- if s.pages.HasPage(pageName) {
- return
- }
- modal := tview.NewModal().
- SetText("Are you sure you want to delete this model?").
- AddButtons([]string{"Cancel", "Delete"}).
- SetDoneFunc(func(buttonIndex int, buttonLabel string) {
- s.pages.RemovePage(pageName)
- if buttonLabel == "Delete" {
- s.deleteModel(index)
- }
- })
- modal.SetTitle("Confirm Delete").SetBorder(true)
- s.pages.AddPage(pageName, modal, true, true)
- })
- form.AddButton("Test", func() {
- s.testModel(model)
- })
- form.AddButton("Back", func() {
- s.pop()
- })
-
- form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
- if event.Key() == tcell.KeyEsc {
- s.pop()
- return nil
- }
- return event
- })
- return form
-}
-
-func addInput(form *tview.Form, label, value string, onChange func(string)) {
- form.AddInputField(label, value, 128, nil, func(text string) {
- onChange(strings.TrimSpace(text))
- })
-}
-
-func addIntInput(form *tview.Form, label string, value int, onChange func(int)) {
- form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
- var parsed int
- if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
- onChange(parsed)
- }
- })
-}
-
-func (s *appState) addModel(model picoclawconfig.ModelConfig) {
- s.config.ModelList = append(s.config.ModelList, model)
-}
-
-func (s *appState) deleteModel(index int) {
- if index < 0 || index >= len(s.config.ModelList) {
- return
- }
- s.config.ModelList = append(s.config.ModelList[:index], s.config.ModelList[index+1:]...)
- s.pop()
-}
-
-func modelStatusColor(valid bool, selected bool) *tcell.Color {
- if valid {
- color := tview.Styles.PrimaryTextColor
- return &color
- }
- color := tcell.ColorGray
- return &color
-}
-
-func refreshModelMenu(menu *Menu, currentModel string, models []picoclawconfig.ModelConfig) {
- for i, model := range models {
- row := i
- label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
- isValid := isModelValid(model)
- if model.ModelName == currentModel && currentModel != "" {
- label = "* " + label
- }
- cell := menu.GetCell(row, 0)
- if cell != nil {
- cell.SetText(label)
- isSelected := model.ModelName == currentModel && currentModel != ""
- color := modelStatusColor(isValid, isSelected)
- if color != nil {
- cell.SetTextColor(*color)
- }
- }
- }
-}
-
-func refreshModelMenuFromState(menu *Menu, s *appState) {
- items := make([]MenuItem, 0, 1+len(s.config.ModelList))
- currentModel := strings.TrimSpace(s.config.Agents.Defaults.Model)
- for i := range s.config.ModelList {
- index := i
- model := s.config.ModelList[i]
- isValid := isModelValid(model)
- desc := model.APIBase
- if desc == "" {
- desc = model.AuthMethod
- }
- if desc == "" {
- desc = "api_key required"
- }
- label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
- if model.ModelName == currentModel && currentModel != "" {
- label = "* " + label
- }
- isSelected := model.ModelName == currentModel && currentModel != ""
- items = append(items, MenuItem{
- Label: label,
- Description: desc,
- MainColor: modelStatusColor(isValid, isSelected),
- Action: func() {
- s.push(fmt.Sprintf("model-%d", index), s.modelForm(index))
- },
- })
- }
- items = append(items,
- MenuItem{
- Label: "**Add Model**",
- Description: "Append a new model entry",
- Action: func() {
- newName := s.nextAvailableModelName("new-model")
- s.addModel(
- picoclawconfig.ModelConfig{ModelName: newName, Model: "openai/gpt-5.4"},
- )
- s.push(fmt.Sprintf("model-%d", len(s.config.ModelList)-1), s.modelForm(len(s.config.ModelList)-1))
- },
- },
- )
- menu.applyItems(items)
-}
-
-func isModelValid(model picoclawconfig.ModelConfig) bool {
- hasKey := strings.TrimSpace(model.APIKey) != "" ||
- strings.TrimSpace(model.AuthMethod) == "oauth"
- hasModel := strings.TrimSpace(model.Model) != ""
- return hasKey && hasModel
-}
-
-func (s *appState) modelNameExists(name string, excludeIndex int) bool {
- target := strings.TrimSpace(name)
- if target == "" {
- return false
- }
- for i := range s.config.ModelList {
- if i == excludeIndex {
- continue
- }
- if strings.TrimSpace(s.config.ModelList[i].ModelName) == target {
- return true
- }
- }
- return false
-}
-
-func (s *appState) nextAvailableModelName(base string) string {
- name := strings.TrimSpace(base)
- if name == "" {
- name = "new-model"
- }
- if !s.modelNameExists(name, -1) {
- return name
- }
- for i := 2; ; i++ {
- candidate := fmt.Sprintf("%s-%d", name, i)
- if !s.modelNameExists(candidate, -1) {
- return candidate
- }
- }
-}
-
-func (s *appState) testModel(model *picoclawconfig.ModelConfig) {
- if model == nil {
- return
- }
- if strings.TrimSpace(model.APIKey) == "" {
- s.showMessage("Missing API Key", "Set api_key before testing")
- return
- }
- base := strings.TrimSpace(model.APIBase)
- if base == "" {
- s.showMessage("Missing API Base", "Set api_base before testing")
- return
- }
- modelID := strings.TrimSpace(model.Model)
- if modelID == "" {
- s.showMessage("Missing Model", "Set model before testing")
- return
- }
- if !strings.HasPrefix(modelID, "openai/") {
- s.showMessage("Unsupported model", "Only openai/* models are supported for test")
- return
- }
- modelName := strings.TrimPrefix(modelID, "openai/")
- endpoint := strings.TrimRight(base, "/") + "/chat/completions"
-
- payload := fmt.Sprintf(
- `{"model":"%s","messages":[{"role":"user","content":"ping"}],"max_tokens":1}`,
- modelName,
- )
- client := &http.Client{Timeout: 10 * time.Second}
- request, err := http.NewRequest("POST", endpoint, strings.NewReader(payload))
- if err != nil {
- s.showMessage("Test failed", err.Error())
- return
- }
- request.Header.Set("Content-Type", "application/json")
- request.Header.Set("Authorization", "Bearer "+strings.TrimSpace(model.APIKey))
-
- resp, err := client.Do(request)
- if err != nil {
- s.showMessage("Test failed", err.Error())
- return
- }
- defer resp.Body.Close()
- if resp.StatusCode >= 200 && resp.StatusCode < 300 {
- s.showMessage("Test OK", resp.Status)
- return
- }
- body, err := io.ReadAll(io.LimitReader(resp.Body, 2048))
- if err != nil {
- s.showMessage("Test failed", fmt.Sprintf("failed to read response: %v", err))
- return
- }
- s.showMessage(
- "Test failed",
- fmt.Sprintf("%s: %s", resp.Status, strings.TrimSpace(string(body))),
- )
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/style.go b/cmd/picoclaw-launcher-tui/internal/ui/style.go
deleted file mode 100644
index da3c3526d..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/style.go
+++ /dev/null
@@ -1,55 +0,0 @@
-package ui
-
-import (
- "github.com/gdamore/tcell/v2"
- "github.com/rivo/tview"
-)
-
-const (
- colorBlue = "[#3e5db9]"
- colorRed = "[#d54646]"
- banner = "\r\n[::b]" +
- colorBlue + "██████╗ ██╗ ██████╗ ██████╗ " + colorRed + " ██████╗██╗ █████╗ ██╗ ██╗\n" +
- colorBlue + "██╔══██╗██║██╔════╝██╔═══██╗" + colorRed + "██╔════╝██║ ██╔══██╗██║ ██║\n" +
- colorBlue + "██████╔╝██║██║ ██║ ██║" + colorRed + "██║ ██║ ███████║██║ █╗ ██║\n" +
- colorBlue + "██╔═══╝ ██║██║ ██║ ██║" + colorRed + "██║ ██║ ██╔══██║██║███╗██║\n" +
- colorBlue + "██║ ██║╚██████╗╚██████╔╝" + colorRed + "╚██████╗███████╗██║ ██║╚███╔███╔╝\n" +
- colorBlue + "╚═╝ ╚═╝ ╚═════╝ ╚═════╝ " + colorRed + " ╚═════╝╚══════╝╚═╝ ╚═╝ ╚══╝╚══╝\n " +
- "[:]"
-)
-
-func applyStyles() {
- tview.Styles.PrimitiveBackgroundColor = tcell.NewRGBColor(12, 13, 22)
- tview.Styles.ContrastBackgroundColor = tcell.NewRGBColor(34, 19, 53)
- tview.Styles.MoreContrastBackgroundColor = tcell.NewRGBColor(18, 18, 32)
- tview.Styles.BorderColor = tcell.NewRGBColor(112, 102, 255)
- tview.Styles.TitleColor = tcell.NewRGBColor(255, 121, 198)
- tview.Styles.GraphicsColor = tcell.NewRGBColor(139, 233, 253)
- tview.Styles.PrimaryTextColor = tcell.NewRGBColor(241, 250, 255)
- tview.Styles.SecondaryTextColor = tcell.NewRGBColor(80, 250, 123)
- tview.Styles.TertiaryTextColor = tcell.NewRGBColor(139, 233, 253)
- tview.Styles.InverseTextColor = tcell.NewRGBColor(12, 13, 22)
- tview.Styles.ContrastSecondaryTextColor = tcell.NewRGBColor(189, 147, 249)
-}
-
-func bannerView() *tview.TextView {
- text := tview.NewTextView()
- text.SetDynamicColors(true)
- text.SetTextAlign(tview.AlignCenter)
- text.SetBackgroundColor(tview.Styles.PrimitiveBackgroundColor)
- text.SetText(banner)
- text.SetBorder(false)
- return text
-}
-
-const footerText = "Esc: Back/Exit | Enter: Enter | ←↓↑→ : Move | Space: Select | Tab/Shift+Tab: Switch"
-
-func footerView() *tview.TextView {
- text := tview.NewTextView()
- text.SetTextAlign(tview.AlignCenter)
- text.SetText(footerText)
- text.SetBackgroundColor(tview.Styles.MoreContrastBackgroundColor)
- text.SetTextColor(tview.Styles.PrimaryTextColor)
- text.SetBorder(false)
- return text
-}
diff --git a/cmd/picoclaw-launcher-tui/main.go b/cmd/picoclaw-launcher-tui/main.go
index 0e8cce415..3cb7110c1 100644
--- a/cmd/picoclaw-launcher-tui/main.go
+++ b/cmd/picoclaw-launcher-tui/main.go
@@ -1,15 +1,48 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
package main
import (
"fmt"
"os"
+ "os/exec"
+ "path/filepath"
- "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/internal/ui"
+ tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+ "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/ui"
)
func main() {
- if err := ui.Run(); err != nil {
- fmt.Fprintln(os.Stderr, err)
+ configPath := tuicfg.DefaultConfigPath()
+ if len(os.Args) > 1 {
+ configPath = os.Args[1]
+ }
+
+ configDir := filepath.Dir(configPath)
+ if _, err := os.Stat(configDir); os.IsNotExist(err) {
+ cmd := exec.Command("picoclaw", "onboard")
+ cmd.Stdin = os.Stdin
+ cmd.Stdout = os.Stdout
+ cmd.Stderr = os.Stderr
+ _ = cmd.Run()
+ }
+
+ cfg, err := tuicfg.Load(configPath)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "picoclaw-launcher-tui: %v\n", err)
+ os.Exit(1)
+ }
+
+ app := ui.New(cfg, configPath)
+ // Bind model selection hook to sync to main config
+ app.OnModelSelected = func(scheme tuicfg.Scheme, user tuicfg.User, modelID string) {
+ _ = tuicfg.SyncSelectedModelToMainConfig(scheme, user, modelID)
+ }
+ if err := app.Run(); err != nil {
+ fmt.Fprintf(os.Stderr, "picoclaw-launcher-tui: %v\n", err)
os.Exit(1)
}
}
diff --git a/cmd/picoclaw-launcher-tui/ui/app.go b/cmd/picoclaw-launcher-tui/ui/app.go
new file mode 100644
index 000000000..a65693b01
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/app.go
@@ -0,0 +1,325 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+ "fmt"
+ "sync"
+
+ "github.com/gdamore/tcell/v2"
+ "github.com/rivo/tview"
+
+ tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+)
+
+// App is the root TUI application.
+type App struct {
+ tapp *tview.Application
+ pages *tview.Pages
+ pageStack []string
+ cfg *tuicfg.TUIConfig
+ configPath string
+ pageRefreshFns map[string]func()
+ headerModelTV *tview.TextView
+ modalOpen map[string]bool
+
+ // OnModelSelected is called when a model is selected in the UI.
+ // Can be nil to disable.
+ OnModelSelected func(scheme tuicfg.Scheme, user tuicfg.User, modelID string)
+
+ modelCache map[string][]modelEntry
+ modelCacheMu sync.RWMutex
+ refreshMu sync.Mutex
+}
+
+// cacheKey returns the map key for a (scheme, user) pair.
+func cacheKey(schemeName, userName string) string {
+ return fmt.Sprintf("%s/%s", schemeName, userName)
+}
+
+// cachedModels returns a defensive copy of the cached model list for a user (may be nil).
+func (a *App) cachedModels(schemeName, userName string) []modelEntry {
+ a.modelCacheMu.RLock()
+ defer a.modelCacheMu.RUnlock()
+ entries := a.modelCache[cacheKey(schemeName, userName)]
+ return append([]modelEntry(nil), entries...)
+}
+
+// refreshModelCache fetches models for every user in the config concurrently.
+// Serialized by refreshMu so concurrent calls don't race on the cache map.
+// When all fetches complete it calls onDone via QueueUpdateDraw.
+func (a *App) refreshModelCache(onDone func()) {
+ go func() {
+ a.refreshMu.Lock()
+ defer a.refreshMu.Unlock()
+
+ users := a.cfg.Provider.Users
+ schemes := a.cfg.Provider.Schemes
+
+ schemeURL := make(map[string]string, len(schemes))
+ for _, s := range schemes {
+ schemeURL[s.Name] = s.BaseURL
+ }
+
+ var wg sync.WaitGroup
+ for _, u := range users {
+ baseURL, ok := schemeURL[u.Scheme]
+ if !ok || baseURL == "" {
+ continue
+ }
+ if u.Key == "" {
+ a.modelCacheMu.Lock()
+ if a.modelCache == nil {
+ a.modelCache = make(map[string][]modelEntry)
+ }
+ a.modelCache[cacheKey(u.Scheme, u.Name)] = nil
+ a.modelCacheMu.Unlock()
+ continue
+ }
+ wg.Add(1)
+ bURL := baseURL
+ go func() {
+ defer wg.Done()
+ entries, err := fetchModels(bURL, u.Key)
+ a.modelCacheMu.Lock()
+ if a.modelCache == nil {
+ a.modelCache = make(map[string][]modelEntry)
+ }
+ if err != nil || len(entries) == 0 {
+ a.modelCache[cacheKey(u.Scheme, u.Name)] = nil
+ } else {
+ a.modelCache[cacheKey(u.Scheme, u.Name)] = entries
+ }
+ a.modelCacheMu.Unlock()
+ }()
+ }
+ wg.Wait()
+
+ if onDone != nil {
+ a.tapp.QueueUpdateDraw(onDone)
+ }
+ }()
+}
+
+// New creates and wires up the TUI application.
+func New(cfg *tuicfg.TUIConfig, configPath string) *App {
+ // Cyberpunk Theme Colors
+ // Dark background
+ tview.Styles.PrimitiveBackgroundColor = tcell.NewHexColor(0x050510) // Deep Void
+ tview.Styles.ContrastBackgroundColor = tcell.NewHexColor(0x1a1a2e) // Dark Indigo
+ tview.Styles.MoreContrastBackgroundColor = tcell.NewHexColor(0x2a2a40)
+
+ // Borders and Titles
+ tview.Styles.BorderColor = tcell.NewHexColor(0x00f0ff) // Neon Cyan
+ tview.Styles.TitleColor = tcell.NewHexColor(0x00f0ff) // Neon Cyan
+ tview.Styles.GraphicsColor = tcell.NewHexColor(0xff00ff) // Neon Magenta
+
+ // Text
+ tview.Styles.PrimaryTextColor = tcell.NewHexColor(0xe0e0e0) // Off-white
+ tview.Styles.SecondaryTextColor = tcell.NewHexColor(0x00f0ff) // Neon Cyan
+ tview.Styles.TertiaryTextColor = tcell.NewHexColor(0x39ff14) // Neon Lime
+ tview.Styles.InverseTextColor = tcell.NewHexColor(0x000000) // Black
+ tview.Styles.ContrastSecondaryTextColor = tcell.NewHexColor(0xff00ff) // Neon Magenta
+
+ a := &App{
+ tapp: tview.NewApplication(),
+ pages: tview.NewPages(),
+ pageStack: []string{},
+ cfg: cfg,
+ configPath: configPath,
+ pageRefreshFns: make(map[string]func()),
+ modalOpen: make(map[string]bool),
+ }
+
+ a.tapp.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ if event.Key() == tcell.KeyEscape {
+ if len(a.modalOpen) > 0 {
+ return event
+ }
+ return a.goBack()
+ }
+ return event
+ })
+
+ a.buildPages()
+ return a
+}
+
+// Run starts the TUI event loop.
+func (a *App) Run() error {
+ return a.tapp.SetRoot(a.pages, true).EnableMouse(true).Run()
+}
+
+func (a *App) buildPages() {
+ a.pages.AddPage("home", a.newHomePage(), true, true)
+ a.pageStack = []string{"home"}
+}
+
+func (a *App) navigateTo(name string, page tview.Primitive) {
+ a.pages.RemovePage(name)
+ a.pages.AddPage(name, page, true, false)
+ a.pageStack = append(a.pageStack, name)
+ a.pages.SwitchToPage(name)
+}
+
+func (a *App) goBack() *tcell.EventKey {
+ if len(a.pageStack) <= 1 {
+ return nil
+ }
+ popped := a.pageStack[len(a.pageStack)-1]
+ a.pageStack = a.pageStack[:len(a.pageStack)-1]
+ a.pages.RemovePage(popped)
+ prev := a.pageStack[len(a.pageStack)-1]
+ if fn, ok := a.pageRefreshFns[prev]; ok {
+ fn()
+ }
+ if prev == "home" && a.headerModelTV != nil {
+ a.headerModelTV.SetText(a.cfg.CurrentModelLabel() + " ")
+ }
+ a.pages.SwitchToPage(prev)
+ return nil
+}
+
+func (a *App) showModal(name string, primitive tview.Primitive) {
+ a.modalOpen[name] = true
+ a.pages.AddPage(name, primitive, true, true)
+}
+
+func (a *App) hideModal(name string) {
+ delete(a.modalOpen, name)
+ a.pages.HidePage(name)
+ a.pages.RemovePage(name)
+}
+
+func (a *App) save() {
+ if err := tuicfg.Save(a.configPath, a.cfg); err != nil {
+ a.showError("save failed: " + err.Error())
+ }
+}
+
+func (a *App) showError(msg string) {
+ modal := tview.NewModal().
+ SetText(" [red::b]ERROR[-::-]\n\n" + msg).
+ AddButtons([]string{"OK"}).
+ SetDoneFunc(func(_ int, _ string) {
+ a.hideModal("error")
+ })
+ // Cyberpunk Modal Style
+ modal.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e)) // Deep Indigo
+ modal.SetTextColor(tcell.NewHexColor(0xffffff)) // White
+ modal.SetButtonBackgroundColor(tcell.NewHexColor(0xff2a2a)) // Neon Red
+ modal.SetButtonTextColor(tcell.NewHexColor(0xffffff)) // White
+ a.showModal("error", modal)
+}
+
+func (a *App) confirmDelete(label string, onConfirm func()) {
+ modal := tview.NewModal().
+ SetText(" [red::b]DELETE WARNING[-::-]\n\nDelete " + label + "?\n[gray]This action cannot be undone.[-]").
+ AddButtons([]string{"Delete", "Cancel"}).
+ SetDoneFunc(func(_ int, buttonLabel string) {
+ a.hideModal("confirm-delete")
+ if buttonLabel == "Delete" {
+ onConfirm()
+ }
+ })
+ // Cyberpunk Modal Style
+ modal.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e)) // Deep Indigo
+ modal.SetTextColor(tcell.NewHexColor(0xffffff)) // White
+ modal.SetButtonBackgroundColor(tcell.NewHexColor(0xff2a2a)) // Neon Red for danger
+ modal.SetButtonTextColor(tcell.NewHexColor(0xffffff)) // White
+ a.showModal("confirm-delete", modal)
+}
+
+func centeredForm(form *tview.Form, widthPct, height int) tview.Primitive {
+ return tview.NewFlex().
+ AddItem(tview.NewBox(), 0, 1, false).
+ AddItem(tview.NewFlex().SetDirection(tview.FlexRow).
+ AddItem(tview.NewBox(), 0, 1, false).
+ AddItem(form, height, 1, true).
+ AddItem(tview.NewBox(), 0, 1, false), 0, widthPct, true).
+ AddItem(tview.NewBox(), 0, 1, false)
+}
+
+func hintBar(text string) *tview.TextView {
+ tv := tview.NewTextView().
+ SetText(text).
+ SetDynamicColors(true).
+ SetTextAlign(tview.AlignCenter).
+ SetTextColor(tcell.NewHexColor(0x00f0ff)) // Neon Cyan
+ tv.SetBackgroundColor(tcell.NewHexColor(0x2a2a40)) // Darker Indigo
+ return tv
+}
+
+func (a *App) buildShell(pageID string, content tview.Primitive, hint string) tview.Primitive {
+ var modelTV *tview.TextView
+ if pageID == "home" {
+ if a.headerModelTV == nil {
+ a.headerModelTV = tview.NewTextView()
+ a.headerModelTV.SetTextAlign(tview.AlignRight).
+ SetTextColor(tcell.NewHexColor(0x39ff14)). // Neon Lime
+ SetDynamicColors(true).
+ SetBackgroundColor(tcell.NewHexColor(0x050510))
+ }
+ modelTV = a.headerModelTV
+ modelTV.SetText("MODEL: " + a.cfg.CurrentModelLabel() + " ")
+ } else {
+ modelTV = tview.NewTextView()
+ modelTV.SetBackgroundColor(tcell.NewHexColor(0x050510))
+ }
+
+ headerLeft := tview.NewTextView().
+ SetText(" [#ff00ff::b]///[#00f0ff] PICOCLAW LAUNCHER [#ff00ff]///").
+ SetDynamicColors(true).
+ SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ header := tview.NewFlex().
+ AddItem(headerLeft, 0, 1, false).
+ AddItem(modelTV, 0, 1, false)
+
+ sidebar := tview.NewTextView().
+ SetDynamicColors(true).
+ SetWrap(false)
+ sidebar.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e)) // Deep Indigo
+
+ // Cyberpunk Sidebar Styling
+ activePrefix := "[#39ff14::b]>> " // Neon Lime arrow
+ activeSuffix := "[-]"
+ inactivePrefix := "[#808080] "
+ inactiveSuffix := "[-]"
+
+ sbText := "\n\n" // Top padding
+
+ menuItem := func(id, label string) string {
+ if pageID == id {
+ return activePrefix + label + activeSuffix + "\n\n"
+ }
+ return inactivePrefix + label + inactiveSuffix + "\n\n"
+ }
+
+ sbText += menuItem("home", "HOME")
+ sbText += menuItem("schemes", "SCHEMES")
+ sbText += menuItem("users", "USERS")
+ sbText += menuItem("models", "MODELS")
+ sbText += menuItem("channels", "CHANNELS")
+ sbText += menuItem("gateway", "GATEWAY")
+
+ sidebar.SetText(sbText)
+
+ footer := hintBar(hint)
+
+ grid := tview.NewGrid().
+ SetRows(1, 0, 1).
+ SetColumns(20, 0). // Slightly wider sidebar
+ AddItem(header, 0, 0, 1, 2, 0, 0, false).
+ AddItem(sidebar, 1, 0, 1, 1, 0, 0, false).
+ AddItem(content, 1, 1, 1, 1, 0, 0, true).
+ AddItem(footer, 2, 0, 1, 2, 0, 0, false)
+
+ // Add a border around the content area if possible, or ensure content has its own border
+ // grid.SetBorders(false) // Grid borders usually look bad, handled by components
+
+ return grid
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/channels.go b/cmd/picoclaw-launcher-tui/ui/channels.go
new file mode 100644
index 000000000..c976f1fcd
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/channels.go
@@ -0,0 +1,202 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "reflect"
+ "strconv"
+
+ "github.com/gdamore/tcell/v2"
+ "github.com/rivo/tview"
+)
+
+func (a *App) newChannelsPage() tview.Primitive {
+ list := tview.NewList()
+ list.SetBorder(true).
+ SetTitle(" [#00f0ff::b] COMMUNICATION CHANNELS ").
+ SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ list.SetMainTextColor(tcell.NewHexColor(0xe0e0e0))
+ list.SetSecondaryTextColor(tcell.NewHexColor(0x808080))
+ list.SetSelectedStyle(
+ tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0x050510)),
+ )
+ list.SetHighlightFullLine(true)
+ list.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ rebuild := func() {
+ sel := list.GetCurrentItem()
+ list.Clear()
+
+ home, err := os.UserHomeDir()
+ if err != nil {
+ home = "."
+ }
+ configPath := filepath.Join(home, ".picoclaw", "config.json")
+
+ var cfg map[string]any
+ if data, err := os.ReadFile(configPath); err == nil {
+ _ = json.Unmarshal(data, &cfg)
+ }
+
+ if chRaw, ok := cfg["channels"].(map[string]any); ok {
+ for name, ch := range chRaw {
+ chMap, ok := ch.(map[string]any)
+ enabled := "disabled"
+ if ok {
+ if e, ok := chMap["enabled"].(bool); ok && e {
+ enabled = "enabled"
+ }
+ }
+ list.AddItem(name, fmt.Sprintf("Status: %s", enabled), 0, func() {
+ a.showChannelEditForm(configPath, name, chMap)
+ })
+ }
+ }
+
+ if sel >= 0 && sel < list.GetItemCount() {
+ list.SetCurrentItem(sel)
+ }
+ }
+ rebuild()
+
+ a.pageRefreshFns["channels"] = rebuild
+
+ list.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ if event.Key() == tcell.KeyEscape {
+ return a.goBack()
+ }
+ return event
+ })
+
+ return a.buildShell("channels", list, " [#ff00ff]Enter:[-] edit [#ff2a2a]ESC:[-] back ")
+}
+
+func (a *App) showChannelEditForm(configPath, channelName string, existing map[string]any) {
+ form := tview.NewForm()
+ form.SetBorder(true).
+ SetTitle(" [::b]EDIT CHANNEL ").
+ SetTitleColor(tcell.NewHexColor(0x39ff14)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
+ form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
+ form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
+ form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
+ form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
+ form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
+
+ fields := make(map[string]*tview.InputField)
+ var nameField *tview.InputField
+
+ if channelName == "" {
+ nameField = tview.NewInputField().
+ SetLabel("Channel Name").
+ SetText("").
+ SetFieldWidth(28)
+ form.AddFormItem(nameField)
+ }
+
+ for k, v := range existing {
+ if reflect.ValueOf(v).Kind() == reflect.Map || reflect.ValueOf(v).Kind() == reflect.Slice {
+ continue
+ }
+ valStr := fmt.Sprintf("%v", v)
+ field := tview.NewInputField().
+ SetLabel(k).
+ SetText(valStr).
+ SetFieldWidth(28)
+ form.AddFormItem(field)
+ fields[k] = field
+ }
+
+ form.AddButton("SAVE", func() {
+ var cfg map[string]any
+ if data, err := os.ReadFile(configPath); err == nil {
+ if err := json.Unmarshal(data, &cfg); err != nil {
+ cfg = make(map[string]any)
+ }
+ } else {
+ cfg = make(map[string]any)
+ }
+
+ if _, ok := cfg["channels"]; !ok {
+ cfg["channels"] = make(map[string]any)
+ }
+ channels, ok := cfg["channels"].(map[string]any)
+ if !ok {
+ channels = make(map[string]any)
+ cfg["channels"] = channels
+ }
+
+ finalName := channelName
+ if channelName == "" {
+ if nameField == nil || nameField.GetText() == "" {
+ a.showError("Channel name is required")
+ return
+ }
+ finalName = nameField.GetText()
+ }
+
+ updated := make(map[string]any)
+ if existing != nil {
+ for k, v := range existing {
+ updated[k] = v
+ }
+ }
+ for k, field := range fields {
+ val := field.GetText()
+ if val == "true" {
+ updated[k] = true
+ } else if val == "false" {
+ updated[k] = false
+ } else if num, err := strconv.Atoi(val); err == nil {
+ updated[k] = num
+ } else {
+ updated[k] = val
+ }
+ }
+
+ if channelName != "" && finalName != channelName {
+ delete(channels, channelName)
+ }
+ channels[finalName] = updated
+
+ data, err := json.MarshalIndent(cfg, "", " ")
+ if err != nil {
+ a.showError(fmt.Sprintf("Failed to save config: %v", err))
+ return
+ }
+ if err := os.MkdirAll(filepath.Dir(configPath), 0o700); err != nil {
+ a.showError(fmt.Sprintf("Failed to create config directory: %v", err))
+ return
+ }
+ if err := os.WriteFile(configPath, data, 0o600); err != nil {
+ a.showError(fmt.Sprintf("Failed to write config: %v", err))
+ return
+ }
+
+ a.hideModal("channel-edit")
+ a.goBack()
+ })
+
+ form.AddButton("CANCEL", func() {
+ a.hideModal("channel-edit")
+ })
+
+ form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ if event.Key() == tcell.KeyEscape {
+ a.hideModal("channel-edit")
+ return nil
+ }
+ return event
+ })
+
+ a.showModal("channel-edit", centeredForm(form, 4, 20))
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/gateway.go b/cmd/picoclaw-launcher-tui/ui/gateway.go
new file mode 100644
index 000000000..1138c12db
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/gateway.go
@@ -0,0 +1,261 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+ "fmt"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "runtime"
+ "strconv"
+ "strings"
+ "time"
+
+ "github.com/gdamore/tcell/v2"
+ "github.com/rivo/tview"
+)
+
+const pidFileName = "gateway.pid"
+
+type gatewayStatus struct {
+ running bool
+ pid int
+}
+
+func getPidPath() string {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ home = "."
+ }
+ return filepath.Join(home, ".picoclaw", pidFileName)
+}
+
+func isProcessRunning(pid int) bool {
+ if runtime.GOOS == "windows" {
+ cmd := exec.Command("tasklist", "/FI", fmt.Sprintf("PID eq %d", pid))
+ output, err := cmd.Output()
+ if err != nil {
+ return false
+ }
+ return strings.Contains(string(output), strconv.Itoa(pid))
+ } else if runtime.GOOS == "darwin" {
+ cmd := exec.Command("ps", "aux")
+ output, err := cmd.Output()
+ if err != nil {
+ return false
+ }
+ return strings.Contains(string(output), fmt.Sprintf(" %d ", pid))
+ }
+ // Linux
+ _, err := os.Stat(fmt.Sprintf("/proc/%d", pid))
+ return err == nil
+}
+
+func getGatewayStatus() gatewayStatus {
+ pidPath := getPidPath()
+ data, err := os.ReadFile(pidPath)
+ if err != nil {
+ return gatewayStatus{running: false}
+ }
+ pid, err := strconv.Atoi(strings.TrimSpace(string(data)))
+ if err != nil {
+ return gatewayStatus{running: false}
+ }
+ if !isProcessRunning(pid) {
+ os.Remove(pidPath)
+ return gatewayStatus{running: false}
+ }
+ return gatewayStatus{
+ running: true,
+ pid: pid,
+ }
+}
+
+func startGateway() error {
+ status := getGatewayStatus()
+ if status.running {
+ return fmt.Errorf("gateway is already running (PID: %d)", status.pid)
+ }
+
+ pidPath := getPidPath()
+ var cmd *exec.Cmd
+
+ if runtime.GOOS == "windows" {
+ cmd = exec.Command("cmd", "/C", "start /B picoclaw gateway > NUL 2>&1")
+ } else {
+ cmd = exec.Command("sh", "-c", "nohup picoclaw gateway > /dev/null 2>&1 & echo $! > "+pidPath)
+ }
+
+ err := cmd.Start()
+ if err != nil {
+ return err
+ }
+
+ time.Sleep(1 * time.Second)
+
+ if runtime.GOOS == "windows" {
+ cmd := exec.Command(
+ "wmic",
+ "process",
+ "where",
+ "name='picoclaw.exe' and commandline like '%gateway%'",
+ "get",
+ "processid",
+ )
+ output, err := cmd.Output()
+ if err != nil {
+ return fmt.Errorf("failed to get gateway PID: %w", err)
+ }
+ lines := strings.Split(string(output), "\n")
+ for _, line := range lines[1:] {
+ line = strings.TrimSpace(line)
+ if line == "" {
+ continue
+ }
+ pid, err := strconv.Atoi(line)
+ if err == nil {
+ os.WriteFile(pidPath, []byte(strconv.Itoa(pid)), 0o600)
+ break
+ }
+ }
+ }
+
+ status = getGatewayStatus()
+ if !status.running {
+ return fmt.Errorf("failed to start gateway")
+ }
+ return nil
+}
+
+func stopGateway() error {
+ status := getGatewayStatus()
+ if !status.running {
+ return fmt.Errorf("gateway is not running")
+ }
+
+ var err error
+ if runtime.GOOS == "windows" {
+ err = exec.Command("taskkill", "/F", "/PID", strconv.Itoa(status.pid)).Run()
+ } else {
+ err = exec.Command("kill", "-9", strconv.Itoa(status.pid)).Run()
+ }
+ if err != nil {
+ return err
+ }
+
+ // 多次尝试确认进程已停止
+ for i := 0; i < 5; i++ {
+ if !isProcessRunning(status.pid) {
+ break
+ }
+ time.Sleep(200 * time.Millisecond)
+ }
+
+ os.Remove(getPidPath())
+ return nil
+}
+
+func (a *App) newGatewayPage() tview.Primitive {
+ flex := tview.NewFlex().SetDirection(tview.FlexRow)
+ flex.SetBorder(true).
+ SetTitle(" [#00f0ff::b] GATEWAY MANAGEMENT ").
+ SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ flex.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ statusTV := tview.NewTextView().
+ SetDynamicColors(true).
+ SetTextAlign(tview.AlignCenter).
+ SetText("Checking status...")
+ statusTV.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ var updateStatus func()
+
+ // 使用List作为按钮，保证显示和交互正常
+ buttons := tview.NewList()
+ buttons.SetBackgroundColor(tcell.NewHexColor(0x050510))
+ buttons.SetMainTextColor(tcell.ColorWhite)
+ buttons.SetSelectedBackgroundColor(tcell.NewHexColor(0xff00ff))
+ buttons.SetSelectedTextColor(tcell.ColorBlack)
+
+ buttons.AddItem(" [lime]START[white] ", "", 0, func() {
+ if !getGatewayStatus().running {
+ err := startGateway()
+ if err != nil {
+ a.showError(err.Error())
+ }
+ updateStatus()
+ }
+ })
+ buttons.AddItem(" [red]STOP[white] ", "", 0, func() {
+ if getGatewayStatus().running {
+ err := stopGateway()
+ if err != nil {
+ a.showError(err.Error())
+ }
+ updateStatus()
+ }
+ })
+
+ buttonFlex := tview.NewFlex().SetDirection(tview.FlexColumn)
+ buttonFlex.
+ AddItem(tview.NewBox(), 0, 1, false).
+ AddItem(buttons, 20, 1, true).
+ AddItem(tview.NewBox(), 0, 1, false)
+
+ flex.
+ AddItem(tview.NewBox(), 0, 1, false).
+ AddItem(statusTV, 3, 1, false).
+ AddItem(tview.NewBox(), 0, 1, false).
+ AddItem(buttonFlex, 4, 1, true).
+ AddItem(tview.NewBox(), 0, 1, false)
+
+ updateStatus = func() {
+ status := getGatewayStatus()
+ if status.running {
+ statusTV.SetText(fmt.Sprintf("[#39ff14::b]GATEWAY RUNNING[-]\n\nPID: %d", status.pid))
+ buttons.SetItemText(0, " [gray]START[white] ", "")
+ buttons.SetItemText(1, " [red]STOP[white] ", "")
+ } else {
+ statusTV.SetText("[#ff2a2a::b]GATEWAY STOPPED[-]\n\nPID: N/A")
+ buttons.SetItemText(0, " [lime]START[white] ", "")
+ buttons.SetItemText(1, " [gray]STOP[white] ", "")
+ }
+ }
+
+ updateStatus()
+
+ done := make(chan struct{})
+ go func() {
+ ticker := time.NewTicker(2 * time.Second)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ticker.C:
+ a.tapp.QueueUpdateDraw(updateStatus)
+ case <-done:
+ return
+ }
+ }
+ }()
+
+ originalInputCapture := flex.GetInputCapture()
+ flex.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ if event.Key() == tcell.KeyEscape {
+ close(done)
+ return a.goBack()
+ }
+ if originalInputCapture != nil {
+ return originalInputCapture(event)
+ }
+ return event
+ })
+
+ a.pageRefreshFns["gateway"] = updateStatus
+
+ return a.buildShell("gateway", flex, " [#39ff14]Enter:[-] select [#ff2a2a]ESC:[-] back ")
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/home.go b/cmd/picoclaw-launcher-tui/ui/home.go
new file mode 100644
index 000000000..74a7769cf
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/home.go
@@ -0,0 +1,70 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+ "os"
+ "os/exec"
+
+ "github.com/gdamore/tcell/v2"
+ "github.com/rivo/tview"
+)
+
+func (a *App) newHomePage() tview.Primitive {
+ list := tview.NewList()
+ list.SetBorder(true).
+ SetTitle(" [#00f0ff::b] ACTIVE CONFIGURATION ").
+ SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ list.SetMainTextColor(tcell.NewHexColor(0xe0e0e0))
+ list.SetSecondaryTextColor(tcell.NewHexColor(0x808080))
+ list.SetSelectedStyle(
+ tcell.StyleDefault.Background(tcell.NewHexColor(0x39ff14)).Foreground(tcell.NewHexColor(0x050510)),
+ )
+ list.SetHighlightFullLine(true)
+ list.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ rebuildList := func() {
+ sel := list.GetCurrentItem()
+ list.Clear()
+ list.AddItem("MODEL: "+a.cfg.CurrentModelLabel(), "Select to configure AI model", 'm', func() {
+ a.navigateTo("schemes", a.newSchemesPage())
+ })
+ list.AddItem(
+ "CHANNELS: Configure communication channels",
+ "Manage Telegram/Discord/WeChat channels",
+ 'n',
+ func() {
+ a.navigateTo("channels", a.newChannelsPage())
+ },
+ )
+ list.AddItem("GATEWAY MANAGEMENT", "Manage PicoClaw gateway daemon", 'g', func() {
+ a.navigateTo("gateway", a.newGatewayPage())
+ })
+ list.AddItem("CHAT: Start AI agent chat", "Launch interactive chat session", 'c', func() {
+ a.tapp.Suspend(func() {
+ cmd := exec.Command("picoclaw", "agent")
+ cmd.Stdin = os.Stdin
+ cmd.Stdout = os.Stdout
+ cmd.Stderr = os.Stderr
+ _ = cmd.Run()
+ })
+ })
+ list.AddItem("QUIT SYSTEM", "Exit PicoClaw Launcher", 'q', func() { a.tapp.Stop() })
+ if sel >= 0 && sel < list.GetItemCount() {
+ list.SetCurrentItem(sel)
+ }
+ }
+ rebuildList()
+
+ a.pageRefreshFns["home"] = rebuildList
+
+ return a.buildShell(
+ "home",
+ list,
+ " [#00f0ff]m:[-] model [#00f0ff]n:[-] channels [#00f0ff]g:[-] gateway [#00f0ff]c:[-] chat [#ff2a2a]q:[-] quit ",
+ )
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/models.go b/cmd/picoclaw-launcher-tui/ui/models.go
new file mode 100644
index 000000000..20e5f0182
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/models.go
@@ -0,0 +1,200 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "strings"
+ "time"
+
+ "github.com/gdamore/tcell/v2"
+ "github.com/rivo/tview"
+
+ tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+)
+
+type modelsAPIResponse struct {
+ Data []modelEntry `json:"data"`
+}
+
+type modelEntry struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Description string `json:"description"`
+}
+
+func (a *App) newModelsPage(schemeName, userName, baseURL string) tview.Primitive {
+ table := tview.NewTable().
+ SetBorders(false).
+ SetSelectable(true, false).
+ SetFixed(0, 0)
+ table.SetBorder(true).
+ SetTitle(fmt.Sprintf(" [#00f0ff::b] MODELS · %s / %s ", schemeName, userName)).
+ SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ table.SetSelectedStyle(
+ tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
+ )
+ table.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ var modelIDs []string
+
+ status := tview.NewTextView().
+ SetTextAlign(tview.AlignCenter).
+ SetDynamicColors(true).
+ SetText("[#ffff00]FETCHING MODELS...[-]")
+ status.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ flex := tview.NewFlex().
+ SetDirection(tview.FlexRow).
+ AddItem(status, 1, 0, false).
+ AddItem(table, 0, 1, false)
+
+ apiKey := a.resolveKey(schemeName, userName)
+
+ go func() {
+ var entries []modelEntry
+ var err error
+ if apiKey == "" {
+ err = fmt.Errorf("key is required")
+ } else {
+ entries, err = fetchModels(baseURL, apiKey)
+ }
+
+ a.modelCacheMu.Lock()
+ if a.modelCache == nil {
+ a.modelCache = make(map[string][]modelEntry)
+ }
+ if err == nil && len(entries) > 0 {
+ a.modelCache[cacheKey(schemeName, userName)] = entries
+ } else {
+ a.modelCache[cacheKey(schemeName, userName)] = nil
+ }
+ a.modelCacheMu.Unlock()
+
+ a.tapp.QueueUpdateDraw(func() {
+ if err != nil {
+ status.SetText(fmt.Sprintf("[#ff2a2a]ERROR: %s[-]", err.Error()))
+ table.SetCell(0, 0, tview.NewTableCell(" (failed to load models)"))
+ a.tapp.SetFocus(table)
+ return
+ }
+ if len(entries) == 0 {
+ status.SetText("[#ff2a2a]NO MODELS RETURNED[-]")
+ table.SetCell(0, 0, tview.NewTableCell(" (no models available)"))
+ a.tapp.SetFocus(table)
+ return
+ }
+
+ status.SetText(fmt.Sprintf("[#39ff14]%d MODEL(S) LOADED[-]", len(entries)))
+ for i, m := range entries {
+ modelIDs = append(modelIDs, m.ID)
+ table.SetCell(i, 0,
+ tview.NewTableCell(fmt.Sprintf("%3d", i+1)).
+ SetAlign(tview.AlignRight).
+ SetTextColor(tcell.NewHexColor(0x808080)).
+ SetSelectable(false),
+ )
+ table.SetCell(i, 1,
+ tview.NewTableCell(" "+m.ID).
+ SetAlign(tview.AlignLeft).
+ SetExpansion(1).
+ SetTextColor(tcell.NewHexColor(0xe0e0e0)),
+ )
+ }
+ a.tapp.SetFocus(table)
+ })
+ }()
+
+ table.SetSelectedFunc(func(row, _ int) {
+ if row < 0 || row >= len(modelIDs) {
+ return
+ }
+ a.cfg.Provider.Current = tuicfg.ProviderCurrent{
+ Scheme: schemeName,
+ User: userName,
+ Model: modelIDs[row],
+ }
+ a.save()
+
+ // Trigger model selected callback if set
+ if a.OnModelSelected != nil && a.cfg.Model.Type == "provider" {
+ scheme := a.cfg.Provider.SchemeByName(schemeName)
+ if scheme == nil {
+ a.goBack()
+ return
+ }
+ var user tuicfg.User
+ for _, u := range a.cfg.Provider.Users {
+ if u.Scheme == schemeName && u.Name == userName {
+ user = u
+ break
+ }
+ }
+ a.OnModelSelected(*scheme, user, modelIDs[row])
+ }
+
+ a.goBack()
+ })
+
+ return a.buildShell("models", flex, " [#39ff14]Enter:[-] select [#ff00ff]ESC:[-] back ")
+}
+
+func (a *App) resolveKey(schemeName, userName string) string {
+ for _, u := range a.cfg.Provider.Users {
+ if u.Scheme == schemeName && u.Name == userName {
+ return u.Key
+ }
+ }
+ return ""
+}
+
+func fetchModels(baseURL, apiKey string) ([]modelEntry, error) {
+ url := strings.TrimRight(baseURL, "/") + "/models"
+
+ client := &http.Client{Timeout: 15 * time.Second}
+ req, err := http.NewRequest(http.MethodGet, url, nil)
+ if err != nil {
+ return nil, fmt.Errorf("build request: %w", err)
+ }
+ if apiKey != "" {
+ req.Header.Set("Authorization", "Bearer "+apiKey)
+ }
+
+ resp, err := client.Do(req)
+ if err != nil {
+ return nil, fmt.Errorf("request failed: %w", err)
+ }
+ defer resp.Body.Close()
+
+ if resp.StatusCode != http.StatusOK {
+ body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+ return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+ }
+
+ body, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return nil, fmt.Errorf("read response: %w", err)
+ }
+
+ var result modelsAPIResponse
+ if err := json.Unmarshal(body, &result); err == nil && len(result.Data) > 0 {
+ return result.Data, nil
+ }
+
+ var arr []modelEntry
+ if err := json.Unmarshal(body, &arr); err == nil {
+ return arr, nil
+ }
+
+ return nil, fmt.Errorf(
+ "decode response: unrecognized shape: %s",
+ strings.TrimSpace(string(body[:min(len(body), 256)])),
+ )
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/schemes.go b/cmd/picoclaw-launcher-tui/ui/schemes.go
new file mode 100644
index 000000000..e38d7fa86
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/schemes.go
@@ -0,0 +1,252 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+ "fmt"
+
+ "github.com/gdamore/tcell/v2"
+ "github.com/rivo/tview"
+
+ tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+)
+
+func (a *App) newSchemesPage() tview.Primitive {
+ table := tview.NewTable().
+ SetBorders(false).
+ SetSelectable(true, false)
+ table.SetBorder(true).
+ SetTitle(" [#00f0ff::b] PROVIDER SCHEMES ").
+ SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ table.SetSelectedStyle(
+ tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
+ )
+ table.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ rowToIdx := func(row int) int { return row / 2 }
+
+ selectedSchemeName := func() string {
+ row, _ := table.GetSelection()
+ idx := rowToIdx(row)
+ schemes := a.cfg.Provider.Schemes
+ if idx >= 0 && idx < len(schemes) {
+ return schemes[idx].Name
+ }
+ return ""
+ }
+
+ rebuild := func() {
+ selName := selectedSchemeName()
+ table.Clear()
+ schemes := a.cfg.Provider.Schemes
+ for i, s := range schemes {
+ nameRow := i * 2
+ detailRow := nameRow + 1
+
+ table.SetCell(nameRow, 0,
+ tview.NewTableCell(" "+s.Name).
+ SetTextColor(tcell.NewHexColor(0xe0e0e0)).
+ SetExpansion(1).
+ SetSelectable(true),
+ )
+
+ users := a.cfg.Provider.UsersForScheme(s.Name)
+ n := len(users)
+ m := 0
+ for _, u := range users {
+ if models := a.cachedModels(s.Name, u.Name); len(models) > 0 {
+ m++
+ }
+ }
+ table.SetCell(detailRow, 0,
+ tview.NewTableCell(fmt.Sprintf(" [#808080](%d/%d) %s", m, n, s.BaseURL)).
+ SetTextColor(tcell.NewHexColor(0x808080)).
+ SetExpansion(1).
+ SetSelectable(false),
+ )
+ table.SetCell(detailRow, 1,
+ tview.NewTableCell("[#00f0ff]"+s.Type+" ").
+ SetAlign(tview.AlignRight).
+ SetSelectable(false),
+ )
+ }
+ if selName != "" {
+ for i, s := range schemes {
+ if s.Name == selName {
+ table.Select(i*2, 0)
+ return
+ }
+ }
+ }
+ if table.GetRowCount() > 0 {
+ table.Select(0, 0)
+ }
+ }
+ rebuild()
+
+ a.refreshModelCache(rebuild)
+ a.pageRefreshFns["schemes"] = func() { a.refreshModelCache(rebuild) }
+
+ table.SetSelectedFunc(func(row, _ int) {
+ idx := rowToIdx(row)
+ schemes := a.cfg.Provider.Schemes
+ if idx < 0 || idx >= len(schemes) {
+ return
+ }
+ name := schemes[idx].Name
+ a.navigateTo("users", a.newUsersPage(name))
+ })
+
+ table.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ row, _ := table.GetSelection()
+ idx := rowToIdx(row)
+ schemes := a.cfg.Provider.Schemes
+ switch event.Rune() {
+ case 'a':
+ a.showSchemeForm(nil, func(s tuicfg.Scheme) {
+ a.cfg.Provider.Schemes = append(a.cfg.Provider.Schemes, s)
+ a.save()
+ a.refreshModelCache(rebuild)
+ })
+ return nil
+ case 'e':
+ if idx < 0 || idx >= len(schemes) {
+ return nil
+ }
+ origName := schemes[idx].Name
+ orig := schemes[idx]
+ a.showSchemeForm(&orig, func(s tuicfg.Scheme) {
+ current := a.cfg.Provider.Schemes
+ for i, sc := range current {
+ if sc.Name == origName {
+ a.cfg.Provider.Schemes[i] = s
+ break
+ }
+ }
+ a.save()
+ a.refreshModelCache(func() {
+ rebuild()
+ for i, sc := range a.cfg.Provider.Schemes {
+ if sc.Name == s.Name {
+ table.Select(i*2, 0)
+ break
+ }
+ }
+ })
+ })
+ return nil
+ case 'd':
+ if idx < 0 || idx >= len(schemes) {
+ return nil
+ }
+ name := schemes[idx].Name
+ a.confirmDelete(fmt.Sprintf("scheme %q", name), func() {
+ current := a.cfg.Provider.Schemes
+ newSchemes := make([]tuicfg.Scheme, 0, len(current))
+ for _, sc := range current {
+ if sc.Name != name {
+ newSchemes = append(newSchemes, sc)
+ }
+ }
+ a.cfg.Provider.Schemes = newSchemes
+
+ existing := a.cfg.Provider.Users
+ filtered := make([]tuicfg.User, 0, len(existing))
+ for _, u := range existing {
+ if u.Scheme != name {
+ filtered = append(filtered, u)
+ }
+ }
+ a.cfg.Provider.Users = filtered
+
+ a.save()
+ a.refreshModelCache(rebuild)
+ })
+ return nil
+ }
+ return event
+ })
+
+ return a.buildShell(
+ "schemes",
+ table,
+ " [#00f0ff]a:[-] add [#00f0ff]e:[-] edit [#ff2a2a]d:[-] delete [#39ff14]Enter:[-] open [#ff00ff]ESC:[-] back ",
+ )
+}
+
+func (a *App) showSchemeForm(existing *tuicfg.Scheme, onSave func(tuicfg.Scheme)) {
+ name := ""
+ baseURL := ""
+ schemeType := "openai-compatible"
+ title := " ADD SCHEME "
+
+ if existing != nil {
+ name = existing.Name
+ baseURL = existing.BaseURL
+ schemeType = existing.Type
+ title = " EDIT SCHEME "
+ }
+
+ typeOptions := []string{"openai-compatible", "anthropic"}
+ typeIdx := 0
+ for i, t := range typeOptions {
+ if t == schemeType {
+ typeIdx = i
+ break
+ }
+ }
+
+ form := tview.NewForm()
+
+ form.
+ AddInputField("Name", name, 20, nil, func(text string) { name = text }).
+ AddInputField("Base URL", baseURL, 28, nil, func(text string) { baseURL = text }).
+ AddDropDown("Type", typeOptions, typeIdx, func(option string, _ int) { schemeType = option }).
+ AddButton("SAVE", func() {
+ if name == "" {
+ a.showError("Name is required")
+ return
+ }
+ if baseURL == "" {
+ a.showError("Base URL is required")
+ return
+ }
+ if existing == nil {
+ for _, s := range a.cfg.Provider.Schemes {
+ if s.Name == name {
+ a.showError(fmt.Sprintf("Scheme name %q already exists", name))
+ return
+ }
+ }
+ }
+ a.hideModal("scheme-form")
+ onSave(tuicfg.Scheme{Name: name, BaseURL: baseURL, Type: schemeType})
+ }).
+ AddButton("CANCEL", func() {
+ a.hideModal("scheme-form")
+ })
+
+ form.SetBorder(true).
+ SetTitle(" [::b]" + title + " ").
+ SetTitleColor(tcell.NewHexColor(0x39ff14)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
+ form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
+ form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
+ form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
+ form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
+ form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
+ form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ if event.Key() == tcell.KeyEscape {
+ a.hideModal("scheme-form")
+ return nil
+ }
+ return event
+ })
+
+ a.showModal("scheme-form", centeredForm(form, 4, 12))
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/users.go b/cmd/picoclaw-launcher-tui/ui/users.go
new file mode 100644
index 000000000..b00fc8982
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/users.go
@@ -0,0 +1,261 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+ "fmt"
+
+ "github.com/gdamore/tcell/v2"
+ "github.com/rivo/tview"
+
+ tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+)
+
+func (a *App) newUsersPage(schemeName string) tview.Primitive {
+ table := tview.NewTable().
+ SetBorders(false).
+ SetSelectable(true, false)
+ table.SetBorder(true).
+ SetTitle(fmt.Sprintf(" [#00f0ff::b] USERS · %s ", schemeName)).
+ SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ table.SetSelectedStyle(
+ tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
+ )
+ table.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+ visibleUsers := func() []tuicfg.User {
+ var out []tuicfg.User
+ for _, u := range a.cfg.Provider.Users {
+ if u.Scheme == schemeName {
+ out = append(out, u)
+ }
+ }
+ return out
+ }
+
+ findUserGlobalIdx := func(userName string) int {
+ for i, u := range a.cfg.Provider.Users {
+ if u.Scheme == schemeName && u.Name == userName {
+ return i
+ }
+ }
+ return -1
+ }
+
+ rowToVisIdx := func(row int) int { return row / 2 }
+
+ selectedUserName := func() string {
+ row, _ := table.GetSelection()
+ users := visibleUsers()
+ visIdx := rowToVisIdx(row)
+ if visIdx >= 0 && visIdx < len(users) {
+ return users[visIdx].Name
+ }
+ return ""
+ }
+
+ rebuild := func() {
+ selName := selectedUserName()
+ table.Clear()
+ users := visibleUsers()
+ for i, u := range users {
+ nameRow := i * 2
+ detailRow := nameRow + 1
+
+ table.SetCell(nameRow, 0,
+ tview.NewTableCell(" "+u.Name).
+ SetTextColor(tcell.NewHexColor(0xe0e0e0)).
+ SetExpansion(1).
+ SetSelectable(true),
+ )
+ table.SetCell(nameRow, 1,
+ tview.NewTableCell("").
+ SetSelectable(false),
+ )
+
+ models := a.cachedModels(schemeName, u.Name)
+ var detailText string
+ if len(models) > 0 {
+ detailText = fmt.Sprintf(" [#39ff14]%d models available[-]", len(models))
+ } else {
+ detailText = " [#ff2a2a]Inactive / No Access[-]"
+ }
+ table.SetCell(detailRow, 0,
+ tview.NewTableCell(detailText).
+ SetTextColor(tcell.NewHexColor(0x808080)).
+ SetExpansion(1).
+ SetSelectable(false),
+ )
+ table.SetCell(detailRow, 1,
+ tview.NewTableCell("[#00f0ff]"+u.Type+" ").
+ SetAlign(tview.AlignRight).
+ SetSelectable(false),
+ )
+ }
+ if selName != "" {
+ for i, u := range users {
+ if u.Name == selName {
+ table.Select(i*2, 0)
+ return
+ }
+ }
+ }
+ if table.GetRowCount() > 0 {
+ table.Select(0, 0)
+ }
+ }
+ rebuild()
+
+ a.refreshModelCache(rebuild)
+ a.pageRefreshFns["users"] = func() { a.refreshModelCache(rebuild) }
+
+ table.SetSelectedFunc(func(row, _ int) {
+ visIdx := rowToVisIdx(row)
+ users := visibleUsers()
+ if visIdx < 0 || visIdx >= len(users) {
+ return
+ }
+ uName := users[visIdx].Name
+ scheme := a.cfg.Provider.SchemeByName(schemeName)
+ if scheme == nil {
+ a.showError(fmt.Sprintf("Scheme %q not found", schemeName))
+ return
+ }
+ a.navigateTo("models", a.newModelsPage(schemeName, uName, scheme.BaseURL))
+ })
+
+ table.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ row, _ := table.GetSelection()
+ visIdx := rowToVisIdx(row)
+ users := visibleUsers()
+ switch event.Rune() {
+ case 'a':
+ a.showUserForm(schemeName, nil, func(u tuicfg.User) {
+ a.cfg.Provider.Users = append(a.cfg.Provider.Users, u)
+ a.save()
+ a.refreshModelCache(rebuild)
+ })
+ return nil
+ case 'e':
+ if visIdx < 0 || visIdx >= len(users) {
+ return nil
+ }
+ origName := users[visIdx].Name
+ orig := a.cfg.Provider.Users[findUserGlobalIdx(origName)]
+ a.showUserForm(schemeName, &orig, func(u tuicfg.User) {
+ cfgIdx := findUserGlobalIdx(origName)
+ if cfgIdx < 0 {
+ a.showError(fmt.Sprintf("User %q no longer exists", origName))
+ return
+ }
+ a.cfg.Provider.Users[cfgIdx] = u
+ a.save()
+ a.refreshModelCache(func() {
+ rebuild()
+ for i, usr := range visibleUsers() {
+ if usr.Name == u.Name {
+ table.Select(i*2, 0)
+ break
+ }
+ }
+ })
+ })
+ return nil
+ case 'd':
+ if visIdx < 0 || visIdx >= len(users) {
+ return nil
+ }
+ uName := users[visIdx].Name
+ a.confirmDelete(fmt.Sprintf("user %q", uName), func() {
+ cfgIdx := findUserGlobalIdx(uName)
+ if cfgIdx < 0 {
+ return
+ }
+ all := a.cfg.Provider.Users
+ a.cfg.Provider.Users = append(all[:cfgIdx], all[cfgIdx+1:]...)
+ a.save()
+ a.refreshModelCache(rebuild)
+ })
+ return nil
+ }
+ return event
+ })
+
+ return a.buildShell(
+ "users",
+ table,
+ " [#00f0ff]a:[-] add [#00f0ff]e:[-] edit [#ff2a2a]d:[-] delete [#39ff14]Enter:[-] models [#ff00ff]ESC:[-] back ",
+ )
+}
+
+func (a *App) showUserForm(schemeName string, existing *tuicfg.User, onSave func(tuicfg.User)) {
+ name := ""
+ userType := "key"
+ key := ""
+ title := " ADD USER "
+
+ if existing != nil {
+ name = existing.Name
+ userType = existing.Type
+ key = existing.Key
+ title = " EDIT USER "
+ }
+
+ typeOptions := []string{"key", "OAuth"}
+ typeIdx := 0
+ for i, t := range typeOptions {
+ if t == userType {
+ typeIdx = i
+ break
+ }
+ }
+
+ form := tview.NewForm()
+ form.
+ AddInputField("Name", name, 20, nil, func(text string) { name = text }).
+ AddDropDown("Type", typeOptions, typeIdx, func(option string, _ int) { userType = option }).
+ AddPasswordField("Key", key, 28, '*', func(text string) { key = text }).
+ AddButton("SAVE", func() {
+ if name == "" {
+ a.showError("Name is required")
+ return
+ }
+ if existing == nil {
+ for _, u := range a.cfg.Provider.Users {
+ if u.Scheme == schemeName && u.Name == name {
+ a.showError(fmt.Sprintf("User name %q already exists for this scheme", name))
+ return
+ }
+ }
+ }
+ a.hideModal("user-form")
+ onSave(tuicfg.User{Name: name, Scheme: schemeName, Type: userType, Key: key})
+ }).
+ AddButton("CANCEL", func() {
+ a.hideModal("user-form")
+ })
+
+ form.SetBorder(true).
+ SetTitle(" [::b]" + title + " ").
+ SetTitleColor(tcell.NewHexColor(0x39ff14)).
+ SetBorderColor(tcell.NewHexColor(0x00f0ff))
+ form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
+ form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
+ form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
+ form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
+ form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
+ form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
+ form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ if event.Key() == tcell.KeyEscape {
+ a.hideModal("user-form")
+ return nil
+ }
+ return event
+ })
+
+ a.showModal("user-form", centeredForm(form, 4, 13))
+}
diff --git a/cmd/picoclaw/dns_noresolv.go b/cmd/picoclaw/dns_noresolv.go
new file mode 100644
index 000000000..ba4ae1f4f
--- /dev/null
+++ b/cmd/picoclaw/dns_noresolv.go
@@ -0,0 +1,64 @@
+package main
+
+import (
+ "context"
+ "net"
+ "net/http"
+ "os"
+ "strings"
+ "sync/atomic"
+ "time"
+)
+
+func init() {
+ // 仅在 /etc/resolv.conf 不存在时才覆盖（即 Android 环境）
+ if _, err := os.Stat("/etc/resolv.conf"); err == nil {
+ return
+ }
+
+ // 从环境变量获取 DNS server 列表，多个用 ; 隔开
+ // 例如: PICOCLAW_DNS_SERVER="8.8.8.8:53;1.1.1.1:53;223.5.5.5:53"
+ dnsEnv := os.Getenv("PICOCLAW_DNS_SERVER")
+ if dnsEnv == "" {
+ dnsEnv = "8.8.8.8:53;1.1.1.1:53"
+ }
+
+ var dnsServers []string
+ for _, s := range strings.Split(dnsEnv, ";") {
+ s = strings.TrimSpace(s)
+ if s != "" {
+ // 如果没有带端口号，自动补上 :53
+ if _, _, err := net.SplitHostPort(s); err != nil {
+ s = s + ":53"
+ }
+ dnsServers = append(dnsServers, s)
+ }
+ }
+
+ // 轮询索引，在多个 DNS 服务器之间轮转
+ var idx uint64
+
+ customResolver := &net.Resolver{
+ PreferGo: true,
+ Dial: func(ctx context.Context, network, address string) (net.Conn, error) {
+ d := net.Dialer{Timeout: 5 * time.Second}
+ // Round-robin: 依次尝试不同的 DNS 服务器
+ server := dnsServers[atomic.AddUint64(&idx, 1)%uint64(len(dnsServers))]
+ return d.DialContext(ctx, "udp", server)
+ },
+ }
+
+ // 覆盖全局 DefaultResolver
+ net.DefaultResolver = customResolver
+
+ // 覆盖 http.DefaultTransport 使用自定义 DNS 解析的 DialContext
+ dialer := &net.Dialer{
+ Timeout: 30 * time.Second,
+ KeepAlive: 30 * time.Second,
+ Resolver: customResolver,
+ }
+
+ if tr, ok := http.DefaultTransport.(*http.Transport); ok {
+ tr.DialContext = dialer.DialContext
+ }
+}
diff --git a/cmd/picoclaw/internal/agent/helpers.go b/cmd/picoclaw/internal/agent/helpers.go
index c3ddbb77f..0af743bb5 100644
--- a/cmd/picoclaw/internal/agent/helpers.go
+++ b/cmd/picoclaw/internal/agent/helpers.go
@@ -23,16 +23,16 @@ func agentCmd(message, sessionKey, model string, debug bool) error {
sessionKey = "cli:default"
}
- if debug {
- logger.SetLevel(logger.DEBUG)
- fmt.Println("🔍 Debug mode enabled")
- }
-
cfg, err := internal.LoadConfig()
if err != nil {
return fmt.Errorf("error loading config: %w", err)
}
+ if debug {
+ logger.SetLevel(logger.DEBUG)
+ fmt.Println("🔍 Debug mode enabled")
+ }
+
if model != "" {
cfg.Agents.Defaults.ModelName = model
}
diff --git a/cmd/picoclaw/internal/auth/helpers.go b/cmd/picoclaw/internal/auth/helpers.go
index 4bf132685..531cb76aa 100644
--- a/cmd/picoclaw/internal/auth/helpers.go
+++ b/cmd/picoclaw/internal/auth/helpers.go
@@ -56,9 +56,6 @@ func authLoginOpenAI(useDeviceCode bool) error {
appCfg, err := internal.LoadConfig()
if err == nil {
- // Update Providers (legacy format)
- appCfg.Providers.OpenAI.AuthMethod = "oauth"
-
// Update or add openai in ModelList
foundOpenAI := false
for i := range appCfg.ModelList {
@@ -71,7 +68,7 @@ func authLoginOpenAI(useDeviceCode bool) error {
// If no openai in ModelList, add it
if !foundOpenAI {
- appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
+ appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
ModelName: "gpt-5.4",
Model: "openai/gpt-5.4",
AuthMethod: "oauth",
@@ -130,9 +127,6 @@ func authLoginGoogleAntigravity() error {
appCfg, err := internal.LoadConfig()
if err == nil {
- // Update Providers (legacy format, for backward compatibility)
- appCfg.Providers.Antigravity.AuthMethod = "oauth"
-
// Update or add antigravity in ModelList
foundAntigravity := false
for i := range appCfg.ModelList {
@@ -145,7 +139,7 @@ func authLoginGoogleAntigravity() error {
// If no antigravity in ModelList, add it
if !foundAntigravity {
- appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
+ appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
ModelName: "gemini-flash",
Model: "antigravity/gemini-3-flash",
AuthMethod: "oauth",
@@ -210,8 +204,6 @@ func authLoginAnthropicSetupToken() error {
appCfg, err := internal.LoadConfig()
if err == nil {
- appCfg.Providers.Anthropic.AuthMethod = "oauth"
-
found := false
for i := range appCfg.ModelList {
if isAnthropicModel(appCfg.ModelList[i].Model) {
@@ -221,7 +213,7 @@ func authLoginAnthropicSetupToken() error {
}
}
if !found {
- appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
+ appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
ModelName: defaultAnthropicModel,
Model: "anthropic/" + defaultAnthropicModel,
AuthMethod: "oauth",
@@ -287,7 +279,6 @@ func authLoginPasteToken(provider string) error {
if err == nil {
switch provider {
case "anthropic":
- appCfg.Providers.Anthropic.AuthMethod = "token"
// Update ModelList
found := false
for i := range appCfg.ModelList {
@@ -298,7 +289,7 @@ func authLoginPasteToken(provider string) error {
}
}
if !found {
- appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
+ appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
ModelName: defaultAnthropicModel,
Model: "anthropic/" + defaultAnthropicModel,
AuthMethod: "token",
@@ -306,7 +297,6 @@ func authLoginPasteToken(provider string) error {
appCfg.Agents.Defaults.ModelName = defaultAnthropicModel
}
case "openai":
- appCfg.Providers.OpenAI.AuthMethod = "token"
// Update ModelList
found := false
for i := range appCfg.ModelList {
@@ -317,7 +307,7 @@ func authLoginPasteToken(provider string) error {
}
}
if !found {
- appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
+ appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
ModelName: "gpt-5.4",
Model: "openai/gpt-5.4",
AuthMethod: "token",
@@ -365,15 +355,6 @@ func authLogoutCmd(provider string) error {
}
}
}
- // Clear AuthMethod in Providers (legacy)
- switch provider {
- case "openai":
- appCfg.Providers.OpenAI.AuthMethod = ""
- case "anthropic":
- appCfg.Providers.Anthropic.AuthMethod = ""
- case "google-antigravity", "antigravity":
- appCfg.Providers.Antigravity.AuthMethod = ""
- }
config.SaveConfig(internal.GetConfigPath(), appCfg)
}
@@ -392,10 +373,6 @@ func authLogoutCmd(provider string) error {
for i := range appCfg.ModelList {
appCfg.ModelList[i].AuthMethod = ""
}
- // Clear all AuthMethods in Providers (legacy)
- appCfg.Providers.OpenAI.AuthMethod = ""
- appCfg.Providers.Anthropic.AuthMethod = ""
- appCfg.Providers.Antigravity.AuthMethod = ""
config.SaveConfig(internal.GetConfigPath(), appCfg)
}
diff --git a/cmd/picoclaw/internal/gateway/command.go b/cmd/picoclaw/internal/gateway/command.go
index 4812f1bee..7fa588c5c 100644
--- a/cmd/picoclaw/internal/gateway/command.go
+++ b/cmd/picoclaw/internal/gateway/command.go
@@ -34,7 +34,7 @@ func NewGatewayCommand() *cobra.Command {
return nil
},
RunE: func(_ *cobra.Command, _ []string) error {
- return gateway.Run(debug, internal.GetConfigPath(), allowEmpty)
+ return gateway.Run(debug, internal.GetPicoclawHome(), internal.GetConfigPath(), allowEmpty)
},
}
diff --git a/cmd/picoclaw/internal/helpers.go b/cmd/picoclaw/internal/helpers.go
index 6b2d65c91..17de88ccb 100644
--- a/cmd/picoclaw/internal/helpers.go
+++ b/cmd/picoclaw/internal/helpers.go
@@ -4,10 +4,12 @@ import (
"os"
"path/filepath"
+ "github.com/sipeed/picoclaw/pkg"
"github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/logger"
)
-const Logo = "🦞"
+const Logo = pkg.Logo
// GetPicoclawHome returns the picoclaw home directory.
// Priority: $PICOCLAW_HOME > ~/.picoclaw
@@ -16,7 +18,7 @@ func GetPicoclawHome() string {
return home
}
home, _ := os.UserHomeDir()
- return filepath.Join(home, ".picoclaw")
+ return filepath.Join(home, pkg.DefaultPicoClawHome)
}
func GetConfigPath() string {
@@ -27,7 +29,12 @@ func GetConfigPath() string {
}
func LoadConfig() (*config.Config, error) {
- return config.LoadConfig(GetConfigPath())
+ cfg, err := config.LoadConfig(GetConfigPath())
+ if err != nil {
+ return nil, err
+ }
+ logger.SetLevelFromString(cfg.Gateway.LogLevel)
+ return cfg, nil
}
// FormatVersion returns the version string with optional git commit
diff --git a/cmd/picoclaw/internal/helpers_test.go b/cmd/picoclaw/internal/helpers_test.go
index 583751781..953da8886 100644
--- a/cmd/picoclaw/internal/helpers_test.go
+++ b/cmd/picoclaw/internal/helpers_test.go
@@ -8,6 +8,8 @@ import (
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
+
+ "github.com/sipeed/picoclaw/pkg/config"
)
func TestGetConfigPath(t *testing.T) {
@@ -20,7 +22,7 @@ func TestGetConfigPath(t *testing.T) {
}
func TestGetConfigPath_WithPICOCLAW_HOME(t *testing.T) {
- t.Setenv("PICOCLAW_HOME", "/custom/picoclaw")
+ t.Setenv(config.EnvHome, "/custom/picoclaw")
t.Setenv("HOME", "/tmp/home")
got := GetConfigPath()
@@ -31,7 +33,7 @@ func TestGetConfigPath_WithPICOCLAW_HOME(t *testing.T) {
func TestGetConfigPath_WithPICOCLAW_CONFIG(t *testing.T) {
t.Setenv("PICOCLAW_CONFIG", "/custom/config.json")
- t.Setenv("PICOCLAW_HOME", "/custom/picoclaw")
+ t.Setenv(config.EnvHome, "/custom/picoclaw")
t.Setenv("HOME", "/tmp/home")
got := GetConfigPath()
diff --git a/cmd/picoclaw/internal/model/command.go b/cmd/picoclaw/internal/model/command.go
index cad106fd5..314259d0f 100644
--- a/cmd/picoclaw/internal/model/command.go
+++ b/cmd/picoclaw/internal/model/command.go
@@ -56,9 +56,6 @@ Note: 'local-model' is a special value for using a local VLLM server
func showCurrentModel(cfg *config.Config) {
defaultModel := cfg.Agents.Defaults.ModelName
- if defaultModel == "" {
- defaultModel = cfg.Agents.Defaults.Model
- }
if defaultModel == "" {
fmt.Println("No default model is currently set.")
@@ -78,16 +75,13 @@ func listAvailableModels(cfg *config.Config) {
}
defaultModel := cfg.Agents.Defaults.ModelName
- if defaultModel == "" {
- defaultModel = cfg.Agents.Defaults.Model
- }
for _, model := range cfg.ModelList {
marker := " "
if model.ModelName == defaultModel {
marker = "> "
}
- if model.APIKey == "" {
+ if model.APIKey() == "" {
continue
}
fmt.Printf("%s- %s (%s)\n", marker, model.ModelName, model.Model)
@@ -98,7 +92,7 @@ func setDefaultModel(configPath string, cfg *config.Config, modelName string) er
// Validate that the model exists in model_list
modelFound := false
for _, model := range cfg.ModelList {
- if model.APIKey != "" && model.ModelName == modelName {
+ if model.APIKey() != "" && model.ModelName == modelName {
modelFound = true
break
}
@@ -111,12 +105,8 @@ func setDefaultModel(configPath string, cfg *config.Config, modelName string) er
// Update the default model
// Clear old model field and set new model_name
oldModel := cfg.Agents.Defaults.ModelName
- if oldModel == "" {
- oldModel = cfg.Agents.Defaults.Model
- }
cfg.Agents.Defaults.ModelName = modelName
- cfg.Agents.Defaults.Model = "" // Clear deprecated field
// Save config back to file
if err := config.SaveConfig(configPath, cfg); err != nil {
diff --git a/cmd/picoclaw/internal/model/command_test.go b/cmd/picoclaw/internal/model/command_test.go
index 82943e4a6..6cbbf0b55 100644
--- a/cmd/picoclaw/internal/model/command_test.go
+++ b/cmd/picoclaw/internal/model/command_test.go
@@ -58,17 +58,24 @@ func TestNewModelCommand(t *testing.T) {
}
func TestShowCurrentModel_WithDefaultModel(t *testing.T) {
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "gpt-4",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "gpt-4", Model: "openai/gpt-4", APIKey: "test"},
- {ModelName: "claude-3", Model: "anthropic/claude-3", APIKey: "test"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "gpt-4", Model: "openai/gpt-4"},
+ {ModelName: "claude-3", Model: "anthropic/claude-3"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "gpt-4": {
+ APIKeys: []string{"test"},
+ },
+ "claude-3": {
+ APIKeys: []string{"test"},
+ },
+ }})
output := captureStdout(func() {
showCurrentModel(cfg)
@@ -81,17 +88,20 @@ func TestShowCurrentModel_WithDefaultModel(t *testing.T) {
}
func TestShowCurrentModel_NoDefaultModel(t *testing.T) {
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "",
- Model: "",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "gpt-4", Model: "openai/gpt-4", APIKey: "test"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "gpt-4", Model: "openai/gpt-4"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "gpt-4": {
+ APIKeys: []string{"test"},
+ },
+ }})
output := captureStdout(func() {
showCurrentModel(cfg)
@@ -101,26 +111,9 @@ func TestShowCurrentModel_NoDefaultModel(t *testing.T) {
assert.Contains(t, output, "Available models in your config:")
}
-func TestShowCurrentModel_BackwardCompatibility(t *testing.T) {
- cfg := &config.Config{
- Agents: config.AgentsConfig{
- Defaults: config.AgentDefaults{
- Model: "legacy-model",
- },
- },
- ModelList: []config.ModelConfig{},
- }
-
- output := captureStdout(func() {
- showCurrentModel(cfg)
- })
-
- assert.Contains(t, output, "Current default model: legacy-model")
-}
-
func TestListAvailableModels_Empty(t *testing.T) {
cfg := &config.Config{
- ModelList: []config.ModelConfig{},
+ ModelList: []*config.ModelConfig{},
}
output := captureStdout(func() {
@@ -131,18 +124,25 @@ func TestListAvailableModels_Empty(t *testing.T) {
}
func TestListAvailableModels_WithModels(t *testing.T) {
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "gpt-4",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "gpt-4", Model: "openai/gpt-4", APIKey: "test"},
- {ModelName: "claude-3", Model: "anthropic/claude-3", APIKey: "test"},
- {ModelName: "no-key-model", Model: "openai/test", APIKey: ""},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "gpt-4", Model: "openai/gpt-4"},
+ {ModelName: "claude-3", Model: "anthropic/claude-3"},
+ {ModelName: "no-key-model", Model: "openai/test"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "gpt-4": {
+ APIKeys: []string{"test"},
+ },
+ "claude-3": {
+ APIKeys: []string{"test"},
+ },
+ }})
output := captureStdout(func() {
listAvailableModels(cfg)
@@ -157,17 +157,24 @@ func TestListAvailableModels_WithModels(t *testing.T) {
func TestSetDefaultModel_ValidModel(t *testing.T) {
initTest(t)
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "old-model",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "new-model", Model: "openai/new-model", APIKey: "test"},
- {ModelName: "old-model", Model: "openai/old-model", APIKey: "test"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "new-model", Model: "openai/new-model"},
+ {ModelName: "old-model", Model: "openai/old-model"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "new-model": {
+ APIKeys: []string{"test"},
+ },
+ "old-model": {
+ APIKeys: []string{"test"},
+ },
+ }})
output := captureStdout(func() {
err := setDefaultModel(configPath, cfg, "new-model")
@@ -180,44 +187,25 @@ func TestSetDefaultModel_ValidModel(t *testing.T) {
updatedCfg, err := config.LoadConfig(configPath)
require.NoError(t, err)
assert.Equal(t, "new-model", updatedCfg.Agents.Defaults.ModelName)
- assert.Empty(t, updatedCfg.Agents.Defaults.Model)
-}
-
-func TestSetDefaultModel_LegacyModelField(t *testing.T) {
- initTest(t)
-
- cfg := &config.Config{
- Agents: config.AgentsConfig{
- Defaults: config.AgentDefaults{
- Model: "legacy-old",
- },
- },
- ModelList: []config.ModelConfig{
- {ModelName: "new-model", Model: "openai/new-model", APIKey: "test"},
- },
- }
-
- output := captureStdout(func() {
- err := setDefaultModel(configPath, cfg, "new-model")
- assert.NoError(t, err)
- })
-
- assert.Contains(t, output, "Default model changed from 'legacy-old' to 'new-model'")
}
func TestSetDefaultModel_InvalidModel(t *testing.T) {
initTest(t)
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "existing-model",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "existing-model", Model: "openai/existing", APIKey: "test"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "existing-model", Model: "openai/existing"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "existing-model": {
+ APIKeys: []string{"test"},
+ },
+ }})
assert.Error(t, setDefaultModel(configPath, cfg, "nonexistent-model"))
}
@@ -225,17 +213,24 @@ func TestSetDefaultModel_InvalidModel(t *testing.T) {
func TestSetDefaultModel_ModelWithoutAPIKey(t *testing.T) {
initTest(t)
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "existing-model",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "existing-model", Model: "openai/existing", APIKey: "test"},
- {ModelName: "no-key-model", Model: "openai/nokey", APIKey: ""},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "existing-model", Model: "openai/existing"},
+ {ModelName: "no-key-model", Model: "openai/nokey"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "existing-model": {
+ APIKeys: []string{"test"},
+ },
+ "no-key-model": {
+ APIKeys: []string{""},
+ },
+ }})
assert.Error(t, setDefaultModel(configPath, cfg, "no-key-model"))
}
@@ -244,16 +239,20 @@ func TestSetDefaultModel_SaveConfigError(t *testing.T) {
// Use an invalid path to trigger save error
invalidPath := "/nonexistent/directory/config.json"
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "old-model",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "new-model", Model: "openai/new-model", APIKey: "test"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "new-model", Model: "openai/new-model"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "new-model": {
+ APIKeys: []string{"test"},
+ },
+ }})
err := setDefaultModel(invalidPath, cfg, "new-model")
@@ -285,16 +284,20 @@ func TestModelCommandExecution_Show(t *testing.T) {
initTest(t)
// Create a test config
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "test-model",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "test-model", Model: "openai/test", APIKey: "test"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "test-model", Model: "openai/test"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "test-model": {
+ APIKeys: []string{"test"},
+ },
+ }})
err := config.SaveConfig(configPath, cfg)
require.NoError(t, err)
@@ -312,17 +315,25 @@ func TestModelCommandExecution_Show(t *testing.T) {
func TestModelCommandExecution_Set(t *testing.T) {
initTest(t)
- cfg := &config.Config{
+ sec := &config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "old-model": {
+ APIKeys: []string{"test"},
+ },
+ "new-model": {
+ APIKeys: []string{"test"},
+ },
+ }}
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "old-model",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "old-model", Model: "openai/old", APIKey: "test"},
- {ModelName: "new-model", Model: "openai/new", APIKey: "test"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "old-model", Model: "openai/old"},
+ {ModelName: "new-model", Model: "openai/new"},
},
- }
+ }).WithSecurity(sec)
err := config.SaveConfig(configPath, cfg)
require.NoError(t, err)
@@ -346,18 +357,28 @@ func TestModelCommandExecution_TooManyArgs(t *testing.T) {
}
func TestListAvailableModels_MarkerLogic(t *testing.T) {
- cfg := &config.Config{
+ cfg := (&config.Config{
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
ModelName: "middle-model",
},
},
- ModelList: []config.ModelConfig{
- {ModelName: "first-model", Model: "openai/first", APIKey: "test"},
- {ModelName: "middle-model", Model: "openai/middle", APIKey: "test"},
- {ModelName: "last-model", Model: "openai/last", APIKey: "test"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "first-model", Model: "openai/first"},
+ {ModelName: "middle-model", Model: "openai/middle"},
+ {ModelName: "last-model", Model: "openai/last"},
},
- }
+ }).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "first-model": {
+ APIKeys: []string{"test"},
+ },
+ "middle-model": {
+ APIKeys: []string{"test"},
+ },
+ "last-model": {
+ APIKeys: []string{"test"},
+ },
+ }})
output := captureStdout(func() {
listAvailableModels(cfg)
diff --git a/cmd/picoclaw/internal/onboard/command.go b/cmd/picoclaw/internal/onboard/command.go
index 9f8b288c6..1f94c6718 100644
--- a/cmd/picoclaw/internal/onboard/command.go
+++ b/cmd/picoclaw/internal/onboard/command.go
@@ -16,14 +16,22 @@ func NewOnboardCommand() *cobra.Command {
cmd := &cobra.Command{
Use: "onboard",
Aliases: []string{"o"},
- Short: "Initialize picoclaw configuration and workspace",
+ Short: "Initialize picoclaw configuration, workspace, and channel accounts",
+ // Run without subcommands → original onboard flow
Run: func(cmd *cobra.Command, args []string) {
- onboard(encrypt)
+ if len(args) == 0 {
+ onboard(encrypt)
+ } else {
+ _ = cmd.Help()
+ }
},
}
cmd.Flags().BoolVar(&encrypt, "enc", false,
"Enable credential encryption (generates SSH key and prompts for passphrase)")
+ // Channel onboarding subcommands
+ cmd.AddCommand(newWeixinCommand())
+
return cmd
}
diff --git a/cmd/picoclaw/internal/onboard/command_test.go b/cmd/picoclaw/internal/onboard/command_test.go
index 56936190b..6b9fb6e95 100644
--- a/cmd/picoclaw/internal/onboard/command_test.go
+++ b/cmd/picoclaw/internal/onboard/command_test.go
@@ -13,7 +13,7 @@ func TestNewOnboardCommand(t *testing.T) {
require.NotNil(t, cmd)
assert.Equal(t, "onboard", cmd.Use)
- assert.Equal(t, "Initialize picoclaw configuration and workspace", cmd.Short)
+ assert.Equal(t, "Initialize picoclaw configuration, workspace, and channel accounts", cmd.Short)
assert.Len(t, cmd.Aliases, 1)
assert.True(t, cmd.HasAlias("o"))
@@ -28,5 +28,6 @@ func TestNewOnboardCommand(t *testing.T) {
encFlag := cmd.Flags().Lookup("enc")
require.NotNil(t, encFlag, "expected --enc flag to be registered")
assert.Equal(t, "false", encFlag.DefValue, "--enc should default to false")
- assert.False(t, cmd.HasSubCommands())
+ assert.True(t, cmd.HasSubCommands())
+ assert.NotNil(t, cmd.Commands())
}
diff --git a/cmd/picoclaw/internal/onboard/helpers_test.go b/cmd/picoclaw/internal/onboard/helpers_test.go
index f3e0c92e0..23fc97c5a 100644
--- a/cmd/picoclaw/internal/onboard/helpers_test.go
+++ b/cmd/picoclaw/internal/onboard/helpers_test.go
@@ -6,20 +6,32 @@ import (
"testing"
)
-func TestCopyEmbeddedToTargetUsesAgentsMarkdown(t *testing.T) {
+func TestCopyEmbeddedToTargetUsesStructuredAgentFiles(t *testing.T) {
targetDir := t.TempDir()
if err := copyEmbeddedToTarget(targetDir); err != nil {
t.Fatalf("copyEmbeddedToTarget() error = %v", err)
}
- agentsPath := filepath.Join(targetDir, "AGENTS.md")
- if _, err := os.Stat(agentsPath); err != nil {
- t.Fatalf("expected %s to exist: %v", agentsPath, err)
+ agentPath := filepath.Join(targetDir, "AGENT.md")
+ if _, err := os.Stat(agentPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", agentPath, err)
}
- legacyPath := filepath.Join(targetDir, "AGENT.md")
- if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
- t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+ soulPath := filepath.Join(targetDir, "SOUL.md")
+ if _, err := os.Stat(soulPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", soulPath, err)
+ }
+
+ userPath := filepath.Join(targetDir, "USER.md")
+ if _, err := os.Stat(userPath); err != nil {
+ t.Fatalf("expected %s to exist: %v", userPath, err)
+ }
+
+ for _, legacyName := range []string{"AGENTS.md", "IDENTITY.md"} {
+ legacyPath := filepath.Join(targetDir, legacyName)
+ if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
+ t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+ }
}
}
diff --git a/cmd/picoclaw/internal/onboard/weixin.go b/cmd/picoclaw/internal/onboard/weixin.go
new file mode 100644
index 000000000..2e1c2ad75
--- /dev/null
+++ b/cmd/picoclaw/internal/onboard/weixin.go
@@ -0,0 +1,124 @@
+package onboard
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ "github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+ "github.com/sipeed/picoclaw/pkg/channels/weixin"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func newWeixinCommand() *cobra.Command {
+ var baseURL string
+ var proxy string
+ var timeout int
+
+ cmd := &cobra.Command{
+ Use: "weixin",
+ Short: "Connect a WeChat personal account via QR code",
+ Long: `Start the interactive Weixin (WeChat personal) QR code login flow.
+
+A QR code is displayed in the terminal. Scan it with the WeChat mobile app
+to authorize your account. On success, the bot token is saved to the picoclaw
+config so you can start the gateway immediately.
+
+Example:
+ picoclaw onboard weixin`,
+ RunE: func(cmd *cobra.Command, _ []string) error {
+ return runWeixinOnboard(baseURL, proxy, time.Duration(timeout)*time.Second)
+ },
+ }
+
+ cmd.Flags().StringVar(&baseURL, "base-url", "https://ilinkai.weixin.qq.com/", "iLink API base URL")
+ cmd.Flags().StringVar(&proxy, "proxy", "", "HTTP proxy URL (e.g. http://localhost:7890)")
+ cmd.Flags().IntVar(&timeout, "timeout", 300, "Login timeout in seconds")
+
+ return cmd
+}
+
+func runWeixinOnboard(baseURL, proxy string, timeout time.Duration) error {
+ fmt.Println("Starting Weixin (WeChat personal) login...")
+ fmt.Println()
+
+ botToken, userID, accountID, returnedBaseURL, err := weixin.PerformLoginInteractive(
+ context.Background(),
+ weixin.AuthFlowOpts{
+ BaseURL: baseURL,
+ Timeout: timeout,
+ Proxy: proxy,
+ },
+ )
+ if err != nil {
+ return fmt.Errorf("login failed: %w", err)
+ }
+
+ fmt.Println()
+ fmt.Println("✅ Login successful!")
+ fmt.Printf(" Account ID : %s\n", accountID)
+ if userID != "" {
+ fmt.Printf(" User ID : %s\n", userID)
+ }
+ fmt.Println()
+
+ // Prefer the server-returned base URL (may be region-specific)
+ effectiveBaseURL := returnedBaseURL
+ if effectiveBaseURL == "" {
+ effectiveBaseURL = baseURL
+ }
+
+ if err := saveWeixinConfig(botToken, effectiveBaseURL, proxy); err != nil {
+ fmt.Printf("⚠️ Could not auto-save to config: %v\n", err)
+ printManualWeixinConfig(botToken, effectiveBaseURL)
+ return nil
+ }
+
+ fmt.Println("✓ Config updated. Start the gateway with:")
+ fmt.Println()
+ fmt.Println(" picoclaw gateway")
+ fmt.Println()
+ fmt.Println("To restrict which WeChat users can send messages, add their user IDs")
+ fmt.Println("to channels.weixin.allow_from in your config.")
+
+ return nil
+}
+
+// saveWeixinConfig patches channels.weixin in the config and saves it.
+func saveWeixinConfig(token, baseURL, proxy string) error {
+ cfgPath := internal.GetConfigPath()
+
+ cfg, err := config.LoadConfig(cfgPath)
+ if err != nil {
+ return fmt.Errorf("failed to load config: %w", err)
+ }
+
+ cfg.Channels.Weixin.Enabled = true
+ cfg.Channels.Weixin.SetToken(token)
+ const defaultBase = "https://ilinkai.weixin.qq.com/"
+ if baseURL != "" && baseURL != defaultBase {
+ cfg.Channels.Weixin.BaseURL = baseURL
+ }
+ if proxy != "" {
+ cfg.Channels.Weixin.Proxy = proxy
+ }
+
+ return config.SaveConfig(cfgPath, cfg)
+}
+
+func printManualWeixinConfig(token, baseURL string) {
+ fmt.Println()
+ fmt.Println("Add the following to the channels section of your picoclaw config:")
+ fmt.Println()
+ fmt.Println(` "weixin": {`)
+ fmt.Println(` "enabled": true,`)
+ fmt.Printf(" \"token\": %q,\n", token)
+ const defaultBase = "https://ilinkai.weixin.qq.com/"
+ if baseURL != "" && baseURL != defaultBase {
+ fmt.Printf(" \"base_url\": %q,\n", baseURL)
+ }
+ fmt.Println(` "allow_from": []`)
+ fmt.Println(` }`)
+}
diff --git a/cmd/picoclaw/internal/skills/command.go b/cmd/picoclaw/internal/skills/command.go
index 8c666b810..4f64ef3f9 100644
--- a/cmd/picoclaw/internal/skills/command.go
+++ b/cmd/picoclaw/internal/skills/command.go
@@ -31,7 +31,7 @@ func NewSkillsCommand() *cobra.Command {
d.workspace = cfg.WorkspacePath()
installer, err := skills.NewSkillInstaller(
d.workspace,
- cfg.Tools.Skills.Github.Token,
+ cfg.Tools.Skills.Github.Token(),
cfg.Tools.Skills.Github.Proxy,
)
if err != nil {
diff --git a/cmd/picoclaw/internal/skills/helpers.go b/cmd/picoclaw/internal/skills/helpers.go
index a59a2013a..a246f7da5 100644
--- a/cmd/picoclaw/internal/skills/helpers.go
+++ b/cmd/picoclaw/internal/skills/helpers.go
@@ -64,9 +64,20 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) er
fmt.Printf("Installing skill '%s' from %s registry...\n", slug, registryName)
+ clawHubConfig := cfg.Tools.Skills.Registries.ClawHub
registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
- ClawHub: skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+ ClawHub: skills.ClawHubConfig{
+ Enabled: clawHubConfig.Enabled,
+ BaseURL: clawHubConfig.BaseURL,
+ AuthToken: clawHubConfig.AuthToken(),
+ SearchPath: clawHubConfig.SearchPath,
+ SkillsPath: clawHubConfig.SkillsPath,
+ DownloadPath: clawHubConfig.DownloadPath,
+ Timeout: clawHubConfig.Timeout,
+ MaxZipSize: clawHubConfig.MaxZipSize,
+ MaxResponseSize: clawHubConfig.MaxResponseSize,
+ },
})
registry := registryMgr.GetRegistry(registryName)
@@ -226,9 +237,20 @@ func skillsSearchCmd(query string) {
return
}
+ clawHubConfig := cfg.Tools.Skills.Registries.ClawHub
registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
- ClawHub: skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+ ClawHub: skills.ClawHubConfig{
+ Enabled: clawHubConfig.Enabled,
+ BaseURL: clawHubConfig.BaseURL,
+ AuthToken: clawHubConfig.AuthToken(),
+ SearchPath: clawHubConfig.SearchPath,
+ SkillsPath: clawHubConfig.SkillsPath,
+ DownloadPath: clawHubConfig.DownloadPath,
+ Timeout: clawHubConfig.Timeout,
+ MaxZipSize: clawHubConfig.MaxZipSize,
+ MaxResponseSize: clawHubConfig.MaxResponseSize,
+ },
})
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
diff --git a/cmd/picoclaw/internal/status/helpers.go b/cmd/picoclaw/internal/status/helpers.go
index dd7063fe6..43c5786a8 100644
--- a/cmd/picoclaw/internal/status/helpers.go
+++ b/cmd/picoclaw/internal/status/helpers.go
@@ -42,48 +42,6 @@ func statusCmd() {
if _, err := os.Stat(configPath); err == nil {
fmt.Printf("Model: %s\n", cfg.Agents.Defaults.GetModelName())
- hasOpenRouter := cfg.Providers.OpenRouter.APIKey != ""
- hasAnthropic := cfg.Providers.Anthropic.APIKey != ""
- hasOpenAI := cfg.Providers.OpenAI.APIKey != ""
- hasGemini := cfg.Providers.Gemini.APIKey != ""
- hasZhipu := cfg.Providers.Zhipu.APIKey != ""
- hasQwen := cfg.Providers.Qwen.APIKey != ""
- hasGroq := cfg.Providers.Groq.APIKey != ""
- hasVLLM := cfg.Providers.VLLM.APIBase != ""
- hasMoonshot := cfg.Providers.Moonshot.APIKey != ""
- hasDeepSeek := cfg.Providers.DeepSeek.APIKey != ""
- hasVolcEngine := cfg.Providers.VolcEngine.APIKey != ""
- hasNvidia := cfg.Providers.Nvidia.APIKey != ""
- hasOllama := cfg.Providers.Ollama.APIBase != ""
-
- status := func(enabled bool) string {
- if enabled {
- return "✓"
- }
- return "not set"
- }
- fmt.Println("OpenRouter API:", status(hasOpenRouter))
- fmt.Println("Anthropic API:", status(hasAnthropic))
- fmt.Println("OpenAI API:", status(hasOpenAI))
- fmt.Println("Gemini API:", status(hasGemini))
- fmt.Println("Zhipu API:", status(hasZhipu))
- fmt.Println("Qwen API:", status(hasQwen))
- fmt.Println("Groq API:", status(hasGroq))
- fmt.Println("Moonshot API:", status(hasMoonshot))
- fmt.Println("DeepSeek API:", status(hasDeepSeek))
- fmt.Println("VolcEngine API:", status(hasVolcEngine))
- fmt.Println("Nvidia API:", status(hasNvidia))
- if hasVLLM {
- fmt.Printf("vLLM/Local: ✓ %s\n", cfg.Providers.VLLM.APIBase)
- } else {
- fmt.Println("vLLM/Local: not set")
- }
- if hasOllama {
- fmt.Printf("Ollama: ✓ %s\n", cfg.Providers.Ollama.APIBase)
- } else {
- fmt.Println("Ollama: not set")
- }
-
store, _ := auth.LoadStore()
if store != nil && len(store.Credentials) > 0 {
fmt.Println("\nOAuth/Token Auth:")
diff --git a/config/config.example.json b/config/config.example.json
index 221e89491..88578701a 100644
--- a/config/config.example.json
+++ b/config/config.example.json
@@ -5,6 +5,7 @@
"restrict_to_workspace": true,
"model_name": "gpt-5.4",
"max_tokens": 8192,
+ "context_window": 131072,
"temperature": 0.7,
"max_tool_iterations": 20,
"summarize_message_threshold": 20,
@@ -84,7 +85,10 @@
"proxy": "",
"allow_from": ["YOUR_USER_ID"],
"use_markdown_v2": false,
- "reasoning_channel_id": ""
+ "reasoning_channel_id": "",
+ "streaming": {
+ "enabled": true
+ }
},
"discord": {
"enabled": false,
@@ -213,6 +217,25 @@
"welcome_message": "Hello! I'm your AI assistant. How can I help you today?",
"reasoning_channel_id": ""
},
+ "pico": {
+ "enabled": false,
+ "token": "YOUR_PICO_TOKEN",
+ "allow_token_query": false,
+ "allow_origins": [],
+ "ping_interval": 30,
+ "read_timeout": 60,
+ "max_connections": 100,
+ "allow_from": []
+ },
+ "pico_client": {
+ "enabled": false,
+ "url": "wss://remote-pico-server/pico/ws",
+ "token": "YOUR_PICO_TOKEN",
+ "session_id": "",
+ "ping_interval": 30,
+ "read_timeout": 60,
+ "allow_from": []
+ },
"irc": {
"enabled": false,
"server": "irc.libera.chat:6697",
@@ -524,11 +547,22 @@
"monitor_usb": true
},
"voice": {
+ "model_name": "",
"echo_transcription": false
},
+ "hooks": {
+ "enabled": true,
+ "defaults": {
+ "observer_timeout_ms": 500,
+ "interceptor_timeout_ms": 5000,
+ "approval_timeout_ms": 60000
+ }
+ },
"gateway": {
+ "_comment": "Default log level is set to 'fatal'. Other available options are 'debug', 'info', 'warn' and 'error'.",
"host": "127.0.0.1",
"port": 18790,
- "hot_reload": false
+ "hot_reload": false,
+ "log_level": "fatal"
}
}
diff --git a/docker/Dockerfile.heavy b/docker/Dockerfile.heavy
new file mode 100644
index 000000000..cbc243e39
--- /dev/null
+++ b/docker/Dockerfile.heavy
@@ -0,0 +1,67 @@
+# ============================================================
+# Stage 1: Build the picoclaw binary
+# ============================================================
+FROM golang:1.26.0-alpine AS builder
+
+RUN apk add --no-cache git make
+
+WORKDIR /src
+
+# Cache dependencies
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source and build
+COPY . .
+RUN make build
+
+# ============================================================
+# Stage 2: Node.js runtime with Python + MCP support
+# ============================================================
+FROM node:24-alpine3.23
+
+RUN apk add --no-cache \
+ ca-certificates \
+ curl \
+ git \
+ python3 \
+ py3-pip \
+ chromium \
+ jq
+
+# Install Playwright browsers for agent-browser
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers
+RUN npm install -g agent-browser && \
+ npx playwright install chromium && \
+ chmod -R o+rx $PLAYWRIGHT_BROWSERS_PATH
+
+# Install uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
+ ln -s /root/.local/bin/uv /usr/local/bin/uv && \
+ ln -s /root/.local/bin/uvx /usr/local/bin/uvx && \
+ uv --version
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+ CMD wget -q --spider http://localhost:18790/health || exit 1
+
+# Copy binary
+COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
+
+# Reuse existing node user (UID/GID 1000) — rename to picoclaw
+RUN deluser node 2>/dev/null; delgroup node 2>/dev/null; \
+ addgroup -g 1000 picoclaw 2>/dev/null; \
+ adduser -D -u 1000 -G picoclaw -h /home/picoclaw picoclaw 2>/dev/null || true
+
+USER picoclaw
+
+# Run onboard to create initial directories and config
+RUN /usr/local/bin/picoclaw onboard
+
+# Copy default workspace
+COPY --chown=picoclaw:picoclaw workspace/ /home/picoclaw/.picoclaw/workspace/
+
+VOLUME /home/picoclaw/.picoclaw/workspace
+
+ENTRYPOINT ["picoclaw"]
+CMD ["gateway"]
diff --git a/docs/ANTIGRAVITY_AUTH.md b/docs/ANTIGRAVITY_AUTH.md
index 89261d899..d88d73c8d 100644
--- a/docs/ANTIGRAVITY_AUTH.md
+++ b/docs/ANTIGRAVITY_AUTH.md
@@ -438,7 +438,7 @@ type ProviderAuthResult = {
### 1. Required Environment/Dependencies
-- Go ≥ 1.21
+- Go ≥ 1.25
- PicoClaw codebase (`pkg/providers/` and `pkg/auth/`)
- `crypto` and `net/http` standard library packages
@@ -584,7 +584,7 @@ Each SSE message (`data: {...}`) is wrapped in a `response` field:
],
"agents": {
"defaults": {
- "model": "gemini-flash"
+ "model_name": "gemini-flash"
}
}
}
@@ -674,7 +674,7 @@ Add a default entry in `pkg/config/defaults.go`:
#### 5. Add Auth Support (Optional)
-If your provider requires OAuth or special authentication, add a case to `cmd/picoclaw/cmd_auth.go`:
+If your provider requires OAuth or special authentication, add a case to `cmd/picoclaw/internal/auth/helpers.go`:
```go
case "your-provider":
@@ -736,7 +736,7 @@ export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/m
- `pkg/auth/store.go` - Auth credential storage (`~/.picoclaw/auth.json`)
- `pkg/providers/factory.go` - Provider factory and protocol routing
- `pkg/providers/types.go` - Provider interface definitions
- - `cmd/picoclaw/cmd_auth.go` - Auth CLI commands
+ - `cmd/picoclaw/internal/auth/helpers.go` - Auth CLI commands
- **Documentation:**
- `docs/ANTIGRAVITY_USAGE.md` - Antigravity usage guide
diff --git a/docs/agent-refactor/context.md b/docs/agent-refactor/context.md
new file mode 100644
index 000000000..2269d9258
--- /dev/null
+++ b/docs/agent-refactor/context.md
@@ -0,0 +1,164 @@
+# Context
+
+## What this document covers
+
+This document makes explicit the boundaries of context management in the agent loop:
+
+- what fills the context window and how space is divided
+- what is stored in session history vs. built at request time
+- when and how context compression happens
+- how token budgets are estimated
+
+These are existing concepts. This document clarifies their boundaries rather than introducing new ones.
+
+---
+
+## Context window regions
+
+The context window is the model's total input capacity. Four regions fill it:
+
+| Region | Assembled by | Stored in session? |
+|---|---|---|
+| System prompt | `BuildMessages()` — static + dynamic parts | No |
+| Summary | `SetSummary()` stores it; `BuildMessages()` injects it | Separate from history |
+| Session history | User / assistant / tool messages | Yes |
+| Tool definitions | Provider adapter injects at call time | No |
+
+`MaxTokens` (the output generation limit) must also be reserved from the total budget.
+
+The available space for history is therefore:
+
+```
+history_budget = ContextWindow - system_prompt - summary - tool_definitions - MaxTokens
+```
+
+---
+
+## ContextWindow vs MaxTokens
+
+These serve different purposes:
+
+- **MaxTokens** — maximum tokens the LLM may generate in one response. Sent as the `max_tokens` request parameter.
+- **ContextWindow** — the model's total input context capacity.
+
+These were previously set to the same value, which caused the summarization threshold to fire either far too early (at the default 32K) or not at all (when a user raised `max_tokens`).
+
+Current default when not explicitly configured: `ContextWindow = MaxTokens * 4`.
+
+---
+
+## Session history
+
+Session history stores only conversation messages:
+
+- `user` — user input
+- `assistant` — LLM response (may include `ToolCalls`)
+- `tool` — tool execution results
+
+Session history does **not** contain:
+
+- System prompts — assembled at request time by `BuildMessages`
+- Summary content — stored separately via `SetSummary`, injected by `BuildMessages`
+
+This distinction matters: any code that operates on session history — compression, boundary detection, token estimation — must not assume a system message is present.
+
+---
+
+## Turn
+
+A **Turn** is one complete cycle:
+
+> user message -> LLM iterations (possibly including tool calls) -> final assistant response
+
+This definition comes from the agent loop design (#1316). In session history, Turn boundaries are identified by `user`-role messages.
+
+Turn is the atomic unit for compression. Cutting inside a Turn can orphan tool-call sequences — an assistant message with `ToolCalls` separated from its corresponding `tool` results. Compressing at Turn boundaries avoids this by construction.
+
+`parseTurnBoundaries(history)` returns the starting index of each Turn.
+`findSafeBoundary(history, targetIndex)` snaps a target cut point to the nearest Turn boundary.
+
+---
+
+## Compression paths
+
+Three compression paths exist, in order of preference:
+
+### 1. Async summarization
+
+`maybeSummarize` runs after each Turn completes.
+
+Triggers when message count exceeds a threshold, or when estimated history tokens exceed a percentage of `ContextWindow`. If triggered, a background goroutine calls the LLM to produce a summary of the oldest messages. The summary is stored via `SetSummary`; `BuildMessages` injects it into the system prompt on the next call.
+
+Cut point uses `findSafeBoundary` so no Turn is split.
+
+### 2. Proactive budget check
+
+`isOverContextBudget` runs before each LLM call.
+
+Uses the full budget formula: `message_tokens + tool_def_tokens + MaxTokens > ContextWindow`. If over budget, triggers `forceCompression` and rebuilds messages before calling the LLM.
+
+This prevents wasted (and billed) LLM calls that would otherwise fail with a context-window error.
+
+### 3. Emergency compression (reactive)
+
+`forceCompression` runs when the LLM returns a context-window error despite the proactive check.
+
+Drops the oldest ~50% of Turns. If the history is a single Turn with no safe split point (e.g. one user message followed by a massive tool response), falls back to keeping only the most recent user message — breaking Turn atomicity as a last resort to avoid a context-exceeded loop.
+
+Stores a compression note in the session summary (not in history messages) so `BuildMessages` can include it in the next system prompt.
+
+This is the fallback for when the token estimate undershoots reality.
+
+---
+
+## Token estimation
+
+Estimation uses a heuristic of ~2.5 characters per token (`chars * 2 / 5`).
+
+`estimateMessageTokens` counts:
+
+- `Content` (rune count, for multibyte correctness)
+- `ReasoningContent` (extended thinking / chain-of-thought)
+- `ToolCalls` — ID, type, function name, arguments
+- `ToolCallID` (tool result metadata)
+- Per-message overhead (role label, JSON structure)
+- `Media` items — flat per-item token estimate, added directly to the final count (not through the character heuristic, since actual cost depends on resolution and provider-specific image tokenization)
+
+`estimateToolDefsTokens` counts tool definition overhead: name, description, JSON schema of parameters.
+
+These are deliberately heuristic. The proactive check handles the common case; the reactive path catches estimation errors.
+
+---
+
+## Interface boundaries
+
+Context budget functions (`parseTurnBoundaries`, `findSafeBoundary`, `estimateMessageTokens`, `isOverContextBudget`) are **pure functions**. They take `[]providers.Message` and integer parameters. They have no dependency on `AgentLoop` or any other runtime struct.
+
+`BuildMessages` is the sole assembler of the final message array sent to the LLM. Budget functions inform compression decisions but do not construct messages.
+
+`forceCompression` and `summarizeSession` mutate session state (history and summary). `BuildMessages` reads that state to construct context. The flow is:
+
+```
+budget check --> compression decision --> mutate session --> BuildMessages reads session --> LLM call
+```
+
+---
+
+## Known gaps
+
+These are recognized limitations in the current implementation, documented here for visibility:
+
+- **Summarization trigger does not use the full budget formula.** `maybeSummarize` compares estimated history tokens against a percentage of `ContextWindow`. It does not account for system prompt size, tool definition overhead, or `MaxTokens` reserve. The proactive check covers the critical path (preventing 400 errors), but the summarization trigger could be aligned with the same budget model for more accurate early compression.
+
+- **Token estimation is heuristic.** It does not account for provider-specific tokenization, exact system prompt size (assembled separately), or variable image token costs. The two-path design (proactive + reactive) is intended to tolerate this imprecision.
+
+- **Reactive retry does not preserve media.** When the reactive path rebuilds context after compression, it currently passes empty values for media references. This is a pre-existing issue in the main loop, not introduced by the budget system.
+
+---
+
+## What this document does not cover
+
+- How `AGENT.md` frontmatter configures context parameters — that is part of the Agent definition work
+- How the context builder assembles context in the new architecture — that is upcoming work
+- How compression events surface through the event system — that is part of the event model (#1316)
+- Subagent context isolation — that is a separate track
diff --git a/docs/channels/dingtalk/README.fr.md b/docs/channels/dingtalk/README.fr.md
new file mode 100644
index 000000000..969346d65
--- /dev/null
+++ b/docs/channels/dingtalk/README.fr.md
@@ -0,0 +1,35 @@
+> Retour au [README](../../../README.fr.md)
+
+# DingTalk
+
+DingTalk est la plateforme de communication d'entreprise d'Alibaba, très populaire dans les milieux professionnels chinois. Elle utilise un SDK de streaming pour maintenir des connexions persistantes.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "dingtalk": {
+ "enabled": true,
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ------------- | ------ | ------ | ---------------------------------------------------------------- |
+| enabled | bool | Oui | Activer ou non le canal DingTalk |
+| client_id | string | Oui | Client ID de l'application DingTalk |
+| client_secret | string | Oui | Client Secret de l'application DingTalk |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
+
+## Procédure de configuration
+
+1. Rendez-vous sur la [plateforme ouverte DingTalk](https://open.dingtalk.com/)
+2. Créez une application interne d'entreprise
+3. Obtenez le Client ID et le Client Secret depuis les paramètres de l'application
+4. Configurez OAuth et les abonnements aux événements (si nécessaire)
+5. Renseignez le Client ID et le Client Secret dans le fichier de configuration
diff --git a/docs/channels/dingtalk/README.ja.md b/docs/channels/dingtalk/README.ja.md
new file mode 100644
index 000000000..d44a87820
--- /dev/null
+++ b/docs/channels/dingtalk/README.ja.md
@@ -0,0 +1,35 @@
+> [README](../../../README.ja.md) に戻る
+
+# DingTalk
+
+DingTalkはアリババの企業向けコミュニケーションプラットフォームで、中国のビジネス環境で広く利用されています。ストリーミング SDK を使用して持続的な接続を維持します。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "dingtalk": {
+ "enabled": true,
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ------------- | ------ | ---- | -------------------------------------------- |
+| enabled | bool | はい | DingTalk チャンネルを有効にするかどうか |
+| client_id | string | はい | DingTalk アプリケーションの Client ID |
+| client_secret | string | はい | DingTalk アプリケーションの Client Secret |
+| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
+
+## セットアップ手順
+
+1. [DingTalk オープンプラットフォーム](https://open.dingtalk.com/) にアクセスする
+2. 企業内部アプリケーションを作成する
+3. アプリケーション設定から Client ID と Client Secret を取得する
+4. OAuth とイベントサブスクリプションを設定する（必要な場合）
+5. Client ID と Client Secret を設定ファイルに入力する
diff --git a/docs/channels/dingtalk/README.md b/docs/channels/dingtalk/README.md
new file mode 100644
index 000000000..a3f23a1e6
--- /dev/null
+++ b/docs/channels/dingtalk/README.md
@@ -0,0 +1,35 @@
+> Back to [README](../../../README.md)
+
+# DingTalk
+
+DingTalk is Alibaba's enterprise communication platform, widely used in Chinese workplaces. It uses a streaming SDK to maintain persistent connections.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "dingtalk": {
+ "enabled": true,
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ------------- | ------ | -------- | -------------------------------------------------------- |
+| enabled | bool | Yes | Whether to enable the DingTalk channel |
+| client_id | string | Yes | Client ID of the DingTalk application |
+| client_secret | string | Yes | Client Secret of the DingTalk application |
+| allow_from | array | No | User ID whitelist; empty means all users are allowed |
+
+## Setup
+
+1. Go to the [DingTalk Open Platform](https://open.dingtalk.com/)
+2. Create an internal enterprise application
+3. Obtain the Client ID and Client Secret from the application settings
+4. Configure OAuth and event subscriptions (if needed)
+5. Fill in the Client ID and Client Secret in the configuration file
diff --git a/docs/channels/dingtalk/README.pt-br.md b/docs/channels/dingtalk/README.pt-br.md
new file mode 100644
index 000000000..f9056217f
--- /dev/null
+++ b/docs/channels/dingtalk/README.pt-br.md
@@ -0,0 +1,35 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# DingTalk
+
+DingTalk é a plataforma de comunicação empresarial da Alibaba, amplamente utilizada no ambiente corporativo chinês. Ela usa um SDK de streaming para manter conexões persistentes.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "dingtalk": {
+ "enabled": true,
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ------------- | ------ | ----------- | ---------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal DingTalk deve ser habilitado |
+| client_id | string | Sim | Client ID do aplicativo DingTalk |
+| client_secret | string | Sim | Client Secret do aplicativo DingTalk |
+| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
+
+## Configuração passo a passo
+
+1. Acesse a [Plataforma Aberta DingTalk](https://open.dingtalk.com/)
+2. Crie um aplicativo interno corporativo
+3. Obtenha o Client ID e o Client Secret nas configurações do aplicativo
+4. Configure OAuth e assinaturas de eventos (se necessário)
+5. Preencha o Client ID e o Client Secret no arquivo de configuração
diff --git a/docs/channels/dingtalk/README.vi.md b/docs/channels/dingtalk/README.vi.md
new file mode 100644
index 000000000..8c060a382
--- /dev/null
+++ b/docs/channels/dingtalk/README.vi.md
@@ -0,0 +1,35 @@
+> Quay lại [README](../../../README.vi.md)
+
+# DingTalk
+
+DingTalk là nền tảng giao tiếp doanh nghiệp của Alibaba, được sử dụng rộng rãi trong môi trường làm việc tại Trung Quốc. Nền tảng này sử dụng SDK streaming để duy trì kết nối liên tục.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "dingtalk": {
+ "enabled": true,
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ------------- | ------ | -------- | ---------------------------------------------------------------- |
+| enabled | bool | Có | Có bật kênh DingTalk hay không |
+| client_id | string | Có | Client ID của ứng dụng DingTalk |
+| client_secret | string | Có | Client Secret của ứng dụng DingTalk |
+| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
+
+## Quy trình thiết lập
+
+1. Truy cập [Nền tảng mở DingTalk](https://open.dingtalk.com/)
+2. Tạo một ứng dụng nội bộ doanh nghiệp
+3. Lấy Client ID và Client Secret từ cài đặt ứng dụng
+4. Cấu hình OAuth và đăng ký sự kiện (nếu cần)
+5. Điền Client ID và Client Secret vào file cấu hình
diff --git a/docs/channels/dingtalk/README.zh.md b/docs/channels/dingtalk/README.zh.md
index 1e445d0b0..bdaaa1ee1 100644
--- a/docs/channels/dingtalk/README.zh.md
+++ b/docs/channels/dingtalk/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# 钉钉
钉钉是阿里巴巴的企业通讯平台，在中国职场中广受欢迎。它采用流式 SDK 来维持持久连接。
diff --git a/docs/channels/discord/README.fr.md b/docs/channels/discord/README.fr.md
new file mode 100644
index 000000000..61c34abb9
--- /dev/null
+++ b/docs/channels/discord/README.fr.md
@@ -0,0 +1,39 @@
+> Retour au [README](../../../README.fr.md)
+
+# Discord
+
+Discord est une application gratuite de chat vocal, vidéo et textuel conçue pour les communautés. PicoClaw se connecte aux serveurs Discord via l'API Bot Discord, avec prise en charge de la réception et de l'envoi de messages.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "discord": {
+ "enabled": true,
+ "token": "YOUR_BOT_TOKEN",
+ "allow_from": ["YOUR_USER_ID"],
+ "group_trigger": {
+ "mention_only": false
+ }
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ------------- | ------ | ------ | --------------------------------------------------------------------------- |
+| enabled | bool | Oui | Activer ou non le canal Discord |
+| token | string | Oui | Token du bot Discord |
+| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
+| group_trigger | object | Non | Paramètres de déclenchement de groupe (exemple : { "mention_only": false }) |
+
+## Configuration initiale
+
+1. Accéder au [Portail des développeurs Discord](https://discord.com/developers/applications) et créer une nouvelle application
+2. Activer les Intents :
+ - Message Content Intent
+ - Server Members Intent
+3. Obtenir le Token du bot
+4. Renseigner le Token du bot dans le fichier de configuration
+5. Inviter le bot sur le serveur et lui accorder les permissions nécessaires (ex. envoyer des messages, lire l'historique des messages)
diff --git a/docs/channels/discord/README.ja.md b/docs/channels/discord/README.ja.md
new file mode 100644
index 000000000..ecce30059
--- /dev/null
+++ b/docs/channels/discord/README.ja.md
@@ -0,0 +1,39 @@
+> [README](../../../README.ja.md) に戻る
+
+# Discord
+
+Discord はコミュニティ向けに設計された無料の音声・ビデオ・テキストチャットアプリケーションです。PicoClaw は Discord Bot API を通じて Discord サーバーに接続し、メッセージの受信と送信をサポートします。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "discord": {
+ "enabled": true,
+ "token": "YOUR_BOT_TOKEN",
+ "allow_from": ["YOUR_USER_ID"],
+ "group_trigger": {
+ "mention_only": false
+ }
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ------------- | ------ | ------ | ----------------------------------------------------------------- |
+| enabled | bool | はい | Discord チャンネルを有効にするかどうか |
+| token | string | はい | Discord ボットトークン |
+| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
+| group_trigger | object | いいえ | グループトリガー設定（例: { "mention_only": false }） |
+
+## セットアップ手順
+
+1. [Discord 開発者ポータル](https://discord.com/developers/applications) にアクセスして新しいアプリケーションを作成する
+2. Intents を有効にする:
+ - Message Content Intent
+ - Server Members Intent
+3. Bot トークンを取得する
+4. 設定ファイルに Bot トークンを入力する
+5. ボットをサーバーに招待し、必要な権限を付与する（例: メッセージの送信、メッセージ履歴の読み取りなど）
diff --git a/docs/channels/discord/README.md b/docs/channels/discord/README.md
new file mode 100644
index 000000000..e1ce7ab06
--- /dev/null
+++ b/docs/channels/discord/README.md
@@ -0,0 +1,39 @@
+> Back to [README](../../../README.md)
+
+# Discord
+
+Discord is a free voice, video, and text chat application designed for communities. PicoClaw connects to Discord servers via the Discord Bot API, supporting both receiving and sending messages.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "discord": {
+ "enabled": true,
+ "token": "YOUR_BOT_TOKEN",
+ "allow_from": ["YOUR_USER_ID"],
+ "group_trigger": {
+ "mention_only": false
+ }
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| enabled | bool | Yes | Whether to enable the Discord channel |
+| token | string | Yes | Discord Bot Token |
+| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
+| group_trigger | object | No | Group trigger settings (example: { "mention_only": false }) |
+
+## Setup
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create a new application
+2. Enable Intents:
+ - Message Content Intent
+ - Server Members Intent
+3. Obtain the Bot Token
+4. Fill in the Bot Token in the configuration file
+5. Invite the bot to your server and grant the necessary permissions (e.g. Send Messages, Read Message History)
diff --git a/docs/channels/discord/README.pt-br.md b/docs/channels/discord/README.pt-br.md
new file mode 100644
index 000000000..c9ed2809b
--- /dev/null
+++ b/docs/channels/discord/README.pt-br.md
@@ -0,0 +1,39 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Discord
+
+Discord é um aplicativo gratuito de chat de voz, vídeo e texto projetado para comunidades. O PicoClaw se conecta a servidores Discord via Discord Bot API, com suporte para receber e enviar mensagens.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "discord": {
+ "enabled": true,
+ "token": "YOUR_BOT_TOKEN",
+ "allow_from": ["YOUR_USER_ID"],
+ "group_trigger": {
+ "mention_only": false
+ }
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ------------- | ------ | ----------- | --------------------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal Discord deve ser habilitado |
+| token | string | Sim | Token do Bot Discord |
+| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
+| group_trigger | object | Não | Configurações de gatilho de grupo (exemplo: { "mention_only": false }) |
+
+## Configuração inicial
+
+1. Acesse o [Portal de Desenvolvedores do Discord](https://discord.com/developers/applications) e crie uma nova aplicação
+2. Habilite os Intents:
+ - Message Content Intent
+ - Server Members Intent
+3. Obtenha o Token do Bot
+4. Preencha o Token do Bot no arquivo de configuração
+5. Convide o bot para o servidor e conceda as permissões necessárias (ex. enviar mensagens, ler histórico de mensagens)
diff --git a/docs/channels/discord/README.vi.md b/docs/channels/discord/README.vi.md
new file mode 100644
index 000000000..7073b04f1
--- /dev/null
+++ b/docs/channels/discord/README.vi.md
@@ -0,0 +1,39 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Discord
+
+Discord là ứng dụng chat thoại, video và văn bản miễn phí được thiết kế cho cộng đồng. PicoClaw kết nối với máy chủ Discord qua Discord Bot API, hỗ trợ nhận và gửi tin nhắn.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "discord": {
+ "enabled": true,
+ "token": "YOUR_BOT_TOKEN",
+ "allow_from": ["YOUR_USER_ID"],
+ "group_trigger": {
+ "mention_only": false
+ }
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| enabled | bool | Có | Có bật kênh Discord hay không |
+| token | string | Có | Token Bot Discord |
+| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
+| group_trigger | object | Không | Cài đặt kích hoạt nhóm (ví dụ: { "mention_only": false }) |
+
+## Hướng dẫn thiết lập
+
+1. Truy cập [Discord Developer Portal](https://discord.com/developers/applications) và tạo ứng dụng mới
+2. Bật các Intents:
+ - Message Content Intent
+ - Server Members Intent
+3. Lấy Bot Token
+4. Điền Bot Token vào file cấu hình
+5. Mời bot vào máy chủ và cấp các quyền cần thiết (ví dụ: gửi tin nhắn, đọc lịch sử tin nhắn)
diff --git a/docs/channels/discord/README.zh.md b/docs/channels/discord/README.zh.md
index 6d3c502cf..673af4854 100644
--- a/docs/channels/discord/README.zh.md
+++ b/docs/channels/discord/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# Discord
Discord 是一个专为社区设计的免费语音、视频和文本聊天应用。PicoClaw 通过 Discord Bot API 连接到 Discord 服务器，支持接收和发送消息。
diff --git a/docs/channels/feishu/README.fr.md b/docs/channels/feishu/README.fr.md
new file mode 100644
index 000000000..f1ff26480
--- /dev/null
+++ b/docs/channels/feishu/README.fr.md
@@ -0,0 +1,52 @@
+> Retour au [README](../../../README.fr.md)
+
+# Feishu
+
+Feishu (nom international : Lark) est une plateforme de collaboration d'entreprise de ByteDance. Elle prend en charge les marchés chinois et mondiaux via des connexions WebSocket pilotées par événements.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "feishu": {
+ "enabled": true,
+ "app_id": "cli_xxx",
+ "app_secret": "xxx",
+ "encrypt_key": "",
+ "verification_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| --------------------- | ------ | ------ | --------------------------------------------------------------------------- |
+| enabled | bool | Oui | Activer ou non le canal Feishu |
+| app_id | string | Oui | App ID de l'application Feishu (commence par `cli_`) |
+| app_secret | string | Oui | App Secret de l'application Feishu |
+| encrypt_key | string | Non | Clé de chiffrement pour les callbacks d'événements |
+| verification_token | string | Non | Token utilisé pour la vérification des événements Webhook |
+| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
+| random_reaction_emoji | array | Non | Liste d'emojis de réaction aléatoires ; vide utilise le "Pin" par défaut |
+
+## Configuration initiale
+
+1. Accéder à la [plateforme ouverte Feishu](https://open.feishu.cn/) et créer une application
+2. Activer la capacité **Bot** dans les paramètres de l'application
+3. Créer une version et publier l'application (la configuration prend effet après la publication)
+4. Obtenir l'**App ID** (commence par `cli_`) et l'**App Secret**
+5. Renseigner l'App ID et l'App Secret dans le fichier de configuration PicoClaw
+6. Exécuter `picoclaw gateway` pour démarrer le service
+7. Rechercher le nom du bot dans Feishu et commencer une conversation
+
+> PicoClaw se connecte à Feishu en mode WebSocket/SDK — aucune adresse de callback publique ni URL Webhook n'est requise.
+>
+> `encrypt_key` et `verification_token` sont optionnels ; l'activation du chiffrement des événements est recommandée pour les environnements de production.
+>
+> Pour les références d'emojis personnalisés, voir : [Liste des emojis Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## Limitations de plateforme
+
+> ⚠️ **Le canal Feishu ne prend pas en charge les appareils 32 bits.** Le SDK Feishu ne fournit que des builds 64 bits. Les architectures 32 bits (armv6, armv7, mipsle, etc.) ne peuvent pas utiliser le canal Feishu. Pour la messagerie sur des appareils 32 bits, utilisez Telegram, Discord ou OneBot.
diff --git a/docs/channels/feishu/README.ja.md b/docs/channels/feishu/README.ja.md
new file mode 100644
index 000000000..4bb75a734
--- /dev/null
+++ b/docs/channels/feishu/README.ja.md
@@ -0,0 +1,52 @@
+> [README](../../../README.ja.md) に戻る
+
+# 飛書（Feishu）
+
+飛書（国際名：Lark）は ByteDance が提供するエンタープライズコラボレーションプラットフォームです。イベント駆動型の WebSocket 接続を通じて、中国および世界市場の両方をサポートします。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "feishu": {
+ "enabled": true,
+ "app_id": "cli_xxx",
+ "app_secret": "xxx",
+ "encrypt_key": "",
+ "verification_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| --------------------- | ------ | ------ | ----------------------------------------------------------------- |
+| enabled | bool | はい | 飛書チャンネルを有効にするかどうか |
+| app_id | string | はい | 飛書アプリケーションの App ID（`cli_` で始まる） |
+| app_secret | string | はい | 飛書アプリケーションの App Secret |
+| encrypt_key | string | いいえ | イベントコールバックの暗号化キー |
+| verification_token | string | いいえ | Webhook イベント検証に使用するトークン |
+| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
+| random_reaction_emoji | array | いいえ | ランダムに追加する絵文字のリスト。空の場合はデフォルトの "Pin" を使用 |
+
+## セットアップ手順
+
+1. [飛書オープンプラットフォーム](https://open.feishu.cn/) にアクセスしてアプリケーションを作成する
+2. アプリケーション設定で**ボット**機能を有効にする
+3. バージョンを作成してアプリケーションを公開する（公開後に設定が有効になる）
+4. **App ID**（`cli_` で始まる）と **App Secret** を取得する
+5. PicoClaw 設定ファイルに App ID と App Secret を入力する
+6. `picoclaw gateway` を実行してサービスを起動する
+7. 飛書でボット名を検索して会話を始める
+
+> PicoClaw は WebSocket/SDK モードで飛書に接続するため、公開コールバックアドレスや Webhook URL の設定は不要です。
+>
+> `encrypt_key` と `verification_token` はオプションですが、本番環境ではイベント暗号化を有効にすることを推奨します。
+>
+> カスタム絵文字の参考：[飛書絵文字リスト](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## プラットフォーム制限
+
+> ⚠️ **飛書チャネルは 32 ビットデバイスをサポートしていません。** 飛書 SDK は 64 ビットビルドのみ提供しています。armv6 / armv7 / mipsle などの 32 ビットアーキテクチャでは飛書チャネルを使用できません。32 ビットデバイスでのメッセージングには、Telegram、Discord、または OneBot をご利用ください。
diff --git a/docs/channels/feishu/README.md b/docs/channels/feishu/README.md
new file mode 100644
index 000000000..2aeaa31cb
--- /dev/null
+++ b/docs/channels/feishu/README.md
@@ -0,0 +1,52 @@
+> Back to [README](../../../README.md)
+
+# Feishu
+
+Feishu (international name: Lark) is an enterprise collaboration platform by ByteDance. It supports both Chinese and global markets through event-driven WebSocket connections.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "feishu": {
+ "enabled": true,
+ "app_id": "cli_xxx",
+ "app_secret": "xxx",
+ "encrypt_key": "",
+ "verification_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| --------------------- | ------ | -------- | ------------------------------------------------------------------ |
+| enabled | bool | Yes | Whether to enable the Feishu channel |
+| app_id | string | Yes | App ID of the Feishu application (starts with `cli_`) |
+| app_secret | string | Yes | App Secret of the Feishu application |
+| encrypt_key | string | No | Encryption key for event callbacks |
+| verification_token | string | No | Token used for Webhook event verification |
+| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
+| random_reaction_emoji | array | No | List of random reaction emojis; empty uses the default "Pin" |
+
+## Setup
+
+1. Go to the [Feishu Open Platform](https://open.feishu.cn/) and create an application
+2. Enable the **Bot** capability in the application settings
+3. Create a version and publish the application (configuration takes effect only after publishing)
+4. Obtain the **App ID** (starts with `cli_`) and **App Secret**
+5. Fill in the App ID and App Secret in the PicoClaw configuration file
+6. Run `picoclaw gateway` to start the service
+7. Search for the bot name in Feishu and start a conversation
+
+> PicoClaw connects to Feishu using WebSocket/SDK mode — no public callback address or Webhook URL is required.
+>
+> `encrypt_key` and `verification_token` are optional; enabling event encryption is recommended for production environments.
+>
+> For custom emoji references, see: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## Platform Limitations
+
+> ⚠️ **Feishu channel does not support 32-bit devices.** The Feishu SDK only provides 64-bit builds. Devices running armv6, armv7, mipsle, or other 32-bit architectures cannot use the Feishu channel. For messaging on 32-bit devices, use Telegram, Discord, or OneBot instead.
diff --git a/docs/channels/feishu/README.pt-br.md b/docs/channels/feishu/README.pt-br.md
new file mode 100644
index 000000000..5b5fcaf68
--- /dev/null
+++ b/docs/channels/feishu/README.pt-br.md
@@ -0,0 +1,52 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Feishu
+
+Feishu (nome internacional: Lark) é uma plataforma de colaboração empresarial da ByteDance. Suporta os mercados chinês e global por meio de conexões WebSocket orientadas a eventos.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "feishu": {
+ "enabled": true,
+ "app_id": "cli_xxx",
+ "app_secret": "xxx",
+ "encrypt_key": "",
+ "verification_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| --------------------- | ------ | ----------- | -------------------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal Feishu deve ser habilitado |
+| app_id | string | Sim | App ID da aplicação Feishu (começa com `cli_`) |
+| app_secret | string | Sim | App Secret da aplicação Feishu |
+| encrypt_key | string | Não | Chave de criptografia para callbacks de eventos |
+| verification_token | string | Não | Token usado para verificação de eventos Webhook |
+| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
+| random_reaction_emoji | array | Não | Lista de emojis de reação aleatórios; vazio usa o "Pin" padrão |
+
+## Configuração inicial
+
+1. Acesse a [Plataforma Aberta Feishu](https://open.feishu.cn/) e crie uma aplicação
+2. Habilite a capacidade de **Bot** nas configurações da aplicação
+3. Crie uma versão e publique a aplicação (a configuração entra em vigor após a publicação)
+4. Obtenha o **App ID** (começa com `cli_`) e o **App Secret**
+5. Preencha o App ID e o App Secret no arquivo de configuração do PicoClaw
+6. Execute `picoclaw gateway` para iniciar o serviço
+7. Pesquise o nome do bot no Feishu e inicie uma conversa
+
+> O PicoClaw se conecta ao Feishu usando o modo WebSocket/SDK — nenhum endereço de callback público ou URL de Webhook é necessário.
+>
+> `encrypt_key` e `verification_token` são opcionais; recomenda-se habilitar a criptografia de eventos em ambientes de produção.
+>
+> Para referências de emojis personalizados, consulte: [Lista de Emojis do Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## Limitações de Plataforma
+
+> ⚠️ **O canal Feishu não suporta dispositivos 32 bits.** O SDK do Feishu fornece apenas builds 64 bits. Arquiteturas 32 bits (armv6, armv7, mipsle, etc.) não podem usar o canal Feishu. Para mensagens em dispositivos 32 bits, use Telegram, Discord ou OneBot.
diff --git a/docs/channels/feishu/README.vi.md b/docs/channels/feishu/README.vi.md
new file mode 100644
index 000000000..e704b7794
--- /dev/null
+++ b/docs/channels/feishu/README.vi.md
@@ -0,0 +1,52 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Feishu
+
+Feishu (tên quốc tế: Lark) là nền tảng cộng tác doanh nghiệp của ByteDance. Hỗ trợ cả thị trường Trung Quốc và toàn cầu thông qua kết nối WebSocket theo hướng sự kiện.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "feishu": {
+ "enabled": true,
+ "app_id": "cli_xxx",
+ "app_secret": "xxx",
+ "encrypt_key": "",
+ "verification_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| --------------------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled | bool | Có | Có bật kênh Feishu hay không |
+| app_id | string | Có | App ID của ứng dụng Feishu (bắt đầu bằng `cli_`) |
+| app_secret | string | Có | App Secret của ứng dụng Feishu |
+| encrypt_key | string | Không | Khóa mã hóa cho callback sự kiện |
+| verification_token | string | Không | Token dùng để xác minh sự kiện Webhook |
+| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
+| random_reaction_emoji | array | Không | Danh sách emoji phản ứng ngẫu nhiên; để trống dùng "Pin" mặc định |
+
+## Hướng dẫn thiết lập
+
+1. Truy cập [Nền tảng Mở Feishu](https://open.feishu.cn/) và tạo ứng dụng
+2. Bật khả năng **Bot** trong cài đặt ứng dụng
+3. Tạo phiên bản và xuất bản ứng dụng (cấu hình có hiệu lực sau khi xuất bản)
+4. Lấy **App ID** (bắt đầu bằng `cli_`) và **App Secret**
+5. Điền App ID và App Secret vào file cấu hình PicoClaw
+6. Chạy `picoclaw gateway` để khởi động dịch vụ
+7. Tìm kiếm tên bot trong Feishu và bắt đầu trò chuyện
+
+> PicoClaw kết nối với Feishu bằng chế độ WebSocket/SDK — không cần cấu hình địa chỉ callback công khai hay Webhook URL.
+>
+> `encrypt_key` và `verification_token` là tùy chọn; nên bật mã hóa sự kiện trong môi trường sản xuất.
+>
+> Tham khảo emoji tùy chỉnh: [Danh sách Emoji Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## Giới hạn nền tảng
+
+> ⚠️ **Kênh Feishu không hỗ trợ thiết bị 32 bit.** SDK Feishu chỉ cung cấp bản build 64 bit. Các kiến trúc 32 bit (armv6, armv7, mipsle, v.v.) không thể sử dụng kênh Feishu. Để nhắn tin trên thiết bị 32 bit, hãy dùng Telegram, Discord hoặc OneBot.
diff --git a/docs/channels/feishu/README.zh.md b/docs/channels/feishu/README.zh.md
index db7eb56eb..6e2829547 100644
--- a/docs/channels/feishu/README.zh.md
+++ b/docs/channels/feishu/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# 飞书
飞书（国际版名称：Lark）是字节跳动旗下的企业协作平台。它通过事件驱动的 Webhook 同时支持中国和全球市场。
@@ -39,3 +41,7 @@
4. 设置加密(可选,生产环境建议启用)
5. 将 App ID、App Secret、Encrypt Key 和 Verification Token(如果启用加密) 填入配置文件中
6. 自定义你希望 PicoClaw react 你消息时的表情（可选, Reference URL: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce))
+
+## 平台限制
+
+> ⚠️ **飞书通道不支持 32 位设备。** 飞书官方 SDK 仅提供 64 位构建，armv6 / armv7 / mipsle 等 32 位架构无法使用飞书通道。如需在 32 位设备上接入即时通讯，请改用 Telegram、Discord 或 OneBot 等通道。
diff --git a/docs/channels/line/README.fr.md b/docs/channels/line/README.fr.md
new file mode 100644
index 000000000..10bdf3e58
--- /dev/null
+++ b/docs/channels/line/README.fr.md
@@ -0,0 +1,40 @@
+> Retour au [README](../../../README.fr.md)
+
+# Line
+
+PicoClaw prend en charge LINE via l'API LINE Messaging avec des callbacks webhook.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "line": {
+ "enabled": true,
+ "channel_secret": "YOUR_CHANNEL_SECRET",
+ "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+ "webhook_path": "/webhook/line",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| -------------------- | ------ | ------ | ------------------------------------------------------------------------ |
+| enabled | bool | Oui | Activer ou non le canal LINE |
+| channel_secret | string | Oui | Channel Secret de l'API LINE Messaging |
+| channel_access_token | string | Oui | Channel Access Token de l'API LINE Messaging |
+| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/line) |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
+
+## Procédure de configuration
+
+1. Rendez-vous sur la [LINE Developers Console](https://developers.line.biz/console/) et créez un fournisseur de services ainsi qu'un canal Messaging API
+2. Obtenez le Channel Secret et le Channel Access Token
+3. Configurez le webhook :
+ - LINE exige que les webhooks utilisent HTTPS. Vous devez donc déployer un serveur compatible HTTPS ou utiliser un outil de proxy inverse comme ngrok pour exposer votre serveur local sur Internet
+ - PicoClaw utilise un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux, écoutant par défaut sur 127.0.0.1:18790
+ - Définissez l'URL du webhook sur `https://your-domain.com/webhook/line`, puis configurez un proxy inverse de votre domaine externe vers le Gateway local (port par défaut 18790)
+ - Activez le webhook et vérifiez l'URL
+4. Renseignez le Channel Secret et le Channel Access Token dans le fichier de configuration
diff --git a/docs/channels/line/README.ja.md b/docs/channels/line/README.ja.md
new file mode 100644
index 000000000..0e559093a
--- /dev/null
+++ b/docs/channels/line/README.ja.md
@@ -0,0 +1,40 @@
+> [README](../../../README.ja.md) に戻る
+
+# Line
+
+PicoClaw は LINE Messaging API と Webhook コールバックを通じて LINE をサポートします。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "line": {
+ "enabled": true,
+ "channel_secret": "YOUR_CHANNEL_SECRET",
+ "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+ "webhook_path": "/webhook/line",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| -------------------- | ------ | ------ | ------------------------------------------------------------------ |
+| enabled | bool | はい | LINE チャンネルを有効にするかどうか |
+| channel_secret | string | はい | LINE Messaging API の Channel Secret |
+| channel_access_token | string | はい | LINE Messaging API の Channel Access Token |
+| webhook_path | string | いいえ | Webhook のパス（デフォルト: /webhook/line） |
+| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
+
+## セットアップ手順
+
+1. [LINE Developers Console](https://developers.line.biz/console/) にアクセスし、サービスプロバイダーと Messaging API チャンネルを作成する
+2. Channel Secret と Channel Access Token を取得する
+3. Webhook を設定する:
+ - LINE は Webhook に HTTPS が必要なため、HTTPS 対応サーバーをデプロイするか、ngrok などのリバースプロキシツールを使用してローカルサーバーをインターネットに公開する必要があります
+ - PicoClaw は共有の Gateway HTTP サーバーを使用してすべてのチャンネルの Webhook コールバックを受信します。デフォルトのリッスンアドレスは 127.0.0.1:18790 です
+ - Webhook URL を `https://your-domain.com/webhook/line` に設定し、外部ドメインをローカルの Gateway（デフォルトポート 18790）にリバースプロキシする
+ - Webhook を有効にして URL を検証する
+4. Channel Secret と Channel Access Token を設定ファイルに入力する
diff --git a/docs/channels/line/README.md b/docs/channels/line/README.md
new file mode 100644
index 000000000..1aad18eee
--- /dev/null
+++ b/docs/channels/line/README.md
@@ -0,0 +1,40 @@
+> Back to [README](../../../README.md)
+
+# Line
+
+PicoClaw supports LINE through the LINE Messaging API with webhook callbacks.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "line": {
+ "enabled": true,
+ "channel_secret": "YOUR_CHANNEL_SECRET",
+ "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+ "webhook_path": "/webhook/line",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| -------------------- | ------ | -------- | ------------------------------------------------------------------ |
+| enabled | bool | Yes | Whether to enable the LINE channel |
+| channel_secret | string | Yes | Channel Secret for the LINE Messaging API |
+| channel_access_token | string | Yes | Channel Access Token for the LINE Messaging API |
+| webhook_path | string | No | Webhook path (default: /webhook/line) |
+| allow_from | array | No | User ID whitelist; empty means all users are allowed |
+
+## Setup
+
+1. Go to the [LINE Developers Console](https://developers.line.biz/console/) and create a provider and a Messaging API channel
+2. Obtain the Channel Secret and Channel Access Token
+3. Configure the webhook:
+ - LINE requires webhooks to use HTTPS, so you need to deploy a server with HTTPS support, or use a reverse proxy tool like ngrok to expose your local server to the internet
+ - PicoClaw uses a shared Gateway HTTP server to receive webhook callbacks for all channels, listening on 127.0.0.1:18790 by default
+ - Set the Webhook URL to `https://your-domain.com/webhook/line`, then reverse-proxy your external domain to the local Gateway (default port 18790)
+ - Enable the webhook and verify the URL
+4. Fill in the Channel Secret and Channel Access Token in the configuration file
diff --git a/docs/channels/line/README.pt-br.md b/docs/channels/line/README.pt-br.md
new file mode 100644
index 000000000..b3334461f
--- /dev/null
+++ b/docs/channels/line/README.pt-br.md
@@ -0,0 +1,40 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Line
+
+O PicoClaw suporta o LINE por meio da LINE Messaging API com callbacks de webhook.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "line": {
+ "enabled": true,
+ "channel_secret": "YOUR_CHANNEL_SECRET",
+ "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+ "webhook_path": "/webhook/line",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| -------------------- | ------ | ----------- | ---------------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal LINE deve ser habilitado |
+| channel_secret | string | Sim | Channel Secret da LINE Messaging API |
+| channel_access_token | string | Sim | Channel Access Token da LINE Messaging API |
+| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/line) |
+| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
+
+## Configuração passo a passo
+
+1. Acesse o [LINE Developers Console](https://developers.line.biz/console/) e crie um provedor de serviços e um canal Messaging API
+2. Obtenha o Channel Secret e o Channel Access Token
+3. Configure o webhook:
+ - O LINE exige que os webhooks usem HTTPS, portanto é necessário implantar um servidor com suporte a HTTPS ou usar uma ferramenta de proxy reverso como o ngrok para expor seu servidor local à internet
+ - O PicoClaw usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais, escutando em 127.0.0.1:18790 por padrão
+ - Defina a URL do webhook como `https://your-domain.com/webhook/line` e configure um proxy reverso do seu domínio externo para o Gateway local (porta padrão 18790)
+ - Ative o webhook e verifique a URL
+4. Preencha o Channel Secret e o Channel Access Token no arquivo de configuração
diff --git a/docs/channels/line/README.vi.md b/docs/channels/line/README.vi.md
new file mode 100644
index 000000000..3e5511a84
--- /dev/null
+++ b/docs/channels/line/README.vi.md
@@ -0,0 +1,40 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Line
+
+PicoClaw hỗ trợ LINE thông qua LINE Messaging API kết hợp với webhook callback.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "line": {
+ "enabled": true,
+ "channel_secret": "YOUR_CHANNEL_SECRET",
+ "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+ "webhook_path": "/webhook/line",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| -------------------- | ------ | -------- | ---------------------------------------------------------------------- |
+| enabled | bool | Có | Có bật kênh LINE hay không |
+| channel_secret | string | Có | Channel Secret của LINE Messaging API |
+| channel_access_token | string | Có | Channel Access Token của LINE Messaging API |
+| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/line) |
+| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
+
+## Quy trình thiết lập
+
+1. Truy cập [LINE Developers Console](https://developers.line.biz/console/) và tạo một nhà cung cấp dịch vụ cùng một kênh Messaging API
+2. Lấy Channel Secret và Channel Access Token
+3. Cấu hình webhook:
+ - LINE yêu cầu webhook phải sử dụng HTTPS, vì vậy bạn cần triển khai máy chủ hỗ trợ HTTPS hoặc dùng công cụ reverse proxy như ngrok để expose máy chủ cục bộ ra internet
+ - PicoClaw sử dụng máy chủ HTTP Gateway dùng chung để nhận webhook callback cho tất cả các kênh, mặc định lắng nghe tại 127.0.0.1:18790
+ - Đặt Webhook URL thành `https://your-domain.com/webhook/line`, sau đó reverse proxy tên miền bên ngoài về Gateway cục bộ (cổng mặc định 18790)
+ - Bật webhook và xác minh URL
+4. Điền Channel Secret và Channel Access Token vào file cấu hình
diff --git a/docs/channels/line/README.zh.md b/docs/channels/line/README.zh.md
index a36f622c2..0f7dd0cd8 100644
--- a/docs/channels/line/README.zh.md
+++ b/docs/channels/line/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# Line
PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的支持。
diff --git a/docs/channels/maixcam/README.fr.md b/docs/channels/maixcam/README.fr.md
new file mode 100644
index 000000000..8fddb203a
--- /dev/null
+++ b/docs/channels/maixcam/README.fr.md
@@ -0,0 +1,35 @@
+> Retour au [README](../../../README.fr.md)
+
+# MaixCam
+
+MaixCam est un canal dédié à la connexion aux caméras AI Sipeed MaixCAM et MaixCAM2. Il utilise des sockets TCP pour une communication bidirectionnelle et prend en charge les scénarios de déploiement d'IA en périphérie.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "maixcam": {
+ "enabled": true,
+ "host": "0.0.0.0",
+ "port": 18790,
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------- | ------ | ------ | --------------------------------------------------------------------------- |
+| enabled | bool | Oui | Activer ou non le canal MaixCam |
+| host | string | Oui | Adresse d'écoute du serveur TCP |
+| port | int | Oui | Port d'écoute du serveur TCP |
+| allow_from | array | Non | Liste blanche d'identifiants d'appareils ; vide signifie tous les appareils |
+
+## Cas d'utilisation
+
+Le canal MaixCam permet à PicoClaw de fonctionner comme backend IA pour les appareils en périphérie :
+
+- **Surveillance intelligente** : MaixCAM envoie des images ; PicoClaw les analyse via des modèles de vision
+- **Contrôle IoT** : Les appareils envoient des données de capteurs ; PicoClaw coordonne les réponses
+- **IA hors ligne** : Déployer PicoClaw sur un réseau local pour une inférence à faible latence
diff --git a/docs/channels/maixcam/README.ja.md b/docs/channels/maixcam/README.ja.md
new file mode 100644
index 000000000..0a5f27baa
--- /dev/null
+++ b/docs/channels/maixcam/README.ja.md
@@ -0,0 +1,35 @@
+> [README](../../../README.ja.md) に戻る
+
+# MaixCam
+
+MaixCam は、Sipeed MaixCAM および MaixCAM2 AI カメラデバイスへの接続専用チャンネルです。TCP ソケットを使用した双方向通信を実装し、エッジ AI デプロイメントシナリオをサポートします。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "maixcam": {
+ "enabled": true,
+ "host": "0.0.0.0",
+ "port": 18790,
+ "allow_from": []
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------- | ------ | ------ | ------------------------------------------------------------- |
+| enabled | bool | はい | MaixCam チャンネルを有効にするかどうか |
+| host | string | はい | TCP サーバーのリッスンアドレス |
+| port | int | はい | TCP サーバーのリッスンポート |
+| allow_from | array | いいえ | 許可するデバイスIDのリスト。空の場合はすべてのデバイスを許可 |
+
+## ユースケース
+
+MaixCam チャンネルにより、PicoClaw はエッジデバイスの AI バックエンドとして機能できます：
+
+- **スマート監視**：MaixCAM が画像フレームを送信し、PicoClaw がビジョンモデルで分析する
+- **IoT 制御**：デバイスがセンサーデータを送信し、PicoClaw がレスポンスを調整する
+- **オフライン AI**：ローカルネットワークに PicoClaw をデプロイして低遅延推論を実現する
diff --git a/docs/channels/maixcam/README.md b/docs/channels/maixcam/README.md
new file mode 100644
index 000000000..c22c9236f
--- /dev/null
+++ b/docs/channels/maixcam/README.md
@@ -0,0 +1,35 @@
+> Back to [README](../../../README.md)
+
+# MaixCam
+
+MaixCam is a dedicated channel for connecting to Sipeed MaixCAM and MaixCAM2 AI camera devices. It uses TCP sockets for bidirectional communication and supports edge AI deployment scenarios.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "maixcam": {
+ "enabled": true,
+ "host": "0.0.0.0",
+ "port": 18790,
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------- | ------ | -------- | ---------------------------------------------------------------- |
+| enabled | bool | Yes | Whether to enable the MaixCam channel |
+| host | string | Yes | TCP server listening address |
+| port | int | Yes | TCP server listening port |
+| allow_from | array | No | Allowlist of device IDs; empty means all devices are allowed |
+
+## Use Cases
+
+The MaixCam channel enables PicoClaw to act as an AI backend for edge devices:
+
+- **Smart Surveillance**: MaixCAM sends image frames; PicoClaw analyzes them using vision models
+- **IoT Control**: Devices send sensor data; PicoClaw coordinates responses
+- **Offline AI**: Deploy PicoClaw on a local network for low-latency inference
diff --git a/docs/channels/maixcam/README.pt-br.md b/docs/channels/maixcam/README.pt-br.md
new file mode 100644
index 000000000..81a1f3f00
--- /dev/null
+++ b/docs/channels/maixcam/README.pt-br.md
@@ -0,0 +1,35 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# MaixCam
+
+MaixCam é um canal dedicado para conectar dispositivos de câmera AI Sipeed MaixCAM e MaixCAM2. Utiliza sockets TCP para comunicação bidirecional e suporta cenários de implantação de IA na borda.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "maixcam": {
+ "enabled": true,
+ "host": "0.0.0.0",
+ "port": 18790,
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal MaixCam deve ser habilitado |
+| host | string | Sim | Endereço de escuta do servidor TCP |
+| port | int | Sim | Porta de escuta do servidor TCP |
+| allow_from | array | Não | Lista de IDs de dispositivos permitidos; vazio significa todos os dispositivos |
+
+## Casos de uso
+
+O canal MaixCam permite que o PicoClaw atue como backend de IA para dispositivos de borda:
+
+- **Vigilância inteligente**: MaixCAM envia quadros de imagem; PicoClaw os analisa usando modelos de visão
+- **Controle IoT**: Dispositivos enviam dados de sensores; PicoClaw coordena as respostas
+- **IA offline**: Implante o PicoClaw em uma rede local para inferência de baixa latência
diff --git a/docs/channels/maixcam/README.vi.md b/docs/channels/maixcam/README.vi.md
new file mode 100644
index 000000000..8955bae86
--- /dev/null
+++ b/docs/channels/maixcam/README.vi.md
@@ -0,0 +1,35 @@
+> Quay lại [README](../../../README.vi.md)
+
+# MaixCam
+
+MaixCam là kênh chuyên dụng để kết nối với các thiết bị camera AI Sipeed MaixCAM và MaixCAM2. Sử dụng TCP socket để giao tiếp hai chiều và hỗ trợ các kịch bản triển khai AI tại biên.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "maixcam": {
+ "enabled": true,
+ "host": "0.0.0.0",
+ "port": 18790,
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled | bool | Có | Có bật kênh MaixCam hay không |
+| host | string | Có | Địa chỉ lắng nghe của máy chủ TCP |
+| port | int | Có | Cổng lắng nghe của máy chủ TCP |
+| allow_from | array | Không | Danh sách trắng ID thiết bị; để trống nghĩa là cho phép tất cả thiết bị |
+
+## Trường hợp sử dụng
+
+Kênh MaixCam cho phép PicoClaw hoạt động như backend AI cho các thiết bị biên:
+
+- **Giám sát thông minh**: MaixCAM gửi khung hình ảnh; PicoClaw phân tích bằng mô hình thị giác
+- **Điều khiển IoT**: Thiết bị gửi dữ liệu cảm biến; PicoClaw điều phối phản hồi
+- **AI ngoại tuyến**: Triển khai PicoClaw trên mạng nội bộ để suy luận độ trễ thấp
diff --git a/docs/channels/maixcam/README.zh.md b/docs/channels/maixcam/README.zh.md
index 8d53d4bef..b0d58e733 100644
--- a/docs/channels/maixcam/README.zh.md
+++ b/docs/channels/maixcam/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# MaixCam
MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的通道。它采用 TCP 套接字实现双向通信，支持边缘 AI 部署场景。
@@ -9,18 +11,20 @@ MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的
"channels": {
"maixcam": {
"enabled": true,
- "server_address": "0.0.0.0:8899",
+ "host": "0.0.0.0",
+ "port": 18790,
"allow_from": []
}
}
}
```
-| 字段 | 类型 | 必填 | 描述 |
-| -------------- | ------ | ---- | -------------------------------- |
-| enabled | bool | 是 | 是否启用 MaixCam 频道 |
-| server_address | string | 是 | TCP 服务器监听地址和端口 |
-| allow_from | array | 否 | 设备ID白名单，空表示允许所有设备 |
+| 字段 | 类型 | 必填 | 描述 |
+| ---------- | ------ | ---- | -------------------------------- |
+| enabled | bool | 是 | 是否启用 MaixCam 频道 |
+| host | string | 是 | TCP 服务器监听地址 |
+| port | int | 是 | TCP 服务器监听端口 |
+| allow_from | array | 否 | 设备ID白名单，空表示允许所有设备 |
## 使用场景
diff --git a/docs/channels/matrix/README.fr.md b/docs/channels/matrix/README.fr.md
new file mode 100644
index 000000000..ec762a8b8
--- /dev/null
+++ b/docs/channels/matrix/README.fr.md
@@ -0,0 +1,64 @@
+> Retour au [README](../../../README.fr.md)
+
+# Guide de configuration du canal Matrix
+
+## 1. Exemple de configuration
+
+Ajoutez ceci à `config.json` :
+
+```json
+{
+ "channels": {
+ "matrix": {
+ "enabled": true,
+ "homeserver": "https://matrix.org",
+ "user_id": "@your-bot:matrix.org",
+ "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+ "device_id": "",
+ "join_on_invite": true,
+ "allow_from": [],
+ "group_trigger": {
+ "mention_only": true
+ },
+ "placeholder": {
+ "enabled": true,
+ "text": "Thinking..."
+ },
+ "reasoning_channel_id": "",
+ "message_format": "richtext"
+ }
+ }
+}
+```
+
+## 2. Référence des champs
+
+| Champ | Type | Requis | Description |
+|----------------------|----------|--------|-------------|
+| enabled | bool | Oui | Activer ou désactiver le canal Matrix |
+| homeserver | string | Oui | URL du homeserver Matrix (par exemple `https://matrix.org`) |
+| user_id | string | Oui | ID utilisateur Matrix du bot (par exemple `@bot:matrix.org`) |
+| access_token | string | Oui | Jeton d'accès du bot |
+| device_id | string | Non | ID d'appareil Matrix optionnel |
+| join_on_invite | bool | Non | Rejoindre automatiquement les salons invités |
+| allow_from | []string | Non | Liste blanche d'utilisateurs (IDs Matrix) |
+| group_trigger | object | Non | Stratégie de déclenchement de groupe (`mention_only` / `prefixes`) |
+| placeholder | object | Non | Configuration du message de remplacement |
+| reasoning_channel_id | string | Non | Canal cible pour la sortie de raisonnement |
+| message_format | string | Non | Format de sortie : `"richtext"` (défaut) rend le markdown en HTML ; `"plain"` envoie du texte brut uniquement |
+
+## 3. Fonctionnalités actuellement supportées
+
+- Envoi/réception de messages texte avec rendu markdown (gras, italique, titres, blocs de code, etc.)
+- Format de message configurable (`richtext` / `plain`)
+- Téléchargement d'images/audio/vidéo/fichiers entrants (MediaStore en priorité, chemin local en secours)
+- Normalisation de l'audio entrant dans le flux de transcription existant (`[audio: ...]`)
+- Upload et envoi d'images/audio/vidéo/fichiers sortants
+- Règles de déclenchement de groupe (y compris le mode mention uniquement)
+- État de frappe (`m.typing`)
+- Message de remplacement + remplacement de la réponse finale
+- Rejoindre automatiquement les salons invités (peut être désactivé)
+
+## 4. TODO
+
+- Améliorations des métadonnées des médias riches (par exemple taille et miniatures des images/vidéos)
diff --git a/docs/channels/matrix/README.ja.md b/docs/channels/matrix/README.ja.md
new file mode 100644
index 000000000..e5a773d4d
--- /dev/null
+++ b/docs/channels/matrix/README.ja.md
@@ -0,0 +1,64 @@
+> [README](../../../README.ja.md) に戻る
+
+# Matrix チャンネル設定ガイド
+
+## 1. 設定例
+
+`config.json` に以下を追加してください：
+
+```json
+{
+ "channels": {
+ "matrix": {
+ "enabled": true,
+ "homeserver": "https://matrix.org",
+ "user_id": "@your-bot:matrix.org",
+ "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+ "device_id": "",
+ "join_on_invite": true,
+ "allow_from": [],
+ "group_trigger": {
+ "mention_only": true
+ },
+ "placeholder": {
+ "enabled": true,
+ "text": "Thinking..."
+ },
+ "reasoning_channel_id": "",
+ "message_format": "richtext"
+ }
+ }
+}
+```
+
+## 2. フィールドリファレンス
+
+| フィールド | 型 | 必須 | 説明 |
+|----------------------|----------|------|------|
+| enabled | bool | はい | Matrix チャンネルの有効/無効 |
+| homeserver | string | はい | Matrix ホームサーバー URL（例：`https://matrix.org`） |
+| user_id | string | はい | ボットの Matrix ユーザー ID（例：`@bot:matrix.org`） |
+| access_token | string | はい | ボットのアクセストークン |
+| device_id | string | いいえ | オプションの Matrix デバイス ID |
+| join_on_invite | bool | いいえ | 招待されたルームに自動参加 |
+| allow_from | []string | いいえ | ユーザーホワイトリスト（Matrix ユーザー ID） |
+| group_trigger | object | いいえ | グループトリガー戦略（`mention_only` / `prefixes`） |
+| placeholder | object | いいえ | プレースホルダーメッセージ設定 |
+| reasoning_channel_id | string | いいえ | 推論出力のターゲットチャンネル |
+| message_format | string | いいえ | 出力形式：`"richtext"`（デフォルト）は markdown を HTML としてレンダリング；`"plain"` はプレーンテキストのみ送信 |
+
+## 3. 現在サポートされている機能
+
+- markdown レンダリング付きテキストメッセージ送受信（太字、斜体、見出し、コードブロックなど）
+- 設定可能なメッセージ形式（`richtext` / `plain`）
+- 受信画像/音声/動画/ファイルのダウンロード（MediaStore 優先、ローカルパスフォールバック）
+- 受信音声の既存文字起こしフローへの正規化（`[audio: ...]`）
+- 送信画像/音声/動画/ファイルのアップロードと送信
+- グループトリガールール（メンションのみモードを含む）
+- タイピング状態（`m.typing`）
+- プレースホルダーメッセージ + 最終返信の置き換え
+- 招待されたルームへの自動参加（無効化可能）
+
+## 4. TODO
+
+- リッチメディアメタデータの改善（例：画像/動画のサイズとサムネイル）
diff --git a/docs/channels/matrix/README.md b/docs/channels/matrix/README.md
index 233f5c0a3..2ed19245a 100644
--- a/docs/channels/matrix/README.md
+++ b/docs/channels/matrix/README.md
@@ -1,3 +1,5 @@
+> Back to [README](../../../README.md)
+
# Matrix Channel Configuration Guide
## 1. Example Configuration
diff --git a/docs/channels/matrix/README.pt-br.md b/docs/channels/matrix/README.pt-br.md
new file mode 100644
index 000000000..11a9aaa11
--- /dev/null
+++ b/docs/channels/matrix/README.pt-br.md
@@ -0,0 +1,64 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Guia de Configuração do Canal Matrix
+
+## 1. Exemplo de Configuração
+
+Adicione isto ao `config.json`:
+
+```json
+{
+ "channels": {
+ "matrix": {
+ "enabled": true,
+ "homeserver": "https://matrix.org",
+ "user_id": "@your-bot:matrix.org",
+ "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+ "device_id": "",
+ "join_on_invite": true,
+ "allow_from": [],
+ "group_trigger": {
+ "mention_only": true
+ },
+ "placeholder": {
+ "enabled": true,
+ "text": "Thinking..."
+ },
+ "reasoning_channel_id": "",
+ "message_format": "richtext"
+ }
+ }
+}
+```
+
+## 2. Referência de Campos
+
+| Campo | Tipo | Obrigatório | Descrição |
+|----------------------|----------|-------------|-----------|
+| enabled | bool | Sim | Habilitar ou desabilitar o canal Matrix |
+| homeserver | string | Sim | URL do homeserver Matrix (por exemplo `https://matrix.org`) |
+| user_id | string | Sim | ID de usuário Matrix do bot (por exemplo `@bot:matrix.org`) |
+| access_token | string | Sim | Token de acesso do bot |
+| device_id | string | Não | ID de dispositivo Matrix opcional |
+| join_on_invite | bool | Não | Entrar automaticamente em salas convidadas |
+| allow_from | []string | Não | Lista branca de usuários (IDs Matrix) |
+| group_trigger | object | Não | Estratégia de gatilho de grupo (`mention_only` / `prefixes`) |
+| placeholder | object | Não | Configuração de mensagem de espaço reservado |
+| reasoning_channel_id | string | Não | Canal alvo para saída de raciocínio |
+| message_format | string | Não | Formato de saída: `"richtext"` (padrão) renderiza markdown como HTML; `"plain"` envia apenas texto simples |
+
+## 3. Suporte Atual
+
+- Envio/recebimento de mensagens de texto com renderização markdown (negrito, itálico, cabeçalhos, blocos de código, etc.)
+- Formato de mensagem configurável (`richtext` / `plain`)
+- Download de imagens/áudio/vídeo/arquivos recebidos (MediaStore primeiro, fallback para caminho local)
+- Normalização de áudio recebido no fluxo de transcrição existente (`[audio: ...]`)
+- Upload e envio de imagens/áudio/vídeo/arquivos de saída
+- Regras de gatilho de grupo (incluindo modo somente menção)
+- Estado de digitação (`m.typing`)
+- Mensagem de espaço reservado + substituição de resposta final
+- Entrada automática em salas convidadas (pode ser desabilitado)
+
+## 4. TODO
+
+- Melhorias nos metadados de mídia rica (por exemplo tamanho e miniaturas de imagens/vídeos)
diff --git a/docs/channels/matrix/README.vi.md b/docs/channels/matrix/README.vi.md
new file mode 100644
index 000000000..f1272076f
--- /dev/null
+++ b/docs/channels/matrix/README.vi.md
@@ -0,0 +1,64 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Hướng dẫn Cấu hình Kênh Matrix
+
+## 1. Cấu hình Mẫu
+
+Thêm vào `config.json`:
+
+```json
+{
+ "channels": {
+ "matrix": {
+ "enabled": true,
+ "homeserver": "https://matrix.org",
+ "user_id": "@your-bot:matrix.org",
+ "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+ "device_id": "",
+ "join_on_invite": true,
+ "allow_from": [],
+ "group_trigger": {
+ "mention_only": true
+ },
+ "placeholder": {
+ "enabled": true,
+ "text": "Thinking..."
+ },
+ "reasoning_channel_id": "",
+ "message_format": "richtext"
+ }
+ }
+}
+```
+
+## 2. Tham chiếu Trường
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+|----------------------|----------|----------|-------|
+| enabled | bool | Có | Bật hoặc tắt kênh Matrix |
+| homeserver | string | Có | URL homeserver Matrix (ví dụ `https://matrix.org`) |
+| user_id | string | Có | ID người dùng Matrix của bot (ví dụ `@bot:matrix.org`) |
+| access_token | string | Có | Token truy cập của bot |
+| device_id | string | Không | ID thiết bị Matrix tùy chọn |
+| join_on_invite | bool | Không | Tự động tham gia phòng được mời |
+| allow_from | []string | Không | Danh sách trắng người dùng (ID Matrix) |
+| group_trigger | object | Không | Chiến lược kích hoạt nhóm (`mention_only` / `prefixes`) |
+| placeholder | object | Không | Cấu hình tin nhắn giữ chỗ |
+| reasoning_channel_id | string | Không | Kênh đích cho đầu ra suy luận |
+| message_format | string | Không | Định dạng đầu ra: `"richtext"` (mặc định) render markdown thành HTML; `"plain"` chỉ gửi văn bản thuần |
+
+## 3. Tính năng Hiện tại
+
+- Gửi/nhận tin nhắn văn bản với render markdown (đậm, nghiêng, tiêu đề, khối code, v.v.)
+- Định dạng tin nhắn có thể cấu hình (`richtext` / `plain`)
+- Tải xuống hình ảnh/âm thanh/video/tệp đến (MediaStore trước, fallback đường dẫn cục bộ)
+- Chuẩn hóa âm thanh đến vào luồng phiên âm hiện có (`[audio: ...]`)
+- Tải lên và gửi hình ảnh/âm thanh/video/tệp đi
+- Quy tắc kích hoạt nhóm (bao gồm chế độ chỉ đề cập)
+- Trạng thái đang gõ (`m.typing`)
+- Tin nhắn giữ chỗ + thay thế phản hồi cuối cùng
+- Tự động tham gia phòng được mời (có thể tắt)
+
+## 4. TODO
+
+- Cải thiện metadata phương tiện phong phú (ví dụ kích thước và hình thu nhỏ hình ảnh/video)
diff --git a/docs/channels/matrix/README.zh.md b/docs/channels/matrix/README.zh.md
index efbc13093..8db3e4383 100644
--- a/docs/channels/matrix/README.zh.md
+++ b/docs/channels/matrix/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# Matrix 通道配置指南
## 1. 配置示例
@@ -42,6 +44,7 @@
| group_trigger | object | 否 | 群聊触发策略（支持 `mention_only` / `prefixes`） |
| placeholder | object | 否 | 占位消息配置 |
| reasoning_channel_id | string | 否 | 思维链输出目标通道 |
+| message_format | string | 否 | 消息格式：`richtext`（富文本）或 `plain`（纯文本） |
## 3. 当前支持
diff --git a/docs/channels/onebot/README.fr.md b/docs/channels/onebot/README.fr.md
new file mode 100644
index 000000000..7c9ffe1d3
--- /dev/null
+++ b/docs/channels/onebot/README.fr.md
@@ -0,0 +1,33 @@
+> Retour au [README](../../../README.fr.md)
+
+# OneBot
+
+OneBot est un standard de protocole ouvert pour les bots QQ, fournissant une interface unifiée pour diverses implémentations de bots QQ (par exemple go-cqhttp, Mirai). Il utilise WebSocket pour la communication.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "onebot": {
+ "enabled": true,
+ "ws_url": "ws://localhost:8080",
+ "access_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ------------ | ------ | ------ | -------------------------------------------------------------------- |
+| enabled | bool | Oui | Activer ou non le canal OneBot |
+| ws_url | string | Oui | URL WebSocket du serveur OneBot |
+| access_token | string | Non | Jeton d'accès pour la connexion au serveur OneBot |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
+
+## Procédure de configuration
+
+1. Déployez une implémentation compatible OneBot (par exemple napcat)
+2. Configurez l'implémentation OneBot pour activer le service WebSocket et définir un jeton d'accès (si nécessaire)
+3. Renseignez l'URL WebSocket et le jeton d'accès dans le fichier de configuration
diff --git a/docs/channels/onebot/README.ja.md b/docs/channels/onebot/README.ja.md
new file mode 100644
index 000000000..ce628572b
--- /dev/null
+++ b/docs/channels/onebot/README.ja.md
@@ -0,0 +1,33 @@
+> [README](../../../README.ja.md) に戻る
+
+# OneBot
+
+OneBot は QQ ボット向けのオープンプロトコル標準で、複数の QQ ボット実装（例: go-cqhttp、Mirai）に統一されたインターフェースを提供します。通信には WebSocket を使用します。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "onebot": {
+ "enabled": true,
+ "ws_url": "ws://localhost:8080",
+ "access_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ------------ | ------ | ------ | ---------------------------------------------------------------- |
+| enabled | bool | はい | OneBot チャンネルを有効にするかどうか |
+| ws_url | string | はい | OneBot サーバーの WebSocket URL |
+| access_token | string | いいえ | OneBot サーバーへの接続に使用するアクセストークン |
+| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
+
+## セットアップ手順
+
+1. OneBot 互換の実装（例: napcat）をデプロイする
+2. OneBot 実装で WebSocket サービスを有効にし、アクセストークンを設定する（必要な場合）
+3. WebSocket URL とアクセストークンを設定ファイルに入力する
diff --git a/docs/channels/onebot/README.md b/docs/channels/onebot/README.md
new file mode 100644
index 000000000..42af39b4e
--- /dev/null
+++ b/docs/channels/onebot/README.md
@@ -0,0 +1,33 @@
+> Back to [README](../../../README.md)
+
+# OneBot
+
+OneBot is an open protocol standard for QQ bots, providing a unified interface for various QQ bot implementations (e.g. go-cqhttp, Mirai). It uses WebSocket for communication.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "onebot": {
+ "enabled": true,
+ "ws_url": "ws://localhost:8080",
+ "access_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ------------ | ------ | -------- | ---------------------------------------------------------------- |
+| enabled | bool | Yes | Whether to enable the OneBot channel |
+| ws_url | string | Yes | WebSocket URL of the OneBot server |
+| access_token | string | No | Access token for connecting to the OneBot server |
+| allow_from | array | No | User ID whitelist; empty means all users are allowed |
+
+## Setup
+
+1. Deploy a OneBot-compatible implementation (e.g. napcat)
+2. Configure the OneBot implementation to enable the WebSocket service and set an access token (if needed)
+3. Fill in the WebSocket URL and access token in the configuration file
diff --git a/docs/channels/onebot/README.pt-br.md b/docs/channels/onebot/README.pt-br.md
new file mode 100644
index 000000000..5323163ee
--- /dev/null
+++ b/docs/channels/onebot/README.pt-br.md
@@ -0,0 +1,33 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# OneBot
+
+OneBot é um padrão de protocolo aberto para bots QQ, fornecendo uma interface unificada para diversas implementações de bots QQ (ex.: go-cqhttp, Mirai). Utiliza WebSocket para comunicação.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "onebot": {
+ "enabled": true,
+ "ws_url": "ws://localhost:8080",
+ "access_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ------------ | ------ | ----------- | -------------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal OneBot deve ser habilitado |
+| ws_url | string | Sim | URL WebSocket do servidor OneBot |
+| access_token | string | Não | Token de acesso para conexão ao servidor OneBot |
+| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
+
+## Configuração passo a passo
+
+1. Implante uma implementação compatível com OneBot (ex.: napcat)
+2. Configure a implementação OneBot para habilitar o serviço WebSocket e definir um token de acesso (se necessário)
+3. Preencha a URL WebSocket e o token de acesso no arquivo de configuração
diff --git a/docs/channels/onebot/README.vi.md b/docs/channels/onebot/README.vi.md
new file mode 100644
index 000000000..a572e7afa
--- /dev/null
+++ b/docs/channels/onebot/README.vi.md
@@ -0,0 +1,33 @@
+> Quay lại [README](../../../README.vi.md)
+
+# OneBot
+
+OneBot là tiêu chuẩn giao thức mở dành cho bot QQ, cung cấp giao diện thống nhất cho nhiều triển khai bot QQ khác nhau (ví dụ: go-cqhttp, Mirai). Nó sử dụng WebSocket để giao tiếp.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "onebot": {
+ "enabled": true,
+ "ws_url": "ws://localhost:8080",
+ "access_token": "",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ------------ | ------ | -------- | -------------------------------------------------------------------- |
+| enabled | bool | Có | Có bật kênh OneBot hay không |
+| ws_url | string | Có | URL WebSocket của máy chủ OneBot |
+| access_token | string | Không | Token truy cập để kết nối với máy chủ OneBot |
+| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
+
+## Quy trình thiết lập
+
+1. Triển khai một bản triển khai tương thích OneBot (ví dụ: napcat)
+2. Cấu hình bản triển khai OneBot để bật dịch vụ WebSocket và đặt token truy cập (nếu cần)
+3. Điền URL WebSocket và token truy cập vào file cấu hình
diff --git a/docs/channels/onebot/README.zh.md b/docs/channels/onebot/README.zh.md
index 6195f1c98..8caba0b80 100644
--- a/docs/channels/onebot/README.zh.md
+++ b/docs/channels/onebot/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# OneBot
OneBot 是一个面向 QQ 机器人的开放协议标准，为多种 QQ 机器人实现（例如 go-cqhttp、Mirai）提供了统一的接口。它使用 WebSocket 进行通信。
diff --git a/docs/channels/qq/README.fr.md b/docs/channels/qq/README.fr.md
new file mode 100644
index 000000000..38de1b751
--- /dev/null
+++ b/docs/channels/qq/README.fr.md
@@ -0,0 +1,54 @@
+> Retour au [README](../../../README.fr.md)
+
+# QQ
+
+PicoClaw prend en charge QQ via l'API Bot officielle de la plateforme ouverte QQ.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "qq": {
+ "enabled": true,
+ "app_id": "YOUR_APP_ID",
+ "app_secret": "YOUR_APP_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------- | ------ | ------ | --------------------------------------------------------------------------- |
+| enabled | bool | Oui | Activer ou non le canal QQ |
+| app_id | string | Oui | App ID de l'application bot QQ |
+| app_secret | string | Oui | App Secret de l'application bot QQ |
+| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
+
+## Configuration initiale
+
+### Configuration rapide (recommandée)
+
+La plateforme ouverte QQ propose une entrée de création en un clic :
+
+1. Ouvrir [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) et se connecter en scannant le QR code
+2. Le système crée automatiquement un bot — copier l'**App ID** et l'**App Secret**
+3. Renseigner les identifiants dans le fichier de configuration PicoClaw
+4. Exécuter `picoclaw gateway` pour démarrer le service
+5. Ouvrir QQ et commencer à discuter avec le bot
+
+> L'App Secret n'est affiché qu'une seule fois — sauvegardez-le immédiatement. Le consulter à nouveau forcera une réinitialisation.
+>
+> Les bots créés via l'entrée rapide sont réservés à l'usage personnel du créateur et ne prennent pas en charge les discussions de groupe. Pour la prise en charge des groupes, configurez le mode sandbox sur la [plateforme ouverte QQ](https://q.qq.com/).
+
+### Configuration manuelle
+
+1. Se connecter à la [plateforme ouverte QQ](https://q.qq.com/) avec son compte QQ et s'inscrire en tant que développeur
+2. Créer un bot QQ et personnaliser son avatar et son nom
+3. Obtenir l'**App ID** et l'**App Secret** dans les paramètres du bot
+4. Renseigner les identifiants dans le fichier de configuration PicoClaw
+5. Exécuter `picoclaw gateway` pour démarrer le service
+6. Rechercher votre bot dans QQ et commencer à discuter
+
+> Pendant le développement, il est recommandé d'activer le mode sandbox et d'y ajouter les utilisateurs et groupes de test pour le débogage.
diff --git a/docs/channels/qq/README.ja.md b/docs/channels/qq/README.ja.md
new file mode 100644
index 000000000..2990f9622
--- /dev/null
+++ b/docs/channels/qq/README.ja.md
@@ -0,0 +1,54 @@
+> [README](../../../README.ja.md) に戻る
+
+# QQ
+
+PicoClaw は QQ オープンプラットフォームの公式 Bot API を通じて QQ をサポートします。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "qq": {
+ "enabled": true,
+ "app_id": "YOUR_APP_ID",
+ "app_secret": "YOUR_APP_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------- | ------ | ------ | ------------------------------------------------------------- |
+| enabled | bool | はい | QQ チャンネルを有効にするかどうか |
+| app_id | string | はい | QQ ボットアプリケーションの App ID |
+| app_secret | string | はい | QQ ボットアプリケーションの App Secret |
+| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
+
+## セットアップ手順
+
+### クイックセットアップ（推奨）
+
+QQ オープンプラットフォームにはワンクリック作成エントリーが用意されています：
+
+1. [QQ ボットクイック作成](https://q.qq.com/qqbot/openclaw/index.html) を開き、QR コードをスキャンしてログインする
+2. システムが自動的にボットを作成するので、**App ID** と **App Secret** をコピーする
+3. PicoClaw 設定ファイルに認証情報を入力する
+4. `picoclaw gateway` を実行してサービスを起動する
+5. QQ を開いてボットとの会話を始める
+
+> App Secret は一度しか表示されません。すぐに保存してください。再度表示しようとすると強制的にリセットされます。
+>
+> クイックエントリーで作成したボットは作成者本人のみが使用でき、グループチャットには対応していません。グループチャット機能が必要な場合は、[QQ オープンプラットフォーム](https://q.qq.com/) でサンドボックスモードを設定してください。
+
+### 手動セットアップ
+
+1. QQ アカウントで [QQ オープンプラットフォーム](https://q.qq.com/) にログインし、開発者アカウントを登録する
+2. QQ ボットを作成し、アバターと名前をカスタマイズする
+3. ボット設定から **App ID** と **App Secret** を取得する
+4. PicoClaw 設定ファイルに認証情報を入力する
+5. `picoclaw gateway` を実行してサービスを起動する
+6. QQ でボットを検索して会話を始める
+
+> 開発段階ではサンドボックスモードを有効にし、テストユーザーとグループをサンドボックスに追加してデバッグすることを推奨します。
diff --git a/docs/channels/qq/README.md b/docs/channels/qq/README.md
new file mode 100644
index 000000000..35e4a769c
--- /dev/null
+++ b/docs/channels/qq/README.md
@@ -0,0 +1,54 @@
+> Back to [README](../../../README.md)
+
+# QQ
+
+PicoClaw provides QQ support via the official Bot API from the QQ Open Platform.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "qq": {
+ "enabled": true,
+ "app_id": "YOUR_APP_ID",
+ "app_secret": "YOUR_APP_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------- | ------ | -------- | -------------------------------------------------------- |
+| enabled | bool | Yes | Whether to enable the QQ channel |
+| app_id | string | Yes | App ID of the QQ bot application |
+| app_secret | string | Yes | App Secret of the QQ bot application |
+| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
+
+## Setup
+
+### Quick Setup (Recommended)
+
+The QQ Open Platform provides a one-click creation entry:
+
+1. Open [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) and log in by scanning the QR code
+2. The system automatically creates a bot — copy the **App ID** and **App Secret**
+3. Fill in the credentials in the PicoClaw configuration file
+4. Run `picoclaw gateway` to start the service
+5. Open QQ and start chatting with the bot
+
+> The App Secret is only shown once — save it immediately. Viewing it again will force a reset.
+>
+> Bots created via the quick entry are for the creator's personal use only and do not support group chats. For group chat support, configure sandbox mode on the [QQ Open Platform](https://q.qq.com/).
+
+### Manual Setup
+
+1. Log in to the [QQ Open Platform](https://q.qq.com/) with your QQ account and register as a developer
+2. Create a QQ bot and customize its avatar and name
+3. Obtain the **App ID** and **App Secret** from the bot settings
+4. Fill in the credentials in the PicoClaw configuration file
+5. Run `picoclaw gateway` to start the service
+6. Search for your bot in QQ and start chatting
+
+> During development, it is recommended to enable sandbox mode and add test users and groups to the sandbox for debugging.
diff --git a/docs/channels/qq/README.pt-br.md b/docs/channels/qq/README.pt-br.md
new file mode 100644
index 000000000..507df7f7e
--- /dev/null
+++ b/docs/channels/qq/README.pt-br.md
@@ -0,0 +1,54 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# QQ
+
+O PicoClaw oferece suporte ao QQ via API Bot oficial da Plataforma Aberta QQ.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "qq": {
+ "enabled": true,
+ "app_id": "YOUR_APP_ID",
+ "app_secret": "YOUR_APP_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal QQ deve ser habilitado |
+| app_id | string | Sim | App ID da aplicação bot QQ |
+| app_secret | string | Sim | App Secret da aplicação bot QQ |
+| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
+
+## Configuração inicial
+
+### Configuração rápida (recomendada)
+
+A Plataforma Aberta QQ oferece uma entrada de criação com um clique:
+
+1. Abra o [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) e faça login escaneando o QR code
+2. O sistema cria o bot automaticamente — copie o **App ID** e o **App Secret**
+3. Preencha as credenciais no arquivo de configuração do PicoClaw
+4. Execute `picoclaw gateway` para iniciar o serviço
+5. Abra o QQ e comece a conversar com o bot
+
+> O App Secret é exibido apenas uma vez — salve-o imediatamente. Visualizá-lo novamente forçará uma redefinição.
+>
+> Bots criados pela entrada rápida são apenas para uso pessoal do criador e não suportam chats em grupo. Para suporte a grupos, configure o modo sandbox na [Plataforma Aberta QQ](https://q.qq.com/).
+
+### Configuração manual
+
+1. Faça login na [Plataforma Aberta QQ](https://q.qq.com/) com sua conta QQ e registre-se como desenvolvedor
+2. Crie um bot QQ e personalize seu avatar e nome
+3. Obtenha o **App ID** e o **App Secret** nas configurações do bot
+4. Preencha as credenciais no arquivo de configuração do PicoClaw
+5. Execute `picoclaw gateway` para iniciar o serviço
+6. Pesquise seu bot no QQ e comece a conversar
+
+> Durante o desenvolvimento, recomenda-se habilitar o modo sandbox e adicionar usuários e grupos de teste ao sandbox para depuração.
diff --git a/docs/channels/qq/README.vi.md b/docs/channels/qq/README.vi.md
new file mode 100644
index 000000000..1f3eb89da
--- /dev/null
+++ b/docs/channels/qq/README.vi.md
@@ -0,0 +1,54 @@
+> Quay lại [README](../../../README.vi.md)
+
+# QQ
+
+PicoClaw hỗ trợ QQ thông qua API Bot chính thức của Nền tảng Mở QQ.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "qq": {
+ "enabled": true,
+ "app_id": "YOUR_APP_ID",
+ "app_secret": "YOUR_APP_SECRET",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled | bool | Có | Có bật kênh QQ hay không |
+| app_id | string | Có | App ID của ứng dụng bot QQ |
+| app_secret | string | Có | App Secret của ứng dụng bot QQ |
+| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
+
+## Hướng dẫn thiết lập
+
+### Thiết lập nhanh (Khuyến nghị)
+
+Nền tảng Mở QQ cung cấp lối vào tạo bot một chạm:
+
+1. Mở [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) và đăng nhập bằng cách quét mã QR
+2. Hệ thống tự động tạo bot — sao chép **App ID** và **App Secret**
+3. Điền thông tin xác thực vào file cấu hình PicoClaw
+4. Chạy `picoclaw gateway` để khởi động dịch vụ
+5. Mở QQ và bắt đầu trò chuyện với bot
+
+> App Secret chỉ hiển thị một lần — hãy lưu lại ngay. Xem lại sẽ buộc phải đặt lại.
+>
+> Bot được tạo qua lối vào nhanh chỉ dành cho người tạo sử dụng cá nhân và chưa hỗ trợ chat nhóm. Để hỗ trợ chat nhóm, hãy cấu hình chế độ sandbox trên [Nền tảng Mở QQ](https://q.qq.com/).
+
+### Tạo thủ công
+
+1. Đăng nhập vào [Nền tảng Mở QQ](https://q.qq.com/) bằng tài khoản QQ và đăng ký tài khoản nhà phát triển
+2. Tạo bot QQ, tùy chỉnh ảnh đại diện và tên
+3. Lấy **App ID** và **App Secret** trong cài đặt bot
+4. Điền thông tin xác thực vào file cấu hình PicoClaw
+5. Chạy `picoclaw gateway` để khởi động dịch vụ
+6. Tìm kiếm bot của bạn trong QQ và bắt đầu trò chuyện
+
+> Trong giai đoạn phát triển, nên bật chế độ sandbox và thêm người dùng, nhóm thử nghiệm vào sandbox để gỡ lỗi.
diff --git a/docs/channels/qq/README.zh.md b/docs/channels/qq/README.zh.md
index 6211d2ec4..e7f6d2050 100644
--- a/docs/channels/qq/README.zh.md
+++ b/docs/channels/qq/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# QQ
PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
@@ -28,7 +30,27 @@ PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
## 设置流程
-1. 前往 [QQ 开放平台](https://q.qq.com/) 创建一个机器人
-2. 通过仪表盘获取 App ID 和 App Secret
-3. 开启机器人沙箱模式, 将用户和群添加到沙箱中
-4. 将 App ID 和 App Secret 填入配置文件中
+### 快捷方式（推荐）
+
+QQ 开放平台提供了一键创建入口：
+
+1. 打开 [QQ 机器人快速创建](https://q.qq.com/qqbot/openclaw/index.html)，扫码登录
+2. 系统自动创建机器人，复制 **App ID** 和 **App Secret**
+3. 将凭证填入 PicoClaw 配置文件
+4. 运行 `picoclaw gateway` 启动服务
+5. 打开 QQ，与机器人开始对话
+
+> App Secret 仅显示一次，请立即保存。再次查看将强制重置。
+>
+> 通过快捷入口创建的机器人仅供创建人使用，暂不支持群聊。如需群聊功能，请在 [QQ 开放平台](https://q.qq.com/) 配置沙箱模式。
+
+### 手动创建
+
+1. 使用 QQ 账号登录 [QQ 开放平台](https://q.qq.com/)，注册开发者账号
+2. 创建 QQ 机器人，自定义头像和名称
+3. 在机器人设置中获取 **App ID** 和 **App Secret**
+4. 将凭证填入 PicoClaw 配置文件
+5. 运行 `picoclaw gateway` 启动服务
+6. 在 QQ 中搜索你的机器人，开始对话
+
+> 开发阶段建议开启沙箱模式，将测试用户和群添加到沙箱中进行调试。
diff --git a/docs/channels/slack/README.fr.md b/docs/channels/slack/README.fr.md
new file mode 100644
index 000000000..81dcebdec
--- /dev/null
+++ b/docs/channels/slack/README.fr.md
@@ -0,0 +1,35 @@
+> Retour au [README](../../../README.fr.md)
+
+# Slack
+
+Slack est l'une des principales plateformes de messagerie instantanée pour les entreprises. PicoClaw utilise le Socket Mode de Slack pour une communication bidirectionnelle en temps réel, sans nécessiter la configuration d'un endpoint webhook public.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "slack": {
+ "enabled": true,
+ "bot_token": "xoxb-...",
+ "app_token": "xapp-...",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------- | ------ | ------ | ---------------------------------------------------------------------------- |
+| enabled | bool | Oui | Activer ou non le canal Slack |
+| bot_token | string | Oui | Bot User OAuth Token du bot Slack (commence par xoxb-) |
+| app_token | string | Oui | App Level Token Socket Mode de l'application Slack (commence par xapp-) |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
+
+## Procédure de configuration
+
+1. Rendez-vous sur [Slack API](https://api.slack.com/) et créez une nouvelle application Slack
+2. Activez le Socket Mode et obtenez l'App Level Token
+3. Ajoutez des Bot Token Scopes (par exemple `chat:write`, `im:history`, etc.)
+4. Installez l'application dans votre espace de travail et obtenez le Bot User OAuth Token
+5. Renseignez le Bot Token et l'App Token dans le fichier de configuration
diff --git a/docs/channels/slack/README.ja.md b/docs/channels/slack/README.ja.md
new file mode 100644
index 000000000..c8d268b9c
--- /dev/null
+++ b/docs/channels/slack/README.ja.md
@@ -0,0 +1,35 @@
+> [README](../../../README.ja.md) に戻る
+
+# Slack
+
+Slack は世界をリードする企業向けインスタントメッセージングプラットフォームです。PicoClaw は Slack の Socket Mode を使用してリアルタイムの双方向通信を実現しており、公開 Webhook エンドポイントの設定は不要です。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "slack": {
+ "enabled": true,
+ "bot_token": "xoxb-...",
+ "app_token": "xapp-...",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------- | ------ | ------ | ------------------------------------------------------------------------ |
+| enabled | bool | はい | Slack チャンネルを有効にするかどうか |
+| bot_token | string | はい | Slack ボットの Bot User OAuth Token（xoxb- で始まる） |
+| app_token | string | はい | Slack アプリの Socket Mode App Level Token（xapp- で始まる） |
+| allow_from | array | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
+
+## セットアップ手順
+
+1. [Slack API](https://api.slack.com/) にアクセスして新しい Slack アプリを作成する
+2. Socket Mode を有効にして App Level Token を取得する
+3. Bot Token Scopes を追加する（例: `chat:write`、`im:history` など）
+4. アプリをワークスペースにインストールして Bot User OAuth Token を取得する
+5. Bot Token と App Token を設定ファイルに入力する
diff --git a/docs/channels/slack/README.md b/docs/channels/slack/README.md
new file mode 100644
index 000000000..9d5aafab9
--- /dev/null
+++ b/docs/channels/slack/README.md
@@ -0,0 +1,35 @@
+> Back to [README](../../../README.md)
+
+# Slack
+
+Slack is a leading enterprise instant messaging platform. PicoClaw uses Slack's Socket Mode for real-time bidirectional communication, with no need to configure a public webhook endpoint.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "slack": {
+ "enabled": true,
+ "bot_token": "xoxb-...",
+ "app_token": "xapp-...",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled | bool | Yes | Whether to enable the Slack channel |
+| bot_token | string | Yes | Bot User OAuth Token for the Slack bot (starts with xoxb-) |
+| app_token | string | Yes | Socket Mode App Level Token for the Slack app (starts with xapp-) |
+| allow_from | array | No | User ID whitelist; empty means all users are allowed |
+
+## Setup
+
+1. Go to [Slack API](https://api.slack.com/) and create a new Slack app
+2. Enable Socket Mode and obtain the App Level Token
+3. Add Bot Token Scopes (e.g. `chat:write`, `im:history`, etc.)
+4. Install the app to your workspace and obtain the Bot User OAuth Token
+5. Fill in the Bot Token and App Token in the configuration file
diff --git a/docs/channels/slack/README.pt-br.md b/docs/channels/slack/README.pt-br.md
new file mode 100644
index 000000000..ea8a6c0fc
--- /dev/null
+++ b/docs/channels/slack/README.pt-br.md
@@ -0,0 +1,35 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Slack
+
+O Slack é uma das principais plataformas de mensagens instantâneas para empresas. O PicoClaw usa o Socket Mode do Slack para comunicação bidirecional em tempo real, sem necessidade de configurar um endpoint de webhook público.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "slack": {
+ "enabled": true,
+ "bot_token": "xoxb-...",
+ "app_token": "xapp-...",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------- | ------ | ----------- | ---------------------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal Slack deve ser habilitado |
+| bot_token | string | Sim | Bot User OAuth Token do bot Slack (começa com xoxb-) |
+| app_token | string | Sim | App Level Token do Socket Mode do aplicativo Slack (começa com xapp-) |
+| allow_from | array | Não | Lista de permissão de IDs de usuário; vazio permite todos |
+
+## Configuração passo a passo
+
+1. Acesse o [Slack API](https://api.slack.com/) e crie um novo aplicativo Slack
+2. Ative o Socket Mode e obtenha o App Level Token
+3. Adicione Bot Token Scopes (ex.: `chat:write`, `im:history`, etc.)
+4. Instale o aplicativo no seu workspace e obtenha o Bot User OAuth Token
+5. Preencha o Bot Token e o App Token no arquivo de configuração
diff --git a/docs/channels/slack/README.vi.md b/docs/channels/slack/README.vi.md
new file mode 100644
index 000000000..dae84728c
--- /dev/null
+++ b/docs/channels/slack/README.vi.md
@@ -0,0 +1,35 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Slack
+
+Slack là nền tảng nhắn tin tức thì hàng đầu dành cho doanh nghiệp. PicoClaw sử dụng Socket Mode của Slack để giao tiếp hai chiều theo thời gian thực, không cần cấu hình endpoint webhook công khai.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "slack": {
+ "enabled": true,
+ "bot_token": "xoxb-...",
+ "app_token": "xapp-...",
+ "allow_from": []
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
+| enabled | bool | Có | Có bật kênh Slack hay không |
+| bot_token | string | Có | Bot User OAuth Token của Slack bot (bắt đầu bằng xoxb-) |
+| app_token | string | Có | App Level Token Socket Mode của ứng dụng Slack (bắt đầu bằng xapp-) |
+| allow_from | array | Không | Danh sách trắng ID người dùng; để trống cho phép tất cả |
+
+## Quy trình thiết lập
+
+1. Truy cập [Slack API](https://api.slack.com/) và tạo một ứng dụng Slack mới
+2. Bật Socket Mode và lấy App Level Token
+3. Thêm Bot Token Scopes (ví dụ: `chat:write`, `im:history`, v.v.)
+4. Cài đặt ứng dụng vào workspace và lấy Bot User OAuth Token
+5. Điền Bot Token và App Token vào file cấu hình
diff --git a/docs/channels/slack/README.zh.md b/docs/channels/slack/README.zh.md
index 58ebcb566..884039162 100644
--- a/docs/channels/slack/README.zh.md
+++ b/docs/channels/slack/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
# Slack
Slack 是全球领先的企业级即时通讯平台。PicoClaw 采用 Slack 的 Socket Mode 实现实时双向通信，无需配置公开的 Webhook 端点。
diff --git a/docs/channels/telegram/README.fr.md b/docs/channels/telegram/README.fr.md
new file mode 100644
index 000000000..d9ab0644f
--- /dev/null
+++ b/docs/channels/telegram/README.fr.md
@@ -0,0 +1,35 @@
+> Retour au [README](../../../README.fr.md)
+
+# Telegram
+
+Le canal Telegram utilise le long polling via l'API Bot Telegram pour une communication basée sur les bots. Il prend en charge les messages texte, les pièces jointes multimédias (photos, messages vocaux, audio, documents), la transcription vocale via Groq Whisper et la gestion des commandes intégrée.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+ "allow_from": ["123456789"],
+ "proxy": ""
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------- | ------ | ------ | ------------------------------------------------------------------------ |
+| enabled | bool | Oui | Activer ou non le canal Telegram |
+| token | string | Oui | Token de l'API Bot Telegram |
+| allow_from | array | Non | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
+| proxy | string | Non | URL du proxy pour se connecter à l'API Telegram (ex. http://127.0.0.1:7890) |
+
+## Configuration initiale
+
+1. Rechercher `@BotFather` dans Telegram
+2. Envoyer la commande `/newbot` et suivre les instructions pour créer un nouveau bot
+3. Obtenir le Token de l'API HTTP
+4. Renseigner le Token dans le fichier de configuration
+5. (Optionnel) Configurer `allow_from` pour restreindre les identifiants utilisateur autorisés à interagir (les IDs peuvent être obtenus via `@userinfobot`)
diff --git a/docs/channels/telegram/README.ja.md b/docs/channels/telegram/README.ja.md
new file mode 100644
index 000000000..03c48cb64
--- /dev/null
+++ b/docs/channels/telegram/README.ja.md
@@ -0,0 +1,35 @@
+> [README](../../../README.ja.md) に戻る
+
+# Telegram
+
+Telegram チャンネルは、Telegram Bot API を使用したロングポーリングによるボットベースの通信を実装しています。テキストメッセージ、メディア添付ファイル（写真、音声、オーディオ、ドキュメント）、Groq Whisper による音声文字起こし、および組み込みコマンドハンドラーをサポートしています。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+ "allow_from": ["123456789"],
+ "proxy": ""
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------- | ------ | ---- | ----------------------------------------------------------------- |
+| enabled | bool | はい | Telegram チャンネルを有効にするかどうか |
+| token | string | はい | Telegram Bot API トークン |
+| allow_from | array | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
+| proxy | string | いいえ | Telegram API への接続に使用するプロキシ URL (例: http://127.0.0.1:7890) |
+
+## セットアップ手順
+
+1. Telegram で `@BotFather` を検索する
+2. `/newbot` コマンドを送信し、指示に従って新しいボットを作成する
+3. HTTP API トークンを取得する
+4. 設定ファイルにトークンを入力する
+5. (任意) `allow_from` を設定して、対話を許可するユーザー ID を制限する（ID は `@userinfobot` で取得可能）
diff --git a/docs/channels/telegram/README.md b/docs/channels/telegram/README.md
new file mode 100644
index 000000000..86c016a5d
--- /dev/null
+++ b/docs/channels/telegram/README.md
@@ -0,0 +1,55 @@
+> Back to [README](../../../README.md)
+
+# Telegram
+
+The Telegram channel uses long polling via the Telegram Bot API for bot-based communication. It supports text messages, media attachments (photos, voice, audio, documents), voice transcription ([setup](../../providers.md#voice-transcription)), and built-in command handling.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+ "allow_from": ["123456789"],
+ "proxy": ""
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------- | ------ | -------- | ------------------------------------------------------------------ |
+| enabled | bool | Yes | Whether to enable the Telegram channel |
+| token | string | Yes | Telegram Bot API Token |
+| allow_from | array | No | Allowlist of user IDs; empty means all users are allowed |
+| proxy | string | No | Proxy URL for connecting to the Telegram API (e.g. http://127.0.0.1:7890) |
+
+## Setup
+
+1. Search for `@BotFather` in Telegram
+2. Send the `/newbot` command and follow the prompts to create a new bot
+3. Obtain the HTTP API Token
+4. Fill in the Token in the configuration file
+5. (Optional) Configure `allow_from` to restrict which user IDs can interact (you can get IDs via `@userinfobot`)
+
+## Built-in Commands
+
+Telegram auto-registers PicoClaw's top-level bot commands at startup, including `/start`, `/help`, `/show`, `/list`, and `/use`.
+
+Skill-related commands:
+
+- `/list skills` lists the installed skills visible to the current agent.
+- `/use ` forces a skill for a single request.
+- `/use ` arms the skill for your next message in the same chat.
+- `/use clear` clears a pending skill override.
+
+Examples:
+
+```text
+/list skills
+/use git explain how to squash the last 3 commits
+/use git
+explain how to squash the last 3 commits
+```
diff --git a/docs/channels/telegram/README.pt-br.md b/docs/channels/telegram/README.pt-br.md
new file mode 100644
index 000000000..8d2c935b4
--- /dev/null
+++ b/docs/channels/telegram/README.pt-br.md
@@ -0,0 +1,35 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Telegram
+
+O canal Telegram utiliza long polling via a API de Bot do Telegram para comunicação baseada em bots. Suporta mensagens de texto, anexos de mídia (fotos, voz, áudio, documentos), transcrição de voz via Groq Whisper e tratamento de comandos integrado.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+ "allow_from": ["123456789"],
+ "proxy": ""
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
+| enabled | bool | Sim | Se o canal Telegram deve ser habilitado |
+| token | string | Sim | Token da API de Bot do Telegram |
+| allow_from | array | Não | Lista de IDs de usuários permitidos; vazio significa todos os usuários |
+| proxy | string | Não | URL do proxy para conexão com a API do Telegram (ex. http://127.0.0.1:7890) |
+
+## Configuração inicial
+
+1. Pesquise por `@BotFather` no Telegram
+2. Envie o comando `/newbot` e siga as instruções para criar um novo bot
+3. Obtenha o Token da API HTTP
+4. Preencha o Token no arquivo de configuração
+5. (Opcional) Configure `allow_from` para restringir quais IDs de usuário podem interagir (os IDs podem ser obtidos via `@userinfobot`)
diff --git a/docs/channels/telegram/README.vi.md b/docs/channels/telegram/README.vi.md
new file mode 100644
index 000000000..858a9fc41
--- /dev/null
+++ b/docs/channels/telegram/README.vi.md
@@ -0,0 +1,35 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Telegram
+
+Kênh Telegram sử dụng long polling qua Telegram Bot API để giao tiếp dựa trên bot. Hỗ trợ tin nhắn văn bản, tệp đính kèm đa phương tiện (ảnh, giọng nói, âm thanh, tài liệu), chuyển giọng nói thành văn bản qua Groq Whisper và xử lý lệnh tích hợp sẵn.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+ "allow_from": ["123456789"],
+ "proxy": ""
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled | bool | Có | Có bật kênh Telegram hay không |
+| token | string | Có | Token API Bot Telegram |
+| allow_from | array | Không | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả |
+| proxy | string | Không | URL proxy để kết nối với Telegram API (ví dụ: http://127.0.0.1:7890) |
+
+## Hướng dẫn thiết lập
+
+1. Tìm kiếm `@BotFather` trong Telegram
+2. Gửi lệnh `/newbot` và làm theo hướng dẫn để tạo bot mới
+3. Lấy Token API HTTP
+4. Điền Token vào file cấu hình
+5. (Tùy chọn) Cấu hình `allow_from` để giới hạn ID người dùng được phép tương tác (có thể lấy ID qua `@userinfobot`)
diff --git a/docs/channels/telegram/README.zh.md b/docs/channels/telegram/README.zh.md
index d453c68fa..1d9dcc46e 100644
--- a/docs/channels/telegram/README.zh.md
+++ b/docs/channels/telegram/README.zh.md
@@ -1,6 +1,8 @@
+> 返回 [README](../../../README.zh.md)
+
# Telegram
-Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、通过 Groq Whisper 进行语音转录以及内置命令处理器。
+Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、语音转录（配置见[提供商与模型配置](../../zh/providers.md#语音转录)），以及内置命令处理器。
## 配置
@@ -31,3 +33,23 @@ Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器
3. 获取 HTTP API Token
4. 将 Token 填入配置文件中
5. (可选) 配置 `allow_from` 以限制允许互动的用户 ID (可通过 `@userinfobot` 获取 ID)
+
+## 内置命令
+
+Telegram 会在启动时自动注册 PicoClaw 的顶级 Bot 命令，包括 `/start`、`/help`、`/show`、`/list` 和 `/use`。
+
+与技能相关的命令：
+
+- `/list skills`：列出当前 Agent 可见的已安装技能。
+- `/use `：只在本次请求中强制使用指定技能。
+- `/use `：为同一聊天中的下一条消息预先启用该技能。
+- `/use clear`：清除待应用的技能覆盖。
+
+示例：
+
+```text
+/list skills
+/use git explain how to squash the last 3 commits
+/use italiapersonalfinance
+dammi le ultime news
+```
diff --git a/docs/channels/wecom/wecom_aibot/README.fr.md b/docs/channels/wecom/wecom_aibot/README.fr.md
new file mode 100644
index 000000000..8020dd7b0
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.fr.md
@@ -0,0 +1,118 @@
+> Retour au [README](../../../../README.fr.md)
+
+# WeCom AI Bot
+
+Le WeCom AI Bot est une méthode d'intégration de conversation IA officiellement fournie par WeCom. Il prend en charge les conversations privées et de groupe, intègre un protocole de réponse en streaming et supporte l'envoi proactif de la réponse finale via `response_url` en cas de dépassement de délai.
+
+## Comparaison avec les autres canaux WeCom
+
+| Fonctionnalité | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|----------------|-----------|-----------|-----------------|
+| Chat privé | ✅ | ✅ | ✅ |
+| Chat de groupe | ✅ | ❌ | ✅ |
+| Sortie en streaming | ❌ | ❌ | ✅ |
+| Push proactif en cas de timeout | ❌ | ✅ | ✅ |
+| Complexité de configuration | Faible | Élevée | Moyenne |
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "wecom_aibot": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-aibot",
+ "allow_from": [],
+ "welcome_message": "你好！有什么可以帮助你的吗？",
+ "max_steps": 10
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------------- | ------ | ------ | -------------------------------------------------- |
+| token | string | Oui | Jeton de vérification du callback, configuré sur la page de gestion de l'AI Bot |
+| encoding_aes_key | string | Oui | Clé AES de 43 caractères, générée aléatoirement sur la page de gestion de l'AI Bot |
+| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/wecom-aibot) |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs ; un tableau vide autorise tous les utilisateurs |
+| welcome_message | string | Non | Message de bienvenue envoyé à l'ouverture du chat ; laisser vide pour désactiver |
+| reply_timeout | int | Non | Délai de réponse en secondes (par défaut : 5) |
+| max_steps | int | Non | Nombre maximum d'étapes d'exécution de l'agent (par défaut : 10) |
+
+## Procédure de configuration
+
+1. Connectez-vous à la [console d'administration WeCom](https://work.weixin.qq.com/wework_admin)
+2. Accédez à « Gestion des applications » → « AI Bot », puis créez ou sélectionnez un AI Bot
+3. Sur la page de configuration de l'AI Bot, renseignez les informations de « Réception des messages » :
+ - **URL** : `http://:18790/webhook/wecom-aibot`
+ - **Token** : Généré aléatoirement ou personnalisé
+ - **EncodingAESKey** : Cliquez sur « Générer aléatoirement » pour obtenir une clé de 43 caractères
+4. Saisissez le Token et l'EncodingAESKey dans le fichier de configuration PicoClaw, démarrez le service, puis revenez à la console d'administration pour enregistrer (WeCom enverra une requête de vérification)
+
+> [!TIP]
+> Le serveur doit être accessible par les serveurs WeCom. Si vous êtes sur un intranet ou en développement local, utilisez [ngrok](https://ngrok.com) ou frp pour le tunneling.
+
+## Protocole de réponse en streaming
+
+Le WeCom AI Bot utilise un protocole de « pull en streaming », différent de la réponse unique d'un webhook standard :
+
+```
+L'utilisateur envoie un message
+ │
+ ▼
+PicoClaw retourne immédiatement {finish: false} (l'agent commence le traitement)
+ │
+ ▼
+WeCom effectue un pull environ toutes les 1 seconde avec {msgtype: "stream", stream: {id: "..."}}
+ │
+ ├─ Agent non terminé → retourne {finish: false} (continuer à attendre)
+ │
+ └─ Agent terminé → retourne {finish: true, content: "contenu de la réponse"}
+```
+
+**Gestion du timeout** (tâche dépassant 30 secondes) :
+
+Si le traitement de l'agent dépasse environ 30 secondes (la fenêtre de polling maximale de WeCom est de 6 minutes), PicoClaw va :
+
+1. Fermer immédiatement le stream et afficher à l'utilisateur : « ⏳ 正在处理中，请稍候，结果将稍后发送。 »
+2. L'agent continue de s'exécuter en arrière-plan
+3. Une fois l'agent terminé, la réponse finale est envoyée proactivement à l'utilisateur via le `response_url` inclus dans le message
+
+> `response_url` est émis par WeCom, valable 1 heure, utilisable une seule fois, sans chiffrement requis — il suffit de POSTer directement le corps du message markdown.
+
+## Message de bienvenue
+
+Lorsque `welcome_message` est configuré, PicoClaw répond automatiquement avec ce message lorsqu'un utilisateur ouvre la fenêtre de chat avec l'AI Bot (événement `enter_chat`). Laisser vide pour ignorer silencieusement.
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## FAQ
+
+### Échec de la vérification de l'URL de callback
+
+- Vérifiez que le pare-feu du serveur autorise le port concerné (par défaut 18790)
+- Vérifiez que `token` et `encoding_aes_key` sont correctement renseignés
+- Consultez les logs PicoClaw pour voir si une requête GET de WeCom a été reçue
+
+### Les messages ne reçoivent pas de réponse
+
+- Vérifiez que `allow_from` ne restreint pas accidentellement l'expéditeur
+- Recherchez `context canceled` ou des erreurs d'agent dans les logs
+- Vérifiez que la configuration de l'agent (ex. `model_name`) est correcte
+
+### Pas de push final reçu pour les tâches longues
+
+- Vérifiez que le callback du message inclut `response_url` (uniquement supporté par la nouvelle version du WeCom AI Bot)
+- Vérifiez que le serveur peut effectuer des requêtes sortantes (nécessite un POST vers `response_url`)
+- Consultez les logs pour les mots-clés `response_url mode` et `Sending reply via response_url`
+
+## Références
+
+- [Documentation d'intégration WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
+- [Description du protocole de réponse en streaming](https://developer.work.weixin.qq.com/document/path/100719)
+- [Réponse proactive via response_url](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.ja.md b/docs/channels/wecom/wecom_aibot/README.ja.md
new file mode 100644
index 000000000..210caffb4
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.ja.md
@@ -0,0 +1,118 @@
+> [README](../../../../README.ja.md) に戻る
+
+# 企業WeChat AIボット
+
+企業WeChat AIボット（AI Bot）は、企業WeChatが公式に提供するAI会話連携方式です。プライベートチャットとグループチャットの両方をサポートし、ストリーミングレスポンスプロトコルを内蔵しており、タイムアウト後に `response_url` を通じて最終返信をプッシュする機能もサポートしています。
+
+## 他のWeCom チャンネルとの比較
+
+| 機能 | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|------|-----------|-----------|-----------------|
+| プライベートチャット | ✅ | ✅ | ✅ |
+| グループチャット | ✅ | ❌ | ✅ |
+| ストリーミング出力 | ❌ | ❌ | ✅ |
+| タイムアウト時のプッシュ | ❌ | ✅ | ✅ |
+| 設定の複雑さ | 低 | 高 | 中 |
+
+## 設定
+
+```json
+{
+ "channels": {
+ "wecom_aibot": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-aibot",
+ "allow_from": [],
+ "welcome_message": "你好！有什么可以帮助你的吗？",
+ "max_steps": 10
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------------- | ------ | ---- | -------------------------------------------------- |
+| token | string | はい | コールバック検証トークン。AIボット管理ページで設定 |
+| encoding_aes_key | string | はい | 43文字のAESキー。AIボット管理ページでランダム生成 |
+| webhook_path | string | いいえ | Webhookパス（デフォルト：/webhook/wecom-aibot） |
+| allow_from | array | いいえ | ユーザーIDの許可リスト。空配列は全ユーザーを許可 |
+| welcome_message | string | いいえ | ユーザーがチャットを開いたときに送信するウェルカムメッセージ。空白の場合は送信しない |
+| reply_timeout | int | いいえ | 返信タイムアウト（秒、デフォルト：5） |
+| max_steps | int | いいえ | エージェントの最大実行ステップ数（デフォルト：10） |
+
+## セットアップ手順
+
+1. [企業WeChat管理コンソール](https://work.weixin.qq.com/wework_admin) にログイン
+2. 「アプリ管理」→「AIボット」に進み、AIボットを作成または選択
+3. AIボット設定ページで「メッセージ受信」情報を入力：
+ - **URL**：`http://:18790/webhook/wecom-aibot`
+ - **Token**：ランダム生成またはカスタム
+ - **EncodingAESKey**：「ランダム生成」をクリックして43文字のキーを取得
+4. TokenとEncodingAESKeyをPicoClawの設定ファイルに入力し、サービスを起動してから管理コンソールに戻って保存（企業WeChatが検証リクエストを送信します）
+
+> [!TIP]
+> サーバーは企業WeChatのサーバーからアクセス可能である必要があります。イントラネットやローカル開発環境の場合は、[ngrok](https://ngrok.com) またはfrpを使用してトンネリングしてください。
+
+## ストリーミングレスポンスプロトコル
+
+WeCom AIボットは「ストリーミングプル」プロトコルを使用しており、通常のWebhookの一回限りの返信とは異なります：
+
+```
+ユーザーがメッセージを送信
+ │
+ ▼
+PicoClawが即座に {finish: false} を返す（エージェントが処理開始）
+ │
+ ▼
+企業WeChatが約1秒ごとに {msgtype: "stream", stream: {id: "..."}} でプル
+ │
+ ├─ エージェント未完了 → {finish: false} を返す（待機継続）
+ │
+ └─ エージェント完了 → {finish: true, content: "返信内容"} を返す
+```
+
+**タイムアウト処理**（タスクが30秒を超える場合）：
+
+エージェントの処理時間が約30秒を超えた場合（企業WeChatの最大ポーリングウィンドウは6分）、PicoClawは：
+
+1. 即座にストリームを閉じ、ユーザーに「⏳ 正在处理中，请稍候，结果将稍后发送。」と表示
+2. エージェントはバックグラウンドで処理を継続
+3. エージェント完了後、メッセージに含まれる `response_url` を通じて最終返信をユーザーにプッシュ
+
+> `response_url` は企業WeChatが発行し、有効期限は1時間、使用は1回限りで、暗号化不要。マークダウンメッセージ本文をそのままPOSTするだけです。
+
+## ウェルカムメッセージ
+
+`welcome_message` を設定すると、ユーザーがAIボットとのチャットウィンドウを開いたとき（`enter_chat` イベント）に、PicoClawが自動的にそのメッセージを返信します。空白の場合は無視されます。
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## よくある質問
+
+### コールバックURL検証の失敗
+
+- サーバーのファイアウォールで該当ポートが開放されているか確認（デフォルト18790）
+- `token` と `encoding_aes_key` が正しく入力されているか確認
+- PicoClawのログに企業WeChatからのGETリクエストが届いているか確認
+
+### メッセージに返信がない
+
+- `allow_from` が誤って送信者を制限していないか確認
+- ログに `context canceled` またはエージェントエラーが出ていないか確認
+- エージェント設定（`model_name` など）が正しいか確認
+
+### 長時間タスクで最終プッシュが届かない
+
+- メッセージコールバックに `response_url` が含まれているか確認（新バージョンの企業WeChat AIボットのみ対応）
+- サーバーが外部ネットワークへのアウトバウンドリクエストを送信できるか確認（`response_url` へのPOSTが必要）
+- ログのキーワード `response_url mode` と `Sending reply via response_url` を確認
+
+## 参考ドキュメント
+
+- [企業WeChat AIボット連携ドキュメント](https://developer.work.weixin.qq.com/document/path/100719)
+- [ストリーミングレスポンスプロトコルの説明](https://developer.work.weixin.qq.com/document/path/100719)
+- [response_url によるプロアクティブ返信](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.md b/docs/channels/wecom/wecom_aibot/README.md
new file mode 100644
index 000000000..31d831617
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.md
@@ -0,0 +1,118 @@
+> Back to [README](../../../../README.md)
+
+# WeCom AI Bot
+
+The WeCom AI Bot is an official AI conversation integration provided by WeCom. It supports both private and group chats, has a built-in streaming response protocol, and supports proactively pushing the final reply via `response_url` after a timeout.
+
+## Comparison with Other WeCom Channels
+
+| Feature | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|---------|-----------|-----------|-----------------|
+| Private Chat | ✅ | ✅ | ✅ |
+| Group Chat | ✅ | ❌ | ✅ |
+| Streaming Output | ❌ | ❌ | ✅ |
+| Proactive Push on Timeout | ❌ | ✅ | ✅ |
+| Configuration Complexity | Low | High | Medium |
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "wecom_aibot": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-aibot",
+ "allow_from": [],
+ "welcome_message": "你好！有什么可以帮助你的吗？",
+ "max_steps": 10
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------------- | ------ | -------- | -------------------------------------------------- |
+| token | string | Yes | Callback verification token, configured on the AI Bot management page |
+| encoding_aes_key | string | Yes | 43-character AES key, randomly generated on the AI Bot management page |
+| webhook_path | string | No | Webhook path (default: /webhook/wecom-aibot) |
+| allow_from | array | No | User ID allowlist; empty array allows all users |
+| welcome_message | string | No | Welcome message sent when a user opens the chat; leave empty to disable |
+| reply_timeout | int | No | Reply timeout in seconds (default: 5) |
+| max_steps | int | No | Maximum agent execution steps (default: 10) |
+
+## Setup
+
+1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin)
+2. Go to "App Management" → "AI Bot", then create or select an AI Bot
+3. On the AI Bot configuration page, fill in the "Message Reception" details:
+ - **URL**: `http://:18790/webhook/wecom-aibot`
+ - **Token**: Randomly generated or custom
+ - **EncodingAESKey**: Click "Random Generate" to get a 43-character key
+4. Enter the Token and EncodingAESKey into the PicoClaw config file, start the service, then return to the admin console to save (WeCom will send a verification request)
+
+> [!TIP]
+> The server must be accessible by WeCom's servers. If you are on an intranet or developing locally, use [ngrok](https://ngrok.com) or frp for tunneling.
+
+## Streaming Response Protocol
+
+WeCom AI Bot uses a "streaming pull" protocol, which differs from the one-shot reply of a standard webhook:
+
+```
+User sends a message
+ │
+ ▼
+PicoClaw immediately returns {finish: false} (Agent starts processing)
+ │
+ ▼
+WeCom pulls approximately every 1 second with {msgtype: "stream", stream: {id: "..."}}
+ │
+ ├─ Agent not done → returns {finish: false} (keep waiting)
+ │
+ └─ Agent done → returns {finish: true, content: "reply content"}
+```
+
+**Timeout Handling** (task exceeds 30 seconds):
+
+If the Agent takes longer than approximately 30 seconds (WeCom's maximum polling window is 6 minutes), PicoClaw will:
+
+1. Immediately close the stream and show the user: "⏳ 正在处理中，请稍候，结果将稍后发送。"
+2. The Agent continues running in the background
+3. Once the Agent finishes, the final reply is proactively pushed to the user via the `response_url` included in the message
+
+> `response_url` is issued by WeCom, valid for 1 hour, can only be used once, requires no encryption — just POST the markdown message body directly.
+
+## Welcome Message
+
+When `welcome_message` is configured, PicoClaw will automatically reply with it when a user opens the chat window with the AI Bot (`enter_chat` event). Leave it empty to silently ignore the event.
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## FAQ
+
+### Callback URL Verification Failed
+
+- Confirm the server firewall has the relevant port open (default 18790)
+- Confirm `token` and `encoding_aes_key` are entered correctly
+- Check PicoClaw logs to see if a GET request from WeCom was received
+
+### Messages Not Getting a Reply
+
+- Check whether `allow_from` is accidentally restricting the sender
+- Look for `context canceled` or Agent errors in the logs
+- Confirm the Agent configuration (e.g., `model_name`) is correct
+
+### No Final Push Received for Long-Running Tasks
+
+- Confirm the message callback includes `response_url` (only supported by the newer WeCom AI Bot)
+- Confirm the server can make outbound requests (needs to POST to `response_url`)
+- Check logs for keywords `response_url mode` and `Sending reply via response_url`
+
+## Reference
+
+- [WeCom AI Bot Integration Docs](https://developer.work.weixin.qq.com/document/path/100719)
+- [Streaming Response Protocol](https://developer.work.weixin.qq.com/document/path/100719)
+- [Proactive Reply via response_url](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.pt-br.md b/docs/channels/wecom/wecom_aibot/README.pt-br.md
new file mode 100644
index 000000000..1ab735c41
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.pt-br.md
@@ -0,0 +1,118 @@
+> Voltar ao [README](../../../../README.pt-br.md)
+
+# WeCom AI Bot
+
+O WeCom AI Bot é uma forma oficial de integração de conversas com IA fornecida pelo WeCom. Suporta conversas privadas e em grupo, possui um protocolo de resposta em streaming integrado e suporta o envio proativo da resposta final via `response_url` após um timeout.
+
+## Comparação com outros canais WeCom
+
+| Recurso | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|---------|-----------|-----------|-----------------|
+| Chat privado | ✅ | ✅ | ✅ |
+| Chat em grupo | ✅ | ❌ | ✅ |
+| Saída em streaming | ❌ | ❌ | ✅ |
+| Push proativo em timeout | ❌ | ✅ | ✅ |
+| Complexidade de configuração | Baixa | Alta | Média |
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "wecom_aibot": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-aibot",
+ "allow_from": [],
+ "welcome_message": "你好！有什么可以帮助你的吗？",
+ "max_steps": 10
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------------- | ------ | ----------- | -------------------------------------------------- |
+| token | string | Sim | Token de verificação de callback, configurado na página de gerenciamento do AI Bot |
+| encoding_aes_key | string | Sim | Chave AES de 43 caracteres, gerada aleatoriamente na página de gerenciamento do AI Bot |
+| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/wecom-aibot) |
+| allow_from | array | Não | Lista de permissão de IDs de usuários; array vazio permite todos os usuários |
+| welcome_message | string | Não | Mensagem de boas-vindas enviada quando o usuário abre o chat; deixe vazio para desativar |
+| reply_timeout | int | Não | Timeout de resposta em segundos (padrão: 5) |
+| max_steps | int | Não | Número máximo de etapas de execução do agente (padrão: 10) |
+
+## Configuração passo a passo
+
+1. Faça login no [Console de Administração do WeCom](https://work.weixin.qq.com/wework_admin)
+2. Acesse "Gerenciamento de Apps" → "AI Bot", depois crie ou selecione um AI Bot
+3. Na página de configuração do AI Bot, preencha as informações de "Recebimento de Mensagens":
+ - **URL**: `http://:18790/webhook/wecom-aibot`
+ - **Token**: Gerado aleatoriamente ou personalizado
+ - **EncodingAESKey**: Clique em "Gerar Aleatoriamente" para obter uma chave de 43 caracteres
+4. Insira o Token e o EncodingAESKey no arquivo de configuração do PicoClaw, inicie o serviço e volte ao console de administração para salvar (o WeCom enviará uma requisição de verificação)
+
+> [!TIP]
+> O servidor precisa ser acessível pelos servidores do WeCom. Se estiver em uma intranet ou desenvolvendo localmente, use [ngrok](https://ngrok.com) ou frp para tunelamento.
+
+## Protocolo de resposta em streaming
+
+O WeCom AI Bot usa um protocolo de "pull em streaming", diferente da resposta única de um webhook padrão:
+
+```
+Usuário envia uma mensagem
+ │
+ ▼
+PicoClaw retorna imediatamente {finish: false} (Agente começa a processar)
+ │
+ ▼
+WeCom faz pull aproximadamente a cada 1 segundo com {msgtype: "stream", stream: {id: "..."}}
+ │
+ ├─ Agente não concluído → retorna {finish: false} (continuar aguardando)
+ │
+ └─ Agente concluído → retorna {finish: true, content: "conteúdo da resposta"}
+```
+
+**Tratamento de timeout** (tarefa excede 30 segundos):
+
+Se o processamento do agente demorar mais de aproximadamente 30 segundos (a janela máxima de polling do WeCom é de 6 minutos), o PicoClaw irá:
+
+1. Fechar imediatamente o stream e exibir ao usuário: "⏳ 正在处理中，请稍候，结果将稍后发送。"
+2. O agente continua executando em segundo plano
+3. Após a conclusão do agente, a resposta final é enviada proativamente ao usuário via `response_url` incluído na mensagem
+
+> `response_url` é emitido pelo WeCom, válido por 1 hora, pode ser usado apenas uma vez, sem necessidade de criptografia — basta fazer um POST com o corpo da mensagem em markdown diretamente.
+
+## Mensagem de boas-vindas
+
+Quando `welcome_message` está configurado, o PicoClaw responde automaticamente com essa mensagem quando um usuário abre a janela de chat com o AI Bot (evento `enter_chat`). Deixe vazio para ignorar silenciosamente.
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## Perguntas frequentes
+
+### Falha na verificação da URL de callback
+
+- Confirme que o firewall do servidor tem a porta correspondente aberta (padrão 18790)
+- Confirme que `token` e `encoding_aes_key` estão preenchidos corretamente
+- Verifique os logs do PicoClaw para ver se uma requisição GET do WeCom foi recebida
+
+### Mensagens sem resposta
+
+- Verifique se `allow_from` está restringindo acidentalmente o remetente
+- Procure por `context canceled` ou erros do agente nos logs
+- Confirme que a configuração do agente (ex.: `model_name`) está correta
+
+### Nenhum push final recebido para tarefas longas
+
+- Confirme que o callback da mensagem inclui `response_url` (suportado apenas pelo novo WeCom AI Bot)
+- Confirme que o servidor consegue fazer requisições de saída (precisa fazer POST para `response_url`)
+- Verifique nos logs as palavras-chave `response_url mode` e `Sending reply via response_url`
+
+## Referências
+
+- [Documentação de integração do WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
+- [Descrição do protocolo de resposta em streaming](https://developer.work.weixin.qq.com/document/path/100719)
+- [Resposta proativa via response_url](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.vi.md b/docs/channels/wecom/wecom_aibot/README.vi.md
new file mode 100644
index 000000000..cb6586e6e
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.vi.md
@@ -0,0 +1,118 @@
+> Quay lại [README](../../../../README.vi.md)
+
+# WeCom AI Bot
+
+WeCom AI Bot là phương thức tích hợp hội thoại AI chính thức do WeCom cung cấp. Hỗ trợ cả chat riêng tư và chat nhóm, tích hợp giao thức phản hồi streaming, và hỗ trợ chủ động đẩy phản hồi cuối cùng qua `response_url` sau khi hết thời gian chờ.
+
+## So sánh với các kênh WeCom khác
+
+| Tính năng | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|-----------|-----------|-----------|-----------------|
+| Chat riêng tư | ✅ | ✅ | ✅ |
+| Chat nhóm | ✅ | ❌ | ✅ |
+| Đầu ra streaming | ❌ | ❌ | ✅ |
+| Đẩy chủ động khi timeout | ❌ | ✅ | ✅ |
+| Độ phức tạp cấu hình | Thấp | Cao | Trung bình |
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "wecom_aibot": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-aibot",
+ "allow_from": [],
+ "welcome_message": "你好！有什么可以帮助你的吗？",
+ "max_steps": 10
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------------- | ------ | --------- | -------------------------------------------------- |
+| token | string | Có | Token xác minh callback, cấu hình trên trang quản lý AI Bot |
+| encoding_aes_key | string | Có | Khóa AES 43 ký tự, được tạo ngẫu nhiên trên trang quản lý AI Bot |
+| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/wecom-aibot) |
+| allow_from | array | Không | Danh sách cho phép ID người dùng; mảng rỗng cho phép tất cả người dùng |
+| welcome_message | string | Không | Tin nhắn chào mừng gửi khi người dùng mở chat; để trống để tắt |
+| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây (mặc định: 5) |
+| max_steps | int | Không | Số bước thực thi tối đa của agent (mặc định: 10) |
+
+## Hướng dẫn thiết lập
+
+1. Đăng nhập vào [Bảng điều khiển quản trị WeCom](https://work.weixin.qq.com/wework_admin)
+2. Vào "Quản lý ứng dụng" → "AI Bot", sau đó tạo hoặc chọn một AI Bot
+3. Trên trang cấu hình AI Bot, điền thông tin "Nhận tin nhắn":
+ - **URL**: `http://:18790/webhook/wecom-aibot`
+ - **Token**: Tạo ngẫu nhiên hoặc tùy chỉnh
+ - **EncodingAESKey**: Nhấp "Tạo ngẫu nhiên" để lấy khóa 43 ký tự
+4. Nhập Token và EncodingAESKey vào file cấu hình PicoClaw, khởi động dịch vụ rồi quay lại bảng điều khiển quản trị để lưu (WeCom sẽ gửi yêu cầu xác minh)
+
+> [!TIP]
+> Máy chủ cần có thể truy cập được từ các máy chủ WeCom. Nếu bạn đang ở mạng nội bộ hoặc phát triển cục bộ, hãy sử dụng [ngrok](https://ngrok.com) hoặc frp để tạo tunnel.
+
+## Giao thức phản hồi streaming
+
+WeCom AI Bot sử dụng giao thức "pull streaming", khác với phản hồi một lần của webhook thông thường:
+
+```
+Người dùng gửi tin nhắn
+ │
+ ▼
+PicoClaw trả về ngay {finish: false} (Agent bắt đầu xử lý)
+ │
+ ▼
+WeCom pull khoảng mỗi 1 giây với {msgtype: "stream", stream: {id: "..."}}
+ │
+ ├─ Agent chưa xong → trả về {finish: false} (tiếp tục chờ)
+ │
+ └─ Agent xong → trả về {finish: true, content: "nội dung phản hồi"}
+```
+
+**Xử lý timeout** (tác vụ vượt quá 30 giây):
+
+Nếu thời gian xử lý của agent vượt quá khoảng 30 giây (cửa sổ polling tối đa của WeCom là 6 phút), PicoClaw sẽ:
+
+1. Đóng stream ngay lập tức và hiển thị cho người dùng: "⏳ 正在处理中，请稍候，结果将稍后发送。"
+2. Agent tiếp tục chạy ở nền
+3. Sau khi agent hoàn thành, phản hồi cuối cùng được chủ động đẩy đến người dùng qua `response_url` có trong tin nhắn
+
+> `response_url` do WeCom cấp, có hiệu lực 1 giờ, chỉ dùng được một lần, không cần mã hóa — chỉ cần POST trực tiếp nội dung tin nhắn markdown.
+
+## Tin nhắn chào mừng
+
+Khi `welcome_message` được cấu hình, PicoClaw sẽ tự động phản hồi bằng tin nhắn đó khi người dùng mở cửa sổ chat với AI Bot (sự kiện `enter_chat`). Để trống để bỏ qua im lặng.
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## Câu hỏi thường gặp
+
+### Xác minh URL callback thất bại
+
+- Xác nhận tường lửa máy chủ đã mở cổng tương ứng (mặc định 18790)
+- Xác nhận `token` và `encoding_aes_key` được điền đúng
+- Kiểm tra log PicoClaw xem có nhận được yêu cầu GET từ WeCom không
+
+### Tin nhắn không nhận được phản hồi
+
+- Kiểm tra xem `allow_from` có vô tình hạn chế người gửi không
+- Tìm `context canceled` hoặc lỗi agent trong log
+- Xác nhận cấu hình agent (ví dụ: `model_name`) là đúng
+
+### Không nhận được push cuối cùng cho tác vụ dài
+
+- Xác nhận callback tin nhắn có chứa `response_url` (chỉ hỗ trợ bởi WeCom AI Bot phiên bản mới)
+- Xác nhận máy chủ có thể thực hiện yêu cầu ra ngoài (cần POST đến `response_url`)
+- Kiểm tra log với từ khóa `response_url mode` và `Sending reply via response_url`
+
+## Tài liệu tham khảo
+
+- [Tài liệu tích hợp WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
+- [Mô tả giao thức phản hồi streaming](https://developer.work.weixin.qq.com/document/path/100719)
+- [Phản hồi chủ động qua response_url](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.zh.md b/docs/channels/wecom/wecom_aibot/README.zh.md
index de4fba445..9da5ee1b9 100644
--- a/docs/channels/wecom/wecom_aibot/README.zh.md
+++ b/docs/channels/wecom/wecom_aibot/README.zh.md
@@ -1,6 +1,11 @@
+> 返回 [README](../../../../README.zh.md)
+
# 企业微信智能机器人 (AI Bot)
-企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议。
+企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议。PicoClaw 当前同时支持两种接入模式：
+
+- WebSocket 长连接模式：使用 `bot_id` + `secret`，优先级更高，推荐使用
+- Webhook 短连接模式：使用 `token` + `encoding_aes_key`，兼容传统回调，并支持超时后通过 `response_url` 主动推送最终回复
## 与其他 WeCom 通道的对比
@@ -14,6 +19,8 @@
## 配置
+### WebSocket 长连接模式（推荐）
+
```json
{
"channels": {
@@ -29,22 +36,113 @@
}
```
-| 字段 | 类型 | 必填 | 描述 |
-| ---------------- | ------ | ---- | -------------------------------------------------- |
-| bot_id | string | 是 | AI Bot 的唯一标识，在 AI Bot 管理页面配置 |
-| secret | string | 是 | AI Bot 的密钥，在 AI Bot 管理页面配置 |
-| allow_from | array | 否 | 用户 ID 白名单，空数组表示允许所有用户 |
-| welcome_message | string | 否 | 用户进入聊天时发送的欢迎语，留空则不发送 |
-| reply_timeout | int | 否 | 回复超时时间（秒，默认：5） |
-| max_steps | int | 否 | Agent 最大执行步骤数（默认：10） |
+### Webhook 短连接模式
+
+```json
+{
+ "channels": {
+ "wecom_aibot": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-aibot",
+ "allow_from": [],
+ "welcome_message": "你好！有什么可以帮助你的吗？",
+ "processing_message": "⏳ Processing, please wait. The results will be sent shortly.",
+ "max_steps": 10
+ }
+ }
+}
+```
+
+### WebSocket 模式字段
+
+| 字段 | 类型 | 必填 | 描述 |
+|--------|--------|------|--------------------------------------------|
+| bot_id | string | 是 | AI Bot 的唯一标识，在 AI Bot 管理页面配置 |
+| secret | string | 是 | AI Bot 的密钥，在 AI Bot 管理页面配置 |
+
+### Webhook 模式字段
+
+| 字段 | 类型 | 必填 | 描述 |
+|------------------|--------|------|----------------------------------------------|
+| token | string | 是 | 回调验证令牌，在 AI Bot 管理页面配置 |
+| encoding_aes_key | string | 是 | 43 字符 AES 密钥，在 AI Bot 管理页面随机生成 |
+| webhook_path | string | 否 | Webhook 路径，默认 `/webhook/wecom-aibot` |
+| processing_message | string | 否 | 流式超时后返回给用户的提示语 |
+
+### 通用字段
+
+| 字段 | 类型 | 必填 | 描述 |
+|-----------------|--------|------|------------------------------------------|
+| allow_from | array | 否 | 用户 ID 白名单，空数组表示允许所有用户 |
+| welcome_message | string | 否 | 用户进入聊天时发送的欢迎语，留空则不发送 |
+| reply_timeout | int | 否 | 回复超时时间（秒，默认：5） |
+| max_steps | int | 否 | Agent 最大执行步骤数（默认：10） |
+
+## 模式选择
+
+- 当 `bot_id` 和 `secret` 同时存在时，PicoClaw 会优先使用 WebSocket 长连接模式
+- 否则，当 `token` 和 `encoding_aes_key` 同时存在时，PicoClaw 会使用 Webhook 短连接模式
## 设置流程
+### WebSocket 长连接模式
+
1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
-3. 在 AI Bot 配置页面，配置Bot的名称、头像等信息，获取 `Bot ID` 和 `Secret`
+3. 在 AI Bot 配置页面，配置 Bot 的名称、头像等信息，获取 `Bot ID` 和 `Secret`
4. 在 PicoClaw 配置文件中添加上述配置，重启 PicoClaw
+### Webhook 短连接模式
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
+2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
+3. 在 AI Bot 配置页面，填写"消息接收"信息：
+ - **URL**：`http://:18790/webhook/wecom-aibot`
+ - **Token**：随机生成或自定义
+ - **EncodingAESKey**：点击"随机生成"，得到 43 字符密钥
+4. 将 Token 和 EncodingAESKey 填入 PicoClaw 配置文件，启动服务后回到管理后台保存
+
+> [!TIP]
+> 服务器需要能被企业微信服务器访问。如在内网或本地开发，可使用 [ngrok](https://ngrok.com) 或 frp 做内网穿透。
+
+## Webhook 模式的流式响应协议
+
+Webhook 模式使用"流式拉取"协议，区别于普通 Webhook 的一次性回复：
+
+```
+用户发消息
+ │
+ ▼
+PicoClaw 立即返回 {finish: false}（Agent 开始处理）
+ │
+ ▼
+企业微信每隔约 1 秒拉取一次 {msgtype: "stream", stream: {id: "..."}}
+ │
+ ├─ Agent 未完成 → 返回 {finish: false}（继续等待）
+ │
+ └─ Agent 完成 → 返回 {finish: true, content: "回答内容"}
+```
+
+**超时处理**（任务超过约 30 秒）：
+
+若 Agent 处理时间超过轮询窗口，PicoClaw 会：
+
+1. 立即关闭流，向用户显示 `processing_message` 提示语
+2. Agent 继续在后台运行
+3. Agent 完成后，通过消息中携带的 `response_url` 将最终回复主动推送给用户
+
+> `response_url` 由企业微信颁发，有效期 1 小时，只可使用一次，无需加密，直接 POST markdown 消息体即可。
+
+## 超时提示语
+
+配置 `processing_message` 后，当 Webhook 模式的流式轮询超时并切换到 `response_url` 主动推送模式时，PicoClaw 会先返回这段提示语来结束当前流。
+
+```json
+"processing_message": "⏳ Processing, please wait. The results will be sent shortly."
+```
+
## 欢迎语
配置 `welcome_message` 后，当用户打开与 AI Bot 的聊天窗口时（`enter_chat` 事件），PicoClaw 会自动回复该欢迎语。留空则静默忽略。
@@ -55,12 +153,33 @@
## 常见问题
+### WebSocket 模式无法连接
+
+- 检查 `bot_id` 和 `secret` 是否填写正确
+- 查看日志中是否有 WebSocket 连接或鉴权失败信息
+- 确认服务器可以访问企业微信长连接接口
+
+### 回调 URL 验证失败
+
+
+- 确认 `token` 与 `encoding_aes_key` 填写正确
+- 确认服务器防火墙已开放对应端口
+- 检查 PicoClaw 日志是否收到了来自企业微信的验证请求
+
### 消息没有回复
- 检查 `allow_from` 是否意外限制了发送者
- 查看日志中是否出现 `context canceled` 或 Agent 错误
- 确认 Agent 配置（`model_name` 等）正确
+### 超长任务没有收到最终推送
+
+- 确认消息回调中携带了 `response_url`
+- 确认服务器能主动访问外网
+- 查看日志关键词 `response_url mode` 和 `Sending reply via response_url`
+
## 参考文档
- [企业微信 AI Bot 接入文档](https://developer.work.weixin.qq.com/document/path/101463)
+- [流式响应协议说明](https://developer.work.weixin.qq.com/document/path/100719)
+- [response_url 主动回复](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_app/README.fr.md b/docs/channels/wecom/wecom_app/README.fr.md
new file mode 100644
index 000000000..f95426497
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.fr.md
@@ -0,0 +1,47 @@
+> Retour au [README](../../../../README.fr.md)
+
+# Application interne WeCom
+
+Une application interne WeCom est une application créée par une entreprise au sein de WeCom, principalement destinée à un usage interne. Grâce aux applications internes WeCom, les entreprises peuvent assurer une communication et une collaboration efficaces avec leurs employés, améliorant ainsi la productivité.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "wecom_app": {
+ "enabled": true,
+ "corp_id": "wwxxxxxxxxxxxxxxxx",
+ "corp_secret": "YOUR_CORP_SECRET",
+ "agent_id": 1000002,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-app",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------------- | ------ | ------ | ---------------------------------------- |
+| corp_id | string | Oui | ID de l'entreprise |
+| corp_secret | string | Oui | Secret de l'application |
+| agent_id | int | Oui | ID de l'agent de l'application |
+| token | string | Oui | Jeton de vérification du callback |
+| encoding_aes_key | string | Oui | Clé AES de 43 caractères |
+| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/wecom-app) |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs |
+| reply_timeout | int | Non | Délai de réponse en secondes |
+
+## Procédure de configuration
+
+1. Connectez-vous à la [console d'administration WeCom](https://work.weixin.qq.com/)
+2. Accédez à « Gestion des applications » -> « Créer une application »
+3. Obtenez l'ID d'entreprise (CorpID) et le Secret de l'application
+4. Configurez « Réception des messages » dans les paramètres de l'application pour obtenir le Token et l'EncodingAESKey
+5. Définissez l'URL de callback sur `http://:/webhook/wecom-app`
+6. Saisissez le CorpID, le Secret, l'AgentID et les autres informations dans le fichier de configuration
+
+ Remarque : PicoClaw utilise désormais un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux. L'adresse d'écoute par défaut est 127.0.0.1:18790. Pour recevoir des callbacks depuis l'internet public, configurez un reverse proxy de votre domaine externe vers le Gateway (port par défaut 18790).
diff --git a/docs/channels/wecom/wecom_app/README.ja.md b/docs/channels/wecom/wecom_app/README.ja.md
new file mode 100644
index 000000000..4bd5a7101
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.ja.md
@@ -0,0 +1,47 @@
+> [README](../../../../README.ja.md) に戻る
+
+# 企業WeChat 自社開発アプリ
+
+企業WeChat 自社開発アプリとは、企業が企業WeChat内で作成するアプリケーションで、主に社内利用を目的としています。企業WeChat 自社開発アプリを通じて、企業は従業員との効率的なコミュニケーションと協業を実現し、業務効率を向上させることができます。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "wecom_app": {
+ "enabled": true,
+ "corp_id": "wwxxxxxxxxxxxxxxxx",
+ "corp_secret": "YOUR_CORP_SECRET",
+ "agent_id": 1000002,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-app",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------------- | ------ | ---- | ---------------------------------------- |
+| corp_id | string | はい | 企業ID |
+| corp_secret | string | はい | アプリケーションシークレット |
+| agent_id | int | はい | アプリケーションエージェントID |
+| token | string | はい | コールバック検証トークン |
+| encoding_aes_key | string | はい | 43文字のAESキー |
+| webhook_path | string | いいえ | Webhookパス（デフォルト：/webhook/wecom-app） |
+| allow_from | array | いいえ | ユーザーIDの許可リスト |
+| reply_timeout | int | いいえ | 返信タイムアウト（秒） |
+
+## セットアップ手順
+
+1. [企業WeChat管理コンソール](https://work.weixin.qq.com/) にログイン
+2. 「アプリ管理」→「アプリを作成」に進む
+3. 企業ID（CorpID）とアプリのSecretを取得
+4. アプリ設定で「メッセージ受信」を設定し、TokenとEncodingAESKeyを取得
+5. コールバックURLを `http://:/webhook/wecom-app` に設定
+6. CorpID、Secret、AgentIDなどの情報を設定ファイルに入力
+
+ 注意：PicoClawは現在、すべてのチャンネルのwebhookコールバックを受信するために共有のGateway HTTPサーバーを使用しています。デフォルトのリスニングアドレスは127.0.0.1:18790です。公共インターネットからコールバックを受信するには、外部ドメインをGateway（デフォルトポート18790）にリバースプロキシしてください。
diff --git a/docs/channels/wecom/wecom_app/README.md b/docs/channels/wecom/wecom_app/README.md
new file mode 100644
index 000000000..4397f805a
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.md
@@ -0,0 +1,47 @@
+> Back to [README](../../../../README.md)
+
+# WeCom Internal App
+
+A WeCom Internal App is an application created by an enterprise within WeCom, primarily intended for internal use. Through WeCom Internal Apps, enterprises can achieve efficient communication and collaboration with employees, improving productivity.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "wecom_app": {
+ "enabled": true,
+ "corp_id": "wwxxxxxxxxxxxxxxxx",
+ "corp_secret": "YOUR_CORP_SECRET",
+ "agent_id": 1000002,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-app",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------------- | ------ | -------- | ---------------------------------------- |
+| corp_id | string | Yes | Enterprise ID |
+| corp_secret | string | Yes | Application secret |
+| agent_id | int | Yes | Application agent ID |
+| token | string | Yes | Callback verification token |
+| encoding_aes_key | string | Yes | 43-character AES key |
+| webhook_path | string | No | Webhook path (default: /webhook/wecom-app) |
+| allow_from | array | No | User ID allowlist |
+| reply_timeout | int | No | Reply timeout in seconds |
+
+## Setup
+
+1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/)
+2. Go to "App Management" -> "Create App"
+3. Obtain the Enterprise ID (CorpID) and App Secret
+4. Configure "Receive Messages" in the app settings to get the Token and EncodingAESKey
+5. Set the callback URL to `http://:/webhook/wecom-app`
+6. Enter the CorpID, Secret, AgentID, and other details into the config file
+
+ Note: PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels. The default listening address is 127.0.0.1:18790. To receive callbacks from the public internet, reverse-proxy your external domain to the Gateway (default port 18790).
diff --git a/docs/channels/wecom/wecom_app/README.pt-br.md b/docs/channels/wecom/wecom_app/README.pt-br.md
new file mode 100644
index 000000000..bd0538ed0
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.pt-br.md
@@ -0,0 +1,47 @@
+> Voltar ao [README](../../../../README.pt-br.md)
+
+# App Interno WeCom
+
+Um App Interno WeCom é um aplicativo criado por uma empresa dentro do WeCom, destinado principalmente ao uso interno. Por meio dos Apps Internos WeCom, as empresas podem alcançar comunicação e colaboração eficientes com os funcionários, melhorando a produtividade.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "wecom_app": {
+ "enabled": true,
+ "corp_id": "wwxxxxxxxxxxxxxxxx",
+ "corp_secret": "YOUR_CORP_SECRET",
+ "agent_id": 1000002,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-app",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------------- | ------ | ----------- | ---------------------------------------- |
+| corp_id | string | Sim | ID da empresa |
+| corp_secret | string | Sim | Segredo da aplicação |
+| agent_id | int | Sim | ID do agente da aplicação |
+| token | string | Sim | Token de verificação de callback |
+| encoding_aes_key | string | Sim | Chave AES de 43 caracteres |
+| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/wecom-app) |
+| allow_from | array | Não | Lista de permissão de IDs de usuários |
+| reply_timeout | int | Não | Timeout de resposta em segundos |
+
+## Configuração passo a passo
+
+1. Faça login no [Console de Administração do WeCom](https://work.weixin.qq.com/)
+2. Acesse "Gerenciamento de Apps" -> "Criar App"
+3. Obtenha o ID da Empresa (CorpID) e o Secret do App
+4. Configure "Receber Mensagens" nas configurações do app para obter o Token e o EncodingAESKey
+5. Defina a URL de callback como `http://:/webhook/wecom-app`
+6. Insira o CorpID, Secret, AgentID e outras informações no arquivo de configuração
+
+ Nota: O PicoClaw agora usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais. O endereço de escuta padrão é 127.0.0.1:18790. Para receber callbacks da internet pública, configure um reverse proxy do seu domínio externo para o Gateway (porta padrão 18790).
diff --git a/docs/channels/wecom/wecom_app/README.vi.md b/docs/channels/wecom/wecom_app/README.vi.md
new file mode 100644
index 000000000..f713f9501
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.vi.md
@@ -0,0 +1,47 @@
+> Quay lại [README](../../../../README.vi.md)
+
+# Ứng dụng nội bộ WeCom
+
+Ứng dụng nội bộ WeCom là ứng dụng được doanh nghiệp tạo ra trong WeCom, chủ yếu dùng cho mục đích nội bộ. Thông qua ứng dụng nội bộ WeCom, doanh nghiệp có thể thực hiện giao tiếp và cộng tác hiệu quả với nhân viên, nâng cao hiệu suất làm việc.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "wecom_app": {
+ "enabled": true,
+ "corp_id": "wwxxxxxxxxxxxxxxxx",
+ "corp_secret": "YOUR_CORP_SECRET",
+ "agent_id": 1000002,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_path": "/webhook/wecom-app",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------------- | ------ | --------- | ---------------------------------------- |
+| corp_id | string | Có | ID doanh nghiệp |
+| corp_secret | string | Có | Secret của ứng dụng |
+| agent_id | int | Có | ID agent của ứng dụng |
+| token | string | Có | Token xác minh callback |
+| encoding_aes_key | string | Có | Khóa AES 43 ký tự |
+| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/wecom-app) |
+| allow_from | array | Không | Danh sách cho phép ID người dùng |
+| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây |
+
+## Hướng dẫn thiết lập
+
+1. Đăng nhập vào [Bảng điều khiển quản trị WeCom](https://work.weixin.qq.com/)
+2. Vào "Quản lý ứng dụng" -> "Tạo ứng dụng"
+3. Lấy ID doanh nghiệp (CorpID) và Secret của ứng dụng
+4. Cấu hình "Nhận tin nhắn" trong cài đặt ứng dụng để lấy Token và EncodingAESKey
+5. Đặt URL callback thành `http://:/webhook/wecom-app`
+6. Nhập CorpID, Secret, AgentID và các thông tin khác vào file cấu hình
+
+ Lưu ý: PicoClaw hiện sử dụng máy chủ HTTP Gateway dùng chung để nhận callback webhook cho tất cả các kênh. Địa chỉ lắng nghe mặc định là 127.0.0.1:18790. Để nhận callback từ internet công cộng, hãy cấu hình reverse proxy từ tên miền bên ngoài của bạn đến Gateway (cổng mặc định 18790).
diff --git a/docs/channels/wecom/wecom_app/README.zh.md b/docs/channels/wecom/wecom_app/README.zh.md
index 0a9858107..81268692d 100644
--- a/docs/channels/wecom/wecom_app/README.zh.md
+++ b/docs/channels/wecom/wecom_app/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../../README.zh.md)
+
# 企业微信自建应用
企业微信自建应用是指企业在企业微信中创建的应用，主要用于企业内部使用。通过企业微信自建应用，企业可以实现与员工的高效沟通和协作，提高工作效率。
diff --git a/docs/channels/wecom/wecom_bot/README.fr.md b/docs/channels/wecom/wecom_bot/README.fr.md
new file mode 100644
index 000000000..fa3caeb37
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.fr.md
@@ -0,0 +1,41 @@
+> Retour au [README](../../../../README.fr.md)
+
+# WeCom Bot
+
+Le WeCom Bot est une méthode d'intégration rapide fournie par WeCom, permettant de recevoir des messages via une URL Webhook.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "wecom": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+ "webhook_path": "/webhook/wecom",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------------- | ------ | ------ | -------------------------------------------- |
+| token | string | Oui | Jeton de vérification de signature |
+| encoding_aes_key | string | Oui | Clé AES de 43 caractères utilisée pour le déchiffrement |
+| webhook_url | string | Oui | URL Webhook du bot de groupe WeCom utilisée pour envoyer les réponses |
+| webhook_path | string | Non | Chemin de l'endpoint webhook (par défaut : /webhook/wecom) |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs (vide = autoriser tous les utilisateurs) |
+| reply_timeout | int | Non | Délai de réponse en secondes (par défaut : 5) |
+
+## Procédure de configuration
+
+1. Ajouter un bot à un groupe WeCom
+2. Obtenir l'URL Webhook
+3. (Pour recevoir des messages) Configurer l'adresse API de réception des messages (URL de callback), le Token et l'EncodingAESKey sur la page de configuration du bot
+4. Saisir les informations pertinentes dans le fichier de configuration
+
+ Remarque : PicoClaw utilise désormais un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux. L'adresse d'écoute par défaut est 127.0.0.1:18790. Pour recevoir des callbacks depuis l'internet public, configurez un reverse proxy de votre domaine externe vers le Gateway (port par défaut 18790).
diff --git a/docs/channels/wecom/wecom_bot/README.ja.md b/docs/channels/wecom/wecom_bot/README.ja.md
new file mode 100644
index 000000000..c932c6b4f
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.ja.md
@@ -0,0 +1,41 @@
+> [README](../../../../README.ja.md) に戻る
+
+# 企業WeChat ボット
+
+企業WeChat ボットは、企業WeChatが提供するWebhook URLを通じてメッセージを受信できる迅速な連携方式です。
+
+## 設定
+
+```json
+{
+ "channels": {
+ "wecom": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+ "webhook_path": "/webhook/wecom",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------------- | ------ | ---- | -------------------------------------------- |
+| token | string | はい | 署名検証トークン |
+| encoding_aes_key | string | はい | 復号化に使用する43文字のAESキー |
+| webhook_url | string | はい | 返信送信に使用する企業WeChatグループボットのWebhook URL |
+| webhook_path | string | いいえ | Webhookエンドポイントパス（デフォルト：/webhook/wecom） |
+| allow_from | array | いいえ | ユーザーIDの許可リスト（空 = 全ユーザーを許可） |
+| reply_timeout | int | いいえ | 返信タイムアウト（秒、デフォルト：5） |
+
+## セットアップ手順
+
+1. 企業WeChatグループにボットを追加
+2. Webhook URLを取得
+3. （メッセージを受信する場合）ボット設定ページでメッセージ受信APIアドレス（コールバックURL）、Token、EncodingAESKeyを設定
+4. 関連情報を設定ファイルに入力
+
+ 注意：PicoClawは現在、すべてのチャンネルのwebhookコールバックを受信するために共有のGateway HTTPサーバーを使用しています。デフォルトのリスニングアドレスは127.0.0.1:18790です。公共インターネットからコールバックを受信するには、外部ドメインをGateway（デフォルトポート18790）にリバースプロキシしてください。
diff --git a/docs/channels/wecom/wecom_bot/README.md b/docs/channels/wecom/wecom_bot/README.md
new file mode 100644
index 000000000..2600a6a6b
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.md
@@ -0,0 +1,41 @@
+> Back to [README](../../../../README.md)
+
+# WeCom Bot
+
+WeCom Bot is a quick integration method provided by WeCom that can receive messages via a Webhook URL.
+
+## Configuration
+
+```json
+{
+ "channels": {
+ "wecom": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+ "webhook_path": "/webhook/wecom",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------------- | ------ | -------- | -------------------------------------------- |
+| token | string | Yes | Signature verification token |
+| encoding_aes_key | string | Yes | 43-character AES key used for decryption |
+| webhook_url | string | Yes | WeCom group bot webhook URL used to send replies |
+| webhook_path | string | No | Webhook endpoint path (default: /webhook/wecom) |
+| allow_from | array | No | User ID allowlist (empty = allow all users) |
+| reply_timeout | int | No | Reply timeout in seconds (default: 5) |
+
+## Setup
+
+1. Add a bot to a WeCom group
+2. Obtain the Webhook URL
+3. (To receive messages) Configure the message receiving API address (callback URL), Token, and EncodingAESKey on the bot configuration page
+4. Enter the relevant information into the config file
+
+ Note: PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels. The default listening address is 127.0.0.1:18790. To receive callbacks from the public internet, reverse-proxy your external domain to the Gateway (default port 18790).
diff --git a/docs/channels/wecom/wecom_bot/README.pt-br.md b/docs/channels/wecom/wecom_bot/README.pt-br.md
new file mode 100644
index 000000000..4b3af1404
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.pt-br.md
@@ -0,0 +1,41 @@
+> Voltar ao [README](../../../../README.pt-br.md)
+
+# WeCom Bot
+
+O WeCom Bot é um método de integração rápida fornecido pelo WeCom que pode receber mensagens via URL de Webhook.
+
+## Configuração
+
+```json
+{
+ "channels": {
+ "wecom": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+ "webhook_path": "/webhook/wecom",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------------- | ------ | ----------- | -------------------------------------------- |
+| token | string | Sim | Token de verificação de assinatura |
+| encoding_aes_key | string | Sim | Chave AES de 43 caracteres usada para descriptografia |
+| webhook_url | string | Sim | URL do webhook do bot de grupo WeCom usada para enviar respostas |
+| webhook_path | string | Não | Caminho do endpoint webhook (padrão: /webhook/wecom) |
+| allow_from | array | Não | Lista de permissão de IDs de usuários (vazio = permitir todos) |
+| reply_timeout | int | Não | Timeout de resposta em segundos (padrão: 5) |
+
+## Configuração passo a passo
+
+1. Adicione um bot a um grupo WeCom
+2. Obtenha a URL do Webhook
+3. (Para receber mensagens) Configure o endereço da API de recebimento de mensagens (URL de callback), Token e EncodingAESKey na página de configuração do bot
+4. Insira as informações relevantes no arquivo de configuração
+
+ Nota: O PicoClaw agora usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais. O endereço de escuta padrão é 127.0.0.1:18790. Para receber callbacks da internet pública, configure um reverse proxy do seu domínio externo para o Gateway (porta padrão 18790).
diff --git a/docs/channels/wecom/wecom_bot/README.vi.md b/docs/channels/wecom/wecom_bot/README.vi.md
new file mode 100644
index 000000000..aab4b46cd
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.vi.md
@@ -0,0 +1,41 @@
+> Quay lại [README](../../../../README.vi.md)
+
+# WeCom Bot
+
+WeCom Bot là phương thức tích hợp nhanh do WeCom cung cấp, có thể nhận tin nhắn qua URL Webhook.
+
+## Cấu hình
+
+```json
+{
+ "channels": {
+ "wecom": {
+ "enabled": true,
+ "token": "YOUR_TOKEN",
+ "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+ "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+ "webhook_path": "/webhook/wecom",
+ "allow_from": [],
+ "reply_timeout": 5
+ }
+ }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------------- | ------ | --------- | -------------------------------------------- |
+| token | string | Có | Token xác minh chữ ký |
+| encoding_aes_key | string | Có | Khóa AES 43 ký tự dùng để giải mã |
+| webhook_url | string | Có | URL webhook của bot nhóm WeCom dùng để gửi phản hồi |
+| webhook_path | string | Không | Đường dẫn endpoint webhook (mặc định: /webhook/wecom) |
+| allow_from | array | Không | Danh sách cho phép ID người dùng (rỗng = cho phép tất cả) |
+| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây (mặc định: 5) |
+
+## Hướng dẫn thiết lập
+
+1. Thêm bot vào một nhóm WeCom
+2. Lấy URL Webhook
+3. (Để nhận tin nhắn) Cấu hình địa chỉ API nhận tin nhắn (URL callback), Token và EncodingAESKey trên trang cấu hình bot
+4. Nhập thông tin liên quan vào file cấu hình
+
+ Lưu ý: PicoClaw hiện sử dụng máy chủ HTTP Gateway dùng chung để nhận callback webhook cho tất cả các kênh. Địa chỉ lắng nghe mặc định là 127.0.0.1:18790. Để nhận callback từ internet công cộng, hãy cấu hình reverse proxy từ tên miền bên ngoài của bạn đến Gateway (cổng mặc định 18790).
diff --git a/docs/channels/wecom/wecom_bot/README.zh.md b/docs/channels/wecom/wecom_bot/README.zh.md
index 63d9b84d6..016fcf973 100644
--- a/docs/channels/wecom/wecom_bot/README.zh.md
+++ b/docs/channels/wecom/wecom_bot/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../../README.zh.md)
+
# 企业微信机器人
企业微信机器人是企业微信提供的一种快速接入方式，可以通过 Webhook URL 接收消息。
diff --git a/docs/channels/weixin/README.md b/docs/channels/weixin/README.md
new file mode 100644
index 000000000..22687fec4
--- /dev/null
+++ b/docs/channels/weixin/README.md
@@ -0,0 +1,58 @@
+# 💬 Weixin (WeChat Personal) Channel
+
+PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API.
+
+## 🚀 Quick Onboarding
+
+The easiest way to set up the Weixin channel is using the interactive onboarding command:
+
+```bash
+picoclaw onboard weixin
+```
+
+This command will:
+1. Request a QR code from the iLink API and display it in your terminal.
+2. Wait for you to scan the QR code with your WeChat mobile app.
+3. Upon approval, automatically save the generated access token to your `~/.picoclaw/config.json`.
+
+After onboarding, you can start the gateway:
+
+```bash
+picoclaw gateway
+```
+
+---
+
+## ⚙️ Configuration
+
+You can also manually configure the filter rules in `config.json` under the `channels.weixin` section.
+
+```json
+{
+ "channels": {
+ "weixin": {
+ "enabled": true,
+ "token": "YOUR_WEIXIN_TOKEN",
+ "allow_from": [
+ "user_id_1",
+ "user_id_2"
+ ],
+ "proxy": ""
+ }
+ }
+}
+```
+
+### Configuration Fields
+
+| Field | Description |
+|---|---|
+| `enabled` | Set to `true` to enable the channel at startup. |
+| `token` | The authentication token obtained via QR login. |
+| `allow_from` | (Optional) List of WeChat User IDs permitted to interact with the bot. If empty, anyone who can send messages to the connected account can trigger the bot. |
+| `proxy` | (Optional) HTTP proxy address (e.g. `http://localhost:7890`) for environments where connection to `ilinkai.weixin.qq.com` is restricted. |
+
+## ⚠️ Important Notes
+
+- **One Account Only**: The iLink token binds to a single session. Starting a new interaction generally invalidates older tokens if another device authorizes.
+- **Message Rate Limits**: To avoid getting your account restricted by WeChat anti-spam systems, avoid loop triggers or high-frequency broadcasts.
diff --git a/docs/channels/weixin/README.zh.md b/docs/channels/weixin/README.zh.md
new file mode 100644
index 000000000..d5e6f0a49
--- /dev/null
+++ b/docs/channels/weixin/README.zh.md
@@ -0,0 +1,58 @@
+# 💬 微信个人号渠道 (Weixin)
+
+PicoClaw 支持使用腾讯官方 iLink API 连接您的个人微信账号。
+
+## 🚀 快速激活
+
+最简单的方法是使用交互式 onboarding 命令进行一键激活：
+
+```bash
+picoclaw onboard weixin
+```
+
+该命令将：
+1. 从 iLink API 获取二维码并在终端中打印。
+2. 等待您使用手机微信 App 扫码。
+3. 扫码确认后，自动将生成的 Access Token 保存至您的 `~/.picoclaw/config.json` 中。
+
+配置完成后，即可启动网关：
+
+```bash
+picoclaw gateway
+```
+
+---
+
+## ⚙️ 配置说明
+
+您也可以在 `config.json` 的 `channels.weixin` 段目下进行手动维护。
+
+```json
+{
+ "channels": {
+ "weixin": {
+ "enabled": true,
+ "token": "YOUR_WEIXIN_TOKEN",
+ "allow_from": [
+ "user_id_1",
+ "user_id_2"
+ ],
+ "proxy": ""
+ }
+ }
+}
+```
+
+### 字段解析
+
+| 字段 | 说明 |
+|---|---|
+| `enabled` | 设置为 `true` 以在启动时激活该频道。 |
+| `token` | 通过扫码获取的认证令牌。 |
+| `allow_from` | (可选) 允许与机器人交互的微信 User ID 列表。如果为空，任何能给此微信号发消息的人都可以触发机器人。 |
+| `proxy` | (可选) HTTP 代理地址（例如 `http://localhost:7890`），适合网络访问受限环境。 |
+
+## ⚠️ 注意事项
+
+- **单端绑定**: iLink 令牌通常与单个会话绑定。在其他地方重新扫码激活可能会导致旧令牌失效。
+- **频率控制**: 为避免触发微信的风控反垃圾机制，请避免设置死循环触发、高频广播等恶意行为。
diff --git a/docs/chat-apps.md b/docs/chat-apps.md
index 05afc7f33..d300f5544 100644
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@@ -8,23 +8,25 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,
> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.
-| Channel | Setup |
-| ------------ | ---------------------------------- |
-| **Telegram** | Easy (just a token) |
-| **Discord** | Easy (bot token + intents) |
-| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
-| **Matrix** | Medium (homeserver + bot access token) |
-| **QQ** | Easy (AppID + AppSecret) |
-| **DingTalk** | Medium (app credentials) |
-| **LINE** | Medium (credentials + webhook URL) |
-| **WeCom AI Bot** | Medium (Token + AES key) |
-| **Feishu** | Medium (App ID + Secret, WebSocket mode) |
-| **Slack** | Medium (Bot token + App token) |
-| **IRC** | Medium (server + TLS config) |
-| **OneBot** | Medium (QQ via OneBot protocol) |
-| **MaixCam** | Easy (Sipeed hardware integration) |
-| **Pico** | Native PicoClaw protocol |
+| Channel | Difficulty | Description | Documentation |
+| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Telegram** | ⭐ Easy | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](channels/telegram/README.md) |
+| **Discord** | ⭐ Easy | Socket Mode, group/DM support, rich bot ecosystem | [Docs](channels/discord/README.md) |
+| **WhatsApp** | ⭐ Easy | Native (QR scan) or Bridge URL | [Docs](#whatsapp) |
+| **Weixin** | ⭐ Easy | Native QR scan (Tencent iLink API) | [Docs](#weixin) |
+| **Slack** | ⭐ Easy | **Socket Mode** (no public IP needed), enterprise | [Docs](channels/slack/README.md) |
+| **Matrix** | ⭐⭐ Medium | Federated protocol, self-hosting supported | [Docs](channels/matrix/README.md) |
+| **QQ** | ⭐⭐ Medium | Official bot API, Chinese community | [Docs](channels/qq/README.md) |
+| **DingTalk** | ⭐⭐ Medium | Stream mode (no public IP needed), enterprise | [Docs](channels/dingtalk/README.md) |
+| **LINE** | ⭐⭐⭐ Advanced | HTTPS Webhook required | [Docs](channels/line/README.md) |
+| **WeCom (企业微信)** | ⭐⭐⭐ Advanced | Group Bot (Webhook), custom App (API), AI Bot | [Bot](channels/wecom/wecom_bot/README.md) / [App](channels/wecom/wecom_app/README.md) / [AI Bot](channels/wecom/wecom_aibot/README.md) |
+| **Feishu (飞书)** | ⭐⭐⭐ Advanced | Enterprise collaboration, feature-rich | [Docs](channels/feishu/README.md) |
+| **IRC** | ⭐⭐ Medium | Server + TLS configuration | [Docs](#irc) |
+| **OneBot** | ⭐⭐ Medium | NapCat/Go-CQHTTP compatible, community ecosystem | [Docs](channels/onebot/README.md) |
+| **MaixCam** | ⭐ Easy | Hardware integration channel for Sipeed AI cameras | [Docs](channels/maixcam/README.md) |
+| **Pico** | ⭐ Easy | Native PicoClaw protocol channel | |
+
Telegram (Recommended) `
+- `/use ` and then send the actual request in the next message
+- `/use clear`
+
**4. Advanced Formatting**
You can set use_markdown_v2: true to enable enhanced formatting options. This allows the bot to utilize the full range of Telegram MarkdownV2 features, including nested styles, spoilers, and custom fixed-width blocks.
+
Discord
+
WhatsApp (native via whatsmeow)/whatsapp
+
+Weixin (WeChat Personal)
+
+
QQ /whatsapp
}
```
-> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
+4. Run `picoclaw gateway` and open QQ to chat with your bot
-**3. Run**
+> The App Secret is only shown once. Save it immediately — viewing it again will force a reset.
+>
+> Bots created via the quick setup page are initially for the creator only and do not support group chats. To enable group access, configure sandbox mode on the [QQ Open Platform](https://q.qq.com/).
-```bash
-picoclaw gateway
-```
+**Manual setup**
+
+If you prefer to create the bot manually:
+
+* Log in at [QQ Open Platform](https://q.qq.com/) to register as a developer
+* Create a QQ bot — customize its avatar and name
+* Copy the **App ID** and **App Secret** from the bot settings
+* Configure as shown above and run `picoclaw gateway`
+
DingTalk
+
Matrix
+
LINE
+
WeCom (企业微信)
+
+
+Feishu (Lark)
+
+
+Slack
+
+
+IRC
+
+
+OneBot (QQ via OneBot protocol)
diff --git a/docs/config-versioning.md b/docs/config-versioning.md
new file mode 100644
index 000000000..36d7fdd25
--- /dev/null
+++ b/docs/config-versioning.md
@@ -0,0 +1,230 @@
+# Config Schema Versioning Guide
+
+## Overview
+
+PicoClaw uses a schema versioning system for `config.json` to ensure smooth upgrades as the configuration format evolves.
+
+## Version History
+
+### Version 1
+- **Introduction**: Initial version with version field support
+- **Changes**: Added `version` field to Config struct
+- **Migration**: No structural changes needed for existing configs
+
+## How It Works
+
+### Automatic Migration
+When you load a config file:
+1. The system first reads the `version` field from the JSON
+2. Based on the detected version, it loads the appropriate config struct (`ConfigV0`, `ConfigV1`, etc.)
+3. If the loaded version is less than the latest, migrations are applied incrementally
+4. The version number is updated automatically
+5. The migrated config is automatically saved back to disk
+
+### Version Field
+The `version` field in `config.json` indicates the schema version:
+- `0` or missing: Legacy config (no version field)
+- `1`: Current version with versioning support
+
+```json
+{
+ "version": 1,
+ "agents": {...},
+ ...
+}
+```
+
+## Adding a New Migration
+
+When making breaking changes to the config schema:
+
+### Step 1: Define the New Version Struct
+
+Create a new struct for the new version if the structure changes significantly:
+
+```go
+// ConfigV2 represents version 2 config structure
+type ConfigV2 struct {
+ Version int `json:"version"`
+ Agents AgentsConfig `json:"agents"`
+ // ... other fields with new structure
+}
+```
+
+### Step 2: Update Current Config Version
+
+```go
+const CurrentConfigVersion = 2 // Increment this
+```
+
+### Step 3: Add a Loader Function
+
+```go
+// loadConfigV2 loads a version 2 config
+func loadConfigV2(data []byte) (*Config, error) {
+ cfg := DefaultConfig()
+
+ // Parse to ConfigV2 struct
+ var v2 ConfigV2
+ if err := json.Unmarshal(data, &v2); err != nil {
+ return nil, err
+ }
+
+ // Convert to current Config
+ cfg.Version = v2.Version
+ cfg.Agents = v2.Agents
+ // ... map other fields
+
+ return cfg, nil
+}
+```
+
+### Step 4: Add Migration Logic
+
+```go
+// applyMigration applies a single migration step from fromVersion to toVersion
+func applyMigration(cfg *Config, fromVersion, toVersion int) (*Config, error) {
+ switch toVersion {
+ case 1:
+ // Migration from version 0 to 1
+ return &Config{
+ Version: 1,
+ Agents: cfg.Agents,
+ // ... copy all fields
+ }, nil
+ case 2:
+ // Migration from version 1 to 2
+ // Example: Move or rename fields
+ migrated := *cfg
+ migrated.Version = 2
+ // Apply structural changes
+ if cfg.SomeOldField != "" {
+ migrated.SomeNewField = cfg.SomeOldField
+ }
+ return &migrated, nil
+ default:
+ return nil, fmt.Errorf("unsupported migration target version: %d", toVersion)
+ }
+}
+```
+
+### Step 5: Update LoadConfig Switch
+
+```go
+func LoadConfig(path string) (*Config, error) {
+ // ... read file ...
+
+ switch versionInfo.Version {
+ case 0:
+ cfg, err = loadConfigV0(data)
+ case 1:
+ cfg, err = loadConfigV1(data)
+ case 2:
+ cfg, err = loadConfigV2(data)
+ default:
+ return nil, fmt.Errorf("unsupported config version: %d", versionInfo.Version)
+ }
+
+ // ... migrate and validate ...
+}
+```
+
+### Step 6: Test Your Migration
+
+Create a test in `config_migration_test.go`:
+
+```go
+func TestMigrateV1ToV2(t *testing.T) {
+ // Create a version 1 config
+ v1Config := Config{
+ Version: 1,
+ // ... set up test data
+ }
+
+ // Apply migration
+ migrated, err := applyMigration(&v1Config, 1, 2)
+ if err != nil {
+ t.Fatalf("Migration failed: %v", err)
+ }
+
+ // Verify version is updated
+ if migrated.Version != 2 {
+ t.Errorf("Expected version 2, got %d", migrated.Version)
+ }
+
+ // Verify data is preserved/transformed correctly
+ // ...
+}
+```
+
+## Migration Best Practices
+
+1. **Version-Specific Structs**: Define a separate struct for each version that has structural changes
+2. **Backward Compatibility**: Ensure old configs can still be loaded with their specific structs
+3. **No Data Loss**: Migrations should preserve all user settings
+4. **Idempotent**: Running the same migration multiple times should be safe
+5. **Auto-Save**: Migrated configs are automatically saved to update the user's file
+6. **Test Thoroughly**: Test with real user config files
+7. **Update Defaults**: Keep `defaults.go` in sync with the latest schema
+
+## Example Migration
+
+### Scenario: Adding a new field with default value
+
+Old config (version 1):
+```json
+{
+ "version": 1,
+ "agents": {
+ "defaults": {
+ "max_tokens": 32768
+ }
+ }
+}
+```
+
+Migration to version 2:
+```go
+case 2:
+ migrated := *cfg
+ migrated.Version = 2
+
+ // Add new field with default value if not set
+ if migrated.Agents.Defaults.NewFeatureEnabled == false {
+ // Use default value
+ }
+
+ return &migrated, nil
+```
+
+New config (version 2):
+```json
+{
+ "version": 2,
+ "agents": {
+ "defaults": {
+ "max_tokens": 32768,
+ "new_feature_enabled": false
+ }
+ }
+}
+```
+
+## Troubleshooting
+
+### Config Not Upgrading
+- Check that `CurrentConfigVersion` is incremented
+- Verify migration logic in `applyMigration()` handles the target version
+- Ensure `migrateConfig()` is called in `LoadConfig()`
+
+### Migration Errors
+- Check error messages for specific migration failures
+- Review migration logic for edge cases
+- Ensure all required fields are properly initialized
+- Verify the loader function for the source version
+
+### Data Loss After Migration
+- Ensure all fields are copied during migration
+- Check that the migration doesn't overwrite values with defaults unnecessarily
+- Review the conversion logic in the loader functions
+
diff --git a/docs/configuration.md b/docs/configuration.md
index 202ad4f59..f15a14c9a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -57,7 +57,7 @@ By default, skills are loaded from:
1. `~/.picoclaw/workspace/skills` (workspace)
2. `~/.picoclaw/skills` (global)
-3. `/skills` (builtin)
+3. `/skills` (builtin, set at build time)
For advanced/test setups, you can override the builtin skills root with:
@@ -65,12 +65,159 @@ For advanced/test setups, you can override the builtin skills root with:
export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
```
+### Using Skills From Chat Channels
+
+Once skills are installed, you can inspect and force them directly from a chat channel:
+
+- `/list skills` shows the installed skill names available to the current agent.
+- `/use ` forces a specific skill for a single request.
+- `/use ` arms that skill for your next message in the same chat session.
+- `/use clear` cancels a pending skill override created by `/use `.
+
+Examples:
+
+```text
+/list skills
+/use git explain how to squash the last 3 commits
+/use italiapersonalfinance
+dammi le ultime news
+```
+
### Unified Command Execution Policy
- Generic slash commands are executed through a single path in `pkg/agent/loop.go` via `commands.Executor`.
- Channel adapters no longer consume generic commands locally; they forward inbound text to the bus/agent path. Telegram still auto-registers supported commands at startup.
- Unknown slash command (for example `/foo`) passes through to normal LLM processing.
- Registered but unsupported command on the current channel (for example `/show` on WhatsApp) returns an explicit user-facing error and stops further processing.
+
+### Agent Bindings (Route messages to specific agents)
+
+Use `bindings` in `config.json` to route incoming messages to different agents by channel/account/context.
+
+```json
+{
+ "agents": {
+ "defaults": {
+ "workspace": "~/.picoclaw/workspace",
+ "model_name": "gpt-4o-mini"
+ },
+ "list": [
+ { "id": "main", "default": true, "name": "Main Assistant" },
+ { "id": "support", "name": "Support Assistant" },
+ { "id": "sales", "name": "Sales Assistant" }
+ ]
+ },
+ "bindings": [
+ {
+ "agent_id": "support",
+ "match": {
+ "channel": "telegram",
+ "account_id": "*",
+ "peer": { "kind": "direct", "id": "user123" }
+ }
+ },
+ {
+ "agent_id": "sales",
+ "match": {
+ "channel": "discord",
+ "account_id": "my-discord-bot",
+ "guild_id": "987654321"
+ }
+ }
+ ]
+}
+```
+
+#### `bindings` fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `agent_id` | Yes | Target agent id in `agents.list` |
+| `match.channel` | Yes | Channel name (e.g. `telegram`, `discord`) |
+| `match.account_id` | No | Channel account filter. Use `"*"` for all accounts of that channel. If omitted, only default account is matched |
+| `match.peer.kind` + `match.peer.id` | No | Exact peer match (e.g. direct chat / topic / group id) |
+| `match.guild_id` | No | Guild/server-level match |
+| `match.team_id` | No | Team/workspace-level match |
+
+#### Matching priority
+
+When multiple bindings exist, PicoClaw resolves in this order:
+
+1. `peer`
+2. `parent_peer` (for thread/topic parent contexts)
+3. `guild_id`
+4. `team_id`
+5. `account_id` (non-wildcard)
+6. channel wildcard (`account_id: "*"`)
+7. default agent
+
+If a binding points to a missing `agent_id`, PicoClaw falls back to the default agent.
+
+#### How matching works (step-by-step)
+
+1. PicoClaw first filters bindings by `match.channel` (must equal current channel).
+2. It then filters by `match.account_id`:
+ - omitted: match only the channel's default account
+ - `"*"`: match all accounts on this channel
+ - explicit value: exact account id match (case-insensitive)
+3. From the remaining candidates, it applies the priority chain above and stops at the first hit.
+
+In other words: **channel + account form the candidate set; peer/guild/team then decide final winner**.
+
+#### Common recipes
+
+**1) Route one specific DM user to a specialist agent**
+
+```json
+{
+ "agent_id": "support",
+ "match": {
+ "channel": "telegram",
+ "account_id": "*",
+ "peer": { "kind": "direct", "id": "user123" }
+ }
+}
+```
+
+**2) Route one Discord server (guild) to a dedicated agent**
+
+```json
+{
+ "agent_id": "sales",
+ "match": {
+ "channel": "discord",
+ "account_id": "my-discord-bot",
+ "guild_id": "987654321"
+ }
+}
+```
+
+**3) Route all remaining traffic of a channel to a fallback agent**
+
+```json
+{
+ "agent_id": "main",
+ "match": {
+ "channel": "discord",
+ "account_id": "*"
+ }
+}
+```
+
+#### Authoring guidelines (important)
+
+- Keep exactly one clear default agent in `agents.list` (`"default": true`).
+- Put specific rules (`peer`, `guild_id`, `team_id`) and broad rules (`account_id: "*"` only) together safely; priority already guarantees specific rules win.
+- Avoid duplicate rules with the same specificity and match values. If duplicates exist, the first matching entry in the config array wins.
+- Ensure every `agent_id` exists in `agents.list`; unknown IDs silently fall back to default.
+
+#### Troubleshooting checklist
+
+- **Rule not taking effect?** Check `match.channel` spelling first (must be exact).
+- **Expected account-specific routing but still using default?** Verify `match.account_id` equals actual runtime account id.
+- **Wildcard catches too much traffic?** Add more specific `peer/guild/team` rules for critical paths.
+- **Unexpected default fallback?** Confirm `agent_id` exists and is not misspelled.
+
### 🔒 Security Sandbox
PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.
@@ -218,3 +365,396 @@ For long-running tasks (web search, API calls), use the `spawn` tool to create a
```markdown
# Periodic Tasks
+
+## Quick Tasks (respond directly)
+
+- Report current time
+
+## Long Tasks (use spawn for async)
+
+- Search the web for AI news and summarize
+- Check email and report important messages
+```
+
+**Key behaviors:**
+
+| Feature | Description |
+| ----------------------- | --------------------------------------------------------- |
+| **spawn** | Creates async subagent, doesn't block heartbeat |
+| **Independent context** | Subagent has its own context, no session history |
+| **message tool** | Subagent communicates with user directly via message tool |
+| **Non-blocking** | After spawning, heartbeat continues to next task |
+
+#### How Subagent Communication Works
+
+```
+Heartbeat triggers
+ ↓
+Agent reads HEARTBEAT.md
+ ↓
+For long task: spawn subagent
+ ↓ ↓
+Continue to next task Subagent works independently
+ ↓ ↓
+All tasks done Subagent uses "message" tool
+ ↓ ↓
+Respond HEARTBEAT_OK User receives result directly
+```
+
+The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent.
+
+**Configuration:**
+
+```json
+{
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ }
+}
+```
+
+| Option | Default | Description |
+| ---------- | ------- | ---------------------------------- |
+| `enabled` | `true` | Enable/disable heartbeat |
+| `interval` | `30` | Check interval in minutes (min: 5) |
+
+**Environment variables:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval
+
+### Providers
+
+> [!NOTE]
+> Groq provides free voice transcription via Whisper. If configured, audio messages from any channel will be automatically transcribed at the agent level.
+
+| Provider | Purpose | Get API Key |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) |
+| `volcengine` | LLM (Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |
+| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |
+| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |
+| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |
+| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) |
+| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) |
+| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) |
+
+### Model Configuration (model_list)
+
+> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers — **zero code changes required!**
+
+This design also enables **multi-agent support** with flexible provider selection:
+
+- **Different agents, different providers**: Each agent can use its own LLM provider
+- **Model fallbacks**: Configure primary and fallback models for resilience
+- **Load balancing**: Distribute requests across multiple endpoints
+- **Centralized configuration**: Manage all providers in one place
+
+#### All Supported Vendors
+
+| Vendor | `model` Prefix | Default API Base | Protocol | API Key |
+| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) |
+| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) |
+| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) |
+| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) |
+| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) |
+| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) |
+| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) |
+| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) |
+| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) |
+| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) |
+| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key |
+| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |
+| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) |
+| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | — |
+| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) |
+| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) |
+| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) |
+| **ModelScope (魔搭)** | `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) |
+| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only |
+| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | — |
+
+#### Basic Configuration
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "ark-code-latest",
+ "model": "volcengine/ark-code-latest",
+ "api_key": "sk-your-api-key"
+ },
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_key": "sk-your-openai-key"
+ },
+ {
+ "model_name": "claude-sonnet-4.6",
+ "model": "anthropic/claude-sonnet-4.6",
+ "api_key": "sk-ant-your-key"
+ },
+ {
+ "model_name": "glm-4.7",
+ "model": "zhipu/glm-4.7",
+ "api_key": "your-zhipu-key"
+ }
+ ],
+ "agents": {
+ "defaults": {
+ "model": "gpt-5.4"
+ }
+ }
+}
+```
+
+#### Vendor-Specific Examples
+
+
+OpenAI
+
+
+VolcEngine (Doubao)
+
+
+智谱 AI (GLM)
+
+
+DeepSeek
+
+
+Anthropic
+
+
+Ollama (local)
+
+
+Custom Proxy / LiteLLM
+
+#### Load Balancing
+
+Configure multiple endpoints for the same model name — PicoClaw will automatically round-robin between them:
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_base": "https://api1.example.com/v1",
+ "api_key": "sk-key1"
+ },
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_base": "https://api2.example.com/v1",
+ "api_key": "sk-key2"
+ }
+ ]
+}
+```
+
+#### Migration from Legacy `providers` Config
+
+The old `providers` configuration is **deprecated** but still supported for backward compatibility. See [docs/migration/model-list-migration.md](../migration/model-list-migration.md) for the full guide.
+
+### Provider Architecture
+
+PicoClaw routes providers by protocol family:
+
+- **OpenAI-compatible**: OpenRouter, Groq, Zhipu, vLLM-style endpoints, and most others.
+- **Anthropic**: Claude-native API behavior.
+- **Codex/OAuth**: OpenAI OAuth/token authentication route.
+
+This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
+
+
+Zhipu (legacy providers format)
+
+
+Full config example
+
+### Scheduled Tasks / Reminders
+
+PicoClaw supports cron-style scheduled tasks via the `cron` tool. The agent can set, list, and cancel reminders or recurring jobs that trigger at specified times.
+
+```json
+{
+ "tools": {
+ "cron": {
+ "enabled": true,
+ "exec_timeout_minutes": 5
+ }
+ }
+}
+```
+
+Scheduled tasks persist across restarts and are stored in `~/.picoclaw/workspace/cron/`.
+
+### Advanced Topics
+
+| Topic | Description |
+| ----- | ----------- |
+| [Hook System](hooks/README.md) | Event-driven hooks: observers, interceptors, approval hooks |
+| [Steering](steering.md) | Inject messages into a running agent loop between tool calls |
+| [SubTurn](subturn.md) | Subagent coordination, concurrency control, lifecycle |
+| [Context Management](agent-refactor/context.md) | Context boundary detection, proactive budget check, compression |
diff --git a/docs/credential_encryption.md b/docs/credential_encryption.md
index 448eaaa10..dde8c782c 100644
--- a/docs/credential_encryption.md
+++ b/docs/credential_encryption.md
@@ -30,8 +30,9 @@ enc://AAAA...base64...
"model_list": [
{
"model_name": "gpt-4o",
+ "model": "openai/gpt-4o",
"api_key": "enc://AAAA...base64...",
- "base_url": "https://api.openai.com/v1"
+ "api_base": "https://api.openai.com/v1"
}
]
}
@@ -54,20 +55,12 @@ enc://AAAA...base64...
### Key Derivation
-Encryption uses **HKDF-SHA256** with an optional SSH private key as a second factor.
+Encryption uses **HKDF-SHA256** with an SSH private key as a second factor.
```
-Without SSH key (passphrase only):
-
- ikm = SHA256(passphrase)
- aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
-
-
-With SSH key (recommended):
-
- sshHash = SHA256(ssh_private_key_file_bytes)
- ikm = HMAC-SHA256(key=sshHash, message=passphrase)
- aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
```
### Encryption
@@ -125,7 +118,7 @@ This means a leaked config file alone is not sufficient to recover the API key,
| Variable | Required | Description |
|----------|----------|-------------|
| `PICOCLAW_KEY_PASSPHRASE` | Yes (for `enc://`) | Passphrase used for key derivation |
-| `PICOCLAW_SSH_KEY_PATH` | No | Path to SSH private key. Set to `""` to disable auto-detection and use passphrase-only mode |
+| `PICOCLAW_SSH_KEY_PATH` | No | Path to SSH private key. If not set, auto-detects from `~/.ssh/picoclaw_ed25519.key` |
### SSH Key Auto-Detection
@@ -140,11 +133,7 @@ Run `picoclaw onboard` to generate it automatically.
`os.UserHomeDir()` is used for cross-platform home directory resolution (reads `USERPROFILE` on Windows, `HOME` on Unix/macOS).
-To explicitly disable SSH key usage and use passphrase-only mode:
-
-```bash
-export PICOCLAW_SSH_KEY_PATH=""
-```
+> **Note:** An SSH key file is required for credential encryption. If no key is found and `PICOCLAW_SSH_KEY_PATH` is not set, encryption/decryption will fail. Run `picoclaw onboard` to generate the key automatically.
---
@@ -162,7 +151,7 @@ No re-encryption is needed.
## Security Considerations
-- **Passphrase strength matters in passphrase-only mode.** Without an SSH key, a weak passphrase can be brute-forced offline. Use `PICOCLAW_SSH_KEY_PATH=""` only in environments where no SSH key is available and the passphrase is sufficiently strong (≥ 32 random characters).
+- **Both passphrase and SSH key are required.** The SSH key acts as a second factor — without it, encryption/decryption will fail. Run `picoclaw onboard` to generate the key if it doesn't exist.
- **The SSH key is read-only at runtime.** PicoClaw never writes to or modifies the SSH key file.
- **Plaintext keys remain supported.** Existing configs without `enc://` are unaffected.
- **The `enc://` format is versioned** via the HKDF `info` field (`picoclaw-credential-v1`), allowing future algorithm upgrades without breaking existing encrypted values.
diff --git a/docs/design/hook-system-design.zh.md b/docs/design/hook-system-design.zh.md
new file mode 100644
index 000000000..ab5566bec
--- /dev/null
+++ b/docs/design/hook-system-design.zh.md
@@ -0,0 +1,476 @@
+# PicoClaw Hook 系统设计（基于 `refactor/agent`）
+
+## 背景
+
+本设计围绕两个议题展开：
+
+- `#1316`：把 agent loop 重构为事件驱动、可中断、可追加、可观测
+- `#1796`：在 EventBus 稳定后，把 hooks 设计为 EventBus 的 consumer，而不是重新发明一套事件模型
+
+当前分支已经完成了第一步里的“事件系统基础”，但还没有真正的 hook 挂载层。因此这里的目标不是重新设计 event，而是在已有实现上补出一层可扩展、可拦截、可外挂的 HookManager。
+
+## 外部项目对比
+
+### OpenClaw
+
+OpenClaw 的扩展能力分成三层：
+
+- Internal hooks：目录发现，运行在 Gateway 进程内
+- Plugin hooks：插件在运行时注册 hook，也在进程内
+- Webhooks：外部系统通过 HTTP 触发 Gateway 动作，属于进程外
+
+值得借鉴的点：
+
+- 有“项目内挂载”和“项目外挂载”两种路径
+- hook 是配置驱动，可启停
+- 外部入口有明确的安全边界和映射层
+
+不建议直接照搬的点：
+
+- OpenClaw 的 hooks / plugin hooks / webhooks 是三套路由，PicoClaw 当前体量下会偏重
+- HTTP webhook 更适合“事件进入系统”，不适合作为“可同步拦截 agent loop”的基础机制
+
+### pi-mono
+
+pi-mono 的核心思路更接近当前分支：
+
+- 扩展统一为 extension API
+- 事件分为观察型和可变更型
+- 某些阶段允许 `transform` / `block` / `replace`
+- 扩展代码主要是进程内执行
+- RPC mode 把 UI 交互桥接到进程外客户端
+
+值得借鉴的点：
+
+- 不把“观察”和“拦截”混成一个接口
+- 允许返回结构化动作，而不是只有回调
+- 进程外通信只暴露必要协议，不把整个内部对象图泄露出去
+
+## 当前分支现状
+
+### 已有能力
+
+当前分支已经具备 hook 系统的地基：
+
+- `pkg/agent/events.go` 定义了稳定的 `EventKind`、`EventMeta` 和 payload
+- `pkg/agent/eventbus.go` 提供了非阻塞 fan-out 的 `EventBus`
+- `pkg/agent/loop.go` 中的 `runTurn()` 已在 turn、llm、tool、interrupt、follow-up、summary 等节点发射事件
+- `pkg/agent/steering.go` 已支持 steering、graceful interrupt、hard abort
+- `pkg/agent/turn.go` 已维护 turn phase、恢复点、active turn、abort 状态
+
+### 现有缺口
+
+当前分支还缺四件事：
+
+- 没有 HookManager，只有 EventBus
+- 没有 Before/After LLM、Before/After Tool 这种同步拦截点
+- 没有审批型 hook
+- 子 agent 仍走 `pkg/tools/SubagentManager + RunToolLoop`，没有接入 `pkg/agent` 的 turn tree 和事件流
+
+### 一个关键现实
+
+`#1316` 文案里提到“只读并行、写入串行”的工具执行策略，但当前 `runTurn()` 实现已经先收敛成“顺序执行 + 每个工具后检查 steering / interrupt”。因此 hook 设计不应依赖未来的并行模型，而应该先兼容当前顺序执行，再为以后增加 `ReadOnlyIndicator` 留口子。
+
+## 设计原则
+
+- Hook 必须建立在 `pkg/agent` 的 EventBus 和 turn 上下文之上
+- EventBus 负责广播，HookManager 负责拦截，两者职责分离
+- 项目内挂载要简单，项目外挂载必须走 IPC
+- 观察型 hook 不能阻塞 loop；拦截型 hook 必须有超时
+- 先覆盖主 turn，不把 sub-turn 一次做满
+- 不新增第二套用户事件命名系统，优先复用 `EventKind.String()`
+
+## 总体架构
+
+分成三层：
+
+1. `EventBus`
+ 负责广播只读事件，现有实现直接复用
+
+2. `HookManager`
+ 负责管理 hook、排序、超时、错误隔离，并在 `runTurn()` 的明确检查点执行同步拦截
+
+3. `HookMount`
+ 负责两种挂载方式：
+ - 进程内 Go hook
+ - 进程外 IPC hook
+
+换句话说：
+
+- EventBus 是“发生了什么”
+- HookManager 是“谁能介入”
+- HookMount 是“这些 hook 从哪里来”
+
+## Hook 分类
+
+不建议把所有 hook 都设计成 `OnEvent(evt)`。
+
+建议拆成两类。
+
+### 1. 观察型
+
+只消费事件，不修改流程：
+
+```go
+type EventObserver interface {
+ OnEvent(ctx context.Context, evt agent.Event) error
+}
+```
+
+这类 hook 直接订阅 EventBus 即可。
+
+适用场景：
+
+- 审计日志
+- 指标上报
+- 调试 trace
+- 将事件转发给外部 UI / TUI / Web 面板
+
+### 2. 拦截型
+
+只在少数明确节点触发，允许返回动作：
+
+```go
+type LLMInterceptor interface {
+ BeforeLLM(ctx context.Context, req *LLMRequest) HookDecision[*LLMRequest]
+ AfterLLM(ctx context.Context, resp *LLMResponse) HookDecision[*LLMResponse]
+}
+
+type ToolInterceptor interface {
+ BeforeTool(ctx context.Context, call *ToolCall) HookDecision[*ToolCall]
+ AfterTool(ctx context.Context, result *ToolResultView) HookDecision[*ToolResultView]
+}
+
+type ToolApprover interface {
+ ApproveTool(ctx context.Context, req *ToolApprovalRequest) ApprovalDecision
+}
+```
+
+这里的 `HookDecision` 统一支持：
+
+- `continue`
+- `modify`
+- `deny_tool`
+- `abort_turn`
+- `hard_abort`
+
+## 对外暴露的最小 hook 面
+
+V1 不需要把所有 EventKind 都变成可拦截点。
+
+建议只开放这些同步 hook：
+
+- `before_llm`
+- `after_llm`
+- `before_tool`
+- `after_tool`
+- `approve_tool`
+
+其余节点继续作为只读事件暴露：
+
+- `turn_start`
+- `turn_end`
+- `llm_request`
+- `llm_response`
+- `tool_exec_start`
+- `tool_exec_end`
+- `tool_exec_skipped`
+- `steering_injected`
+- `follow_up_queued`
+- `interrupt_received`
+- `context_compress`
+- `session_summarize`
+- `error`
+
+`subturn_*` 在 V1 中保留名字，但不承诺一定触发，直到子 turn 迁移完成。
+
+## 项目内挂载
+
+内部挂载必须尽量低摩擦。
+
+建议提供两种等价方式，底层都走 HookManager。
+
+### 方式 A：代码显式挂载
+
+```go
+al.MountHook(hooks.Named("audit", &AuditHook{}))
+```
+
+适用于：
+
+- 仓内内建 hook
+- 单元测试
+- feature flag 控制
+
+### 方式 B：内建 registry
+
+```go
+func init() {
+ hooks.RegisterBuiltin("audit", func() hooks.Hook {
+ return &AuditHook{}
+ })
+}
+```
+
+启动时根据配置启用：
+
+```json
+{
+ "hooks": {
+ "builtins": {
+ "audit": { "enabled": true }
+ }
+ }
+}
+```
+
+这比 OpenClaw 的目录扫描更轻，也更贴合 Go 项目。
+
+## 项目外挂载
+
+这是本设计的硬要求。
+
+建议 V1 采用：
+
+- `JSON-RPC over stdio`
+
+原因：
+
+- 跨平台最简单
+- 不依赖额外端口
+- 非常适合“由 PicoClaw 启动一个外部 hook 进程”
+- 比 HTTP webhook 更适合同步拦截
+
+### 外部 hook 进程模型
+
+PicoClaw 启动外部进程，并在其 stdin/stdout 上跑协议。
+
+配置示例：
+
+```json
+{
+ "hooks": {
+ "processes": {
+ "review-gate": {
+ "enabled": true,
+ "transport": "stdio",
+ "command": ["uvx", "picoclaw-hook-reviewer"],
+ "observe": ["turn_start", "turn_end", "tool_exec_end"],
+ "intercept": ["before_tool", "approve_tool"],
+ "timeout_ms": 5000
+ }
+ }
+ }
+}
+```
+
+### 协议边界
+
+不要把内部 Go 结构体直接暴露给 IPC。
+
+建议定义稳定的协议对象：
+
+- `HookHandshake`
+- `HookEventNotification`
+- `BeforeLLMRequest`
+- `AfterLLMRequest`
+- `BeforeToolRequest`
+- `AfterToolRequest`
+- `ApproveToolRequest`
+- `HookDecision`
+
+其中：
+
+- 观察型事件用 notification，fire-and-forget
+- 拦截型事件用 request/response，同步等待
+
+### 为什么是 stdio，而不是直接用 HTTP webhook
+
+因为两者用途不同：
+
+- HTTP webhook 更适合“外部系统向 PicoClaw 投递事件”
+- stdio/RPC 更适合“PicoClaw 在 turn 内同步询问外部 hook 是否改写 / 放行 / 拒绝”
+
+如果未来需要 OpenClaw 式 webhook，可以作为独立入口层，再把外部事件转成 inbound message 或 steering，而不是直接替代 hook IPC。
+
+## Hook 执行顺序
+
+建议统一排序规则：
+
+- 先内建 in-process hook
+- 再外部 IPC hook
+- 同组内按 `priority` 从小到大执行
+
+原因：
+
+- 内建 hook 延迟更低，适合做基础规范化
+- 外部 hook 更适合做审批、审计、组织级策略
+
+## 超时与错误策略
+
+### 观察型
+
+- 默认超时：`500ms`
+- 超时或报错：记录日志，继续主流程
+
+### 拦截型
+
+- `before_llm` / `after_llm` / `before_tool` / `after_tool`：默认 `5s`
+- `approve_tool`：默认 `60s`
+
+超时行为：
+
+- 普通拦截：`continue`
+- 审批：`deny`
+
+这点应直接沿用 `#1316` 的安全倾向。
+
+## 与当前分支的对接点
+
+### 直接复用
+
+- 事件定义：`pkg/agent/events.go`
+- 事件广播：`pkg/agent/eventbus.go`
+- 活跃 turn / interrupt / rollback：`pkg/agent/turn.go`
+- 事件发射点：`pkg/agent/loop.go`
+
+### 需要新增
+
+- `pkg/agent/hooks.go`
+ - Hook 接口
+ - HookDecision / ApprovalDecision
+ - HookManager
+
+- `pkg/agent/hook_mount.go`
+ - 内建 hook 注册
+ - 外部进程 hook 注册
+
+- `pkg/agent/hook_ipc.go`
+ - stdio JSON-RPC bridge
+
+- `pkg/agent/hook_types.go`
+ - IPC 稳定载荷
+
+### 需要改造
+
+- `pkg/agent/loop.go`
+ - 在 LLM 和 tool 关键路径前后插入 HookManager 调用
+
+- `pkg/tools/base.go`
+ - 可选新增 `ReadOnlyIndicator`
+
+- `pkg/tools/spawn.go`
+- `pkg/tools/subagent.go`
+ - 先保留现状
+ - 等 sub-turn 迁移后再接入 `subturn_*` hook
+
+## 一个更贴合当前分支的数据流
+
+### 观察链路
+
+```text
+runTurn() -> emitEvent() -> EventBus -> observers
+```
+
+### 拦截链路
+
+```text
+runTurn()
+ -> HookManager.BeforeLLM()
+ -> Provider.Chat()
+ -> HookManager.AfterLLM()
+ -> HookManager.BeforeTool()
+ -> HookManager.ApproveTool()
+ -> tool.Execute()
+ -> HookManager.AfterTool()
+```
+
+也就是说：
+
+- observer 不改变现有 `emitEvent()`
+- interceptor 直接插在 `runTurn()` 热路径
+
+## 用户可见配置
+
+建议新增：
+
+```json
+{
+ "hooks": {
+ "enabled": true,
+ "builtins": {},
+ "processes": {},
+ "defaults": {
+ "observer_timeout_ms": 500,
+ "interceptor_timeout_ms": 5000,
+ "approval_timeout_ms": 60000
+ }
+ }
+}
+```
+
+V1 不做复杂自动发现。
+
+原因：
+
+- 当前分支重点是把地基打稳
+- 目录扫描、安装器、脚手架可以后置
+- 先让仓内和仓外都能挂上去，比“管理体验完整”更重要
+
+## 推荐的 V1 范围
+
+### 必做
+
+- HookManager
+- in-process 挂载
+- stdio IPC 挂载
+- observer hooks
+- `before_tool` / `after_tool` / `approve_tool`
+- `before_llm` / `after_llm`
+
+### 可后置
+
+- hook CLI 管理命令
+- hook 自动发现
+- Unix socket / named pipe transport
+- sub-turn hook 生命周期
+- read-only 并行分组
+- webhook 到 inbound message 的映射入口
+
+## 分阶段落地
+
+### Phase 1
+
+- 引入 HookManager
+- 支持 in-process observer + interceptor
+- 先只接主 turn
+
+### Phase 2
+
+- 引入 `stdio` 外部 hook 进程桥
+- 支持组织级审批 / 审计 / 参数改写
+
+### Phase 3
+
+- 把 `SubagentManager` 迁移到 `runTurn/sub-turn`
+- 接通 `subturn_spawn` / `subturn_end` / `subturn_result_delivered`
+
+### Phase 4
+
+- 视需求补 `ReadOnlyIndicator`
+- 在主 turn 和 sub-turn 上统一只读并行策略
+
+## 最终结论
+
+最适合 PicoClaw 当前分支的方案，不是直接复制 OpenClaw 的 hooks，也不是完整照搬 pi-mono 的 extension system，而是：
+
+- 以现有 `EventBus` 为只读观察面
+- 以新增 `HookManager` 为同步拦截面
+- 项目内通过 Go 对象直接挂载
+- 项目外通过 `stdio JSON-RPC` 进程通信挂载
+
+这样做有三个好处：
+
+- 和 `#1796` 一致，hooks 只是 EventBus 之上的消费层
+- 和当前 `refactor/agent` 实现一致，不需要推翻已有事件系统
+- 同时满足“仓内简单挂载”和“仓外进程通信挂载”两个硬需求
diff --git a/docs/design/steering-spec.md b/docs/design/steering-spec.md
new file mode 100644
index 000000000..0951bf864
--- /dev/null
+++ b/docs/design/steering-spec.md
@@ -0,0 +1,306 @@
+# Steering — Implementation Specification
+
+## Problem
+
+When the agent is running (executing a chain of tool calls), the user has no way to redirect it. They must wait for the full cycle to complete before sending a new message. This creates a poor experience when the agent takes a wrong direction — the user watches it waste time on tools that are no longer relevant.
+
+## Solution
+
+Steering introduces a **message queue** that external callers can push into at any time. The agent loop polls this queue at well-defined checkpoints. When a steering message is found, the agent:
+
+1. Stops executing further tools in the current batch
+2. Injects the user's message into the conversation context
+3. Calls the LLM again with the updated context
+
+The user's intent reaches the model **as soon as the current tool finishes**, not after the entire turn completes.
+
+## Architecture Overview
+
+```mermaid
+graph TD
+ subgraph External Callers
+ TG[Telegram]
+ DC[Discord]
+ SL[Slack]
+ end
+
+ subgraph AgentLoop
+ BUS[MessageBus]
+ DRAIN[drainBusToSteering goroutine]
+ SQ[steeringQueue]
+ RLI[runLLMIteration]
+ TE[Tool Execution Loop]
+ LLM[LLM Call]
+ end
+
+ TG -->|PublishInbound| BUS
+ DC -->|PublishInbound| BUS
+ SL -->|PublishInbound| BUS
+
+ BUS -->|ConsumeInbound while busy| DRAIN
+ DRAIN -->|Steer| SQ
+
+ RLI -->|1. initial poll| SQ
+ TE -->|2. poll after each tool| SQ
+
+ SQ -->|pendingMessages| RLI
+ RLI -->|inject into context| LLM
+```
+
+### Bus drain mechanism
+
+Channels (Telegram, Discord, etc.) publish messages to the `MessageBus` via `PublishInbound`. Without additional wiring, these messages would sit in the bus buffer until the current `processMessage` finishes — meaning steering would never work for real users.
+
+The solution: when `Run()` starts processing a message, it spawns a **drain goroutine** (`drainBusToSteering`) that keeps consuming from the bus and calling `Steer()`. When `processMessage` returns, the drain is canceled and normal consumption resumes.
+
+```mermaid
+sequenceDiagram
+ participant Bus
+ participant Run
+ participant Drain
+ participant AgentLoop
+
+ Run->>Bus: ConsumeInbound() → msg
+ Run->>Drain: spawn drainBusToSteering(ctx)
+ Run->>Run: processMessage(msg)
+
+ Note over Drain: running concurrently
+
+ Bus-->>Drain: ConsumeInbound() → newMsg
+ Drain->>AgentLoop: al.transcribeAudioInMessage(ctx, newMsg)
+ Drain->>AgentLoop: Steer(providers.Message{Content: newMsg.Content})
+
+ Run->>Run: processMessage returns
+ Run->>Drain: cancel context
+ Note over Drain: exits
+```
+
+## Data Structures
+
+### steeringQueue
+
+A thread-safe FIFO queue, private to the `agent` package.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mu` | `sync.Mutex` | Protects all access to `queue` and `mode` |
+| `queue` | `[]providers.Message` | Pending steering messages |
+| `mode` | `SteeringMode` | Dequeue strategy |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `push(msg) error` | Appends a message to the queue. Returns an error if the queue is full (`MaxQueueSize`) |
+| `dequeue() []Message` | Removes and returns messages according to `mode`. Returns `nil` if empty |
+| `len() int` | Returns the current queue length |
+| `setMode(mode)` | Updates the dequeue strategy |
+| `getMode() SteeringMode` | Returns the current mode |
+
+### SteeringMode
+
+| Value | Constant | Behavior |
+|-------|----------|----------|
+| `"one-at-a-time"` | `SteeringOneAtATime` | `dequeue()` returns only the **first** message. Remaining messages stay in the queue for subsequent polls. |
+| `"all"` | `SteeringAll` | `dequeue()` drains the **entire** queue and returns all messages at once. |
+
+Default: `"one-at-a-time"`.
+
+### processOptions extension
+
+A new field was added to `processOptions`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `SkipInitialSteeringPoll` | `bool` | When `true`, the initial steering poll at loop start is skipped. Used by `Continue()` to avoid double-dequeuing. |
+
+## Public API on AgentLoop
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `Steer` | `Steer(msg providers.Message) error` | Enqueues a steering message. Returns an error if the queue is full or not initialized. Thread-safe, can be called from any goroutine. |
+| `SteeringMode` | `SteeringMode() SteeringMode` | Returns the current dequeue mode. |
+| `SetSteeringMode` | `SetSteeringMode(mode SteeringMode)` | Changes the dequeue mode at runtime. |
+| `Continue` | `Continue(ctx, sessionKey, channel, chatID) (string, error)` | Resumes an idle agent using pending steering messages. Returns `""` if queue is empty. |
+
+## Integration into the Agent Loop
+
+### Where steering is wired
+
+The steering queue lives as a field on `AgentLoop`:
+
+```
+AgentLoop
+ ├── bus
+ ├── cfg
+ ├── registry
+ ├── steering *steeringQueue ← new
+ ├── ...
+```
+
+It is initialized in `NewAgentLoop` from `cfg.Agents.Defaults.SteeringMode`.
+
+### Detailed flow through runLLMIteration
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant AgentLoop
+ participant runLLMIteration
+ participant ToolExecution
+ participant LLM
+
+ User->>AgentLoop: Steer(message)
+ Note over AgentLoop: steeringQueue.push(message)
+
+ Note over runLLMIteration: ── iteration starts ──
+
+ runLLMIteration->>AgentLoop: dequeueSteeringMessages()"
+}
+```
+
+These results are:
+- Appended to the conversation `messages[]`
+- Saved to the session via `AddFullMessage`
+
+This ensures the LLM knows which of its requested actions were not performed.
+
+### Loop condition change
+
+The iteration loop condition was changed from:
+
+```go
+for iteration < agent.MaxIterations
+```
+
+to:
+
+```go
+for iteration < agent.MaxIterations || len(pendingMessages) > 0
+```
+
+This allows **one extra iteration** when steering arrives right at the max iteration boundary, ensuring the steering message is always processed.
+
+### Tool execution: parallel → sequential
+
+**Before steering:** all tool calls in a batch were executed in parallel using `sync.WaitGroup`.
+
+**After steering:** tool calls execute **sequentially**. This is required because steering must be polled between individual tool completions. A parallel execution model would not allow interrupting mid-batch.
+
+> **Trade-off:** This introduces latency when the LLM requests multiple independent tools in a single turn. In practice, most batches contain 1-2 tools, so the impact is minimal. The benefit of being able to interrupt outweighs the cost.
+
+### Why skip remaining tools (instead of letting them finish)
+
+Two strategies were considered when a steering message is detected mid-batch:
+
+1. **Skip remaining tools** (chosen) — stop executing, mark the rest as skipped, inject steering
+2. **Finish all tools, then inject** — let everything run, append steering afterwards
+
+Strategy 2 was rejected for three reasons:
+
+**Irreversible side effects.** Tools can send emails, write files, spawn subagents, or call external APIs. If the user says "stop" or "change direction", those actions have already happened and cannot be undone.
+
+| Tool batch | Steering | Skip (1) | Finish (2) |
+|---|---|---|---|
+| `[search, send_email]` | "don't send it" | Email not sent | Email sent |
+| `[query, write_file, spawn]` | "wrong database" | Only query runs | File + subagent wasted |
+| `[fetch₁, fetch₂, fetch₃, write]` | topic change | 1 fetch | 3 fetches + write, all discarded |
+
+**Wasted latency.** Tools like web fetches and API calls take seconds each. In a 3-tool batch averaging 3-4s per tool, the user would wait 10+ seconds for work that gets thrown away.
+
+**The LLM retains full awareness.** Skipped tools receive an explicit `"Skipped due to queued user message."` result, so the model knows what was not done and can decide whether to re-execute with the new context or take a different path.
+
+## The Continue() method
+
+`Continue` handles the case where the agent is **idle** (its last message was from the assistant) and the user has enqueued steering messages in the meantime.
+
+```mermaid
+flowchart TD
+ A[Continue called] --> B{dequeueSteeringMessages}
+ B -->|empty| C["return ('', nil)"]
+ B -->|messages found| D[Combine message contents]
+ D --> E["runAgentLoop with {
+ const response = await fetch(
+ "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+ { headers: { Authorization: `Bearer ${accessToken}` } }
+ );
+ const data = await response.json();
+ return data.email;
+}
+```
+
+**ID du projet (requis pour les appels API) :**
+```typescript
+async function fetchProjectId(accessToken: string): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "google-api-nodejs-client/9.15.1",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ "Client-Metadata": JSON.stringify({
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ }),
+ };
+
+ const response = await fetch(
+ "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({
+ metadata: {
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ const data = await response.json();
+ return data.cloudaicompanionProject || "rising-fact-p41fc"; // Valeur par défaut
+}
+```
+
+---
+
+## Détails de l'implémentation OAuth
+
+### Identifiants client
+
+**Important :** Ceux-ci sont encodés en base64 dans le code source pour la synchronisation avec pi-ai :
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+ "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### Modes de flux OAuth
+
+1. **Flux automatique** (machines locales avec navigateur) :
+ - Ouvre le navigateur automatiquement
+ - Le serveur de callback local capture la redirection
+ - Aucune interaction utilisateur requise après l'authentification initiale
+
+2. **Flux manuel** (distant/sans interface/WSL2) :
+ - URL affichée pour copier-coller manuellement
+ - L'utilisateur complète l'authentification dans un navigateur externe
+ - L'utilisateur colle l'URL de redirection complète
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+ return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## Gestion des jetons
+
+### Structure du profil d'authentification
+
+```typescript
+type OAuthCredential = {
+ type: "oauth";
+ provider: "google-antigravity";
+ access: string; // Jeton d'accès
+ refresh: string; // Jeton de rafraîchissement
+ expires: number; // Horodatage d'expiration (ms depuis epoch)
+ email?: string; // E-mail de l'utilisateur
+ projectId?: string; // ID du projet Google Cloud
+};
+```
+
+### Rafraîchissement des jetons
+
+Les identifiants incluent un jeton de rafraîchissement qui peut être utilisé pour obtenir de nouveaux jetons d'accès lorsque le jeton actuel expire. L'expiration est définie avec un tampon de 5 minutes pour éviter les conditions de concurrence.
+
+---
+
+## Récupération de la liste des modèles
+
+### Récupérer les modèles disponibles
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+ accessToken: string,
+ projectId: string
+): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ };
+
+ const response = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ const data = await response.json();
+
+ // Retourne les modèles avec les informations de quota
+ return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+ id: modelId,
+ displayName: modelInfo.displayName,
+ quotaInfo: {
+ remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+ resetTime: modelInfo.quotaInfo?.resetTime,
+ isExhausted: modelInfo.quotaInfo?.isExhausted,
+ },
+ }));
+}
+```
+
+### Format de réponse
+
+```typescript
+type FetchAvailableModelsResponse = {
+ models?: Record;
+};
+```
+
+---
+
+## Suivi de l'utilisation
+
+### Récupérer les données d'utilisation
+
+```typescript
+export async function fetchAntigravityUsage(
+ token: string,
+ timeoutMs: number
+): Promise {
+ // 1. Récupérer les crédits et les informations du plan
+ const loadCodeAssistRes = await fetch(
+ `${BASE_URL}/v1internal:loadCodeAssist`,
+ {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${token}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ metadata: {
+ ideType: "ANTIGRAVITY",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ // Extraire les informations de crédits
+ const { availablePromptCredits, planInfo, currentTier } = data;
+
+ // 2. Récupérer les quotas des modèles
+ const modelsRes = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers: { Authorization: `Bearer ${token}` },
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ // Construire les fenêtres d'utilisation
+ return {
+ provider: "google-antigravity",
+ displayName: "Google Antigravity",
+ windows: [
+ { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+ // Quotas individuels des modèles...
+ ],
+ plan: currentTier?.name || planType,
+ };
+}
+```
+
+### Structure de la réponse d'utilisation
+
+```typescript
+type ProviderUsageSnapshot = {
+ provider: "google-antigravity";
+ displayName: string;
+ windows: UsageWindow[];
+ plan?: string;
+ error?: string;
+};
+
+type UsageWindow = {
+ label: string; // "Credits" ou ID du modèle
+ usedPercent: number; // 0-100
+ resetAt?: number; // Horodatage de réinitialisation du quota
+};
+```
+
+---
+
+## Structure du plugin fournisseur
+
+### Définition du plugin
+
+```typescript
+const antigravityPlugin = {
+ id: "google-antigravity-auth",
+ name: "Google Antigravity Auth",
+ description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+ configSchema: emptyPluginConfigSchema(),
+
+ register(api: PicoClawPluginApi) {
+ api.registerProvider({
+ id: "google-antigravity",
+ label: "Google Antigravity",
+ docsPath: "/providers/models",
+ aliases: ["antigravity"],
+
+ auth: [
+ {
+ id: "oauth",
+ label: "Google OAuth",
+ hint: "PKCE + localhost callback",
+ kind: "oauth",
+ run: async (ctx: ProviderAuthContext) => {
+ // Implémentation OAuth ici
+ },
+ },
+ ],
+ });
+ },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+ config: PicoClawConfig;
+ agentDir?: string;
+ workspaceDir?: string;
+ prompter: WizardPrompter; // Invites/notifications UI
+ runtime: RuntimeEnv; // Journalisation, etc.
+ isRemote: boolean; // Exécution à distance ou non
+ openUrl: (url: string) => Promise; // Ouverture du navigateur
+ oauth: {
+ createVpsAwareHandlers: Function;
+ };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+ profiles: Array<{
+ profileId: string;
+ credential: AuthProfileCredential;
+ }>;
+ configPatch?: Partial;
+ defaultModel?: string;
+ notes?: string[];
+};
+```
+
+---
+
+## Exigences d'intégration
+
+### 1. Environnement/dépendances requis
+
+- Go ≥ 1.25
+- Base de code PicoClaw (`pkg/providers/` et `pkg/auth/`)
+- Packages de la bibliothèque standard `crypto` et `net/http`
+
+### 2. En-têtes requis pour les appels API
+
+```typescript
+const REQUIRED_HEADERS = {
+ "Authorization": `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity", // ou "google-api-nodejs-client/9.15.1"
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// Pour les appels loadCodeAssist, inclure également :
+const CLIENT_METADATA = {
+ ideType: "ANTIGRAVITY", // ou "IDE_UNSPECIFIED"
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+};
+```
+
+### 3. Assainissement des schémas de modèles
+
+Antigravity utilise des modèles compatibles Gemini, les schémas d'outils doivent donc être assainis :
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+ "patternProperties",
+ "additionalProperties",
+ "$schema",
+ "$id",
+ "$ref",
+ "$defs",
+ "definitions",
+ "examples",
+ "minLength",
+ "maxLength",
+ "minimum",
+ "maximum",
+ "multipleOf",
+ "pattern",
+ "format",
+ "minItems",
+ "maxItems",
+ "uniqueItems",
+ "minProperties",
+ "maxProperties",
+]);
+
+// Nettoyer le schéma avant l'envoi
+function cleanToolSchemaForGemini(schema: Record): unknown {
+ // Supprimer les mots-clés non supportés
+ // S'assurer que le niveau supérieur a type: "object"
+ // Aplatir les unions anyOf/oneOf
+}
+```
+
+### 4. Gestion des blocs de réflexion (modèles Claude)
+
+Pour les modèles Claude via Antigravity, les blocs de réflexion nécessitent un traitement spécial :
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+ messages: AgentMessage[]
+): AgentMessage[] {
+ // Valider les signatures de réflexion
+ // Normaliser les champs de signature
+ // Rejeter les blocs de réflexion non signés
+}
+```
+
+---
+
+## Points de terminaison API
+
+### Points de terminaison d'authentification
+
+| Point de terminaison | Méthode | Objectif |
+|---------------------|---------|----------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | Autorisation OAuth |
+| `https://oauth2.googleapis.com/token` | POST | Échange de jetons |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | Informations utilisateur (e-mail) |
+
+### Points de terminaison Cloud Code Assist
+
+| Point de terminaison | Méthode | Objectif |
+|---------------------|---------|----------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | Charger les infos du projet, crédits, plan |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | Lister les modèles disponibles avec quotas |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | Point de terminaison de streaming de chat |
+
+**Format de requête API (chat) :**
+Le point de terminaison `v1internal:streamGenerateContent` attend une enveloppe encapsulant la requête Gemini standard :
+
+```json
+{
+ "project": "your-project-id",
+ "model": "model-id",
+ "request": {
+ "contents": [...],
+ "systemInstruction": {...},
+ "generationConfig": {...},
+ "tools": [...]
+ },
+ "requestType": "agent",
+ "userAgent": "antigravity",
+ "requestId": "agent-timestamp-random"
+}
+```
+
+**Format de réponse API (SSE) :**
+Chaque message SSE (`data: {...}`) est encapsulé dans un champ `response` :
+
+```json
+{
+ "response": {
+ "candidates": [...],
+ "usageMetadata": {...},
+ "modelVersion": "...",
+ "responseId": "..."
+ },
+ "traceId": "...",
+ "metadata": {}
+}
+```
+
+---
+
+## Configuration
+
+### Configuration config.json
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gemini-flash",
+ "model": "antigravity/gemini-3-flash",
+ "auth_method": "oauth"
+ }
+ ],
+ "agents": {
+ "defaults": {
+ "model_name": "gemini-flash"
+ }
+ }
+}
+```
+
+### Stockage du profil d'authentification
+
+Les profils d'authentification sont stockés dans `~/.picoclaw/auth.json` :
+
+```json
+{
+ "credentials": {
+ "google-antigravity": {
+ "access_token": "ya29...",
+ "refresh_token": "1//...",
+ "expires_at": "2026-01-01T00:00:00Z",
+ "provider": "google-antigravity",
+ "auth_method": "oauth",
+ "email": "user@example.com",
+ "project_id": "my-project-id"
+ }
+ }
+}
+```
+
+---
+
+## Créer un nouveau fournisseur dans PicoClaw
+
+Les fournisseurs PicoClaw sont implémentés en tant que packages Go sous `pkg/providers/`. Pour ajouter un nouveau fournisseur :
+
+### Implémentation étape par étape
+
+#### 1. Créer le fichier du fournisseur
+
+Créez un nouveau fichier Go dans `pkg/providers/` :
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. Implémenter l'interface Provider
+
+Votre fournisseur doit implémenter l'interface `Provider` définie dans `pkg/providers/types.go` :
+
+```go
+package providers
+
+type YourProvider struct {
+ apiKey string
+ apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+ if apiBase == "" {
+ apiBase = "https://api.your-provider.com/v1"
+ }
+ return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+ // Implémenter la complétion de chat avec streaming
+}
+```
+
+#### 3. Enregistrer dans la factory
+
+Ajoutez votre fournisseur au switch de protocole dans `pkg/providers/factory.go` :
+
+```go
+case "your-provider":
+ return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. Ajouter la configuration par défaut (optionnel)
+
+Ajoutez une entrée par défaut dans `pkg/config/defaults.go` :
+
+```go
+{
+ ModelName: "your-model",
+ Model: "your-provider/model-name",
+ APIKey: "",
+},
+```
+
+#### 5. Ajouter le support d'authentification (optionnel)
+
+Si votre fournisseur nécessite OAuth ou une authentification spéciale, ajoutez un cas dans `cmd/picoclaw/internal/auth/helpers.go` :
+
+```go
+case "your-provider":
+ authLoginYourProvider()
+```
+
+#### 6. Configurer via `config.json`
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "your-model",
+ "model": "your-provider/model-name",
+ "api_key": "your-api-key",
+ "api_base": "https://api.your-provider.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## Tester votre implémentation
+
+### Commandes CLI
+
+```bash
+# S'authentifier avec un fournisseur
+picoclaw auth login --provider your-provider
+
+# Lister les modèles (pour Antigravity)
+picoclaw auth models
+
+# Démarrer la passerelle
+picoclaw gateway
+
+# Exécuter un agent avec un modèle spécifique
+picoclaw agent -m "Hello" --model your-model
+```
+
+### Variables d'environnement pour les tests
+
+```bash
+# Remplacer le modèle par défaut
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# Remplacer les paramètres du fournisseur
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## Références
+
+- **Fichiers source :**
+ - `pkg/providers/antigravity_provider.go` - Implémentation du fournisseur Antigravity
+ - `pkg/auth/oauth.go` - Implémentation du flux OAuth
+ - `pkg/auth/store.go` - Stockage des identifiants d'authentification (`~/.picoclaw/auth.json`)
+ - `pkg/providers/factory.go` - Factory des fournisseurs et routage de protocole
+ - `pkg/providers/types.go` - Définitions de l'interface fournisseur
+ - `cmd/picoclaw/internal/auth/helpers.go` - Commandes CLI d'authentification
+
+- **Documentation :**
+ - `docs/ANTIGRAVITY_USAGE.md` - Guide d'utilisation d'Antigravity
+ - `docs/migration/model-list-migration.md` - Guide de migration
+
+---
+
+## Notes
+
+1. **Projet Google Cloud :** Antigravity nécessite que Gemini for Google Cloud soit activé sur votre projet Google Cloud
+2. **Quotas :** Utilise les quotas du projet Google Cloud (pas de facturation séparée)
+3. **Accès aux modèles :** Les modèles disponibles dépendent de la configuration de votre projet Google Cloud
+4. **Blocs de réflexion :** Les modèles Claude via Antigravity nécessitent un traitement spécial des blocs de réflexion avec signatures
+5. **Assainissement des schémas :** Les schémas d'outils doivent être assainis pour supprimer les mots-clés JSON Schema non supportés
+
+---
+
+---
+
+## Gestion des erreurs courantes
+
+### 1. Limitation de débit (HTTP 429)
+
+Antigravity retourne une erreur 429 lorsque les quotas du projet/modèle sont épuisés. La réponse d'erreur contient souvent un `quotaResetDelay` dans le champ `details`.
+
+**Exemple d'erreur 429 :**
+```json
+{
+ "error": {
+ "code": 429,
+ "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+ "status": "RESOURCE_EXHAUSTED",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+ "metadata": {
+ "quotaResetDelay": "4h30m28.060903746s"
+ }
+ }
+ ]
+ }
+}
+```
+
+### 2. Réponses vides (modèles restreints)
+
+Certains modèles peuvent apparaître dans la liste des modèles disponibles mais retourner une réponse vide (200 OK mais flux SSE vide). Cela se produit généralement pour les modèles en préversion ou restreints que le projet actuel n'a pas la permission d'utiliser.
+
+**Traitement :** Traiter les réponses vides comme des erreurs informant l'utilisateur que le modèle pourrait être restreint ou invalide pour son projet.
+
+---
+
+## Dépannage
+
+### "Token expired" (jeton expiré)
+- Rafraîchir les jetons OAuth : `picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled" (Gemini for Google Cloud n'est pas activé)
+- Activer l'API dans votre Google Cloud Console
+
+### "Project not found" (projet non trouvé)
+- Vérifier que votre projet Google Cloud a les API nécessaires activées
+- Vérifier que l'ID du projet est correctement récupéré lors de l'authentification
+
+### Les modèles n'apparaissent pas dans la liste
+- Vérifier que l'authentification OAuth s'est terminée avec succès
+- Vérifier le stockage du profil d'authentification : `~/.picoclaw/auth.json`
+- Relancer `picoclaw auth login --provider antigravity`
diff --git a/docs/fr/ANTIGRAVITY_USAGE.md b/docs/fr/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..d6d0a2bd4
--- /dev/null
+++ b/docs/fr/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> Retour au [README](../../README.fr.md)
+
+# Utiliser le fournisseur Antigravity dans PicoClaw
+
+Ce guide explique comment configurer et utiliser le fournisseur **Antigravity** (Google Cloud Code Assist) dans PicoClaw.
+
+## Prérequis
+
+1. Un compte Google.
+2. Google Cloud Code Assist activé (généralement disponible via l'intégration « Gemini for Google Cloud »).
+
+## 1. Authentification
+
+Pour vous authentifier avec Antigravity, exécutez la commande suivante :
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### Authentification manuelle (Headless/VPS)
+Si vous exécutez PicoClaw sur un serveur (Coolify/Docker) et ne pouvez pas accéder à `localhost`, suivez ces étapes :
+1. Exécutez la commande ci-dessus.
+2. Copiez l'URL fournie et ouvrez-la dans votre navigateur local.
+3. Complétez la connexion.
+4. Votre navigateur sera redirigé vers une URL `localhost:51121` (qui ne se chargera pas).
+5. **Copiez cette URL finale** depuis la barre d'adresse de votre navigateur.
+6. **Collez-la dans le terminal** où PicoClaw attend.
+
+PicoClaw extraira automatiquement le code d'autorisation et terminera le processus.
+
+## 2. Gestion des modèles
+
+### Lister les modèles disponibles
+Pour voir quels modèles sont accessibles à votre projet et vérifier leurs quotas :
+
+```bash
+picoclaw auth models
+```
+
+### Changer de modèle
+Vous pouvez modifier le modèle par défaut dans `~/.picoclaw/config.json` ou le remplacer via le CLI :
+
+```bash
+# Remplacer pour une seule commande
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. Utilisation en production (Coolify/Docker)
+
+Si vous déployez via Coolify ou Docker, suivez ces étapes pour tester :
+
+1. **Variables d'environnement** :
+ * `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2. **Persistance de l'authentification** :
+ Si vous vous êtes connecté localement, vous pouvez copier vos identifiants vers le serveur :
+ ```bash
+ scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+ ```
+ *Alternativement*, exécutez la commande `auth login` une fois sur le serveur si vous avez un accès terminal.
+
+## 4. Dépannage
+
+* **Réponse vide** : Si un modèle renvoie une réponse vide, il peut être restreint pour votre projet. Essayez `gemini-3-flash` ou `claude-opus-4-6-thinking`.
+* **429 Limite de débit** : Antigravity a des quotas stricts. PicoClaw affichera le « temps de réinitialisation » dans le message d'erreur si vous atteignez une limite.
+* **404 Non trouvé** : Assurez-vous d'utiliser un ID de modèle provenant de la liste `picoclaw auth models`. Utilisez l'ID court (par ex. `gemini-3-flash`) et non le chemin complet.
+
+## 5. Résumé des modèles fonctionnels
+
+D'après les tests, les modèles suivants sont les plus fiables :
+* `gemini-3-flash` (Rapide, haute disponibilité)
+* `gemini-2.5-flash-lite` (Léger)
+* `claude-opus-4-6-thinking` (Puissant, inclut le raisonnement)
diff --git a/docs/fr/chat-apps.md b/docs/fr/chat-apps.md
index 03bb6e17b..daff951f4 100644
--- a/docs/fr/chat-apps.md
+++ b/docs/fr/chat-apps.md
@@ -8,23 +8,25 @@ Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, Din
> **Note** : Tous les canaux basés sur les webhooks (LINE, WeCom, etc.) sont servis sur un seul serveur HTTP Gateway partagé (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`). Il n'y a pas de ports par canal à configurer. Note : Feishu utilise le mode WebSocket/SDK et n'utilise pas le serveur HTTP webhook partagé.
-| Canal | Configuration |
-| ------------ | -------------------------------------- |
-| **Telegram** | Facile (juste un token) |
-| **Discord** | Facile (bot token + intents) |
-| **WhatsApp** | Facile (natif : scan QR ; ou bridge URL) |
-| **Matrix** | Moyen (homeserver + bot access token) |
-| **QQ** | Facile (AppID + AppSecret) |
-| **DingTalk** | Moyen (identifiants de l'application) |
-| **LINE** | Moyen (identifiants + webhook URL) |
-| **WeCom AI Bot** | Moyen (Token + clé AES) |
-| **Feishu** | Moyen (App ID + Secret, mode WebSocket) |
-| **Slack** | Moyen (Bot token + App token) |
-| **IRC** | Moyen (serveur + configuration TLS) |
-| **OneBot** | Moyen (QQ via protocole OneBot) |
-| **MaixCam** | Facile (intégration matérielle Sipeed) |
-| **Pico** | Native PicoClaw protocol |
+| Canal | Difficulté | Description | Documentation |
+| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Telegram** | ⭐ Facile | Recommandé, transcription vocale, long polling (pas d'IP publique requise) | [Documentation](../channels/telegram/README.fr.md) |
+| **Discord** | ⭐ Facile | Socket Mode, groupes/DM, écosystème bot riche | [Documentation](../channels/discord/README.fr.md) |
+| **WhatsApp** | ⭐ Facile | Natif (scan QR) ou Bridge URL | [Documentation](#whatsapp) |
+| **Weixin** | ⭐ Facile | Scan QR natif (API Tencent iLink) | [Documentation](#weixin) |
+| **Slack** | ⭐ Facile | **Socket Mode** (pas d'IP publique requise), entreprise | [Documentation](../channels/slack/README.fr.md) |
+| **Matrix** | ⭐⭐ Moyen | Protocole fédéré, auto-hébergement possible | [Documentation](../channels/matrix/README.fr.md) |
+| **QQ** | ⭐⭐ Moyen | API bot officielle, communauté chinoise | [Documentation](../channels/qq/README.fr.md) |
+| **DingTalk** | ⭐⭐ Moyen | Mode Stream (pas d'IP publique requise), entreprise | [Documentation](../channels/dingtalk/README.fr.md) |
+| **LINE** | ⭐⭐⭐ Avancé | HTTPS Webhook requis | [Documentation](../channels/line/README.fr.md) |
+| **WeCom (企业微信)** | ⭐⭐⭐ Avancé | Bot groupe (Webhook), app personnalisée (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.fr.md) / [App](../channels/wecom/wecom_app/README.fr.md) / [AI Bot](../channels/wecom/wecom_aibot/README.fr.md) |
+| **Feishu (飞书)** | ⭐⭐⭐ Avancé | Collaboration entreprise, fonctionnalités riches | [Documentation](../channels/feishu/README.fr.md) |
+| **IRC** | ⭐⭐ Moyen | Serveur + configuration TLS | [Documentation](#irc) |
+| **OneBot** | ⭐⭐ Moyen | Compatible NapCat/Go-CQHTTP, écosystème communautaire | [Documentation](../channels/onebot/README.fr.md) |
+| **MaixCam** | ⭐ Facile | Canal d'intégration matérielle pour caméras AI Sipeed | [Documentation](../channels/maixcam/README.fr.md) |
+| **Pico** | ⭐ Facile | Canal protocole natif PicoClaw | |
+
Telegram (Recommandé)
+
Discord
+
WhatsApp (natif via whatsmeow)/what
+
+Weixin (WeChat Personnel)
+
+
QQ /what
}
```
-> Définissez `allow_from` vide pour autoriser tous les utilisateurs, ou spécifiez des numéros QQ pour restreindre l'accès.
+4. Lancez `picoclaw gateway` et ouvrez QQ pour discuter avec votre bot
-**3. Lancer**
+> L'App Secret n'est affiché qu'une seule fois. Enregistrez-le immédiatement — le consulter à nouveau forcera une réinitialisation.
+>
+> Les bots créés via la page de configuration rapide sont initialement réservés au créateur et ne prennent pas en charge les discussions de groupe. Pour activer l'accès en groupe, configurez le mode sandbox sur la [QQ Open Platform](https://q.qq.com/).
-```bash
-picoclaw gateway
-```
+**Configuration manuelle**
+
+Si vous préférez créer le bot manuellement :
+
+* Connectez-vous sur [QQ Open Platform](https://q.qq.com/) pour vous inscrire en tant que développeur
+* Créez un bot QQ — personnalisez son avatar et son nom
+* Copiez l'**App ID** et l'**App Secret** depuis les paramètres du bot
+* Configurez comme indiqué ci-dessus et lancez `picoclaw gateway`
+
DingTalk
+
Matrix
+
LINE
+
WeCom (企业微信)
+
Feishu (飞书)
+
Slack
+
IRC
+
-OneBot OneBot (QQ via protocole OneBot)
+
MaixCam /skills` (builtin)
+3. `/skills` (intégré)
Pour les configurations avancées/de test, vous pouvez remplacer la racine des compétences builtin avec :
@@ -214,5 +214,150 @@ L'agent lira ce fichier toutes les 30 minutes (configurable) et exécutera toute
Pour les tâches longues (recherche web, appels API), utilisez l'outil `spawn` pour créer un **subagent** :
```markdown
-# Periodic Tasks
+# Tâches Périodiques
+
+## Tâches Rapides (répondre directement)
+
+- Indiquer l'heure actuelle
+
+## Tâches Longues (utiliser spawn pour l'asynchrone)
+
+- Rechercher les actualités IA sur le web et résumer
+- Vérifier les e-mails et signaler les messages importants
```
+
+**Comportements clés :**
+
+| Fonctionnalité | Description |
+| ---------------- | ------------------------------------------------------------------ |
+| **spawn** | Crée un subagent asynchrone, ne bloque pas le heartbeat |
+| **Contexte indépendant** | Le subagent a son propre contexte, sans historique de session |
+| **message tool** | Le subagent communique directement avec l'utilisateur |
+| **Non-bloquant** | Après le spawn, le heartbeat continue vers la tâche suivante |
+
+#### Flux de Communication du Subagent
+
+```
+Heartbeat déclenché
+ ↓
+Agent lit HEARTBEAT.md
+ ↓
+Tâche longue : spawn subagent
+ ↓ ↓
+Continue tâche suivante Subagent travaille indépendamment
+ ↓ ↓
+Toutes tâches terminées Subagent utilise "message" tool
+ ↓ ↓
+Répond HEARTBEAT_OK Utilisateur reçoit le résultat
+```
+
+**Configuration :**
+
+```json
+{
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ }
+}
+```
+
+| Option | Défaut | Description |
+| ---------- | ------ | ---------------------------------------- |
+| `enabled` | `true` | Activer/désactiver le heartbeat |
+| `interval` | `30` | Intervalle en minutes (minimum : 5) |
+
+**Variables d'environnement :**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` pour désactiver
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` pour changer l'intervalle
+
+### Providers
+
+> [!NOTE]
+> Groq fournit une transcription vocale gratuite via Whisper. Si configuré, les messages audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent.
+
+| Provider | Usage | Obtenir une clé API |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) |
+| `volcengine` | LLM (Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM (recommandé, accès à tous modèles) | [openrouter.ai](https://openrouter.ai) |
+| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |
+| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |
+| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |
+| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq` | LLM + **Transcription vocale** (Whisper)| [console.groq.com](https://console.groq.com) |
+| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) |
+| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) |
+
+### Configuration des Modèles (model_list)
+
+> **Nouveauté :** PicoClaw utilise désormais une approche **centrée sur le modèle**. Spécifiez simplement le format `vendor/model` (ex. `zhipu/glm-4.7`) pour ajouter de nouveaux providers — **aucune modification de code requise !**
+
+#### Tous les Vendors Supportés
+
+| Vendor | Préfixe `model` | API Base par défaut | Protocole | API Key |
+| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obtenir](https://platform.openai.com) |
+| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obtenir](https://console.anthropic.com) |
+| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obtenir](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obtenir](https://platform.deepseek.com) |
+| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obtenir](https://aistudio.google.com/api-keys) |
+| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obtenir](https://console.groq.com) |
+| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obtenir](https://dashscope.console.aliyun.com) |
+| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (pas de clé) |
+| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obtenir](https://openrouter.ai/keys) |
+| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obtenir](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth uniquement |
+
+#### Équilibrage de Charge
+
+Configurez plusieurs endpoints pour le même nom de modèle — PicoClaw effectuera automatiquement un round-robin :
+
+```json
+{
+ "model_list": [
+ { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
+ { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
+ ]
+}
+```
+
+#### Migration depuis l'ancienne config `providers`
+
+L'ancienne configuration `providers` est **dépréciée** mais toujours supportée. Voir [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Architecture des Providers
+
+PicoClaw route les providers par famille de protocole :
+
+- **Compatible OpenAI** : OpenRouter, Groq, Zhipu, endpoints vLLM et la plupart des autres.
+- **Anthropic** : Comportement natif de l'API Claude.
+- **Codex/OAuth** : Route d'authentification OAuth/token OpenAI.
+
+### Tâches Planifiées / Rappels
+
+PicoClaw supporte les tâches planifiées via l'outil `cron`. L'agent peut définir, lister et annuler des rappels ou tâches récurrentes.
+
+```json
+{
+ "tools": {
+ "cron": {
+ "enabled": true,
+ "exec_timeout_minutes": 5
+ }
+ }
+}
+```
+
+Les tâches planifiées persistent après redémarrage dans `~/.picoclaw/workspace/cron/`.
+
+### Sujets Avancés
+
+| Sujet | Description |
+| ----- | ----------- |
+| [Système de Hooks](../hooks/README.md) | Hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
+| [Steering](../steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
+| [SubTurn](../subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
+| [Gestion du Contexte](../agent-refactor/context.md) | Détection des limites de contexte, compression |
diff --git a/docs/fr/credential_encryption.md b/docs/fr/credential_encryption.md
new file mode 100644
index 000000000..eec765039
--- /dev/null
+++ b/docs/fr/credential_encryption.md
@@ -0,0 +1,159 @@
+> Retour au [README](../../README.fr.md)
+
+# Chiffrement des identifiants
+
+PicoClaw prend en charge le chiffrement des valeurs `api_key` dans les entrées de configuration `model_list`.
+Les clés chiffrées sont stockées sous forme de chaînes `enc://` et déchiffrées automatiquement au démarrage.
+
+---
+
+## Démarrage rapide
+
+**1. Définir votre phrase secrète**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. Chiffrer une clé API**
+
+Exécutez `picoclaw onboard` — il vous demande votre phrase secrète et génère la clé SSH,
+puis re-chiffre automatiquement toutes les entrées `api_key` en clair dans votre configuration
+lors du prochain appel à `SaveConfig`. La valeur `enc://` résultante ressemblera à :
+
+```
+enc://AAAA...base64...
+```
+
+**3. Coller la sortie dans votre configuration**
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-4o",
+ "model": "openai/gpt-4o",
+ "api_key": "enc://AAAA...base64...",
+ "api_base": "https://api.openai.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## Formats `api_key` pris en charge
+
+| Format | Exemple | Comportement |
+|--------|---------|--------------|
+| Texte clair | `sk-abc123` | Utilisé tel quel |
+| Référence fichier | `file://openai.key` | Contenu lu depuis le même répertoire que le fichier de configuration |
+| Chiffré | `enc://` | Déchiffré au démarrage avec `PICOCLAW_KEY_PASSPHRASE` |
+| Vide | `""` | Transmis tel quel (utilisé avec `auth_method: oauth`) |
+
+---
+
+## Conception cryptographique
+
+### Dérivation de clé
+
+Le chiffrement utilise **HKDF-SHA256** avec une clé privée SSH comme second facteur.
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### Chiffrement
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### Format de transmission
+
+```
+enc://
+```
+
+| Champ | Taille | Description |
+|-------|--------|-------------|
+| `salt` | 16 octets | Aléatoire par chiffrement ; fourni à HKDF |
+| `nonce` | 12 octets | Aléatoire par chiffrement ; IV AES-GCM |
+| `ciphertext` | variable | Texte chiffré AES-256-GCM + tag d'authentification de 16 octets |
+
+Le tag d'authentification GCM est automatiquement ajouté au texte chiffré. Toute altération provoque l'échec du déchiffrement avec une erreur plutôt que de retourner un texte clair corrompu.
+
+### Performance
+
+| Opération | Durée (ARM Cortex-A) |
+|-----------|----------------------|
+| Dérivation de clé (HKDF) | < 1 ms |
+| Déchiffrement AES-256-GCM | < 1 ms |
+| **Surcoût total au démarrage** | **< 2 ms par clé** |
+
+---
+
+## Sécurité à deux facteurs avec clé SSH
+
+Lorsqu'une clé privée SSH est fournie, casser le chiffrement nécessite **les deux** :
+
+1. La **phrase secrète** (`PICOCLAW_KEY_PASSPHRASE`)
+2. Le **fichier de clé privée SSH**
+
+Cela signifie qu'un fichier de configuration divulgué seul ne suffit pas pour récupérer la clé API, même si la phrase secrète est faible. La clé SSH apporte 256 bits d'entropie (Ed25519) indépendamment de la force de la phrase secrète.
+
+### Modèle de menace
+
+| Ce que l'attaquant possède | Peut-il déchiffrer ? |
+|---------------------------|---------------------|
+| Fichier de configuration uniquement | Non — nécessite la phrase secrète + la clé SSH |
+| Clé SSH uniquement | Non — nécessite la phrase secrète |
+| Phrase secrète uniquement | Non — nécessite la clé SSH |
+| Fichier de configuration + clé SSH + phrase secrète | Oui — compromission totale |
+
+---
+
+## Variables d'environnement
+
+| Variable | Requis | Description |
+|----------|--------|-------------|
+| `PICOCLAW_KEY_PASSPHRASE` | Oui (pour `enc://`) | Phrase secrète utilisée pour la dérivation de clé |
+| `PICOCLAW_SSH_KEY_PATH` | Non | Chemin vers la clé privée SSH. Si non défini, détection automatique depuis `~/.ssh/picoclaw_ed25519.key` |
+
+### Détection automatique de la clé SSH
+
+Si `PICOCLAW_SSH_KEY_PATH` n'est pas défini, PicoClaw recherche la clé dédiée :
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+Ce fichier dédié évite les conflits avec les clés SSH existantes de l'utilisateur.
+Exécutez `picoclaw onboard` pour le générer automatiquement.
+
+`os.UserHomeDir()` est utilisé pour la résolution multiplateforme du répertoire personnel (lit `USERPROFILE` sous Windows, `HOME` sous Unix/macOS).
+
+> **Remarque :** Un fichier de clé SSH est requis pour le chiffrement des identifiants. Si aucune clé n'est trouvée et que `PICOCLAW_SSH_KEY_PATH` n'est pas défini, le chiffrement/déchiffrement échouera. Exécutez `picoclaw onboard` pour générer la clé automatiquement.
+
+---
+
+## Migration
+
+Étant donné que les seuls éléments secrets sont `PICOCLAW_KEY_PASSPHRASE` et le fichier de clé privée SSH, la migration est simple :
+
+1. Copiez le fichier de configuration sur la nouvelle machine.
+2. Définissez `PICOCLAW_KEY_PASSPHRASE` avec la même valeur.
+3. Copiez le fichier de clé privée SSH au même chemin (ou définissez `PICOCLAW_SSH_KEY_PATH` vers son nouvel emplacement).
+
+Aucun re-chiffrement n'est nécessaire.
+
+---
+
+## Considérations de sécurité
+
+- **La phrase secrète et la clé SSH sont toutes deux requises.** La clé SSH agit comme un second facteur — sans elle, le chiffrement/déchiffrement échouera. Exécutez `picoclaw onboard` pour générer la clé si elle n'existe pas.
+- **La clé SSH est en lecture seule à l'exécution.** PicoClaw n'écrit ni ne modifie jamais le fichier de clé SSH.
+- **Les clés en texte clair restent prises en charge.** Les configurations existantes sans `enc://` ne sont pas affectées.
+- **Le format `enc://` est versionné** via le champ `info` de HKDF (`picoclaw-credential-v1`), permettant de futures mises à niveau d'algorithme sans casser les valeurs chiffrées existantes.
diff --git a/docs/fr/debug.md b/docs/fr/debug.md
new file mode 100644
index 000000000..5753ccf8c
--- /dev/null
+++ b/docs/fr/debug.md
@@ -0,0 +1,36 @@
+# Débogage de PicoClaw
+
+> Retour au [README](../../README.fr.md)
+
+PicoClaw effectue de multiples interactions complexes en arrière-plan pour chaque requête qu'il reçoit — du routage des messages et de l'évaluation de la complexité, à l'exécution des outils et à l'adaptation aux défaillances de modèle. Pouvoir voir exactement ce qui se passe est crucial, non seulement pour résoudre les problèmes potentiels, mais aussi pour véritablement comprendre le fonctionnement de l'agent.
+
+## Démarrer PicoClaw en mode débogage
+
+Pour obtenir des informations détaillées sur ce que fait l'agent (requêtes LLM, appels d'outils, routage des messages), vous pouvez démarrer la passerelle PicoClaw avec le drapeau de débogage :
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+Dans ce mode, le système formate les logs de manière détaillée et affiche des aperçus des prompts système et des résultats d'exécution des outils.
+
+## Désactiver la troncature des logs (logs complets)
+
+Par défaut, PicoClaw tronque les chaînes très longues (comme le *Prompt Système* ou les résultats JSON volumineux) dans les logs de débogage afin de garder la console lisible.
+
+Si vous avez besoin d'inspecter la sortie complète d'une commande ou le payload exact envoyé au modèle LLM, vous pouvez utiliser le drapeau `--no-truncate`.
+
+**Remarque :** Ce drapeau fonctionne *uniquement* en combinaison avec le mode `--debug`.
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+Lorsque ce drapeau est actif, la fonction de troncature globale est désactivée. Cela est extrêmement utile pour :
+
+* Vérifier la syntaxe exacte des messages envoyés au fournisseur.
+* Lire la sortie complète d'outils comme `exec`, `web_fetch` ou `read_file`.
+* Déboguer l'historique de session sauvegardé en mémoire.
diff --git a/docs/fr/docker.md b/docs/fr/docker.md
index f17ec355d..432edb1b2 100644
--- a/docs/fr/docker.md
+++ b/docs/fr/docker.md
@@ -12,6 +12,7 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. Premier lancement — génère automatiquement docker/data/config.json puis s'arrête
+# (se déclenche uniquement quand config.json et workspace/ sont tous deux absents)
docker compose -f docker/docker-compose.yml --profile gateway up
# Le conteneur affiche "First-run setup complete." et s'arrête.
diff --git a/docs/fr/hardware-compatibility.md b/docs/fr/hardware-compatibility.md
new file mode 100644
index 000000000..c1f397e80
--- /dev/null
+++ b/docs/fr/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> Retour au [README](../../README.fr.md)
+
+# 🖥️ PicoClaw Liste de compatibilité matérielle
+
+PicoClaw fonctionne sur pratiquement n'importe quel appareil Linux. Cette page répertorie les puces, produits et cartes de développement vérifiés.
+
+**Votre matériel n'est pas listé ?** Soumettez une PR pour l'ajouter ! Les fabricants de matériel sont invités à contribuer et à co-promouvoir.
+
+---
+
+## 1. Support de puces vérifié
+
+### x86
+
+| Fabricant | Puce | Notes |
+|-----------|------|-------|
+| Intel | Any x86 CPU (i386+) | Tous les processeurs de bureau/serveur/portable |
+| AMD | Any x86 CPU | Tous les processeurs de bureau/serveur/portable |
+
+### ARM
+
+| Sous-arch | Puces typiques | Notes |
+|-----------|----------------|-------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Monocœur ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Monocœur Cortex-A7, utilisé dans LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Quadricœur Cortex-A53, utilisé dans Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Quadricœur Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Quadricœur Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Bicœur Cortex-A53 + NPU, utilisé dans NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| Fabricant | Puce | Cœur | Notes |
+|-----------|------|------|-------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 intégré, utilisé dans LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L intégré, 1 TOPS NPU, caméra AI 4K SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | Série de caméras AI RISC-V |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Utilisé dans HaaS506-LD1 RTU industriel |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Utilisé dans Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | Conforme RVA23, RVV 1024 bits, inférence AI FP8 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 cœurs, 16MB cache L3, classe bureau |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, utilisé dans CanMV-K230 |
+
+### MIPS
+
+| Fabricant | Puce | Notes |
+|-----------|------|-------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, utilisé dans de nombreux routeurs OpenWrt (ex. Xiaomi Router 3G) |
+
+### LoongArch (loong64)
+
+| Fabricant | Puce | Notes |
+|-----------|------|-------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Quadricœur LA464 @ 2.5GHz, bureau/station de travail |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Quadricœur 4C/8T @ 2.5GHz, IPC comparable à Intel 10e génération |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Bicœur @ 1GHz, applications industrielles/IoT |
+
+---
+
+## 2. Produits vérifiés (par date de sortie)
+
+Produits grand public, routeurs et appareils industriels testés avec PicoClaw.
+
+| Année | Produit | Arch | SoC | RAM | Catégorie |
+|-------|---------|------|-----|-----|-----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Smartphone |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Tablette |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Routeur (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | Boîtier TV / Serveur domestique |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Enceinte connectée |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | RTU industriel |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | IP-KVM Pro |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | Caméra AI 4K |
+
+---
+
+## 3. Cartes de développement vérifiées (par date de sortie)
+
+| Année | Carte | Arch | SoC | RAM | Lien d'achat |
+|-------|-------|------|-----|-----|--------------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. Fonctionne également sur
+
+### Téléphones Android (via Termux)
+
+Tout téléphone Android ARM64 (2015+) avec 1 Go+ de RAM. Installez [Termux](https://github.com/termux/termux-app), utilisez `proot` pour exécuter PicoClaw.
+
+> Voir [README : Exécuter sur d'anciens téléphones Android](../../README.fr.md#-run-on-old-android-phones) pour les instructions de configuration.
+
+### Bureau / Serveur / Cloud
+
+| Plateforme | Notes |
+|------------|-------|
+| x86_64 Linux | Binaire natif, aucune dépendance |
+| x86_64 Windows | Binaire natif |
+| macOS (Intel / Apple Silicon) | Binaire natif |
+| Docker (any platform) | `docker compose` en une ligne, voir [Guide Docker](docker.md) |
+| OpenWrt routers | Builds MIPS/ARM, nécessite >32 Mo de RAM libre |
+| FreeBSD / NetBSD | Builds x86_64 et arm64 disponibles |
+
+---
+
+## 5. Configuration minimale requise
+
+| Ressource | Minimum | Recommandé |
+|-----------|---------|------------|
+| RAM | 10 Mo libres | 32 Mo+ libres |
+| Stockage | 20 Mo (binaire) | 50 Mo+ (avec espace de travail) |
+| CPU | N'importe lequel (monocœur 0,6 GHz+) | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| Réseau | Requis (pour les appels API LLM) | Ethernet ou WiFi |
+
+---
+
+## 6. Comment tester et contribuer
+
+```bash
+# 1. Télécharger pour votre architecture
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. Initialiser
+./picoclaw onboard
+
+# 3. Tester
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+Builds disponibles : `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### Ajouter votre matériel
+
+1. Forkez ce dépôt
+2. Ajoutez votre puce / produit / carte dans le tableau approprié
+3. Incluez : nom, architecture, SoC, RAM, année et un lien si disponible
+4. Soumettez une PR
+
+Fabricants de matériel : vous souhaitez ajouter un support officiel ou co-promouvoir ? Ouvrez une issue ou contactez-nous via [Discord](https://discord.gg/V4sAZ9XWpN).
diff --git a/docs/fr/providers.md b/docs/fr/providers.md
index b0b950a44..39f5cf36a 100644
--- a/docs/fr/providers.md
+++ b/docs/fr/providers.md
@@ -93,7 +93,7 @@ Cette conception permet également le **support multi-agents** avec une sélecti
],
"agents": {
"defaults": {
- "model": "gpt-5.4"
+ "model_name": "gpt-5.4"
}
}
}
@@ -266,13 +266,13 @@ L'ancienne configuration `providers` est **dépréciée** mais toujours prise en
],
"agents": {
"defaults": {
- "model": "glm-4.7"
+ "model_name": "glm-4.7"
}
}
}
```
-Pour un guide de migration détaillé, voir [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
+Pour un guide de migration détaillé, voir [migration/model-list-migration.md](../migration/model-list-migration.md).
### Architecture des Fournisseurs
@@ -298,7 +298,7 @@ Cela maintient le runtime léger tout en faisant des nouveaux backends compatibl
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
- "model": "glm-4.7",
+ "model_name": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
@@ -328,12 +328,11 @@ picoclaw agent -m "Hello"
{
"agents": {
"defaults": {
- "model": "anthropic/claude-opus-4-5"
+ "model_name": "anthropic/claude-opus-4-5"
}
},
"session": {
- "dm_scope": "per-channel-peer",
- "backlog_limit": 20
+ "dm_scope": "per-channel-peer"
},
"providers": {
"openrouter": {
diff --git a/docs/fr/tools_configuration.md b/docs/fr/tools_configuration.md
index 15573fc30..1324d49e5 100644
--- a/docs/fr/tools_configuration.md
+++ b/docs/fr/tools_configuration.md
@@ -41,14 +41,6 @@ Paramètres généraux pour la récupération et le traitement du contenu des pa
| `fetch_limit_bytes` | int | 10485760 | Taille maximale du contenu de la page web à récupérer, en octets (par défaut 10 Mo). |
| `format` | string | "plaintext" | Format de sortie du contenu récupéré. Options : `plaintext` ou `markdown` (recommandé). |
-### Brave
-
-| Config | Type | Par défaut | Description |
-|---------------|--------|------------|---------------------------|
-| `enabled` | bool | false | Activer la recherche Brave |
-| `api_key` | string | - | Clé API Brave Search |
-| `max_results` | int | 5 | Nombre maximum de résultats |
-
### DuckDuckGo
| Config | Type | Par défaut | Description |
@@ -56,13 +48,73 @@ Paramètres généraux pour la récupération et le traitement du contenu des pa
| `enabled` | bool | true | Activer la recherche DuckDuckGo |
| `max_results` | int | 5 | Nombre maximum de résultats |
+### Baidu Search
+
+| Config | Type | Par défaut | Description |
+|---------------|--------|-----------------------------------------------------------------|------------------------------------|
+| `enabled` | bool | false | Activer la recherche Baidu |
+| `api_key` | string | - | Clé API Qianfan |
+| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL de l'API Baidu Search |
+| `max_results` | int | 10 | Nombre maximum de résultats |
+
+```json
+{
+ "tools": {
+ "web": {
+ "baidu_search": {
+ "enabled": true,
+ "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+ "max_results": 10
+ }
+ }
+ }
+}
+```
+
### Perplexity
| Config | Type | Par défaut | Description |
|---------------|--------|------------|--------------------------------|
-| `enabled` | bool | false | Activer la recherche Perplexity |
-| `api_key` | string | - | Clé API Perplexity |
-| `max_results` | int | 5 | Nombre maximum de résultats |
+| `enabled` | bool | false | Activer la recherche Perplexity |
+| `api_key` | string | - | Clé API Perplexity |
+| `api_keys` | string[] | - | Plusieurs clés API Perplexity pour la rotation (`api_key` prioritaire) |
+| `max_results` | int | 5 | Nombre maximum de résultats |
+
+### Brave
+
+| Config | Type | Par défaut | Description |
+|---------------|--------|------------|---------------------------|
+| `enabled` | bool | false | Activer la recherche Brave |
+| `api_key` | string | - | Clé API Brave Search |
+| `api_keys` | string[] | - | Plusieurs clés API Brave Search pour la rotation (`api_key` prioritaire) |
+| `max_results` | int | 5 | Nombre maximum de résultats |
+
+### Tavily
+
+| Config | Type | Par défaut | Description |
+|---------------|--------|------------|------------------------------------|
+| `enabled` | bool | false | Activer la recherche Tavily |
+| `api_key` | string | - | Clé API Tavily |
+| `base_url` | string | - | URL de base Tavily personnalisée |
+| `max_results` | int | 0 | Nombre maximum de résultats (0 = défaut) |
+
+### SearXNG
+
+| Config | Type | Par défaut | Description |
+|---------------|--------|--------------------------|--------------------------------|
+| `enabled` | bool | false | Activer la recherche SearXNG |
+| `base_url` | string | `http://localhost:8888` | URL de l'instance SearXNG |
+| `max_results` | int | 5 | Nombre maximum de résultats |
+
+### GLM Search
+
+| Config | Type | Par défaut | Description |
+|-----------------|--------|------------------------------------------------------|---------------------------|
+| `enabled` | bool | false | Activer GLM Search |
+| `api_key` | string | - | Clé API GLM |
+| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL de l'API GLM Search |
+| `search_engine` | string | `search_std` | Type de moteur de recherche |
+| `max_results` | int | 5 | Nombre maximum de résultats |
## Outil Exec
@@ -70,9 +122,32 @@ L'outil exec est utilisé pour exécuter des commandes shell.
| Config | Type | Par défaut | Description |
|------------------------|-------|------------|------------------------------------------------|
+| `enabled` | bool | true | Activer l'outil exec |
| `enable_deny_patterns` | bool | true | Activer le blocage par défaut des commandes dangereuses |
| `custom_deny_patterns` | array | [] | Modèles de refus personnalisés (expressions régulières) |
+### Désactivation de l'Outil Exec
+
+Pour désactiver complètement l'outil `exec`, définissez `enabled` à `false` :
+
+**Via le fichier de configuration :**
+```json
+{
+ "tools": {
+ "exec": {
+ "enabled": false
+ }
+ }
+}
+```
+
+**Via la variable d'environnement :**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Note :** Lorsqu'il est désactivé, l'agent ne pourra pas exécuter de commandes shell. Cela affecte également la capacité de l'outil Cron à exécuter des commandes shell planifiées.
+
### Fonctionnalité
- **`enable_deny_patterns`** : Définir à `false` pour désactiver complètement les modèles de blocage par défaut des commandes dangereuses
@@ -329,6 +404,7 @@ Toutes les options de configuration peuvent être remplacées via des variables
Par exemple :
- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
- `PICOCLAW_TOOLS_MCP_ENABLED=true`
diff --git a/docs/fr/troubleshooting.md b/docs/fr/troubleshooting.md
index bfe8901ef..d2d099ad3 100644
--- a/docs/fr/troubleshooting.md
+++ b/docs/fr/troubleshooting.md
@@ -16,7 +16,7 @@
**Correction :** Dans `~/.picoclaw/config.json` (ou votre chemin de configuration) :
-1. **agents.defaults.model** doit correspondre à un `model_name` dans `model_list` (par ex. `"openrouter-free"`).
+1. **agents.defaults.model_name** doit correspondre à un `model_name` dans `model_list` (par ex. `"openrouter-free"`).
2. Le **model** de cette entrée doit être un identifiant de modèle OpenRouter valide, par exemple :
- `"openrouter/free"` – niveau gratuit automatique
- `"google/gemini-2.0-flash-exp:free"`
@@ -28,7 +28,7 @@ Exemple :
{
"agents": {
"defaults": {
- "model": "openrouter-free"
+ "model_name": "openrouter-free"
}
},
"model_list": [
diff --git a/docs/hardware-compatibility.md b/docs/hardware-compatibility.md
new file mode 100644
index 000000000..c11849822
--- /dev/null
+++ b/docs/hardware-compatibility.md
@@ -0,0 +1,150 @@
+# 🖥️ PicoClaw Hardware Compatibility List
+
+PicoClaw runs on virtually any Linux device. This page tracks verified chips, products, and development boards.
+
+**Your hardware not listed?** Submit a PR to add it! Hardware vendors are welcome to contribute and co-promote.
+
+---
+
+## 1. Verified Chip Support
+
+### x86
+
+| Vendor | Chip | Notes |
+|--------|------|-------|
+| Intel | Any x86 CPU (i386+) | All desktop/server/laptop processors |
+| AMD | Any x86 CPU | All desktop/server/laptop processors |
+
+### ARM
+
+| Sub-arch | Typical Chips | Notes |
+|----------|--------------|-------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Single-core ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Single-core Cortex-A7, used in LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Quad-core Cortex-A53, used in Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Quad-core Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Quad-core Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Dual-core Cortex-A53 + NPU, used in NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| Vendor | Chip | Core | Notes |
+|--------|------|------|-------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 on-chip, used in LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L on-chip, 1 TOPS NPU, 4K AI camera SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | RISC-V AI camera series |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Used in HaaS506-LD1 industrial RTU |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Used in Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | RVA23 compliant, 1024-bit RVV, FP8 AI inference |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8-core, 16MB L3 cache, desktop-class |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, used in CanMV-K230 |
+
+### MIPS
+
+| Vendor | Chip | Notes |
+|--------|------|-------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, used in many OpenWrt routers (e.g. Xiaomi Router 3G) |
+
+### LoongArch (loong64)
+
+| Vendor | Chip | Notes |
+|--------|------|-------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Quad-core LA464 @ 2.5GHz, desktop/workstation |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Quad-core 4C/8T @ 2.5GHz, IPC comparable to Intel 10th gen |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Dual-core @ 1GHz, industrial/IoT applications |
+
+---
+
+## 2. Verified Products (by release date)
+
+Consumer products, routers, and industrial devices that have been tested with PicoClaw.
+
+| Year | Product | Arch | SoC | RAM | Category |
+|------|---------|------|-----|-----|----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Smartphone |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Tablet |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Router (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV Box / Home Server |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Smart Speaker |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | Industrial RTU |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | Pro IP-KVM |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | 4K AI Camera |
+
+---
+
+## 3. Verified Development Boards (by release date)
+
+| Year | Board | Arch | SoC | RAM | Buy Link |
+|------|-------|------|-----|-----|----------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. Also Works On
+
+### Android Phones (via Termux)
+
+Any ARM64 Android phone (2015+) with 1GB+ RAM. Install [Termux](https://github.com/termux/termux-app), use `proot` to run PicoClaw.
+
+> See [README: Run on old Android Phones](../README.md#-run-on-old-android-phones) for setup instructions.
+
+### Desktop / Server / Cloud
+
+| Platform | Notes |
+|----------|-------|
+| x86_64 Linux | Native binary, no dependencies |
+| x86_64 Windows | Native binary |
+| macOS (Intel / Apple Silicon) | Native binary |
+| Docker (any platform) | `docker compose` one-liner, see [Docker Guide](docker.md) |
+| OpenWrt routers | MIPS/ARM builds, requires >32MB free RAM |
+| FreeBSD / NetBSD | x86_64 and arm64 builds available |
+
+---
+
+## 5. Minimum Requirements
+
+| Resource | Minimum | Recommended |
+|----------|---------|-------------|
+| RAM | 10MB free | 32MB+ free |
+| Storage | 20MB (binary) | 50MB+ (with workspace) |
+| CPU | Any (single core 0.6GHz+) | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| Network | Required (for LLM API calls) | Ethernet or WiFi |
+
+---
+
+## 6. How to Test & Contribute
+
+```bash
+# 1. Download for your architecture
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. Initialize
+./picoclaw onboard
+
+# 3. Test
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+Available builds: `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### Add Your Hardware
+
+1. Fork this repo
+2. Add your chip / product / board to the appropriate table
+3. Include: name, arch, SoC, RAM, year, and a link if available
+4. Submit a PR
+
+Hardware vendors: want to add official support or co-promote? Open an issue or reach out via [Discord](https://discord.gg/V4sAZ9XWpN).
diff --git a/docs/hooks/README.md b/docs/hooks/README.md
new file mode 100644
index 000000000..ec3bbc46a
--- /dev/null
+++ b/docs/hooks/README.md
@@ -0,0 +1,679 @@
+# Hook System Guide
+
+This document describes the hook system that is implemented in the current repository, not the older design draft.
+
+The current implementation supports two mounting modes:
+
+1. In-process hooks
+2. Out-of-process process hooks (`JSON-RPC over stdio`)
+
+The repository no longer ships standalone example source files. The Go and Python examples below are embedded directly in this document. If you want to use them, copy them into your own local files first.
+
+## Supported Hook Types
+
+| Type | Interface | Stage | Can modify data |
+| --- | --- | --- | --- |
+| Observer | `EventObserver` | EventBus broadcast | No |
+| LLM interceptor | `LLMInterceptor` | `before_llm` / `after_llm` | Yes |
+| Tool interceptor | `ToolInterceptor` | `before_tool` / `after_tool` | Yes |
+| Tool approver | `ToolApprover` | `approve_tool` | No, returns allow/deny |
+
+The currently exposed synchronous hook points are:
+
+- `before_llm`
+- `after_llm`
+- `before_tool`
+- `after_tool`
+- `approve_tool`
+
+Everything else is exposed as read-only events.
+
+## Execution Order
+
+`HookManager` sorts hooks like this:
+
+1. In-process hooks first
+2. Process hooks second
+3. Lower `priority` first within the same source
+4. Name order as the final tie-breaker
+
+## Timeouts
+
+Global defaults live under `hooks.defaults`:
+
+- `observer_timeout_ms`
+- `interceptor_timeout_ms`
+- `approval_timeout_ms`
+
+Note: the current implementation does not support per-process-hook `timeout_ms`. Timeouts are global defaults.
+
+## Quick Start
+
+If your first goal is simply to prove that the hook flow works and observe real requests, the easiest path is the Python process-hook example below:
+
+1. Enable `hooks.enabled`
+2. Save the Python example from this document to a local file, for example `/tmp/review_gate.py`
+3. Set `PICOCLAW_HOOK_LOG_FILE`
+4. Restart the gateway
+5. Watch the log file with `tail -f`
+
+Example:
+
+```json
+{
+ "hooks": {
+ "enabled": true,
+ "processes": {
+ "py_review_gate": {
+ "enabled": true,
+ "priority": 100,
+ "transport": "stdio",
+ "command": [
+ "python3",
+ "/tmp/review_gate.py"
+ ],
+ "observe": [
+ "tool_exec_start",
+ "tool_exec_end",
+ "tool_exec_skipped"
+ ],
+ "intercept": [
+ "before_tool",
+ "approve_tool"
+ ],
+ "env": {
+ "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
+ }
+ }
+ }
+ }
+}
+```
+
+Watch it with:
+
+```bash
+tail -f /tmp/picoclaw-hook-review-gate.log
+```
+
+If you are developing PicoClaw itself rather than only validating the protocol, continue with the Go in-process example as well.
+
+## What The Two Examples Are For
+
+- Go in-process example
+ Best for validating the host-side hook chain and understanding `MountHook()` plus the synchronous stages
+- Python process example
+ Best for understanding the `JSON-RPC over stdio` protocol and verifying the message flow between PicoClaw and an external process
+
+Both examples are intentionally safe: they only log, never rewrite, and never deny.
+
+## Go In-Process Example
+
+The following is a minimal logging hook for in-process use. It implements:
+
+1. `EventObserver`
+2. `LLMInterceptor`
+3. `ToolInterceptor`
+4. `ToolApprover`
+
+It only records activity. It does not rewrite requests or reject tools.
+
+You can save it as your own Go file, for example `pkg/myhooks/example_logger.go`:
+
+```go
+package myhooks
+
+import (
+ "context"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/agent"
+ "github.com/sipeed/picoclaw/pkg/logger"
+)
+
+type ExampleLoggerHookOptions struct {
+ LogFile string `json:"log_file,omitempty"`
+ LogEvents bool `json:"log_events,omitempty"`
+}
+
+type ExampleLoggerHook struct {
+ logFile string
+ logEvents bool
+ mu sync.Mutex
+}
+
+func NewExampleLoggerHook(opts ExampleLoggerHookOptions) *ExampleLoggerHook {
+ return &ExampleLoggerHook{
+ logFile: strings.TrimSpace(opts.LogFile),
+ logEvents: opts.LogEvents,
+ }
+}
+
+func (h *ExampleLoggerHook) OnEvent(ctx context.Context, evt agent.Event) error {
+ _ = ctx
+ if h == nil || !h.logEvents {
+ return nil
+ }
+ h.record("event", evt.Meta, map[string]any{
+ "event": evt.Kind.String(),
+ "payload": evt.Payload,
+ }, nil)
+ return nil
+}
+
+func (h *ExampleLoggerHook) BeforeLLM(
+ ctx context.Context,
+ req *agent.LLMHookRequest,
+) (*agent.LLMHookRequest, agent.HookDecision, error) {
+ _ = ctx
+ h.record("before_llm", req.Meta, req, agent.HookDecision{Action: agent.HookActionContinue})
+ return req, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) AfterLLM(
+ ctx context.Context,
+ resp *agent.LLMHookResponse,
+) (*agent.LLMHookResponse, agent.HookDecision, error) {
+ _ = ctx
+ h.record("after_llm", resp.Meta, resp, agent.HookDecision{Action: agent.HookActionContinue})
+ return resp, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) BeforeTool(
+ ctx context.Context,
+ call *agent.ToolCallHookRequest,
+) (*agent.ToolCallHookRequest, agent.HookDecision, error) {
+ _ = ctx
+ h.record("before_tool", call.Meta, call, agent.HookDecision{Action: agent.HookActionContinue})
+ return call, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) AfterTool(
+ ctx context.Context,
+ result *agent.ToolResultHookResponse,
+) (*agent.ToolResultHookResponse, agent.HookDecision, error) {
+ _ = ctx
+ h.record("after_tool", result.Meta, result, agent.HookDecision{Action: agent.HookActionContinue})
+ return result, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) ApproveTool(
+ ctx context.Context,
+ req *agent.ToolApprovalRequest,
+) (agent.ApprovalDecision, error) {
+ _ = ctx
+ decision := agent.ApprovalDecision{Approved: true}
+ h.record("approve_tool", req.Meta, req, decision)
+ return decision, nil
+}
+
+func (h *ExampleLoggerHook) record(stage string, meta agent.EventMeta, payload any, decision any) {
+ logger.InfoCF("hooks", "Example hook observed", map[string]any{
+ "stage": stage,
+ })
+ if h == nil || h.logFile == "" {
+ return
+ }
+
+ entry := map[string]any{
+ "ts": time.Now().UTC(),
+ "stage": stage,
+ "meta": meta,
+ "payload": payload,
+ "decision": decision,
+ }
+
+ body, err := json.Marshal(entry)
+ if err != nil {
+ logger.WarnCF("hooks", "Example hook log encode failed", map[string]any{
+ "stage": stage,
+ "error": err.Error(),
+ })
+ return
+ }
+
+ h.mu.Lock()
+ defer h.mu.Unlock()
+
+ if dir := filepath.Dir(h.logFile); dir != "" && dir != "." {
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ logger.WarnCF("hooks", "Example hook log mkdir failed", map[string]any{
+ "stage": stage,
+ "path": h.logFile,
+ "error": err.Error(),
+ })
+ return
+ }
+ }
+
+ file, err := os.OpenFile(h.logFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+ if err != nil {
+ logger.WarnCF("hooks", "Example hook log open failed", map[string]any{
+ "stage": stage,
+ "path": h.logFile,
+ "error": err.Error(),
+ })
+ return
+ }
+ defer func() { _ = file.Close() }()
+
+ if _, err := file.Write(append(body, '\n')); err != nil {
+ logger.WarnCF("hooks", "Example hook log write failed", map[string]any{
+ "stage": stage,
+ "path": h.logFile,
+ "error": err.Error(),
+ })
+ }
+}
+```
+
+### Mounting It In Code
+
+If code mounting is enough, call this after `AgentLoop` is initialized:
+
+```go
+hook := myhooks.NewExampleLoggerHook(myhooks.ExampleLoggerHookOptions{
+ LogFile: "/tmp/picoclaw-hook-example-logger.log",
+ LogEvents: true,
+})
+
+if err := al.MountHook(agent.NamedHook("example-logger", hook)); err != nil {
+ panic(err)
+}
+```
+
+### If You Also Want Config Mounting
+
+The hook system supports builtin hooks, but that requires you to compile the factory into your binary. In practice, that means you need registration code like this alongside the hook definition above:
+
+```go
+package myhooks
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+
+ "github.com/sipeed/picoclaw/pkg/agent"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+ if err := agent.RegisterBuiltinHook("example_logger", func(
+ ctx context.Context,
+ spec config.BuiltinHookConfig,
+ ) (any, error) {
+ _ = ctx
+
+ var opts ExampleLoggerHookOptions
+ if len(spec.Config) > 0 {
+ if err := json.Unmarshal(spec.Config, &opts); err != nil {
+ return nil, fmt.Errorf("decode example_logger config: %w", err)
+ }
+ }
+ return NewExampleLoggerHook(opts), nil
+ }); err != nil {
+ panic(err)
+ }
+}
+```
+
+Only after you register that builtin will the following config work:
+
+```json
+{
+ "hooks": {
+ "enabled": true,
+ "builtins": {
+ "example_logger": {
+ "enabled": true,
+ "priority": 10,
+ "config": {
+ "log_file": "/tmp/picoclaw-hook-example-logger.log",
+ "log_events": true
+ }
+ }
+ }
+ }
+}
+```
+
+### How To Observe It
+
+- If `log_file` is set, each hook call is appended as JSON Lines
+- If `log_file` is not set, the hook still writes summaries to the gateway log
+- Requests that only hit the LLM path usually show `before_llm` and `after_llm`
+- Requests that trigger tools usually also show `before_tool`, `approve_tool`, and `after_tool`
+- If `log_events=true`, you will also see `event`
+
+Typical log lines:
+
+```json
+{"ts":"2026-03-21T14:10:00Z","stage":"before_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"action":"continue"}}
+{"ts":"2026-03-21T14:10:00Z","stage":"approve_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"approved":true}}
+```
+
+If you only see `before_llm` and `after_llm`, that usually means the request did not trigger any tool call, not that the hook failed to mount.
+
+## Python Process-Hook Example
+
+The following script is a minimal process-hook example. It uses only the Python standard library and supports:
+
+1. `hook.hello`
+2. `hook.event`
+3. `hook.before_tool`
+4. `hook.approve_tool`
+
+It only records activity. It does not rewrite or deny anything.
+
+Save it to any local path, for example `/tmp/review_gate.py`:
+
+```python
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import signal
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+LOG_EVENTS = os.getenv("PICOCLAW_HOOK_LOG_EVENTS", "1").lower() not in {"0", "false", "no"}
+LOG_FILE = os.getenv("PICOCLAW_HOOK_LOG_FILE", "").strip()
+
+
+def append_log(entry: dict[str, Any]) -> None:
+ if not LOG_FILE:
+ return
+
+ payload = {
+ "ts": datetime.now(timezone.utc).isoformat(),
+ **entry,
+ }
+ try:
+ log_dir = os.path.dirname(LOG_FILE)
+ if log_dir:
+ os.makedirs(log_dir, exist_ok=True)
+ with open(LOG_FILE, "a", encoding="utf-8") as handle:
+ handle.write(json.dumps(payload, ensure_ascii=True) + "\n")
+ except OSError as exc:
+ log_stderr(f"failed to write hook log file {LOG_FILE}: {exc}")
+
+
+def send_response(message_id: int, result: Any | None = None, error: str | None = None) -> None:
+ payload: dict[str, Any] = {
+ "jsonrpc": "2.0",
+ "id": message_id,
+ }
+ if error is not None:
+ payload["error"] = {"code": -32000, "message": error}
+ else:
+ payload["result"] = result if result is not None else {}
+
+ append_log({
+ "direction": "out",
+ "id": message_id,
+ "response": payload.get("result"),
+ "error": payload.get("error"),
+ })
+
+ try:
+ sys.stdout.write(json.dumps(payload, ensure_ascii=True) + "\n")
+ sys.stdout.flush()
+ except BrokenPipeError:
+ raise SystemExit(0) from None
+
+
+def log_stderr(message: str) -> None:
+ try:
+ sys.stderr.write(message + "\n")
+ sys.stderr.flush()
+ except BrokenPipeError:
+ raise SystemExit(0) from None
+
+
+def handle_shutdown_signal(signum: int, _frame: Any) -> None:
+ raise KeyboardInterrupt(f"received signal {signum}")
+
+
+def handle_before_tool(params: dict[str, Any]) -> dict[str, Any]:
+ _ = params
+ return {"action": "continue"}
+
+
+def handle_approve_tool(params: dict[str, Any]) -> dict[str, Any]:
+ _ = params
+ return {"approved": True}
+
+
+def handle_request(method: str, params: dict[str, Any]) -> dict[str, Any]:
+ if method == "hook.hello":
+ return {"ok": True, "name": "python-review-gate"}
+ if method == "hook.before_tool":
+ return handle_before_tool(params)
+ if method == "hook.approve_tool":
+ return handle_approve_tool(params)
+ if method == "hook.before_llm":
+ return {"action": "continue"}
+ if method == "hook.after_llm":
+ return {"action": "continue"}
+ if method == "hook.after_tool":
+ return {"action": "continue"}
+ raise KeyError(f"method not found: {method}")
+
+
+def main() -> int:
+ try:
+ for raw_line in sys.stdin:
+ line = raw_line.strip()
+ if not line:
+ continue
+
+ try:
+ message = json.loads(line)
+ except json.JSONDecodeError as exc:
+ log_stderr(f"failed to decode request: {exc}")
+ append_log({
+ "direction": "in",
+ "decode_error": str(exc),
+ "raw": line,
+ })
+ continue
+
+ method = message.get("method")
+ message_id = message.get("id", 0)
+ params = message.get("params") or {}
+ if not isinstance(params, dict):
+ params = {}
+
+ append_log({
+ "direction": "in",
+ "id": message_id,
+ "method": method,
+ "params": params,
+ "notification": not bool(message_id),
+ })
+
+ if not message_id:
+ if method == "hook.event" and LOG_EVENTS:
+ log_stderr(f"observed event: {params.get('Kind')}")
+ continue
+
+ try:
+ result = handle_request(str(method or ""), params)
+ except KeyError as exc:
+ send_response(int(message_id), error=str(exc))
+ continue
+ except Exception as exc:
+ send_response(int(message_id), error=f"unexpected error: {exc}")
+ continue
+
+ send_response(int(message_id), result=result)
+ except KeyboardInterrupt:
+ return 0
+
+ return 0
+
+
+if __name__ == "__main__":
+ signal.signal(signal.SIGINT, handle_shutdown_signal)
+ signal.signal(signal.SIGTERM, handle_shutdown_signal)
+ raise SystemExit(main())
+```
+
+### Configuration
+
+```json
+{
+ "hooks": {
+ "enabled": true,
+ "processes": {
+ "py_review_gate": {
+ "enabled": true,
+ "priority": 100,
+ "transport": "stdio",
+ "command": [
+ "python3",
+ "/abs/path/to/review_gate.py"
+ ],
+ "observe": [
+ "tool_exec_start",
+ "tool_exec_end",
+ "tool_exec_skipped"
+ ],
+ "intercept": [
+ "before_tool",
+ "approve_tool"
+ ],
+ "env": {
+ "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
+ }
+ }
+ }
+ }
+}
+```
+
+### Environment Variables
+
+- `PICOCLAW_HOOK_LOG_EVENTS`
+ Whether to write `hook.event` summaries to `stderr`, enabled by default
+- `PICOCLAW_HOOK_LOG_FILE`
+ Path to an external log file. When set, the script appends inbound hook requests, notifications, and outbound responses as JSON Lines
+
+Note: `PICOCLAW_HOOK_LOG_FILE` has no default. If you do not set it, the script does not write any file logs.
+
+### How To Confirm It Received Hooks
+
+Watch two places:
+
+- Gateway logs
+ Useful for confirming that the host successfully started the process and for seeing event summaries written to `stderr`
+- `PICOCLAW_HOOK_LOG_FILE`
+ Useful for seeing the exact requests the script received and the exact responses it returned
+
+Typical interpretation:
+
+- Only `hook.hello`
+ The process started and completed the handshake, but no business hook request has arrived yet
+- `hook.event`
+ The `observe` configuration is working
+- `hook.before_tool`
+ The `intercept: ["before_tool", ...]` configuration is working
+- `hook.approve_tool`
+ The approval hook path is working
+
+Because this example never rewrites or denies, the expected responses look like:
+
+```json
+{"direction":"out","id":7,"response":{"action":"continue"},"error":null}
+{"direction":"out","id":8,"response":{"approved":true},"error":null}
+```
+
+A complete sample:
+
+```json
+{"ts":"2026-03-21T14:12:00+00:00","direction":"in","id":1,"method":"hook.hello","params":{"name":"py_review_gate","version":1,"modes":["observe","tool","approve"]},"notification":false}
+{"ts":"2026-03-21T14:12:00+00:00","direction":"out","id":1,"response":{"ok":true,"name":"python-review-gate"},"error":null}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":0,"method":"hook.event","params":{"Kind":"tool_exec_start"},"notification":true}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":7,"method":"hook.before_tool","params":{"tool":"echo_text","arguments":{"text":"hello"}},"notification":false}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"out","id":7,"response":{"action":"continue"},"error":null}
+```
+
+Additional notes:
+
+- Timestamps are UTC
+- `notification=true` means it was a notification such as `hook.event`, which does not expect a response
+- `id` increases within a single hook process; if the process restarts, the counter starts over
+
+## Process-Hook Protocol
+
+Current process hooks use `JSON-RPC over stdio`:
+
+- PicoClaw starts the external process
+- Requests and responses are exchanged as one JSON message per line
+- `hook.event` is a notification and does not need a response
+- `hook.before_llm`, `hook.after_llm`, `hook.before_tool`, `hook.after_tool`, and `hook.approve_tool` are request/response calls
+
+The host does not currently accept new RPCs initiated by the process hook. In practice, that means an external hook can only respond to PicoClaw calls; it cannot call back into the host to send channel messages.
+
+## Configuration Fields
+
+### `hooks.builtins.`
+
+- `enabled`
+- `priority`
+- `config`
+
+### `hooks.processes.`
+
+- `enabled`
+- `priority`
+- `transport`
+ Currently only `stdio` is supported
+- `command`
+- `dir`
+- `env`
+- `observe`
+- `intercept`
+
+## Troubleshooting
+
+If a hook looks like it is not firing, check these in order:
+
+1. `hooks.enabled`
+2. Whether the target builtin or process hook is `enabled`
+3. Whether the process-hook `command` path is correct
+4. Whether you are watching the correct log file
+5. Whether the current request actually reached the stage you care about
+6. Whether `observe` or `intercept` contains the hook point you want
+
+A practical minimal troubleshooting pair is:
+
+- Use the Python process-hook example from this document to validate the external protocol
+- Use the Go in-process example from this document to validate the host-side chain
+
+If the Python side shows `hook.hello` but no business hook requests, the protocol is usually fine; the current request simply did not trigger the stage you expected.
+
+## Scope And Limits
+
+The current hook system is best suited for:
+
+- LLM request rewriting
+- Tool argument normalization
+- Pre-execution tool approval
+- Auditing and observability
+
+It is not yet well suited for:
+
+- External hooks actively sending channel messages
+- Suspending a turn and waiting for human approval replies
+- Full inbound/outbound message interception across the whole platform
+
+If you want a real human approval workflow, use hooks as the approval entry point and keep the state machine plus channel interaction in a separate `ApprovalManager`.
diff --git a/docs/hooks/README.zh.md b/docs/hooks/README.zh.md
new file mode 100644
index 000000000..46c7c9392
--- /dev/null
+++ b/docs/hooks/README.zh.md
@@ -0,0 +1,679 @@
+# Hook 系统使用说明
+
+这份文档对应当前仓库里已经实现的 hook 系统，而不是设计草案。
+
+当前实现支持两类挂载方式：
+
+1. 进程内 hook
+2. 进程外 process hook（`JSON-RPC over stdio`）
+
+当前仓库不再内置示例代码文件。下面的 Go / Python 示例都直接写在本文档里；如果你要使用它们，需要先复制到你自己的文件路径。
+
+## 支持的 hook 类型
+
+| 类型 | 接口 | 作用阶段 | 能否改写 |
+| --- | --- | --- | --- |
+| 观察型 | `EventObserver` | EventBus 广播事件时 | 否 |
+| LLM 拦截型 | `LLMInterceptor` | `before_llm` / `after_llm` | 是 |
+| Tool 拦截型 | `ToolInterceptor` | `before_tool` / `after_tool` | 是 |
+| Tool 审批型 | `ToolApprover` | `approve_tool` | 否，返回批准/拒绝 |
+
+当前公开的同步点位只有：
+
+- `before_llm`
+- `after_llm`
+- `before_tool`
+- `after_tool`
+- `approve_tool`
+
+其余 lifecycle 通过事件形式只读暴露。
+
+## 执行顺序
+
+HookManager 的排序规则是：
+
+1. 先执行进程内 hook
+2. 再执行 process hook
+3. 同一来源内按 `priority` 从小到大
+4. 若 `priority` 相同，再按名字排序
+
+## 超时
+
+当前配置在 `hooks.defaults` 中统一设置：
+
+- `observer_timeout_ms`
+- `interceptor_timeout_ms`
+- `approval_timeout_ms`
+
+注意：当前实现还没有单个 process hook 自己的 `timeout_ms` 字段，超时配置是全局默认值。
+
+## 快速开始
+
+如果你的目标只是先把当前 hook 流程跑通并观察到实际请求，最省事的是先用下面的 Python process hook 示例：
+
+1. 打开 `hooks.enabled`
+2. 把下面文档里的 Python 示例保存到本地文件，例如 `/tmp/review_gate.py`
+3. 给它配置 `PICOCLAW_HOOK_LOG_FILE`
+4. 重启 gateway
+5. 用 `tail -f` 观察日志文件
+
+例如：
+
+```json
+{
+ "hooks": {
+ "enabled": true,
+ "processes": {
+ "py_review_gate": {
+ "enabled": true,
+ "priority": 100,
+ "transport": "stdio",
+ "command": [
+ "python3",
+ "/tmp/review_gate.py"
+ ],
+ "observe": [
+ "tool_exec_start",
+ "tool_exec_end",
+ "tool_exec_skipped"
+ ],
+ "intercept": [
+ "before_tool",
+ "approve_tool"
+ ],
+ "env": {
+ "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
+ }
+ }
+ }
+ }
+}
+```
+
+观察方式：
+
+```bash
+tail -f /tmp/picoclaw-hook-review-gate.log
+```
+
+如果你是在开发 PicoClaw 本体，而不是只想验证协议，那么再看后面的 Go in-process 示例。
+
+## 两个示例的定位
+
+- Go in-process 示例
+ 适合验证宿主内的 hook 链路、理解 `MountHook()` 和各个同步点位
+- Python process 示例
+ 适合理解 `JSON-RPC over stdio` 协议、确认宿主和外部进程之间的消息来回是否正常
+
+这两个示例都刻意保持为“只记录、不改写、不拒绝”的安全模式。它们的目的不是提供策略能力，而是帮你观察当前 hook 系统。
+
+## Go 进程内示例
+
+下面这段代码是一个最小的“记录型” in-process hook。它实现了：
+
+1. `EventObserver`
+2. `LLMInterceptor`
+3. `ToolInterceptor`
+4. `ToolApprover`
+
+它只记录，不改写请求，也不拒绝工具。
+
+你可以把它保存成你自己的 Go 文件，例如 `pkg/myhooks/example_logger.go`：
+
+```go
+package myhooks
+
+import (
+ "context"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/agent"
+ "github.com/sipeed/picoclaw/pkg/logger"
+)
+
+type ExampleLoggerHookOptions struct {
+ LogFile string `json:"log_file,omitempty"`
+ LogEvents bool `json:"log_events,omitempty"`
+}
+
+type ExampleLoggerHook struct {
+ logFile string
+ logEvents bool
+ mu sync.Mutex
+}
+
+func NewExampleLoggerHook(opts ExampleLoggerHookOptions) *ExampleLoggerHook {
+ return &ExampleLoggerHook{
+ logFile: strings.TrimSpace(opts.LogFile),
+ logEvents: opts.LogEvents,
+ }
+}
+
+func (h *ExampleLoggerHook) OnEvent(ctx context.Context, evt agent.Event) error {
+ _ = ctx
+ if h == nil || !h.logEvents {
+ return nil
+ }
+ h.record("event", evt.Meta, map[string]any{
+ "event": evt.Kind.String(),
+ "payload": evt.Payload,
+ }, nil)
+ return nil
+}
+
+func (h *ExampleLoggerHook) BeforeLLM(
+ ctx context.Context,
+ req *agent.LLMHookRequest,
+) (*agent.LLMHookRequest, agent.HookDecision, error) {
+ _ = ctx
+ h.record("before_llm", req.Meta, req, agent.HookDecision{Action: agent.HookActionContinue})
+ return req, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) AfterLLM(
+ ctx context.Context,
+ resp *agent.LLMHookResponse,
+) (*agent.LLMHookResponse, agent.HookDecision, error) {
+ _ = ctx
+ h.record("after_llm", resp.Meta, resp, agent.HookDecision{Action: agent.HookActionContinue})
+ return resp, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) BeforeTool(
+ ctx context.Context,
+ call *agent.ToolCallHookRequest,
+) (*agent.ToolCallHookRequest, agent.HookDecision, error) {
+ _ = ctx
+ h.record("before_tool", call.Meta, call, agent.HookDecision{Action: agent.HookActionContinue})
+ return call, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) AfterTool(
+ ctx context.Context,
+ result *agent.ToolResultHookResponse,
+) (*agent.ToolResultHookResponse, agent.HookDecision, error) {
+ _ = ctx
+ h.record("after_tool", result.Meta, result, agent.HookDecision{Action: agent.HookActionContinue})
+ return result, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) ApproveTool(
+ ctx context.Context,
+ req *agent.ToolApprovalRequest,
+) (agent.ApprovalDecision, error) {
+ _ = ctx
+ decision := agent.ApprovalDecision{Approved: true}
+ h.record("approve_tool", req.Meta, req, decision)
+ return decision, nil
+}
+
+func (h *ExampleLoggerHook) record(stage string, meta agent.EventMeta, payload any, decision any) {
+ logger.InfoCF("hooks", "Example hook observed", map[string]any{
+ "stage": stage,
+ })
+ if h == nil || h.logFile == "" {
+ return
+ }
+
+ entry := map[string]any{
+ "ts": time.Now().UTC(),
+ "stage": stage,
+ "meta": meta,
+ "payload": payload,
+ "decision": decision,
+ }
+
+ body, err := json.Marshal(entry)
+ if err != nil {
+ logger.WarnCF("hooks", "Example hook log encode failed", map[string]any{
+ "stage": stage,
+ "error": err.Error(),
+ })
+ return
+ }
+
+ h.mu.Lock()
+ defer h.mu.Unlock()
+
+ if dir := filepath.Dir(h.logFile); dir != "" && dir != "." {
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ logger.WarnCF("hooks", "Example hook log mkdir failed", map[string]any{
+ "stage": stage,
+ "path": h.logFile,
+ "error": err.Error(),
+ })
+ return
+ }
+ }
+
+ file, err := os.OpenFile(h.logFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+ if err != nil {
+ logger.WarnCF("hooks", "Example hook log open failed", map[string]any{
+ "stage": stage,
+ "path": h.logFile,
+ "error": err.Error(),
+ })
+ return
+ }
+ defer func() { _ = file.Close() }()
+
+ if _, err := file.Write(append(body, '\n')); err != nil {
+ logger.WarnCF("hooks", "Example hook log write failed", map[string]any{
+ "stage": stage,
+ "path": h.logFile,
+ "error": err.Error(),
+ })
+ }
+}
+```
+
+### 如何挂载
+
+如果你只需要代码挂载，直接在 `AgentLoop` 初始化后调用：
+
+```go
+hook := myhooks.NewExampleLoggerHook(myhooks.ExampleLoggerHookOptions{
+ LogFile: "/tmp/picoclaw-hook-example-logger.log",
+ LogEvents: true,
+})
+
+if err := al.MountHook(agent.NamedHook("example-logger", hook)); err != nil {
+ panic(err)
+}
+```
+
+### 如果你还想用配置挂载
+
+当前 hook 系统支持 builtin hook，但这要求你自己把 factory 编进二进制。也就是说，下面这段注册代码需要和上面的 hook 定义一起放进你的工程里：
+
+```go
+package myhooks
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+
+ "github.com/sipeed/picoclaw/pkg/agent"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+ if err := agent.RegisterBuiltinHook("example_logger", func(
+ ctx context.Context,
+ spec config.BuiltinHookConfig,
+ ) (any, error) {
+ _ = ctx
+
+ var opts ExampleLoggerHookOptions
+ if len(spec.Config) > 0 {
+ if err := json.Unmarshal(spec.Config, &opts); err != nil {
+ return nil, fmt.Errorf("decode example_logger config: %w", err)
+ }
+ }
+ return NewExampleLoggerHook(opts), nil
+ }); err != nil {
+ panic(err)
+ }
+}
+```
+
+只有在你自己注册了 builtin 之后，下面的配置才会生效：
+
+```json
+{
+ "hooks": {
+ "enabled": true,
+ "builtins": {
+ "example_logger": {
+ "enabled": true,
+ "priority": 10,
+ "config": {
+ "log_file": "/tmp/picoclaw-hook-example-logger.log",
+ "log_events": true
+ }
+ }
+ }
+ }
+}
+```
+
+### 如何观察它是否生效
+
+- 如果设置了 `log_file`，它会把每次 hook 调用按 JSON Lines 写入文件
+- 如果没有设置 `log_file`，它仍然会把摘要写到 gateway 日志
+- 普通只走 LLM 的请求，通常会看到 `before_llm` 和 `after_llm`
+- 触发工具调用的请求，通常还会看到 `before_tool`、`approve_tool`、`after_tool`
+- 如果 `log_events=true`，还会额外看到 `event`
+
+典型日志：
+
+```json
+{"ts":"2026-03-21T14:10:00Z","stage":"before_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"action":"continue"}}
+{"ts":"2026-03-21T14:10:00Z","stage":"approve_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"approved":true}}
+```
+
+如果你只看到了 `before_llm` / `after_llm`，没有看到 tool 相关阶段，通常不是 hook 没挂上，而是这次请求本身没有触发工具调用。
+
+## Python process hook 示例
+
+下面这段脚本是一个最小的 `process hook` 示例。它只使用 Python 标准库，支持：
+
+1. `hook.hello`
+2. `hook.event`
+3. `hook.before_tool`
+4. `hook.approve_tool`
+
+它默认只记录，不改写，也不拒绝。
+
+你可以把它保存到任意本地路径，例如 `/tmp/review_gate.py`：
+
+```python
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import signal
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+LOG_EVENTS = os.getenv("PICOCLAW_HOOK_LOG_EVENTS", "1").lower() not in {"0", "false", "no"}
+LOG_FILE = os.getenv("PICOCLAW_HOOK_LOG_FILE", "").strip()
+
+
+def append_log(entry: dict[str, Any]) -> None:
+ if not LOG_FILE:
+ return
+
+ payload = {
+ "ts": datetime.now(timezone.utc).isoformat(),
+ **entry,
+ }
+ try:
+ log_dir = os.path.dirname(LOG_FILE)
+ if log_dir:
+ os.makedirs(log_dir, exist_ok=True)
+ with open(LOG_FILE, "a", encoding="utf-8") as handle:
+ handle.write(json.dumps(payload, ensure_ascii=True) + "\n")
+ except OSError as exc:
+ log_stderr(f"failed to write hook log file {LOG_FILE}: {exc}")
+
+
+def send_response(message_id: int, result: Any | None = None, error: str | None = None) -> None:
+ payload: dict[str, Any] = {
+ "jsonrpc": "2.0",
+ "id": message_id,
+ }
+ if error is not None:
+ payload["error"] = {"code": -32000, "message": error}
+ else:
+ payload["result"] = result if result is not None else {}
+
+ append_log({
+ "direction": "out",
+ "id": message_id,
+ "response": payload.get("result"),
+ "error": payload.get("error"),
+ })
+
+ try:
+ sys.stdout.write(json.dumps(payload, ensure_ascii=True) + "\n")
+ sys.stdout.flush()
+ except BrokenPipeError:
+ raise SystemExit(0) from None
+
+
+def log_stderr(message: str) -> None:
+ try:
+ sys.stderr.write(message + "\n")
+ sys.stderr.flush()
+ except BrokenPipeError:
+ raise SystemExit(0) from None
+
+
+def handle_shutdown_signal(signum: int, _frame: Any) -> None:
+ raise KeyboardInterrupt(f"received signal {signum}")
+
+
+def handle_before_tool(params: dict[str, Any]) -> dict[str, Any]:
+ _ = params
+ return {"action": "continue"}
+
+
+def handle_approve_tool(params: dict[str, Any]) -> dict[str, Any]:
+ _ = params
+ return {"approved": True}
+
+
+def handle_request(method: str, params: dict[str, Any]) -> dict[str, Any]:
+ if method == "hook.hello":
+ return {"ok": True, "name": "python-review-gate"}
+ if method == "hook.before_tool":
+ return handle_before_tool(params)
+ if method == "hook.approve_tool":
+ return handle_approve_tool(params)
+ if method == "hook.before_llm":
+ return {"action": "continue"}
+ if method == "hook.after_llm":
+ return {"action": "continue"}
+ if method == "hook.after_tool":
+ return {"action": "continue"}
+ raise KeyError(f"method not found: {method}")
+
+
+def main() -> int:
+ try:
+ for raw_line in sys.stdin:
+ line = raw_line.strip()
+ if not line:
+ continue
+
+ try:
+ message = json.loads(line)
+ except json.JSONDecodeError as exc:
+ log_stderr(f"failed to decode request: {exc}")
+ append_log({
+ "direction": "in",
+ "decode_error": str(exc),
+ "raw": line,
+ })
+ continue
+
+ method = message.get("method")
+ message_id = message.get("id", 0)
+ params = message.get("params") or {}
+ if not isinstance(params, dict):
+ params = {}
+
+ append_log({
+ "direction": "in",
+ "id": message_id,
+ "method": method,
+ "params": params,
+ "notification": not bool(message_id),
+ })
+
+ if not message_id:
+ if method == "hook.event" and LOG_EVENTS:
+ log_stderr(f"observed event: {params.get('Kind')}")
+ continue
+
+ try:
+ result = handle_request(str(method or ""), params)
+ except KeyError as exc:
+ send_response(int(message_id), error=str(exc))
+ continue
+ except Exception as exc:
+ send_response(int(message_id), error=f"unexpected error: {exc}")
+ continue
+
+ send_response(int(message_id), result=result)
+ except KeyboardInterrupt:
+ return 0
+
+ return 0
+
+
+if __name__ == "__main__":
+ signal.signal(signal.SIGINT, handle_shutdown_signal)
+ signal.signal(signal.SIGTERM, handle_shutdown_signal)
+ raise SystemExit(main())
+```
+
+### 如何配置
+
+```json
+{
+ "hooks": {
+ "enabled": true,
+ "processes": {
+ "py_review_gate": {
+ "enabled": true,
+ "priority": 100,
+ "transport": "stdio",
+ "command": [
+ "python3",
+ "/abs/path/to/review_gate.py"
+ ],
+ "observe": [
+ "tool_exec_start",
+ "tool_exec_end",
+ "tool_exec_skipped"
+ ],
+ "intercept": [
+ "before_tool",
+ "approve_tool"
+ ],
+ "env": {
+ "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
+ }
+ }
+ }
+ }
+}
+```
+
+### 环境变量
+
+- `PICOCLAW_HOOK_LOG_EVENTS`
+ 是否把 `hook.event` 写到 `stderr`，默认开启
+- `PICOCLAW_HOOK_LOG_FILE`
+ 外部日志文件路径。设置后，脚本会把收到的 hook 请求、notification 和返回结果按 JSON Lines 追加到该文件
+
+注意：`PICOCLAW_HOOK_LOG_FILE` 没有默认值。不设置时，脚本不会自动落盘日志。
+
+### 如何确认它收到了 hook
+
+推荐同时看两个地方：
+
+- gateway 日志
+ 用来观察宿主是否成功启动了外部进程，以及脚本写到 `stderr` 的事件摘要
+- `PICOCLAW_HOOK_LOG_FILE`
+ 用来观察脚本实际收到了什么请求、返回了什么响应
+
+典型判断方式：
+
+- 只看到 `hook.hello`
+ 说明进程启动并完成握手了，但还没有新的业务 hook 请求真正打进来
+- 看到 `hook.event`
+ 说明 `observe` 配置生效了
+- 看到 `hook.before_tool`
+ 说明 `intercept: ["before_tool", ...]` 生效了
+- 看到 `hook.approve_tool`
+ 说明审批 hook 生效了
+
+这份示例脚本不会改写任何参数，也不会拒绝工具，所以你应该看到的典型返回是：
+
+```json
+{"direction":"out","id":7,"response":{"action":"continue"},"error":null}
+{"direction":"out","id":8,"response":{"approved":true},"error":null}
+```
+
+一组完整样例：
+
+```json
+{"ts":"2026-03-21T14:12:00+00:00","direction":"in","id":1,"method":"hook.hello","params":{"name":"py_review_gate","version":1,"modes":["observe","tool","approve"]},"notification":false}
+{"ts":"2026-03-21T14:12:00+00:00","direction":"out","id":1,"response":{"ok":true,"name":"python-review-gate"},"error":null}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":0,"method":"hook.event","params":{"Kind":"tool_exec_start"},"notification":true}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":7,"method":"hook.before_tool","params":{"tool":"echo_text","arguments":{"text":"hello"}},"notification":false}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"out","id":7,"response":{"action":"continue"},"error":null}
+```
+
+补充说明：
+
+- 时间戳是 UTC，不是本地时区
+- `notification=true` 表示这是 `hook.event` 这类不需要响应的通知
+- `id` 会随着当前进程内的请求递增；如果 hook 进程重启，计数会重新开始
+
+## Process Hook 协议约定
+
+当前 process hook 使用 `JSON-RPC over stdio`：
+
+- PicoClaw 启动外部进程
+- 请求和响应都按“一行一个 JSON 消息”传输
+- `hook.event` 是 notification，不需要响应
+- `hook.before_llm` / `hook.after_llm` / `hook.before_tool` / `hook.after_tool` / `hook.approve_tool` 是 request/response
+
+当前宿主不会接受 process hook 主动发起的新 RPC。也就是说，外部 hook 现在只能“响应 PicoClaw 的调用”，不能反向调用宿主去发送 channel 消息。
+
+## 配置字段
+
+### `hooks.builtins.`
+
+- `enabled`
+- `priority`
+- `config`
+
+### `hooks.processes.`
+
+- `enabled`
+- `priority`
+- `transport`
+ 当前只支持 `stdio`
+- `command`
+- `dir`
+- `env`
+- `observe`
+- `intercept`
+
+## 排查建议
+
+当你觉得“hook 没触发”时，优先按这个顺序排查：
+
+1. `hooks.enabled` 是否为 `true`
+2. 对应的 builtin/process hook 是否 `enabled`
+3. process hook 的 `command` 路径是否正确
+4. 你看的是否是正确的日志文件
+5. 当前请求是否真的走到了对应阶段
+6. `observe` / `intercept` 是否包含了你想看的点位
+
+一个很实用的最小排查组合是：
+
+- 先用文档里的 Python process 示例确认外部协议没问题
+- 再用文档里的 Go in-process 示例确认宿主内的 hook 链路没问题
+
+如果前者有 `hook.hello` 但没有业务请求，通常不是协议挂了，而是当前这次请求没有真正触发对应的 hook 点位。
+
+## 适用边界
+
+当前 hook 系统最适合做这些事：
+
+- LLM 请求改写
+- 工具参数规范化
+- 工具执行前审批
+- 审计和观测
+
+当前还不适合直接承载这些需求：
+
+- 外部 hook 主动发 channel 消息
+- 挂起 turn 并等待人工审批回复
+- inbound/outbound 全链路消息拦截
+
+如果你要做人审流转，推荐把 hook 作为审批入口，把审批状态机和 channel 交互放到独立的 `ApprovalManager`。
diff --git a/docs/ja/ANTIGRAVITY_AUTH.md b/docs/ja/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..b55e4ab1b
--- /dev/null
+++ b/docs/ja/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,809 @@
+> [README](../../README.ja.md) に戻る
+
+# Antigravity 認証・統合ガイド
+
+## 概要
+
+**Antigravity**（Google Cloud Code Assist）は、Google が提供する AI モデルプロバイダーで、Google のクラウドインフラストラクチャを通じて Claude Opus 4.6 や Gemini などのモデルへのアクセスを提供します。本ドキュメントでは、認証の仕組み、モデルの取得方法、PicoClaw での新しいプロバイダーの実装方法について完全なガイドを提供します。
+
+---
+
+## 目次
+
+1. [認証フロー](#認証フロー)
+2. [OAuth 実装の詳細](#oauth-実装の詳細)
+3. [トークン管理](#トークン管理)
+4. [モデルリストの取得](#モデルリストの取得)
+5. [使用量トラッキング](#使用量トラッキング)
+6. [プロバイダープラグイン構造](#プロバイダープラグイン構造)
+7. [統合要件](#統合要件)
+8. [API エンドポイント](#api-エンドポイント)
+9. [設定](#設定)
+10. [PicoClaw での新しいプロバイダーの作成](#picoclaw-での新しいプロバイダーの作成)
+
+---
+
+## 認証フロー
+
+### 1. PKCE 付き OAuth 2.0
+
+Antigravity はセキュアな認証のために **OAuth 2.0 with PKCE（Proof Key for Code Exchange）** を使用します：
+
+```
+┌─────────────┐ ┌─────────────────┐
+│ Client │ ───(1) Generate PKCE Pair────────> │ │
+│ │ ───(2) Open Auth URL─────────────> │ Google OAuth │
+│ │ │ Server │
+│ │ <──(3) Redirect with Code───────── │ │
+│ │ └─────────────────┘
+│ │ ───(4) Exchange Code for Tokens──> │ Token URL │
+│ │ │ │
+│ │ <──(5) Access + Refresh Tokens──── │ │
+└─────────────┘ └─────────────────┘
+```
+
+### 2. 詳細手順
+
+#### ステップ 1：PKCE パラメータの生成
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+ const verifier = randomBytes(32).toString("hex");
+ const challenge = createHash("sha256").update(verifier).digest("base64url");
+ return { verifier, challenge };
+}
+```
+
+#### ステップ 2：認可 URL の構築
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+ const url = new URL(AUTH_URL);
+ url.searchParams.set("client_id", CLIENT_ID);
+ url.searchParams.set("response_type", "code");
+ url.searchParams.set("redirect_uri", REDIRECT_URI);
+ url.searchParams.set("scope", SCOPES.join(" "));
+ url.searchParams.set("code_challenge", params.challenge);
+ url.searchParams.set("code_challenge_method", "S256");
+ url.searchParams.set("state", params.state);
+ url.searchParams.set("access_type", "offline");
+ url.searchParams.set("prompt", "consent");
+ return url.toString();
+}
+```
+
+**必要なスコープ：**
+```typescript
+const SCOPES = [
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/userinfo.email",
+ "https://www.googleapis.com/auth/userinfo.profile",
+ "https://www.googleapis.com/auth/cclog",
+ "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### ステップ 3：OAuth コールバックの処理
+
+**自動モード（ローカル開発）：**
+- ポート 51121 でローカル HTTP サーバーを起動
+- Google からのリダイレクトを待機
+- クエリパラメータから認可コードを抽出
+
+**手動モード（リモート/ヘッドレス）：**
+- ユーザーに認可 URL を表示
+- ユーザーがブラウザで認証を完了
+- ユーザーが完全なリダイレクト URL をターミナルに貼り付け
+- 貼り付けられた URL からコードを解析
+
+#### ステップ 4：コードをトークンに交換
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+ code: string;
+ verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+ const response = await fetch(TOKEN_URL, {
+ method: "POST",
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
+ body: new URLSearchParams({
+ client_id: CLIENT_ID,
+ client_secret: CLIENT_SECRET,
+ code: params.code,
+ grant_type: "authorization_code",
+ redirect_uri: REDIRECT_URI,
+ code_verifier: params.verifier,
+ }),
+ });
+
+ const data = await response.json();
+
+ return {
+ access: data.access_token,
+ refresh: data.refresh_token,
+ expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+ };
+}
+```
+
+#### ステップ 5：追加のユーザーデータの取得
+
+**ユーザーメール：**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise {
+ const response = await fetch(
+ "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+ { headers: { Authorization: `Bearer ${accessToken}` } }
+ );
+ const data = await response.json();
+ return data.email;
+}
+```
+
+**プロジェクト ID（API 呼び出しに必須）：**
+```typescript
+async function fetchProjectId(accessToken: string): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "google-api-nodejs-client/9.15.1",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ "Client-Metadata": JSON.stringify({
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ }),
+ };
+
+ const response = await fetch(
+ "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({
+ metadata: {
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ const data = await response.json();
+ return data.cloudaicompanionProject || "rising-fact-p41fc"; // デフォルトのフォールバック
+}
+```
+
+---
+
+## OAuth 実装の詳細
+
+### クライアント認証情報
+
+**重要：** これらは pi-ai との同期のためにソースコード内で base64 エンコードされています：
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+ "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### OAuth フローモード
+
+1. **自動フロー**（ブラウザのあるローカルマシン）：
+ - ブラウザを自動的に開く
+ - ローカルコールバックサーバーがリダイレクトをキャプチャ
+ - 初回認証後はユーザー操作不要
+
+2. **手動フロー**（リモート/ヘッドレス/WSL2）：
+ - 手動コピー＆ペースト用の URL を表示
+ - ユーザーが外部ブラウザで認証を完了
+ - ユーザーが完全なリダイレクト URL を貼り付け
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+ return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## トークン管理
+
+### 認証プロファイル構造
+
+```typescript
+type OAuthCredential = {
+ type: "oauth";
+ provider: "google-antigravity";
+ access: string; // アクセストークン
+ refresh: string; // リフレッシュトークン
+ expires: number; // 有効期限タイムスタンプ（エポックからのミリ秒）
+ email?: string; // ユーザーメール
+ projectId?: string; // Google Cloud プロジェクト ID
+};
+```
+
+### トークンの更新
+
+認証情報にはリフレッシュトークンが含まれており、現在のアクセストークンが期限切れになった際に新しいアクセストークンを取得するために使用できます。有効期限は競合状態を防ぐために 5 分のバッファを設けています。
+
+---
+
+## モデルリストの取得
+
+### 利用可能なモデルの取得
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+ accessToken: string,
+ projectId: string
+): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ };
+
+ const response = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ const data = await response.json();
+
+ // クォータ情報付きのモデルを返す
+ return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+ id: modelId,
+ displayName: modelInfo.displayName,
+ quotaInfo: {
+ remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+ resetTime: modelInfo.quotaInfo?.resetTime,
+ isExhausted: modelInfo.quotaInfo?.isExhausted,
+ },
+ }));
+}
+```
+
+### レスポンス形式
+
+```typescript
+type FetchAvailableModelsResponse = {
+ models?: Record;
+};
+```
+
+---
+
+## 使用量トラッキング
+
+### 使用量データの取得
+
+```typescript
+export async function fetchAntigravityUsage(
+ token: string,
+ timeoutMs: number
+): Promise {
+ // 1. クレジットとプラン情報を取得
+ const loadCodeAssistRes = await fetch(
+ `${BASE_URL}/v1internal:loadCodeAssist`,
+ {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${token}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ metadata: {
+ ideType: "ANTIGRAVITY",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ // クレジット情報を抽出
+ const { availablePromptCredits, planInfo, currentTier } = data;
+
+ // 2. モデルクォータを取得
+ const modelsRes = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers: { Authorization: `Bearer ${token}` },
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ // 使用量ウィンドウを構築
+ return {
+ provider: "google-antigravity",
+ displayName: "Google Antigravity",
+ windows: [
+ { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+ // 個別モデルクォータ...
+ ],
+ plan: currentTier?.name || planType,
+ };
+}
+```
+
+### 使用量レスポンス構造
+
+```typescript
+type ProviderUsageSnapshot = {
+ provider: "google-antigravity";
+ displayName: string;
+ windows: UsageWindow[];
+ plan?: string;
+ error?: string;
+};
+
+type UsageWindow = {
+ label: string; // "Credits" またはモデル ID
+ usedPercent: number; // 0-100
+ resetAt?: number; // クォータがリセットされるタイムスタンプ
+};
+```
+
+---
+
+## プロバイダープラグイン構造
+
+### プラグイン定義
+
+```typescript
+const antigravityPlugin = {
+ id: "google-antigravity-auth",
+ name: "Google Antigravity Auth",
+ description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+ configSchema: emptyPluginConfigSchema(),
+
+ register(api: PicoClawPluginApi) {
+ api.registerProvider({
+ id: "google-antigravity",
+ label: "Google Antigravity",
+ docsPath: "/providers/models",
+ aliases: ["antigravity"],
+
+ auth: [
+ {
+ id: "oauth",
+ label: "Google OAuth",
+ hint: "PKCE + localhost callback",
+ kind: "oauth",
+ run: async (ctx: ProviderAuthContext) => {
+ // OAuth 実装はここに記述
+ },
+ },
+ ],
+ });
+ },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+ config: PicoClawConfig;
+ agentDir?: string;
+ workspaceDir?: string;
+ prompter: WizardPrompter; // UI プロンプト/通知
+ runtime: RuntimeEnv; // ログなど
+ isRemote: boolean; // リモート実行かどうか
+ openUrl: (url: string) => Promise; // ブラウザオープナー
+ oauth: {
+ createVpsAwareHandlers: Function;
+ };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+ profiles: Array<{
+ profileId: string;
+ credential: AuthProfileCredential;
+ }>;
+ configPatch?: Partial;
+ defaultModel?: string;
+ notes?: string[];
+};
+```
+
+---
+
+## 統合要件
+
+### 1. 必要な環境/依存関係
+
+- Go ≥ 1.25
+- PicoClaw コードベース（`pkg/providers/` および `pkg/auth/`）
+- `crypto` および `net/http` 標準ライブラリパッケージ
+
+### 2. API 呼び出しに必要なヘッダー
+
+```typescript
+const REQUIRED_HEADERS = {
+ "Authorization": `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity", // または "google-api-nodejs-client/9.15.1"
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// loadCodeAssist 呼び出しには以下も含める：
+const CLIENT_METADATA = {
+ ideType: "ANTIGRAVITY", // または "IDE_UNSPECIFIED"
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+};
+```
+
+### 3. モデルスキーマのサニタイズ
+
+Antigravity は Gemini 互換モデルを使用するため、ツールスキーマのサニタイズが必要です：
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+ "patternProperties",
+ "additionalProperties",
+ "$schema",
+ "$id",
+ "$ref",
+ "$defs",
+ "definitions",
+ "examples",
+ "minLength",
+ "maxLength",
+ "minimum",
+ "maximum",
+ "multipleOf",
+ "pattern",
+ "format",
+ "minItems",
+ "maxItems",
+ "uniqueItems",
+ "minProperties",
+ "maxProperties",
+]);
+
+// 送信前にスキーマをクリーンアップ
+function cleanToolSchemaForGemini(schema: Record): unknown {
+ // サポートされていないキーワードを削除
+ // トップレベルに type: "object" があることを確認
+ // anyOf/oneOf ユニオンをフラット化
+}
+```
+
+### 4. 思考ブロックの処理（Claude モデル）
+
+Antigravity の Claude モデルでは、思考ブロックに特別な処理が必要です：
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+ messages: AgentMessage[]
+): AgentMessage[] {
+ // 思考シグネチャを検証
+ // シグネチャフィールドを正規化
+ // 署名されていない思考ブロックを破棄
+}
+```
+
+---
+
+## API エンドポイント
+
+### 認証エンドポイント
+
+| エンドポイント | メソッド | 用途 |
+|---------------|---------|------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | OAuth 認可 |
+| `https://oauth2.googleapis.com/token` | POST | トークン交換 |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | ユーザー情報（メール） |
+
+### Cloud Code Assist エンドポイント
+
+| エンドポイント | メソッド | 用途 |
+|---------------|---------|------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | プロジェクト情報、クレジット、プランの読み込み |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | クォータ付き利用可能モデルの一覧 |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | チャットストリーミングエンドポイント |
+
+**API リクエスト形式（チャット）：**
+`v1internal:streamGenerateContent` エンドポイントは、標準の Gemini リクエストをラップするエンベロープ形式を期待します：
+
+```json
+{
+ "project": "your-project-id",
+ "model": "model-id",
+ "request": {
+ "contents": [...],
+ "systemInstruction": {...},
+ "generationConfig": {...},
+ "tools": [...]
+ },
+ "requestType": "agent",
+ "userAgent": "antigravity",
+ "requestId": "agent-timestamp-random"
+}
+```
+
+**API レスポンス形式（SSE）：**
+各 SSE メッセージ（`data: {...}`）は `response` フィールドでラップされます：
+
+```json
+{
+ "response": {
+ "candidates": [...],
+ "usageMetadata": {...},
+ "modelVersion": "...",
+ "responseId": "..."
+ },
+ "traceId": "...",
+ "metadata": {}
+}
+```
+
+---
+
+## 設定
+
+### config.json の設定
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gemini-flash",
+ "model": "antigravity/gemini-3-flash",
+ "auth_method": "oauth"
+ }
+ ],
+ "agents": {
+ "defaults": {
+ "model_name": "gemini-flash"
+ }
+ }
+}
+```
+
+### 認証プロファイルの保存
+
+認証プロファイルは `~/.picoclaw/auth.json` に保存されます：
+
+```json
+{
+ "credentials": {
+ "google-antigravity": {
+ "access_token": "ya29...",
+ "refresh_token": "1//...",
+ "expires_at": "2026-01-01T00:00:00Z",
+ "provider": "google-antigravity",
+ "auth_method": "oauth",
+ "email": "user@example.com",
+ "project_id": "my-project-id"
+ }
+ }
+}
+```
+
+---
+
+## PicoClaw での新しいプロバイダーの作成
+
+PicoClaw のプロバイダーは `pkg/providers/` 配下の Go パッケージとして実装されます。新しいプロバイダーを追加するには：
+
+### ステップバイステップの実装
+
+#### 1. プロバイダーファイルの作成
+
+`pkg/providers/` に新しい Go ファイルを作成します：
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. Provider インターフェースの実装
+
+プロバイダーは `pkg/providers/types.go` で定義された `Provider` インターフェースを実装する必要があります：
+
+```go
+package providers
+
+type YourProvider struct {
+ apiKey string
+ apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+ if apiBase == "" {
+ apiBase = "https://api.your-provider.com/v1"
+ }
+ return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+ // ストリーミング付きチャット補完を実装
+}
+```
+
+#### 3. ファクトリーへの登録
+
+`pkg/providers/factory.go` のプロトコルスイッチにプロバイダーを追加します：
+
+```go
+case "your-provider":
+ return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. デフォルト設定の追加（オプション）
+
+`pkg/config/defaults.go` にデフォルトエントリを追加します：
+
+```go
+{
+ ModelName: "your-model",
+ Model: "your-provider/model-name",
+ APIKey: "",
+},
+```
+
+#### 5. 認証サポートの追加（オプション）
+
+プロバイダーが OAuth や特別な認証を必要とする場合、`cmd/picoclaw/internal/auth/helpers.go` にケースを追加します：
+
+```go
+case "your-provider":
+ authLoginYourProvider()
+```
+
+#### 6. `config.json` での設定
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "your-model",
+ "model": "your-provider/model-name",
+ "api_key": "your-api-key",
+ "api_base": "https://api.your-provider.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## 実装のテスト
+
+### CLI コマンド
+
+```bash
+# プロバイダーで認証
+picoclaw auth login --provider your-provider
+
+# モデルの一覧表示（Antigravity 用）
+picoclaw auth models
+
+# ゲートウェイの起動
+picoclaw gateway
+
+# 特定のモデルでエージェントを実行
+picoclaw agent -m "Hello" --model your-model
+```
+
+### テスト用環境変数
+
+```bash
+# デフォルトモデルの上書き
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# プロバイダー設定の上書き
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## 参考資料
+
+- **ソースファイル：**
+ - `pkg/providers/antigravity_provider.go` - Antigravity プロバイダー実装
+ - `pkg/auth/oauth.go` - OAuth フロー実装
+ - `pkg/auth/store.go` - 認証情報ストレージ（`~/.picoclaw/auth.json`）
+ - `pkg/providers/factory.go` - プロバイダーファクトリーとプロトコルルーティング
+ - `pkg/providers/types.go` - プロバイダーインターフェース定義
+ - `cmd/picoclaw/internal/auth/helpers.go` - 認証 CLI コマンド
+
+- **ドキュメント：**
+ - `docs/ANTIGRAVITY_USAGE.md` - Antigravity 使用ガイド
+ - `docs/migration/model-list-migration.md` - 移行ガイド
+
+---
+
+## 注意事項
+
+1. **Google Cloud プロジェクト：** Antigravity は Google Cloud プロジェクトで Gemini for Google Cloud が有効になっている必要があります
+2. **クォータ：** Google Cloud プロジェクトのクォータを使用します（個別の課金ではありません）
+3. **モデルアクセス：** 利用可能なモデルは Google Cloud プロジェクトの設定に依存します
+4. **思考ブロック：** Antigravity 経由の Claude モデルは、署名付き思考ブロックの特別な処理が必要です
+5. **スキーマサニタイズ：** ツールスキーマはサポートされていない JSON Schema キーワードを削除するためにサニタイズが必要です
+
+---
+
+---
+
+## 一般的なエラー処理
+
+### 1. レート制限（HTTP 429）
+
+プロジェクト/モデルのクォータが枯渇すると、Antigravity は 429 エラーを返します。エラーレスポンスには通常、`details` フィールドに `quotaResetDelay` が含まれます。
+
+**429 エラーの例：**
+```json
+{
+ "error": {
+ "code": 429,
+ "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+ "status": "RESOURCE_EXHAUSTED",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+ "metadata": {
+ "quotaResetDelay": "4h30m28.060903746s"
+ }
+ }
+ ]
+ }
+}
+```
+
+### 2. 空のレスポンス（制限付きモデル）
+
+一部のモデルは利用可能モデルリストに表示されますが、空のレスポンスを返す場合があります（200 OK だが SSE ストリームが空）。これは通常、現在のプロジェクトに使用権限がないプレビュー版または制限付きモデルで発生します。
+
+**対処法：** 空のレスポンスをエラーとして扱い、そのモデルがプロジェクトに対して制限されているか無効である可能性があることをユーザーに通知します。
+
+---
+
+## トラブルシューティング
+
+### "Token expired"（トークン期限切れ）
+- OAuth トークンを更新：`picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled"（Gemini for Google Cloud が有効になっていない）
+- Google Cloud Console で API を有効にしてください
+
+### "Project not found"（プロジェクトが見つからない）
+- Google Cloud プロジェクトで必要な API が有効になっていることを確認してください
+- 認証中にプロジェクト ID が正しく取得されているか確認してください
+
+### モデルがリストに表示されない
+- OAuth 認証が正常に完了したことを確認してください
+- 認証プロファイルストレージを確認：`~/.picoclaw/auth.json`
+- `picoclaw auth login --provider antigravity` を再実行してください
diff --git a/docs/ja/ANTIGRAVITY_USAGE.md b/docs/ja/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..c044c1970
--- /dev/null
+++ b/docs/ja/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> [README](../../README.ja.md) に戻る
+
+# PicoClaw で Antigravity プロバイダーを使用する
+
+このガイドでは、PicoClaw で **Antigravity**（Google Cloud Code Assist）プロバイダーをセットアップして使用する方法を説明します。
+
+## 前提条件
+
+1. Google アカウント。
+2. Google Cloud Code Assist が有効であること（通常「Gemini for Google Cloud」のオンボーディングから利用可能）。
+
+## 1. 認証
+
+Antigravity で認証するには、以下のコマンドを実行します：
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### 手動認証（ヘッドレス/VPS）
+サーバー（Coolify/Docker）上で実行しており、`localhost` にアクセスできない場合は、以下の手順に従ってください：
+1. 上記のコマンドを実行します。
+2. 表示された URL をコピーし、ローカルブラウザで開きます。
+3. ログインを完了します。
+4. ブラウザが `localhost:51121` URL にリダイレクトされます（ページは読み込めません）。
+5. **ブラウザのアドレスバーからその最終 URL をコピーします**。
+6. **PicoClaw が待機しているターミナルにそれを貼り付けます**。
+
+PicoClaw が自動的に認証コードを抽出し、プロセスを完了します。
+
+## 2. モデルの管理
+
+### 利用可能なモデルの一覧
+プロジェクトがアクセスできるモデルとそのクォータを確認するには：
+
+```bash
+picoclaw auth models
+```
+
+### モデルの切り替え
+`~/.picoclaw/config.json` でデフォルトモデルを変更するか、CLI でオーバーライドできます：
+
+```bash
+# 単一コマンドでオーバーライド
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. 実際の使用方法（Coolify/Docker）
+
+Coolify または Docker でデプロイしている場合、以下の手順でテストしてください：
+
+1. **環境変数**：
+ * `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2. **認証の永続化**：
+ ローカルでログイン済みの場合、認証情報をサーバーにコピーできます：
+ ```bash
+ scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+ ```
+ *または*、ターミナルアクセスがある場合、サーバー上で `auth login` コマンドを一度実行してください。
+
+## 4. トラブルシューティング
+
+* **空のレスポンス**：モデルが空の応答を返す場合、プロジェクトで制限されている可能性があります。`gemini-3-flash` または `claude-opus-4-6-thinking` を試してください。
+* **429 レート制限**：Antigravity には厳格なクォータがあります。制限に達した場合、PicoClaw はエラーメッセージに「リセット時間」を表示します。
+* **404 Not Found**：`picoclaw auth models` リストのモデル ID を使用していることを確認してください。フルパスではなく、短い ID（例：`gemini-3-flash`）を使用してください。
+
+## 5. 動作確認済みモデルのまとめ
+
+テストに基づき、以下のモデルが最も信頼性が高いです：
+* `gemini-3-flash`（高速、高可用性）
+* `gemini-2.5-flash-lite`（軽量）
+* `claude-opus-4-6-thinking`（高性能、推論機能を含む）
diff --git a/docs/ja/chat-apps.md b/docs/ja/chat-apps.md
index 6d01c817b..789c0125f 100644
--- a/docs/ja/chat-apps.md
+++ b/docs/ja/chat-apps.md
@@ -12,23 +12,25 @@ PicoClaw は複数のチャットプラットフォームをサポートして
| チャネル | セットアップ難易度 | 特徴 | ドキュメント |
| -------------------- | ------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| **Telegram** | ⭐ 簡単 | 推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要） | [ドキュメント](../channels/telegram/README.zh.md) |
-| **Discord** | ⭐ 簡単 | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.zh.md) |
-| **WhatsApp** | ⭐ 簡単 | ネイティブ (QR スキャン) または Bridge URL | [ドキュメント](../channels/whatsapp/README.zh.md) |
-| **Slack** | ⭐ 簡単 | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.zh.md) |
-| **Matrix** | ⭐⭐ 中程度 | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.zh.md) |
-| **QQ** | ⭐⭐ 中程度 | 公式ボット API、中国コミュニティ向け | [ドキュメント](../channels/qq/README.zh.md) |
-| **DingTalk** | ⭐⭐ 中程度 | Stream モード（公開 IP 不要）、企業向け | [ドキュメント](../channels/dingtalk/README.zh.md) |
-| **LINE** | ⭐⭐⭐ やや難 | HTTPS Webhook が必要 | [ドキュメント](../channels/line/README.zh.md) |
-| **WeCom (企業微信)** | ⭐⭐⭐ やや難 | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.zh.md) / [App](../channels/wecom/wecom_app/README.zh.md) / [AI Bot](../channels/wecom/wecom_aibot/README.zh.md) |
-| **Feishu (飛書)** | ⭐⭐⭐ やや難 | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.zh.md) |
-| **IRC** | ⭐⭐ 中程度 | サーバー + TLS 設定 | - |
-| **OneBot** | ⭐⭐ 中程度 | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.zh.md) |
-| **MaixCam** | ⭐ 簡単 | Sipeed AI カメラハードウェア統合チャネル | [ドキュメント](../channels/maixcam/README.zh.md) |
+| **Telegram** | ⭐ 簡単 | 推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要） | [ドキュメント](../channels/telegram/README.ja.md) |
+| **Discord** | ⭐ 簡単 | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.ja.md) |
+| **WhatsApp** | ⭐ 簡単 | ネイティブ (QR スキャン) または Bridge URL | [ドキュメント](#whatsapp) |
+| **微信 (Weixin)** | ⭐ 簡単 | ネイティブ QR スキャン（Tencent iLink API）| [ドキュメント](#weixin) |
+| **Slack** | ⭐ 簡単 | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.ja.md) |
+| **Matrix** | ⭐⭐ 中程度 | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.ja.md) |
+| **QQ** | ⭐⭐ 中程度 | 公式ボット API、中国コミュニティ向け | [ドキュメント](../channels/qq/README.ja.md) |
+| **DingTalk** | ⭐⭐ 中程度 | Stream モード（公開 IP 不要）、企業向け | [ドキュメント](../channels/dingtalk/README.ja.md) |
+| **LINE** | ⭐⭐⭐ やや難 | HTTPS Webhook が必要 | [ドキュメント](../channels/line/README.ja.md) |
+| **WeCom (企業微信)** | ⭐⭐⭐ やや難 | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.ja.md) / [App](../channels/wecom/wecom_app/README.ja.md) / [AI Bot](../channels/wecom/wecom_aibot/README.ja.md) |
+| **Feishu (飛書)** | ⭐⭐⭐ やや難 | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.ja.md) |
+| **IRC** | ⭐⭐ 中程度 | サーバー + TLS 設定 | [ドキュメント](#irc) |
+| **OneBot** | ⭐⭐ 中程度 | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.ja.md) |
+| **MaixCam** | ⭐ 簡単 | Sipeed AI カメラハードウェア統合チャネル | [ドキュメント](../channels/maixcam/README.ja.md) |
| **Pico** | ⭐ 簡単 | PicoClaw ネイティブプロトコルチャネル | |
---
+
Telegram （推奨）
+
Discord
+
WhatsApp （ネイティブ whatsmeow）
+
+微信 (Weixin)
+
+
Matrix
+
QQ
+
Slack
+
IRC
+
DingTalk
+
LINE
+
Feishu (飛書)
+
WeCom (企業微信)
+
-OneBot OneBot（OneBot プロトコル経由の QQ）
+
MaixCam /skills`（ビルトイン）
+3. `<ビルド時埋め込みパス>/skills`（ビルトイン）
高度な/テスト用セットアップでは、以下の環境変数でビルトインスキルのルートを上書きできます：
@@ -256,3 +256,109 @@ Agent は 30 分ごと（設定可能）にこのファイルを読み取り、
- `PICOCLAW_HEARTBEAT_ENABLED=false` で無効化
- `PICOCLAW_HEARTBEAT_INTERVAL=60` で間隔を変更
+
+#### サブ Agent の通信フロー
+
+```
+ハートビート起動
+ ↓
+Agent が HEARTBEAT.md を読む
+ ↓
+長時間タスク：spawn サブ Agent
+ ↓ ↓
+次のタスクへ継続 サブ Agent が独立して動作
+ ↓ ↓
+全タスク完了 サブ Agent が "message" ツールを使用
+ ↓ ↓
+HEARTBEAT_OK を返信 ユーザーが直接結果を受信
+```
+
+### Providers
+
+> [!NOTE]
+> Groq は Whisper による無料音声文字起こしを提供します。設定すると、任意のチャンネルの音声メッセージが Agent レベルで自動的に文字起こしされます。
+
+| Provider | 用途 | API キー取得 |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini` | LLM（Gemini 直接） | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM（Zhipu 直接） | [bigmodel.cn](https://bigmodel.cn) |
+| `volcengine` | LLM（Volcengine 直接） | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM（推奨、全モデルにアクセス可能） | [openrouter.ai](https://openrouter.ai) |
+| `anthropic` | LLM（Claude 直接） | [console.anthropic.com](https://console.anthropic.com) |
+| `openai` | LLM（GPT 直接） | [platform.openai.com](https://platform.openai.com) |
+| `deepseek` | LLM（DeepSeek 直接） | [platform.deepseek.com](https://platform.deepseek.com) |
+| `qwen` | LLM（Qwen 直接） | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq` | LLM + **音声文字起こし**（Whisper） | [console.groq.com](https://console.groq.com) |
+| `cerebras` | LLM（Cerebras 直接） | [cerebras.ai](https://cerebras.ai) |
+| `vivgrid` | LLM（Vivgrid 直接） | [vivgrid.com](https://vivgrid.com) |
+
+### モデル設定 (model_list)
+
+> **新機能：** PicoClaw は**モデル中心**の設定アプローチを採用しました。`vendor/model` 形式（例：`zhipu/glm-4.7`）を指定するだけで新しい Provider を追加できます — **コード変更不要！**
+
+#### サポートされている全 Vendor
+
+| Vendor | `model` プレフィックス | デフォルト API Base | プロトコル | API Key |
+| ----------------------- | ---------------------- | --------------------------------------------------- | ---------- | ---------------------------------------------------------------- |
+| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [取得](https://platform.openai.com) |
+| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [取得](https://console.anthropic.com) |
+| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [取得](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [取得](https://platform.deepseek.com) |
+| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [取得](https://aistudio.google.com/api-keys) |
+| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [取得](https://console.groq.com) |
+| **通義千問 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [取得](https://dashscope.console.aliyun.com) |
+| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | ローカル（キー不要） |
+| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [取得](https://openrouter.ai/keys) |
+| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [取得](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth のみ |
+
+#### ロードバランシング
+
+同じモデル名に複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンします：
+
+```json
+{
+ "model_list": [
+ { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
+ { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
+ ]
+}
+```
+
+#### 旧 `providers` 設定からの移行
+
+旧 `providers` 設定は**非推奨**ですが後方互換性のためサポートされています。[docs/migration/model-list-migration.md](../migration/model-list-migration.md) を参照してください。
+
+### Provider アーキテクチャ
+
+PicoClaw はプロトコルファミリーで Provider をルーティングします：
+
+- **OpenAI 互換**：OpenRouter、Groq、Zhipu、vLLM スタイルのエンドポイントなど。
+- **Anthropic**：Claude ネイティブ API の動作。
+- **Codex/OAuth**：OpenAI OAuth/トークン認証ルート。
+
+### スケジュールタスク / リマインダー
+
+PicoClaw は `cron` ツールを通じて cron スタイルのスケジュールタスクをサポートします。
+
+```json
+{
+ "tools": {
+ "cron": {
+ "enabled": true,
+ "exec_timeout_minutes": 5
+ }
+ }
+}
+```
+
+スケジュールタスクは再起動後も `~/.picoclaw/workspace/cron/` に保存されます。
+
+### 高度なトピック
+
+| トピック | 説明 |
+| -------- | ---- |
+| [Hook システム](../hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
+| [Steering](../steering.md) | 実行中の Agent ループにメッセージを注入 |
+| [SubTurn](../subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
+| [コンテキスト管理](../agent-refactor/context.md) | コンテキスト境界検出、圧縮戦略 |
diff --git a/docs/ja/credential_encryption.md b/docs/ja/credential_encryption.md
new file mode 100644
index 000000000..ea74b65d2
--- /dev/null
+++ b/docs/ja/credential_encryption.md
@@ -0,0 +1,158 @@
+> [README](../../README.ja.md) に戻る
+
+# クレデンシャル暗号化
+
+PicoClaw は `model_list` 設定エントリの `api_key` 値の暗号化をサポートしています。
+暗号化されたキーは `enc://` 文字列として保存され、起動時に自動的に復号されます。
+
+---
+
+## クイックスタート
+
+**1. パスフレーズを設定する**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. API キーを暗号化する**
+
+`picoclaw onboard` を実行します — パスフレーズの入力を求められ、SSH キーが生成されます。
+その後、次の `SaveConfig` 呼び出し時に、設定内のすべての平文 `api_key` エントリが自動的に再暗号化されます。生成される `enc://` 値は以下のようになります：
+
+```
+enc://AAAA...base64...
+```
+
+**3. 出力を設定に貼り付ける**
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-4o",
+ "model": "openai/gpt-4o",
+ "api_key": "enc://AAAA...base64...",
+ "api_base": "https://api.openai.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## サポートされる `api_key` 形式
+
+| 形式 | 例 | 動作 |
+|------|---|------|
+| 平文 | `sk-abc123` | そのまま使用 |
+| ファイル参照 | `file://openai.key` | 設定ファイルと同じディレクトリから内容を読み取り |
+| 暗号化 | `enc://` | 起動時に `PICOCLAW_KEY_PASSPHRASE` を使用して復号 |
+| 空 | `""` | そのまま渡される（`auth_method: oauth` で使用） |
+
+---
+
+## 暗号設計
+
+### 鍵導出
+
+暗号化には **HKDF-SHA256** を使用し、SSH 秘密鍵を第二要素とします。
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### 暗号化
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### ワイヤーフォーマット
+
+```
+enc://
+```
+
+| フィールド | サイズ | 説明 |
+|-----------|--------|------|
+| `salt` | 16 バイト | 暗号化ごとにランダム生成；HKDF に入力 |
+| `nonce` | 12 バイト | 暗号化ごとにランダム生成；AES-GCM IV |
+| `ciphertext` | 可変 | AES-256-GCM 暗号文 + 16 バイト認証タグ |
+
+GCM 認証タグは暗号文に自動的に付加されます。改ざんがあった場合、破損した平文を返すのではなく、エラーで復号が失敗します。
+
+### パフォーマンス
+
+| 操作 | 所要時間 (ARM Cortex-A) |
+|------|------------------------|
+| 鍵導出 (HKDF) | < 1 ms |
+| AES-256-GCM 復号 | < 1 ms |
+| **起動時の総オーバーヘッド** | **キーあたり < 2 ms** |
+
+---
+
+## SSH キーによる二要素セキュリティ
+
+SSH 秘密鍵が提供されている場合、暗号を破るには**両方**が必要です：
+
+1. **パスフレーズ** (`PICOCLAW_KEY_PASSPHRASE`)
+2. **SSH 秘密鍵ファイル**
+
+これは、設定ファイルが漏洩しただけでは、パスフレーズが弱い場合でも API キーを復元できないことを意味します。SSH キーはパスフレーズの強度に関係なく、256 ビットのエントロピー（Ed25519）を提供します。
+
+### 脅威モデル
+
+| 攻撃者が持っているもの | 復号可能か？ |
+|----------------------|-------------|
+| 設定ファイルのみ | いいえ — パスフレーズ + SSH キーが必要 |
+| SSH キーのみ | いいえ — パスフレーズが必要 |
+| パスフレーズのみ | いいえ — SSH キーが必要 |
+| 設定ファイル + SSH キー + パスフレーズ | はい — 完全な侵害 |
+
+---
+
+## 環境変数
+
+| 変数 | 必須 | 説明 |
+|------|------|------|
+| `PICOCLAW_KEY_PASSPHRASE` | はい（`enc://` 使用時） | 鍵導出に使用するパスフレーズ |
+| `PICOCLAW_SSH_KEY_PATH` | いいえ | SSH 秘密鍵のパス。未設定の場合、`~/.ssh/picoclaw_ed25519.key` から自動検出 |
+
+### SSH キーの自動検出
+
+`PICOCLAW_SSH_KEY_PATH` が設定されていない場合、PicoClaw は専用キーを探します：
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+この専用ファイルにより、ユーザーの既存の SSH キーとの競合を回避します。
+`picoclaw onboard` を実行すると自動的に生成されます。
+
+`os.UserHomeDir()` はクロスプラットフォームのホームディレクトリ解決に使用されます（Windows では `USERPROFILE`、Unix/macOS では `HOME` を読み取ります）。
+
+> **注意：** SSH キーファイルはクレデンシャル暗号化に必須です。キーが見つからず `PICOCLAW_SSH_KEY_PATH` も設定されていない場合、暗号化/復号は失敗します。`picoclaw onboard` を実行してキーを自動生成してください。
+
+---
+
+## 移行
+
+唯一の秘密情報は `PICOCLAW_KEY_PASSPHRASE` と SSH 秘密鍵ファイルであるため、移行は簡単です：
+
+1. 設定ファイルを新しいマシンにコピーします。
+2. `PICOCLAW_KEY_PASSPHRASE` を同じ値に設定します。
+3. SSH 秘密鍵ファイルを同じパスにコピーします（または `PICOCLAW_SSH_KEY_PATH` を新しい場所に設定します）。
+
+再暗号化は不要です。
+
+---
+
+## セキュリティに関する考慮事項
+
+- **パスフレーズと SSH キーの両方が必須です。** SSH キーは第二要素として機能します — これがなければ暗号化/復号は失敗します。キーが存在しない場合は `picoclaw onboard` を実行して生成してください。
+- **SSH キーは実行時に読み取り専用です。** PicoClaw は SSH キーファイルへの書き込みや変更を行いません。
+- **平文キーは引き続きサポートされます。** `enc://` を使用しない既存の設定は影響を受けません。
+- **`enc://` 形式はバージョン管理されています。** HKDF `info` フィールド（`picoclaw-credential-v1`）により、既存の暗号化値を壊すことなく将来のアルゴリズムアップグレードが可能です。
diff --git a/docs/ja/debug.md b/docs/ja/debug.md
new file mode 100644
index 000000000..ecc52f454
--- /dev/null
+++ b/docs/ja/debug.md
@@ -0,0 +1,36 @@
+# PicoClaw のデバッグ
+
+> [README](../../README.ja.md) に戻る
+
+PicoClaw は、受信するすべてのリクエストに対して、メッセージのルーティングや複雑度の評価、ツールの実行、モデル障害への適応など、多くの複雑な処理をバックグラウンドで実行しています。何が起きているかを正確に把握できることは、潜在的な問題のトラブルシューティングだけでなく、エージェントの動作を真に理解するためにも非常に重要です。
+
+## デバッグモードで PicoClaw を起動する
+
+エージェントの動作に関する詳細情報（LLM リクエスト、ツール呼び出し、メッセージルーティング）を取得するには、デバッグフラグを付けて PicoClaw ゲートウェイを起動します：
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+このモードでは、システムがログを詳細にフォーマットし、システムプロンプトやツール実行結果のプレビューを表示します。
+
+## ログの切り詰めを無効にする（完全なログ）
+
+デフォルトでは、PicoClaw はコンソールの可読性を保つために、デバッグログ内の非常に長い文字列（*システムプロンプト*や大きな JSON 出力結果など）を切り詰めます。
+
+コマンドの完全な出力や、LLM モデルに送信された正確なペイロードを確認する必要がある場合は、`--no-truncate` フラグを使用できます。
+
+**注意：** このフラグは `--debug` モードと組み合わせた場合に*のみ*機能します。
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+このフラグが有効な場合、グローバルな切り詰め機能が無効になります。これは以下の場合に非常に便利です：
+
+* プロバイダーに送信されるメッセージの正確な構文を確認する。
+* `exec`、`web_fetch`、`read_file` などのツールの完全な出力を読む。
+* メモリに保存されたセッション履歴をデバッグする。
diff --git a/docs/ja/docker.md b/docs/ja/docker.md
index 6ad55d41d..31ed17ec5 100644
--- a/docs/ja/docker.md
+++ b/docs/ja/docker.md
@@ -12,6 +12,7 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. 初回実行 — docker/data/config.json を自動生成して終了
+# （config.json と workspace/ の両方が存在しない場合のみ実行）
docker compose -f docker/docker-compose.yml --profile gateway up
# コンテナが "First-run setup complete." と表示して停止します
diff --git a/docs/ja/hardware-compatibility.md b/docs/ja/hardware-compatibility.md
new file mode 100644
index 000000000..96ccd1cd1
--- /dev/null
+++ b/docs/ja/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> [README](../../README.ja.md) に戻る
+
+# 🖥️ PicoClaw ハードウェア互換性リスト
+
+PicoClaw はほぼすべての Linux デバイスで動作します。このページでは、検証済みのチップ、製品、開発ボードを記録しています。
+
+**お使いのハードウェアがリストにない場合は？** PR を送信して追加してください！ハードウェアベンダーの貢献と共同プロモーションを歓迎します。
+
+---
+
+## 1. 検証済みチップサポート
+
+### x86
+
+| ベンダー | チップ | 備考 |
+|----------|--------|------|
+| Intel | Any x86 CPU (i386+) | すべてのデスクトップ/サーバー/ノートPC プロセッサ |
+| AMD | Any x86 CPU | すべてのデスクトップ/サーバー/ノートPC プロセッサ |
+
+### ARM
+
+| サブアーキテクチャ | 代表的なチップ | 備考 |
+|--------------------|----------------|------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | シングルコア ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | シングルコア Cortex-A7、LicheePi Zero で使用 |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | クアッドコア Cortex-A53、Orange Pi Zero 3 で使用 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | クアッドコア Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | クアッドコア Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | デュアルコア Cortex-A53 + NPU、NanoKVM-Pro / MaixCAM2 で使用 |
+
+### RISC-V (riscv64)
+
+| ベンダー | チップ | コア | 備考 |
+|----------|--------|------|------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 オンチップ、LicheeRV-Nano / NanoKVM / MaixCAM で使用 |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L オンチップ、1 TOPS NPU、4K AI カメラ SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | RISC-V AI カメラシリーズ |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | HaaS506-LD1 産業用 RTU で使用 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Milk-V Jupiter, BananaPi BPI-F3 で使用 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | RVA23 準拠、1024 ビット RVV、FP8 AI 推論 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 コア、16MB L3 キャッシュ、デスクトップクラス |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU、CanMV-K230 で使用 |
+
+### MIPS
+
+| ベンダー | チップ | 備考 |
+|----------|--------|------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz、多くの OpenWrt ルーターで使用（例：Xiaomi Router 3G） |
+
+### LoongArch (loong64)
+
+| ベンダー | チップ | 備考 |
+|----------|--------|------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | クアッドコア LA464 @ 2.5GHz、デスクトップ/ワークステーション |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | クアッドコア 4C/8T @ 2.5GHz、IPC は Intel 第10世代に匹敵 |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | デュアルコア @ 1GHz、産業/IoT アプリケーション |
+
+---
+
+## 2. 検証済み製品（発売日順）
+
+PicoClaw でテスト済みのコンシューマー製品、ルーター、産業用デバイス。
+
+| 年 | 製品 | アーキテクチャ | SoC | RAM | カテゴリ |
+|----|------|----------------|-----|-----|----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | スマートフォン |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | タブレット |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | ルーター (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV ボックス / ホームサーバー |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | スマートスピーカー |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | 産業用 RTU |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | プロ IP-KVM |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | 4K AI カメラ |
+
+---
+
+## 3. 検証済み開発ボード（発売日順）
+
+| 年 | ボード | アーキテクチャ | SoC | RAM | 購入リンク |
+|----|--------|----------------|-----|-----|------------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. その他の対応環境
+
+### Android スマートフォン（Termux 経由）
+
+1GB 以上の RAM を搭載した ARM64 Android スマートフォン（2015年以降）。[Termux](https://github.com/termux/termux-app) をインストールし、`proot` を使用して PicoClaw を実行します。
+
+> セットアップ手順は [README：古い Android スマートフォンで実行](../../README.ja.md#-run-on-old-android-phones) を参照してください。
+
+### デスクトップ / サーバー / クラウド
+
+| プラットフォーム | 備考 |
+|------------------|------|
+| x86_64 Linux | ネイティブバイナリ、依存関係なし |
+| x86_64 Windows | ネイティブバイナリ |
+| macOS (Intel / Apple Silicon) | ネイティブバイナリ |
+| Docker (any platform) | `docker compose` ワンライナー、[Docker ガイド](docker.md) を参照 |
+| OpenWrt routers | MIPS/ARM ビルド、32MB 以上の空きメモリが必要 |
+| FreeBSD / NetBSD | x86_64 および arm64 ビルドが利用可能 |
+
+---
+
+## 5. 最小要件
+
+| リソース | 最小 | 推奨 |
+|----------|------|------|
+| RAM | 10MB 空き | 32MB 以上空き |
+| ストレージ | 20MB（バイナリ） | 50MB 以上（ワークスペース含む） |
+| CPU | 任意（シングルコア 0.6GHz 以上） | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| ネットワーク | 必須（LLM API 呼び出し用） | イーサネットまたは WiFi |
+
+---
+
+## 6. テストと貢献の方法
+
+```bash
+# 1. お使いのアーキテクチャ向けをダウンロード
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. 初期化
+./picoclaw onboard
+
+# 3. テスト
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+利用可能なビルド：`linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### ハードウェアを追加する
+
+1. このリポジトリをフォーク
+2. 該当するテーブルにチップ/製品/ボードを追加
+3. 名前、アーキテクチャ、SoC、RAM、年、リンク（あれば）を含める
+4. PR を送信
+
+ハードウェアベンダーの方へ：公式サポートの追加や共同プロモーションをご希望ですか？Issue を作成するか、[Discord](https://discord.gg/V4sAZ9XWpN) でお問い合わせください。
diff --git a/docs/ja/providers.md b/docs/ja/providers.md
index 2323a27cc..9a53a4b69 100644
--- a/docs/ja/providers.md
+++ b/docs/ja/providers.md
@@ -93,7 +93,7 @@
],
"agents": {
"defaults": {
- "model": "gpt-5.4"
+ "model_name": "gpt-5.4"
}
}
}
@@ -266,7 +266,7 @@ PicoClaw はリクエスト送信前に外側の `litellm/` プレフィック
],
"agents": {
"defaults": {
- "model": "glm-4.7"
+ "model_name": "glm-4.7"
}
}
}
@@ -298,7 +298,7 @@ PicoClaw はプロトコルファミリーごとに Provider をルーティン
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
- "model": "glm-4.7",
+ "model_name": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
@@ -328,12 +328,11 @@ picoclaw agent -m "こんにちは"
{
"agents": {
"defaults": {
- "model": "anthropic/claude-opus-4-5"
+ "model_name": "anthropic/claude-opus-4-5"
}
},
"session": {
- "dm_scope": "per-channel-peer",
- "backlog_limit": 20
+ "dm_scope": "per-channel-peer"
},
"providers": {
"openrouter": {
diff --git a/docs/ja/tools_configuration.md b/docs/ja/tools_configuration.md
index e4568f6ae..c946bf088 100644
--- a/docs/ja/tools_configuration.md
+++ b/docs/ja/tools_configuration.md
@@ -41,14 +41,6 @@ Web ツールはウェブ検索とフェッチに使用されます。
| `fetch_limit_bytes` | int | 10485760 | 取得するウェブページペイロードの最大サイズ（バイト単位、デフォルトは10MB）。 |
| `format` | string | "plaintext" | 取得コンテンツの出力形式。オプション：`plaintext` または `markdown`（推奨）。 |
-### Brave
-
-| 設定項目 | 型 | デフォルト | 説明 |
-|---------------|--------|------------|-----------------------|
-| `enabled` | bool | false | Brave 検索を有効にする |
-| `api_key` | string | - | Brave Search API キー |
-| `max_results` | int | 5 | 最大結果数 |
-
### DuckDuckGo
| 設定項目 | 型 | デフォルト | 説明 |
@@ -56,13 +48,73 @@ Web ツールはウェブ検索とフェッチに使用されます。
| `enabled` | bool | true | DuckDuckGo 検索を有効にする |
| `max_results` | int | 5 | 最大結果数 |
+### Baidu Search
+
+| 設定項目 | 型 | デフォルト | 説明 |
+|---------------|--------|-----------------------------------------------------------------|-------------------------------|
+| `enabled` | bool | false | Baidu 検索を有効にする |
+| `api_key` | string | - | Qianfan API キー |
+| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | Baidu Search API URL |
+| `max_results` | int | 10 | 最大結果数 |
+
+```json
+{
+ "tools": {
+ "web": {
+ "baidu_search": {
+ "enabled": true,
+ "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+ "max_results": 10
+ }
+ }
+ }
+}
+```
+
### Perplexity
| 設定項目 | 型 | デフォルト | 説明 |
|---------------|--------|------------|---------------------------|
-| `enabled` | bool | false | Perplexity 検索を有効にする |
-| `api_key` | string | - | Perplexity API キー |
-| `max_results` | int | 5 | 最大結果数 |
+| `enabled` | bool | false | Perplexity 検索を有効にする |
+| `api_key` | string | - | Perplexity API キー |
+| `api_keys` | string[] | - | 複数の Perplexity API キー（ローテーション用、`api_key` より優先） |
+| `max_results` | int | 5 | 最大結果数 |
+
+### Brave
+
+| 設定項目 | 型 | デフォルト | 説明 |
+|---------------|--------|------------|-----------------------|
+| `enabled` | bool | false | Brave 検索を有効にする |
+| `api_key` | string | - | Brave Search API キー |
+| `api_keys` | string[] | - | 複数の Brave Search API キー（ローテーション用、`api_key` より優先） |
+| `max_results` | int | 5 | 最大結果数 |
+
+### Tavily
+
+| 設定項目 | 型 | デフォルト | 説明 |
+|---------------|--------|------------|-----------------------------------|
+| `enabled` | bool | false | Tavily 検索を有効にする |
+| `api_key` | string | - | Tavily API キー |
+| `base_url` | string | - | カスタム Tavily API ベース URL |
+| `max_results` | int | 0 | 最大結果数（0 = デフォルト） |
+
+### SearXNG
+
+| 設定項目 | 型 | デフォルト | 説明 |
+|---------------|--------|--------------------------|---------------------------|
+| `enabled` | bool | false | SearXNG 検索を有効にする |
+| `base_url` | string | `http://localhost:8888` | SearXNG インスタンス URL |
+| `max_results` | int | 5 | 最大結果数 |
+
+### GLM Search
+
+| 設定項目 | 型 | デフォルト | 説明 |
+|-----------------|--------|------------------------------------------------------|---------------------------|
+| `enabled` | bool | false | GLM Search を有効にする |
+| `api_key` | string | - | GLM API キー |
+| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | GLM Search API URL |
+| `search_engine` | string | `search_std` | 検索エンジンタイプ |
+| `max_results` | int | 5 | 最大結果数 |
## Exec ツール
@@ -70,9 +122,32 @@ Exec ツールはシェルコマンドの実行に使用されます。
| 設定項目 | 型 | デフォルト | 説明 |
|------------------------|-------|------------|------------------------------------|
+| `enabled` | bool | true | Exec ツールを有効にする |
| `enable_deny_patterns` | bool | true | デフォルトの危険コマンドブロックを有効にする |
| `custom_deny_patterns` | array | [] | カスタム拒否パターン（正規表現） |
+### Exec ツールの無効化
+
+`exec` ツールを完全に無効にするには、`enabled` を `false` に設定します：
+
+**設定ファイル経由：**
+```json
+{
+ "tools": {
+ "exec": {
+ "enabled": false
+ }
+ }
+}
+```
+
+**環境変数経由：**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **注意：** 無効にすると、エージェントはシェルコマンドを実行できなくなります。これは Cron ツールがスケジュールされたシェルコマンドを実行する能力にも影響します。
+
### 機能
- **`enable_deny_patterns`**：`false` に設定すると、デフォルトの危険コマンドブロックパターンを完全に無効にします
@@ -329,6 +404,7 @@ Skills ツールは ClawHub などのレジストリを通じたスキルの発
例：
- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
- `PICOCLAW_TOOLS_MCP_ENABLED=true`
diff --git a/docs/ja/troubleshooting.md b/docs/ja/troubleshooting.md
index 1c98224b9..f18b456db 100644
--- a/docs/ja/troubleshooting.md
+++ b/docs/ja/troubleshooting.md
@@ -16,7 +16,7 @@
**修正方法：** `~/.picoclaw/config.json`（またはお使いの設定パス）で：
-1. **agents.defaults.model** は `model_list` 内の `model_name` と一致する必要があります（例：`"openrouter-free"`）。
+1. **agents.defaults.model_name** は `model_list` 内の `model_name` と一致する必要があります（例：`"openrouter-free"`）。
2. そのエントリの **model** は有効な OpenRouter モデル ID である必要があります。例：
- `"openrouter/free"` – 自動無料枠
- `"google/gemini-2.0-flash-exp:free"`
@@ -28,7 +28,7 @@
{
"agents": {
"defaults": {
- "model": "openrouter-free"
+ "model_name": "openrouter-free"
}
},
"model_list": [
diff --git a/docs/migration/model-list-migration.md b/docs/migration/model-list-migration.md
index eed228d4d..9d05ac599 100644
--- a/docs/migration/model-list-migration.md
+++ b/docs/migration/model-list-migration.md
@@ -70,7 +70,7 @@ The new `model_list` configuration offers several advantages:
],
"agents": {
"defaults": {
- "model": "gpt4"
+ "model_name": "gpt4"
}
}
}
@@ -184,7 +184,7 @@ During the migration period, your existing `providers` configuration will contin
- [ ] Identify all providers you're currently using
- [ ] Create `model_list` entries for each provider
- [ ] Use appropriate protocol prefixes
-- [ ] Update `agents.defaults.model` to reference the new `model_name`
+- [ ] Update `agents.defaults.model_name` to reference the new `model_name`
- [ ] Test that all models work correctly
- [ ] Remove or comment out the old `providers` section
@@ -196,7 +196,7 @@ During the migration period, your existing `providers` configuration will contin
model "xxx" not found in model_list or providers
```
-**Solution**: Ensure the `model_name` in `model_list` matches the value in `agents.defaults.model`.
+**Solution**: Ensure the `model_name` in `model_list` matches the value in `agents.defaults.model_name`.
### Unknown protocol error
diff --git a/docs/providers.md b/docs/providers.md
index e62cbb969..3a740d3b8 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -5,7 +5,7 @@
### Providers
> [!NOTE]
-> Groq provides free voice transcription via Whisper. If configured, audio messages from any channel will be automatically transcribed at the agent level.
+> Voice transcription can use a configured multimodal model via `voice.model_name`. Groq Whisper remains available as a fallback when no voice model is configured.
| Provider | Purpose | Get API Key |
| ------------ | --------------------------------------- | ------------------------------------------------------------ |
@@ -95,7 +95,34 @@ This design also enables **multi-agent support** with flexible provider selectio
],
"agents": {
"defaults": {
- "model": "gpt-5.4"
+ "model_name": "gpt-5.4"
+ }
+ }
+}
+```
+
+#### Voice Transcription
+
+You can configure a dedicated model for audio transcription with `voice.model_name`. This lets you reuse existing multimodal providers that support audio input instead of relying only on Groq.
+
+If `voice.model_name` is not configured, PicoClaw will continue to fall back to Groq transcription when a Groq API key is available.
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "voice-gemini",
+ "model": "gemini/gemini-2.5-flash",
+ "api_key": "your-gemini-key"
+ }
+ ],
+ "voice": {
+ "model_name": "voice-gemini",
+ "echo_transcription": false
+ },
+ "providers": {
+ "groq": {
+ "api_key": "gsk_xxx"
}
}
}
@@ -268,13 +295,13 @@ The old `providers` configuration is **deprecated** but still supported for back
],
"agents": {
"defaults": {
- "model": "glm-4.7"
+ "model_name": "glm-4.7"
}
}
}
```
-For detailed migration guide, see [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
+For detailed migration guide, see [migration/model-list-migration.md](migration/model-list-migration.md).
### Provider Architecture
@@ -300,7 +327,7 @@ This keeps the runtime lightweight while making new OpenAI-compatible backends m
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
- "model": "glm-4.7",
+ "model_name": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
@@ -330,12 +357,11 @@ picoclaw agent -m "Hello"
{
"agents": {
"defaults": {
- "model": "anthropic/claude-opus-4-5"
+ "model_name": "anthropic/claude-opus-4-5"
}
},
"session": {
- "dm_scope": "per-channel-peer",
- "backlog_limit": 20
+ "dm_scope": "per-channel-peer"
},
"providers": {
"openrouter": {
@@ -345,6 +371,10 @@ picoclaw agent -m "Hello"
"api_key": "gsk_xxx"
}
},
+ "voice": {
+ "model_name": "voice-gemini",
+ "echo_transcription": false
+ },
"channels": {
"telegram": {
"enabled": true,
diff --git a/docs/pt-br/ANTIGRAVITY_AUTH.md b/docs/pt-br/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..d243783cb
--- /dev/null
+++ b/docs/pt-br/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,809 @@
+> Voltar ao [README](../../README.pt-br.md)
+
+# Guia de Autenticação e Integração do Antigravity
+
+## Visão Geral
+
+**Antigravity** (Google Cloud Code Assist) é um provedor de modelos de IA apoiado pelo Google que oferece acesso a modelos como Claude Opus 4.6 e Gemini através da infraestrutura de nuvem do Google. Este documento fornece um guia completo sobre como a autenticação funciona, como buscar modelos e como implementar um novo provedor no PicoClaw.
+
+---
+
+## Índice
+
+1. [Fluxo de Autenticação](#fluxo-de-autenticação)
+2. [Detalhes da Implementação OAuth](#detalhes-da-implementação-oauth)
+3. [Gerenciamento de Tokens](#gerenciamento-de-tokens)
+4. [Busca da Lista de Modelos](#busca-da-lista-de-modelos)
+5. [Rastreamento de Uso](#rastreamento-de-uso)
+6. [Estrutura do Plugin do Provedor](#estrutura-do-plugin-do-provedor)
+7. [Requisitos de Integração](#requisitos-de-integração)
+8. [Endpoints da API](#endpoints-da-api)
+9. [Configuração](#configuração)
+10. [Criando um Novo Provedor no PicoClaw](#criando-um-novo-provedor-no-picoclaw)
+
+---
+
+## Fluxo de Autenticação
+
+### 1. OAuth 2.0 com PKCE
+
+O Antigravity utiliza **OAuth 2.0 com PKCE (Proof Key for Code Exchange)** para autenticação segura:
+
+```
+┌─────────────┐ ┌─────────────────┐
+│ Client │ ───(1) Generate PKCE Pair────────> │ │
+│ │ ───(2) Open Auth URL─────────────> │ Google OAuth │
+│ │ │ Server │
+│ │ <──(3) Redirect with Code───────── │ │
+│ │ └─────────────────┘
+│ │ ───(4) Exchange Code for Tokens──> │ Token URL │
+│ │ │ │
+│ │ <──(5) Access + Refresh Tokens──── │ │
+└─────────────┘ └─────────────────┘
+```
+
+### 2. Etapas Detalhadas
+
+#### Etapa 1: Gerar Parâmetros PKCE
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+ const verifier = randomBytes(32).toString("hex");
+ const challenge = createHash("sha256").update(verifier).digest("base64url");
+ return { verifier, challenge };
+}
+```
+
+#### Etapa 2: Construir a URL de Autorização
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+ const url = new URL(AUTH_URL);
+ url.searchParams.set("client_id", CLIENT_ID);
+ url.searchParams.set("response_type", "code");
+ url.searchParams.set("redirect_uri", REDIRECT_URI);
+ url.searchParams.set("scope", SCOPES.join(" "));
+ url.searchParams.set("code_challenge", params.challenge);
+ url.searchParams.set("code_challenge_method", "S256");
+ url.searchParams.set("state", params.state);
+ url.searchParams.set("access_type", "offline");
+ url.searchParams.set("prompt", "consent");
+ return url.toString();
+}
+```
+
+**Escopos Necessários:**
+```typescript
+const SCOPES = [
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/userinfo.email",
+ "https://www.googleapis.com/auth/userinfo.profile",
+ "https://www.googleapis.com/auth/cclog",
+ "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### Etapa 3: Tratar o Callback OAuth
+
+**Modo Automático (Desenvolvimento Local):**
+- Iniciar um servidor HTTP local na porta 51121
+- Aguardar o redirecionamento do Google
+- Extrair o código de autorização dos parâmetros da query
+
+**Modo Manual (Remoto/Sem Interface Gráfica):**
+- Exibir a URL de autorização para o usuário
+- O usuário completa a autenticação no navegador
+- O usuário cola a URL de redirecionamento completa no terminal
+- Analisar o código da URL colada
+
+#### Etapa 4: Trocar o Código por Tokens
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+ code: string;
+ verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+ const response = await fetch(TOKEN_URL, {
+ method: "POST",
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
+ body: new URLSearchParams({
+ client_id: CLIENT_ID,
+ client_secret: CLIENT_SECRET,
+ code: params.code,
+ grant_type: "authorization_code",
+ redirect_uri: REDIRECT_URI,
+ code_verifier: params.verifier,
+ }),
+ });
+
+ const data = await response.json();
+
+ return {
+ access: data.access_token,
+ refresh: data.refresh_token,
+ expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+ };
+}
+```
+
+#### Etapa 5: Buscar Dados Adicionais do Usuário
+
+**E-mail do Usuário:**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise {
+ const response = await fetch(
+ "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+ { headers: { Authorization: `Bearer ${accessToken}` } }
+ );
+ const data = await response.json();
+ return data.email;
+}
+```
+
+**ID do Projeto (Necessário para chamadas de API):**
+```typescript
+async function fetchProjectId(accessToken: string): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "google-api-nodejs-client/9.15.1",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ "Client-Metadata": JSON.stringify({
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ }),
+ };
+
+ const response = await fetch(
+ "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({
+ metadata: {
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ const data = await response.json();
+ return data.cloudaicompanionProject || "rising-fact-p41fc"; // Valor padrão de fallback
+}
+```
+
+---
+
+## Detalhes da Implementação OAuth
+
+### Credenciais do Cliente
+
+**Importante:** Estas são codificadas em base64 no código-fonte para sincronização com pi-ai:
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+ "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### Modos do Fluxo OAuth
+
+1. **Fluxo Automático** (máquinas locais com navegador):
+ - Abre o navegador automaticamente
+ - O servidor de callback local captura o redirecionamento
+ - Nenhuma interação do usuário necessária após a autenticação inicial
+
+2. **Fluxo Manual** (remoto/sem interface/WSL2):
+ - URL exibida para copiar e colar manualmente
+ - O usuário completa a autenticação em um navegador externo
+ - O usuário cola a URL de redirecionamento completa de volta
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+ return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## Gerenciamento de Tokens
+
+### Estrutura do Perfil de Autenticação
+
+```typescript
+type OAuthCredential = {
+ type: "oauth";
+ provider: "google-antigravity";
+ access: string; // Token de acesso
+ refresh: string; // Token de atualização
+ expires: number; // Timestamp de expiração (ms desde epoch)
+ email?: string; // E-mail do usuário
+ projectId?: string; // ID do projeto Google Cloud
+};
+```
+
+### Atualização de Tokens
+
+A credencial inclui um token de atualização que pode ser usado para obter novos tokens de acesso quando o atual expira. A expiração é definida com um buffer de 5 minutos para evitar condições de corrida.
+
+---
+
+## Busca da Lista de Modelos
+
+### Buscar Modelos Disponíveis
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+ accessToken: string,
+ projectId: string
+): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ };
+
+ const response = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ const data = await response.json();
+
+ // Retorna modelos com informações de cota
+ return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+ id: modelId,
+ displayName: modelInfo.displayName,
+ quotaInfo: {
+ remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+ resetTime: modelInfo.quotaInfo?.resetTime,
+ isExhausted: modelInfo.quotaInfo?.isExhausted,
+ },
+ }));
+}
+```
+
+### Formato da Resposta
+
+```typescript
+type FetchAvailableModelsResponse = {
+ models?: Record;
+};
+```
+
+---
+
+## Rastreamento de Uso
+
+### Buscar Dados de Uso
+
+```typescript
+export async function fetchAntigravityUsage(
+ token: string,
+ timeoutMs: number
+): Promise {
+ // 1. Buscar créditos e informações do plano
+ const loadCodeAssistRes = await fetch(
+ `${BASE_URL}/v1internal:loadCodeAssist`,
+ {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${token}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ metadata: {
+ ideType: "ANTIGRAVITY",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ // Extrair informações de créditos
+ const { availablePromptCredits, planInfo, currentTier } = data;
+
+ // 2. Buscar cotas dos modelos
+ const modelsRes = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers: { Authorization: `Bearer ${token}` },
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ // Construir janelas de uso
+ return {
+ provider: "google-antigravity",
+ displayName: "Google Antigravity",
+ windows: [
+ { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+ // Cotas individuais dos modelos...
+ ],
+ plan: currentTier?.name || planType,
+ };
+}
+```
+
+### Estrutura da Resposta de Uso
+
+```typescript
+type ProviderUsageSnapshot = {
+ provider: "google-antigravity";
+ displayName: string;
+ windows: UsageWindow[];
+ plan?: string;
+ error?: string;
+};
+
+type UsageWindow = {
+ label: string; // "Credits" ou ID do modelo
+ usedPercent: number; // 0-100
+ resetAt?: number; // Timestamp de quando a cota é redefinida
+};
+```
+
+---
+
+## Estrutura do Plugin do Provedor
+
+### Definição do Plugin
+
+```typescript
+const antigravityPlugin = {
+ id: "google-antigravity-auth",
+ name: "Google Antigravity Auth",
+ description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+ configSchema: emptyPluginConfigSchema(),
+
+ register(api: PicoClawPluginApi) {
+ api.registerProvider({
+ id: "google-antigravity",
+ label: "Google Antigravity",
+ docsPath: "/providers/models",
+ aliases: ["antigravity"],
+
+ auth: [
+ {
+ id: "oauth",
+ label: "Google OAuth",
+ hint: "PKCE + localhost callback",
+ kind: "oauth",
+ run: async (ctx: ProviderAuthContext) => {
+ // Implementação OAuth aqui
+ },
+ },
+ ],
+ });
+ },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+ config: PicoClawConfig;
+ agentDir?: string;
+ workspaceDir?: string;
+ prompter: WizardPrompter; // Prompts/notificações da UI
+ runtime: RuntimeEnv; // Logging, etc.
+ isRemote: boolean; // Se está executando remotamente
+ openUrl: (url: string) => Promise; // Abridor de navegador
+ oauth: {
+ createVpsAwareHandlers: Function;
+ };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+ profiles: Array<{
+ profileId: string;
+ credential: AuthProfileCredential;
+ }>;
+ configPatch?: Partial;
+ defaultModel?: string;
+ notes?: string[];
+};
+```
+
+---
+
+## Requisitos de Integração
+
+### 1. Ambiente/Dependências Necessários
+
+- Go ≥ 1.25
+- Base de código do PicoClaw (`pkg/providers/` e `pkg/auth/`)
+- Pacotes da biblioteca padrão `crypto` e `net/http`
+
+### 2. Cabeçalhos Necessários para Chamadas de API
+
+```typescript
+const REQUIRED_HEADERS = {
+ "Authorization": `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity", // ou "google-api-nodejs-client/9.15.1"
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// Para chamadas loadCodeAssist, incluir também:
+const CLIENT_METADATA = {
+ ideType: "ANTIGRAVITY", // ou "IDE_UNSPECIFIED"
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+};
+```
+
+### 3. Sanitização de Schemas de Modelos
+
+O Antigravity usa modelos compatíveis com Gemini, então os schemas de ferramentas devem ser sanitizados:
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+ "patternProperties",
+ "additionalProperties",
+ "$schema",
+ "$id",
+ "$ref",
+ "$defs",
+ "definitions",
+ "examples",
+ "minLength",
+ "maxLength",
+ "minimum",
+ "maximum",
+ "multipleOf",
+ "pattern",
+ "format",
+ "minItems",
+ "maxItems",
+ "uniqueItems",
+ "minProperties",
+ "maxProperties",
+]);
+
+// Limpar schema antes de enviar
+function cleanToolSchemaForGemini(schema: Record): unknown {
+ // Remover palavras-chave não suportadas
+ // Garantir que o nível superior tenha type: "object"
+ // Achatar uniões anyOf/oneOf
+}
+```
+
+### 4. Tratamento de Blocos de Pensamento (Modelos Claude)
+
+Para modelos Claude via Antigravity, os blocos de pensamento requerem tratamento especial:
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+ messages: AgentMessage[]
+): AgentMessage[] {
+ // Validar assinaturas de pensamento
+ // Normalizar campos de assinatura
+ // Descartar blocos de pensamento não assinados
+}
+```
+
+---
+
+## Endpoints da API
+
+### Endpoints de Autenticação
+
+| Endpoint | Método | Finalidade |
+|----------|--------|-----------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | Autorização OAuth |
+| `https://oauth2.googleapis.com/token` | POST | Troca de tokens |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | Informações do usuário (e-mail) |
+
+### Endpoints do Cloud Code Assist
+
+| Endpoint | Método | Finalidade |
+|----------|--------|-----------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | Carregar informações do projeto, créditos, plano |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | Listar modelos disponíveis com cotas |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | Endpoint de streaming de chat |
+
+**Formato de Requisição da API (Chat):**
+O endpoint `v1internal:streamGenerateContent` espera um envelope encapsulando a requisição Gemini padrão:
+
+```json
+{
+ "project": "your-project-id",
+ "model": "model-id",
+ "request": {
+ "contents": [...],
+ "systemInstruction": {...},
+ "generationConfig": {...},
+ "tools": [...]
+ },
+ "requestType": "agent",
+ "userAgent": "antigravity",
+ "requestId": "agent-timestamp-random"
+}
+```
+
+**Formato de Resposta da API (SSE):**
+Cada mensagem SSE (`data: {...}`) é encapsulada em um campo `response`:
+
+```json
+{
+ "response": {
+ "candidates": [...],
+ "usageMetadata": {...},
+ "modelVersion": "...",
+ "responseId": "..."
+ },
+ "traceId": "...",
+ "metadata": {}
+}
+```
+
+---
+
+## Configuração
+
+### Configuração do config.json
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gemini-flash",
+ "model": "antigravity/gemini-3-flash",
+ "auth_method": "oauth"
+ }
+ ],
+ "agents": {
+ "defaults": {
+ "model_name": "gemini-flash"
+ }
+ }
+}
+```
+
+### Armazenamento do Perfil de Autenticação
+
+Os perfis de autenticação são armazenados em `~/.picoclaw/auth.json`:
+
+```json
+{
+ "credentials": {
+ "google-antigravity": {
+ "access_token": "ya29...",
+ "refresh_token": "1//...",
+ "expires_at": "2026-01-01T00:00:00Z",
+ "provider": "google-antigravity",
+ "auth_method": "oauth",
+ "email": "user@example.com",
+ "project_id": "my-project-id"
+ }
+ }
+}
+```
+
+---
+
+## Criando um Novo Provedor no PicoClaw
+
+Os provedores do PicoClaw são implementados como pacotes Go em `pkg/providers/`. Para adicionar um novo provedor:
+
+### Implementação Passo a Passo
+
+#### 1. Criar o Arquivo do Provedor
+
+Crie um novo arquivo Go em `pkg/providers/`:
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. Implementar a Interface Provider
+
+Seu provedor deve implementar a interface `Provider` definida em `pkg/providers/types.go`:
+
+```go
+package providers
+
+type YourProvider struct {
+ apiKey string
+ apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+ if apiBase == "" {
+ apiBase = "https://api.your-provider.com/v1"
+ }
+ return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+ // Implementar conclusão de chat com streaming
+}
+```
+
+#### 3. Registrar na Factory
+
+Adicione seu provedor ao switch de protocolo em `pkg/providers/factory.go`:
+
+```go
+case "your-provider":
+ return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. Adicionar Configuração Padrão (Opcional)
+
+Adicione uma entrada padrão em `pkg/config/defaults.go`:
+
+```go
+{
+ ModelName: "your-model",
+ Model: "your-provider/model-name",
+ APIKey: "",
+},
+```
+
+#### 5. Adicionar Suporte de Autenticação (Opcional)
+
+Se seu provedor requer OAuth ou autenticação especial, adicione um caso em `cmd/picoclaw/internal/auth/helpers.go`:
+
+```go
+case "your-provider":
+ authLoginYourProvider()
+```
+
+#### 6. Configurar via `config.json`
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "your-model",
+ "model": "your-provider/model-name",
+ "api_key": "your-api-key",
+ "api_base": "https://api.your-provider.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## Testando Sua Implementação
+
+### Comandos CLI
+
+```bash
+# Autenticar com um provedor
+picoclaw auth login --provider your-provider
+
+# Listar modelos (para Antigravity)
+picoclaw auth models
+
+# Iniciar o gateway
+picoclaw gateway
+
+# Executar um agente com um modelo específico
+picoclaw agent -m "Hello" --model your-model
+```
+
+### Variáveis de Ambiente para Testes
+
+```bash
+# Substituir o modelo padrão
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# Substituir configurações do provedor
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## Referências
+
+- **Arquivos Fonte:**
+ - `pkg/providers/antigravity_provider.go` - Implementação do provedor Antigravity
+ - `pkg/auth/oauth.go` - Implementação do fluxo OAuth
+ - `pkg/auth/store.go` - Armazenamento de credenciais de autenticação (`~/.picoclaw/auth.json`)
+ - `pkg/providers/factory.go` - Factory de provedores e roteamento de protocolo
+ - `pkg/providers/types.go` - Definições da interface do provedor
+ - `cmd/picoclaw/internal/auth/helpers.go` - Comandos CLI de autenticação
+
+- **Documentação:**
+ - `docs/ANTIGRAVITY_USAGE.md` - Guia de uso do Antigravity
+ - `docs/migration/model-list-migration.md` - Guia de migração
+
+---
+
+## Observações
+
+1. **Projeto Google Cloud:** O Antigravity requer que o Gemini for Google Cloud esteja habilitado no seu projeto Google Cloud
+2. **Cotas:** Usa cotas do projeto Google Cloud (sem cobrança separada)
+3. **Acesso a Modelos:** Os modelos disponíveis dependem da configuração do seu projeto Google Cloud
+4. **Blocos de Pensamento:** Modelos Claude via Antigravity requerem tratamento especial de blocos de pensamento com assinaturas
+5. **Sanitização de Schemas:** Os schemas de ferramentas devem ser sanitizados para remover palavras-chave JSON Schema não suportadas
+
+---
+
+---
+
+## Tratamento de Erros Comuns
+
+### 1. Limitação de Taxa (HTTP 429)
+
+O Antigravity retorna um erro 429 quando as cotas do projeto/modelo estão esgotadas. A resposta de erro frequentemente contém um `quotaResetDelay` no campo `details`.
+
+**Exemplo de Erro 429:**
+```json
+{
+ "error": {
+ "code": 429,
+ "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+ "status": "RESOURCE_EXHAUSTED",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+ "metadata": {
+ "quotaResetDelay": "4h30m28.060903746s"
+ }
+ }
+ ]
+ }
+}
+```
+
+### 2. Respostas Vazias (Modelos Restritos)
+
+Alguns modelos podem aparecer na lista de modelos disponíveis, mas retornar uma resposta vazia (200 OK mas stream SSE vazio). Isso geralmente acontece com modelos em preview ou restritos que o projeto atual não tem permissão para usar.
+
+**Tratamento:** Tratar respostas vazias como erros informando ao usuário que o modelo pode estar restrito ou inválido para seu projeto.
+
+---
+
+## Solução de Problemas
+
+### "Token expired" (token expirado)
+- Atualizar tokens OAuth: `picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled" (Gemini for Google Cloud não está habilitado)
+- Habilitar a API no seu Google Cloud Console
+
+### "Project not found" (projeto não encontrado)
+- Verificar se seu projeto Google Cloud tem as APIs necessárias habilitadas
+- Verificar se o ID do projeto foi obtido corretamente durante a autenticação
+
+### Modelos não aparecem na lista
+- Verificar se a autenticação OAuth foi concluída com sucesso
+- Verificar o armazenamento do perfil de autenticação: `~/.picoclaw/auth.json`
+- Executar novamente `picoclaw auth login --provider antigravity`
diff --git a/docs/pt-br/ANTIGRAVITY_USAGE.md b/docs/pt-br/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..d4b681ad0
--- /dev/null
+++ b/docs/pt-br/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> Voltar ao [README](../../README.pt-br.md)
+
+# Usando o provedor Antigravity no PicoClaw
+
+Este guia explica como configurar e usar o provedor **Antigravity** (Google Cloud Code Assist) no PicoClaw.
+
+## Pré-requisitos
+
+1. Uma conta Google.
+2. Google Cloud Code Assist habilitado (geralmente disponível através da integração "Gemini for Google Cloud").
+
+## 1. Autenticação
+
+Para se autenticar com o Antigravity, execute o seguinte comando:
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### Autenticação manual (Headless/VPS)
+Se você está executando em um servidor (Coolify/Docker) e não consegue acessar `localhost`, siga estas etapas:
+1. Execute o comando acima.
+2. Copie a URL fornecida e abra-a no seu navegador local.
+3. Complete o login.
+4. Seu navegador será redirecionado para uma URL `localhost:51121` (que não carregará).
+5. **Copie essa URL final** da barra de endereços do seu navegador.
+6. **Cole-a de volta no terminal** onde o PicoClaw está aguardando.
+
+O PicoClaw extrairá automaticamente o código de autorização e completará o processo.
+
+## 2. Gerenciando modelos
+
+### Listar modelos disponíveis
+Para ver quais modelos seu projeto tem acesso e verificar suas cotas:
+
+```bash
+picoclaw auth models
+```
+
+### Trocar de modelo
+Você pode alterar o modelo padrão em `~/.picoclaw/config.json` ou substituí-lo via CLI:
+
+```bash
+# Substituir para um único comando
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. Uso em produção (Coolify/Docker)
+
+Se você está implantando via Coolify ou Docker, siga estas etapas para testar:
+
+1. **Variáveis de ambiente**:
+ * `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2. **Persistência da autenticação**:
+ Se você já fez login localmente, pode copiar suas credenciais para o servidor:
+ ```bash
+ scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+ ```
+ *Alternativamente*, execute o comando `auth login` uma vez no servidor se você tiver acesso ao terminal.
+
+## 4. Solução de problemas
+
+* **Resposta vazia**: Se um modelo retorna uma resposta vazia, ele pode estar restrito para o seu projeto. Tente `gemini-3-flash` ou `claude-opus-4-6-thinking`.
+* **429 Limite de taxa**: O Antigravity possui cotas rigorosas. O PicoClaw exibirá o "tempo de redefinição" na mensagem de erro se você atingir um limite.
+* **404 Não encontrado**: Certifique-se de que está usando um ID de modelo da lista `picoclaw auth models`. Use o ID curto (ex.: `gemini-3-flash`) e não o caminho completo.
+
+## 5. Resumo dos modelos funcionais
+
+Com base nos testes, os seguintes modelos são os mais confiáveis:
+* `gemini-3-flash` (Rápido, alta disponibilidade)
+* `gemini-2.5-flash-lite` (Leve)
+* `claude-opus-4-6-thinking` (Poderoso, inclui raciocínio)
diff --git a/docs/pt-br/chat-apps.md b/docs/pt-br/chat-apps.md
index 5f18080f0..4fa59b1b2 100644
--- a/docs/pt-br/chat-apps.md
+++ b/docs/pt-br/chat-apps.md
@@ -8,23 +8,25 @@ Converse com seu picoclaw através do Telegram, Discord, WhatsApp, Matrix, QQ, D
> **Nota**: Todos os canais baseados em webhook (LINE, WeCom, etc.) são servidos em um único servidor HTTP Gateway compartilhado (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`). Não há portas por canal para configurar. Nota: Feishu usa o modo WebSocket/SDK e não utiliza o servidor HTTP webhook compartilhado.
-| Channel | Setup |
-| ------------ | ---------------------------------- |
-| **Telegram** | Easy (just a token) |
-| **Discord** | Easy (bot token + intents) |
-| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
-| **Matrix** | Medium (homeserver + bot access token) |
-| **QQ** | Easy (AppID + AppSecret) |
-| **DingTalk** | Medium (app credentials) |
-| **LINE** | Medium (credentials + webhook URL) |
-| **WeCom AI Bot** | Medium (Token + AES key) |
-| **Feishu** | Medium (App ID + Secret, WebSocket mode) |
-| **Slack** | Medium (Bot token + App token) |
-| **IRC** | Medium (server + TLS config) |
-| **OneBot** | Medium (QQ via OneBot protocol) |
-| **MaixCam** | Easy (Sipeed hardware integration) |
-| **Pico** | Native PicoClaw protocol |
+| Canal | Dificuldade | Descrição | Documentação |
+| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Telegram** | ⭐ Fácil | Recomendado, voz para texto, long polling (sem IP público) | [Documentação](../channels/telegram/README.pt-br.md) |
+| **Discord** | ⭐ Fácil | Socket Mode, suporte a grupos/DM, ecossistema bot rico | [Documentação](../channels/discord/README.pt-br.md) |
+| **WhatsApp** | ⭐ Fácil | Nativo (scan QR) ou Bridge URL | [Documentação](#whatsapp) |
+| **Weixin** | ⭐ Fácil | Scan QR nativo (API Tencent iLink) | [Documentação](#weixin) |
+| **Slack** | ⭐ Fácil | **Socket Mode** (sem IP público), empresarial | [Documentação](../channels/slack/README.pt-br.md) |
+| **Matrix** | ⭐⭐ Médio | Protocolo federado, suporte a auto-hospedagem | [Documentação](../channels/matrix/README.pt-br.md) |
+| **QQ** | ⭐⭐ Médio | API bot oficial, comunidade chinesa | [Documentação](../channels/qq/README.pt-br.md) |
+| **DingTalk** | ⭐⭐ Médio | Modo Stream (sem IP público), empresarial | [Documentação](../channels/dingtalk/README.pt-br.md) |
+| **LINE** | ⭐⭐⭐ Avançado | HTTPS Webhook obrigatório | [Documentação](../channels/line/README.pt-br.md) |
+| **WeCom (企业微信)** | ⭐⭐⭐ Avançado | Bot de grupo (Webhook), app personalizado (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.pt-br.md) / [App](../channels/wecom/wecom_app/README.pt-br.md) / [AI Bot](../channels/wecom/wecom_aibot/README.pt-br.md) |
+| **Feishu (飞书)** | ⭐⭐⭐ Avançado | Colaboração empresarial, rico em recursos | [Documentação](../channels/feishu/README.pt-br.md) |
+| **IRC** | ⭐⭐ Médio | Servidor + configuração TLS | [Documentação](#irc) |
+| **OneBot** | ⭐⭐ Médio | Compatível com NapCat/Go-CQHTTP, ecossistema comunitário | [Documentação](../channels/onebot/README.pt-br.md) |
+| **MaixCam** | ⭐ Fácil | Canal de integração de hardware para câmeras AI Sipeed | [Documentação](../channels/maixcam/README.pt-br.md) |
+| **Pico** | ⭐ Fácil | Canal de protocolo nativo PicoClaw | |
+
Telegram (Recomendado)
+
Discord
+
WhatsApp (nativo via whatsmeow)/w
+
+Weixin (WeChat Pessoal)
+
+
QQ /w
}
```
-> Defina `allow_from` como vazio para permitir todos os usuários, ou especifique números QQ para restringir o acesso.
+4. Execute `picoclaw gateway` e abra o QQ para conversar com seu bot
-**3. Executar**
+> O App Secret é exibido apenas uma vez. Salve-o imediatamente — visualizá-lo novamente forçará uma redefinição.
+>
+> Bots criados pela página de configuração rápida são inicialmente apenas para o criador e não suportam chats de grupo. Para habilitar o acesso em grupo, configure o modo sandbox na [QQ Open Platform](https://q.qq.com/).
-```bash
-picoclaw gateway
-```
+**Configuração manual**
+
+Se preferir criar o bot manualmente:
+
+* Faça login na [QQ Open Platform](https://q.qq.com/) para se registrar como desenvolvedor
+* Crie um bot QQ — personalize seu avatar e nome
+* Copie o **App ID** e o **App Secret** nas configurações do bot
+* Configure conforme mostrado acima e execute `picoclaw gateway`
+
DingTalk
+
+MaixCam
+
+
+
Matrix
+
LINE
+
WeCom (企业微信)
+
+
+Feishu (Lark)
+
+
+Slack
+
+
+IRC
+
+
+OneBot (QQ via protocolo OneBot)
+
+
+MaixCam
diff --git a/docs/pt-br/configuration.md b/docs/pt-br/configuration.md
index e7e2c7ec0..ff3ce2b34 100644
--- a/docs/pt-br/configuration.md
+++ b/docs/pt-br/configuration.md
@@ -57,7 +57,7 @@ Por padrão, as skills são carregadas de:
1. `~/.picoclaw/workspace/skills` (workspace)
2. `~/.picoclaw/skills` (global)
-3. `/skills` (builtin)
+3. `/skills` (embutido)
Para configurações avançadas/de teste, você pode substituir o diretório raiz de skills builtin com:
@@ -216,4 +216,149 @@ Para tarefas de longa duração (busca na web, chamadas de API), use a ferrament
```markdown
# Tarefas Periódicas
+
+## Tarefas Rápidas (responder diretamente)
+
+- Informar a hora atual
+
+## Tarefas Longas (usar spawn para assíncrono)
+
+- Pesquisar notícias de IA na web e resumir
+- Verificar e-mails e reportar mensagens importantes
```
+
+**Comportamentos principais:**
+
+| Funcionalidade | Descrição |
+| ---------------- | ------------------------------------------------------------------ |
+| **spawn** | Cria subagente assíncrono, não bloqueia o heartbeat |
+| **Contexto independente** | Subagente tem seu próprio contexto, sem histórico de sessão |
+| **message tool** | Subagente comunica diretamente com o usuário via message tool |
+| **Não-bloqueante** | Após o spawn, o heartbeat continua para a próxima tarefa |
+
+#### Fluxo de Comunicação do Subagente
+
+```
+Heartbeat disparado
+ ↓
+Agent lê HEARTBEAT.md
+ ↓
+Tarefa longa: spawn subagente
+ ↓ ↓
+Continua próxima tarefa Subagente trabalha independentemente
+ ↓ ↓
+Todas tarefas concluídas Subagente usa ferramenta "message"
+ ↓ ↓
+Responde HEARTBEAT_OK Usuário recebe resultado diretamente
+```
+
+**Configuração:**
+
+```json
+{
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ }
+}
+```
+
+| Opção | Padrão | Descrição |
+| ---------- | ------ | -------------------------------------- |
+| `enabled` | `true` | Ativar/desativar heartbeat |
+| `interval` | `30` | Intervalo em minutos (mínimo: 5) |
+
+**Variáveis de ambiente:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` para desativar
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo
+
+### Providers
+
+> [!NOTE]
+> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de áudio de qualquer canal serão automaticamente transcritas no nível do agente.
+
+| Provider | Finalidade | Obter API Key |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini` | LLM (Gemini direto) | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM (Zhipu direto) | [bigmodel.cn](https://bigmodel.cn) |
+| `volcengine` | LLM (Volcengine direto) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM (recomendado, acesso a todos modelos) | [openrouter.ai](https://openrouter.ai) |
+| `anthropic` | LLM (Claude direto) | [console.anthropic.com](https://console.anthropic.com) |
+| `openai` | LLM (GPT direto) | [platform.openai.com](https://platform.openai.com) |
+| `deepseek` | LLM (DeepSeek direto) | [platform.deepseek.com](https://platform.deepseek.com) |
+| `qwen` | LLM (Qwen direto) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq` | LLM + **Transcrição de voz** (Whisper) | [console.groq.com](https://console.groq.com) |
+| `cerebras` | LLM (Cerebras direto) | [cerebras.ai](https://cerebras.ai) |
+| `vivgrid` | LLM (Vivgrid direto) | [vivgrid.com](https://vivgrid.com) |
+
+### Configuração de Modelos (model_list)
+
+> **Novidade:** PicoClaw agora usa uma abordagem **centrada no modelo**. Basta especificar o formato `vendor/model` (ex.: `zhipu/glm-4.7`) para adicionar novos providers — **sem alterações de código!**
+
+#### Todos os Vendors Suportados
+
+| Vendor | Prefixo `model` | API Base padrão | Protocolo | API Key |
+| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obter](https://platform.openai.com) |
+| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obter](https://console.anthropic.com) |
+| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obter](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obter](https://platform.deepseek.com) |
+| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obter](https://aistudio.google.com/api-keys) |
+| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obter](https://console.groq.com) |
+| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obter](https://dashscope.console.aliyun.com) |
+| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (sem chave) |
+| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obter](https://openrouter.ai/keys) |
+| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obter](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **Antigravity** | `antigravity/` | Google Cloud | Custom | Somente OAuth |
+
+#### Balanceamento de Carga
+
+Configure múltiplos endpoints para o mesmo nome de modelo — PicoClaw fará round-robin automaticamente:
+
+```json
+{
+ "model_list": [
+ { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
+ { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
+ ]
+}
+```
+
+#### Migração da Configuração Legada `providers`
+
+A configuração antiga `providers` está **depreciada** mas ainda é suportada. Veja [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Arquitetura de Providers
+
+PicoClaw roteia providers por família de protocolo:
+
+- **Compatível com OpenAI**: OpenRouter, Groq, Zhipu, endpoints vLLM e a maioria dos outros.
+- **Anthropic**: Comportamento nativo da API Claude.
+- **Codex/OAuth**: Rota de autenticação OAuth/token OpenAI.
+
+### Tarefas Agendadas / Lembretes
+
+PicoClaw suporta tarefas agendadas via ferramenta `cron`.
+
+```json
+{
+ "tools": {
+ "cron": {
+ "enabled": true,
+ "exec_timeout_minutes": 5
+ }
+ }
+}
+```
+
+As tarefas agendadas persistem após reinicializações em `~/.picoclaw/workspace/cron/`.
+
+### Tópicos Avançados
+
+| Tópico | Descrição |
+| ------ | --------- |
+| [Sistema de Hooks](../hooks/README.md) | Hooks orientados a eventos: observadores, interceptores, hooks de aprovação |
+| [Steering](../steering.md) | Injetar mensagens em um loop de agente em execução |
+| [SubTurn](../subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
+| [Gerenciamento de Contexto](../agent-refactor/context.md) | Detecção de limites de contexto, compressão |
diff --git a/docs/pt-br/credential_encryption.md b/docs/pt-br/credential_encryption.md
new file mode 100644
index 000000000..59a31e438
--- /dev/null
+++ b/docs/pt-br/credential_encryption.md
@@ -0,0 +1,159 @@
+> Voltar ao [README](../../README.pt-br.md)
+
+# Criptografia de Credenciais
+
+O PicoClaw suporta a criptografia de valores `api_key` nas entradas de configuração `model_list`.
+As chaves criptografadas são armazenadas como strings `enc://` e descriptografadas automaticamente na inicialização.
+
+---
+
+## Início Rápido
+
+**1. Defina sua frase secreta**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. Criptografe uma chave de API**
+
+Execute `picoclaw onboard` — ele solicita sua frase secreta e gera a chave SSH,
+depois recriptografa automaticamente quaisquer entradas `api_key` em texto simples na sua configuração
+na próxima chamada `SaveConfig`. O valor `enc://` resultante será semelhante a:
+
+```
+enc://AAAA...base64...
+```
+
+**3. Cole a saída na sua configuração**
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-4o",
+ "model": "openai/gpt-4o",
+ "api_key": "enc://AAAA...base64...",
+ "api_base": "https://api.openai.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## Formatos de `api_key` Suportados
+
+| Formato | Exemplo | Comportamento |
+|---------|---------|---------------|
+| Texto simples | `sk-abc123` | Usado como está |
+| Referência de arquivo | `file://openai.key` | Conteúdo lido do mesmo diretório do arquivo de configuração |
+| Criptografado | `enc://` | Descriptografado na inicialização usando `PICOCLAW_KEY_PASSPHRASE` |
+| Vazio | `""` | Passado sem alteração (usado com `auth_method: oauth`) |
+
+---
+
+## Design Criptográfico
+
+### Derivação de Chave
+
+A criptografia utiliza **HKDF-SHA256** com uma chave privada SSH como segundo fator.
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### Criptografia
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### Formato de Transmissão
+
+```
+enc://
+```
+
+| Campo | Tamanho | Descrição |
+|-------|---------|-----------|
+| `salt` | 16 bytes | Aleatório por criptografia; alimentado no HKDF |
+| `nonce` | 12 bytes | Aleatório por criptografia; IV do AES-GCM |
+| `ciphertext` | variável | Texto cifrado AES-256-GCM + tag de autenticação de 16 bytes |
+
+O tag de autenticação GCM é anexado automaticamente ao texto cifrado. Qualquer adulteração faz com que a descriptografia falhe com um erro em vez de retornar texto simples corrompido.
+
+### Desempenho
+
+| Operação | Tempo (ARM Cortex-A) |
+|----------|----------------------|
+| Derivação de chave (HKDF) | < 1 ms |
+| Descriptografia AES-256-GCM | < 1 ms |
+| **Sobrecarga total na inicialização** | **< 2 ms por chave** |
+
+---
+
+## Segurança de Dois Fatores com Chave SSH
+
+Quando uma chave privada SSH é fornecida, quebrar a criptografia requer **ambos**:
+
+1. A **frase secreta** (`PICOCLAW_KEY_PASSPHRASE`)
+2. O **arquivo de chave privada SSH**
+
+Isso significa que um arquivo de configuração vazado sozinho não é suficiente para recuperar a chave de API, mesmo que a frase secreta seja fraca. A chave SSH contribui com 256 bits de entropia (Ed25519) independentemente da força da frase secreta.
+
+### Modelo de Ameaça
+
+| O que o atacante possui | Pode descriptografar? |
+|------------------------|----------------------|
+| Apenas o arquivo de configuração | Não — necessita da frase secreta + chave SSH |
+| Apenas a chave SSH | Não — necessita da frase secreta |
+| Apenas a frase secreta | Não — necessita da chave SSH |
+| Arquivo de configuração + chave SSH + frase secreta | Sim — comprometimento total |
+
+---
+
+## Variáveis de Ambiente
+
+| Variável | Obrigatório | Descrição |
+|----------|-------------|-----------|
+| `PICOCLAW_KEY_PASSPHRASE` | Sim (para `enc://`) | Frase secreta usada para derivação de chave |
+| `PICOCLAW_SSH_KEY_PATH` | Não | Caminho para a chave privada SSH. Se não definido, detecta automaticamente em `~/.ssh/picoclaw_ed25519.key` |
+
+### Detecção Automática da Chave SSH
+
+Se `PICOCLAW_SSH_KEY_PATH` não estiver definido, o PicoClaw procura a chave dedicada:
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+Este arquivo dedicado evita conflitos com as chaves SSH existentes do usuário.
+Execute `picoclaw onboard` para gerá-lo automaticamente.
+
+`os.UserHomeDir()` é usado para resolução multiplataforma do diretório home (lê `USERPROFILE` no Windows, `HOME` no Unix/macOS).
+
+> **Nota:** Um arquivo de chave SSH é obrigatório para a criptografia de credenciais. Se nenhuma chave for encontrada e `PICOCLAW_SSH_KEY_PATH` não estiver definido, a criptografia/descriptografia falhará. Execute `picoclaw onboard` para gerar a chave automaticamente.
+
+---
+
+## Migração
+
+Como os únicos materiais secretos são `PICOCLAW_KEY_PASSPHRASE` e o arquivo de chave privada SSH, a migração é simples:
+
+1. Copie o arquivo de configuração para a nova máquina.
+2. Defina `PICOCLAW_KEY_PASSPHRASE` com o mesmo valor.
+3. Copie o arquivo de chave privada SSH para o mesmo caminho (ou defina `PICOCLAW_SSH_KEY_PATH` para sua nova localização).
+
+Nenhuma recriptografia é necessária.
+
+---
+
+## Considerações de Segurança
+
+- **Tanto a frase secreta quanto a chave SSH são obrigatórias.** A chave SSH atua como um segundo fator — sem ela, a criptografia/descriptografia falhará. Execute `picoclaw onboard` para gerar a chave se ela não existir.
+- **A chave SSH é somente leitura em tempo de execução.** O PicoClaw nunca escreve ou modifica o arquivo de chave SSH.
+- **Chaves em texto simples continuam sendo suportadas.** Configurações existentes sem `enc://` não são afetadas.
+- **O formato `enc://` é versionado** através do campo `info` do HKDF (`picoclaw-credential-v1`), permitindo futuras atualizações de algoritmo sem quebrar valores criptografados existentes.
diff --git a/docs/pt-br/debug.md b/docs/pt-br/debug.md
new file mode 100644
index 000000000..8614cd5ed
--- /dev/null
+++ b/docs/pt-br/debug.md
@@ -0,0 +1,36 @@
+# Depuração do PicoClaw
+
+> Voltar ao [README](../../README.pt-br.md)
+
+O PicoClaw realiza múltiplas interações complexas nos bastidores para cada requisição que recebe — desde o roteamento de mensagens e avaliação de complexidade, até a execução de ferramentas e adaptação a falhas de modelo. Poder ver exatamente o que está acontecendo é crucial, não apenas para solucionar problemas potenciais, mas também para realmente entender como o agente opera.
+
+## Iniciando o PicoClaw em modo de depuração
+
+Para obter informações detalhadas sobre o que o agente está fazendo (requisições LLM, chamadas de ferramentas, roteamento de mensagens), você pode iniciar o gateway do PicoClaw com a flag de depuração:
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+Neste modo, o sistema formata os logs de forma detalhada e exibe prévias dos prompts do sistema e dos resultados de execução das ferramentas.
+
+## Desabilitando a truncagem de logs (logs completos)
+
+Por padrão, o PicoClaw trunca strings muito longas (como o *Prompt do Sistema* ou resultados JSON grandes) nos logs de depuração para manter o console legível.
+
+Se você precisar inspecionar a saída completa de um comando ou o payload exato enviado ao modelo LLM, pode usar a flag `--no-truncate`.
+
+**Nota:** Esta flag *só* funciona quando combinada com o modo `--debug`.
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+Quando esta flag está ativa, a função de truncagem global é desabilitada. Isso é extremamente útil para:
+
+* Verificar a sintaxe exata das mensagens enviadas ao provedor.
+* Ler a saída completa de ferramentas como `exec`, `web_fetch` ou `read_file`.
+* Depurar o histórico de sessão salvo na memória.
diff --git a/docs/pt-br/docker.md b/docs/pt-br/docker.md
index af58c89b2..bac48954b 100644
--- a/docs/pt-br/docker.md
+++ b/docs/pt-br/docker.md
@@ -12,6 +12,7 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. Primeira execução — gera automaticamente docker/data/config.json e encerra
+# (só é acionado quando config.json e workspace/ estão ambos ausentes)
docker compose -f docker/docker-compose.yml --profile gateway up
# O contêiner exibe "First-run setup complete." e para.
diff --git a/docs/pt-br/hardware-compatibility.md b/docs/pt-br/hardware-compatibility.md
new file mode 100644
index 000000000..771621014
--- /dev/null
+++ b/docs/pt-br/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> Voltar ao [README](../../README.pt-br.md)
+
+# 🖥️ PicoClaw Lista de compatibilidade de hardware
+
+O PicoClaw roda em praticamente qualquer dispositivo Linux. Esta página registra chips, produtos e placas de desenvolvimento verificados.
+
+**Seu hardware não está na lista?** Envie um PR para adicioná-lo! Fabricantes de hardware são bem-vindos para contribuir e co-promover.
+
+---
+
+## 1. Suporte a chips verificado
+
+### x86
+
+| Fabricante | Chip | Notas |
+|------------|------|-------|
+| Intel | Any x86 CPU (i386+) | Todos os processadores desktop/servidor/notebook |
+| AMD | Any x86 CPU | Todos os processadores desktop/servidor/notebook |
+
+### ARM
+
+| Sub-arq | Chips típicos | Notas |
+|---------|---------------|-------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Single-core ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Single-core Cortex-A7, usado no LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Quad-core Cortex-A53, usado no Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Quad-core Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Quad-core Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Dual-core Cortex-A53 + NPU, usado no NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| Fabricante | Chip | Núcleo | Notas |
+|------------|------|--------|-------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 integrado, usado no LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L integrado, 1 TOPS NPU, câmera AI 4K SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | Série de câmeras AI RISC-V |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Usado no HaaS506-LD1 RTU industrial |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Usado no Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | Compatível com RVA23, RVV de 1024 bits, inferência AI FP8 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 núcleos, 16MB cache L3, classe desktop |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, usado no CanMV-K230 |
+
+### MIPS
+
+| Fabricante | Chip | Notas |
+|------------|------|-------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, usado em muitos roteadores OpenWrt (ex. Xiaomi Router 3G) |
+
+### LoongArch (loong64)
+
+| Fabricante | Chip | Notas |
+|------------|------|-------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Quad-core LA464 @ 2.5GHz, desktop/estação de trabalho |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Quad-core 4C/8T @ 2.5GHz, IPC comparável ao Intel 10ª geração |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Dual-core @ 1GHz, aplicações industriais/IoT |
+
+---
+
+## 2. Produtos verificados (por data de lançamento)
+
+Produtos de consumo, roteadores e dispositivos industriais testados com o PicoClaw.
+
+| Ano | Produto | Arq | SoC | RAM | Categoria |
+|-----|---------|-----|-----|-----|-----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Smartphone |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Tablet |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Roteador (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV Box / Servidor doméstico |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Alto-falante inteligente |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | RTU industrial |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | IP-KVM Pro |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | Câmera AI 4K |
+
+---
+
+## 3. Placas de desenvolvimento verificadas (por data de lançamento)
+
+| Ano | Placa | Arq | SoC | RAM | Link de compra |
+|-----|-------|-----|-----|-----|----------------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. Também funciona em
+
+### Celulares Android (via Termux)
+
+Qualquer celular Android ARM64 (2015+) com 1GB+ de RAM. Instale o [Termux](https://github.com/termux/termux-app), use `proot` para rodar o PicoClaw.
+
+> Veja [README: Rodar em celulares Android antigos](../../README.pt-br.md#-run-on-old-android-phones) para instruções de configuração.
+
+### Desktop / Servidor / Nuvem
+
+| Plataforma | Notas |
+|------------|-------|
+| x86_64 Linux | Binário nativo, sem dependências |
+| x86_64 Windows | Binário nativo |
+| macOS (Intel / Apple Silicon) | Binário nativo |
+| Docker (any platform) | `docker compose` em uma linha, veja [Guia Docker](docker.md) |
+| OpenWrt routers | Builds MIPS/ARM, requer >32MB de RAM livre |
+| FreeBSD / NetBSD | Builds x86_64 e arm64 disponíveis |
+
+---
+
+## 5. Requisitos mínimos
+
+| Recurso | Mínimo | Recomendado |
+|---------|--------|-------------|
+| RAM | 10MB livres | 32MB+ livres |
+| Armazenamento | 20MB (binário) | 50MB+ (com workspace) |
+| CPU | Qualquer (single-core 0,6GHz+) | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| Rede | Necessária (para chamadas de API LLM) | Ethernet ou WiFi |
+
+---
+
+## 6. Como testar e contribuir
+
+```bash
+# 1. Baixar para sua arquitetura
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. Inicializar
+./picoclaw onboard
+
+# 3. Testar
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+Builds disponíveis: `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### Adicionar seu hardware
+
+1. Faça fork deste repositório
+2. Adicione seu chip / produto / placa na tabela apropriada
+3. Inclua: nome, arquitetura, SoC, RAM, ano e um link se disponível
+4. Envie um PR
+
+Fabricantes de hardware: deseja adicionar suporte oficial ou co-promover? Abra uma issue ou entre em contato via [Discord](https://discord.gg/V4sAZ9XWpN).
diff --git a/docs/pt-br/providers.md b/docs/pt-br/providers.md
index 04fb9fc6b..0f7a4b5a1 100644
--- a/docs/pt-br/providers.md
+++ b/docs/pt-br/providers.md
@@ -93,7 +93,7 @@ Este design também permite **suporte multi-agente** com seleção flexível de
],
"agents": {
"defaults": {
- "model": "gpt-5.4"
+ "model_name": "gpt-5.4"
}
}
}
@@ -266,13 +266,13 @@ A configuração antiga `providers` está **descontinuada** mas ainda é suporta
],
"agents": {
"defaults": {
- "model": "glm-4.7"
+ "model_name": "glm-4.7"
}
}
}
```
-Para guia de migração detalhado, veja [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
+Para guia de migração detalhado, veja [migration/model-list-migration.md](../migration/model-list-migration.md).
### Arquitetura de Provedores
@@ -298,7 +298,7 @@ Isso mantém o runtime leve enquanto torna novos backends compatíveis com OpenA
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
- "model": "glm-4.7",
+ "model_name": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
@@ -328,12 +328,11 @@ picoclaw agent -m "Hello"
{
"agents": {
"defaults": {
- "model": "anthropic/claude-opus-4-5"
+ "model_name": "anthropic/claude-opus-4-5"
}
},
"session": {
- "dm_scope": "per-channel-peer",
- "backlog_limit": 20
+ "dm_scope": "per-channel-peer"
},
"providers": {
"openrouter": {
diff --git a/docs/pt-br/tools_configuration.md b/docs/pt-br/tools_configuration.md
index b6f726aa4..feec3c3d8 100644
--- a/docs/pt-br/tools_configuration.md
+++ b/docs/pt-br/tools_configuration.md
@@ -41,14 +41,6 @@ Configurações gerais para busca e processamento de conteúdo de páginas web.
| `fetch_limit_bytes` | int | 10485760 | Tamanho máximo do payload da página web a ser buscado, em bytes (padrão é 10MB). |
| `format` | string | "plaintext" | Formato de saída do conteúdo buscado. Opções: `plaintext` ou `markdown` (recomendado). |
-### Brave
-
-| Config | Tipo | Padrão | Descrição |
-|---------------|--------|--------|----------------------------|
-| `enabled` | bool | false | Habilitar pesquisa Brave |
-| `api_key` | string | - | Chave API do Brave Search |
-| `max_results` | int | 5 | Número máximo de resultados |
-
### DuckDuckGo
| Config | Tipo | Padrão | Descrição |
@@ -56,13 +48,73 @@ Configurações gerais para busca e processamento de conteúdo de páginas web.
| `enabled` | bool | true | Habilitar pesquisa DuckDuckGo |
| `max_results` | int | 5 | Número máximo de resultados |
+### Baidu Search
+
+| Config | Tipo | Padrão | Descrição |
+|---------------|--------|-----------------------------------------------------------------|------------------------------------|
+| `enabled` | bool | false | Habilitar pesquisa Baidu |
+| `api_key` | string | - | Chave API Qianfan |
+| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL da API Baidu Search |
+| `max_results` | int | 10 | Número máximo de resultados |
+
+```json
+{
+ "tools": {
+ "web": {
+ "baidu_search": {
+ "enabled": true,
+ "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+ "max_results": 10
+ }
+ }
+ }
+}
+```
+
### Perplexity
| Config | Tipo | Padrão | Descrição |
|---------------|--------|--------|--------------------------------|
-| `enabled` | bool | false | Habilitar pesquisa Perplexity |
-| `api_key` | string | - | Chave API do Perplexity |
-| `max_results` | int | 5 | Número máximo de resultados |
+| `enabled` | bool | false | Habilitar pesquisa Perplexity |
+| `api_key` | string | - | Chave API do Perplexity |
+| `api_keys` | string[] | - | Várias chaves API do Perplexity para rotação (prioridade sobre `api_key`) |
+| `max_results` | int | 5 | Número máximo de resultados |
+
+### Brave
+
+| Config | Tipo | Padrão | Descrição |
+|---------------|--------|--------|----------------------------|
+| `enabled` | bool | false | Habilitar pesquisa Brave |
+| `api_key` | string | - | Chave API única do Brave Search |
+| `api_keys` | string[] | - | Várias chaves API do Brave para rotação (prioridade sobre `api_key`) |
+| `max_results` | int | 5 | Número máximo de resultados |
+
+### Tavily
+
+| Config | Tipo | Padrão | Descrição |
+|---------------|--------|--------|------------------------------------|
+| `enabled` | bool | false | Habilitar pesquisa Tavily |
+| `api_key` | string | - | Chave API do Tavily |
+| `base_url` | string | - | URL base personalizada do Tavily |
+| `max_results` | int | 0 | Número máximo de resultados (0 = padrão) |
+
+### SearXNG
+
+| Config | Tipo | Padrão | Descrição |
+|---------------|--------|--------------------------|--------------------------------|
+| `enabled` | bool | false | Habilitar pesquisa SearXNG |
+| `base_url` | string | `http://localhost:8888` | URL da instância SearXNG |
+| `max_results` | int | 5 | Número máximo de resultados |
+
+### GLM Search
+
+| Config | Tipo | Padrão | Descrição |
+|-----------------|--------|------------------------------------------------------|----------------------------|
+| `enabled` | bool | false | Habilitar GLM Search |
+| `api_key` | string | - | Chave API GLM |
+| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL da API GLM Search |
+| `search_engine` | string | `search_std` | Tipo de motor de busca |
+| `max_results` | int | 5 | Número máximo de resultados |
## Ferramenta Exec
@@ -70,9 +122,32 @@ A ferramenta exec é usada para executar comandos shell.
| Config | Tipo | Padrão | Descrição |
|------------------------|-------|--------|-------------------------------------------------|
+| `enabled` | bool | true | Habilitar a ferramenta exec |
| `enable_deny_patterns` | bool | true | Habilitar bloqueio padrão de comandos perigosos |
| `custom_deny_patterns` | array | [] | Padrões de negação personalizados (expressões regulares) |
+### Desabilitando a Ferramenta Exec
+
+Para desabilitar completamente a ferramenta `exec`, defina `enabled` como `false`:
+
+**Via arquivo de configuração:**
+```json
+{
+ "tools": {
+ "exec": {
+ "enabled": false
+ }
+ }
+}
+```
+
+**Via variável de ambiente:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Nota:** Quando desabilitada, o agent não poderá executar comandos shell. Isso também afeta a capacidade da ferramenta Cron de executar comandos shell agendados.
+
### Funcionalidade
- **`enable_deny_patterns`**: Defina como `false` para desabilitar completamente os padrões de bloqueio de comandos perigosos padrão
@@ -329,6 +404,7 @@ Todas as opções de configuração podem ser substituídas via variáveis de am
Por exemplo:
- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
- `PICOCLAW_TOOLS_MCP_ENABLED=true`
diff --git a/docs/pt-br/troubleshooting.md b/docs/pt-br/troubleshooting.md
index e6c1a55ab..286ad2ac8 100644
--- a/docs/pt-br/troubleshooting.md
+++ b/docs/pt-br/troubleshooting.md
@@ -16,7 +16,7 @@
**Correção:** Em `~/.picoclaw/config.json` (ou seu caminho de configuração):
-1. **agents.defaults.model** deve corresponder a um `model_name` em `model_list` (ex.: `"openrouter-free"`).
+1. **agents.defaults.model_name** deve corresponder a um `model_name` em `model_list` (ex.: `"openrouter-free"`).
2. O **model** dessa entrada deve ser um ID de modelo OpenRouter válido, por exemplo:
- `"openrouter/free"` – nível gratuito automático
- `"google/gemini-2.0-flash-exp:free"`
@@ -28,7 +28,7 @@ Exemplo:
{
"agents": {
"defaults": {
- "model": "openrouter-free"
+ "model_name": "openrouter-free"
}
},
"model_list": [
diff --git a/docs/spawn-tasks.md b/docs/spawn-tasks.md
index eff96ce45..05a5215d2 100644
--- a/docs/spawn-tasks.md
+++ b/docs/spawn-tasks.md
@@ -2,6 +2,15 @@
> Back to [README](../README.md)
+PicoClaw supports **asynchronous task execution** via the `spawn` tool. This is primarily used by the **Heartbeat** system to run long-running tasks without blocking the main agent loop.
+
+## Heartbeat
+
+The heartbeat system periodically checks `workspace/HEARTBEAT.md` for scheduled tasks. On first run, a default template is auto-generated. You can customize it to define quick tasks (handled inline) and long tasks (delegated via `spawn`).
+
+**Example `HEARTBEAT.md`:**
+
+```markdown
## Quick Tasks (respond directly)
- Report current time
diff --git a/docs/steering.md b/docs/steering.md
new file mode 100644
index 000000000..63294ac5f
--- /dev/null
+++ b/docs/steering.md
@@ -0,0 +1,199 @@
+# Steering
+
+Steering allows injecting messages into an already-running agent loop, interrupting it between tool calls without waiting for the entire cycle to complete.
+
+## How it works
+
+When the agent is executing a sequence of tool calls (e.g. the model requested 3 tools in a single turn), steering checks the queue **after each tool** completes. If it finds queued messages:
+
+1. The remaining tools are **skipped** and receive `"Skipped due to queued user message."` as their result
+2. The steering messages are **injected into the conversation context**
+3. The model is called again with the updated context, including the user's steering message
+
+```
+User ──► Steer("change approach")
+ │
+Agent Loop ▼
+ ├─ tool[0] ✔ (executed)
+ ├─ [polling] → steering found!
+ ├─ tool[1] ✘ (skipped)
+ ├─ tool[2] ✘ (skipped)
+ └─ new LLM turn with steering message
+```
+
+## Scoped queues
+
+Steering is now isolated per resolved session scope, not stored in a single
+global queue.
+
+- The active turn writes and reads from its own scope key (usually the routed session key such as `agent::...`)
+- `Steer()` still works outside an active turn through a legacy fallback queue
+- `Continue()` first dequeues messages for the requested session scope, then falls back to the legacy queue for backwards compatibility
+
+This prevents a message arriving from another chat, DM peer, or routed agent
+session from being injected into the wrong conversation.
+
+## Configuration
+
+In `config.json`, under `agents.defaults`:
+
+```json
+{
+ "agents": {
+ "defaults": {
+ "steering_mode": "one-at-a-time"
+ }
+ }
+}
+```
+
+### Modes
+
+| Value | Behavior |
+|-------|----------|
+| `"one-at-a-time"` | **(default)** Dequeues only one message per polling cycle. If there are 3 messages in the queue, they are processed one at a time across 3 successive iterations. |
+| `"all"` | Drains the entire queue in a single poll. All pending messages are injected into the context together. |
+
+The environment variable `PICOCLAW_AGENTS_DEFAULTS_STEERING_MODE` can be used as an alternative.
+
+## Go API
+
+### Steer — Send a steering message
+
+```go
+err := agentLoop.Steer(providers.Message{
+ Role: "user",
+ Content: "change direction, focus on X instead",
+})
+if err != nil {
+ // Queue is full (MaxQueueSize=10) or not initialized
+}
+```
+
+The message is enqueued in a thread-safe manner. Returns an error if the queue is full or not initialized. It will be picked up at the next polling point (after the current tool finishes).
+
+### SteeringMode / SetSteeringMode
+
+```go
+// Read the current mode
+mode := agentLoop.SteeringMode() // SteeringOneAtATime | SteeringAll
+
+// Change it at runtime
+agentLoop.SetSteeringMode(agent.SteeringAll)
+```
+
+### Continue — Resume an idle agent
+
+When the agent is idle (it has finished processing and its last message was from the assistant), `Continue` checks if there are steering messages in the queue and uses them to start a new cycle:
+
+```go
+response, err := agentLoop.Continue(ctx, sessionKey, channel, chatID)
+if err != nil {
+ // Error (e.g. "no default agent available")
+}
+if response == "" {
+ // No steering messages in queue, the agent stays idle
+}
+```
+
+`Continue` internally uses `SkipInitialSteeringPoll: true` to avoid double-dequeuing the same messages (since it already extracted them and passes them directly as input).
+
+`Continue` also resolves the target agent from the provided session key, so
+agent-scoped sessions continue on the correct agent instead of always using
+the default one.
+
+## Polling points in the loop
+
+Steering is checked at the following points in the agent cycle:
+
+1. **At loop start** — before the first LLM call, to catch messages enqueued during setup
+2. **After every tool completes** — including the first and the last. If steering is found and there are remaining tools, they are all skipped immediately
+3. **After a direct LLM response** — if a new steering message arrived while the model was generating a non-tool response, the loop continues instead of returning a stale answer
+4. **Right before the turn is finalized** — if steering arrived at the very end of the turn, the agent immediately starts a continuation turn instead of leaving the message orphaned in the queue
+
+## Why remaining tools are skipped
+
+When a steering message is detected, all remaining tools in the batch are skipped rather than executed. The alternative — let all tools finish and inject the steering message afterwards — was considered and rejected. Here is why.
+
+### Preventing unwanted side effects
+
+Tools can have **irreversible side effects**. If the user says "no, wait" while the agent is mid-batch, executing the remaining tools means those side effects happen anyway:
+
+| Tool batch | Steering message | With skip | Without skip |
+|---|---|---|---|
+| `[web_search, send_email]` | "don't send it" | Email **not** sent | Email sent, damage done |
+| `[query_db, write_file, spawn_agent]` | "use another database" | Only the query runs | File written + subagent spawned, all wasted |
+| `[search₁, search₂, search₃, write_file]` | user changes topic entirely | 1 search | 3 searches + file write, all irrelevant |
+
+### Avoiding wasted time
+
+Tools that take seconds (web fetches, API calls, database queries) would all run to completion before the agent sees the user's correction. In a batch of 3 tools each taking 3-4 seconds, that's 10+ seconds of work that will be discarded.
+
+With skipping, the agent reacts as soon as the current tool finishes — typically within a few seconds instead of waiting for the entire batch.
+
+### The LLM gets full context
+
+Skipped tools receive an explicit error result (`"Skipped due to queued user message."`), so the model knows exactly which actions were not performed. It can then decide whether to re-execute them with the new context, or take a different path entirely.
+
+### Trade-off: sequential execution
+
+Skipping requires tools to run **sequentially** (the previous implementation ran them in parallel). This introduces latency when the LLM requests multiple independent tools in a single turn. In practice, most batches contain 1-2 tools, so the impact is minimal compared to the benefit of being able to stop unwanted actions.
+
+## Skipped tool result format
+
+When steering interrupts a batch, each tool that was not executed receives a `tool` result with:
+
+```
+Content: "Skipped due to queued user message."
+```
+
+This is saved to the session via `AddFullMessage` and sent to the model, so it is aware that some requested actions were not performed.
+
+## Full flow example
+
+```
+1. User: "search for info on X, write a file, and send me a message"
+
+2. LLM responds with 3 tool calls: [web_search, write_file, message]
+
+3. web_search is executed → result saved
+
+4. [polling] → User called Steer("no, search for Y instead")
+
+5. write_file is skipped → "Skipped due to queued user message."
+ message is skipped → "Skipped due to queued user message."
+
+6. Message "search for Y instead" injected into context
+
+7. LLM receives the full updated context and responds accordingly
+```
+
+## Automatic bus drain
+
+When the agent loop (`Run()`) starts processing a message, it spawns a background goroutine that keeps consuming new inbound messages from the bus. These messages are automatically redirected into the steering queue via `Steer()`. This means:
+
+- Users on any channel (Telegram, Discord, etc.) don't need to do anything special — their messages are automatically captured as steering when the agent is busy
+- Audio messages are transcribed before being steered, so the agent receives text. If transcription fails, the original (non-transcribed) message is steered as-is
+- Only messages that resolve to the **same steering scope** as the active turn are redirected. Messages for other chats/sessions are requeued onto the inbound bus so they can be processed normally
+- `system` inbound messages are not treated as steering input
+- When `processMessage` finishes, the drain goroutine is canceled and normal message consumption resumes
+
+## Steering with media
+
+Steering messages can include `Media` refs, just like normal inbound user
+messages.
+
+- The original `media://` refs are preserved in session history via `AddFullMessage`
+- Before the next provider call, steering messages go through the normal media resolution pipeline
+- Image refs are converted to data URLs for multimodal providers; non-image refs are resolved the same way as standard inbound media
+
+This applies both to in-turn steering and to idle-session continuation through
+`Continue()`.
+
+## Notes
+
+- Steering **does not interrupt** a tool that is currently executing. It waits for the current tool to finish, then checks the queue.
+- With `one-at-a-time` mode, if multiple messages are enqueued rapidly, they will be processed one per iteration. This gives the model the opportunity to react to each message individually.
+- With `all` mode, all pending messages are combined into a single injection. Useful when you want the agent to receive all the context at once.
+- The steering queue has a maximum capacity of 10 messages (`MaxQueueSize`). `Steer()` returns an error when the queue is full. In the bus drain path, the error is logged as a warning and the message is effectively dropped.
+- Manual `Steer()` calls made outside an active turn still go to the legacy fallback queue, so older integrations keep working.
diff --git a/docs/subturn.md b/docs/subturn.md
new file mode 100644
index 000000000..b84c06627
--- /dev/null
+++ b/docs/subturn.md
@@ -0,0 +1,279 @@
+# 🔄 SubTurn Mechanism
+
+> Back to [README](../README.md)
+
+## Overview
+
+The `SubTurn` mechanism is a core feature in PicoClaw that allows tools to spawn isolated, nested agent loops to handle complex sub-tasks.
+
+By using a SubTurn, an agent can break down a problem and run a separate LLM invocation in an independent, ephemeral session. This ensures that intermediate reasoning, background tasks, or sub-agent outputs do not pollute the main conversation history.
+
+## Core Capabilities
+
+- **Context Isolation**: Each SubTurn uses an `ephemeralSessionStore`. Its message history does not leak into the parent task and is destroyed upon completion. The ephemeral session holds at most **50 messages**; older messages are automatically truncated when this limit is reached.
+- **Depth & Concurrency Limits**: Prevents infinite loops and resource exhaustion.
+ - **Maximum Depth**: Up to 3 nested levels.
+ - **Maximum Concurrency**: Up to 5 concurrent sub-turns per parent turn (managed via a semaphore with a 30-second timeout).
+- **Context Protection**: Supports soft context limits (`MaxContextRunes`). It proactively truncates old messages (while preserving system prompts and recent context) before hitting the provider's hard context window limit.
+- **Error Recovery**: Automatically detects and recovers from provider context length exceeded errors and truncation errors by compressing history and retrying.
+
+## Configuration (`SubTurnConfig`)
+
+When spawning a SubTurn, you must provide a `SubTurnConfig`:
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `Model` | `string` | The LLM model to use for the sub-turn (e.g., `gpt-4o-mini`). **Required.** |
+| `Tools` | `[]tools.Tool` | Tools granted to the sub-turn. If empty, it inherits the parent's tools. |
+| `SystemPrompt` | `string` | The task description for the sub-turn. Sent as the first user message to the LLM (not as a system prompt override). |
+| `ActualSystemPrompt` | `string` | Optional explicit system prompt to replace the agent's default. Leave empty to inherit the parent agent's system prompt. |
+| `MaxTokens` | `int` | Maximum tokens for the generated response. |
+| `Async` | `bool` | Controls the result delivery mode (Synchronous vs. Asynchronous). |
+| `Critical` | `bool` | If `true`, the sub-turn continues running even if the parent finishes gracefully. |
+| `Timeout` | `time.Duration` | Maximum execution time (default: 5 minutes). |
+| `MaxContextRunes`| `int` | Soft context limit. `0` = auto-calculate (75% of model's context window, recommended), `-1` = no limit (disable soft truncation, rely only on hard context error recovery), `>0` = use specified rune limit. |
+
+> **Note:** The `Async` flag does **not** make the call non-blocking. It only controls whether the result is also delivered to the parent's `pendingResults` channel. Both modes block the caller until the sub-turn completes. For true non-blocking execution, the caller must spawn the sub-turn in a separate goroutine.
+
+## Execution Modes
+
+### Synchronous (`Async: false`)
+
+This is the standard mode where the caller needs the result immediately to proceed.
+
+- The caller blocks until the sub-turn completes.
+- The result is **only** returned directly via the function return value.
+- It is **not** delivered to the parent's pending results channel.
+
+**Example:**
+```go
+cfg := agent.SubTurnConfig{
+ Model: "gpt-4o-mini",
+ SystemPrompt: "Analyze the provided codebase...",
+ Async: false,
+}
+result, err := agent.SpawnSubTurn(ctx, cfg)
+// Process result immediately
+```
+
+### Asynchronous (`Async: true`)
+
+Used for "fire-and-forget" operations or parallel processing where the parent turn collects results later.
+
+- The result is delivered to the parent turn's `pendingResults` channel.
+- The result is **also** returned via the function return value (for consistency).
+- The parent's Agent Loop will poll this channel in subsequent iterations and automatically inject the results into the ongoing conversation context as `[SubTurn Result]`.
+
+**Example:**
+```go
+cfg := agent.SubTurnConfig{
+ Model: "gpt-4o-mini",
+ SystemPrompt: "Run a background security scan...",
+ Async: true,
+}
+result, err := agent.SpawnSubTurn(ctx, cfg)
+// The result will also be injected into the parent loop later via channel
+```
+
+## Error Recovery and Retries
+
+SubTurns implement automatic retry mechanisms for transient errors:
+
+| Error Type | Max Retries | Recovery Action |
+|:-----------|:------------|:----------------|
+| Context Length Exceeded | 2 | Force compress history and retry |
+| Response Truncated (`finish_reason="truncated"`) | 2 | Inject recovery prompt and retry |
+
+### Truncation Recovery
+When the LLM response is truncated (`finish_reason="truncated"`), SubTurn automatically:
+1. Detects the truncation from `turnState.lastFinishReason`
+2. Injects a recovery prompt: "Your previous response was truncated due to length. Please provide a shorter, complete response..."
+3. Retries up to 2 times
+
+### Context Error Recovery
+When the provider returns a context length error (e.g., `context_length_exceeded`):
+1. Force compresses the message history (drops oldest 50% of conversation)
+2. Retries with the compressed context
+3. Up to 2 retries before failing
+
+## Lifecycle and Cancellation
+
+SubTurns operate within an independent context but maintain a structural link to their parent `turnState`.
+
+### Graceful Parent Finish
+When the parent task finishes naturally (`Finish(false)`):
+- **Non-critical** sub-turns receive a signal to exit gracefully without throwing an error.
+- **Critical** (`Critical: true`) sub-turns continue running in the background. Once finished, their results are emitted as **Orphan Results** so the data is not lost.
+
+### Hard Abort
+When the parent task is forcefully aborted (e.g., user interrupts with `/stop`):
+- A cascading cancellation is triggered, instantly terminating all child and grandchild sub-turns.
+- The root turn's session history rolls back to the snapshot taken at turn start (`initialHistoryLength`), preventing dirty context. SubTurns are not affected by this rollback as they use ephemeral sessions that are discarded anyway.
+
+## Agent Loop Integration
+
+### Bus Draining During Processing
+
+When a message enters the `Run()` loop, the agent starts a `drainBusToSteering` goroutine before calling `processMessage`. This goroutine runs concurrently with the entire processing lifecycle and continuously consumes any new inbound messages from the bus, redirecting them into the **steering queue** instead of dropping them.
+
+This ensures that if a user sends a follow-up message while the agent is processing (including during SubTurn execution), the message is not lost — it will be picked up between tool call iterations via `dequeueSteeringMessages`.
+
+The drain goroutine stops automatically when `processMessage` returns (via a cancellable context).
+
+### Pending Result Polling
+
+The agent loop polls for async SubTurn results at two points per iteration:
+1. **Before the LLM call**: injects any arrived results as `[SubTurn Result]` messages into the conversation context.
+2. **After all tool executions**: polls again during the tool loop to catch results that arrived during tool execution.
+3. **After the final iteration**: one last poll before the turn ends to avoid losing late-arriving results.
+
+### Turn State Tracking
+
+All active root turns are registered in `AgentLoop.activeTurnStates` (`sync.Map`, keyed by session key). This allows `HardAbort` and `/subagents` observability commands to find and operate on active turns.
+
+## Event Bus Integration
+
+SubTurns emit specific events to the PicoClaw `EventBus` for observability and debugging:
+
+| Event Kind | When Emitted | Payload |
+|:------|:-------------|:--------|
+| `subturn_spawn` | Sub-turn successfully initialized | `SubTurnSpawnPayload{AgentID, Label, ParentTurnID}` |
+| `subturn_end` | Sub-turn finishes (success or error) | `SubTurnEndPayload{AgentID, Status}` |
+| `subturn_result_delivered` | Async result successfully delivered to parent | `SubTurnResultDeliveredPayload{TargetChannel, TargetChatID, ContentLen}` |
+| `subturn_orphan` | Result cannot be delivered (parent finished or channel full) | `SubTurnOrphanPayload{ParentTurnID, ChildTurnID, Reason}` |
+
+## API Reference
+
+### SpawnSubTurn (Public Entry Point)
+
+```go
+func SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*tools.ToolResult, error)
+```
+
+This is the exported package-level entry point for agent-internal code (e.g., tests, direct invocations). It retrieves `AgentLoop` and `turnState` from context and delegates to the internal `spawnSubTurn`.
+
+**Requirements:**
+- `AgentLoop` must be injected into context via `WithAgentLoop()`
+- Parent `turnState` must exist in context (automatically set when called from tools)
+
+**Returns:**
+- `*tools.ToolResult`: Contains `ForLLM` field with the sub-turn's output
+- `error`: One of the defined error types or context errors
+
+### AgentLoopSpawner (Interface Implementation)
+
+```go
+type AgentLoopSpawner struct { al *AgentLoop }
+
+func (s *AgentLoopSpawner) SpawnSubTurn(ctx context.Context, cfg tools.SubTurnConfig) (*tools.ToolResult, error)
+```
+
+This implements the `tools.SubTurnSpawner` interface for use by tools that need to spawn sub-turns without a direct import of the `agent` package (avoiding circular dependencies). It converts `tools.SubTurnConfig` → `agent.SubTurnConfig` before delegating to the internal `spawnSubTurn`.
+
+### NewSubTurnSpawner
+
+```go
+func NewSubTurnSpawner(al *AgentLoop) *AgentLoopSpawner
+```
+
+Creates a new spawner instance for the given AgentLoop. Pass the returned value to `SpawnTool.SetSpawner()` or `SubagentTool.SetSpawner()` during tool registration.
+
+### Continue
+
+```go
+func (al *AgentLoop) Continue(ctx context.Context, sessionKey string) error
+```
+
+Resumes an idle agent turn by injecting any queued steering messages as a new LLM iteration. Used when the agent is waiting and a deferred steering message needs to be processed without a new inbound message arriving.
+
+## Context Propagation
+
+SubTurn relies on context values for proper operation:
+
+| Context Key | Purpose |
+|:------------|:--------|
+| `agentLoopKey` | Stores `*AgentLoop` for tool access and SubTurn spawning |
+| `turnStateKey` | Stores `*turnState` for hierarchy tracking and result delivery |
+
+### Injecting Dependencies
+
+```go
+// Before calling tools that may spawn SubTurns
+ctx = WithAgentLoop(ctx, agentLoop)
+ctx = withTurnState(ctx, turnState)
+```
+
+### Independent Child Context
+
+**Important**: The child SubTurn uses an **independent context** derived from `context.Background()`, not from the parent context. This design choice:
+
+- Allows critical SubTurns to continue after parent cancellation
+- Prevents parent timeout from affecting child execution
+- Child has its own timeout for self-protection (`Timeout` config or 5 minutes default)
+
+## Error Types
+
+| Error | Condition |
+|:------|:----------|
+| `ErrDepthLimitExceeded` | SubTurn depth exceeds 3 levels |
+| `ErrInvalidSubTurnConfig` | Required field `Model` is empty |
+| `ErrConcurrencyTimeout` | All 5 concurrency slots occupied for 30+ seconds |
+| Context errors | Parent context cancelled during semaphore acquisition |
+
+## Thread Safety
+
+SubTurns are designed for concurrent execution:
+
+- **Parent-child relationships**: Managed under mutex (`parentTS.mu.Lock()`)
+- **Active turn tracking**: Uses `sync.Map` for concurrent access to `activeTurnStates`
+- **ID generation**: Uses `atomic.Int64` for unique SubTurn IDs (format: `subturn-N`, globally monotonic per `AgentLoop` instance)
+- **Result delivery**: Reads parent state under lock, releases before channel send (small race window acceptable)
+
+## Orphan Results
+
+An orphan result occurs when:
+1. Parent turn finishes before the SubTurn completes
+2. The `pendingResults` channel is full (buffer size: 16)
+
+When a result becomes orphan:
+- `SubTurnOrphanResultEvent` is emitted to EventBus
+- The result is **NOT** delivered to the LLM context
+- External systems can listen to this event for custom handling
+
+### Preventing Orphan Results
+- Use `Critical: true` for important SubTurns that must complete
+- Monitor `SubTurnOrphanResultEvent` for observability
+- Consider the 16-buffer limit when spawning many async SubTurns
+
+## Tool Inheritance
+
+### When `cfg.Tools` is empty:
+- SubTurn inherits **all** tools from the parent agent
+- Tools are registered in a new `ToolRegistry` instance
+- Tool TTL is managed independently from parent
+
+### When `cfg.Tools` is specified:
+- Only the specified tools are available to the SubTurn
+- Parent tools are **NOT** merged
+- Use this to restrict SubTurn capabilities for security or focus
+
+**Example - Restricted SubTurn:**
+```go
+cfg := agent.SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Tools: []tools.Tool{readOnlyTool}, // Only read-only access
+ SystemPrompt: "Analyze the file structure...",
+}
+```
+
+## Reference
+
+| Constant | Value |
+|:---------|:------|
+| `maxSubTurnDepth` | 3 |
+| `maxConcurrentSubTurns` | 5 |
+| `concurrencyTimeout` | 30s |
+| `defaultSubTurnTimeout` | 5m |
+| `maxEphemeralHistorySize` | 50 messages |
+| `pendingResults` buffer | 16 |
+| `MaxContextRunes` default | 75% of model context window |
diff --git a/docs/tools_configuration.md b/docs/tools_configuration.md
index a38f0856f..0528fe714 100644
--- a/docs/tools_configuration.md
+++ b/docs/tools_configuration.md
@@ -41,11 +41,12 @@ General settings for fetching and processing webpage content.
### Brave
-| Config | Type | Default | Description |
-|---------------|--------|---------|---------------------------|
-| `enabled` | bool | false | Enable Brave search |
-| `api_key` | string | - | Brave Search API key |
-| `max_results` | int | 5 | Maximum number of results |
+| Config | Type | Default | Description |
+|---------------|----------|---------|------------------------------------------------|
+| `enabled` | bool | false | Enable Brave search |
+| `api_key` | string | - | Brave Search API key |
+| `api_keys` | string[] | - | Multiple API keys for rotation (takes priority over `api_key`) |
+| `max_results` | int | 5 | Maximum number of results |
### DuckDuckGo
@@ -54,13 +55,73 @@ General settings for fetching and processing webpage content.
| `enabled` | bool | true | Enable DuckDuckGo search |
| `max_results` | int | 5 | Maximum number of results |
+### Baidu Search
+
+Baidu Search uses the [Qianfan AI Search API](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5), which is AI-powered and optimized for Chinese-language queries.
+
+| Config | Type | Default | Description |
+|---------------|--------|------------------------------------------------------------------|---------------------------|
+| `enabled` | bool | false | Enable Baidu Search |
+| `api_key` | string | - | Qianfan API key |
+| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | Baidu Search API URL |
+| `max_results` | int | 10 | Maximum number of results |
+
+```json
+{
+ "tools": {
+ "web": {
+ "baidu_search": {
+ "enabled": true,
+ "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+ "max_results": 10
+ }
+ }
+ }
+}
+```
+
### Perplexity
+| Config | Type | Default | Description |
+|---------------|----------|---------|------------------------------------------------|
+| `enabled` | bool | false | Enable Perplexity search |
+| `api_key` | string | - | Perplexity API key |
+| `api_keys` | string[] | - | Multiple API keys for rotation (takes priority over `api_key`) |
+| `max_results` | int | 5 | Maximum number of results |
+
+### Tavily
+
| Config | Type | Default | Description |
|---------------|--------|---------|---------------------------|
-| `enabled` | bool | false | Enable Perplexity search |
-| `api_key` | string | - | Perplexity API key |
-| `max_results` | int | 5 | Maximum number of results |
+| `enabled` | bool | false | Enable Tavily search |
+| `api_key` | string | - | Tavily API key |
+| `base_url` | string | - | Custom Tavily API base URL |
+| `max_results` | int | 0 | Maximum number of results (0 = default) |
+
+### SearXNG
+
+| Config | Type | Default | Description |
+|---------------|--------|--------------------------|---------------------------|
+| `enabled` | bool | false | Enable SearXNG search |
+| `base_url` | string | `http://localhost:8888` | SearXNG instance URL |
+| `max_results` | int | 5 | Maximum number of results |
+
+### GLM Search
+
+| Config | Type | Default | Description |
+|-----------------|--------|------------------------------------------------------|---------------------------|
+| `enabled` | bool | false | Enable GLM Search |
+| `api_key` | string | - | GLM API key |
+| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | GLM Search API URL |
+| `search_engine` | string | `search_std` | Search engine type |
+| `max_results` | int | 5 | Maximum number of results |
+
+### Additional Web Settings
+
+| Config | Type | Default | Description |
+|--------------------------|----------|---------|----------------------------------------------------------------|
+| `prefer_native` | bool | true | Prefer provider's native search over configured search engines |
+| `private_host_whitelist` | string[] | `[]` | Private/internal hosts allowed for web fetching |
## Exec Tool
@@ -68,9 +129,32 @@ The exec tool is used to execute shell commands.
| Config | Type | Default | Description |
|------------------------|-------|---------|--------------------------------------------|
+| `enabled` | bool | true | Enable the exec tool |
| `enable_deny_patterns` | bool | true | Enable default dangerous command blocking |
| `custom_deny_patterns` | array | [] | Custom deny patterns (regular expressions) |
+### Disabling the Exec Tool
+
+To completely disable the `exec` tool, set `enabled` to `false`:
+
+**Via config file:**
+```json
+{
+ "tools": {
+ "exec": {
+ "enabled": false
+ }
+ }
+}
+```
+
+**Via environment variable:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Note:** When disabled, the agent will not be able to execute shell commands. This also affects the Cron tool's ability to run scheduled shell commands.
+
### Functionality
- **`enable_deny_patterns`**: Set to `false` to completely disable the default dangerous command blocking patterns
@@ -132,6 +216,7 @@ The cron tool is used for scheduling periodic tasks.
| Config | Type | Default | Description |
|------------------------|------|---------|------------------------------------------------|
| `exec_timeout_minutes` | int | 5 | Execution timeout in minutes, 0 means no limit |
+| `allow_command` | bool | false | Allow cron tasks to execute shell commands |
## MCP Tool
@@ -347,9 +432,27 @@ The skills tool configures skill discovery and installation via registries like
| `registries.clawhub.enabled` | bool | true | Enable ClawHub registry |
| `registries.clawhub.base_url` | string | `https://clawhub.ai` | ClawHub base URL |
| `registries.clawhub.auth_token` | string | `""` | Optional Bearer token for higher rate limits |
-| `registries.clawhub.search_path` | string | `/api/v1/search` | Search API path |
-| `registries.clawhub.skills_path` | string | `/api/v1/skills` | Skills API path |
-| `registries.clawhub.download_path` | string | `/api/v1/download` | Download API path |
+| `registries.clawhub.search_path` | string | `""` | Search API path |
+| `registries.clawhub.skills_path` | string | `""` | Skills API path |
+| `registries.clawhub.download_path` | string | `""` | Download API path |
+| `registries.clawhub.timeout` | int | 0 | Request timeout in seconds (0 = default) |
+| `registries.clawhub.max_zip_size` | int | 0 | Max skill zip size in bytes (0 = default) |
+| `registries.clawhub.max_response_size` | int | 0 | Max API response size in bytes (0 = default) |
+
+### GitHub Integration
+
+| Config | Type | Default | Description |
+|------------------|--------|---------|--------------------------------------|
+| `github.proxy` | string | `""` | HTTP proxy for GitHub API requests |
+| `github.token` | string | `""` | GitHub personal access token |
+
+### Search Settings
+
+| Config | Type | Default | Description |
+|---------------------------|------|---------|--------------------------------------------|
+| `max_concurrent_searches` | int | 2 | Max concurrent skill search requests |
+| `search_cache.max_size` | int | 50 | Max cached search results |
+| `search_cache.ttl_seconds`| int | 300 | Cache TTL in seconds |
### Configuration Example
@@ -361,11 +464,17 @@ The skills tool configures skill discovery and installation via registries like
"clawhub": {
"enabled": true,
"base_url": "https://clawhub.ai",
- "auth_token": "",
- "search_path": "/api/v1/search",
- "skills_path": "/api/v1/skills",
- "download_path": "/api/v1/download"
+ "auth_token": ""
}
+ },
+ "github": {
+ "proxy": "",
+ "token": ""
+ },
+ "max_concurrent_searches": 2,
+ "search_cache": {
+ "max_size": 50,
+ "ttl_seconds": 300
}
}
}
@@ -379,6 +488,7 @@ All configuration options can be overridden via environment variables with the f
For example:
- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
- `PICOCLAW_TOOLS_MCP_ENABLED=true`
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 219d2c6e3..096beec78 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -14,7 +14,7 @@
**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"`).
+1. **agents.defaults.model_name** 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"`
@@ -26,7 +26,7 @@ Example snippet:
{
"agents": {
"defaults": {
- "model": "openrouter-free"
+ "model_name": "openrouter-free"
}
},
"model_list": [
diff --git a/docs/vi/ANTIGRAVITY_AUTH.md b/docs/vi/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..783dc5181
--- /dev/null
+++ b/docs/vi/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,807 @@
+> Quay lại [README](../../README.vi.md)
+
+# Hướng dẫn Xác thực và Tích hợp Antigravity
+
+## Tổng quan
+
+**Antigravity** (Google Cloud Code Assist) là nhà cung cấp mô hình AI được Google hỗ trợ, cung cấp quyền truy cập vào các mô hình như Claude Opus 4.6 và Gemini thông qua hạ tầng đám mây của Google. Tài liệu này cung cấp hướng dẫn đầy đủ về cách xác thực hoạt động, cách lấy danh sách mô hình và cách triển khai nhà cung cấp mới trong PicoClaw.
+
+---
+
+## Mục lục
+
+1. [Luồng xác thực](#luồng-xác-thực)
+2. [Chi tiết triển khai OAuth](#chi-tiết-triển-khai-oauth)
+3. [Quản lý token](#quản-lý-token)
+4. [Lấy danh sách mô hình](#lấy-danh-sách-mô-hình)
+5. [Theo dõi mức sử dụng](#theo-dõi-mức-sử-dụng)
+6. [Cấu trúc plugin nhà cung cấp](#cấu-trúc-plugin-nhà-cung-cấp)
+7. [Yêu cầu tích hợp](#yêu-cầu-tích-hợp)
+8. [Các endpoint API](#các-endpoint-api)
+9. [Cấu hình](#cấu-hình)
+10. [Tạo nhà cung cấp mới trong PicoClaw](#tạo-nhà-cung-cấp-mới-trong-picoclaw)
+
+---
+
+## Luồng xác thực
+
+### 1. OAuth 2.0 với PKCE
+
+Antigravity sử dụng **OAuth 2.0 với PKCE (Proof Key for Code Exchange)** để xác thực an toàn:
+
+```
+┌─────────────┐ ┌─────────────────┐
+│ Client │ ───(1) Generate PKCE Pair────────> │ │
+│ │ ───(2) Open Auth URL─────────────> │ Google OAuth │
+│ │ │ Server │
+│ │ <──(3) Redirect with Code───────── │ │
+│ │ └─────────────────┘
+│ │ ───(4) Exchange Code for Tokens──> │ Token URL │
+│ │ │ │
+│ │ <──(5) Access + Refresh Tokens──── │ │
+└─────────────┘ └─────────────────┘
+```
+
+### 2. Các bước chi tiết
+
+#### Bước 1: Tạo tham số PKCE
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+ const verifier = randomBytes(32).toString("hex");
+ const challenge = createHash("sha256").update(verifier).digest("base64url");
+ return { verifier, challenge };
+}
+```
+
+#### Bước 2: Xây dựng URL ủy quyền
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+ const url = new URL(AUTH_URL);
+ url.searchParams.set("client_id", CLIENT_ID);
+ url.searchParams.set("response_type", "code");
+ url.searchParams.set("redirect_uri", REDIRECT_URI);
+ url.searchParams.set("scope", SCOPES.join(" "));
+ url.searchParams.set("code_challenge", params.challenge);
+ url.searchParams.set("code_challenge_method", "S256");
+ url.searchParams.set("state", params.state);
+ url.searchParams.set("access_type", "offline");
+ url.searchParams.set("prompt", "consent");
+ return url.toString();
+}
+```
+
+**Các phạm vi quyền cần thiết:**
+```typescript
+const SCOPES = [
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/userinfo.email",
+ "https://www.googleapis.com/auth/userinfo.profile",
+ "https://www.googleapis.com/auth/cclog",
+ "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### Bước 3: Xử lý callback OAuth
+
+**Chế độ tự động (Phát triển cục bộ):**
+- Khởi động máy chủ HTTP cục bộ trên cổng 51121
+- Chờ chuyển hướng từ Google
+- Trích xuất mã ủy quyền từ tham số truy vấn
+
+**Chế độ thủ công (Từ xa/Không có giao diện):**
+- Hiển thị URL ủy quyền cho người dùng
+- Người dùng hoàn tất xác thực trong trình duyệt
+- Người dùng dán URL chuyển hướng đầy đủ vào terminal
+- Phân tích mã từ URL đã dán
+
+#### Bước 4: Đổi mã lấy token
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+ code: string;
+ verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+ const response = await fetch(TOKEN_URL, {
+ method: "POST",
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
+ body: new URLSearchParams({
+ client_id: CLIENT_ID,
+ client_secret: CLIENT_SECRET,
+ code: params.code,
+ grant_type: "authorization_code",
+ redirect_uri: REDIRECT_URI,
+ code_verifier: params.verifier,
+ }),
+ });
+
+ const data = await response.json();
+
+ return {
+ access: data.access_token,
+ refresh: data.refresh_token,
+ expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+ };
+}
+```
+
+#### Bước 5: Lấy dữ liệu người dùng bổ sung
+
+**Email người dùng:**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise {
+ const response = await fetch(
+ "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+ { headers: { Authorization: `Bearer ${accessToken}` } }
+ );
+ const data = await response.json();
+ return data.email;
+}
+```
+
+**ID dự án (Bắt buộc cho các lệnh gọi API):**
+```typescript
+async function fetchProjectId(accessToken: string): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "google-api-nodejs-client/9.15.1",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ "Client-Metadata": JSON.stringify({
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ }),
+ };
+
+ const response = await fetch(
+ "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({
+ metadata: {
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ const data = await response.json();
+ return data.cloudaicompanionProject || "rising-fact-p41fc"; // Giá trị mặc định dự phòng
+}
+```
+
+---
+
+## Chi tiết triển khai OAuth
+
+### Thông tin xác thực client
+
+**Quan trọng:** Các giá trị này được mã hóa base64 trong mã nguồn để đồng bộ với pi-ai:
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+ "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### Các chế độ luồng OAuth
+
+1. **Luồng tự động** (Máy cục bộ có trình duyệt):
+ - Tự động mở trình duyệt
+ - Máy chủ callback cục bộ bắt chuyển hướng
+ - Không cần tương tác người dùng sau xác thực ban đầu
+
+2. **Luồng thủ công** (Từ xa/Không có giao diện/WSL2):
+ - Hiển thị URL để sao chép-dán thủ công
+ - Người dùng hoàn tất xác thực trong trình duyệt bên ngoài
+ - Người dùng dán lại URL chuyển hướng đầy đủ
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+ return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## Quản lý token
+
+### Cấu trúc hồ sơ xác thực
+
+```typescript
+type OAuthCredential = {
+ type: "oauth";
+ provider: "google-antigravity";
+ access: string; // Token truy cập
+ refresh: string; // Token làm mới
+ expires: number; // Dấu thời gian hết hạn (ms kể từ epoch)
+ email?: string; // Email người dùng
+ projectId?: string; // ID dự án Google Cloud
+};
+```
+
+### Làm mới token
+
+Thông tin xác thực bao gồm token làm mới có thể được sử dụng để lấy token truy cập mới khi token hiện tại hết hạn. Thời gian hết hạn được đặt với bộ đệm 5 phút để tránh điều kiện tranh chấp.
+
+---
+
+## Lấy danh sách mô hình
+
+### Lấy các mô hình khả dụng
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+ accessToken: string,
+ projectId: string
+): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ };
+
+ const response = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ const data = await response.json();
+
+ // Trả về các mô hình kèm thông tin hạn mức
+ return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+ id: modelId,
+ displayName: modelInfo.displayName,
+ quotaInfo: {
+ remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+ resetTime: modelInfo.quotaInfo?.resetTime,
+ isExhausted: modelInfo.quotaInfo?.isExhausted,
+ },
+ }));
+}
+```
+
+### Định dạng phản hồi
+
+```typescript
+type FetchAvailableModelsResponse = {
+ models?: Record;
+};
+```
+
+---
+
+## Theo dõi mức sử dụng
+
+### Lấy dữ liệu sử dụng
+
+```typescript
+export async function fetchAntigravityUsage(
+ token: string,
+ timeoutMs: number
+): Promise {
+ // 1. Lấy thông tin tín dụng và gói dịch vụ
+ const loadCodeAssistRes = await fetch(
+ `${BASE_URL}/v1internal:loadCodeAssist`,
+ {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${token}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ metadata: {
+ ideType: "ANTIGRAVITY",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ // Trích xuất thông tin tín dụng
+ const { availablePromptCredits, planInfo, currentTier } = data;
+
+ // 2. Lấy hạn mức mô hình
+ const modelsRes = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers: { Authorization: `Bearer ${token}` },
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ // Xây dựng cửa sổ sử dụng
+ return {
+ provider: "google-antigravity",
+ displayName: "Google Antigravity",
+ windows: [
+ { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+ // Hạn mức từng mô hình...
+ ],
+ plan: currentTier?.name || planType,
+ };
+}
+```
+
+### Cấu trúc phản hồi sử dụng
+
+```typescript
+type ProviderUsageSnapshot = {
+ provider: "google-antigravity";
+ displayName: string;
+ windows: UsageWindow[];
+ plan?: string;
+ error?: string;
+};
+
+type UsageWindow = {
+ label: string; // "Credits" hoặc ID mô hình
+ usedPercent: number; // 0-100
+ resetAt?: number; // Dấu thời gian khi hạn mức được đặt lại
+};
+```
+
+---
+
+## Cấu trúc plugin nhà cung cấp
+
+### Định nghĩa plugin
+
+```typescript
+const antigravityPlugin = {
+ id: "google-antigravity-auth",
+ name: "Google Antigravity Auth",
+ description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+ configSchema: emptyPluginConfigSchema(),
+
+ register(api: PicoClawPluginApi) {
+ api.registerProvider({
+ id: "google-antigravity",
+ label: "Google Antigravity",
+ docsPath: "/providers/models",
+ aliases: ["antigravity"],
+
+ auth: [
+ {
+ id: "oauth",
+ label: "Google OAuth",
+ hint: "PKCE + localhost callback",
+ kind: "oauth",
+ run: async (ctx: ProviderAuthContext) => {
+ // Triển khai OAuth tại đây
+ },
+ },
+ ],
+ });
+ },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+ config: PicoClawConfig;
+ agentDir?: string;
+ workspaceDir?: string;
+ prompter: WizardPrompter; // Lời nhắc/thông báo UI
+ runtime: RuntimeEnv; // Ghi log, v.v.
+ isRemote: boolean; // Có đang chạy từ xa không
+ openUrl: (url: string) => Promise; // Mở trình duyệt
+ oauth: {
+ createVpsAwareHandlers: Function;
+ };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+ profiles: Array<{
+ profileId: string;
+ credential: AuthProfileCredential;
+ }>;
+ configPatch?: Partial;
+ defaultModel?: string;
+ notes?: string[];
+};
+```
+
+---
+
+## Yêu cầu tích hợp
+
+### 1. Môi trường/Phụ thuộc cần thiết
+
+- Go ≥ 1.25
+- Mã nguồn PicoClaw (`pkg/providers/` và `pkg/auth/`)
+- Các gói thư viện chuẩn `crypto` và `net/http`
+
+### 2. Các header bắt buộc cho lệnh gọi API
+
+```typescript
+const REQUIRED_HEADERS = {
+ "Authorization": `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity", // hoặc "google-api-nodejs-client/9.15.1"
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// Đối với các lệnh gọi loadCodeAssist, cũng bao gồm:
+const CLIENT_METADATA = {
+ ideType: "ANTIGRAVITY", // hoặc "IDE_UNSPECIFIED"
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+};
+```
+
+### 3. Làm sạch schema mô hình
+
+Antigravity sử dụng các mô hình tương thích Gemini, vì vậy schema công cụ phải được làm sạch:
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+ "patternProperties",
+ "additionalProperties",
+ "$schema",
+ "$id",
+ "$ref",
+ "$defs",
+ "definitions",
+ "examples",
+ "minLength",
+ "maxLength",
+ "minimum",
+ "maximum",
+ "multipleOf",
+ "pattern",
+ "format",
+ "minItems",
+ "maxItems",
+ "uniqueItems",
+ "minProperties",
+ "maxProperties",
+]);
+
+// Làm sạch schema trước khi gửi
+function cleanToolSchemaForGemini(schema: Record): unknown {
+ // Xóa các từ khóa không được hỗ trợ
+ // Đảm bảo cấp cao nhất có type: "object"
+ // Làm phẳng các union anyOf/oneOf
+}
+```
+
+### 4. Xử lý khối suy nghĩ (Mô hình Claude)
+
+Đối với các mô hình Claude qua Antigravity, khối suy nghĩ cần xử lý đặc biệt:
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+ messages: AgentMessage[]
+): AgentMessage[] {
+ // Xác thực chữ ký suy nghĩ
+ // Chuẩn hóa các trường chữ ký
+ // Loại bỏ các khối suy nghĩ chưa ký
+}
+```
+
+---
+
+## Các endpoint API
+
+### Endpoint xác thực
+
+| Endpoint | Phương thức | Mục đích |
+|----------|------------|----------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | Ủy quyền OAuth |
+| `https://oauth2.googleapis.com/token` | POST | Trao đổi token |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | Thông tin người dùng (email) |
+
+### Endpoint Cloud Code Assist
+
+| Endpoint | Phương thức | Mục đích |
+|----------|------------|----------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | Tải thông tin dự án, tín dụng, gói dịch vụ |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | Liệt kê các mô hình khả dụng kèm hạn mức |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | Endpoint streaming chat |
+
+**Định dạng yêu cầu API (Chat):**
+Endpoint `v1internal:streamGenerateContent` yêu cầu một envelope bao bọc yêu cầu Gemini tiêu chuẩn:
+
+```json
+{
+ "project": "your-project-id",
+ "model": "model-id",
+ "request": {
+ "contents": [...],
+ "systemInstruction": {...},
+ "generationConfig": {...},
+ "tools": [...]
+ },
+ "requestType": "agent",
+ "userAgent": "antigravity",
+ "requestId": "agent-timestamp-random"
+}
+```
+
+**Định dạng phản hồi API (SSE):**
+Mỗi thông điệp SSE (`data: {...}`) được bao bọc trong trường `response`:
+
+```json
+{
+ "response": {
+ "candidates": [...],
+ "usageMetadata": {...},
+ "modelVersion": "...",
+ "responseId": "..."
+ },
+ "traceId": "...",
+ "metadata": {}
+}
+```
+
+---
+
+## Cấu hình
+
+### Cấu hình config.json
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gemini-flash",
+ "model": "antigravity/gemini-3-flash",
+ "auth_method": "oauth"
+ }
+ ],
+ "agents": {
+ "defaults": {
+ "model_name": "gemini-flash"
+ }
+ }
+}
+```
+
+### Lưu trữ hồ sơ xác thực
+
+Hồ sơ xác thực được lưu trữ trong `~/.picoclaw/auth.json`:
+
+```json
+{
+ "credentials": {
+ "google-antigravity": {
+ "access_token": "ya29...",
+ "refresh_token": "1//...",
+ "expires_at": "2026-01-01T00:00:00Z",
+ "provider": "google-antigravity",
+ "auth_method": "oauth",
+ "email": "user@example.com",
+ "project_id": "my-project-id"
+ }
+ }
+}
+```
+
+---
+
+## Tạo nhà cung cấp mới trong PicoClaw
+
+Các nhà cung cấp PicoClaw được triển khai dưới dạng gói Go trong `pkg/providers/`. Để thêm nhà cung cấp mới:
+
+### Triển khai từng bước
+
+#### 1. Tạo file nhà cung cấp
+
+Tạo file Go mới trong `pkg/providers/`:
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. Triển khai interface Provider
+
+Nhà cung cấp của bạn phải triển khai interface `Provider` được định nghĩa trong `pkg/providers/types.go`:
+
+```go
+package providers
+
+type YourProvider struct {
+ apiKey string
+ apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+ if apiBase == "" {
+ apiBase = "https://api.your-provider.com/v1"
+ }
+ return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+ // Triển khai hoàn thành chat với streaming
+}
+```
+
+#### 3. Đăng ký trong factory
+
+Thêm nhà cung cấp của bạn vào switch giao thức trong `pkg/providers/factory.go`:
+
+```go
+case "your-provider":
+ return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. Thêm cấu hình mặc định (Tùy chọn)
+
+Thêm mục mặc định trong `pkg/config/defaults.go`:
+
+```go
+{
+ ModelName: "your-model",
+ Model: "your-provider/model-name",
+ APIKey: "",
+},
+```
+
+#### 5. Thêm hỗ trợ xác thực (Tùy chọn)
+
+Nếu nhà cung cấp của bạn yêu cầu OAuth hoặc xác thực đặc biệt, thêm case vào `cmd/picoclaw/internal/auth/helpers.go`:
+
+```go
+case "your-provider":
+ authLoginYourProvider()
+```
+
+#### 6. Cấu hình qua `config.json`
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "your-model",
+ "model": "your-provider/model-name",
+ "api_key": "your-api-key",
+ "api_base": "https://api.your-provider.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## Kiểm thử triển khai của bạn
+
+### Lệnh CLI
+
+```bash
+# Xác thực với nhà cung cấp
+picoclaw auth login --provider your-provider
+
+# Liệt kê mô hình (cho Antigravity)
+picoclaw auth models
+
+# Khởi động gateway
+picoclaw gateway
+
+# Chạy agent với mô hình cụ thể
+picoclaw agent -m "Hello" --model your-model
+```
+
+### Biến môi trường cho kiểm thử
+
+```bash
+# Ghi đè mô hình mặc định
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# Ghi đè cài đặt nhà cung cấp
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## Tài liệu tham khảo
+
+- **File nguồn:**
+ - `pkg/providers/antigravity_provider.go` - Triển khai nhà cung cấp Antigravity
+ - `pkg/auth/oauth.go` - Triển khai luồng OAuth
+ - `pkg/auth/store.go` - Lưu trữ thông tin xác thực (`~/.picoclaw/auth.json`)
+ - `pkg/providers/factory.go` - Factory nhà cung cấp và định tuyến giao thức
+ - `pkg/providers/types.go` - Định nghĩa interface nhà cung cấp
+ - `cmd/picoclaw/internal/auth/helpers.go` - Lệnh CLI xác thực
+
+- **Tài liệu:**
+ - `docs/ANTIGRAVITY_USAGE.md` - Hướng dẫn sử dụng Antigravity
+ - `docs/migration/model-list-migration.md` - Hướng dẫn di chuyển
+
+---
+
+## Lưu ý
+
+1. **Dự án Google Cloud:** Antigravity yêu cầu Gemini for Google Cloud được bật trên dự án Google Cloud của bạn
+2. **Hạn mức:** Sử dụng hạn mức dự án Google Cloud (không tính phí riêng)
+3. **Truy cập mô hình:** Các mô hình khả dụng phụ thuộc vào cấu hình dự án Google Cloud của bạn
+4. **Khối suy nghĩ:** Mô hình Claude qua Antigravity yêu cầu xử lý đặc biệt khối suy nghĩ có chữ ký
+5. **Làm sạch schema:** Schema công cụ phải được làm sạch để loại bỏ các từ khóa JSON Schema không được hỗ trợ
+
+---
+
+## Xử lý lỗi thường gặp
+
+### 1. Giới hạn tốc độ (HTTP 429)
+
+Antigravity trả về lỗi 429 khi hạn mức dự án/mô hình đã cạn kiệt. Phản hồi lỗi thường chứa `quotaResetDelay` trong trường `details`.
+
+**Ví dụ lỗi 429:**
+```json
+{
+ "error": {
+ "code": 429,
+ "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+ "status": "RESOURCE_EXHAUSTED",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+ "metadata": {
+ "quotaResetDelay": "4h30m28.060903746s"
+ }
+ }
+ ]
+ }
+}
+```
+
+### 2. Phản hồi trống (Mô hình bị hạn chế)
+
+Một số mô hình có thể xuất hiện trong danh sách mô hình khả dụng nhưng trả về phản hồi trống (200 OK nhưng luồng SSE trống). Điều này thường xảy ra với các mô hình xem trước hoặc bị hạn chế mà dự án hiện tại không có quyền sử dụng.
+
+**Cách xử lý:** Coi phản hồi trống là lỗi, thông báo cho người dùng rằng mô hình có thể bị hạn chế hoặc không hợp lệ cho dự án của họ.
+
+---
+
+## Khắc phục sự cố
+
+### "Token expired" (Token đã hết hạn)
+- Làm mới token OAuth: `picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled" (Gemini for Google Cloud chưa được bật)
+- Bật API trong Google Cloud Console của bạn
+
+### "Project not found" (Không tìm thấy dự án)
+- Đảm bảo dự án Google Cloud của bạn đã bật các API cần thiết
+- Kiểm tra xem ID dự án có được lấy chính xác trong quá trình xác thực không
+
+### Mô hình không xuất hiện trong danh sách
+- Xác minh xác thực OAuth đã hoàn tất thành công
+- Kiểm tra lưu trữ hồ sơ xác thực: `~/.picoclaw/auth.json`
+- Chạy lại `picoclaw auth login --provider antigravity`
diff --git a/docs/vi/ANTIGRAVITY_USAGE.md b/docs/vi/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..4a696f770
--- /dev/null
+++ b/docs/vi/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> Quay lại [README](../../README.vi.md)
+
+# Sử dụng nhà cung cấp Antigravity trong PicoClaw
+
+Hướng dẫn này giải thích cách thiết lập và sử dụng nhà cung cấp **Antigravity** (Google Cloud Code Assist) trong PicoClaw.
+
+## Điều kiện tiên quyết
+
+1. Một tài khoản Google.
+2. Đã kích hoạt Google Cloud Code Assist (thường có sẵn thông qua quy trình giới thiệu "Gemini for Google Cloud").
+
+## 1. Xác thực
+
+Để xác thực với Antigravity, chạy lệnh sau:
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### Xác thực thủ công (Headless/VPS)
+Nếu bạn đang chạy trên máy chủ (Coolify/Docker) và không thể truy cập `localhost`, hãy làm theo các bước sau:
+1. Chạy lệnh ở trên.
+2. Sao chép URL được cung cấp và mở nó trong trình duyệt cục bộ của bạn.
+3. Hoàn tất đăng nhập.
+4. Trình duyệt của bạn sẽ chuyển hướng đến URL `localhost:51121` (trang sẽ không tải được).
+5. **Sao chép URL cuối cùng đó** từ thanh địa chỉ trình duyệt.
+6. **Dán nó vào terminal** nơi PicoClaw đang chờ.
+
+PicoClaw sẽ tự động trích xuất mã ủy quyền và hoàn tất quy trình.
+
+## 2. Quản lý mô hình
+
+### Liệt kê các mô hình khả dụng
+Để xem dự án của bạn có quyền truy cập vào những mô hình nào và kiểm tra hạn mức của chúng:
+
+```bash
+picoclaw auth models
+```
+
+### Chuyển đổi mô hình
+Bạn có thể thay đổi mô hình mặc định trong `~/.picoclaw/config.json` hoặc ghi đè qua CLI:
+
+```bash
+# Ghi đè cho một lệnh duy nhất
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. Sử dụng thực tế (Coolify/Docker)
+
+Nếu bạn đang triển khai qua Coolify hoặc Docker, hãy làm theo các bước sau để kiểm tra:
+
+1. **Biến môi trường**:
+ * `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2. **Lưu trữ xác thực**:
+ Nếu bạn đã đăng nhập cục bộ, bạn có thể sao chép thông tin xác thực lên máy chủ:
+ ```bash
+ scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+ ```
+ *Hoặc*, chạy lệnh `auth login` một lần trên máy chủ nếu bạn có quyền truy cập terminal.
+
+## 4. Khắc phục sự cố
+
+* **Phản hồi trống**: Nếu một mô hình trả về phản hồi trống, nó có thể bị hạn chế cho dự án của bạn. Hãy thử `gemini-3-flash` hoặc `claude-opus-4-6-thinking`.
+* **429 Giới hạn tốc độ**: Antigravity có hạn mức nghiêm ngặt. PicoClaw sẽ hiển thị "thời gian đặt lại" trong thông báo lỗi nếu bạn đạt đến giới hạn.
+* **404 Không tìm thấy**: Đảm bảo bạn đang sử dụng ID mô hình từ danh sách `picoclaw auth models`. Sử dụng ID ngắn (ví dụ: `gemini-3-flash`) thay vì đường dẫn đầy đủ.
+
+## 5. Tóm tắt các mô hình hoạt động tốt
+
+Dựa trên kiểm tra, các mô hình sau đáng tin cậy nhất:
+* `gemini-3-flash` (Nhanh, khả dụng cao)
+* `gemini-2.5-flash-lite` (Nhẹ)
+* `claude-opus-4-6-thinking` (Mạnh mẽ, bao gồm khả năng suy luận)
diff --git a/docs/vi/chat-apps.md b/docs/vi/chat-apps.md
index 1fefa00d3..d907e5e91 100644
--- a/docs/vi/chat-apps.md
+++ b/docs/vi/chat-apps.md
@@ -8,23 +8,25 @@ Trò chuyện với picoclaw của bạn qua Telegram, Discord, WhatsApp, Matrix
> **Lưu ý**: Tất cả các kênh dựa trên webhook (LINE, WeCom, v.v.) được phục vụ trên một máy chủ HTTP Gateway chung (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`). Không có port riêng cho từng kênh. Lưu ý: Feishu sử dụng chế độ WebSocket/SDK và không sử dụng máy chủ HTTP webhook chung.
-| Channel | Setup |
-| ------------ | ---------------------------------- |
-| **Telegram** | Easy (just a token) |
-| **Discord** | Easy (bot token + intents) |
-| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
-| **Matrix** | Medium (homeserver + bot access token) |
-| **QQ** | Easy (AppID + AppSecret) |
-| **DingTalk** | Medium (app credentials) |
-| **LINE** | Medium (credentials + webhook URL) |
-| **WeCom AI Bot** | Medium (Token + AES key) |
-| **Feishu** | Medium (App ID + Secret, WebSocket mode) |
-| **Slack** | Medium (Bot token + App token) |
-| **IRC** | Medium (server + TLS config) |
-| **OneBot** | Medium (QQ via OneBot protocol) |
-| **MaixCam** | Easy (Sipeed hardware integration) |
-| **Pico** | Native PicoClaw protocol |
+| Kênh | Độ khó | Mô tả | Tài liệu |
+| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Telegram** | ⭐ Dễ | Khuyến nghị, chuyển giọng nói thành văn bản, long polling (không cần IP công khai) | [Tài liệu](../channels/telegram/README.vi.md) |
+| **Discord** | ⭐ Dễ | Socket Mode, hỗ trợ nhóm/DM, hệ sinh thái bot phong phú | [Tài liệu](../channels/discord/README.vi.md) |
+| **WhatsApp** | ⭐ Dễ | Bản địa (quét QR) hoặc Bridge URL | [Tài liệu](#whatsapp) |
+| **Weixin** | ⭐ Dễ | Quét QR gốc (API Tencent iLink) | [Tài liệu](#weixin) |
+| **Slack** | ⭐ Dễ | **Socket Mode** (không cần IP công khai), doanh nghiệp | [Tài liệu](../channels/slack/README.vi.md) |
+| **Matrix** | ⭐⭐ Trung bình | Giao thức liên kết, hỗ trợ tự lưu trữ | [Tài liệu](../channels/matrix/README.vi.md) |
+| **QQ** | ⭐⭐ Trung bình | API bot chính thức, cộng đồng Trung Quốc | [Tài liệu](../channels/qq/README.vi.md) |
+| **DingTalk** | ⭐⭐ Trung bình | Chế độ Stream (không cần IP công khai), doanh nghiệp | [Tài liệu](../channels/dingtalk/README.vi.md) |
+| **LINE** | ⭐⭐⭐ Nâng cao | Yêu cầu HTTPS Webhook | [Tài liệu](../channels/line/README.vi.md) |
+| **WeCom (企业微信)** | ⭐⭐⭐ Nâng cao | Bot nhóm (Webhook), ứng dụng tùy chỉnh (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.vi.md) / [App](../channels/wecom/wecom_app/README.vi.md) / [AI Bot](../channels/wecom/wecom_aibot/README.vi.md) |
+| **Feishu (飞书)** | ⭐⭐⭐ Nâng cao | Cộng tác doanh nghiệp, nhiều tính năng | [Tài liệu](../channels/feishu/README.vi.md) |
+| **IRC** | ⭐⭐ Trung bình | Máy chủ + cấu hình TLS | [Tài liệu](#irc) |
+| **OneBot** | ⭐⭐ Trung bình | Tương thích NapCat/Go-CQHTTP, hệ sinh thái cộng đồng | [Tài liệu](../channels/onebot/README.vi.md) |
+| **MaixCam** | ⭐ Dễ | Kênh tích hợp phần cứng cho camera AI Sipeed | [Tài liệu](../channels/maixcam/README.vi.md) |
+| **Pico** | ⭐ Dễ | Kênh giao thức bản địa PicoClaw | |
+
Telegram (Khuyến nghị)
+
Discord
+
WhatsApp (native qua whatsmeow)/what
+
+Weixin (WeChat Cá nhân)
+
+
QQ /what
}
```
-> Đặt `allow_from` trống để cho phép tất cả người dùng, hoặc chỉ định số QQ để giới hạn truy cập.
+4. Chạy `picoclaw gateway` và mở QQ để trò chuyện với bot của bạn
-**3. Chạy**
+> App Secret chỉ hiển thị một lần. Lưu ngay lập tức — xem lại sẽ buộc phải đặt lại.
+>
+> Bot được tạo qua trang thiết lập nhanh ban đầu chỉ dành cho người tạo và không hỗ trợ chat nhóm. Để bật quyền truy cập nhóm, cấu hình chế độ sandbox trên [QQ Open Platform](https://q.qq.com/).
-```bash
-picoclaw gateway
-```
+**Thiết lập thủ công**
+
+Nếu bạn muốn tạo bot thủ công:
+
+* Đăng nhập tại [QQ Open Platform](https://q.qq.com/) để đăng ký làm nhà phát triển
+* Tạo bot QQ — tùy chỉnh avatar và tên
+* Sao chép **App ID** và **App Secret** từ cài đặt bot
+* Cấu hình như trên và chạy `picoclaw gateway`
+
DingTalk
+
+MaixCam
+
+
+
Matrix
+
LINE
+
WeCom (企业微信)
+
+
+Feishu (Lark)
+
+
+Slack
+
+
+IRC
+
+
+OneBot (QQ qua giao thức OneBot)
+
+
+MaixCam
diff --git a/docs/vi/configuration.md b/docs/vi/configuration.md
index 847f28e60..fecadc6ff 100644
--- a/docs/vi/configuration.md
+++ b/docs/vi/configuration.md
@@ -57,7 +57,7 @@ Mặc định, skill được tải từ:
1. `~/.picoclaw/workspace/skills` (workspace)
2. `~/.picoclaw/skills` (global)
-3. `/skills` (builtin)
+3. `<đường-dẫn-nhúng-khi-build>/skills` (tích hợp)
Cho thiết lập nâng cao/test, bạn có thể ghi đè thư mục gốc skill builtin với:
@@ -216,4 +216,149 @@ Cho tác vụ chạy lâu (tìm kiếm web, gọi API), sử dụng công cụ `
```markdown
# Tác Vụ Định Kỳ
+
+## Tác Vụ Nhanh (trả lời trực tiếp)
+
+- Báo giờ hiện tại
+
+## Tác Vụ Dài (dùng spawn cho bất đồng bộ)
+
+- Tìm kiếm tin tức AI trên web và tóm tắt
+- Kiểm tra email và báo cáo tin nhắn quan trọng
```
+
+**Hành vi chính:**
+
+| Tính năng | Mô tả |
+| ---------------- | ------------------------------------------------------------------ |
+| **spawn** | Tạo subagent bất đồng bộ, không chặn heartbeat |
+| **Ngữ cảnh độc lập** | Subagent có ngữ cảnh riêng, không có lịch sử phiên |
+| **message tool** | Subagent giao tiếp trực tiếp với người dùng qua message tool |
+| **Không chặn** | Sau khi spawn, heartbeat tiếp tục tác vụ tiếp theo |
+
+#### Luồng Giao Tiếp Của Subagent
+
+```
+Heartbeat kích hoạt
+ ↓
+Agent đọc HEARTBEAT.md
+ ↓
+Tác vụ dài: spawn subagent
+ ↓ ↓
+Tiếp tục tác vụ tiếp theo Subagent hoạt động độc lập
+ ↓ ↓
+Hoàn thành tất cả tác vụ Subagent dùng công cụ "message"
+ ↓ ↓
+Trả lời HEARTBEAT_OK Người dùng nhận kết quả trực tiếp
+```
+
+**Cấu hình:**
+
+```json
+{
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ }
+}
+```
+
+| Tùy chọn | Mặc định | Mô tả |
+| ---------- | -------- | -------------------------------------- |
+| `enabled` | `true` | Bật/tắt heartbeat |
+| `interval` | `30` | Khoảng thời gian kiểm tra tính bằng phút (tối thiểu: 5) |
+
+**Biến môi trường:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` để tắt
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` để thay đổi khoảng thời gian
+
+### Providers
+
+> [!NOTE]
+> Groq cung cấp chuyển đổi giọng nói thành văn bản miễn phí qua Whisper. Nếu được cấu hình, tin nhắn âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển đổi ở cấp độ agent.
+
+| Provider | Mục đích | Lấy API Key |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini` | LLM (Gemini trực tiếp) | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM (Zhipu trực tiếp) | [bigmodel.cn](https://bigmodel.cn) |
+| `volcengine` | LLM (Volcengine trực tiếp) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM (khuyến nghị, truy cập tất cả mô hình) | [openrouter.ai](https://openrouter.ai) |
+| `anthropic` | LLM (Claude trực tiếp) | [console.anthropic.com](https://console.anthropic.com) |
+| `openai` | LLM (GPT trực tiếp) | [platform.openai.com](https://platform.openai.com) |
+| `deepseek` | LLM (DeepSeek trực tiếp) | [platform.deepseek.com](https://platform.deepseek.com) |
+| `qwen` | LLM (Qwen trực tiếp) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq` | LLM + **Chuyển đổi giọng nói** (Whisper)| [console.groq.com](https://console.groq.com) |
+| `cerebras` | LLM (Cerebras trực tiếp) | [cerebras.ai](https://cerebras.ai) |
+| `vivgrid` | LLM (Vivgrid trực tiếp) | [vivgrid.com](https://vivgrid.com) |
+
+### Cấu Hình Mô Hình (model_list)
+
+> **Tính năng mới:** PicoClaw hiện sử dụng cách tiếp cận **lấy mô hình làm trung tâm**. Chỉ cần chỉ định định dạng `vendor/model` (ví dụ: `zhipu/glm-4.7`) để thêm provider mới — **không cần thay đổi code!**
+
+#### Tất Cả Vendor Được Hỗ Trợ
+
+| Vendor | Tiền tố `model` | API Base mặc định | Giao thức | API Key |
+| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Lấy](https://platform.openai.com) |
+| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Lấy](https://console.anthropic.com) |
+| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Lấy](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Lấy](https://platform.deepseek.com) |
+| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Lấy](https://aistudio.google.com/api-keys) |
+| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Lấy](https://console.groq.com) |
+| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Lấy](https://dashscope.console.aliyun.com) |
+| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Cục bộ (không cần key) |
+| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Lấy](https://openrouter.ai/keys) |
+| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Lấy](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **Antigravity** | `antigravity/` | Google Cloud | Custom | Chỉ OAuth |
+
+#### Cân Bằng Tải
+
+Cấu hình nhiều endpoint cho cùng tên mô hình — PicoClaw sẽ tự động round-robin:
+
+```json
+{
+ "model_list": [
+ { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
+ { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
+ ]
+}
+```
+
+#### Di Chuyển Từ Cấu Hình `providers` Cũ
+
+Cấu hình `providers` cũ đã **bị deprecated** nhưng vẫn được hỗ trợ. Xem [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Kiến Trúc Provider
+
+PicoClaw định tuyến provider theo họ giao thức:
+
+- **Tương thích OpenAI**: OpenRouter, Groq, Zhipu, endpoint kiểu vLLM và hầu hết các provider khác.
+- **Anthropic**: Hành vi API Claude gốc.
+- **Codex/OAuth**: Tuyến xác thực OAuth/token OpenAI.
+
+### Tác Vụ Đã Lên Lịch / Nhắc Nhở
+
+PicoClaw hỗ trợ tác vụ theo lịch qua công cụ `cron`.
+
+```json
+{
+ "tools": {
+ "cron": {
+ "enabled": true,
+ "exec_timeout_minutes": 5
+ }
+ }
+}
+```
+
+Tác vụ đã lên lịch được lưu trữ bền vững sau khi khởi động lại tại `~/.picoclaw/workspace/cron/`.
+
+### Chủ Đề Nâng Cao
+
+| Chủ đề | Mô tả |
+| ------ | ----- |
+| [Hệ Thống Hook](../hooks/README.md) | Hook hướng sự kiện: observer, interceptor, approval hook |
+| [Steering](../steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
+| [SubTurn](../subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
+| [Quản Lý Ngữ Cảnh](../agent-refactor/context.md) | Phát hiện ranh giới ngữ cảnh, nén |
diff --git a/docs/vi/credential_encryption.md b/docs/vi/credential_encryption.md
new file mode 100644
index 000000000..9ba24588b
--- /dev/null
+++ b/docs/vi/credential_encryption.md
@@ -0,0 +1,159 @@
+> Quay lại [README](../../README.vi.md)
+
+# Mã hóa Thông tin Xác thực
+
+PicoClaw hỗ trợ mã hóa các giá trị `api_key` trong các mục cấu hình `model_list`.
+Các khóa đã mã hóa được lưu trữ dưới dạng chuỗi `enc://` và được giải mã tự động khi khởi động.
+
+---
+
+## Bắt đầu Nhanh
+
+**1. Đặt cụm mật khẩu**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. Mã hóa khóa API**
+
+Chạy `picoclaw onboard` — nó yêu cầu nhập cụm mật khẩu và tạo khóa SSH,
+sau đó tự động mã hóa lại tất cả các mục `api_key` dạng văn bản thuần trong cấu hình
+ở lần gọi `SaveConfig` tiếp theo. Giá trị `enc://` kết quả sẽ có dạng:
+
+```
+enc://AAAA...base64...
+```
+
+**3. Dán kết quả vào cấu hình**
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-4o",
+ "model": "openai/gpt-4o",
+ "api_key": "enc://AAAA...base64...",
+ "api_base": "https://api.openai.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## Các Định dạng `api_key` được Hỗ trợ
+
+| Định dạng | Ví dụ | Hành vi |
+|-----------|-------|---------|
+| Văn bản thuần | `sk-abc123` | Sử dụng nguyên trạng |
+| Tham chiếu tệp | `file://openai.key` | Nội dung được đọc từ cùng thư mục với tệp cấu hình |
+| Đã mã hóa | `enc://` | Giải mã khi khởi động bằng `PICOCLAW_KEY_PASSPHRASE` |
+| Trống | `""` | Truyền qua không thay đổi (dùng với `auth_method: oauth`) |
+
+---
+
+## Thiết kế Mật mã
+
+### Dẫn xuất Khóa
+
+Mã hóa sử dụng **HKDF-SHA256** với khóa riêng SSH làm yếu tố thứ hai.
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### Mã hóa
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### Định dạng Truyền tải
+
+```
+enc://
+```
+
+| Trường | Kích thước | Mô tả |
+|--------|-----------|-------|
+| `salt` | 16 byte | Ngẫu nhiên mỗi lần mã hóa; đưa vào HKDF |
+| `nonce` | 12 byte | Ngẫu nhiên mỗi lần mã hóa; IV của AES-GCM |
+| `ciphertext` | thay đổi | Bản mã AES-256-GCM + thẻ xác thực 16 byte |
+
+Thẻ xác thực GCM được tự động nối vào bản mã. Bất kỳ sự giả mạo nào đều khiến giải mã thất bại với lỗi thay vì trả về văn bản thuần bị hỏng.
+
+### Hiệu suất
+
+| Thao tác | Thời gian (ARM Cortex-A) |
+|----------|--------------------------|
+| Dẫn xuất khóa (HKDF) | < 1 ms |
+| Giải mã AES-256-GCM | < 1 ms |
+| **Tổng chi phí khởi động** | **< 2 ms mỗi khóa** |
+
+---
+
+## Bảo mật Hai Yếu tố với Khóa SSH
+
+Khi khóa riêng SSH được cung cấp, việc phá vỡ mã hóa yêu cầu **cả hai**:
+
+1. **Cụm mật khẩu** (`PICOCLAW_KEY_PASSPHRASE`)
+2. **Tệp khóa riêng SSH**
+
+Điều này có nghĩa là chỉ rò rỉ tệp cấu hình không đủ để khôi phục khóa API, ngay cả khi cụm mật khẩu yếu. Khóa SSH đóng góp 256 bit entropy (Ed25519) bất kể độ mạnh của cụm mật khẩu.
+
+### Mô hình Mối đe dọa
+
+| Kẻ tấn công có | Có thể giải mã? |
+|----------------|-----------------|
+| Chỉ tệp cấu hình | Không — cần cụm mật khẩu + khóa SSH |
+| Chỉ khóa SSH | Không — cần cụm mật khẩu |
+| Chỉ cụm mật khẩu | Không — cần khóa SSH |
+| Tệp cấu hình + khóa SSH + cụm mật khẩu | Có — xâm phạm hoàn toàn |
+
+---
+
+## Biến Môi trường
+
+| Biến | Bắt buộc | Mô tả |
+|------|----------|-------|
+| `PICOCLAW_KEY_PASSPHRASE` | Có (cho `enc://`) | Cụm mật khẩu dùng để dẫn xuất khóa |
+| `PICOCLAW_SSH_KEY_PATH` | Không | Đường dẫn đến khóa riêng SSH. Nếu không đặt, tự động phát hiện từ `~/.ssh/picoclaw_ed25519.key` |
+
+### Tự động Phát hiện Khóa SSH
+
+Nếu `PICOCLAW_SSH_KEY_PATH` không được đặt, PicoClaw tìm khóa chuyên dụng:
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+Tệp chuyên dụng này tránh xung đột với các khóa SSH hiện có của người dùng.
+Chạy `picoclaw onboard` để tạo tự động.
+
+`os.UserHomeDir()` được sử dụng để phân giải thư mục home đa nền tảng (đọc `USERPROFILE` trên Windows, `HOME` trên Unix/macOS).
+
+> **Lưu ý:** Tệp khóa SSH là bắt buộc cho mã hóa thông tin xác thực. Nếu không tìm thấy khóa và `PICOCLAW_SSH_KEY_PATH` không được đặt, mã hóa/giải mã sẽ thất bại. Chạy `picoclaw onboard` để tạo khóa tự động.
+
+---
+
+## Di chuyển
+
+Vì tài liệu bí mật duy nhất là `PICOCLAW_KEY_PASSPHRASE` và tệp khóa riêng SSH, việc di chuyển rất đơn giản:
+
+1. Sao chép tệp cấu hình sang máy mới.
+2. Đặt `PICOCLAW_KEY_PASSPHRASE` với cùng giá trị.
+3. Sao chép tệp khóa riêng SSH đến cùng đường dẫn (hoặc đặt `PICOCLAW_SSH_KEY_PATH` đến vị trí mới).
+
+Không cần mã hóa lại.
+
+---
+
+## Lưu ý về Bảo mật
+
+- **Cả cụm mật khẩu và khóa SSH đều bắt buộc.** Khóa SSH đóng vai trò yếu tố thứ hai — không có nó, mã hóa/giải mã sẽ thất bại. Chạy `picoclaw onboard` để tạo khóa nếu chưa tồn tại.
+- **Khóa SSH chỉ đọc khi chạy.** PicoClaw không bao giờ ghi hoặc sửa đổi tệp khóa SSH.
+- **Khóa văn bản thuần vẫn được hỗ trợ.** Các cấu hình hiện có không dùng `enc://` không bị ảnh hưởng.
+- **Định dạng `enc://` được quản lý phiên bản** thông qua trường `info` của HKDF (`picoclaw-credential-v1`), cho phép nâng cấp thuật toán trong tương lai mà không làm hỏng các giá trị đã mã hóa hiện có.
diff --git a/docs/vi/debug.md b/docs/vi/debug.md
new file mode 100644
index 000000000..69583d486
--- /dev/null
+++ b/docs/vi/debug.md
@@ -0,0 +1,36 @@
+# Gỡ lỗi PicoClaw
+
+> Quay lại [README](../../README.vi.md)
+
+PicoClaw thực hiện nhiều tương tác phức tạp ở hậu trường cho mỗi yêu cầu nhận được — từ định tuyến tin nhắn và đánh giá độ phức tạp, đến thực thi công cụ và thích ứng với lỗi mô hình. Khả năng xem chính xác những gì đang xảy ra là rất quan trọng, không chỉ để khắc phục các sự cố tiềm ẩn, mà còn để thực sự hiểu cách agent hoạt động.
+
+## Khởi động PicoClaw ở chế độ gỡ lỗi
+
+Để nhận thông tin chi tiết về những gì agent đang thực hiện (yêu cầu LLM, lệnh gọi công cụ, định tuyến tin nhắn), bạn có thể khởi động gateway PicoClaw với cờ gỡ lỗi:
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+Ở chế độ này, hệ thống sẽ định dạng log chi tiết và hiển thị bản xem trước của prompt hệ thống và kết quả thực thi công cụ.
+
+## Tắt cắt ngắn log (log đầy đủ)
+
+Theo mặc định, PicoClaw cắt ngắn các chuỗi rất dài (như *Prompt Hệ thống* hoặc kết quả JSON lớn) trong log gỡ lỗi để giữ cho console dễ đọc.
+
+Nếu bạn cần kiểm tra đầu ra đầy đủ của một lệnh hoặc payload chính xác được gửi đến mô hình LLM, bạn có thể sử dụng cờ `--no-truncate`.
+
+**Lưu ý:** Cờ này *chỉ* hoạt động khi kết hợp với chế độ `--debug`.
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+Khi cờ này được kích hoạt, chức năng cắt ngắn toàn cục sẽ bị vô hiệu hóa. Điều này cực kỳ hữu ích để:
+
+* Xác minh cú pháp chính xác của các tin nhắn được gửi đến nhà cung cấp.
+* Đọc đầu ra đầy đủ của các công cụ như `exec`, `web_fetch` hoặc `read_file`.
+* Gỡ lỗi lịch sử phiên được lưu trong bộ nhớ.
diff --git a/docs/vi/docker.md b/docs/vi/docker.md
index 519ace5ba..eddc20a75 100644
--- a/docs/vi/docker.md
+++ b/docs/vi/docker.md
@@ -12,6 +12,7 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. Lần chạy đầu tiên — tự động tạo docker/data/config.json rồi thoát
+# (chỉ kích hoạt khi cả config.json và workspace/ đều không tồn tại)
docker compose -f docker/docker-compose.yml --profile gateway up
# Container hiển thị "First-run setup complete." và dừng lại.
diff --git a/docs/vi/hardware-compatibility.md b/docs/vi/hardware-compatibility.md
new file mode 100644
index 000000000..8315c049e
--- /dev/null
+++ b/docs/vi/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> Quay lại [README](../../README.vi.md)
+
+# 🖥️ PicoClaw Danh sách tương thích phần cứng
+
+PicoClaw chạy được trên hầu hết mọi thiết bị Linux. Trang này ghi nhận các chip, sản phẩm và bo mạch phát triển đã được xác minh.
+
+**Phần cứng của bạn chưa có trong danh sách?** Gửi PR để thêm vào! Các nhà sản xuất phần cứng được hoan nghênh đóng góp và đồng quảng bá.
+
+---
+
+## 1. Hỗ trợ chip đã xác minh
+
+### x86
+
+| Nhà sản xuất | Chip | Ghi chú |
+|--------------|------|---------|
+| Intel | Any x86 CPU (i386+) | Tất cả bộ xử lý desktop/server/laptop |
+| AMD | Any x86 CPU | Tất cả bộ xử lý desktop/server/laptop |
+
+### ARM
+
+| Kiến trúc phụ | Chip tiêu biểu | Ghi chú |
+|----------------|----------------|---------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Đơn nhân ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Đơn nhân Cortex-A7, dùng trong LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Bốn nhân Cortex-A53, dùng trong Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Bốn nhân Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Bốn nhân Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Hai nhân Cortex-A53 + NPU, dùng trong NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| Nhà sản xuất | Chip | Lõi | Ghi chú |
+|--------------|------|-----|---------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 tích hợp, dùng trong LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L tích hợp, 1 TOPS NPU, camera AI 4K SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | Dòng camera AI RISC-V |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Dùng trong HaaS506-LD1 RTU công nghiệp |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Dùng trong Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | Tuân thủ RVA23, RVV 1024-bit, suy luận AI FP8 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 lõi, 16MB cache L3, cấp desktop |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, dùng trong CanMV-K230 |
+
+### MIPS
+
+| Nhà sản xuất | Chip | Ghi chú |
+|--------------|------|---------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, dùng trong nhiều router OpenWrt (vd. Xiaomi Router 3G) |
+
+### LoongArch (loong64)
+
+| Nhà sản xuất | Chip | Ghi chú |
+|--------------|------|---------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Bốn nhân LA464 @ 2.5GHz, desktop/máy trạm |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Bốn nhân 4C/8T @ 2.5GHz, IPC tương đương Intel thế hệ 10 |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Hai nhân @ 1GHz, ứng dụng công nghiệp/IoT |
+
+---
+
+## 2. Sản phẩm đã xác minh (theo ngày phát hành)
+
+Sản phẩm tiêu dùng, router và thiết bị công nghiệp đã được kiểm thử với PicoClaw.
+
+| Năm | Sản phẩm | Kiến trúc | SoC | RAM | Danh mục |
+|-----|----------|-----------|-----|-----|----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Điện thoại thông minh |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Máy tính bảng |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Router (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV Box / Máy chủ gia đình |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Loa thông minh |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | RTU công nghiệp |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | IP-KVM Pro |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | Camera AI 4K |
+
+---
+
+## 3. Bo mạch phát triển đã xác minh (theo ngày phát hành)
+
+| Năm | Bo mạch | Kiến trúc | SoC | RAM | Liên kết mua |
+|-----|---------|-----------|-----|-----|--------------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. Cũng hoạt động trên
+
+### Điện thoại Android (qua Termux)
+
+Bất kỳ điện thoại Android ARM64 nào (2015+) với 1GB+ RAM. Cài đặt [Termux](https://github.com/termux/termux-app), sử dụng `proot` để chạy PicoClaw.
+
+> Xem [README: Chạy trên điện thoại Android cũ](../../README.vi.md#-run-on-old-android-phones) để biết hướng dẫn cài đặt.
+
+### Desktop / Máy chủ / Đám mây
+
+| Nền tảng | Ghi chú |
+|----------|---------|
+| x86_64 Linux | Binary gốc, không phụ thuộc |
+| x86_64 Windows | Binary gốc |
+| macOS (Intel / Apple Silicon) | Binary gốc |
+| Docker (any platform) | `docker compose` một dòng lệnh, xem [Hướng dẫn Docker](docker.md) |
+| OpenWrt routers | Bản dựng MIPS/ARM, yêu cầu >32MB RAM trống |
+| FreeBSD / NetBSD | Có bản dựng x86_64 và arm64 |
+
+---
+
+## 5. Yêu cầu tối thiểu
+
+| Tài nguyên | Tối thiểu | Khuyến nghị |
+|------------|-----------|-------------|
+| RAM | 10MB trống | 32MB+ trống |
+| Lưu trữ | 20MB (binary) | 50MB+ (với workspace) |
+| CPU | Bất kỳ (đơn nhân 0.6GHz+) | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| Mạng | Bắt buộc (cho các lệnh gọi API LLM) | Ethernet hoặc WiFi |
+
+---
+
+## 6. Cách kiểm thử và đóng góp
+
+```bash
+# 1. Tải xuống cho kiến trúc của bạn
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. Khởi tạo
+./picoclaw onboard
+
+# 3. Kiểm thử
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+Các bản dựng có sẵn: `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### Thêm phần cứng của bạn
+
+1. Fork kho lưu trữ này
+2. Thêm chip / sản phẩm / bo mạch của bạn vào bảng tương ứng
+3. Bao gồm: tên, kiến trúc, SoC, RAM, năm và liên kết nếu có
+4. Gửi PR
+
+Nhà sản xuất phần cứng: muốn thêm hỗ trợ chính thức hoặc đồng quảng bá? Mở issue hoặc liên hệ qua [Discord](https://discord.gg/V4sAZ9XWpN).
diff --git a/docs/vi/providers.md b/docs/vi/providers.md
index f7543eec3..09b51c56b 100644
--- a/docs/vi/providers.md
+++ b/docs/vi/providers.md
@@ -93,7 +93,7 @@ Thiết kế này cũng cho phép **hỗ trợ đa agent** với lựa chọn pr
],
"agents": {
"defaults": {
- "model": "gpt-5.4"
+ "model_name": "gpt-5.4"
}
}
}
@@ -266,13 +266,13 @@ Cấu hình `providers` cũ đã **ngừng hỗ trợ** nhưng vẫn được h
],
"agents": {
"defaults": {
- "model": "glm-4.7"
+ "model_name": "glm-4.7"
}
}
}
```
-Để xem hướng dẫn di chuyển chi tiết, xem [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
+Để xem hướng dẫn di chuyển chi tiết, xem [migration/model-list-migration.md](../migration/model-list-migration.md).
### Kiến Trúc Provider
@@ -298,7 +298,7 @@ PicoClaw định tuyến provider theo họ giao thức:
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
- "model": "glm-4.7",
+ "model_name": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
@@ -328,12 +328,11 @@ picoclaw agent -m "Hello"
{
"agents": {
"defaults": {
- "model": "anthropic/claude-opus-4-5"
+ "model_name": "anthropic/claude-opus-4-5"
}
},
"session": {
- "dm_scope": "per-channel-peer",
- "backlog_limit": 20
+ "dm_scope": "per-channel-peer"
},
"providers": {
"openrouter": {
diff --git a/docs/vi/tools_configuration.md b/docs/vi/tools_configuration.md
index 6cc4dc8b6..55e7699eb 100644
--- a/docs/vi/tools_configuration.md
+++ b/docs/vi/tools_configuration.md
@@ -41,14 +41,6 @@ Cài đặt chung để tải và xử lý nội dung trang web.
| `fetch_limit_bytes` | int | 10485760 | Kích thước tối đa của payload trang web cần tải, tính bằng byte (mặc định là 10MB). |
| `format` | string | "plaintext" | Định dạng đầu ra của nội dung đã tải. Tùy chọn: `plaintext` hoặc `markdown` (khuyến nghị). |
-### Brave
-
-| Cấu hình | Kiểu | Mặc định | Mô tả |
-|----------------|--------|----------|----------------------------|
-| `enabled` | bool | false | Bật tìm kiếm Brave |
-| `api_key` | string | - | Khóa API Brave Search |
-| `max_results` | int | 5 | Số kết quả tối đa |
-
### DuckDuckGo
| Cấu hình | Kiểu | Mặc định | Mô tả |
@@ -56,13 +48,73 @@ Cài đặt chung để tải và xử lý nội dung trang web.
| `enabled` | bool | true | Bật tìm kiếm DuckDuckGo |
| `max_results` | int | 5 | Số kết quả tối đa |
+### Baidu Search
+
+| Cấu hình | Kiểu | Mặc định | Mô tả |
+|----------------|--------|-----------------------------------------------------------------|------------------------------------|
+| `enabled` | bool | false | Bật tìm kiếm Baidu |
+| `api_key` | string | - | Khóa API Qianfan |
+| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL API Baidu Search |
+| `max_results` | int | 10 | Số kết quả tối đa |
+
+```json
+{
+ "tools": {
+ "web": {
+ "baidu_search": {
+ "enabled": true,
+ "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+ "max_results": 10
+ }
+ }
+ }
+}
+```
+
### Perplexity
| Cấu hình | Kiểu | Mặc định | Mô tả |
|----------------|--------|----------|-------------------------------|
-| `enabled` | bool | false | Bật tìm kiếm Perplexity |
-| `api_key` | string | - | Khóa API Perplexity |
-| `max_results` | int | 5 | Số kết quả tối đa |
+| `enabled` | bool | false | Bật tìm kiếm Perplexity |
+| `api_key` | string | - | Khóa API Perplexity |
+| `api_keys` | string[] | - | Nhiều khóa API Perplexity để xoay vòng (ưu tiên hơn `api_key`) |
+| `max_results` | int | 5 | Số kết quả tối đa |
+
+### Brave
+
+| Cấu hình | Kiểu | Mặc định | Mô tả |
+|----------------|--------|----------|----------------------------|
+| `enabled` | bool | false | Bật tìm kiếm Brave |
+| `api_key` | string | - | Khóa API Brave Search |
+| `api_keys` | string[] | - | Nhiều khóa API Brave Search để xoay vòng (ưu tiên hơn `api_key`) |
+| `max_results` | int | 5 | Số kết quả tối đa |
+
+### Tavily
+
+| Cấu hình | Kiểu | Mặc định | Mô tả |
+|----------------|--------|----------|------------------------------------|
+| `enabled` | bool | false | Bật tìm kiếm Tavily |
+| `api_key` | string | - | Khóa API Tavily |
+| `base_url` | string | - | URL cơ sở Tavily tùy chỉnh |
+| `max_results` | int | 0 | Số kết quả tối đa (0 = mặc định) |
+
+### SearXNG
+
+| Cấu hình | Kiểu | Mặc định | Mô tả |
+|----------------|--------|--------------------------|----------------------------|
+| `enabled` | bool | false | Bật tìm kiếm SearXNG |
+| `base_url` | string | `http://localhost:8888` | URL phiên bản SearXNG |
+| `max_results` | int | 5 | Số kết quả tối đa |
+
+### GLM Search
+
+| Cấu hình | Kiểu | Mặc định | Mô tả |
+|------------------|--------|------------------------------------------------------|----------------------------|
+| `enabled` | bool | false | Bật GLM Search |
+| `api_key` | string | - | Khóa API GLM |
+| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL API GLM Search |
+| `search_engine` | string | `search_std` | Loại công cụ tìm kiếm |
+| `max_results` | int | 5 | Số kết quả tối đa |
## Công cụ Exec
@@ -70,9 +122,32 @@ Công cụ exec được sử dụng để thực thi các lệnh shell.
| Cấu hình | Kiểu | Mặc định | Mô tả |
|--------------------------|-------|----------|------------------------------------------------|
+| `enabled` | bool | true | Bật công cụ exec |
| `enable_deny_patterns` | bool | true | Bật chặn lệnh nguy hiểm mặc định |
| `custom_deny_patterns` | array | [] | Mẫu từ chối tùy chỉnh (biểu thức chính quy) |
+### Vô hiệu hóa Công cụ Exec
+
+Để hoàn toàn vô hiệu hóa công cụ `exec`, đặt `enabled` thành `false`:
+
+**Qua tệp cấu hình:**
+```json
+{
+ "tools": {
+ "exec": {
+ "enabled": false
+ }
+ }
+}
+```
+
+**Qua biến môi trường:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Lưu ý:** Khi bị vô hiệu hóa, agent sẽ không thể thực thi lệnh shell. Điều này cũng ảnh hưởng đến khả năng chạy lệnh shell theo lịch của công cụ Cron.
+
### Chức năng
- **`enable_deny_patterns`**: Đặt thành `false` để tắt hoàn toàn các mẫu chặn lệnh nguy hiểm mặc định
@@ -329,6 +404,7 @@ Tất cả các tùy chọn cấu hình có thể được ghi đè qua biến m
Ví dụ:
- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
- `PICOCLAW_TOOLS_MCP_ENABLED=true`
diff --git a/docs/vi/troubleshooting.md b/docs/vi/troubleshooting.md
index d74153aa3..961c932aa 100644
--- a/docs/vi/troubleshooting.md
+++ b/docs/vi/troubleshooting.md
@@ -16,7 +16,7 @@
**Cách sửa:** Trong `~/.picoclaw/config.json` (hoặc đường dẫn cấu hình của bạn):
-1. **agents.defaults.model** phải khớp với một `model_name` trong `model_list` (ví dụ: `"openrouter-free"`).
+1. **agents.defaults.model_name** phải khớp với một `model_name` trong `model_list` (ví dụ: `"openrouter-free"`).
2. **model** của mục đó phải là ID mô hình OpenRouter hợp lệ, ví dụ:
- `"openrouter/free"` – tầng miễn phí tự động
- `"google/gemini-2.0-flash-exp:free"`
@@ -28,7 +28,7 @@ Ví dụ:
{
"agents": {
"defaults": {
- "model": "openrouter-free"
+ "model_name": "openrouter-free"
}
},
"model_list": [
diff --git a/docs/zh/ANTIGRAVITY_AUTH.md b/docs/zh/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..db7c81dea
--- /dev/null
+++ b/docs/zh/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,809 @@
+> 返回 [README](../../README.zh.md)
+
+# Antigravity 认证与集成指南
+
+## 概述
+
+**Antigravity**（Google Cloud Code Assist）是由 Google 支持的 AI 模型提供商，通过 Google 的云基础设施提供对 Claude Opus 4.6 和 Gemini 等模型的访问。本文档提供了关于认证工作原理、如何获取模型以及如何在 PicoClaw 中实现新提供商的完整指南。
+
+---
+
+## 目录
+
+1. [认证流程](#认证流程)
+2. [OAuth 实现细节](#oauth-实现细节)
+3. [令牌管理](#令牌管理)
+4. [模型列表获取](#模型列表获取)
+5. [用量追踪](#用量追踪)
+6. [提供商插件结构](#提供商插件结构)
+7. [集成要求](#集成要求)
+8. [API 端点](#api-端点)
+9. [配置](#配置)
+10. [在 PicoClaw 中创建新提供商](#在-picoclaw-中创建新提供商)
+
+---
+
+## 认证流程
+
+### 1. 带 PKCE 的 OAuth 2.0
+
+Antigravity 使用 **OAuth 2.0 with PKCE（Proof Key for Code Exchange）** 进行安全认证：
+
+```
+┌─────────────┐ ┌─────────────────┐
+│ Client │ ───(1) Generate PKCE Pair────────> │ │
+│ │ ───(2) Open Auth URL─────────────> │ Google OAuth │
+│ │ │ Server │
+│ │ <──(3) Redirect with Code───────── │ │
+│ │ └─────────────────┘
+│ │ ───(4) Exchange Code for Tokens──> │ Token URL │
+│ │ │ │
+│ │ <──(5) Access + Refresh Tokens──── │ │
+└─────────────┘ └─────────────────┘
+```
+
+### 2. 详细步骤
+
+#### 步骤 1：生成 PKCE 参数
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+ const verifier = randomBytes(32).toString("hex");
+ const challenge = createHash("sha256").update(verifier).digest("base64url");
+ return { verifier, challenge };
+}
+```
+
+#### 步骤 2：构建授权 URL
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+ const url = new URL(AUTH_URL);
+ url.searchParams.set("client_id", CLIENT_ID);
+ url.searchParams.set("response_type", "code");
+ url.searchParams.set("redirect_uri", REDIRECT_URI);
+ url.searchParams.set("scope", SCOPES.join(" "));
+ url.searchParams.set("code_challenge", params.challenge);
+ url.searchParams.set("code_challenge_method", "S256");
+ url.searchParams.set("state", params.state);
+ url.searchParams.set("access_type", "offline");
+ url.searchParams.set("prompt", "consent");
+ return url.toString();
+}
+```
+
+**所需权限范围：**
+```typescript
+const SCOPES = [
+ "https://www.googleapis.com/auth/cloud-platform",
+ "https://www.googleapis.com/auth/userinfo.email",
+ "https://www.googleapis.com/auth/userinfo.profile",
+ "https://www.googleapis.com/auth/cclog",
+ "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### 步骤 3：处理 OAuth 回调
+
+**自动模式（本地开发）：**
+- 在端口 51121 上启动本地 HTTP 服务器
+- 等待来自 Google 的重定向
+- 从查询参数中提取授权码
+
+**手动模式（远程/无头环境）：**
+- 向用户显示授权 URL
+- 用户在浏览器中完成认证
+- 用户将完整的重定向 URL 粘贴回终端
+- 从粘贴的 URL 中解析授权码
+
+#### 步骤 4：用授权码交换令牌
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+ code: string;
+ verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+ const response = await fetch(TOKEN_URL, {
+ method: "POST",
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
+ body: new URLSearchParams({
+ client_id: CLIENT_ID,
+ client_secret: CLIENT_SECRET,
+ code: params.code,
+ grant_type: "authorization_code",
+ redirect_uri: REDIRECT_URI,
+ code_verifier: params.verifier,
+ }),
+ });
+
+ const data = await response.json();
+
+ return {
+ access: data.access_token,
+ refresh: data.refresh_token,
+ expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+ };
+}
+```
+
+#### 步骤 5：获取额外的用户数据
+
+**用户邮箱：**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise {
+ const response = await fetch(
+ "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+ { headers: { Authorization: `Bearer ${accessToken}` } }
+ );
+ const data = await response.json();
+ return data.email;
+}
+```
+
+**项目 ID（API 调用必需）：**
+```typescript
+async function fetchProjectId(accessToken: string): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "google-api-nodejs-client/9.15.1",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ "Client-Metadata": JSON.stringify({
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ }),
+ };
+
+ const response = await fetch(
+ "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({
+ metadata: {
+ ideType: "IDE_UNSPECIFIED",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ const data = await response.json();
+ return data.cloudaicompanionProject || "rising-fact-p41fc"; // 默认回退值
+}
+```
+
+---
+
+## OAuth 实现细节
+
+### 客户端凭据
+
+**重要：** 这些凭据在源代码中以 base64 编码存储，用于与 pi-ai 同步：
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+ "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### OAuth 流程模式
+
+1. **自动流程**（有浏览器的本地机器）：
+ - 自动打开浏览器
+ - 本地回调服务器捕获重定向
+ - 初始认证后无需用户交互
+
+2. **手动流程**（远程/无头/WSL2 环境）：
+ - 显示 URL 供手动复制粘贴
+ - 用户在外部浏览器中完成认证
+ - 用户将完整的重定向 URL 粘贴回来
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+ return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## 令牌管理
+
+### 认证配置文件结构
+
+```typescript
+type OAuthCredential = {
+ type: "oauth";
+ provider: "google-antigravity";
+ access: string; // 访问令牌
+ refresh: string; // 刷新令牌
+ expires: number; // 过期时间戳（毫秒，自 epoch 起）
+ email?: string; // 用户邮箱
+ projectId?: string; // Google Cloud 项目 ID
+};
+```
+
+### 令牌刷新
+
+凭据包含一个刷新令牌，可在当前访问令牌过期时用于获取新的访问令牌。过期时间设置了 5 分钟的缓冲区以防止竞态条件。
+
+---
+
+## 模型列表获取
+
+### 获取可用模型
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+ accessToken: string,
+ projectId: string
+): Promise {
+ const headers = {
+ Authorization: `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity",
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+ };
+
+ const response = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers,
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ const data = await response.json();
+
+ // 返回带有配额信息的模型
+ return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+ id: modelId,
+ displayName: modelInfo.displayName,
+ quotaInfo: {
+ remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+ resetTime: modelInfo.quotaInfo?.resetTime,
+ isExhausted: modelInfo.quotaInfo?.isExhausted,
+ },
+ }));
+}
+```
+
+### 响应格式
+
+```typescript
+type FetchAvailableModelsResponse = {
+ models?: Record;
+};
+```
+
+---
+
+## 用量追踪
+
+### 获取用量数据
+
+```typescript
+export async function fetchAntigravityUsage(
+ token: string,
+ timeoutMs: number
+): Promise {
+ // 1. 获取额度和计划信息
+ const loadCodeAssistRes = await fetch(
+ `${BASE_URL}/v1internal:loadCodeAssist`,
+ {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${token}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ metadata: {
+ ideType: "ANTIGRAVITY",
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+ },
+ }),
+ }
+ );
+
+ // 提取额度信息
+ const { availablePromptCredits, planInfo, currentTier } = data;
+
+ // 2. 获取模型配额
+ const modelsRes = await fetch(
+ `${BASE_URL}/v1internal:fetchAvailableModels`,
+ {
+ method: "POST",
+ headers: { Authorization: `Bearer ${token}` },
+ body: JSON.stringify({ project: projectId }),
+ }
+ );
+
+ // 构建用量窗口
+ return {
+ provider: "google-antigravity",
+ displayName: "Google Antigravity",
+ windows: [
+ { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+ // 各模型配额...
+ ],
+ plan: currentTier?.name || planType,
+ };
+}
+```
+
+### 用量响应结构
+
+```typescript
+type ProviderUsageSnapshot = {
+ provider: "google-antigravity";
+ displayName: string;
+ windows: UsageWindow[];
+ plan?: string;
+ error?: string;
+};
+
+type UsageWindow = {
+ label: string; // "Credits" 或模型 ID
+ usedPercent: number; // 0-100
+ resetAt?: number; // 配额重置的时间戳
+};
+```
+
+---
+
+## 提供商插件结构
+
+### 插件定义
+
+```typescript
+const antigravityPlugin = {
+ id: "google-antigravity-auth",
+ name: "Google Antigravity Auth",
+ description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+ configSchema: emptyPluginConfigSchema(),
+
+ register(api: PicoClawPluginApi) {
+ api.registerProvider({
+ id: "google-antigravity",
+ label: "Google Antigravity",
+ docsPath: "/providers/models",
+ aliases: ["antigravity"],
+
+ auth: [
+ {
+ id: "oauth",
+ label: "Google OAuth",
+ hint: "PKCE + localhost callback",
+ kind: "oauth",
+ run: async (ctx: ProviderAuthContext) => {
+ // OAuth 实现在此处
+ },
+ },
+ ],
+ });
+ },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+ config: PicoClawConfig;
+ agentDir?: string;
+ workspaceDir?: string;
+ prompter: WizardPrompter; // UI 提示/通知
+ runtime: RuntimeEnv; // 日志等
+ isRemote: boolean; // 是否在远程运行
+ openUrl: (url: string) => Promise; // 浏览器打开器
+ oauth: {
+ createVpsAwareHandlers: Function;
+ };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+ profiles: Array<{
+ profileId: string;
+ credential: AuthProfileCredential;
+ }>;
+ configPatch?: Partial;
+ defaultModel?: string;
+ notes?: string[];
+};
+```
+
+---
+
+## 集成要求
+
+### 1. 所需环境/依赖
+
+- Go ≥ 1.25
+- PicoClaw 代码库（`pkg/providers/` 和 `pkg/auth/`）
+- `crypto` 和 `net/http` 标准库包
+
+### 2. API 调用所需的请求头
+
+```typescript
+const REQUIRED_HEADERS = {
+ "Authorization": `Bearer ${accessToken}`,
+ "Content-Type": "application/json",
+ "User-Agent": "antigravity", // 或 "google-api-nodejs-client/9.15.1"
+ "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// 对于 loadCodeAssist 调用，还需包含：
+const CLIENT_METADATA = {
+ ideType: "ANTIGRAVITY", // 或 "IDE_UNSPECIFIED"
+ platform: "PLATFORM_UNSPECIFIED",
+ pluginType: "GEMINI",
+};
+```
+
+### 3. 模型 Schema 清理
+
+Antigravity 使用兼容 Gemini 的模型，因此工具 schema 必须进行清理：
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+ "patternProperties",
+ "additionalProperties",
+ "$schema",
+ "$id",
+ "$ref",
+ "$defs",
+ "definitions",
+ "examples",
+ "minLength",
+ "maxLength",
+ "minimum",
+ "maximum",
+ "multipleOf",
+ "pattern",
+ "format",
+ "minItems",
+ "maxItems",
+ "uniqueItems",
+ "minProperties",
+ "maxProperties",
+]);
+
+// 发送前清理 schema
+function cleanToolSchemaForGemini(schema: Record): unknown {
+ // 移除不支持的关键字
+ // 确保顶层有 type: "object"
+ // 展平 anyOf/oneOf 联合类型
+}
+```
+
+### 4. 思维块处理（Claude 模型）
+
+对于 Antigravity 的 Claude 模型，思维块需要特殊处理：
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+ messages: AgentMessage[]
+): AgentMessage[] {
+ // 验证思维签名
+ // 规范化签名字段
+ // 丢弃未签名的思维块
+}
+```
+
+---
+
+## API 端点
+
+### 认证端点
+
+| 端点 | 方法 | 用途 |
+|------|------|------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | OAuth 授权 |
+| `https://oauth2.googleapis.com/token` | POST | 令牌交换 |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | 用户信息（邮箱） |
+
+### Cloud Code Assist 端点
+
+| 端点 | 方法 | 用途 |
+|------|------|------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | 加载项目信息、额度、计划 |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | 列出可用模型及配额 |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | 聊天流式端点 |
+
+**API 请求格式（聊天）：**
+`v1internal:streamGenerateContent` 端点期望一个包装标准 Gemini 请求的信封格式：
+
+```json
+{
+ "project": "your-project-id",
+ "model": "model-id",
+ "request": {
+ "contents": [...],
+ "systemInstruction": {...},
+ "generationConfig": {...},
+ "tools": [...]
+ },
+ "requestType": "agent",
+ "userAgent": "antigravity",
+ "requestId": "agent-timestamp-random"
+}
+```
+
+**API 响应格式（SSE）：**
+每条 SSE 消息（`data: {...}`）被包装在 `response` 字段中：
+
+```json
+{
+ "response": {
+ "candidates": [...],
+ "usageMetadata": {...},
+ "modelVersion": "...",
+ "responseId": "..."
+ },
+ "traceId": "...",
+ "metadata": {}
+}
+```
+
+---
+
+## 配置
+
+### config.json 配置
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gemini-flash",
+ "model": "antigravity/gemini-3-flash",
+ "auth_method": "oauth"
+ }
+ ],
+ "agents": {
+ "defaults": {
+ "model_name": "gemini-flash"
+ }
+ }
+}
+```
+
+### 认证配置文件存储
+
+认证配置文件存储在 `~/.picoclaw/auth.json` 中：
+
+```json
+{
+ "credentials": {
+ "google-antigravity": {
+ "access_token": "ya29...",
+ "refresh_token": "1//...",
+ "expires_at": "2026-01-01T00:00:00Z",
+ "provider": "google-antigravity",
+ "auth_method": "oauth",
+ "email": "user@example.com",
+ "project_id": "my-project-id"
+ }
+ }
+}
+```
+
+---
+
+## 在 PicoClaw 中创建新提供商
+
+PicoClaw 提供商以 Go 包的形式实现，位于 `pkg/providers/` 下。要添加新提供商：
+
+### 分步实现
+
+#### 1. 创建提供商文件
+
+在 `pkg/providers/` 中创建新的 Go 文件：
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. 实现 Provider 接口
+
+你的提供商必须实现 `pkg/providers/types.go` 中定义的 `Provider` 接口：
+
+```go
+package providers
+
+type YourProvider struct {
+ apiKey string
+ apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+ if apiBase == "" {
+ apiBase = "https://api.your-provider.com/v1"
+ }
+ return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+ // 实现带流式传输的聊天补全
+}
+```
+
+#### 3. 在工厂中注册
+
+将你的提供商添加到 `pkg/providers/factory.go` 中的协议分支：
+
+```go
+case "your-provider":
+ return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. 添加默认配置（可选）
+
+在 `pkg/config/defaults.go` 中添加默认条目：
+
+```go
+{
+ ModelName: "your-model",
+ Model: "your-provider/model-name",
+ APIKey: "",
+},
+```
+
+#### 5. 添加认证支持（可选）
+
+如果你的提供商需要 OAuth 或特殊认证，在 `cmd/picoclaw/internal/auth/helpers.go` 中添加分支：
+
+```go
+case "your-provider":
+ authLoginYourProvider()
+```
+
+#### 6. 通过 `config.json` 配置
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "your-model",
+ "model": "your-provider/model-name",
+ "api_key": "your-api-key",
+ "api_base": "https://api.your-provider.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## 测试你的实现
+
+### CLI 命令
+
+```bash
+# 使用提供商进行认证
+picoclaw auth login --provider your-provider
+
+# 列出模型（用于 Antigravity）
+picoclaw auth models
+
+# 启动网关
+picoclaw gateway
+
+# 使用指定模型运行代理
+picoclaw agent -m "Hello" --model your-model
+```
+
+### 测试用环境变量
+
+```bash
+# 覆盖默认模型
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# 覆盖提供商设置
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## 参考资料
+
+- **源文件：**
+ - `pkg/providers/antigravity_provider.go` - Antigravity 提供商实现
+ - `pkg/auth/oauth.go` - OAuth 流程实现
+ - `pkg/auth/store.go` - 认证凭据存储（`~/.picoclaw/auth.json`）
+ - `pkg/providers/factory.go` - 提供商工厂和协议路由
+ - `pkg/providers/types.go` - 提供商接口定义
+ - `cmd/picoclaw/internal/auth/helpers.go` - 认证 CLI 命令
+
+- **文档：**
+ - `docs/ANTIGRAVITY_USAGE.md` - Antigravity 使用指南
+ - `docs/migration/model-list-migration.md` - 迁移指南
+
+---
+
+## 注意事项
+
+1. **Google Cloud 项目：** Antigravity 要求在你的 Google Cloud 项目上启用 Gemini for Google Cloud
+2. **配额：** 使用 Google Cloud 项目配额（非独立计费）
+3. **模型访问：** 可用模型取决于你的 Google Cloud 项目配置
+4. **思维块：** 通过 Antigravity 使用的 Claude 模型需要对带签名的思维块进行特殊处理
+5. **Schema 清理：** 工具 schema 必须清理以移除不支持的 JSON Schema 关键字
+
+---
+
+---
+
+## 常见错误处理
+
+### 1. 速率限制（HTTP 429）
+
+当项目/模型配额耗尽时，Antigravity 会返回 429 错误。错误响应通常在 `details` 字段中包含 `quotaResetDelay`。
+
+**429 错误示例：**
+```json
+{
+ "error": {
+ "code": 429,
+ "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+ "status": "RESOURCE_EXHAUSTED",
+ "details": [
+ {
+ "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+ "metadata": {
+ "quotaResetDelay": "4h30m28.060903746s"
+ }
+ }
+ ]
+ }
+}
+```
+
+### 2. 空响应（受限模型）
+
+某些模型可能出现在可用模型列表中，但返回空响应（200 OK 但 SSE 流为空）。这通常发生在当前项目没有权限使用的预览版或受限模型上。
+
+**处理方式：** 将空响应视为错误，通知用户该模型可能对其项目受限或无效。
+
+---
+
+## 故障排除
+
+### "Token expired"（令牌已过期）
+- 刷新 OAuth 令牌：`picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled"（Gemini for Google Cloud 未启用）
+- 在 Google Cloud Console 中启用该 API
+
+### "Project not found"（项目未找到）
+- 确保你的 Google Cloud 项目已启用必要的 API
+- 检查认证过程中项目 ID 是否正确获取
+
+### 模型未出现在列表中
+- 验证 OAuth 认证是否成功完成
+- 检查认证配置文件存储：`~/.picoclaw/auth.json`
+- 重新运行 `picoclaw auth login --provider antigravity`
diff --git a/docs/zh/ANTIGRAVITY_USAGE.md b/docs/zh/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..2218618a9
--- /dev/null
+++ b/docs/zh/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> 返回 [README](../../README.zh.md)
+
+# 在 PicoClaw 中使用 Antigravity 提供商
+
+本指南介绍如何在 PicoClaw 中设置和使用 **Antigravity**（Google Cloud Code Assist）提供商。
+
+## 前提条件
+
+1. 一个 Google 账户。
+2. 已启用 Google Cloud Code Assist（通常通过"Gemini for Google Cloud"引导流程获取）。
+
+## 1. 身份验证
+
+要使用 Antigravity 进行身份验证，请运行以下命令：
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### 手动验证（无界面/VPS 环境）
+如果你在服务器（Coolify/Docker）上运行且无法访问 `localhost`，请按照以下步骤操作：
+1. 运行上述命令。
+2. 复制提供的 URL 并在本地浏览器中打开。
+3. 完成登录。
+4. 浏览器将重定向到 `localhost:51121` URL（页面将无法加载）。
+5. **从浏览器地址栏复制该最终 URL**。
+6. **将其粘贴回 PicoClaw 正在等待的终端中**。
+
+PicoClaw 将自动提取授权码并完成流程。
+
+## 2. 管理模型
+
+### 列出可用模型
+查看你的项目可以访问哪些模型并检查其配额：
+
+```bash
+picoclaw auth models
+```
+
+### 切换模型
+你可以在 `~/.picoclaw/config.json` 中更改默认模型，或通过 CLI 覆盖：
+
+```bash
+# 为单个命令覆盖
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. 实际使用（Coolify/Docker）
+
+如果你通过 Coolify 或 Docker 部署，请按照以下步骤进行测试：
+
+1. **环境变量**：
+ * `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2. **身份验证持久化**：
+ 如果你已在本地登录，可以将凭据复制到服务器：
+ ```bash
+ scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+ ```
+ *或者*，如果你有终端访问权限，可以在服务器上运行一次 `auth login` 命令。
+
+## 4. 故障排除
+
+* **空响应**：如果模型返回空回复，可能是该模型在你的项目中受到限制。请尝试 `gemini-3-flash` 或 `claude-opus-4-6-thinking`。
+* **429 速率限制**：Antigravity 有严格的配额限制。如果触发限制，PicoClaw 将在错误消息中显示"重置时间"。
+* **404 未找到**：确保你使用的是 `picoclaw auth models` 列表中的模型 ID。请使用短 ID（例如 `gemini-3-flash`），而非完整路径。
+
+## 5. 可用模型总结
+
+根据测试，以下模型最为可靠：
+* `gemini-3-flash`（快速，高可用性）
+* `gemini-2.5-flash-lite`（轻量级）
+* `claude-opus-4-6-thinking`（强大，包含推理能力）
diff --git a/docs/zh/chat-apps.md b/docs/zh/chat-apps.md
index 4957fbcca..aeba7d460 100644
--- a/docs/zh/chat-apps.md
+++ b/docs/zh/chat-apps.md
@@ -14,7 +14,8 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
| -------------------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Telegram** | ⭐ 简单 | 推荐，支持语音转文字，长轮询无需公网 | [查看文档](../channels/telegram/README.zh.md) |
| **Discord** | ⭐ 简单 | Socket Mode，支持群组/私信，Bot 生态成熟 | [查看文档](../channels/discord/README.zh.md) |
-| **WhatsApp** | ⭐ 简单 | 原生 (QR 扫码) 或 Bridge URL | [查看文档](../channels/whatsapp/README.zh.md) |
+| **WhatsApp** | ⭐ 简单 | 原生 (QR 扫码) 或 Bridge URL | [查看文档](#whatsapp) |
+| **微信 (Weixin)** | ⭐ 简单 | 原生扫码（腾讯 iLink API） | [查看文档](#weixin) |
| **Slack** | ⭐ 简单 | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](../channels/slack/README.zh.md) |
| **Matrix** | ⭐⭐ 中等 | 联邦协议，支持自建 homeserver 与公开服务器 | [查看文档](../channels/matrix/README.zh.md) |
| **QQ** | ⭐⭐ 中等 | 官方机器人 API，适合国内社群 | [查看文档](../channels/qq/README.zh.md) |
@@ -22,13 +23,14 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
| **LINE** | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook | [查看文档](../channels/line/README.zh.md) |
| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)、自建应用(API)和智能机器人(AI Bot) | [Bot 文档](../channels/wecom/wecom_bot/README.zh.md) / [App 文档](../channels/wecom/wecom_app/README.zh.md) / [AI Bot 文档](../channels/wecom/wecom_aibot/README.zh.md) |
| **飞书 (Feishu)** | ⭐⭐⭐ 较难 | 企业级协作，功能丰富 | [查看文档](../channels/feishu/README.zh.md) |
-| **IRC** | ⭐⭐ 中等 | 服务器 + TLS 配置 | - |
+| **IRC** | ⭐⭐ 中等 | 服务器 + TLS 配置 | [查看文档](#irc) |
| **OneBot** | ⭐⭐ 中等 | 兼容 NapCat/Go-CQHTTP，社区生态丰富 | [查看文档](../channels/onebot/README.zh.md) |
| **MaixCam** | ⭐ 简单 | 专为 AI 摄像头设计的硬件集成通道 | [查看文档](../channels/maixcam/README.zh.md) |
| **Pico** | ⭐ 简单 | PicoClaw 原生协议通道 | |
---
+
Telegram （推荐） `
+- `/use `，然后在下一条消息里发送真正的请求
+- `/use clear`
+
+
Discord
+
WhatsApp （原生 whatsmeow）
+
+微信 (Weixin)
+
+
Matrix
+
QQ
+
Slack
+
IRC
+
钉钉 (DingTalk)
+
LINE
+
飞书 (Feishu)
+
企业微信 (WeCom)
+
-OneBot OneBot（通过 OneBot 协议连接 QQ）
+
MaixCam /skills`（内置）
+3. `<构建时嵌入路径>/skills`（内置）
在高级/测试场景下，可通过以下环境变量覆盖内置技能目录：
@@ -65,6 +65,24 @@ PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/work
export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
```
+### 在聊天频道中使用技能
+
+技能安装完成后，可以直接在聊天频道里查看并显式启用它们：
+
+- `/list skills`：显示当前 Agent 可用的已安装技能名称。
+- `/use `：只对当前这一条请求强制使用指定技能。
+- `/use `：为同一会话中的下一条消息预先启用该技能。
+- `/use clear`：取消通过 `/use ` 设置的待应用技能。
+
+示例：
+
+```text
+/list skills
+/use git explain how to squash the last 3 commits
+/use italiapersonalfinance
+dammi le ultime news
+```
+
### 统一命令执行策略
- 通用斜杠命令通过 `pkg/agent/loop.go` 中的 `commands.Executor` 统一执行。
@@ -256,3 +274,356 @@ Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具
- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
+
+#### 子 Agent 通信流程
+
+```
+心跳触发
+ ↓
+Agent 读取 HEARTBEAT.md
+ ↓
+遇到耗时任务：spawn 子 Agent
+ ↓ ↓
+继续处理下一个任务 子 Agent 独立运行
+ ↓ ↓
+所有任务完成 子 Agent 使用 "message" 工具
+ ↓ ↓
+回复 HEARTBEAT_OK 用户直接收到结果
+```
+
+子 Agent 拥有工具访问权限（message、web_search 等），可以独立与用户通信，无需经过主 Agent。
+
+### Providers（模型提供商）
+
+> [!NOTE]
+> Groq 通过 Whisper 提供免费语音转录。配置后，任意渠道的语音消息都会在 Agent 层自动转录为文字。
+
+| 提供商 | 用途 | 获取 API Key |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini` | LLM（Gemini 直连） | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM（智谱直连） | [bigmodel.cn](https://bigmodel.cn) |
+| `volcengine` | LLM（火山引擎直连） | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM（推荐，可访问所有模型） | [openrouter.ai](https://openrouter.ai) |
+| `anthropic` | LLM（Claude 直连） | [console.anthropic.com](https://console.anthropic.com) |
+| `openai` | LLM（GPT 直连） | [platform.openai.com](https://platform.openai.com) |
+| `deepseek` | LLM（DeepSeek 直连） | [platform.deepseek.com](https://platform.deepseek.com) |
+| `qwen` | LLM（通义千问直连） | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq` | LLM + **语音转录**（Whisper） | [console.groq.com](https://console.groq.com) |
+| `cerebras` | LLM（Cerebras 直连） | [cerebras.ai](https://cerebras.ai) |
+| `vivgrid` | LLM（Vivgrid 直连） | [vivgrid.com](https://vivgrid.com) |
+
+### 模型配置 (model_list)
+
+> **新特性：** PicoClaw 现在采用**以模型为中心**的配置方式。只需指定 `vendor/model` 格式（例如 `zhipu/glm-4.7`）即可接入新提供商——**无需修改任何代码！**
+
+这一设计同时支持**多 Agent**场景，灵活选择提供商：
+
+- **不同 Agent 使用不同提供商**：每个 Agent 可以使用独立的 LLM 提供商
+- **模型降级**：配置主模型和备用模型，提升可用性
+- **负载均衡**：将请求分发到多个端点
+- **集中管理**：在一处管理所有提供商配置
+
+#### 所有支持的厂商
+
+| 厂商 | `model` 前缀 | 默认 API Base | 协议 | API Key |
+| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [获取](https://platform.openai.com) |
+| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取](https://console.anthropic.com) |
+| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取](https://platform.deepseek.com) |
+| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取](https://aistudio.google.com/api-keys) |
+| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取](https://console.groq.com) |
+| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取](https://platform.moonshot.cn) |
+| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取](https://dashscope.console.aliyun.com) |
+| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取](https://build.nvidia.com) |
+| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地（无需 Key） |
+| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取](https://openrouter.ai/keys) |
+| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | 你的 LiteLLM 代理 Key |
+| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 |
+| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取](https://cerebras.ai) |
+| **火山引擎 (豆包)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [获取](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | — |
+| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [获取](https://www.byteplus.com) |
+| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [获取](https://vivgrid.com) |
+| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [获取](https://longcat.chat/platform) |
+| **ModelScope (魔搭)** | `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [获取](https://modelscope.cn/my/tokens) |
+| **Antigravity** | `antigravity/` | Google Cloud | Custom | 仅 OAuth |
+| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | — |
+
+#### 基础配置
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "ark-code-latest",
+ "model": "volcengine/ark-code-latest",
+ "api_key": "sk-your-api-key"
+ },
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_key": "sk-your-openai-key"
+ },
+ {
+ "model_name": "claude-sonnet-4.6",
+ "model": "anthropic/claude-sonnet-4.6",
+ "api_key": "sk-ant-your-key"
+ },
+ {
+ "model_name": "glm-4.7",
+ "model": "zhipu/glm-4.7",
+ "api_key": "your-zhipu-key"
+ }
+ ],
+ "agents": {
+ "defaults": {
+ "model": "gpt-5.4"
+ }
+ }
+}
+```
+
+#### 各厂商配置示例
+
+
+OpenAI
+
+
+火山引擎（豆包）
+
+
+智谱 AI (GLM)
+
+
+DeepSeek
+
+
+Anthropic
+
+
+Ollama（本地）
+
+
+自定义代理 / LiteLLM
+
+#### 负载均衡
+
+为同一模型名称配置多个端点，PicoClaw 会自动轮询：
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_base": "https://api1.example.com/v1",
+ "api_key": "sk-key1"
+ },
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_base": "https://api2.example.com/v1",
+ "api_key": "sk-key2"
+ }
+ ]
+}
+```
+
+#### 从旧版 `providers` 配置迁移
+
+旧版 `providers` 配置**已废弃**，但仍向后兼容。完整迁移指南见 [docs/migration/model-list-migration.md](../migration/model-list-migration.md)。
+
+### Provider 架构
+
+PicoClaw 按协议族路由提供商：
+
+- **OpenAI 兼容**：OpenRouter、Groq、智谱、vLLM 风格端点及大多数其他提供商。
+- **Anthropic**：Claude 原生 API 行为。
+- **Codex/OAuth**：OpenAI OAuth/Token 认证路由。
+
+这使运行时保持轻量，同时让接入新的 OpenAI 兼容后端基本只需配置 `api_base` + `api_key`。
+
+
+智谱（旧版 providers 格式）
+
+
+完整配置示例
+
+### 定时任务 / 提醒
+
+PicoClaw 通过 `cron` 工具支持 cron 风格的定时任务。Agent 可以设置、列出和取消在指定时间触发的提醒或周期性任务。
+
+```json
+{
+ "tools": {
+ "cron": {
+ "enabled": true,
+ "exec_timeout_minutes": 5
+ }
+ }
+}
+```
+
+定时任务在重启后持久保存，存储于 `~/.picoclaw/workspace/cron/`。
+
+### 进阶主题
+
+| 主题 | 说明 |
+| ---- | ---- |
+| [Hook 系统](../hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
+| [Steering](../steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
+| [SubTurn](../subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
+| [上下文管理](../agent-refactor/context.md) | 上下文边界检测、主动预算检查、压缩策略 |
diff --git a/docs/zh/credential_encryption.md b/docs/zh/credential_encryption.md
new file mode 100644
index 000000000..2105e4307
--- /dev/null
+++ b/docs/zh/credential_encryption.md
@@ -0,0 +1,158 @@
+> 返回 [README](../../README.zh.md)
+
+# 凭据加密
+
+PicoClaw 支持对 `model_list` 配置条目中的 `api_key` 值进行加密。
+加密后的密钥以 `enc://` 字符串形式存储，并在启动时自动解密。
+
+---
+
+## 快速开始
+
+**1. 设置密码短语**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. 加密 API 密钥**
+
+运行 `picoclaw onboard` — 它会提示你输入密码短语并生成 SSH 密钥，
+然后在下一次 `SaveConfig` 调用时自动重新加密配置中所有明文 `api_key` 条目。生成的 `enc://` 值如下所示：
+
+```
+enc://AAAA...base64...
+```
+
+**3. 将输出粘贴到你的配置中**
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-4o",
+ "model": "openai/gpt-4o",
+ "api_key": "enc://AAAA...base64...",
+ "api_base": "https://api.openai.com/v1"
+ }
+ ]
+}
+```
+
+---
+
+## 支持的 `api_key` 格式
+
+| 格式 | 示例 | 行为 |
+|------|------|------|
+| 明文 | `sk-abc123` | 直接使用 |
+| 文件引用 | `file://openai.key` | 从配置文件所在目录读取内容 |
+| 加密 | `enc://` | 启动时使用 `PICOCLAW_KEY_PASSPHRASE` 解密 |
+| 空值 | `""` | 原样传递（用于 `auth_method: oauth`） |
+
+---
+
+## 加密设计
+
+### 密钥派生
+
+加密使用 **HKDF-SHA256**，并以 SSH 私钥作为第二因子。
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### 加密
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### 传输格式
+
+```
+enc://
+```
+
+| 字段 | 大小 | 描述 |
+|------|------|------|
+| `salt` | 16 字节 | 每次加密随机生成；输入 HKDF |
+| `nonce` | 12 字节 | 每次加密随机生成；AES-GCM IV |
+| `ciphertext` | 可变 | AES-256-GCM 密文 + 16 字节认证标签 |
+
+GCM 认证标签会自动附加到密文之后。任何篡改都会导致解密失败并报错，而不是返回损坏的明文。
+
+### 性能
+
+| 操作 | 耗时 (ARM Cortex-A) |
+|------|---------------------|
+| 密钥派生 (HKDF) | < 1 ms |
+| AES-256-GCM 解密 | < 1 ms |
+| **启动总开销** | **每个密钥 < 2 ms** |
+
+---
+
+## 使用 SSH 密钥的双因子安全
+
+当提供 SSH 私钥时，破解加密需要**同时具备**：
+
+1. **密码短语** (`PICOCLAW_KEY_PASSPHRASE`)
+2. **SSH 私钥文件**
+
+这意味着仅泄露配置文件不足以恢复 API 密钥，即使密码短语较弱也是如此。SSH 密钥贡献 256 位熵（Ed25519），与密码短语强度无关。
+
+### 威胁模型
+
+| 攻击者拥有 | 能否解密？ |
+|------------|-----------|
+| 仅配置文件 | 否 — 需要密码短语 + SSH 密钥 |
+| 仅 SSH 密钥 | 否 — 需要密码短语 |
+| 仅密码短语 | 否 — 需要 SSH 密钥 |
+| 配置文件 + SSH 密钥 + 密码短语 | 是 — 完全泄露 |
+
+---
+
+## 环境变量
+
+| 变量 | 是否必需 | 描述 |
+|------|----------|------|
+| `PICOCLAW_KEY_PASSPHRASE` | 是（用于 `enc://`） | 用于密钥派生的密码短语 |
+| `PICOCLAW_SSH_KEY_PATH` | 否 | SSH 私钥路径。如未设置，自动从 `~/.ssh/picoclaw_ed25519.key` 检测 |
+
+### SSH 密钥自动检测
+
+如果未设置 `PICOCLAW_SSH_KEY_PATH`，PicoClaw 会查找专用密钥：
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+此专用文件避免与用户现有的 SSH 密钥冲突。
+运行 `picoclaw onboard` 可自动生成该密钥。
+
+`os.UserHomeDir()` 用于跨平台主目录解析（在 Windows 上读取 `USERPROFILE`，在 Unix/macOS 上读取 `HOME`）。
+
+> **注意：** SSH 密钥文件是凭据加密的必要条件。如果未找到密钥且未设置 `PICOCLAW_SSH_KEY_PATH`，加密/解密将失败。运行 `picoclaw onboard` 可自动生成密钥。
+
+---
+
+## 迁移
+
+由于唯一的密钥材料是 `PICOCLAW_KEY_PASSPHRASE` 和 SSH 私钥文件，迁移非常简单：
+
+1. 将配置文件复制到新机器。
+2. 将 `PICOCLAW_KEY_PASSPHRASE` 设置为相同的值。
+3. 将 SSH 私钥文件复制到相同路径（或将 `PICOCLAW_SSH_KEY_PATH` 设置为新位置）。
+
+无需重新加密。
+
+---
+
+## 安全注意事项
+
+- **密码短语和 SSH 密钥都是必需的。** SSH 密钥作为第二因子 — 没有它，加密/解密将失败。如果密钥不存在，运行 `picoclaw onboard` 生成。
+- **SSH 密钥在运行时为只读。** PicoClaw 不会写入或修改 SSH 密钥文件。
+- **仍然支持明文密钥。** 不使用 `enc://` 的现有配置不受影响。
+- **`enc://` 格式通过版本控制**，通过 HKDF `info` 字段（`picoclaw-credential-v1`）实现，允许未来升级算法而不破坏现有加密值。
diff --git a/docs/zh/debug.md b/docs/zh/debug.md
new file mode 100644
index 000000000..e7f20d777
--- /dev/null
+++ b/docs/zh/debug.md
@@ -0,0 +1,36 @@
+# 调试 PicoClaw
+
+> 返回 [README](../../README.zh.md)
+
+PicoClaw 在处理每一个请求时，都会在后台执行多个复杂的交互操作——从消息路由和复杂度评估，到工具执行和模型故障适配。能够准确地看到正在发生什么至关重要，这不仅有助于排查潜在问题，也有助于真正理解代理的运作方式。
+
+## 以调试模式启动 PicoClaw
+
+要获取代理运行的详细信息（LLM 请求、工具调用、消息路由），可以使用调试标志启动 PicoClaw 网关：
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+在此模式下，系统会对日志进行详细格式化，并显示系统提示词和工具执行结果的预览。
+
+## 禁用日志截断（完整日志）
+
+默认情况下，PicoClaw 会在调试日志中截断过长的字符串（例如*系统提示词*或大型 JSON 输出结果），以保持控制台的可读性。
+
+如果你需要检查某个命令的完整输出，或发送给 LLM 模型的确切载荷，可以使用 `--no-truncate` 标志。
+
+**注意：** 此标志*仅*在与 `--debug` 模式组合使用时有效。
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+当此标志激活时，全局截断功能将被禁用。这在以下场景中非常有用：
+
+* 验证发送给提供商的消息的确切语法。
+* 读取 `exec`、`web_fetch` 或 `read_file` 等工具的完整输出。
+* 调试保存在内存中的会话历史。
diff --git a/docs/zh/docker.md b/docs/zh/docker.md
index d2e582d12..10bc46544 100644
--- a/docs/zh/docker.md
+++ b/docs/zh/docker.md
@@ -12,6 +12,7 @@ git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
+# （仅在 config.json 和 workspace/ 都不存在时触发）
docker compose -f docker/docker-compose.yml --profile gateway up
# 容器打印 "First-run setup complete." 后自动停止
diff --git a/docs/zh/hardware-compatibility.md b/docs/zh/hardware-compatibility.md
new file mode 100644
index 000000000..66bd08072
--- /dev/null
+++ b/docs/zh/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> 返回 [README](../../README.zh.md)
+
+# 🖥️ PicoClaw 硬件兼容性列表
+
+PicoClaw 几乎可以在任何 Linux 设备上运行。本页面记录了已验证的芯片、产品和开发板。
+
+**你的硬件不在列表中？** 提交 PR 来添加它！欢迎硬件厂商贡献和联合推广。
+
+---
+
+## 1. 已验证的芯片支持
+
+### x86
+
+| 厂商 | 芯片 | 备注 |
+|------|------|------|
+| Intel | Any x86 CPU (i386+) | 所有桌面/服务器/笔记本处理器 |
+| AMD | Any x86 CPU | 所有桌面/服务器/笔记本处理器 |
+
+### ARM
+
+| 子架构 | 典型芯片 | 备注 |
+|--------|----------|------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | 单核 ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | 单核 Cortex-A7，用于 LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | 四核 Cortex-A53，用于 Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | 四核 Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | 四核 Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | 双核 Cortex-A53 + NPU，用于 NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| 厂商 | 芯片 | 核心 | 备注 |
+|------|------|------|------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 片上内存，用于 LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L 片上内存，1 TOPS NPU，4K AI 摄像头 SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | RISC-V AI 摄像头系列 |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | 用于 HaaS506-LD1 工业 RTU |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | 用于 Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | 符合 RVA23 规范，1024 位 RVV，FP8 AI 推理 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 核，16MB L3 缓存，桌面级 |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU，用于 CanMV-K230 |
+
+### MIPS
+
+| 厂商 | 芯片 | 备注 |
+|------|------|------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz，用于许多 OpenWrt 路由器（如小米路由器 3G） |
+
+### LoongArch (loong64)
+
+| 厂商 | 芯片 | 备注 |
+|------|------|------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | 四核 LA464 @ 2.5GHz，桌面/工作站 |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | 四核 4C/8T @ 2.5GHz，IPC 可与 Intel 第十代相媲美 |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | 双核 @ 1GHz，工业/物联网应用 |
+
+---
+
+## 2. 已验证的产品（按发布日期排列）
+
+已通过 PicoClaw 测试的消费产品、路由器和工业设备。
+
+| 年份 | 产品 | 架构 | SoC | 内存 | 类别 |
+|------|------|------|-----|------|------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | 智能手机 |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | 平板电脑 |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | 路由器 (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | 电视盒子 / 家庭服务器 |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | 智能音箱 |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | 工业 RTU |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | 专业 IP-KVM |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | 4K AI 摄像头 |
+
+---
+
+## 3. 已验证的开发板（按发布日期排列）
+
+| 年份 | 开发板 | 架构 | SoC | 内存 | 购买链接 |
+|------|--------|------|-----|------|----------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. 同样适用于
+
+### Android 手机（通过 Termux）
+
+任何 ARM64 Android 手机（2015 年以后），1GB 以上内存。安装 [Termux](https://github.com/termux/termux-app)，使用 `proot` 运行 PicoClaw。
+
+> 参见 [README：在旧 Android 手机上运行](../../README.zh.md#-run-on-old-android-phones) 获取设置说明。
+
+### 桌面 / 服务器 / 云
+
+| 平台 | 备注 |
+|------|------|
+| x86_64 Linux | 原生二进制文件，无依赖 |
+| x86_64 Windows | 原生二进制文件 |
+| macOS (Intel / Apple Silicon) | 原生二进制文件 |
+| Docker (any platform) | `docker compose` 一行命令，参见 [Docker 指南](docker.md) |
+| OpenWrt routers | MIPS/ARM 构建，需要 >32MB 可用内存 |
+| FreeBSD / NetBSD | 提供 x86_64 和 arm64 构建 |
+
+---
+
+## 5. 最低要求
+
+| 资源 | 最低要求 | 推荐配置 |
+|------|----------|----------|
+| 内存 | 10MB 可用 | 32MB 以上可用 |
+| 存储 | 20MB（二进制文件） | 50MB 以上（含工作区） |
+| CPU | 任意（单核 0.6GHz 以上） | — |
+| 操作系统 | Linux (kernel 3.x+) | Linux 5.x+ |
+| 网络 | 必需（用于 LLM API 调用） | 以太网或 WiFi |
+
+---
+
+## 6. 如何测试与贡献
+
+```bash
+# 1. 下载适合你架构的版本
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. 初始化
+./picoclaw onboard
+
+# 3. 测试
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+可用构建版本：`linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### 添加你的硬件
+
+1. Fork 本仓库
+2. 将你的芯片/产品/开发板添加到相应的表格中
+3. 包含：名称、架构、SoC、内存、年份，以及可用的链接
+4. 提交 PR
+
+硬件厂商：想要添加官方支持或联合推广？请提交 issue 或通过 [Discord](https://discord.gg/V4sAZ9XWpN) 联系我们。
diff --git a/docs/zh/providers.md b/docs/zh/providers.md
index 5b7a4cc2a..e7b323ebf 100644
--- a/docs/zh/providers.md
+++ b/docs/zh/providers.md
@@ -5,7 +5,7 @@
### 提供商 (Providers)
> [!NOTE]
-> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，任意渠道的音频消息都将在 Agent 层面自动转录为文字。
+> 语音转录现在可以通过 `voice.model_name` 指定的多模态模型完成；如果未配置语音模型，Groq Whisper 仍可作为回退方案。
| 提供商 | 用途 | 获取 API Key |
| -------------------- | ---------------------------- | -------------------------------------------------------------------- |
@@ -93,7 +93,34 @@
],
"agents": {
"defaults": {
- "model": "gpt-5.4"
+ "model_name": "gpt-5.4"
+ }
+ }
+}
+```
+
+#### 语音转录
+
+你可以通过 `voice.model_name` 为语音转录指定一个专用模型。这样可以直接复用已经配置好的、支持音频输入的多模态 provider，而不必只依赖 Groq。
+
+如果没有配置 `voice.model_name`，且存在 Groq API Key，PicoClaw 会继续回退到 Groq 转录。
+
+```json
+{
+ "model_list": [
+ {
+ "model_name": "voice-gemini",
+ "model": "gemini/gemini-2.5-flash",
+ "api_key": "your-gemini-key"
+ }
+ ],
+ "voice": {
+ "model_name": "voice-gemini",
+ "echo_transcription": false
+ },
+ "providers": {
+ "groq": {
+ "api_key": "gsk_xxx"
}
}
}
@@ -266,7 +293,7 @@ PicoClaw 在发送请求前仅去除外层 `litellm/` 前缀，因此 `litellm/l
],
"agents": {
"defaults": {
- "model": "glm-4.7"
+ "model_name": "glm-4.7"
}
}
}
@@ -298,7 +325,7 @@ PicoClaw 按协议族路由 Provider：
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
- "model": "glm-4.7",
+ "model_name": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
@@ -328,12 +355,11 @@ picoclaw agent -m "你好"
{
"agents": {
"defaults": {
- "model": "anthropic/claude-opus-4-5"
+ "model_name": "anthropic/claude-opus-4-5"
}
},
"session": {
- "dm_scope": "per-channel-peer",
- "backlog_limit": 20
+ "dm_scope": "per-channel-peer"
},
"providers": {
"openrouter": {
@@ -343,6 +369,10 @@ picoclaw agent -m "你好"
"api_key": "gsk_xxx"
}
},
+ "voice": {
+ "model_name": "voice-gemini",
+ "echo_transcription": false
+ },
"channels": {
"telegram": {
"enabled": true,
diff --git a/docs/zh/spawn-tasks.md b/docs/zh/spawn-tasks.md
index c6721fceb..781462af2 100644
--- a/docs/zh/spawn-tasks.md
+++ b/docs/zh/spawn-tasks.md
@@ -2,13 +2,15 @@
> 返回 [README](../../README.zh.md)
-### 使用 Spawn 的异步任务
+PicoClaw 通过 `spawn` 工具支持**异步任务执行**。主要由 **Heartbeat（心跳）** 系统使用，在不阻塞主 Agent 循环的情况下运行耗时任务。
-对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**：
+## Heartbeat
+
+心跳系统会定期检查 `workspace/HEARTBEAT.md` 中的计划任务。首次运行时会自动生成默认模板，你可以自定义它来定义快速任务（内联处理）和长任务（通过 `spawn` 委派）。
+
+**`HEARTBEAT.md` 示例：**
```markdown
-# Periodic Tasks
-
## Quick Tasks (respond directly)
- Report current time
diff --git a/docs/zh/tools_configuration.md b/docs/zh/tools_configuration.md
index ff88b6707..a3816a35a 100644
--- a/docs/zh/tools_configuration.md
+++ b/docs/zh/tools_configuration.md
@@ -41,16 +41,54 @@ Web 工具用于网页搜索和抓取。
| `fetch_limit_bytes` | int | 10485760 | 抓取网页负载的最大大小，单位为字节（默认 10MB）。 |
| `format` | string | "plaintext" | 抓取内容的输出格式。选项：`plaintext` 或 `markdown`（推荐）。 |
-### Brave
+### 百度搜索
-| 配置项 | 类型 | 默认值 | 描述 |
-|---------------|--------|--------|--------------------|
-| `enabled` | bool | false | 启用 Brave 搜索 |
-| `api_key` | string | - | Brave Search API 密钥 |
-| `max_results` | int | 5 | 最大结果数 |
+使用[千帆 AI 搜索 API](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5)，国内访问稳定，中文搜索效果好。
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|---------------|--------|----------------------------------------------------------------|-----------------------|
+| `enabled` | bool | false | 启用百度搜索 |
+| `api_key` | string | - | 千帆 API 密钥 |
+| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | 百度搜索 API URL |
+| `max_results` | int | 10 | 最大结果数 |
+
+```json
+{
+ "tools": {
+ "web": {
+ "baidu_search": {
+ "enabled": true,
+ "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+ "max_results": 10
+ }
+ }
+ }
+}
+```
+
+### Tavily
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|---------------|--------|--------|-----------------------------------|
+| `enabled` | bool | false | 启用 Tavily 搜索 |
+| `api_key` | string | - | Tavily API 密钥 |
+| `base_url` | string | - | 自定义 Tavily API 基础 URL |
+| `max_results` | int | 0 | 最大结果数（0 = 默认） |
+
+### GLM Search
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|-----------------|--------|------------------------------------------------------|-----------------------|
+| `enabled` | bool | false | 启用 GLM 搜索 |
+| `api_key` | string | - | GLM API 密钥 |
+| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | GLM Search API URL |
+| `search_engine` | string | `search_std` | 搜索引擎类型 |
+| `max_results` | int | 5 | 最大结果数 |
### DuckDuckGo
+> ⚠️ 国内访问困难，建议搭配代理使用。
+
| 配置项 | 类型 | 默认值 | 描述 |
|---------------|------|--------|-----------------------|
| `enabled` | bool | true | 启用 DuckDuckGo 搜索 |
@@ -58,11 +96,40 @@ Web 工具用于网页搜索和抓取。
### Perplexity
-| 配置项 | 类型 | 默认值 | 描述 |
-|---------------|--------|--------|-----------------------|
-| `enabled` | bool | false | 启用 Perplexity 搜索 |
-| `api_key` | string | - | Perplexity API 密钥 |
-| `max_results` | int | 5 | 最大结果数 |
+> ⚠️ 国内访问困难，建议搭配代理使用。
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|---------------|----------|--------|------------------------------------------------|
+| `enabled` | bool | false | 启用 Perplexity 搜索 |
+| `api_key` | string | - | Perplexity API 密钥 |
+| `api_keys` | string[] | - | 多个 API 密钥轮换（优先于 `api_key`） |
+| `max_results` | int | 5 | 最大结果数 |
+
+### Brave
+
+> ⚠️ 国内访问困难，建议搭配代理使用。
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|---------------|----------|--------|------------------------------------------------|
+| `enabled` | bool | false | 启用 Brave 搜索 |
+| `api_key` | string | - | Brave Search API 密钥 |
+| `api_keys` | string[] | - | 多个 API 密钥轮换（优先于 `api_key`） |
+| `max_results` | int | 5 | 最大结果数 |
+
+### SearXNG
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|---------------|--------|--------------------------|-----------------------|
+| `enabled` | bool | false | 启用 SearXNG 搜索 |
+| `base_url` | string | `http://localhost:8888` | SearXNG 实例 URL |
+| `max_results` | int | 5 | 最大结果数 |
+
+### 其他 Web 设置
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|--------------------------|----------|--------|-------------------------------------------------|
+| `prefer_native` | bool | true | 优先使用 provider 原生搜索而非配置的搜索引擎 |
+| `private_host_whitelist` | string[] | `[]` | 允许 Web 抓取的私有/内部主机白名单 |
## Exec 工具
@@ -70,9 +137,32 @@ Exec 工具用于执行 shell 命令。
| 配置项 | 类型 | 默认值 | 描述 |
|------------------------|-------|--------|--------------------------------|
+| `enabled` | bool | true | 启用 exec 工具 |
| `enable_deny_patterns` | bool | true | 启用默认的危险命令拦截 |
| `custom_deny_patterns` | array | [] | 自定义拒绝模式（正则表达式） |
+### 禁用 Exec 工具
+
+要完全禁用 `exec` 工具，请将 `enabled` 设置为 `false`：
+
+**通过配置文件：**
+```json
+{
+ "tools": {
+ "exec": {
+ "enabled": false
+ }
+ }
+}
+```
+
+**通过环境变量：**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **注意：** 禁用后，代理将无法执行 shell 命令。这也会影响 Cron 工具运行计划 shell 命令的能力。
+
### 功能说明
- **`enable_deny_patterns`**：设为 `false` 可完全禁用默认的危险命令拦截模式
@@ -131,6 +221,7 @@ Cron 工具用于调度周期性任务。
| 配置项 | 类型 | 默认值 | 描述 |
|------------------------|------|--------|-------------------------------------|
| `exec_timeout_minutes` | int | 5 | 执行超时时间（分钟），0 表示无限制 |
+| `allow_command` | bool | false | 允许 cron 任务执行 shell 命令 |
## MCP 工具
@@ -297,9 +388,27 @@ Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。
| `registries.clawhub.enabled` | bool | true | 启用 ClawHub 注册表 |
| `registries.clawhub.base_url` | string | `https://clawhub.ai` | ClawHub 基础 URL |
| `registries.clawhub.auth_token` | string | `""` | 可选的 Bearer 令牌，用于更高速率限制 |
-| `registries.clawhub.search_path` | string | `/api/v1/search` | 搜索 API 路径 |
-| `registries.clawhub.skills_path` | string | `/api/v1/skills` | Skills API 路径 |
-| `registries.clawhub.download_path` | string | `/api/v1/download` | 下载 API 路径 |
+| `registries.clawhub.search_path` | string | `""` | 搜索 API 路径 |
+| `registries.clawhub.skills_path` | string | `""` | Skills API 路径 |
+| `registries.clawhub.download_path` | string | `""` | 下载 API 路径 |
+| `registries.clawhub.timeout` | int | 0 | 请求超时时间（秒），0 = 默认 |
+| `registries.clawhub.max_zip_size` | int | 0 | 技能 zip 最大大小（字节），0 = 默认 |
+| `registries.clawhub.max_response_size` | int | 0 | API 响应最大大小（字节），0 = 默认 |
+
+### GitHub 集成
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|------------------|--------|--------|-------------------------------|
+| `github.proxy` | string | `""` | GitHub API 请求的 HTTP 代理 |
+| `github.token` | string | `""` | GitHub 个人访问令牌 |
+
+### 搜索设置
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|----------------------------|------|--------|--------------------------|
+| `max_concurrent_searches` | int | 2 | 最大并发技能搜索请求数 |
+| `search_cache.max_size` | int | 50 | 最大缓存搜索结果数 |
+| `search_cache.ttl_seconds` | int | 300 | 缓存 TTL（秒） |
### 配置示例
@@ -311,11 +420,17 @@ Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。
"clawhub": {
"enabled": true,
"base_url": "https://clawhub.ai",
- "auth_token": "",
- "search_path": "/api/v1/search",
- "skills_path": "/api/v1/skills",
- "download_path": "/api/v1/download"
+ "auth_token": ""
}
+ },
+ "github": {
+ "proxy": "",
+ "token": ""
+ },
+ "max_concurrent_searches": 2,
+ "search_cache": {
+ "max_size": 50,
+ "ttl_seconds": 300
}
}
}
@@ -329,6 +444,7 @@ Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。
例如：
- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
- `PICOCLAW_TOOLS_MCP_ENABLED=true`
diff --git a/docs/zh/troubleshooting.md b/docs/zh/troubleshooting.md
index a3329ee35..be4d4f5d7 100644
--- a/docs/zh/troubleshooting.md
+++ b/docs/zh/troubleshooting.md
@@ -16,7 +16,7 @@
**修复方法：** 在 `~/.picoclaw/config.json`（或你的配置路径）中：
-1. **agents.defaults.model** 必须匹配 `model_list` 中的某个 `model_name`（例如 `"openrouter-free"`）。
+1. **agents.defaults.model_name** 必须匹配 `model_list` 中的某个 `model_name`（例如 `"openrouter-free"`）。
2. 该条目的 **model** 必须是有效的 OpenRouter 模型 ID，例如：
- `"openrouter/free"` – 自动免费层
- `"google/gemini-2.0-flash-exp:free"`
@@ -28,7 +28,7 @@
{
"agents": {
"defaults": {
- "model": "openrouter-free"
+ "model_name": "openrouter-free"
}
},
"model_list": [
diff --git a/examples/pico-echo-server/README.md b/examples/pico-echo-server/README.md
new file mode 100644
index 000000000..f6b5d8020
--- /dev/null
+++ b/examples/pico-echo-server/README.md
@@ -0,0 +1,47 @@
+# pico-echo-server
+
+Minimal Pico Protocol WebSocket server for testing the `pico_client` channel.
+
+## Usage
+
+```bash
+go run ./examples/pico-echo-server -addr :9090 -token secret
+```
+
+### Flags
+
+| Flag | Default | Description |
+|----------|---------|------------------------------------|
+| `-addr` | `:9090` | Listen address |
+| `-token` | (none) | Auth token; empty disables auth |
+
+## How it works
+
+- Listens for WebSocket connections at `/ws`
+- Authenticates via `Authorization: Bearer ` header or `?token=` query param
+- Prints received `message.send` content to stdout
+- Responds to `ping` with `pong`
+- Lines typed into stdin are broadcast as `message.create` to all connected clients
+
+## Testing with pico_client
+
+1. Start the server:
+ ```bash
+ go run ./examples/pico-echo-server -token mytoken
+ ```
+
+2. Configure `pico_client` in your `config.json`:
+ ```json
+ {
+ "channels": {
+ "pico_client": {
+ "enabled": true,
+ "url": "ws://localhost:9090/ws",
+ "token": "mytoken",
+ "session_id": "test-session"
+ }
+ }
+ }
+ ```
+
+3. Start picoclaw — the client connects and you can exchange messages interactively via stdin/stdout.
diff --git a/examples/pico-echo-server/main.go b/examples/pico-echo-server/main.go
new file mode 100644
index 000000000..46970fb34
--- /dev/null
+++ b/examples/pico-echo-server/main.go
@@ -0,0 +1,160 @@
+// pico-echo-server is a minimal Pico Protocol WebSocket server for testing
+// the pico_client channel. It accepts connections, prints received messages
+// to stdout, and forwards stdin lines as message.create to all connected clients.
+//
+// Usage:
+//
+// go run ./examples/pico-echo-server -addr :9090 -token secret
+//
+// Then configure pico_client with url=ws://localhost:9090/ws&token=secret.
+package main
+
+import (
+ "bufio"
+ "encoding/json"
+ "flag"
+ "fmt"
+ "log"
+ "net/http"
+ "os"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/gorilla/websocket"
+)
+
+type picoMessage struct {
+ Type string `json:"type"`
+ ID string `json:"id,omitempty"`
+ SessionID string `json:"session_id,omitempty"`
+ Timestamp int64 `json:"timestamp,omitempty"`
+ Payload map[string]any `json:"payload,omitempty"`
+}
+
+var upgrader = websocket.Upgrader{CheckOrigin: func(*http.Request) bool { return true }}
+
+type server struct {
+ token string
+ mu sync.Mutex
+ conns map[*websocket.Conn]string // conn → sessionID
+}
+
+func (s *server) handleWS(w http.ResponseWriter, r *http.Request) {
+ if s.token != "" {
+ auth := r.Header.Get("Authorization")
+ if auth != "Bearer "+s.token {
+ http.Error(w, "unauthorized", http.StatusUnauthorized)
+ return
+ }
+ }
+
+ conn, err := upgrader.Upgrade(w, r, nil)
+ if err != nil {
+ log.Printf("upgrade: %v", err)
+ return
+ }
+
+ sessionID := r.URL.Query().Get("session_id")
+ if sessionID == "" {
+ sessionID = fmt.Sprintf("sess-%d", time.Now().UnixMilli())
+ }
+
+ s.mu.Lock()
+ s.conns[conn] = sessionID
+ s.mu.Unlock()
+
+ log.Printf("[+] client connected (session=%s)", sessionID)
+
+ defer func() {
+ s.mu.Lock()
+ delete(s.conns, conn)
+ s.mu.Unlock()
+ conn.Close()
+ log.Printf("[-] client disconnected (session=%s)", sessionID)
+ }()
+
+ for {
+ _, raw, err := conn.ReadMessage()
+ if err != nil {
+ if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
+ log.Printf("read error: %v", err)
+ }
+ return
+ }
+
+ var msg picoMessage
+ if err := json.Unmarshal(raw, &msg); err != nil {
+ log.Printf("bad json: %v", err)
+ continue
+ }
+
+ switch msg.Type {
+ case "ping":
+ pong := picoMessage{Type: "pong", ID: msg.ID, Timestamp: time.Now().UnixMilli()}
+ conn.WriteJSON(pong)
+
+ case "message.send":
+ content, _ := msg.Payload["content"].(string)
+ fmt.Printf("[%s] %s\n", sessionID, content)
+
+ case "typing.start":
+ log.Printf("[%s] typing...", sessionID)
+
+ case "typing.stop":
+ log.Printf("[%s] stopped typing", sessionID)
+
+ default:
+ log.Printf("[%s] unknown type: %s", sessionID, msg.Type)
+ }
+ }
+}
+
+func (s *server) broadcast(content string) {
+ msg := picoMessage{
+ Type: "message.create",
+ Timestamp: time.Now().UnixMilli(),
+ Payload: map[string]any{"content": content},
+ }
+
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ for conn, sid := range s.conns {
+ msg.SessionID = sid
+ if err := conn.WriteJSON(msg); err != nil {
+ log.Printf("write to %s failed: %v", sid, err)
+ }
+ }
+}
+
+func main() {
+ addr := flag.String("addr", ":9090", "listen address")
+ token := flag.String("token", "", "auth token (empty = no auth)")
+ flag.Parse()
+
+ s := &server{
+ token: *token,
+ conns: make(map[*websocket.Conn]string),
+ }
+
+ http.HandleFunc("/ws", s.handleWS)
+
+ log.Printf("listening on %s", *addr)
+ log.Printf("connect with: ws://localhost%s/ws", *addr)
+ fmt.Println("Type messages to send to connected clients (Ctrl+C to quit):")
+
+ go func() {
+ scanner := bufio.NewScanner(os.Stdin)
+ for scanner.Scan() {
+ line := strings.TrimSpace(scanner.Text())
+ if line == "" {
+ continue
+ }
+ s.broadcast(line)
+ log.Printf("[server] sent: %s", line)
+ }
+ }()
+
+ log.Fatal(http.ListenAndServe(*addr, nil))
+}
diff --git a/go.mod b/go.mod
index 4442b28fe..e4b6f37fd 100644
--- a/go.mod
+++ b/go.mod
@@ -1,14 +1,15 @@
module github.com/sipeed/picoclaw
-go 1.25.7
+go 1.25.8
require (
fyne.io/systray v1.12.0
+ github.com/BurntSushi/toml v1.6.0
github.com/adhocore/gronx v1.19.6
github.com/anthropics/anthropic-sdk-go v1.26.0
github.com/bwmarrin/discordgo v0.29.0
github.com/caarlos0/env/v11 v11.4.0
- github.com/ergochat/irc-go v0.5.0
+ github.com/ergochat/irc-go v0.6.0
github.com/ergochat/readline v0.1.3
github.com/gdamore/tcell/v2 v2.13.8
github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab
@@ -17,7 +18,7 @@ require (
github.com/h2non/filetype v1.1.3
github.com/larksuite/oapi-sdk-go/v3 v3.5.3
github.com/mdp/qrterminal/v3 v3.2.1
- github.com/modelcontextprotocol/go-sdk v1.3.1
+ github.com/modelcontextprotocol/go-sdk v1.4.1
github.com/mymmrac/telego v1.7.0
github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
github.com/openai/openai-go/v3 v3.22.0
@@ -29,16 +30,16 @@ require (
github.com/tencent-connect/botgo v0.2.1
go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4
golang.org/x/oauth2 v0.36.0
- golang.org/x/term v0.40.0
+ golang.org/x/term v0.41.0
golang.org/x/time v0.14.0
google.golang.org/protobuf v1.36.11
gopkg.in/yaml.v3 v3.0.1
- maunium.net/go/mautrix v0.26.3
+ maunium.net/go/mautrix v0.26.4
modernc.org/sqlite v1.46.1
)
require (
- filippo.io/edwards25519 v1.1.1 // indirect
+ filippo.io/edwards25519 v1.2.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
@@ -51,18 +52,18 @@ require (
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/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6 // indirect
github.com/pmezard/go-difflib v1.0.0 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
github.com/rivo/uniseg v0.4.7 // indirect
github.com/segmentio/asm v1.1.3 // indirect
- github.com/segmentio/encoding v0.5.3 // indirect
+ github.com/segmentio/encoding v0.5.4 // 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/text v0.34.0 // indirect
+ go.mau.fi/util v0.9.7 // indirect
+ golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 // indirect
+ golang.org/x/text v0.35.0 // indirect
modernc.org/libc v1.67.6 // indirect
modernc.org/mathutil v1.7.1 // indirect
modernc.org/memory v1.11.0 // indirect
@@ -92,8 +93,8 @@ require (
github.com/valyala/fastjson v1.6.10 // indirect
github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
golang.org/x/arch v0.24.0 // indirect
- golang.org/x/crypto v0.48.0
- golang.org/x/net v0.51.0 // indirect
- golang.org/x/sync v0.19.0 // indirect
- golang.org/x/sys v0.41.0 // indirect
+ golang.org/x/crypto v0.49.0
+ golang.org/x/net v0.52.0
+ golang.org/x/sync v0.20.0 // indirect
+ golang.org/x/sys v0.42.0
)
diff --git a/go.sum b/go.sum
index f0e3fc132..f24b997d4 100644
--- a/go.sum
+++ b/go.sum
@@ -1,8 +1,10 @@
cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k=
-filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw=
-filippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
+filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
fyne.io/systray v1.12.0 h1:CA1Kk0e2zwFlxtc02L3QFSiIbxJ/P0n582YrZHT7aTM=
fyne.io/systray v1.12.0/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
+github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
+github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
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=
@@ -46,8 +48,8 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
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/ergochat/irc-go v0.5.0 h1:woQ1RS9YbfgqPgSpPBBQeczXGIGzR0aC7dEgk469fTw=
-github.com/ergochat/irc-go v0.5.0/go.mod h1:2vi7KNpIPWnReB5hmLpl92eMywQvuIeIIGdt/FQCph0=
+github.com/ergochat/irc-go v0.6.0 h1:Y0AGV76aeihJfCtLaQh+OyJKFiKGrYC0VTkeMZ6XW28=
+github.com/ergochat/irc-go v0.6.0/go.mod h1:2vi7KNpIPWnReB5hmLpl92eMywQvuIeIIGdt/FQCph0=
github.com/ergochat/readline v0.1.3 h1:/DytGTmwdUJcLAe3k3VJgowh5vNnsdifYT6uVaf4pSo=
github.com/ergochat/readline v0.1.3/go.mod h1:o3ux9QLHLm77bq7hDB21UTm6HlV2++IPDMfIfKDuOgY=
github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
@@ -70,8 +72,8 @@ github.com/godbus/dbus/v5 v5.1.0 h1:4KLkAxT3aOY8Li4FRJe/KvhoNFFxo0m6fNuFUO8QJUk=
github.com/godbus/dbus/v5 v5.1.0/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-jwt/jwt/v5 v5.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
-github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
+github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo=
+github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/golang/protobuf v1.4.0-rc.1/go.mod h1:ceaxUfeHdC40wWswd/P6IGgMaK3YpKi5j83Wpe3EHw8=
github.com/golang/protobuf v1.4.0-rc.1.0.20200221234624-67d41d38c208/go.mod h1:xKAWHe0F5eneWXFV3EuXVDTCmh+JuBKY0li0aMyXATA=
@@ -140,8 +142,8 @@ github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp
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/modelcontextprotocol/go-sdk v1.3.1 h1:TfqtNKOIWN4Z1oqmPAiWDC2Jq7K9OdJaooe0teoXASI=
-github.com/modelcontextprotocol/go-sdk v1.3.1/go.mod h1:DgVX498dMD8UJlseK1S5i1T4tFz2fkBk4xogC3D15nw=
+github.com/modelcontextprotocol/go-sdk v1.4.1 h1:M4x9GyIPj+HoIlHNGpK2hq5o3BFhC+78PkEaldQRphc=
+github.com/modelcontextprotocol/go-sdk v1.4.1/go.mod h1:Bo/mS87hPQqHSRkMv4dQq1XCu6zv4INdXnFZabkNU6s=
github.com/mymmrac/telego v1.7.0 h1:yRO/l00tFGG4nY66ufUKb4ARqv7qx9+LsjQv/b0NEyo=
github.com/mymmrac/telego v1.7.0/go.mod h1:pdLV346EgVuq7Xrh3kMggeBiazeHhsdEoK0RTEOPXRM=
github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
@@ -158,8 +160,8 @@ 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/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6 h1:rh2lKw/P/EqHa724vYH2+VVQ1YnW4u6EOXl0PMAovZE=
+github.com/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6/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=
@@ -179,8 +181,8 @@ github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
-github.com/segmentio/encoding v0.5.3 h1:OjMgICtcSFuNvQCdwqMCv9Tg7lEOXGwm1J5RPQccx6w=
-github.com/segmentio/encoding v0.5.3/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
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=
@@ -235,8 +237,8 @@ github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9dec
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/util v0.9.7 h1:AWGNbJfz1zRcQOKeOEYhKUG2fT+/26Gy6kyqcH8tnBg=
+go.mau.fi/util v0.9.7/go.mod h1:5T2f3ZWZFAGgmFwg3dGw7YK6kIsb9lryDzvynoR98pE=
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=
@@ -250,16 +252,16 @@ golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPh
golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
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/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
+golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 h1:jiDhWWeC7jfWqR9c/uplMOqJ0sbNlNWv0UkzE0vX1MA=
+golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90/go.mod h1:xE1HEv6b+1SCZ5/uscMRjUBKtIxworgEcEi+/n9NQDQ=
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/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
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=
@@ -273,8 +275,8 @@ golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug
golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
golang.org/x/net v0.19.0/go.mod h1:CfAk/cbD4CthTvqiEl8NpboMuiuOYsAr/7NOjZJtv1U=
-golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
-golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
+golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
+golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
golang.org/x/oauth2 v0.23.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
@@ -284,8 +286,8 @@ golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJ
golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -307,15 +309,15 @@ 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=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
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/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
+golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
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=
@@ -323,8 +325,8 @@ 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/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
-golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
+golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
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=
@@ -334,8 +336,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/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
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=
@@ -365,8 +367,8 @@ 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=
-maunium.net/go/mautrix v0.26.3 h1:tWZih6Vjw0qGTWuPmg9JUrQPzViTNDPGQLVc5UXC4nk=
-maunium.net/go/mautrix v0.26.3/go.mod h1:v5ZdDoCwUpNqEj5OrhEoUa3L1kEddKPaAya9TgGXN38=
+maunium.net/go/mautrix v0.26.4 h1:enHSnkf0L2V9+VnfJfNhKSReSW6pBKS/x3Su+v+Vovs=
+maunium.net/go/mautrix v0.26.4/go.mod h1:YWw8NWTszsbyFAznboicBObwHPgTSLcuTbVX2kY7U2M=
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=
diff --git a/pkg/agent/context.go b/pkg/agent/context.go
index 8db8f0b5e..12e3cdd4d 100644
--- a/pkg/agent/context.go
+++ b/pkg/agent/context.go
@@ -12,6 +12,7 @@ import (
"sync"
"time"
+ "github.com/sipeed/picoclaw/pkg"
"github.com/sipeed/picoclaw/pkg/config"
"github.com/sipeed/picoclaw/pkg/logger"
"github.com/sipeed/picoclaw/pkg/providers"
@@ -59,7 +60,7 @@ func getGlobalConfigDir() string {
if err != nil {
return ""
}
- return filepath.Join(home, ".picoclaw")
+ return filepath.Join(home, pkg.DefaultPicoClawHome)
}
func NewContextBuilder(workspace string) *ContextBuilder {
@@ -222,13 +223,10 @@ func (cb *ContextBuilder) InvalidateCache() {
// invalidation (bootstrap files + memory). Skill roots are handled separately
// because they require both directory-level and recursive file-level checks.
func (cb *ContextBuilder) sourcePaths() []string {
- return []string{
- filepath.Join(cb.workspace, "AGENTS.md"),
- filepath.Join(cb.workspace, "SOUL.md"),
- filepath.Join(cb.workspace, "USER.md"),
- filepath.Join(cb.workspace, "IDENTITY.md"),
- filepath.Join(cb.workspace, "memory", "MEMORY.md"),
- }
+ agentDefinition := cb.LoadAgentDefinition()
+ paths := agentDefinition.trackedPaths(cb.workspace)
+ paths = append(paths, filepath.Join(cb.workspace, "memory", "MEMORY.md"))
+ return uniquePaths(paths)
}
// skillRoots returns all skill root directories that can affect
@@ -432,18 +430,32 @@ func skillFilesChangedSince(skillRoots []string, filesAtCache map[string]time.Ti
}
func (cb *ContextBuilder) LoadBootstrapFiles() string {
- bootstrapFiles := []string{
- "AGENTS.md",
- "SOUL.md",
- "USER.md",
- "IDENTITY.md",
+ var sb strings.Builder
+
+ agentDefinition := cb.LoadAgentDefinition()
+ if agentDefinition.Agent != nil {
+ label := string(agentDefinition.Source)
+ if label == "" {
+ label = relativeWorkspacePath(cb.workspace, agentDefinition.Agent.Path)
+ }
+ fmt.Fprintf(&sb, "## %s\n\n%s\n\n", label, agentDefinition.Agent.Body)
+ }
+ if agentDefinition.Soul != nil {
+ fmt.Fprintf(
+ &sb,
+ "## %s\n\n%s\n\n",
+ relativeWorkspacePath(cb.workspace, agentDefinition.Soul.Path),
+ agentDefinition.Soul.Content,
+ )
+ }
+ if agentDefinition.User != nil {
+ fmt.Fprintf(&sb, "## %s\n\n%s\n\n", "USER.md", agentDefinition.User.Content)
}
- var sb strings.Builder
- for _, filename := range bootstrapFiles {
- filePath := filepath.Join(cb.workspace, filename)
+ if agentDefinition.Source != AgentDefinitionSourceAgent {
+ filePath := filepath.Join(cb.workspace, "IDENTITY.md")
if data, err := os.ReadFile(filePath); err == nil {
- fmt.Fprintf(&sb, "## %s\n\n%s\n\n", filename, data)
+ fmt.Fprintf(&sb, "## %s\n\n%s\n\n", "IDENTITY.md", data)
}
}
@@ -497,6 +509,7 @@ func (cb *ContextBuilder) BuildMessages(
currentMessage string,
media []string,
channel, chatID, senderID, senderDisplayName string,
+ activeSkills ...string,
) []providers.Message {
messages := []providers.Message{}
@@ -530,6 +543,11 @@ func (cb *ContextBuilder) BuildMessages(
{Type: "text", Text: dynamicCtx},
}
+ if skillsText := cb.buildActiveSkillsContext(activeSkills); skillsText != "" {
+ stringParts = append(stringParts, skillsText)
+ contentBlocks = append(contentBlocks, providers.ContentBlock{Type: "text", Text: skillsText})
+ }
+
if summary != "" {
summaryText := fmt.Sprintf(
"CONTEXT_SUMMARY: The following is an approximate summary of prior conversation "+
@@ -660,8 +678,21 @@ func sanitizeHistoryForProvider(history []providers.Message) []providers.Message
// like DeepSeek that enforce: "An assistant message with 'tool_calls' must
// be followed by tool messages responding to each 'tool_call_id'."
final := make([]providers.Message, 0, len(sanitized))
+ seenToolCallID := make(map[string]bool)
for i := 0; i < len(sanitized); i++ {
msg := sanitized[i]
+
+ // Deduplicate tool results by ToolCallID
+ if msg.Role == "tool" && msg.ToolCallID != "" {
+ if seenToolCallID[msg.ToolCallID] {
+ logger.DebugCF("agent", "Dropping duplicate tool result", map[string]any{
+ "tool_call_id": msg.ToolCallID,
+ })
+ continue
+ }
+ seenToolCallID[msg.ToolCallID] = true
+ }
+
if msg.Role == "assistant" && len(msg.ToolCalls) > 0 {
// Collect expected tool_call IDs
expected := make(map[string]bool, len(msg.ToolCalls))
@@ -737,6 +768,68 @@ func (cb *ContextBuilder) AddAssistantMessage(
return messages
}
+func (cb *ContextBuilder) buildActiveSkillsContext(skillNames []string) string {
+ if cb.skillsLoader == nil || len(skillNames) == 0 {
+ return ""
+ }
+
+ var ordered []string
+ seen := make(map[string]struct{}, len(skillNames))
+ for _, name := range skillNames {
+ canonical, ok := cb.ResolveSkillName(name)
+ if !ok {
+ continue
+ }
+ if _, exists := seen[canonical]; exists {
+ continue
+ }
+ seen[canonical] = struct{}{}
+ ordered = append(ordered, canonical)
+ }
+ if len(ordered) == 0 {
+ return ""
+ }
+
+ content := cb.skillsLoader.LoadSkillsForContext(ordered)
+ if strings.TrimSpace(content) == "" {
+ return ""
+ }
+
+ return fmt.Sprintf(`# Active Skills
+
+The following skills are active for this request. Follow them when relevant.
+
+%s`, content)
+}
+
+func (cb *ContextBuilder) ListSkillNames() []string {
+ if cb.skillsLoader == nil {
+ return nil
+ }
+
+ allSkills := cb.skillsLoader.ListSkills()
+ names := make([]string, 0, len(allSkills))
+ for _, skill := range allSkills {
+ names = append(names, skill.Name)
+ }
+ return names
+}
+
+func (cb *ContextBuilder) ResolveSkillName(name string) (string, bool) {
+ name = strings.TrimSpace(name)
+ if name == "" || cb.skillsLoader == nil {
+ return "", false
+ }
+
+ for _, skill := range cb.skillsLoader.ListSkills() {
+ if strings.EqualFold(skill.Name, name) {
+ return skill.Name, true
+ }
+ }
+
+ return "", false
+}
+
// GetSkillsInfo returns information about loaded skills.
func (cb *ContextBuilder) GetSkillsInfo() map[string]any {
allSkills := cb.skillsLoader.ListSkills()
diff --git a/pkg/agent/context_budget.go b/pkg/agent/context_budget.go
new file mode 100644
index 000000000..c87695c7a
--- /dev/null
+++ b/pkg/agent/context_budget.go
@@ -0,0 +1,176 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package agent
+
+import (
+ "encoding/json"
+ "unicode/utf8"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// parseTurnBoundaries returns the starting index of each Turn in the history.
+// A Turn is a complete "user input → LLM iterations → final response" cycle
+// (as defined in #1316). Each Turn begins at a user message and extends
+// through all subsequent assistant/tool messages until the next user message.
+//
+// Cutting at a Turn boundary guarantees that no tool-call sequence
+// (assistant+ToolCalls → tool results) is split across the cut.
+func parseTurnBoundaries(history []providers.Message) []int {
+ var starts []int
+ for i, msg := range history {
+ if msg.Role == "user" {
+ starts = append(starts, i)
+ }
+ }
+ return starts
+}
+
+// isSafeBoundary reports whether index is a valid Turn boundary — i.e.,
+// a position where the kept portion (history[index:]) begins at a user
+// message, so no tool-call sequence is torn apart.
+func isSafeBoundary(history []providers.Message, index int) bool {
+ if index <= 0 || index >= len(history) {
+ return true
+ }
+ return history[index].Role == "user"
+}
+
+// findSafeBoundary locates the nearest Turn boundary to targetIndex.
+// It prefers the boundary at or before targetIndex (preserving more recent
+// context). Falls back to the nearest boundary after targetIndex, and
+// returns targetIndex unchanged only when no Turn boundary exists at all.
+func findSafeBoundary(history []providers.Message, targetIndex int) int {
+ if len(history) == 0 {
+ return 0
+ }
+ if targetIndex <= 0 {
+ return 0
+ }
+ if targetIndex >= len(history) {
+ return len(history)
+ }
+
+ turns := parseTurnBoundaries(history)
+ if len(turns) == 0 {
+ return targetIndex
+ }
+
+ // Find the last Turn boundary at or before targetIndex.
+ // Prefer backward: keeps more recent messages.
+ backward := -1
+ for _, t := range turns {
+ if t <= targetIndex {
+ backward = t
+ }
+ }
+ if backward > 0 {
+ return backward
+ }
+
+ // No valid Turn boundary before target (or only at index 0 which
+ // would keep everything). Use the first Turn after targetIndex.
+ for _, t := range turns {
+ if t > targetIndex {
+ return t
+ }
+ }
+
+ // No Turn boundary after targetIndex either. The only boundary is at
+ // index 0, meaning the entire history is a single Turn. Return 0 to
+ // signal that safe compression is not possible — callers check for
+ // mid <= 0 and skip compression in that case.
+ return 0
+}
+
+// estimateMessageTokens estimates the token count for a single message,
+// including Content, ReasoningContent, ToolCalls arguments, ToolCallID
+// metadata, and Media items. Uses a heuristic of 2.5 characters per token.
+func estimateMessageTokens(msg providers.Message) int {
+ chars := utf8.RuneCountInString(msg.Content)
+
+ // ReasoningContent (extended thinking / chain-of-thought) can be
+ // substantial and is stored in session history via AddFullMessage.
+ if msg.ReasoningContent != "" {
+ chars += utf8.RuneCountInString(msg.ReasoningContent)
+ }
+
+ for _, tc := range msg.ToolCalls {
+ chars += len(tc.ID) + len(tc.Type)
+ if tc.Function != nil {
+ // Count function name + arguments (the wire format for most providers).
+ // tc.Name mirrors tc.Function.Name — count only once to avoid double-counting.
+ chars += len(tc.Function.Name) + len(tc.Function.Arguments)
+ } else {
+ // Fallback: some provider formats use top-level Name without Function.
+ chars += len(tc.Name)
+ }
+ }
+
+ if msg.ToolCallID != "" {
+ chars += len(msg.ToolCallID)
+ }
+
+ // Per-message overhead for role label, JSON structure, separators.
+ const messageOverhead = 12
+ chars += messageOverhead
+
+ tokens := chars * 2 / 5
+
+ // Media items (images, files) are serialized by provider adapters into
+ // multipart or image_url payloads. Add a fixed per-item token estimate
+ // directly (not through the chars heuristic) since actual cost depends
+ // on resolution and provider-specific image tokenization.
+ const mediaTokensPerItem = 256
+ tokens += len(msg.Media) * mediaTokensPerItem
+
+ return tokens
+}
+
+// estimateToolDefsTokens estimates the total token cost of tool definitions
+// as they appear in the LLM request. Each tool's name, description, and
+// JSON schema parameters contribute to the context window budget.
+func estimateToolDefsTokens(defs []providers.ToolDefinition) int {
+ if len(defs) == 0 {
+ return 0
+ }
+
+ totalChars := 0
+ for _, d := range defs {
+ totalChars += len(d.Function.Name) + len(d.Function.Description)
+
+ if d.Function.Parameters != nil {
+ if paramJSON, err := json.Marshal(d.Function.Parameters); err == nil {
+ totalChars += len(paramJSON)
+ }
+ }
+
+ // Per-tool overhead: type field, JSON structure, separators.
+ totalChars += 20
+ }
+
+ return totalChars * 2 / 5
+}
+
+// isOverContextBudget checks whether the assembled messages plus tool definitions
+// and output reserve would exceed the model's context window. This enables
+// proactive compression before calling the LLM, rather than reacting to 400 errors.
+func isOverContextBudget(
+ contextWindow int,
+ messages []providers.Message,
+ toolDefs []providers.ToolDefinition,
+ maxTokens int,
+) bool {
+ msgTokens := 0
+ for _, m := range messages {
+ msgTokens += estimateMessageTokens(m)
+ }
+
+ toolTokens := estimateToolDefsTokens(toolDefs)
+ total := msgTokens + toolTokens + maxTokens
+
+ return total > contextWindow
+}
diff --git a/pkg/agent/context_budget_test.go b/pkg/agent/context_budget_test.go
new file mode 100644
index 000000000..870f0fbe6
--- /dev/null
+++ b/pkg/agent/context_budget_test.go
@@ -0,0 +1,826 @@
+package agent
+
+import (
+ "fmt"
+ "strings"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// msgUser creates a user message.
+func msgUser(content string) providers.Message {
+ return providers.Message{Role: "user", Content: content}
+}
+
+// msgAssistant creates a plain assistant message (no tool calls).
+func msgAssistant(content string) providers.Message {
+ return providers.Message{Role: "assistant", Content: content}
+}
+
+// msgAssistantTC creates an assistant message with tool calls.
+func msgAssistantTC(toolIDs ...string) providers.Message {
+ tcs := make([]providers.ToolCall, len(toolIDs))
+ for i, id := range toolIDs {
+ tcs[i] = providers.ToolCall{
+ ID: id,
+ Type: "function",
+ Name: "tool_" + id,
+ Function: &providers.FunctionCall{
+ Name: "tool_" + id,
+ Arguments: `{"key":"value"}`,
+ },
+ }
+ }
+ return providers.Message{Role: "assistant", ToolCalls: tcs}
+}
+
+// msgTool creates a tool result message.
+func msgTool(callID, content string) providers.Message {
+ return providers.Message{Role: "tool", ToolCallID: callID, Content: content}
+}
+
+func TestParseTurnBoundaries(t *testing.T) {
+ tests := []struct {
+ name string
+ history []providers.Message
+ want []int
+ }{
+ {
+ name: "empty history",
+ history: nil,
+ want: nil,
+ },
+ {
+ name: "simple exchange",
+ history: []providers.Message{
+ msgUser("q1"),
+ msgAssistant("a1"),
+ msgUser("q2"),
+ msgAssistant("a2"),
+ },
+ want: []int{0, 2},
+ },
+ {
+ name: "tool-call Turn",
+ history: []providers.Message{
+ msgUser("search"),
+ msgAssistantTC("tc1"),
+ msgTool("tc1", "result"),
+ msgAssistant("found it"),
+ msgUser("thanks"),
+ msgAssistant("welcome"),
+ },
+ want: []int{0, 4},
+ },
+ {
+ name: "chained tool calls in single Turn",
+ history: []providers.Message{
+ msgUser("save and notify"),
+ msgAssistantTC("tc_save"),
+ msgTool("tc_save", "saved"),
+ msgAssistantTC("tc_notify"),
+ msgTool("tc_notify", "notified"),
+ msgAssistant("done"),
+ },
+ want: []int{0},
+ },
+ {
+ name: "no user messages",
+ history: []providers.Message{
+ msgAssistant("a1"),
+ msgAssistant("a2"),
+ },
+ want: nil,
+ },
+ {
+ name: "leading non-user messages",
+ history: []providers.Message{
+ msgAssistantTC("tc1"),
+ msgTool("tc1", "r1"),
+ msgAssistant("greeting"),
+ msgUser("hello"),
+ msgAssistant("hi"),
+ },
+ want: []int{3},
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := parseTurnBoundaries(tt.history)
+ if len(got) != len(tt.want) {
+ t.Errorf("parseTurnBoundaries() = %v, want %v", got, tt.want)
+ return
+ }
+ for i := range got {
+ if got[i] != tt.want[i] {
+ t.Errorf("parseTurnBoundaries()[%d] = %d, want %d", i, got[i], tt.want[i])
+ }
+ }
+ })
+ }
+}
+
+func TestIsSafeBoundary(t *testing.T) {
+ tests := []struct {
+ name string
+ history []providers.Message
+ index int
+ want bool
+ }{
+ {
+ name: "empty history, index 0",
+ history: nil,
+ index: 0,
+ want: true,
+ },
+ {
+ name: "single user message, index 0",
+ history: []providers.Message{msgUser("hi")},
+ index: 0,
+ want: true,
+ },
+ {
+ name: "single user message, index 1 (end)",
+ history: []providers.Message{msgUser("hi")},
+ index: 1,
+ want: true,
+ },
+ {
+ name: "at user message",
+ history: []providers.Message{
+ msgAssistant("hello"),
+ msgUser("how are you"),
+ msgAssistant("fine"),
+ },
+ index: 1,
+ want: true,
+ },
+ {
+ name: "at assistant without tool calls",
+ history: []providers.Message{
+ msgUser("hello"),
+ msgAssistant("response"),
+ msgUser("follow up"),
+ },
+ index: 1,
+ want: false,
+ },
+ {
+ name: "at assistant with tool calls",
+ history: []providers.Message{
+ msgUser("search something"),
+ msgAssistantTC("tc1"),
+ msgTool("tc1", "result"),
+ msgAssistant("here is what I found"),
+ },
+ index: 1,
+ want: false,
+ },
+ {
+ name: "at tool result",
+ history: []providers.Message{
+ msgUser("do something"),
+ msgAssistantTC("tc1"),
+ msgTool("tc1", "done"),
+ msgAssistant("completed"),
+ },
+ index: 2,
+ want: false,
+ },
+ {
+ name: "negative index",
+ history: []providers.Message{
+ msgUser("hello"),
+ },
+ index: -1,
+ want: true,
+ },
+ {
+ name: "index beyond length",
+ history: []providers.Message{
+ msgUser("hello"),
+ },
+ index: 5,
+ want: true,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := isSafeBoundary(tt.history, tt.index)
+ if got != tt.want {
+ t.Errorf("isSafeBoundary(history, %d) = %v, want %v", tt.index, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestFindSafeBoundary(t *testing.T) {
+ tests := []struct {
+ name string
+ history []providers.Message
+ targetIndex int
+ want int
+ }{
+ {
+ name: "empty history",
+ history: nil,
+ targetIndex: 0,
+ want: 0,
+ },
+ {
+ name: "target at 0",
+ history: []providers.Message{msgUser("hi")},
+ targetIndex: 0,
+ want: 0,
+ },
+ {
+ name: "target beyond length",
+ history: []providers.Message{msgUser("hi")},
+ targetIndex: 5,
+ want: 1,
+ },
+ {
+ name: "target already at user message",
+ history: []providers.Message{
+ msgUser("q1"),
+ msgAssistant("a1"),
+ msgUser("q2"),
+ msgAssistant("a2"),
+ },
+ targetIndex: 2,
+ want: 2,
+ },
+ {
+ name: "target at assistant, scan backward finds user",
+ history: []providers.Message{
+ msgUser("q1"),
+ msgAssistant("a1"),
+ msgUser("q2"),
+ msgAssistant("a2"),
+ msgUser("q3"),
+ },
+ targetIndex: 3, // assistant "a2"
+ want: 2, // backward to user "q2"
+ },
+ {
+ name: "target inside tool sequence, scan backward finds user",
+ history: []providers.Message{
+ msgUser("q1"),
+ msgAssistant("a1"),
+ msgUser("q2"),
+ msgAssistantTC("tc1", "tc2"),
+ msgTool("tc1", "r1"),
+ msgTool("tc2", "r2"),
+ msgAssistant("summary"),
+ msgUser("q3"),
+ },
+ targetIndex: 4, // tool result "r1"
+ want: 2, // backward: 3=assistant+TC (not safe), 2=user → safe
+ },
+ {
+ name: "target inside tool sequence, backward finds user before chain",
+ history: []providers.Message{
+ msgUser("q1"),
+ msgAssistant("a1"),
+ msgUser("q2"),
+ msgAssistantTC("tc1", "tc2"),
+ msgTool("tc1", "r1"),
+ msgTool("tc2", "r2"),
+ msgAssistant("summary"),
+ msgUser("q3"),
+ },
+ targetIndex: 5, // tool result "r2"
+ want: 2, // backward: 4=tool, 3=assistant+TC, 2=user → safe
+ },
+ {
+ name: "no backward user, scan forward finds one",
+ history: []providers.Message{
+ msgAssistantTC("tc1"),
+ msgTool("tc1", "r1"),
+ msgAssistant("a1"),
+ msgUser("q1"),
+ },
+ targetIndex: 1, // tool result
+ want: 3, // forward to user "q1"
+ },
+ {
+ name: "multi-step tool chain preserves atomicity",
+ history: []providers.Message{
+ msgUser("q1"),
+ msgAssistant("a1"),
+ msgUser("q2"),
+ msgAssistantTC("tc1"),
+ msgTool("tc1", "r1"),
+ msgAssistantTC("tc2"),
+ msgTool("tc2", "r2"),
+ msgAssistant("final"),
+ msgUser("q3"),
+ msgAssistant("a3"),
+ },
+ targetIndex: 5, // second assistant+TC
+ want: 2, // backward: 4=tool, 3=assistant+TC, 2=user → safe
+ },
+ {
+ name: "all non-user messages returns target unchanged",
+ history: []providers.Message{
+ msgAssistant("a1"),
+ msgAssistant("a2"),
+ msgAssistant("a3"),
+ },
+ targetIndex: 1,
+ want: 1,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := findSafeBoundary(tt.history, tt.targetIndex)
+ if got != tt.want {
+ t.Errorf("findSafeBoundary(history, %d) = %d, want %d",
+ tt.targetIndex, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestFindSafeBoundary_SingleTurnReturnsZero(t *testing.T) {
+ // A single Turn with no subsequent user message. The only Turn boundary
+ // is at index 0; cutting anywhere else would split the Turn's tool
+ // sequence. findSafeBoundary must return 0 so callers skip compression.
+ history := []providers.Message{
+ msgUser("do everything"), // 0 ← only Turn boundary
+ msgAssistantTC("tc1"), // 1
+ msgTool("tc1", "result"), // 2
+ msgAssistant("all done"), // 3
+ }
+
+ got := findSafeBoundary(history, 2)
+ if got != 0 {
+ t.Errorf("findSafeBoundary(single_turn, 2) = %d, want 0 (cannot split single Turn)", got)
+ }
+}
+
+func TestFindSafeBoundary_BackwardScanSkipsToolSequence(t *testing.T) {
+ // A long tool-call chain: user → assistant+TC → tool → tool → ... → assistant → user
+ // Target is inside the chain; boundary should skip the entire chain backward.
+ history := []providers.Message{
+ msgUser("start"), // 0
+ msgAssistant("before chain"), // 1
+ msgUser("trigger"), // 2 ← expected safe boundary
+ msgAssistantTC("t1", "t2", "t3"), // 3
+ msgTool("t1", "r1"), // 4
+ msgTool("t2", "r2"), // 5
+ msgTool("t3", "r3"), // 6
+ msgAssistantTC("t4"), // 7
+ msgTool("t4", "r4"), // 8
+ msgAssistant("chain done"), // 9
+ msgUser("next"), // 10
+ }
+
+ // Target at index 6 (middle of tool results)
+ got := findSafeBoundary(history, 6)
+ if got != 2 {
+ t.Errorf("findSafeBoundary(history, 6) = %d, want 2 (user before chain)", got)
+ }
+}
+
+func TestEstimateMessageTokens(t *testing.T) {
+ tests := []struct {
+ name string
+ msg providers.Message
+ want int // minimum expected tokens (exact value depends on overhead)
+ }{
+ {
+ name: "plain user message",
+ msg: msgUser("Hello, world!"),
+ want: 1, // at least some tokens
+ },
+ {
+ name: "empty message still has overhead",
+ msg: providers.Message{Role: "user"},
+ want: 1, // message overhead alone
+ },
+ {
+ name: "assistant with tool calls",
+ msg: msgAssistantTC("tc_123"),
+ want: 1,
+ },
+ {
+ name: "tool result with ID",
+ msg: msgTool("call_abc", "Here is the search result with lots of content"),
+ want: 1,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := estimateMessageTokens(tt.msg)
+ if got < tt.want {
+ t.Errorf("estimateMessageTokens() = %d, want >= %d", got, tt.want)
+ }
+ })
+ }
+}
+
+func TestEstimateMessageTokens_ToolCallsContribute(t *testing.T) {
+ plain := msgAssistant("thinking")
+ withTC := providers.Message{
+ Role: "assistant",
+ Content: "thinking",
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Name: "web_search",
+ Function: &providers.FunctionCall{
+ Name: "web_search",
+ Arguments: `{"query":"picoclaw agent framework","max_results":5}`,
+ },
+ },
+ },
+ }
+
+ plainTokens := estimateMessageTokens(plain)
+ withTCTokens := estimateMessageTokens(withTC)
+
+ if withTCTokens <= plainTokens {
+ t.Errorf("message with ToolCalls (%d tokens) should exceed plain message (%d tokens)",
+ withTCTokens, plainTokens)
+ }
+}
+
+func TestEstimateMessageTokens_MultibyteContent(t *testing.T) {
+ // Multi-byte characters (e.g. emoji, accented letters) are single runes
+ // but may map to different token counts. The heuristic should still produce
+ // reasonable estimates via RuneCountInString.
+ msg := msgUser("caf\u00e9 na\u00efve r\u00e9sum\u00e9 \u00fcber stra\u00dfe")
+ tokens := estimateMessageTokens(msg)
+ if tokens <= 0 {
+ t.Errorf("multibyte message should produce positive token count, got %d", tokens)
+ }
+}
+
+func TestEstimateMessageTokens_LargeArguments(t *testing.T) {
+ // Simulate a tool call with large JSON arguments.
+ largeArgs := fmt.Sprintf(`{"content":"%s"}`, strings.Repeat("x", 5000))
+ msg := providers.Message{
+ Role: "assistant",
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "call_large",
+ Type: "function",
+ Name: "write_file",
+ Function: &providers.FunctionCall{
+ Name: "write_file",
+ Arguments: largeArgs,
+ },
+ },
+ },
+ }
+
+ tokens := estimateMessageTokens(msg)
+ // 5000+ chars → at least 2000 tokens with the 2.5 char/token heuristic
+ if tokens < 2000 {
+ t.Errorf("large tool call arguments should produce significant token count, got %d", tokens)
+ }
+}
+
+func TestEstimateMessageTokens_ReasoningContent(t *testing.T) {
+ plain := msgAssistant("result")
+ withReasoning := providers.Message{
+ Role: "assistant",
+ Content: "result",
+ ReasoningContent: strings.Repeat("thinking step ", 200),
+ }
+
+ plainTokens := estimateMessageTokens(plain)
+ reasoningTokens := estimateMessageTokens(withReasoning)
+
+ if reasoningTokens <= plainTokens {
+ t.Errorf("message with ReasoningContent (%d tokens) should exceed plain message (%d tokens)",
+ reasoningTokens, plainTokens)
+ }
+}
+
+func TestEstimateMessageTokens_MediaItems(t *testing.T) {
+ plain := msgUser("describe this")
+ withMedia := providers.Message{
+ Role: "user",
+ Content: "describe this",
+ Media: []string{"media://img1.png", "media://img2.png"},
+ }
+
+ plainTokens := estimateMessageTokens(plain)
+ mediaTokens := estimateMessageTokens(withMedia)
+
+ if mediaTokens <= plainTokens {
+ t.Errorf("message with Media (%d tokens) should exceed plain message (%d tokens)",
+ mediaTokens, plainTokens)
+ }
+
+ // Each media item should add exactly 256 tokens (not run through chars*2/5).
+ expectedDelta := 256 * 2
+ actualDelta := mediaTokens - plainTokens
+ if actualDelta != expectedDelta {
+ t.Errorf("2 media items should add %d tokens, got delta %d", expectedDelta, actualDelta)
+ }
+}
+
+// --- estimateToolDefsTokens tests ---
+
+func TestEstimateToolDefsTokens(t *testing.T) {
+ tests := []struct {
+ name string
+ defs []providers.ToolDefinition
+ want int // minimum expected tokens
+ }{
+ {
+ name: "empty tool list",
+ defs: nil,
+ want: 0,
+ },
+ {
+ name: "single tool with params",
+ defs: []providers.ToolDefinition{
+ {
+ Type: "function",
+ Function: providers.ToolFunctionDefinition{
+ Name: "web_search",
+ Description: "Search the web for information",
+ Parameters: map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "query": map[string]any{"type": "string"},
+ },
+ "required": []any{"query"},
+ },
+ },
+ },
+ },
+ want: 1,
+ },
+ {
+ name: "tool without params",
+ defs: []providers.ToolDefinition{
+ {
+ Type: "function",
+ Function: providers.ToolFunctionDefinition{
+ Name: "list_dir",
+ Description: "List directory contents",
+ },
+ },
+ },
+ want: 1,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := estimateToolDefsTokens(tt.defs)
+ if got < tt.want {
+ t.Errorf("estimateToolDefsTokens() = %d, want >= %d", got, tt.want)
+ }
+ })
+ }
+}
+
+func TestEstimateToolDefsTokens_ScalesWithCount(t *testing.T) {
+ makeTool := func(name string) providers.ToolDefinition {
+ return providers.ToolDefinition{
+ Type: "function",
+ Function: providers.ToolFunctionDefinition{
+ Name: name,
+ Description: "A test tool that does something useful",
+ Parameters: map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "input": map[string]any{"type": "string", "description": "Input value"},
+ },
+ },
+ },
+ }
+ }
+
+ one := estimateToolDefsTokens([]providers.ToolDefinition{makeTool("tool_a")})
+ three := estimateToolDefsTokens([]providers.ToolDefinition{
+ makeTool("tool_a"), makeTool("tool_b"), makeTool("tool_c"),
+ })
+
+ if three <= one {
+ t.Errorf("3 tools (%d tokens) should exceed 1 tool (%d tokens)", three, one)
+ }
+}
+
+// --- isOverContextBudget tests ---
+
+func TestIsOverContextBudget(t *testing.T) {
+ systemMsg := providers.Message{Role: "system", Content: strings.Repeat("x", 1000)}
+ userMsg := msgUser("hello")
+ smallHistory := []providers.Message{systemMsg, msgUser("q1"), msgAssistant("a1"), userMsg}
+
+ tools := []providers.ToolDefinition{
+ {
+ Type: "function",
+ Function: providers.ToolFunctionDefinition{
+ Name: "test_tool",
+ Description: "A test tool",
+ Parameters: map[string]any{"type": "object"},
+ },
+ },
+ }
+
+ tests := []struct {
+ name string
+ contextWindow int
+ messages []providers.Message
+ toolDefs []providers.ToolDefinition
+ maxTokens int
+ want bool
+ }{
+ {
+ name: "within budget",
+ contextWindow: 100000,
+ messages: smallHistory,
+ toolDefs: tools,
+ maxTokens: 4096,
+ want: false,
+ },
+ {
+ name: "over budget with small window",
+ contextWindow: 100, // very small window
+ messages: smallHistory,
+ toolDefs: tools,
+ maxTokens: 4096,
+ want: true,
+ },
+ {
+ name: "large max_tokens eats budget",
+ contextWindow: 2000,
+ messages: smallHistory,
+ toolDefs: tools,
+ maxTokens: 1800, // leaves almost no room
+ want: true,
+ },
+ {
+ name: "empty messages within budget",
+ contextWindow: 10000,
+ messages: nil,
+ toolDefs: nil,
+ maxTokens: 4096,
+ want: false,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := isOverContextBudget(tt.contextWindow, tt.messages, tt.toolDefs, tt.maxTokens)
+ if got != tt.want {
+ t.Errorf("isOverContextBudget() = %v, want %v", got, tt.want)
+ }
+ })
+ }
+}
+
+// --- Tests reflecting actual session data shape ---
+// Session history never contains system messages. The system prompt is
+// built dynamically by BuildMessages. These tests use realistic history
+// shapes: user/assistant/tool only, with tool chains and reasoning content.
+
+func TestFindSafeBoundary_SessionHistoryNoSystem(t *testing.T) {
+ // Real session history starts with a user message, not a system message.
+ history := []providers.Message{
+ msgUser("hello"), // 0
+ msgAssistant("hi there"), // 1
+ msgUser("search for X"), // 2
+ msgAssistantTC("tc1"), // 3
+ msgTool("tc1", "found X"), // 4
+ msgAssistant("here is X"), // 5
+ msgUser("thanks"), // 6
+ msgAssistant("you're welcome"), // 7
+ }
+
+ // Mid-point is 4 (tool result). Should snap backward to 2 (user).
+ got := findSafeBoundary(history, 4)
+ if got != 2 {
+ t.Errorf("findSafeBoundary(session_history, 4) = %d, want 2", got)
+ }
+}
+
+func TestFindSafeBoundary_SessionWithChainedTools(t *testing.T) {
+ // Session with chained tool calls (save then notify).
+ history := []providers.Message{
+ msgUser("save and notify"), // 0
+ msgAssistantTC("tc_save"), // 1
+ msgTool("tc_save", "saved"), // 2
+ msgAssistantTC("tc_notify"), // 3
+ msgTool("tc_notify", "notified"), // 4
+ msgAssistant("done"), // 5
+ msgUser("check status"), // 6
+ msgAssistant("all good"), // 7
+ }
+
+ // Target at 3 (inside chain). Should find user at 0, but backward
+ // scan stops at i>0, so forward scan finds user at 6.
+ // Actually: backward from 3: 2=tool (no), 1=assistantTC (no). Forward: 4=tool, 5=asst, 6=user ✓
+ got := findSafeBoundary(history, 3)
+ if got != 6 {
+ t.Errorf("findSafeBoundary(chained_tools, 3) = %d, want 6", got)
+ }
+}
+
+func TestEstimateMessageTokens_WithReasoningAndMedia(t *testing.T) {
+ // Message with all fields populated — mirrors what AddFullMessage stores.
+ msg := providers.Message{
+ Role: "assistant",
+ Content: "Here is the analysis.",
+ ReasoningContent: strings.Repeat("Let me think about this carefully. ", 50),
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Name: "analyze",
+ Function: &providers.FunctionCall{
+ Name: "analyze",
+ Arguments: `{"data":"sample","depth":3}`,
+ },
+ },
+ },
+ }
+
+ tokens := estimateMessageTokens(msg)
+
+ // ReasoningContent alone is ~1700 chars → ~680 tokens.
+ // Content + TC + overhead adds more. Should be well above 500.
+ if tokens < 500 {
+ t.Errorf("message with reasoning+toolcalls should have significant tokens, got %d", tokens)
+ }
+
+ // Compare without reasoning to ensure it's counted.
+ msgNoReasoning := msg
+ msgNoReasoning.ReasoningContent = ""
+ tokensNoReasoning := estimateMessageTokens(msgNoReasoning)
+
+ if tokens <= tokensNoReasoning {
+ t.Errorf("reasoning content should add tokens: with=%d, without=%d", tokens, tokensNoReasoning)
+ }
+}
+
+func TestIsOverContextBudget_RealisticSession(t *testing.T) {
+ // Simulate what BuildMessages produces: system + session history + current user.
+ // System message is built by BuildMessages, not stored in session.
+ systemMsg := providers.Message{
+ Role: "system",
+ Content: strings.Repeat("system prompt content ", 100),
+ }
+ sessionHistory := []providers.Message{
+ msgUser("first question"),
+ msgAssistant("first answer"),
+ msgUser("use tool X"),
+ {
+ Role: "assistant",
+ Content: "I'll use tool X",
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "tc1", Type: "function", Name: "tool_x",
+ Function: &providers.FunctionCall{
+ Name: "tool_x",
+ Arguments: `{"query":"test","verbose":true}`,
+ },
+ },
+ },
+ },
+ {Role: "tool", Content: strings.Repeat("result data ", 200), ToolCallID: "tc1"},
+ msgAssistant("Here are the results from tool X."),
+ }
+ currentUser := msgUser("follow up question")
+
+ // Assemble as BuildMessages would.
+ messages := make([]providers.Message, 0, 1+len(sessionHistory)+1)
+ messages = append(messages, systemMsg)
+ messages = append(messages, sessionHistory...)
+ messages = append(messages, currentUser)
+
+ tools := []providers.ToolDefinition{
+ {
+ Type: "function",
+ Function: providers.ToolFunctionDefinition{
+ Name: "tool_x",
+ Description: "A useful tool",
+ Parameters: map[string]any{"type": "object"},
+ },
+ },
+ }
+
+ // With a large context window, should be within budget.
+ if isOverContextBudget(131072, messages, tools, 32768) {
+ t.Error("realistic session should be within 131072 context window")
+ }
+
+ // With a tiny context window, should exceed budget.
+ if !isOverContextBudget(500, messages, tools, 32768) {
+ t.Error("realistic session should exceed 500 context window")
+ }
+}
diff --git a/pkg/agent/context_cache_test.go b/pkg/agent/context_cache_test.go
index c26976c3c..81a1534b9 100644
--- a/pkg/agent/context_cache_test.go
+++ b/pkg/agent/context_cache_test.go
@@ -37,7 +37,7 @@ func setupWorkspace(t *testing.T, files map[string]string) string {
// Codex (only reads last system message as instructions).
func TestSingleSystemMessage(t *testing.T) {
tmpDir := setupWorkspace(t, map[string]string{
- "IDENTITY.md": "# Identity\nTest agent.",
+ "AGENT.md": "# Agent\nTest agent.",
})
defer os.RemoveAll(tmpDir)
@@ -202,10 +202,10 @@ func TestMtimeAutoInvalidation(t *testing.T) {
}{
{
name: "bootstrap file change",
- file: "IDENTITY.md",
- contentV1: "# Original Identity",
- contentV2: "# Updated Identity",
- checkField: "Updated Identity",
+ file: "AGENT.md",
+ contentV1: "# Original Agent",
+ contentV2: "# Updated Agent",
+ checkField: "Updated Agent",
},
{
name: "memory file change",
@@ -280,7 +280,7 @@ func TestMtimeAutoInvalidation(t *testing.T) {
// 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",
+ "AGENT.md": "# Test Agent",
})
defer os.RemoveAll(tmpDir)
@@ -307,8 +307,8 @@ func TestExplicitInvalidateCache(t *testing.T) {
// 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",
+ "AGENT.md": "# Agent\nContent",
+ "SOUL.md": "# Soul\nContent",
})
defer os.RemoveAll(tmpDir)
@@ -607,7 +607,7 @@ description: delete-me-v1
// 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.",
+ "AGENT.md": "# Agent\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",
@@ -714,7 +714,7 @@ func BenchmarkBuildMessagesWithCache(b *testing.B) {
os.MkdirAll(filepath.Join(tmpDir, "memory"), 0o755)
os.MkdirAll(filepath.Join(tmpDir, "skills"), 0o755)
- for _, name := range []string{"IDENTITY.md", "SOUL.md", "USER.md"} {
+ for _, name := range []string{"AGENT.md", "SOUL.md"} {
os.WriteFile(filepath.Join(tmpDir, name), []byte(strings.Repeat("Content.\n", 10)), 0o644)
}
diff --git a/pkg/agent/context_test.go b/pkg/agent/context_test.go
index 5756ed911..0d7948eef 100644
--- a/pkg/agent/context_test.go
+++ b/pkg/agent/context_test.go
@@ -188,6 +188,31 @@ func TestSanitizeHistoryForProvider_PlainConversation(t *testing.T) {
assertRoles(t, result, "user", "assistant", "user", "assistant")
}
+func TestSanitizeHistoryForProvider_DuplicateToolResults(t *testing.T) {
+ history := []providers.Message{
+ msg("user", "do something"),
+ assistantWithTools("A", "B"),
+ toolResult("A"),
+ toolResult("B"),
+ toolResult("A"), // duplicate
+ toolResult("B"), // duplicate
+ msg("assistant", "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")
+ // Verify the kept tool results have the correct IDs
+ if result[2].ToolCallID != "A" {
+ t.Errorf("expected tool result A, got %q", result[2].ToolCallID)
+ }
+ if result[3].ToolCallID != "B" {
+ t.Errorf("expected tool result B, got %q", result[3].ToolCallID)
+ }
+}
+
func roles(msgs []providers.Message) []string {
r := make([]string, len(msgs))
for i, m := range msgs {
diff --git a/pkg/agent/definition.go b/pkg/agent/definition.go
new file mode 100644
index 000000000..cf73d607c
--- /dev/null
+++ b/pkg/agent/definition.go
@@ -0,0 +1,255 @@
+package agent
+
+import (
+ "os"
+ "path/filepath"
+ "slices"
+ "strings"
+
+ "github.com/gomarkdown/markdown/parser"
+ "gopkg.in/yaml.v3"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// AgentDefinitionSource identifies which agent bootstrap file produced the definition.
+type AgentDefinitionSource string
+
+const (
+ // AgentDefinitionSourceAgent indicates the new AGENT.md format.
+ AgentDefinitionSourceAgent AgentDefinitionSource = "AGENT.md"
+ // AgentDefinitionSourceAgents indicates the legacy AGENTS.md format.
+ AgentDefinitionSourceAgents AgentDefinitionSource = "AGENTS.md"
+)
+
+// AgentFrontmatter holds machine-readable AGENT.md configuration.
+//
+// Known fields are exposed directly for convenience. Fields keeps the full
+// parsed frontmatter so future refactors can read additional keys without
+// changing the loader contract again.
+type AgentFrontmatter struct {
+ Name string `json:"name"`
+ Description string `json:"description"`
+ Tools []string `json:"tools,omitempty"`
+ Model string `json:"model,omitempty"`
+ MaxTurns *int `json:"maxTurns,omitempty"`
+ Skills []string `json:"skills,omitempty"`
+ MCPServers []string `json:"mcpServers,omitempty"`
+ Fields map[string]any `json:"fields,omitempty"`
+}
+
+// AgentPromptDefinition represents the parsed AGENT.md or AGENTS.md prompt file.
+type AgentPromptDefinition struct {
+ Path string `json:"path"`
+ Raw string `json:"raw"`
+ Body string `json:"body"`
+ RawFrontmatter string `json:"raw_frontmatter,omitempty"`
+ Frontmatter AgentFrontmatter `json:"frontmatter"`
+}
+
+// SoulDefinition represents the resolved SOUL.md file linked to the agent.
+type SoulDefinition struct {
+ Path string `json:"path"`
+ Content string `json:"content"`
+}
+
+// UserDefinition represents the resolved USER.md file linked to the workspace.
+type UserDefinition struct {
+ Path string `json:"path"`
+ Content string `json:"content"`
+}
+
+// AgentContextDefinition captures the workspace agent definition in a runtime-friendly shape.
+type AgentContextDefinition struct {
+ Source AgentDefinitionSource `json:"source,omitempty"`
+ Agent *AgentPromptDefinition `json:"agent,omitempty"`
+ Soul *SoulDefinition `json:"soul,omitempty"`
+ User *UserDefinition `json:"user,omitempty"`
+}
+
+// LoadAgentDefinition parses the workspace agent bootstrap files.
+//
+// It prefers the new AGENT.md format and its paired SOUL.md file. When the
+// structured files are absent, it falls back to the legacy AGENTS.md layout so
+// the current runtime can transition incrementally.
+func (cb *ContextBuilder) LoadAgentDefinition() AgentContextDefinition {
+ return loadAgentDefinition(cb.workspace)
+}
+
+func loadAgentDefinition(workspace string) AgentContextDefinition {
+ definition := AgentContextDefinition{}
+ definition.User = loadUserDefinition(workspace)
+ agentPath := filepath.Join(workspace, string(AgentDefinitionSourceAgent))
+ if content, err := os.ReadFile(agentPath); err == nil {
+ prompt := parseAgentPromptDefinition(agentPath, string(content))
+ definition.Source = AgentDefinitionSourceAgent
+ definition.Agent = &prompt
+ soulPath := filepath.Join(workspace, "SOUL.md")
+ if content, err := os.ReadFile(soulPath); err == nil {
+ definition.Soul = &SoulDefinition{
+ Path: soulPath,
+ Content: string(content),
+ }
+ }
+ return definition
+ }
+
+ legacyPath := filepath.Join(workspace, string(AgentDefinitionSourceAgents))
+ if content, err := os.ReadFile(legacyPath); err == nil {
+ definition.Source = AgentDefinitionSourceAgents
+ definition.Agent = &AgentPromptDefinition{
+ Path: legacyPath,
+ Raw: string(content),
+ Body: string(content),
+ }
+ }
+
+ defaultSoulPath := filepath.Join(workspace, "SOUL.md")
+ if definition.Source != "" || fileExists(defaultSoulPath) {
+ if content, err := os.ReadFile(defaultSoulPath); err == nil {
+ definition.Soul = &SoulDefinition{
+ Path: defaultSoulPath,
+ Content: string(content),
+ }
+ }
+ }
+
+ return definition
+}
+
+func (definition AgentContextDefinition) trackedPaths(workspace string) []string {
+ paths := []string{
+ filepath.Join(workspace, string(AgentDefinitionSourceAgent)),
+ filepath.Join(workspace, "SOUL.md"),
+ filepath.Join(workspace, "USER.md"),
+ }
+ if definition.Source != AgentDefinitionSourceAgent {
+ paths = append(paths,
+ filepath.Join(workspace, string(AgentDefinitionSourceAgents)),
+ filepath.Join(workspace, "IDENTITY.md"),
+ )
+ }
+ return uniquePaths(paths)
+}
+
+func loadUserDefinition(workspace string) *UserDefinition {
+ userPath := filepath.Join(workspace, "USER.md")
+ if content, err := os.ReadFile(userPath); err == nil {
+ return &UserDefinition{
+ Path: userPath,
+ Content: string(content),
+ }
+ }
+
+ return nil
+}
+
+func parseAgentPromptDefinition(path, content string) AgentPromptDefinition {
+ frontmatter, body := splitAgentFrontmatter(content)
+ return AgentPromptDefinition{
+ Path: path,
+ Raw: content,
+ Body: body,
+ RawFrontmatter: frontmatter,
+ Frontmatter: parseAgentFrontmatter(path, frontmatter),
+ }
+}
+
+func parseAgentFrontmatter(path, frontmatter string) AgentFrontmatter {
+ frontmatter = strings.TrimSpace(frontmatter)
+ if frontmatter == "" {
+ return AgentFrontmatter{}
+ }
+
+ rawFields := make(map[string]any)
+ if err := yaml.Unmarshal([]byte(frontmatter), &rawFields); err != nil {
+ logger.WarnCF("agent", "Failed to parse AGENT.md frontmatter", map[string]any{
+ "path": path,
+ "error": err.Error(),
+ })
+ return AgentFrontmatter{}
+ }
+
+ var typed struct {
+ Name string `yaml:"name"`
+ Description string `yaml:"description"`
+ Tools []string `yaml:"tools"`
+ Model string `yaml:"model"`
+ MaxTurns *int `yaml:"maxTurns"`
+ Skills []string `yaml:"skills"`
+ MCPServers []string `yaml:"mcpServers"`
+ }
+ if err := yaml.Unmarshal([]byte(frontmatter), &typed); err != nil {
+ logger.WarnCF("agent", "Failed to decode AGENT.md frontmatter fields", map[string]any{
+ "path": path,
+ "error": err.Error(),
+ })
+ return AgentFrontmatter{}
+ }
+
+ return AgentFrontmatter{
+ Name: strings.TrimSpace(typed.Name),
+ Description: strings.TrimSpace(typed.Description),
+ Tools: append([]string(nil), typed.Tools...),
+ Model: strings.TrimSpace(typed.Model),
+ MaxTurns: typed.MaxTurns,
+ Skills: append([]string(nil), typed.Skills...),
+ MCPServers: append([]string(nil), typed.MCPServers...),
+ Fields: rawFields,
+ }
+}
+
+func splitAgentFrontmatter(content string) (frontmatter, body string) {
+ normalized := string(parser.NormalizeNewlines([]byte(content)))
+ lines := strings.Split(normalized, "\n")
+ if len(lines) == 0 || lines[0] != "---" {
+ return "", content
+ }
+
+ end := -1
+ for i := 1; i < len(lines); i++ {
+ if lines[i] == "---" {
+ end = i
+ break
+ }
+ }
+ if end == -1 {
+ return "", content
+ }
+
+ frontmatter = strings.Join(lines[1:end], "\n")
+ body = strings.Join(lines[end+1:], "\n")
+ body = strings.TrimLeft(body, "\n")
+ return frontmatter, body
+}
+
+func relativeWorkspacePath(workspace, path string) string {
+ if strings.TrimSpace(path) == "" {
+ return ""
+ }
+ relativePath, err := filepath.Rel(workspace, path)
+ if err == nil && relativePath != "." && !strings.HasPrefix(relativePath, "..") {
+ return filepath.ToSlash(relativePath)
+ }
+ return filepath.Clean(path)
+}
+
+func uniquePaths(paths []string) []string {
+ result := make([]string, 0, len(paths))
+ for _, path := range paths {
+ if strings.TrimSpace(path) == "" {
+ continue
+ }
+ cleaned := filepath.Clean(path)
+ if slices.Contains(result, cleaned) {
+ continue
+ }
+ result = append(result, cleaned)
+ }
+ return result
+}
+
+func fileExists(path string) bool {
+ _, err := os.Stat(path)
+ return err == nil
+}
diff --git a/pkg/agent/definition_test.go b/pkg/agent/definition_test.go
new file mode 100644
index 000000000..5ee996967
--- /dev/null
+++ b/pkg/agent/definition_test.go
@@ -0,0 +1,302 @@
+package agent
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestLoadAgentDefinitionParsesFrontmatterAndSoul(t *testing.T) {
+ tmpDir := setupWorkspace(t, map[string]string{
+ "AGENT.md": `---
+name: pico
+description: Structured agent
+model: claude-3-7-sonnet
+tools:
+ - shell
+ - search
+maxTurns: 8
+skills:
+ - review
+ - search-docs
+mcpServers:
+ - github
+metadata:
+ mode: strict
+---
+# Agent
+
+Act directly and use tools first.
+`,
+ "SOUL.md": "# Soul\nStay precise.",
+ })
+ defer cleanupWorkspace(t, tmpDir)
+
+ cb := NewContextBuilder(tmpDir)
+ definition := cb.LoadAgentDefinition()
+
+ if definition.Source != AgentDefinitionSourceAgent {
+ t.Fatalf("expected source %q, got %q", AgentDefinitionSourceAgent, definition.Source)
+ }
+ if definition.Agent == nil {
+ t.Fatal("expected AGENT.md definition to be loaded")
+ }
+ if definition.Agent.Body == "" || !strings.Contains(definition.Agent.Body, "Act directly") {
+ t.Fatalf("expected AGENT.md body to be preserved, got %q", definition.Agent.Body)
+ }
+ if definition.Agent.Frontmatter.Name != "pico" {
+ t.Fatalf("expected name to be parsed, got %q", definition.Agent.Frontmatter.Name)
+ }
+ if definition.Agent.Frontmatter.Model != "claude-3-7-sonnet" {
+ t.Fatalf("expected model to be parsed, got %q", definition.Agent.Frontmatter.Model)
+ }
+ if len(definition.Agent.Frontmatter.Tools) != 2 {
+ t.Fatalf("expected tools to be parsed, got %v", definition.Agent.Frontmatter.Tools)
+ }
+ if definition.Agent.Frontmatter.MaxTurns == nil || *definition.Agent.Frontmatter.MaxTurns != 8 {
+ t.Fatalf("expected maxTurns to be parsed, got %v", definition.Agent.Frontmatter.MaxTurns)
+ }
+ if len(definition.Agent.Frontmatter.Skills) != 2 {
+ t.Fatalf("expected skills to be parsed, got %v", definition.Agent.Frontmatter.Skills)
+ }
+ if len(definition.Agent.Frontmatter.MCPServers) != 1 || definition.Agent.Frontmatter.MCPServers[0] != "github" {
+ t.Fatalf("expected mcpServers to be parsed, got %v", definition.Agent.Frontmatter.MCPServers)
+ }
+ if definition.Agent.Frontmatter.Fields["metadata"] == nil {
+ t.Fatal("expected arbitrary frontmatter fields to remain available")
+ }
+
+ if definition.Soul == nil {
+ t.Fatal("expected SOUL.md to be loaded")
+ }
+ if !strings.Contains(definition.Soul.Content, "Stay precise") {
+ t.Fatalf("expected soul content to be loaded, got %q", definition.Soul.Content)
+ }
+ if definition.Soul.Path != filepath.Join(tmpDir, "SOUL.md") {
+ t.Fatalf("expected default SOUL.md path, got %q", definition.Soul.Path)
+ }
+}
+
+func TestLoadAgentDefinitionFallsBackToLegacyAgentsMarkdown(t *testing.T) {
+ tmpDir := setupWorkspace(t, map[string]string{
+ "AGENTS.md": "# Legacy Agent\nKeep compatibility.",
+ "SOUL.md": "# Soul\nLegacy soul.",
+ })
+ defer cleanupWorkspace(t, tmpDir)
+
+ cb := NewContextBuilder(tmpDir)
+ definition := cb.LoadAgentDefinition()
+
+ if definition.Source != AgentDefinitionSourceAgents {
+ t.Fatalf("expected source %q, got %q", AgentDefinitionSourceAgents, definition.Source)
+ }
+ if definition.Agent == nil {
+ t.Fatal("expected AGENTS.md to be loaded")
+ }
+ if definition.Agent.RawFrontmatter != "" {
+ t.Fatalf("legacy AGENTS.md should not have frontmatter, got %q", definition.Agent.RawFrontmatter)
+ }
+ if !strings.Contains(definition.Agent.Body, "Keep compatibility") {
+ t.Fatalf("expected legacy body to be preserved, got %q", definition.Agent.Body)
+ }
+ if definition.Soul == nil || !strings.Contains(definition.Soul.Content, "Legacy soul") {
+ t.Fatal("expected default SOUL.md to be loaded for legacy format")
+ }
+}
+
+func TestLoadAgentDefinitionLoadsWorkspaceUserMarkdown(t *testing.T) {
+ tmpDir := setupWorkspace(t, map[string]string{
+ "AGENT.md": "# Agent\nStructured agent.",
+ "USER.md": "# User\nWorkspace preferences.",
+ })
+ defer cleanupWorkspace(t, tmpDir)
+
+ cb := NewContextBuilder(tmpDir)
+ definition := cb.LoadAgentDefinition()
+
+ if definition.User == nil {
+ t.Fatal("expected USER.md to be loaded")
+ }
+ if definition.User.Path != filepath.Join(tmpDir, "USER.md") {
+ t.Fatalf("expected workspace USER.md path, got %q", definition.User.Path)
+ }
+ if !strings.Contains(definition.User.Content, "Workspace preferences") {
+ t.Fatalf("expected workspace USER.md content, got %q", definition.User.Content)
+ }
+}
+
+func TestLoadAgentDefinitionInvalidFrontmatterFallsBackToEmptyStructuredFields(t *testing.T) {
+ tmpDir := setupWorkspace(t, map[string]string{
+ "AGENT.md": `---
+name: pico
+tools:
+ - shell
+ broken
+---
+# Agent
+
+Keep going.
+`,
+ })
+ defer cleanupWorkspace(t, tmpDir)
+
+ cb := NewContextBuilder(tmpDir)
+ definition := cb.LoadAgentDefinition()
+
+ if definition.Agent == nil {
+ t.Fatal("expected AGENT.md definition to be loaded")
+ }
+ if !strings.Contains(definition.Agent.Body, "Keep going.") {
+ t.Fatalf("expected AGENT.md body to be preserved, got %q", definition.Agent.Body)
+ }
+ if definition.Agent.Frontmatter.Name != "" ||
+ definition.Agent.Frontmatter.Description != "" ||
+ definition.Agent.Frontmatter.Model != "" ||
+ definition.Agent.Frontmatter.MaxTurns != nil ||
+ len(definition.Agent.Frontmatter.Tools) != 0 ||
+ len(definition.Agent.Frontmatter.Skills) != 0 ||
+ len(definition.Agent.Frontmatter.MCPServers) != 0 ||
+ len(definition.Agent.Frontmatter.Fields) != 0 {
+ t.Fatalf("expected invalid frontmatter to decode as empty struct, got %+v", definition.Agent.Frontmatter)
+ }
+}
+
+func TestLoadBootstrapFilesUsesAgentBodyNotFrontmatter(t *testing.T) {
+ tmpDir := setupWorkspace(t, map[string]string{
+ "AGENT.md": `---
+name: pico
+model: codex-mini
+---
+# Agent
+
+Follow the body prompt.
+`,
+ "SOUL.md": "# Soul\nSpeak plainly.",
+ "IDENTITY.md": "# Identity\nWorkspace identity.",
+ })
+ defer cleanupWorkspace(t, tmpDir)
+
+ cb := NewContextBuilder(tmpDir)
+ bootstrap := cb.LoadBootstrapFiles()
+
+ if !strings.Contains(bootstrap, "Follow the body prompt") {
+ t.Fatalf("expected AGENT.md body in bootstrap, got %q", bootstrap)
+ }
+ if !strings.Contains(bootstrap, "Speak plainly") {
+ t.Fatalf("expected resolved soul content in bootstrap, got %q", bootstrap)
+ }
+ if strings.Contains(bootstrap, "name: pico") {
+ t.Fatalf("bootstrap should not expose raw frontmatter, got %q", bootstrap)
+ }
+ if strings.Contains(bootstrap, "model: codex-mini") {
+ t.Fatalf("bootstrap should not expose raw frontmatter, got %q", bootstrap)
+ }
+ if !strings.Contains(bootstrap, "SOUL.md") {
+ t.Fatalf("expected bootstrap to label SOUL.md, got %q", bootstrap)
+ }
+ if strings.Contains(bootstrap, "Workspace identity") {
+ t.Fatalf("structured bootstrap should ignore IDENTITY.md, got %q", bootstrap)
+ }
+}
+
+func TestLoadBootstrapFilesIncludesWorkspaceUserMarkdown(t *testing.T) {
+ tmpDir := setupWorkspace(t, map[string]string{
+ "AGENT.md": "# Agent\nFollow the new structure.",
+ "SOUL.md": "# Soul\nSpeak plainly.",
+ "USER.md": "# User\nShared profile.",
+ })
+ defer cleanupWorkspace(t, tmpDir)
+
+ cb := NewContextBuilder(tmpDir)
+ bootstrap := cb.LoadBootstrapFiles()
+
+ if !strings.Contains(bootstrap, "Shared profile") {
+ t.Fatalf("expected workspace USER.md in bootstrap, got %q", bootstrap)
+ }
+ if !strings.Contains(bootstrap, "## USER.md") {
+ t.Fatalf("expected USER.md heading in bootstrap, got %q", bootstrap)
+ }
+}
+
+func TestStructuredAgentIgnoresIdentityChanges(t *testing.T) {
+ tmpDir := setupWorkspace(t, map[string]string{
+ "AGENT.md": "# Agent\nFollow the new structure.",
+ "SOUL.md": "# Soul\nVersion one.",
+ "IDENTITY.md": "# Identity\nLegacy identity.",
+ })
+ defer cleanupWorkspace(t, tmpDir)
+
+ cb := NewContextBuilder(tmpDir)
+
+ promptV1 := cb.BuildSystemPromptWithCache()
+ if strings.Contains(promptV1, "Legacy identity") {
+ t.Fatalf("structured prompt should not include IDENTITY.md, got %q", promptV1)
+ }
+
+ identityPath := filepath.Join(tmpDir, "IDENTITY.md")
+ if err := os.WriteFile(identityPath, []byte("# Identity\nVersion two."), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ future := time.Now().Add(2 * time.Second)
+ if err := os.Chtimes(identityPath, future, future); err != nil {
+ t.Fatal(err)
+ }
+
+ cb.systemPromptMutex.RLock()
+ changed := cb.sourceFilesChangedLocked()
+ cb.systemPromptMutex.RUnlock()
+ if changed {
+ t.Fatal("IDENTITY.md should not invalidate cache for structured agent definitions")
+ }
+
+ promptV2 := cb.BuildSystemPromptWithCache()
+ if promptV1 != promptV2 {
+ t.Fatal("structured prompt should remain stable after IDENTITY.md changes")
+ }
+}
+
+func TestStructuredAgentUserChangesInvalidateCache(t *testing.T) {
+ tmpDir := setupWorkspace(t, map[string]string{
+ "AGENT.md": "# Agent\nFollow the new structure.",
+ "SOUL.md": "# Soul\nVersion one.",
+ "USER.md": "# User\nInitial workspace preferences.",
+ })
+ defer cleanupWorkspace(t, tmpDir)
+
+ cb := NewContextBuilder(tmpDir)
+
+ promptV1 := cb.BuildSystemPromptWithCache()
+ if !strings.Contains(promptV1, "Initial workspace preferences") {
+ t.Fatalf("expected workspace USER.md in prompt, got %q", promptV1)
+ }
+
+ userPath := filepath.Join(tmpDir, "USER.md")
+ if err := os.WriteFile(userPath, []byte("# User\nUpdated workspace preferences."), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ future := time.Now().Add(2 * time.Second)
+ if err := os.Chtimes(userPath, future, future); err != nil {
+ t.Fatal(err)
+ }
+
+ cb.systemPromptMutex.RLock()
+ changed := cb.sourceFilesChangedLocked()
+ cb.systemPromptMutex.RUnlock()
+ if !changed {
+ t.Fatal("workspace USER.md changes should invalidate cache")
+ }
+
+ promptV2 := cb.BuildSystemPromptWithCache()
+ if !strings.Contains(promptV2, "Updated workspace preferences") {
+ t.Fatalf("expected updated workspace USER.md in prompt, got %q", promptV2)
+ }
+}
+
+func cleanupWorkspace(t *testing.T, path string) {
+ t.Helper()
+ if err := os.RemoveAll(path); err != nil {
+ t.Fatalf("failed to clean up workspace %s: %v", path, err)
+ }
+}
diff --git a/pkg/agent/eventbus.go b/pkg/agent/eventbus.go
new file mode 100644
index 000000000..546d8436d
--- /dev/null
+++ b/pkg/agent/eventbus.go
@@ -0,0 +1,121 @@
+package agent
+
+import (
+ "sync"
+ "sync/atomic"
+ "time"
+)
+
+const defaultEventSubscriberBuffer = 16
+
+// EventSubscription identifies a subscriber channel returned by EventBus.Subscribe.
+type EventSubscription struct {
+ ID uint64
+ C <-chan Event
+}
+
+type eventSubscriber struct {
+ ch chan Event
+}
+
+// EventBus is a lightweight multi-subscriber broadcaster for agent-loop events.
+type EventBus struct {
+ mu sync.RWMutex
+ subs map[uint64]eventSubscriber
+ nextID uint64
+ closed bool
+ dropped [eventKindCount]atomic.Int64
+}
+
+// NewEventBus creates a new in-process event broadcaster.
+func NewEventBus() *EventBus {
+ return &EventBus{
+ subs: make(map[uint64]eventSubscriber),
+ }
+}
+
+// Subscribe registers a new subscriber with the requested channel buffer size.
+// A non-positive buffer uses the default size.
+func (b *EventBus) Subscribe(buffer int) EventSubscription {
+ if buffer <= 0 {
+ buffer = defaultEventSubscriberBuffer
+ }
+
+ b.mu.Lock()
+ defer b.mu.Unlock()
+
+ if b.closed {
+ ch := make(chan Event)
+ close(ch)
+ return EventSubscription{C: ch}
+ }
+
+ b.nextID++
+ id := b.nextID
+ ch := make(chan Event, buffer)
+ b.subs[id] = eventSubscriber{ch: ch}
+ return EventSubscription{ID: id, C: ch}
+}
+
+// Unsubscribe removes a subscriber and closes its channel.
+func (b *EventBus) Unsubscribe(id uint64) {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+
+ sub, ok := b.subs[id]
+ if !ok {
+ return
+ }
+
+ delete(b.subs, id)
+ close(sub.ch)
+}
+
+// Emit broadcasts an event to all current subscribers without blocking.
+// When a subscriber channel is full, the event is dropped for that subscriber.
+func (b *EventBus) Emit(evt Event) {
+ if evt.Time.IsZero() {
+ evt.Time = time.Now()
+ }
+
+ b.mu.RLock()
+ defer b.mu.RUnlock()
+
+ if b.closed {
+ return
+ }
+
+ for _, sub := range b.subs {
+ select {
+ case sub.ch <- evt:
+ default:
+ if evt.Kind < eventKindCount {
+ b.dropped[evt.Kind].Add(1)
+ }
+ }
+ }
+}
+
+// Dropped returns the number of dropped events for a given kind.
+func (b *EventBus) Dropped(kind EventKind) int64 {
+ if kind >= eventKindCount {
+ return 0
+ }
+ return b.dropped[kind].Load()
+}
+
+// Close closes all subscriber channels and stops future broadcasts.
+func (b *EventBus) Close() {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+
+ if b.closed {
+ return
+ }
+
+ b.closed = true
+ for id, sub := range b.subs {
+ close(sub.ch)
+ delete(b.subs, id)
+ }
+}
diff --git a/pkg/agent/eventbus_test.go b/pkg/agent/eventbus_test.go
new file mode 100644
index 000000000..19a1ea9eb
--- /dev/null
+++ b/pkg/agent/eventbus_test.go
@@ -0,0 +1,684 @@
+package agent
+
+import (
+ "context"
+ "os"
+ "slices"
+ "testing"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/tools"
+)
+
+func TestEventBus_SubscribeEmitUnsubscribeClose(t *testing.T) {
+ eventBus := NewEventBus()
+ sub := eventBus.Subscribe(1)
+
+ eventBus.Emit(Event{
+ Kind: EventKindTurnStart,
+ Meta: EventMeta{TurnID: "turn-1"},
+ })
+
+ select {
+ case evt := <-sub.C:
+ if evt.Kind != EventKindTurnStart {
+ t.Fatalf("expected %v, got %v", EventKindTurnStart, evt.Kind)
+ }
+ if evt.Meta.TurnID != "turn-1" {
+ t.Fatalf("expected turn id turn-1, got %q", evt.Meta.TurnID)
+ }
+ case <-time.After(time.Second):
+ t.Fatal("timed out waiting for event")
+ }
+
+ eventBus.Unsubscribe(sub.ID)
+ if _, ok := <-sub.C; ok {
+ t.Fatal("expected subscriber channel to be closed after unsubscribe")
+ }
+
+ eventBus.Close()
+ closedSub := eventBus.Subscribe(1)
+ if _, ok := <-closedSub.C; ok {
+ t.Fatal("expected closed bus to return a closed subscriber channel")
+ }
+}
+
+func TestEventBus_DropsWhenSubscriberIsFull(t *testing.T) {
+ eventBus := NewEventBus()
+ sub := eventBus.Subscribe(1)
+ defer eventBus.Unsubscribe(sub.ID)
+
+ start := time.Now()
+ for i := 0; i < 1000; i++ {
+ eventBus.Emit(Event{Kind: EventKindLLMRequest})
+ }
+
+ if elapsed := time.Since(start); elapsed > 100*time.Millisecond {
+ t.Fatalf("Emit took too long with a blocked subscriber: %s", elapsed)
+ }
+
+ if got := eventBus.Dropped(EventKindLLMRequest); got != 999 {
+ t.Fatalf("expected 999 dropped events, got %d", got)
+ }
+}
+
+type scriptedToolProvider struct {
+ calls int
+}
+
+func (m *scriptedToolProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ toolDefs []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ m.calls++
+ if m.calls == 1 {
+ return &providers.LLMResponse{
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "call-1",
+ Name: "mock_custom",
+ Arguments: map[string]any{"task": "ping"},
+ },
+ },
+ }, nil
+ }
+
+ return &providers.LLMResponse{
+ Content: "done",
+ }, nil
+}
+
+func (m *scriptedToolProvider) GetDefaultModel() string {
+ return "scripted-tool-model"
+}
+
+func TestAgentLoop_EmitsMinimalTurnEvents(t *testing.T) {
+ tmpDir, err := os.MkdirTemp("", "agent-eventbus-*")
+ 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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ provider := &scriptedToolProvider{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+ al.RegisterTool(&mockCustomTool{})
+ defaultAgent := al.registry.GetDefaultAgent()
+ if defaultAgent == nil {
+ t.Fatal("expected default agent")
+ }
+
+ sub := al.SubscribeEvents(16)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ response, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "run tool",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+ if response != "done" {
+ t.Fatalf("expected final response 'done', got %q", response)
+ }
+
+ events := collectEventStream(sub.C)
+ if len(events) != 8 {
+ t.Fatalf("expected 8 events, got %d", len(events))
+ }
+
+ kinds := make([]EventKind, 0, len(events))
+ for _, evt := range events {
+ kinds = append(kinds, evt.Kind)
+ }
+
+ expectedKinds := []EventKind{
+ EventKindTurnStart,
+ EventKindLLMRequest,
+ EventKindLLMResponse,
+ EventKindToolExecStart,
+ EventKindToolExecEnd,
+ EventKindLLMRequest,
+ EventKindLLMResponse,
+ EventKindTurnEnd,
+ }
+ if !slices.Equal(kinds, expectedKinds) {
+ t.Fatalf("unexpected event sequence: got %v want %v", kinds, expectedKinds)
+ }
+
+ turnID := events[0].Meta.TurnID
+ for i, evt := range events {
+ if evt.Meta.TurnID != turnID {
+ t.Fatalf("event %d has mismatched turn id %q, want %q", i, evt.Meta.TurnID, turnID)
+ }
+ if evt.Meta.SessionKey != "session-1" {
+ t.Fatalf("event %d has session key %q, want session-1", i, evt.Meta.SessionKey)
+ }
+ }
+
+ startPayload, ok := events[0].Payload.(TurnStartPayload)
+ if !ok {
+ t.Fatalf("expected TurnStartPayload, got %T", events[0].Payload)
+ }
+ if startPayload.UserMessage != "run tool" {
+ t.Fatalf("expected user message 'run tool', got %q", startPayload.UserMessage)
+ }
+
+ toolStartPayload, ok := events[3].Payload.(ToolExecStartPayload)
+ if !ok {
+ t.Fatalf("expected ToolExecStartPayload, got %T", events[3].Payload)
+ }
+ if toolStartPayload.Tool != "mock_custom" {
+ t.Fatalf("expected tool name mock_custom, got %q", toolStartPayload.Tool)
+ }
+
+ toolEndPayload, ok := events[4].Payload.(ToolExecEndPayload)
+ if !ok {
+ t.Fatalf("expected ToolExecEndPayload, got %T", events[4].Payload)
+ }
+ if toolEndPayload.Tool != "mock_custom" {
+ t.Fatalf("expected tool end payload for mock_custom, got %q", toolEndPayload.Tool)
+ }
+ if toolEndPayload.IsError {
+ t.Fatal("expected mock_custom tool to succeed")
+ }
+
+ turnEndPayload, ok := events[len(events)-1].Payload.(TurnEndPayload)
+ if !ok {
+ t.Fatalf("expected TurnEndPayload, got %T", events[len(events)-1].Payload)
+ }
+ if turnEndPayload.Status != TurnEndStatusCompleted {
+ t.Fatalf("expected completed turn, got %q", turnEndPayload.Status)
+ }
+ if turnEndPayload.Iterations != 2 {
+ t.Fatalf("expected 2 iterations, got %d", turnEndPayload.Iterations)
+ }
+}
+
+func TestAgentLoop_EmitsSteeringAndSkippedToolEvents(t *testing.T) {
+ tmpDir, err := os.MkdirTemp("", "agent-eventbus-steering-*")
+ 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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ tool1ExecCh := make(chan struct{})
+ tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh}
+ tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond}
+
+ provider := &toolCallProvider{
+ toolCalls: []providers.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Name: "tool_one",
+ Function: &providers.FunctionCall{
+ Name: "tool_one",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ {
+ ID: "call_2",
+ Type: "function",
+ Name: "tool_two",
+ Function: &providers.FunctionCall{
+ Name: "tool_two",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ },
+ finalResp: "steered response",
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, provider)
+ al.RegisterTool(tool1)
+ al.RegisterTool(tool2)
+
+ sub := al.SubscribeEvents(32)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ resultCh := make(chan string, 1)
+ go func() {
+ resp, _ := al.ProcessDirectWithChannel(context.Background(), "do something", "test-session", "test", "chat1")
+ resultCh <- resp
+ }()
+
+ select {
+ case <-tool1ExecCh:
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for tool_one to start")
+ }
+
+ if err := al.Steer(providers.Message{Role: "user", Content: "change course"}); err != nil {
+ t.Fatalf("Steer failed: %v", err)
+ }
+
+ select {
+ case resp := <-resultCh:
+ if resp != "steered response" {
+ t.Fatalf("expected steered response, got %q", resp)
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatal("timeout waiting for steered response")
+ }
+
+ events := collectEventStream(sub.C)
+ steeringEvt, ok := findEvent(events, EventKindSteeringInjected)
+ if !ok {
+ t.Fatal("expected steering injected event")
+ }
+ steeringPayload, ok := steeringEvt.Payload.(SteeringInjectedPayload)
+ if !ok {
+ t.Fatalf("expected SteeringInjectedPayload, got %T", steeringEvt.Payload)
+ }
+ if steeringPayload.Count != 1 {
+ t.Fatalf("expected 1 steering message, got %d", steeringPayload.Count)
+ }
+
+ skippedEvt, ok := findEvent(events, EventKindToolExecSkipped)
+ if !ok {
+ t.Fatal("expected skipped tool event")
+ }
+ skippedPayload, ok := skippedEvt.Payload.(ToolExecSkippedPayload)
+ if !ok {
+ t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload)
+ }
+ if skippedPayload.Tool != "tool_two" {
+ t.Fatalf("expected skipped tool_two, got %q", skippedPayload.Tool)
+ }
+
+ interruptEvt, ok := findEvent(events, EventKindInterruptReceived)
+ if !ok {
+ t.Fatal("expected interrupt received event")
+ }
+ interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload)
+ if !ok {
+ t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload)
+ }
+ if interruptPayload.Role != "user" {
+ t.Fatalf("expected interrupt role user, got %q", interruptPayload.Role)
+ }
+ if interruptPayload.Kind != InterruptKindSteering {
+ t.Fatalf("expected steering interrupt kind, got %q", interruptPayload.Kind)
+ }
+ if interruptPayload.ContentLen != len("change course") {
+ t.Fatalf("expected interrupt content len %d, got %d", len("change course"), interruptPayload.ContentLen)
+ }
+}
+
+func TestAgentLoop_EmitsContextCompressEventOnRetry(t *testing.T) {
+ tmpDir, err := os.MkdirTemp("", "agent-eventbus-compress-*")
+ 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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ contextErr := stringError("InvalidParameter: Total tokens of image and text exceed max message tokens")
+ provider := &failFirstMockProvider{
+ failures: 1,
+ failError: contextErr,
+ successResp: "Recovered from context error",
+ }
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, provider)
+ defaultAgent := al.registry.GetDefaultAgent()
+ if defaultAgent == nil {
+ t.Fatal("expected default agent")
+ }
+
+ defaultAgent.Sessions.SetHistory("session-1", []providers.Message{
+ {Role: "user", Content: "Old message 1"},
+ {Role: "assistant", Content: "Old response 1"},
+ {Role: "user", Content: "Old message 2"},
+ {Role: "assistant", Content: "Old response 2"},
+ {Role: "user", Content: "Trigger message"},
+ })
+
+ sub := al.SubscribeEvents(16)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ resp, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "Trigger message",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+ if resp != "Recovered from context error" {
+ t.Fatalf("expected retry success, got %q", resp)
+ }
+
+ events := collectEventStream(sub.C)
+ retryEvt, ok := findEvent(events, EventKindLLMRetry)
+ if !ok {
+ t.Fatal("expected llm retry event")
+ }
+ retryPayload, ok := retryEvt.Payload.(LLMRetryPayload)
+ if !ok {
+ t.Fatalf("expected LLMRetryPayload, got %T", retryEvt.Payload)
+ }
+ if retryPayload.Reason != "context_limit" {
+ t.Fatalf("expected context_limit retry reason, got %q", retryPayload.Reason)
+ }
+ if retryPayload.Attempt != 1 {
+ t.Fatalf("expected retry attempt 1, got %d", retryPayload.Attempt)
+ }
+
+ compressEvt, ok := findEvent(events, EventKindContextCompress)
+ if !ok {
+ t.Fatal("expected context compress event")
+ }
+ payload, ok := compressEvt.Payload.(ContextCompressPayload)
+ if !ok {
+ t.Fatalf("expected ContextCompressPayload, got %T", compressEvt.Payload)
+ }
+ if payload.Reason != ContextCompressReasonRetry {
+ t.Fatalf("expected retry compress reason, got %q", payload.Reason)
+ }
+ if payload.DroppedMessages == 0 {
+ t.Fatal("expected dropped messages to be recorded")
+ }
+}
+
+func TestAgentLoop_EmitsSessionSummarizeEvent(t *testing.T) {
+ tmpDir, err := os.MkdirTemp("", "agent-eventbus-summary-*")
+ 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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ ContextWindow: 8000,
+ SummarizeMessageThreshold: 2,
+ SummarizeTokenPercent: 75,
+ },
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, &simpleMockProvider{response: "summary text"})
+ defaultAgent := al.registry.GetDefaultAgent()
+ if defaultAgent == nil {
+ t.Fatal("expected default agent")
+ }
+
+ defaultAgent.Sessions.SetHistory("session-1", []providers.Message{
+ {Role: "user", Content: "Question one"},
+ {Role: "assistant", Content: "Answer one"},
+ {Role: "user", Content: "Question two"},
+ {Role: "assistant", Content: "Answer two"},
+ {Role: "user", Content: "Question three"},
+ {Role: "assistant", Content: "Answer three"},
+ })
+
+ sub := al.SubscribeEvents(16)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ turnScope := al.newTurnEventScope(defaultAgent.ID, "session-1")
+ al.summarizeSession(defaultAgent, "session-1", turnScope)
+
+ events := collectEventStream(sub.C)
+ summaryEvt, ok := findEvent(events, EventKindSessionSummarize)
+ if !ok {
+ t.Fatal("expected session summarize event")
+ }
+ payload, ok := summaryEvt.Payload.(SessionSummarizePayload)
+ if !ok {
+ t.Fatalf("expected SessionSummarizePayload, got %T", summaryEvt.Payload)
+ }
+ if payload.SummaryLen == 0 {
+ t.Fatal("expected non-empty summary length")
+ }
+}
+
+func TestAgentLoop_EmitsFollowUpQueuedEvent(t *testing.T) {
+ tmpDir, err := os.MkdirTemp("", "agent-eventbus-followup-*")
+ 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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ provider := &toolCallProvider{
+ toolCalls: []providers.ToolCall{
+ {
+ ID: "call_async_1",
+ Type: "function",
+ Name: "async_followup",
+ Function: &providers.FunctionCall{
+ Name: "async_followup",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ },
+ finalResp: "async launched",
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, provider)
+ doneCh := make(chan struct{})
+ al.RegisterTool(&asyncFollowUpTool{
+ name: "async_followup",
+ followUpText: "background result",
+ completionSig: doneCh,
+ })
+ defaultAgent := al.registry.GetDefaultAgent()
+ if defaultAgent == nil {
+ t.Fatal("expected default agent")
+ }
+
+ sub := al.SubscribeEvents(32)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ resp, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "run async tool",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+ if resp != "async launched" {
+ t.Fatalf("expected final response 'async launched', got %q", resp)
+ }
+
+ select {
+ case <-doneCh:
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for async tool completion")
+ }
+
+ followUpEvt := waitForEvent(t, sub.C, 2*time.Second, func(evt Event) bool {
+ return evt.Kind == EventKindFollowUpQueued
+ })
+ payload, ok := followUpEvt.Payload.(FollowUpQueuedPayload)
+ if !ok {
+ t.Fatalf("expected FollowUpQueuedPayload, got %T", followUpEvt.Payload)
+ }
+ if payload.SourceTool != "async_followup" {
+ t.Fatalf("expected source tool async_followup, got %q", payload.SourceTool)
+ }
+ if payload.Channel != "cli" {
+ t.Fatalf("expected channel cli, got %q", payload.Channel)
+ }
+ if payload.ChatID != "direct" {
+ t.Fatalf("expected chat id direct, got %q", payload.ChatID)
+ }
+ if payload.ContentLen != len("background result") {
+ t.Fatalf("expected content len %d, got %d", len("background result"), payload.ContentLen)
+ }
+ if followUpEvt.Meta.SessionKey != "session-1" {
+ t.Fatalf("expected session key session-1, got %q", followUpEvt.Meta.SessionKey)
+ }
+ if followUpEvt.Meta.TurnID == "" {
+ t.Fatal("expected follow-up event to include turn id")
+ }
+}
+
+func collectEventStream(ch <-chan Event) []Event {
+ var events []Event
+ for {
+ select {
+ case evt, ok := <-ch:
+ if !ok {
+ return events
+ }
+ events = append(events, evt)
+ default:
+ return events
+ }
+ }
+}
+
+func waitForEvent(t *testing.T, ch <-chan Event, timeout time.Duration, match func(Event) bool) Event {
+ t.Helper()
+
+ timer := time.NewTimer(timeout)
+ defer timer.Stop()
+
+ for {
+ select {
+ case evt, ok := <-ch:
+ if !ok {
+ t.Fatal("event stream closed before expected event arrived")
+ }
+ if match(evt) {
+ return evt
+ }
+ case <-timer.C:
+ t.Fatal("timed out waiting for expected event")
+ }
+ }
+}
+
+func findEvent(events []Event, kind EventKind) (Event, bool) {
+ for _, evt := range events {
+ if evt.Kind == kind {
+ return evt, true
+ }
+ }
+ return Event{}, false
+}
+
+type stringError string
+
+func (e stringError) Error() string {
+ return string(e)
+}
+
+type asyncFollowUpTool struct {
+ name string
+ followUpText string
+ completionSig chan struct{}
+}
+
+func (t *asyncFollowUpTool) Name() string {
+ return t.name
+}
+
+func (t *asyncFollowUpTool) Description() string {
+ return "async follow-up tool for testing"
+}
+
+func (t *asyncFollowUpTool) Parameters() map[string]any {
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{},
+ }
+}
+
+func (t *asyncFollowUpTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+ return tools.AsyncResult("async follow-up scheduled")
+}
+
+func (t *asyncFollowUpTool) ExecuteAsync(
+ ctx context.Context,
+ args map[string]any,
+ cb tools.AsyncCallback,
+) *tools.ToolResult {
+ go func() {
+ cb(ctx, &tools.ToolResult{ForLLM: t.followUpText})
+ if t.completionSig != nil {
+ close(t.completionSig)
+ }
+ }()
+ return tools.AsyncResult("async follow-up scheduled")
+}
+
+var (
+ _ tools.Tool = (*mockCustomTool)(nil)
+ _ tools.AsyncExecutor = (*asyncFollowUpTool)(nil)
+)
diff --git a/pkg/agent/events.go b/pkg/agent/events.go
new file mode 100644
index 000000000..f4562b360
--- /dev/null
+++ b/pkg/agent/events.go
@@ -0,0 +1,271 @@
+package agent
+
+import (
+ "fmt"
+ "time"
+)
+
+// EventKind identifies a structured agent-loop event.
+type EventKind uint8
+
+const (
+ // EventKindTurnStart is emitted when a turn begins processing.
+ EventKindTurnStart EventKind = iota
+ // EventKindTurnEnd is emitted when a turn finishes, successfully or with an error.
+ EventKindTurnEnd
+ // EventKindLLMRequest is emitted before a provider chat request is made.
+ EventKindLLMRequest
+ // EventKindLLMDelta is emitted when a streaming provider yields a partial delta.
+ EventKindLLMDelta
+ // EventKindLLMResponse is emitted after a provider chat response is received.
+ EventKindLLMResponse
+ // EventKindLLMRetry is emitted when an LLM request is retried.
+ EventKindLLMRetry
+ // EventKindContextCompress is emitted when session history is forcibly compressed.
+ EventKindContextCompress
+ // EventKindSessionSummarize is emitted when asynchronous summarization completes.
+ EventKindSessionSummarize
+ // EventKindToolExecStart is emitted immediately before a tool executes.
+ EventKindToolExecStart
+ // EventKindToolExecEnd is emitted immediately after a tool finishes executing.
+ EventKindToolExecEnd
+ // EventKindToolExecSkipped is emitted when a queued tool call is skipped.
+ EventKindToolExecSkipped
+ // EventKindSteeringInjected is emitted when queued steering is injected into context.
+ EventKindSteeringInjected
+ // EventKindFollowUpQueued is emitted when an async tool queues a follow-up system message.
+ EventKindFollowUpQueued
+ // EventKindInterruptReceived is emitted when a soft interrupt message is accepted.
+ EventKindInterruptReceived
+ // EventKindSubTurnSpawn is emitted when a sub-turn is spawned.
+ EventKindSubTurnSpawn
+ // EventKindSubTurnEnd is emitted when a sub-turn finishes.
+ EventKindSubTurnEnd
+ // EventKindSubTurnResultDelivered is emitted when a sub-turn result is delivered.
+ EventKindSubTurnResultDelivered
+ // EventKindSubTurnOrphan is emitted when a sub-turn result cannot be delivered.
+ EventKindSubTurnOrphan
+ // EventKindError is emitted when a turn encounters an execution error.
+ EventKindError
+
+ eventKindCount
+)
+
+var eventKindNames = [...]string{
+ "turn_start",
+ "turn_end",
+ "llm_request",
+ "llm_delta",
+ "llm_response",
+ "llm_retry",
+ "context_compress",
+ "session_summarize",
+ "tool_exec_start",
+ "tool_exec_end",
+ "tool_exec_skipped",
+ "steering_injected",
+ "follow_up_queued",
+ "interrupt_received",
+ "subturn_spawn",
+ "subturn_end",
+ "subturn_result_delivered",
+ "subturn_orphan",
+ "error",
+}
+
+// String returns the stable string form of an EventKind.
+func (k EventKind) String() string {
+ if k >= eventKindCount {
+ return fmt.Sprintf("event_kind(%d)", k)
+ }
+ return eventKindNames[k]
+}
+
+// Event is the structured envelope broadcast by the agent EventBus.
+type Event struct {
+ Kind EventKind
+ Time time.Time
+ Meta EventMeta
+ Payload any
+}
+
+// EventMeta contains correlation fields shared by all agent-loop events.
+type EventMeta struct {
+ AgentID string
+ TurnID string
+ ParentTurnID string
+ SessionKey string
+ Iteration int
+ TracePath string
+ Source string
+}
+
+// TurnEndStatus describes the terminal state of a turn.
+type TurnEndStatus string
+
+const (
+ // TurnEndStatusCompleted indicates the turn finished normally.
+ TurnEndStatusCompleted TurnEndStatus = "completed"
+ // TurnEndStatusError indicates the turn ended because of an error.
+ TurnEndStatusError TurnEndStatus = "error"
+ // TurnEndStatusAborted indicates the turn was hard-aborted and rolled back.
+ TurnEndStatusAborted TurnEndStatus = "aborted"
+)
+
+// TurnStartPayload describes the start of a turn.
+type TurnStartPayload struct {
+ Channel string
+ ChatID string
+ UserMessage string
+ MediaCount int
+}
+
+// TurnEndPayload describes the completion of a turn.
+type TurnEndPayload struct {
+ Status TurnEndStatus
+ Iterations int
+ Duration time.Duration
+ FinalContentLen int
+}
+
+// LLMRequestPayload describes an outbound LLM request.
+type LLMRequestPayload struct {
+ Model string
+ MessagesCount int
+ ToolsCount int
+ MaxTokens int
+ Temperature float64
+}
+
+// LLMResponsePayload describes an inbound LLM response.
+type LLMResponsePayload struct {
+ ContentLen int
+ ToolCalls int
+ HasReasoning bool
+}
+
+// LLMDeltaPayload describes a streamed LLM delta.
+type LLMDeltaPayload struct {
+ ContentDeltaLen int
+ ReasoningDeltaLen int
+}
+
+// LLMRetryPayload describes a retry of an LLM request.
+type LLMRetryPayload struct {
+ Attempt int
+ MaxRetries int
+ Reason string
+ Error string
+ Backoff time.Duration
+}
+
+// ContextCompressReason identifies why emergency compression ran.
+type ContextCompressReason string
+
+const (
+ // ContextCompressReasonProactive indicates compression before the first LLM call.
+ ContextCompressReasonProactive ContextCompressReason = "proactive_budget"
+ // ContextCompressReasonRetry indicates compression during context-error retry handling.
+ ContextCompressReasonRetry ContextCompressReason = "llm_retry"
+)
+
+// ContextCompressPayload describes a forced history compression.
+type ContextCompressPayload struct {
+ Reason ContextCompressReason
+ DroppedMessages int
+ RemainingMessages int
+}
+
+// SessionSummarizePayload describes a completed async session summarization.
+type SessionSummarizePayload struct {
+ SummarizedMessages int
+ KeptMessages int
+ SummaryLen int
+ OmittedOversized bool
+}
+
+// ToolExecStartPayload describes a tool execution request.
+type ToolExecStartPayload struct {
+ Tool string
+ Arguments map[string]any
+}
+
+// ToolExecEndPayload describes the outcome of a tool execution.
+type ToolExecEndPayload struct {
+ Tool string
+ Duration time.Duration
+ ForLLMLen int
+ ForUserLen int
+ IsError bool
+ Async bool
+}
+
+// ToolExecSkippedPayload describes a skipped tool call.
+type ToolExecSkippedPayload struct {
+ Tool string
+ Reason string
+}
+
+// SteeringInjectedPayload describes steering messages appended before the next LLM call.
+type SteeringInjectedPayload struct {
+ Count int
+ TotalContentLen int
+}
+
+// FollowUpQueuedPayload describes an async follow-up queued back into the inbound bus.
+type FollowUpQueuedPayload struct {
+ SourceTool string
+ Channel string
+ ChatID string
+ ContentLen int
+}
+
+type InterruptKind string
+
+const (
+ InterruptKindSteering InterruptKind = "steering"
+ InterruptKindGraceful InterruptKind = "graceful"
+ InterruptKindHard InterruptKind = "hard_abort"
+)
+
+// InterruptReceivedPayload describes accepted turn-control input.
+type InterruptReceivedPayload struct {
+ Kind InterruptKind
+ Role string
+ ContentLen int
+ QueueDepth int
+ HintLen int
+}
+
+// SubTurnSpawnPayload describes the creation of a child turn.
+type SubTurnSpawnPayload struct {
+ AgentID string
+ Label string
+ ParentTurnID string
+}
+
+// SubTurnEndPayload describes the completion of a child turn.
+type SubTurnEndPayload struct {
+ AgentID string
+ Status string
+}
+
+// SubTurnResultDeliveredPayload describes delivery of a sub-turn result.
+type SubTurnResultDeliveredPayload struct {
+ TargetChannel string
+ TargetChatID string
+ ContentLen int
+}
+
+// SubTurnOrphanPayload describes a sub-turn result that could not be delivered.
+type SubTurnOrphanPayload struct {
+ ParentTurnID string
+ ChildTurnID string
+ Reason string
+}
+
+// ErrorPayload describes an execution error inside the agent loop.
+type ErrorPayload struct {
+ Stage string
+ Message string
+}
diff --git a/pkg/agent/hook_mount.go b/pkg/agent/hook_mount.go
new file mode 100644
index 000000000..c92145f1f
--- /dev/null
+++ b/pkg/agent/hook_mount.go
@@ -0,0 +1,317 @@
+package agent
+
+import (
+ "context"
+ "fmt"
+ "sort"
+ "sync"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+type hookRuntime struct {
+ initOnce sync.Once
+ mu sync.Mutex
+ initErr error
+ mounted []string
+}
+
+func (r *hookRuntime) setInitErr(err error) {
+ r.mu.Lock()
+ r.initErr = err
+ r.mu.Unlock()
+}
+
+func (r *hookRuntime) getInitErr() error {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ return r.initErr
+}
+
+func (r *hookRuntime) setMounted(names []string) {
+ r.mu.Lock()
+ r.mounted = append([]string(nil), names...)
+ r.mu.Unlock()
+}
+
+func (r *hookRuntime) reset(al *AgentLoop) {
+ r.mu.Lock()
+ names := append([]string(nil), r.mounted...)
+ r.mounted = nil
+ r.initErr = nil
+ r.initOnce = sync.Once{}
+ r.mu.Unlock()
+
+ for _, name := range names {
+ al.UnmountHook(name)
+ }
+}
+
+// BuiltinHookFactory constructs an in-process hook from config.
+type BuiltinHookFactory func(ctx context.Context, spec config.BuiltinHookConfig) (any, error)
+
+var (
+ builtinHookRegistryMu sync.RWMutex
+ builtinHookRegistry = map[string]BuiltinHookFactory{}
+)
+
+// RegisterBuiltinHook registers a named in-process hook factory for config-driven mounting.
+func RegisterBuiltinHook(name string, factory BuiltinHookFactory) error {
+ if name == "" {
+ return fmt.Errorf("builtin hook name is required")
+ }
+ if factory == nil {
+ return fmt.Errorf("builtin hook %q factory is nil", name)
+ }
+
+ builtinHookRegistryMu.Lock()
+ defer builtinHookRegistryMu.Unlock()
+
+ if _, exists := builtinHookRegistry[name]; exists {
+ return fmt.Errorf("builtin hook %q is already registered", name)
+ }
+ builtinHookRegistry[name] = factory
+ return nil
+}
+
+func unregisterBuiltinHook(name string) {
+ if name == "" {
+ return
+ }
+ builtinHookRegistryMu.Lock()
+ delete(builtinHookRegistry, name)
+ builtinHookRegistryMu.Unlock()
+}
+
+func lookupBuiltinHook(name string) (BuiltinHookFactory, bool) {
+ builtinHookRegistryMu.RLock()
+ defer builtinHookRegistryMu.RUnlock()
+
+ factory, ok := builtinHookRegistry[name]
+ return factory, ok
+}
+
+func configureHookManagerFromConfig(hm *HookManager, cfg *config.Config) {
+ if hm == nil || cfg == nil {
+ return
+ }
+ hm.ConfigureTimeouts(
+ hookTimeoutFromMS(cfg.Hooks.Defaults.ObserverTimeoutMS),
+ hookTimeoutFromMS(cfg.Hooks.Defaults.InterceptorTimeoutMS),
+ hookTimeoutFromMS(cfg.Hooks.Defaults.ApprovalTimeoutMS),
+ )
+}
+
+func hookTimeoutFromMS(ms int) time.Duration {
+ if ms <= 0 {
+ return 0
+ }
+ return time.Duration(ms) * time.Millisecond
+}
+
+func (al *AgentLoop) ensureHooksInitialized(ctx context.Context) error {
+ if al == nil || al.cfg == nil || al.hooks == nil {
+ return nil
+ }
+
+ al.hookRuntime.initOnce.Do(func() {
+ al.hookRuntime.setInitErr(al.loadConfiguredHooks(ctx))
+ })
+
+ return al.hookRuntime.getInitErr()
+}
+
+func (al *AgentLoop) loadConfiguredHooks(ctx context.Context) (err error) {
+ if al == nil || al.cfg == nil || !al.cfg.Hooks.Enabled {
+ return nil
+ }
+
+ mounted := make([]string, 0)
+ defer func() {
+ if err != nil {
+ for _, name := range mounted {
+ al.UnmountHook(name)
+ }
+ return
+ }
+ al.hookRuntime.setMounted(mounted)
+ }()
+
+ builtinNames := enabledBuiltinHookNames(al.cfg.Hooks.Builtins)
+ for _, name := range builtinNames {
+ spec := al.cfg.Hooks.Builtins[name]
+ factory, ok := lookupBuiltinHook(name)
+ if !ok {
+ return fmt.Errorf("builtin hook %q is not registered", name)
+ }
+
+ hook, factoryErr := factory(ctx, spec)
+ if factoryErr != nil {
+ return fmt.Errorf("build builtin hook %q: %w", name, factoryErr)
+ }
+ if err := al.MountHook(HookRegistration{
+ Name: name,
+ Priority: spec.Priority,
+ Source: HookSourceInProcess,
+ Hook: hook,
+ }); err != nil {
+ return fmt.Errorf("mount builtin hook %q: %w", name, err)
+ }
+ mounted = append(mounted, name)
+ }
+
+ processNames := enabledProcessHookNames(al.cfg.Hooks.Processes)
+ for _, name := range processNames {
+ spec := al.cfg.Hooks.Processes[name]
+ opts, buildErr := processHookOptionsFromConfig(spec)
+ if buildErr != nil {
+ return fmt.Errorf("configure process hook %q: %w", name, buildErr)
+ }
+
+ processHook, buildErr := NewProcessHook(ctx, name, opts)
+ if buildErr != nil {
+ return fmt.Errorf("start process hook %q: %w", name, buildErr)
+ }
+ if err := al.MountHook(HookRegistration{
+ Name: name,
+ Priority: spec.Priority,
+ Source: HookSourceProcess,
+ Hook: processHook,
+ }); err != nil {
+ _ = processHook.Close()
+ return fmt.Errorf("mount process hook %q: %w", name, err)
+ }
+ mounted = append(mounted, name)
+ }
+
+ return nil
+}
+
+func enabledBuiltinHookNames(specs map[string]config.BuiltinHookConfig) []string {
+ if len(specs) == 0 {
+ return nil
+ }
+
+ names := make([]string, 0, len(specs))
+ for name, spec := range specs {
+ if spec.Enabled {
+ names = append(names, name)
+ }
+ }
+ sort.Strings(names)
+ return names
+}
+
+func enabledProcessHookNames(specs map[string]config.ProcessHookConfig) []string {
+ if len(specs) == 0 {
+ return nil
+ }
+
+ names := make([]string, 0, len(specs))
+ for name, spec := range specs {
+ if spec.Enabled {
+ names = append(names, name)
+ }
+ }
+ sort.Strings(names)
+ return names
+}
+
+func processHookOptionsFromConfig(spec config.ProcessHookConfig) (ProcessHookOptions, error) {
+ transport := spec.Transport
+ if transport == "" {
+ transport = "stdio"
+ }
+ if transport != "stdio" {
+ return ProcessHookOptions{}, fmt.Errorf("unsupported transport %q", transport)
+ }
+ if len(spec.Command) == 0 {
+ return ProcessHookOptions{}, fmt.Errorf("command is required")
+ }
+
+ opts := ProcessHookOptions{
+ Command: append([]string(nil), spec.Command...),
+ Dir: spec.Dir,
+ Env: processHookEnvFromMap(spec.Env),
+ }
+
+ observeKinds, observeEnabled, err := processHookObserveKindsFromConfig(spec.Observe)
+ if err != nil {
+ return ProcessHookOptions{}, err
+ }
+ opts.Observe = observeEnabled
+ opts.ObserveKinds = observeKinds
+
+ for _, intercept := range spec.Intercept {
+ switch intercept {
+ case "before_llm", "after_llm":
+ opts.InterceptLLM = true
+ case "before_tool", "after_tool":
+ opts.InterceptTool = true
+ case "approve_tool":
+ opts.ApproveTool = true
+ case "":
+ continue
+ default:
+ return ProcessHookOptions{}, fmt.Errorf("unsupported intercept %q", intercept)
+ }
+ }
+
+ if !opts.Observe && !opts.InterceptLLM && !opts.InterceptTool && !opts.ApproveTool {
+ return ProcessHookOptions{}, fmt.Errorf("no hook modes enabled")
+ }
+
+ return opts, nil
+}
+
+func processHookEnvFromMap(envMap map[string]string) []string {
+ if len(envMap) == 0 {
+ return nil
+ }
+
+ keys := make([]string, 0, len(envMap))
+ for key := range envMap {
+ keys = append(keys, key)
+ }
+ sort.Strings(keys)
+
+ env := make([]string, 0, len(keys))
+ for _, key := range keys {
+ env = append(env, key+"="+envMap[key])
+ }
+ return env
+}
+
+func processHookObserveKindsFromConfig(observe []string) ([]string, bool, error) {
+ if len(observe) == 0 {
+ return nil, false, nil
+ }
+
+ validKinds := validHookEventKinds()
+ normalized := make([]string, 0, len(observe))
+ for _, kind := range observe {
+ switch kind {
+ case "", "*", "all":
+ return nil, true, nil
+ default:
+ if _, ok := validKinds[kind]; !ok {
+ return nil, false, fmt.Errorf("unsupported observe event %q", kind)
+ }
+ normalized = append(normalized, kind)
+ }
+ }
+
+ if len(normalized) == 0 {
+ return nil, false, nil
+ }
+ return normalized, true, nil
+}
+
+func validHookEventKinds() map[string]struct{} {
+ kinds := make(map[string]struct{}, int(eventKindCount))
+ for kind := EventKind(0); kind < eventKindCount; kind++ {
+ kinds[kind.String()] = struct{}{}
+ }
+ return kinds
+}
diff --git a/pkg/agent/hook_mount_test.go b/pkg/agent/hook_mount_test.go
new file mode 100644
index 000000000..85d8f5c11
--- /dev/null
+++ b/pkg/agent/hook_mount_test.go
@@ -0,0 +1,179 @@
+package agent
+
+import (
+ "context"
+ "encoding/json"
+ "path/filepath"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+type builtinAutoHookConfig struct {
+ Model string `json:"model"`
+ Suffix string `json:"suffix"`
+}
+
+type builtinAutoHook struct {
+ model string
+ suffix string
+}
+
+func (h *builtinAutoHook) BeforeLLM(
+ ctx context.Context,
+ req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+ next := req.Clone()
+ next.Model = h.model
+ return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *builtinAutoHook) AfterLLM(
+ ctx context.Context,
+ resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+ next := resp.Clone()
+ if next.Response != nil {
+ next.Response.Content += h.suffix
+ }
+ return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func newConfiguredHookLoop(t *testing.T, provider *llmHookTestProvider, hooks config.HooksConfig) *AgentLoop {
+ t.Helper()
+
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Workspace: t.TempDir(),
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ Hooks: hooks,
+ }
+
+ return NewAgentLoop(cfg, bus.NewMessageBus(), provider)
+}
+
+func TestAgentLoop_ProcessDirectWithChannel_AutoMountsBuiltinHook(t *testing.T) {
+ const hookName = "test-auto-builtin-hook"
+
+ if err := RegisterBuiltinHook(hookName, func(
+ ctx context.Context,
+ spec config.BuiltinHookConfig,
+ ) (any, error) {
+ var hookCfg builtinAutoHookConfig
+ if len(spec.Config) > 0 {
+ if err := json.Unmarshal(spec.Config, &hookCfg); err != nil {
+ return nil, err
+ }
+ }
+ return &builtinAutoHook{
+ model: hookCfg.Model,
+ suffix: hookCfg.Suffix,
+ }, nil
+ }); err != nil {
+ t.Fatalf("RegisterBuiltinHook failed: %v", err)
+ }
+ t.Cleanup(func() {
+ unregisterBuiltinHook(hookName)
+ })
+
+ rawCfg, err := json.Marshal(builtinAutoHookConfig{
+ Model: "builtin-model",
+ Suffix: "|builtin",
+ })
+ if err != nil {
+ t.Fatalf("json.Marshal failed: %v", err)
+ }
+
+ provider := &llmHookTestProvider{}
+ al := newConfiguredHookLoop(t, provider, config.HooksConfig{
+ Enabled: true,
+ Builtins: map[string]config.BuiltinHookConfig{
+ hookName: {
+ Enabled: true,
+ Config: rawCfg,
+ },
+ },
+ })
+ defer al.Close()
+
+ resp, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct")
+ if err != nil {
+ t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+ }
+ if resp != "provider content|builtin" {
+ t.Fatalf("expected builtin-hooked content, got %q", resp)
+ }
+
+ provider.mu.Lock()
+ lastModel := provider.lastModel
+ provider.mu.Unlock()
+ if lastModel != "builtin-model" {
+ t.Fatalf("expected builtin model, got %q", lastModel)
+ }
+}
+
+func TestAgentLoop_ProcessDirectWithChannel_AutoMountsProcessHook(t *testing.T) {
+ provider := &llmHookTestProvider{}
+ eventLog := filepath.Join(t.TempDir(), "events.log")
+
+ al := newConfiguredHookLoop(t, provider, config.HooksConfig{
+ Enabled: true,
+ Processes: map[string]config.ProcessHookConfig{
+ "ipc-auto": {
+ Enabled: true,
+ Command: processHookHelperCommand(),
+ Env: map[string]string{
+ "PICOCLAW_HOOK_HELPER": "1",
+ "PICOCLAW_HOOK_MODE": "rewrite",
+ "PICOCLAW_HOOK_EVENT_LOG": eventLog,
+ },
+ Observe: []string{"turn_end"},
+ Intercept: []string{"before_llm", "after_llm"},
+ },
+ },
+ })
+ defer al.Close()
+
+ resp, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct")
+ if err != nil {
+ t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+ }
+ if resp != "provider content|ipc" {
+ t.Fatalf("expected process-hooked content, got %q", resp)
+ }
+
+ provider.mu.Lock()
+ lastModel := provider.lastModel
+ provider.mu.Unlock()
+ if lastModel != "process-model" {
+ t.Fatalf("expected process model, got %q", lastModel)
+ }
+
+ waitForFileContains(t, eventLog, "turn_end")
+}
+
+func TestAgentLoop_ProcessDirectWithChannel_InvalidConfiguredHookFails(t *testing.T) {
+ provider := &llmHookTestProvider{}
+ al := newConfiguredHookLoop(t, provider, config.HooksConfig{
+ Enabled: true,
+ Processes: map[string]config.ProcessHookConfig{
+ "bad-hook": {
+ Enabled: true,
+ Command: processHookHelperCommand(),
+ Intercept: []string{"not_supported"},
+ },
+ },
+ })
+ defer al.Close()
+
+ _, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct")
+ if err == nil {
+ t.Fatal("expected invalid configured hook error")
+ }
+}
diff --git a/pkg/agent/hook_process.go b/pkg/agent/hook_process.go
new file mode 100644
index 000000000..e5632913d
--- /dev/null
+++ b/pkg/agent/hook_process.go
@@ -0,0 +1,511 @@
+package agent
+
+import (
+ "bufio"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "os"
+ "os/exec"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
+)
+
+const (
+ processHookJSONRPCVersion = "2.0"
+ processHookReadBufferSize = 1024 * 1024
+ processHookCloseTimeout = 2 * time.Second
+)
+
+type ProcessHookOptions struct {
+ Command []string
+ Dir string
+ Env []string
+ Observe bool
+ ObserveKinds []string
+ InterceptLLM bool
+ InterceptTool bool
+ ApproveTool bool
+}
+
+type ProcessHook struct {
+ name string
+ opts ProcessHookOptions
+
+ cmd *exec.Cmd
+ stdin io.WriteCloser
+ observeKinds map[string]struct{}
+
+ writeMu sync.Mutex
+
+ pendingMu sync.Mutex
+ pending map[uint64]chan processHookRPCMessage
+ nextID atomic.Uint64
+
+ closed atomic.Bool
+ done chan struct{}
+ closeErr error
+ closeMu sync.Mutex
+ closeOnce sync.Once
+}
+
+type processHookRPCMessage struct {
+ JSONRPC string `json:"jsonrpc,omitempty"`
+ ID uint64 `json:"id,omitempty"`
+ Method string `json:"method,omitempty"`
+ Params json.RawMessage `json:"params,omitempty"`
+ Result json.RawMessage `json:"result,omitempty"`
+ Error *processHookRPCError `json:"error,omitempty"`
+}
+
+type processHookRPCError struct {
+ Code int `json:"code"`
+ Message string `json:"message"`
+}
+
+type processHookHelloParams struct {
+ Name string `json:"name"`
+ Version int `json:"version"`
+ Modes []string `json:"modes,omitempty"`
+}
+
+type processHookDecisionResponse struct {
+ Action HookAction `json:"action"`
+ Reason string `json:"reason,omitempty"`
+}
+
+type processHookBeforeLLMResponse struct {
+ processHookDecisionResponse
+ Request *LLMHookRequest `json:"request,omitempty"`
+}
+
+type processHookAfterLLMResponse struct {
+ processHookDecisionResponse
+ Response *LLMHookResponse `json:"response,omitempty"`
+}
+
+type processHookBeforeToolResponse struct {
+ processHookDecisionResponse
+ Call *ToolCallHookRequest `json:"call,omitempty"`
+}
+
+type processHookAfterToolResponse struct {
+ processHookDecisionResponse
+ Result *ToolResultHookResponse `json:"result,omitempty"`
+}
+
+func NewProcessHook(ctx context.Context, name string, opts ProcessHookOptions) (*ProcessHook, error) {
+ if len(opts.Command) == 0 {
+ return nil, fmt.Errorf("process hook command is required")
+ }
+
+ cmd := exec.Command(opts.Command[0], opts.Command[1:]...)
+ cmd.Dir = opts.Dir
+ if len(opts.Env) > 0 {
+ cmd.Env = append(os.Environ(), opts.Env...)
+ }
+ stdin, err := cmd.StdinPipe()
+ if err != nil {
+ return nil, fmt.Errorf("create process hook stdin: %w", err)
+ }
+ stdout, err := cmd.StdoutPipe()
+ if err != nil {
+ return nil, fmt.Errorf("create process hook stdout: %w", err)
+ }
+ stderr, err := cmd.StderrPipe()
+ if err != nil {
+ return nil, fmt.Errorf("create process hook stderr: %w", err)
+ }
+ if err := cmd.Start(); err != nil {
+ return nil, fmt.Errorf("start process hook: %w", err)
+ }
+
+ ph := &ProcessHook{
+ name: name,
+ opts: opts,
+ cmd: cmd,
+ stdin: stdin,
+ observeKinds: newProcessHookObserveKinds(opts.ObserveKinds),
+ pending: make(map[uint64]chan processHookRPCMessage),
+ done: make(chan struct{}),
+ }
+
+ go ph.readLoop(stdout)
+ go ph.readStderr(stderr)
+ go ph.waitLoop()
+
+ helloCtx := ctx
+ if helloCtx == nil {
+ var cancel context.CancelFunc
+ helloCtx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+ }
+ if err := ph.hello(helloCtx); err != nil {
+ _ = ph.Close()
+ return nil, err
+ }
+
+ return ph, nil
+}
+
+func (ph *ProcessHook) Close() error {
+ if ph == nil {
+ return nil
+ }
+
+ ph.closeOnce.Do(func() {
+ ph.closed.Store(true)
+ if ph.stdin != nil {
+ _ = ph.stdin.Close()
+ }
+
+ select {
+ case <-ph.done:
+ case <-time.After(processHookCloseTimeout):
+ if ph.cmd != nil && ph.cmd.Process != nil {
+ _ = ph.cmd.Process.Kill()
+ }
+ <-ph.done
+ }
+ })
+
+ ph.closeMu.Lock()
+ defer ph.closeMu.Unlock()
+ return ph.closeErr
+}
+
+func (ph *ProcessHook) OnEvent(ctx context.Context, evt Event) error {
+ if ph == nil || !ph.opts.Observe {
+ return nil
+ }
+ if len(ph.observeKinds) > 0 {
+ if _, ok := ph.observeKinds[evt.Kind.String()]; !ok {
+ return nil
+ }
+ }
+ return ph.notify(ctx, "hook.event", evt)
+}
+
+func (ph *ProcessHook) BeforeLLM(
+ ctx context.Context,
+ req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+ if ph == nil || !ph.opts.InterceptLLM {
+ return req, HookDecision{Action: HookActionContinue}, nil
+ }
+
+ var resp processHookBeforeLLMResponse
+ if err := ph.call(ctx, "hook.before_llm", req, &resp); err != nil {
+ return nil, HookDecision{}, err
+ }
+ if resp.Request == nil {
+ resp.Request = req
+ }
+ return resp.Request, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil
+}
+
+func (ph *ProcessHook) AfterLLM(
+ ctx context.Context,
+ resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+ if ph == nil || !ph.opts.InterceptLLM {
+ return resp, HookDecision{Action: HookActionContinue}, nil
+ }
+
+ var result processHookAfterLLMResponse
+ if err := ph.call(ctx, "hook.after_llm", resp, &result); err != nil {
+ return nil, HookDecision{}, err
+ }
+ if result.Response == nil {
+ result.Response = resp
+ }
+ return result.Response, HookDecision{Action: result.Action, Reason: result.Reason}, nil
+}
+
+func (ph *ProcessHook) BeforeTool(
+ ctx context.Context,
+ call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision, error) {
+ if ph == nil || !ph.opts.InterceptTool {
+ return call, HookDecision{Action: HookActionContinue}, nil
+ }
+
+ var resp processHookBeforeToolResponse
+ if err := ph.call(ctx, "hook.before_tool", call, &resp); err != nil {
+ return nil, HookDecision{}, err
+ }
+ if resp.Call == nil {
+ resp.Call = call
+ }
+ return resp.Call, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil
+}
+
+func (ph *ProcessHook) AfterTool(
+ ctx context.Context,
+ result *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision, error) {
+ if ph == nil || !ph.opts.InterceptTool {
+ return result, HookDecision{Action: HookActionContinue}, nil
+ }
+
+ var resp processHookAfterToolResponse
+ if err := ph.call(ctx, "hook.after_tool", result, &resp); err != nil {
+ return nil, HookDecision{}, err
+ }
+ if resp.Result == nil {
+ resp.Result = result
+ }
+ return resp.Result, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil
+}
+
+func (ph *ProcessHook) ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error) {
+ if ph == nil || !ph.opts.ApproveTool {
+ return ApprovalDecision{Approved: true}, nil
+ }
+
+ var resp ApprovalDecision
+ if err := ph.call(ctx, "hook.approve_tool", req, &resp); err != nil {
+ return ApprovalDecision{}, err
+ }
+ return resp, nil
+}
+
+func (ph *ProcessHook) hello(ctx context.Context) error {
+ modes := make([]string, 0, 4)
+ if ph.opts.Observe {
+ modes = append(modes, "observe")
+ }
+ if ph.opts.InterceptLLM {
+ modes = append(modes, "llm")
+ }
+ if ph.opts.InterceptTool {
+ modes = append(modes, "tool")
+ }
+ if ph.opts.ApproveTool {
+ modes = append(modes, "approve")
+ }
+
+ var result map[string]any
+ return ph.call(ctx, "hook.hello", processHookHelloParams{
+ Name: ph.name,
+ Version: 1,
+ Modes: modes,
+ }, &result)
+}
+
+func (ph *ProcessHook) notify(ctx context.Context, method string, params any) error {
+ msg := processHookRPCMessage{
+ JSONRPC: processHookJSONRPCVersion,
+ Method: method,
+ }
+ if params != nil {
+ body, err := json.Marshal(params)
+ if err != nil {
+ return err
+ }
+ msg.Params = body
+ }
+ return ph.send(ctx, msg)
+}
+
+func (ph *ProcessHook) call(ctx context.Context, method string, params any, out any) error {
+ if ph.closed.Load() {
+ return fmt.Errorf("process hook %q is closed", ph.name)
+ }
+
+ id := ph.nextID.Add(1)
+ respCh := make(chan processHookRPCMessage, 1)
+ ph.pendingMu.Lock()
+ ph.pending[id] = respCh
+ ph.pendingMu.Unlock()
+
+ msg := processHookRPCMessage{
+ JSONRPC: processHookJSONRPCVersion,
+ ID: id,
+ Method: method,
+ }
+ if params != nil {
+ body, err := json.Marshal(params)
+ if err != nil {
+ ph.removePending(id)
+ return err
+ }
+ msg.Params = body
+ }
+
+ if err := ph.send(ctx, msg); err != nil {
+ ph.removePending(id)
+ return err
+ }
+
+ select {
+ case resp, ok := <-respCh:
+ if !ok {
+ return fmt.Errorf("process hook %q closed while waiting for %s", ph.name, method)
+ }
+ if resp.Error != nil {
+ return fmt.Errorf("process hook %q %s failed: %s", ph.name, method, resp.Error.Message)
+ }
+ if out != nil && len(resp.Result) > 0 {
+ if err := json.Unmarshal(resp.Result, out); err != nil {
+ return fmt.Errorf("decode process hook %q %s result: %w", ph.name, method, err)
+ }
+ }
+ return nil
+ case <-ctx.Done():
+ ph.removePending(id)
+ return ctx.Err()
+ }
+}
+
+func (ph *ProcessHook) send(ctx context.Context, msg processHookRPCMessage) error {
+ body, err := json.Marshal(msg)
+ if err != nil {
+ return err
+ }
+ body = append(body, '\n')
+
+ ph.writeMu.Lock()
+ defer ph.writeMu.Unlock()
+
+ if ph.closed.Load() {
+ return fmt.Errorf("process hook %q is closed", ph.name)
+ }
+
+ done := make(chan error, 1)
+ go func() {
+ _, writeErr := ph.stdin.Write(body)
+ done <- writeErr
+ }()
+
+ select {
+ case err := <-done:
+ if err != nil {
+ return fmt.Errorf("write process hook %q message: %w", ph.name, err)
+ }
+ return nil
+ case <-ctx.Done():
+ return ctx.Err()
+ }
+}
+
+func (ph *ProcessHook) readLoop(stdout io.Reader) {
+ scanner := bufio.NewScanner(stdout)
+ scanner.Buffer(make([]byte, 0, 64*1024), processHookReadBufferSize)
+
+ for scanner.Scan() {
+ var msg processHookRPCMessage
+ if err := json.Unmarshal(scanner.Bytes(), &msg); err != nil {
+ logger.WarnCF("hooks", "Failed to decode process hook message", map[string]any{
+ "hook": ph.name,
+ "error": err.Error(),
+ })
+ continue
+ }
+ if msg.ID == 0 {
+ continue
+ }
+ ph.pendingMu.Lock()
+ respCh, ok := ph.pending[msg.ID]
+ if ok {
+ delete(ph.pending, msg.ID)
+ }
+ ph.pendingMu.Unlock()
+ if ok {
+ respCh <- msg
+ close(respCh)
+ }
+ }
+}
+
+func (ph *ProcessHook) readStderr(stderr io.Reader) {
+ scanner := bufio.NewScanner(stderr)
+ scanner.Buffer(make([]byte, 0, 16*1024), processHookReadBufferSize)
+ for scanner.Scan() {
+ logger.WarnCF("hooks", "Process hook stderr", map[string]any{
+ "hook": ph.name,
+ "stderr": scanner.Text(),
+ })
+ }
+}
+
+func (ph *ProcessHook) waitLoop() {
+ err := ph.cmd.Wait()
+ ph.closeMu.Lock()
+ ph.closeErr = err
+ ph.closeMu.Unlock()
+ ph.failPending(err)
+ close(ph.done)
+}
+
+func (ph *ProcessHook) failPending(err error) {
+ ph.pendingMu.Lock()
+ defer ph.pendingMu.Unlock()
+
+ msg := processHookRPCMessage{
+ Error: &processHookRPCError{
+ Code: -32000,
+ Message: "process exited",
+ },
+ }
+ if err != nil {
+ msg.Error.Message = err.Error()
+ }
+
+ for id, ch := range ph.pending {
+ delete(ph.pending, id)
+ ch <- msg
+ close(ch)
+ }
+}
+
+func (ph *ProcessHook) removePending(id uint64) {
+ ph.pendingMu.Lock()
+ defer ph.pendingMu.Unlock()
+
+ if ch, ok := ph.pending[id]; ok {
+ delete(ph.pending, id)
+ close(ch)
+ }
+}
+
+func (al *AgentLoop) MountProcessHook(ctx context.Context, name string, opts ProcessHookOptions) error {
+ if al == nil {
+ return fmt.Errorf("agent loop is nil")
+ }
+ processHook, err := NewProcessHook(ctx, name, opts)
+ if err != nil {
+ return err
+ }
+ if err := al.MountHook(HookRegistration{
+ Name: name,
+ Source: HookSourceProcess,
+ Hook: processHook,
+ }); err != nil {
+ _ = processHook.Close()
+ return err
+ }
+ return nil
+}
+
+func newProcessHookObserveKinds(kinds []string) map[string]struct{} {
+ if len(kinds) == 0 {
+ return nil
+ }
+
+ normalized := make(map[string]struct{}, len(kinds))
+ for _, kind := range kinds {
+ if kind == "" {
+ continue
+ }
+ normalized[kind] = struct{}{}
+ }
+ if len(normalized) == 0 {
+ return nil
+ }
+ return normalized
+}
diff --git a/pkg/agent/hook_process_test.go b/pkg/agent/hook_process_test.go
new file mode 100644
index 000000000..50f89811f
--- /dev/null
+++ b/pkg/agent/hook_process_test.go
@@ -0,0 +1,339 @@
+package agent
+
+import (
+ "bufio"
+ "context"
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func TestProcessHook_HelperProcess(t *testing.T) {
+ if os.Getenv("PICOCLAW_HOOK_HELPER") != "1" {
+ return
+ }
+ if err := runProcessHookHelper(); err != nil {
+ fmt.Fprintln(os.Stderr, err.Error())
+ os.Exit(1)
+ }
+ os.Exit(0)
+}
+
+func TestAgentLoop_MountProcessHook_LLMAndObserver(t *testing.T) {
+ provider := &llmHookTestProvider{}
+ al, agent, cleanup := newHookTestLoop(t, provider)
+ defer cleanup()
+
+ eventLog := filepath.Join(t.TempDir(), "events.log")
+ if err := al.MountProcessHook(context.Background(), "ipc-llm", ProcessHookOptions{
+ Command: processHookHelperCommand(),
+ Env: processHookHelperEnv("rewrite", eventLog),
+ Observe: true,
+ InterceptLLM: true,
+ }); err != nil {
+ t.Fatalf("MountProcessHook failed: %v", err)
+ }
+
+ resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "hello",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+ if resp != "provider content|ipc" {
+ t.Fatalf("expected process-hooked llm content, got %q", resp)
+ }
+
+ provider.mu.Lock()
+ lastModel := provider.lastModel
+ provider.mu.Unlock()
+ if lastModel != "process-model" {
+ t.Fatalf("expected process model, got %q", lastModel)
+ }
+
+ waitForFileContains(t, eventLog, "turn_end")
+}
+
+func TestAgentLoop_MountProcessHook_ToolRewrite(t *testing.T) {
+ provider := &toolHookProvider{}
+ al, agent, cleanup := newHookTestLoop(t, provider)
+ defer cleanup()
+
+ al.RegisterTool(&echoTextTool{})
+ if err := al.MountProcessHook(context.Background(), "ipc-tool", ProcessHookOptions{
+ Command: processHookHelperCommand(),
+ Env: processHookHelperEnv("rewrite", ""),
+ InterceptTool: true,
+ }); err != nil {
+ t.Fatalf("MountProcessHook failed: %v", err)
+ }
+
+ resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "run tool",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+ if resp != "ipc:ipc" {
+ t.Fatalf("expected rewritten process-hook tool result, got %q", resp)
+ }
+}
+
+type blockedToolProvider struct {
+ calls int
+}
+
+func (p *blockedToolProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ p.calls++
+ if p.calls == 1 {
+ return &providers.LLMResponse{
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "call-1",
+ Name: "blocked_tool",
+ Arguments: map[string]any{},
+ },
+ },
+ }, nil
+ }
+
+ return &providers.LLMResponse{
+ Content: messages[len(messages)-1].Content,
+ }, nil
+}
+
+func (p *blockedToolProvider) GetDefaultModel() string {
+ return "blocked-tool-provider"
+}
+
+func TestAgentLoop_MountProcessHook_ApprovalDeny(t *testing.T) {
+ provider := &blockedToolProvider{}
+ al, agent, cleanup := newHookTestLoop(t, provider)
+ defer cleanup()
+
+ if err := al.MountProcessHook(context.Background(), "ipc-approval", ProcessHookOptions{
+ Command: processHookHelperCommand(),
+ Env: processHookHelperEnv("deny", ""),
+ ApproveTool: true,
+ }); err != nil {
+ t.Fatalf("MountProcessHook failed: %v", err)
+ }
+
+ sub := al.SubscribeEvents(16)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "run blocked tool",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+
+ expected := "Tool execution denied by approval hook: blocked by ipc hook"
+ if resp != expected {
+ t.Fatalf("expected %q, got %q", expected, resp)
+ }
+
+ events := collectEventStream(sub.C)
+ skippedEvt, ok := findEvent(events, EventKindToolExecSkipped)
+ if !ok {
+ t.Fatal("expected tool skipped event")
+ }
+ payload, ok := skippedEvt.Payload.(ToolExecSkippedPayload)
+ if !ok {
+ t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload)
+ }
+ if payload.Reason != expected {
+ t.Fatalf("expected reason %q, got %q", expected, payload.Reason)
+ }
+}
+
+func processHookHelperCommand() []string {
+ return []string{os.Args[0], "-test.run=TestProcessHook_HelperProcess", "--"}
+}
+
+func processHookHelperEnv(mode, eventLog string) []string {
+ env := []string{
+ "PICOCLAW_HOOK_HELPER=1",
+ "PICOCLAW_HOOK_MODE=" + mode,
+ }
+ if eventLog != "" {
+ env = append(env, "PICOCLAW_HOOK_EVENT_LOG="+eventLog)
+ }
+ return env
+}
+
+func waitForFileContains(t *testing.T, path, substring string) {
+ t.Helper()
+
+ deadline := time.Now().Add(3 * time.Second)
+ for time.Now().Before(deadline) {
+ data, err := os.ReadFile(path)
+ if err == nil && strings.Contains(string(data), substring) {
+ return
+ }
+ time.Sleep(20 * time.Millisecond)
+ }
+
+ data, _ := os.ReadFile(path)
+ t.Fatalf("timed out waiting for %q in %s; current content: %q", substring, path, string(data))
+}
+
+func runProcessHookHelper() error {
+ mode := os.Getenv("PICOCLAW_HOOK_MODE")
+ eventLog := os.Getenv("PICOCLAW_HOOK_EVENT_LOG")
+
+ scanner := bufio.NewScanner(os.Stdin)
+ scanner.Buffer(make([]byte, 0, 64*1024), processHookReadBufferSize)
+ encoder := json.NewEncoder(os.Stdout)
+
+ for scanner.Scan() {
+ var msg processHookRPCMessage
+ if err := json.Unmarshal(scanner.Bytes(), &msg); err != nil {
+ return err
+ }
+
+ if msg.ID == 0 {
+ if msg.Method == "hook.event" && eventLog != "" {
+ var evt map[string]any
+ if err := json.Unmarshal(msg.Params, &evt); err == nil {
+ if rawKind, ok := evt["Kind"].(float64); ok {
+ kind := EventKind(rawKind)
+ _ = os.WriteFile(eventLog, []byte(kind.String()+"\n"), 0o644)
+ }
+ }
+ }
+ continue
+ }
+
+ result, rpcErr := handleProcessHookRequest(mode, msg)
+ resp := processHookRPCMessage{
+ JSONRPC: processHookJSONRPCVersion,
+ ID: msg.ID,
+ }
+ if rpcErr != nil {
+ resp.Error = rpcErr
+ } else if result != nil {
+ body, err := json.Marshal(result)
+ if err != nil {
+ return err
+ }
+ resp.Result = body
+ } else {
+ resp.Result = []byte("{}")
+ }
+
+ if err := encoder.Encode(resp); err != nil {
+ return err
+ }
+ }
+
+ return scanner.Err()
+}
+
+func handleProcessHookRequest(mode string, msg processHookRPCMessage) (any, *processHookRPCError) {
+ switch msg.Method {
+ case "hook.hello":
+ return map[string]any{"ok": true}, nil
+ case "hook.before_llm":
+ if mode != "rewrite" {
+ return map[string]any{"action": HookActionContinue}, nil
+ }
+ var req map[string]any
+ _ = json.Unmarshal(msg.Params, &req)
+ req["model"] = "process-model"
+ return map[string]any{
+ "action": HookActionModify,
+ "request": req,
+ }, nil
+ case "hook.after_llm":
+ if mode != "rewrite" {
+ return map[string]any{"action": HookActionContinue}, nil
+ }
+ var resp map[string]any
+ _ = json.Unmarshal(msg.Params, &resp)
+ if rawResponse, ok := resp["response"].(map[string]any); ok {
+ if content, ok := rawResponse["content"].(string); ok {
+ rawResponse["content"] = content + "|ipc"
+ }
+ }
+ return map[string]any{
+ "action": HookActionModify,
+ "response": resp,
+ }, nil
+ case "hook.before_tool":
+ if mode != "rewrite" {
+ return map[string]any{"action": HookActionContinue}, nil
+ }
+ var call map[string]any
+ _ = json.Unmarshal(msg.Params, &call)
+ rawArgs, ok := call["arguments"].(map[string]any)
+ if !ok || rawArgs == nil {
+ rawArgs = map[string]any{}
+ }
+ rawArgs["text"] = "ipc"
+ call["arguments"] = rawArgs
+ return map[string]any{
+ "action": HookActionModify,
+ "call": call,
+ }, nil
+ case "hook.after_tool":
+ if mode != "rewrite" {
+ return map[string]any{"action": HookActionContinue}, nil
+ }
+ var result map[string]any
+ _ = json.Unmarshal(msg.Params, &result)
+ if rawResult, ok := result["result"].(map[string]any); ok {
+ if forLLM, ok := rawResult["for_llm"].(string); ok {
+ rawResult["for_llm"] = "ipc:" + forLLM
+ }
+ }
+ return map[string]any{
+ "action": HookActionModify,
+ "result": result,
+ }, nil
+ case "hook.approve_tool":
+ if mode == "deny" {
+ return ApprovalDecision{
+ Approved: false,
+ Reason: "blocked by ipc hook",
+ }, nil
+ }
+ return ApprovalDecision{Approved: true}, nil
+ default:
+ return nil, &processHookRPCError{
+ Code: -32601,
+ Message: "method not found",
+ }
+ }
+}
diff --git a/pkg/agent/hooks.go b/pkg/agent/hooks.go
new file mode 100644
index 000000000..c1ef58ffd
--- /dev/null
+++ b/pkg/agent/hooks.go
@@ -0,0 +1,809 @@
+package agent
+
+import (
+ "context"
+ "fmt"
+ "io"
+ "sort"
+ "sync"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/tools"
+)
+
+const (
+ defaultHookObserverTimeout = 500 * time.Millisecond
+ defaultHookInterceptorTimeout = 5 * time.Second
+ defaultHookApprovalTimeout = 60 * time.Second
+ hookObserverBufferSize = 64
+)
+
+type HookAction string
+
+const (
+ HookActionContinue HookAction = "continue"
+ HookActionModify HookAction = "modify"
+ HookActionDenyTool HookAction = "deny_tool"
+ HookActionAbortTurn HookAction = "abort_turn"
+ HookActionHardAbort HookAction = "hard_abort"
+)
+
+type HookDecision struct {
+ Action HookAction `json:"action"`
+ Reason string `json:"reason,omitempty"`
+}
+
+func (d HookDecision) normalizedAction() HookAction {
+ if d.Action == "" {
+ return HookActionContinue
+ }
+ return d.Action
+}
+
+type ApprovalDecision struct {
+ Approved bool `json:"approved"`
+ Reason string `json:"reason,omitempty"`
+}
+
+type HookSource uint8
+
+const (
+ HookSourceInProcess HookSource = iota
+ HookSourceProcess
+)
+
+type HookRegistration struct {
+ Name string
+ Priority int
+ Source HookSource
+ Hook any
+}
+
+func NamedHook(name string, hook any) HookRegistration {
+ return HookRegistration{
+ Name: name,
+ Source: HookSourceInProcess,
+ Hook: hook,
+ }
+}
+
+type EventObserver interface {
+ OnEvent(ctx context.Context, evt Event) error
+}
+
+type LLMInterceptor interface {
+ BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLMHookRequest, HookDecision, error)
+ AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LLMHookResponse, HookDecision, error)
+}
+
+type ToolInterceptor interface {
+ BeforeTool(ctx context.Context, call *ToolCallHookRequest) (*ToolCallHookRequest, HookDecision, error)
+ AfterTool(ctx context.Context, result *ToolResultHookResponse) (*ToolResultHookResponse, HookDecision, error)
+}
+
+type ToolApprover interface {
+ ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error)
+}
+
+type LLMHookRequest struct {
+ Meta EventMeta `json:"meta"`
+ Model string `json:"model"`
+ Messages []providers.Message `json:"messages,omitempty"`
+ Tools []providers.ToolDefinition `json:"tools,omitempty"`
+ Options map[string]any `json:"options,omitempty"`
+ Channel string `json:"channel,omitempty"`
+ ChatID string `json:"chat_id,omitempty"`
+ GracefulTerminal bool `json:"graceful_terminal,omitempty"`
+}
+
+func (r *LLMHookRequest) Clone() *LLMHookRequest {
+ if r == nil {
+ return nil
+ }
+ cloned := *r
+ cloned.Messages = cloneProviderMessages(r.Messages)
+ cloned.Tools = cloneToolDefinitions(r.Tools)
+ cloned.Options = cloneStringAnyMap(r.Options)
+ return &cloned
+}
+
+type LLMHookResponse struct {
+ Meta EventMeta `json:"meta"`
+ Model string `json:"model"`
+ Response *providers.LLMResponse `json:"response,omitempty"`
+ Channel string `json:"channel,omitempty"`
+ ChatID string `json:"chat_id,omitempty"`
+}
+
+func (r *LLMHookResponse) Clone() *LLMHookResponse {
+ if r == nil {
+ return nil
+ }
+ cloned := *r
+ cloned.Response = cloneLLMResponse(r.Response)
+ return &cloned
+}
+
+type ToolCallHookRequest struct {
+ Meta EventMeta `json:"meta"`
+ Tool string `json:"tool"`
+ Arguments map[string]any `json:"arguments,omitempty"`
+ Channel string `json:"channel,omitempty"`
+ ChatID string `json:"chat_id,omitempty"`
+}
+
+func (r *ToolCallHookRequest) Clone() *ToolCallHookRequest {
+ if r == nil {
+ return nil
+ }
+ cloned := *r
+ cloned.Arguments = cloneStringAnyMap(r.Arguments)
+ return &cloned
+}
+
+type ToolApprovalRequest struct {
+ Meta EventMeta `json:"meta"`
+ Tool string `json:"tool"`
+ Arguments map[string]any `json:"arguments,omitempty"`
+ Channel string `json:"channel,omitempty"`
+ ChatID string `json:"chat_id,omitempty"`
+}
+
+func (r *ToolApprovalRequest) Clone() *ToolApprovalRequest {
+ if r == nil {
+ return nil
+ }
+ cloned := *r
+ cloned.Arguments = cloneStringAnyMap(r.Arguments)
+ return &cloned
+}
+
+type ToolResultHookResponse struct {
+ Meta EventMeta `json:"meta"`
+ Tool string `json:"tool"`
+ Arguments map[string]any `json:"arguments,omitempty"`
+ Result *tools.ToolResult `json:"result,omitempty"`
+ Duration time.Duration `json:"duration"`
+ Channel string `json:"channel,omitempty"`
+ ChatID string `json:"chat_id,omitempty"`
+}
+
+func (r *ToolResultHookResponse) Clone() *ToolResultHookResponse {
+ if r == nil {
+ return nil
+ }
+ cloned := *r
+ cloned.Arguments = cloneStringAnyMap(r.Arguments)
+ cloned.Result = cloneToolResult(r.Result)
+ return &cloned
+}
+
+type HookManager struct {
+ eventBus *EventBus
+ observerTimeout time.Duration
+ interceptorTimeout time.Duration
+ approvalTimeout time.Duration
+
+ mu sync.RWMutex
+ hooks map[string]HookRegistration
+ ordered []HookRegistration
+
+ sub EventSubscription
+ done chan struct{}
+ closeOnce sync.Once
+}
+
+func NewHookManager(eventBus *EventBus) *HookManager {
+ hm := &HookManager{
+ eventBus: eventBus,
+ observerTimeout: defaultHookObserverTimeout,
+ interceptorTimeout: defaultHookInterceptorTimeout,
+ approvalTimeout: defaultHookApprovalTimeout,
+ hooks: make(map[string]HookRegistration),
+ done: make(chan struct{}),
+ }
+
+ if eventBus == nil {
+ close(hm.done)
+ return hm
+ }
+
+ hm.sub = eventBus.Subscribe(hookObserverBufferSize)
+ go hm.dispatchEvents()
+ return hm
+}
+
+func (hm *HookManager) Close() {
+ if hm == nil {
+ return
+ }
+
+ hm.closeOnce.Do(func() {
+ if hm.eventBus != nil {
+ hm.eventBus.Unsubscribe(hm.sub.ID)
+ }
+ <-hm.done
+ hm.closeAllHooks()
+ })
+}
+
+func (hm *HookManager) ConfigureTimeouts(observer, interceptor, approval time.Duration) {
+ if hm == nil {
+ return
+ }
+ if observer > 0 {
+ hm.observerTimeout = observer
+ }
+ if interceptor > 0 {
+ hm.interceptorTimeout = interceptor
+ }
+ if approval > 0 {
+ hm.approvalTimeout = approval
+ }
+}
+
+func (hm *HookManager) Mount(reg HookRegistration) error {
+ if hm == nil {
+ return fmt.Errorf("hook manager is nil")
+ }
+ if reg.Name == "" {
+ return fmt.Errorf("hook name is required")
+ }
+ if reg.Hook == nil {
+ return fmt.Errorf("hook %q is nil", reg.Name)
+ }
+
+ hm.mu.Lock()
+ defer hm.mu.Unlock()
+
+ if existing, ok := hm.hooks[reg.Name]; ok {
+ closeHookIfPossible(existing.Hook)
+ }
+ hm.hooks[reg.Name] = reg
+ hm.rebuildOrdered()
+ return nil
+}
+
+func (hm *HookManager) Unmount(name string) {
+ if hm == nil || name == "" {
+ return
+ }
+
+ hm.mu.Lock()
+ defer hm.mu.Unlock()
+
+ if existing, ok := hm.hooks[name]; ok {
+ closeHookIfPossible(existing.Hook)
+ }
+ delete(hm.hooks, name)
+ hm.rebuildOrdered()
+}
+
+func (hm *HookManager) dispatchEvents() {
+ defer close(hm.done)
+
+ for evt := range hm.sub.C {
+ for _, reg := range hm.snapshotHooks() {
+ observer, ok := reg.Hook.(EventObserver)
+ if !ok {
+ continue
+ }
+ hm.runObserver(reg.Name, observer, evt)
+ }
+ }
+}
+
+func (hm *HookManager) BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLMHookRequest, HookDecision) {
+ if hm == nil || req == nil {
+ return req, HookDecision{Action: HookActionContinue}
+ }
+
+ current := req.Clone()
+ for _, reg := range hm.snapshotHooks() {
+ interceptor, ok := reg.Hook.(LLMInterceptor)
+ if !ok {
+ continue
+ }
+
+ next, decision, ok := hm.callBeforeLLM(ctx, reg.Name, interceptor, current.Clone())
+ if !ok {
+ continue
+ }
+
+ switch decision.normalizedAction() {
+ case HookActionContinue, HookActionModify:
+ if next != nil {
+ current = next
+ }
+ case HookActionAbortTurn, HookActionHardAbort:
+ return current, decision
+ default:
+ hm.logUnsupportedAction(reg.Name, "before_llm", decision.Action)
+ }
+ }
+ return current, HookDecision{Action: HookActionContinue}
+}
+
+func (hm *HookManager) AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LLMHookResponse, HookDecision) {
+ if hm == nil || resp == nil {
+ return resp, HookDecision{Action: HookActionContinue}
+ }
+
+ current := resp.Clone()
+ for _, reg := range hm.snapshotHooks() {
+ interceptor, ok := reg.Hook.(LLMInterceptor)
+ if !ok {
+ continue
+ }
+
+ next, decision, ok := hm.callAfterLLM(ctx, reg.Name, interceptor, current.Clone())
+ if !ok {
+ continue
+ }
+
+ switch decision.normalizedAction() {
+ case HookActionContinue, HookActionModify:
+ if next != nil {
+ current = next
+ }
+ case HookActionAbortTurn, HookActionHardAbort:
+ return current, decision
+ default:
+ hm.logUnsupportedAction(reg.Name, "after_llm", decision.Action)
+ }
+ }
+ return current, HookDecision{Action: HookActionContinue}
+}
+
+func (hm *HookManager) BeforeTool(
+ ctx context.Context,
+ call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision) {
+ if hm == nil || call == nil {
+ return call, HookDecision{Action: HookActionContinue}
+ }
+
+ current := call.Clone()
+ for _, reg := range hm.snapshotHooks() {
+ interceptor, ok := reg.Hook.(ToolInterceptor)
+ if !ok {
+ continue
+ }
+
+ next, decision, ok := hm.callBeforeTool(ctx, reg.Name, interceptor, current.Clone())
+ if !ok {
+ continue
+ }
+
+ switch decision.normalizedAction() {
+ case HookActionContinue, HookActionModify:
+ if next != nil {
+ current = next
+ }
+ case HookActionDenyTool, HookActionAbortTurn, HookActionHardAbort:
+ return current, decision
+ default:
+ hm.logUnsupportedAction(reg.Name, "before_tool", decision.Action)
+ }
+ }
+ return current, HookDecision{Action: HookActionContinue}
+}
+
+func (hm *HookManager) AfterTool(
+ ctx context.Context,
+ result *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision) {
+ if hm == nil || result == nil {
+ return result, HookDecision{Action: HookActionContinue}
+ }
+
+ current := result.Clone()
+ for _, reg := range hm.snapshotHooks() {
+ interceptor, ok := reg.Hook.(ToolInterceptor)
+ if !ok {
+ continue
+ }
+
+ next, decision, ok := hm.callAfterTool(ctx, reg.Name, interceptor, current.Clone())
+ if !ok {
+ continue
+ }
+
+ switch decision.normalizedAction() {
+ case HookActionContinue, HookActionModify:
+ if next != nil {
+ current = next
+ }
+ case HookActionAbortTurn, HookActionHardAbort:
+ return current, decision
+ default:
+ hm.logUnsupportedAction(reg.Name, "after_tool", decision.Action)
+ }
+ }
+ return current, HookDecision{Action: HookActionContinue}
+}
+
+func (hm *HookManager) ApproveTool(ctx context.Context, req *ToolApprovalRequest) ApprovalDecision {
+ if hm == nil || req == nil {
+ return ApprovalDecision{Approved: true}
+ }
+
+ for _, reg := range hm.snapshotHooks() {
+ approver, ok := reg.Hook.(ToolApprover)
+ if !ok {
+ continue
+ }
+
+ decision, ok := hm.callApproveTool(ctx, reg.Name, approver, req.Clone())
+ if !ok {
+ return ApprovalDecision{
+ Approved: false,
+ Reason: fmt.Sprintf("tool approval hook %q failed", reg.Name),
+ }
+ }
+ if !decision.Approved {
+ return decision
+ }
+ }
+
+ return ApprovalDecision{Approved: true}
+}
+
+func (hm *HookManager) rebuildOrdered() {
+ hm.ordered = hm.ordered[:0]
+ for _, reg := range hm.hooks {
+ hm.ordered = append(hm.ordered, reg)
+ }
+ sort.SliceStable(hm.ordered, func(i, j int) bool {
+ if hm.ordered[i].Source != hm.ordered[j].Source {
+ return hm.ordered[i].Source < hm.ordered[j].Source
+ }
+ if hm.ordered[i].Priority == hm.ordered[j].Priority {
+ return hm.ordered[i].Name < hm.ordered[j].Name
+ }
+ return hm.ordered[i].Priority < hm.ordered[j].Priority
+ })
+}
+
+func (hm *HookManager) snapshotHooks() []HookRegistration {
+ hm.mu.RLock()
+ defer hm.mu.RUnlock()
+
+ snapshot := make([]HookRegistration, len(hm.ordered))
+ copy(snapshot, hm.ordered)
+ return snapshot
+}
+
+func (hm *HookManager) closeAllHooks() {
+ hm.mu.Lock()
+ defer hm.mu.Unlock()
+
+ for name, reg := range hm.hooks {
+ closeHookIfPossible(reg.Hook)
+ delete(hm.hooks, name)
+ }
+ hm.ordered = nil
+}
+
+func (hm *HookManager) runObserver(name string, observer EventObserver, evt Event) {
+ ctx, cancel := context.WithTimeout(context.Background(), hm.observerTimeout)
+ defer cancel()
+
+ done := make(chan error, 1)
+ go func() {
+ done <- observer.OnEvent(ctx, evt)
+ }()
+
+ select {
+ case err := <-done:
+ if err != nil {
+ logger.WarnCF("hooks", "Event observer failed", map[string]any{
+ "hook": name,
+ "event": evt.Kind.String(),
+ "error": err.Error(),
+ })
+ }
+ case <-ctx.Done():
+ logger.WarnCF("hooks", "Event observer timed out", map[string]any{
+ "hook": name,
+ "event": evt.Kind.String(),
+ "timeout_ms": hm.observerTimeout.Milliseconds(),
+ })
+ }
+}
+
+func (hm *HookManager) callBeforeLLM(
+ parent context.Context,
+ name string,
+ interceptor LLMInterceptor,
+ req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, bool) {
+ return runInterceptorHook(
+ parent,
+ hm.interceptorTimeout,
+ name,
+ "before_llm",
+ func(ctx context.Context) (*LLMHookRequest, HookDecision, error) {
+ return interceptor.BeforeLLM(ctx, req)
+ },
+ )
+}
+
+func (hm *HookManager) callAfterLLM(
+ parent context.Context,
+ name string,
+ interceptor LLMInterceptor,
+ resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, bool) {
+ return runInterceptorHook(
+ parent,
+ hm.interceptorTimeout,
+ name,
+ "after_llm",
+ func(ctx context.Context) (*LLMHookResponse, HookDecision, error) {
+ return interceptor.AfterLLM(ctx, resp)
+ },
+ )
+}
+
+func (hm *HookManager) callBeforeTool(
+ parent context.Context,
+ name string,
+ interceptor ToolInterceptor,
+ call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision, bool) {
+ return runInterceptorHook(
+ parent,
+ hm.interceptorTimeout,
+ name,
+ "before_tool",
+ func(ctx context.Context) (*ToolCallHookRequest, HookDecision, error) {
+ return interceptor.BeforeTool(ctx, call)
+ },
+ )
+}
+
+func (hm *HookManager) callAfterTool(
+ parent context.Context,
+ name string,
+ interceptor ToolInterceptor,
+ resultView *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision, bool) {
+ return runInterceptorHook(
+ parent,
+ hm.interceptorTimeout,
+ name,
+ "after_tool",
+ func(ctx context.Context) (*ToolResultHookResponse, HookDecision, error) {
+ return interceptor.AfterTool(ctx, resultView)
+ },
+ )
+}
+
+func (hm *HookManager) callApproveTool(
+ parent context.Context,
+ name string,
+ approver ToolApprover,
+ req *ToolApprovalRequest,
+) (ApprovalDecision, bool) {
+ return runApprovalHook(
+ parent,
+ hm.approvalTimeout,
+ name,
+ "approve_tool",
+ func(ctx context.Context) (ApprovalDecision, error) {
+ return approver.ApproveTool(ctx, req)
+ },
+ )
+}
+
+func runInterceptorHook[T any](
+ parent context.Context,
+ timeout time.Duration,
+ name string,
+ stage string,
+ fn func(ctx context.Context) (T, HookDecision, error),
+) (T, HookDecision, bool) {
+ var zero T
+
+ ctx, cancel := context.WithTimeout(parent, timeout)
+ defer cancel()
+
+ type result struct {
+ value T
+ decision HookDecision
+ err error
+ }
+ done := make(chan result, 1)
+ go func() {
+ value, decision, err := fn(ctx)
+ done <- result{value: value, decision: decision, err: err}
+ }()
+
+ select {
+ case res := <-done:
+ if res.err != nil {
+ logger.WarnCF("hooks", "Interceptor hook failed", map[string]any{
+ "hook": name,
+ "stage": stage,
+ "error": res.err.Error(),
+ })
+ return zero, HookDecision{}, false
+ }
+ return res.value, res.decision, true
+ case <-ctx.Done():
+ logger.WarnCF("hooks", "Interceptor hook timed out", map[string]any{
+ "hook": name,
+ "stage": stage,
+ "timeout_ms": timeout.Milliseconds(),
+ })
+ return zero, HookDecision{}, false
+ }
+}
+
+func runApprovalHook(
+ parent context.Context,
+ timeout time.Duration,
+ name string,
+ stage string,
+ fn func(ctx context.Context) (ApprovalDecision, error),
+) (ApprovalDecision, bool) {
+ ctx, cancel := context.WithTimeout(parent, timeout)
+ defer cancel()
+
+ type result struct {
+ decision ApprovalDecision
+ err error
+ }
+ done := make(chan result, 1)
+ go func() {
+ decision, err := fn(ctx)
+ done <- result{decision: decision, err: err}
+ }()
+
+ select {
+ case res := <-done:
+ if res.err != nil {
+ logger.WarnCF("hooks", "Approval hook failed", map[string]any{
+ "hook": name,
+ "stage": stage,
+ "error": res.err.Error(),
+ })
+ return ApprovalDecision{}, false
+ }
+ return res.decision, true
+ case <-ctx.Done():
+ logger.WarnCF("hooks", "Approval hook timed out", map[string]any{
+ "hook": name,
+ "stage": stage,
+ "timeout_ms": timeout.Milliseconds(),
+ })
+ return ApprovalDecision{
+ Approved: false,
+ Reason: fmt.Sprintf("tool approval hook %q timed out", name),
+ }, true
+ }
+}
+
+func (hm *HookManager) logUnsupportedAction(name, stage string, action HookAction) {
+ logger.WarnCF("hooks", "Hook returned unsupported action for stage", map[string]any{
+ "hook": name,
+ "stage": stage,
+ "action": action,
+ })
+}
+
+func cloneProviderMessages(messages []providers.Message) []providers.Message {
+ if len(messages) == 0 {
+ return nil
+ }
+
+ cloned := make([]providers.Message, len(messages))
+ for i, msg := range messages {
+ cloned[i] = msg
+ if len(msg.Media) > 0 {
+ cloned[i].Media = append([]string(nil), msg.Media...)
+ }
+ if len(msg.SystemParts) > 0 {
+ cloned[i].SystemParts = append([]providers.ContentBlock(nil), msg.SystemParts...)
+ }
+ if len(msg.ToolCalls) > 0 {
+ cloned[i].ToolCalls = cloneProviderToolCalls(msg.ToolCalls)
+ }
+ }
+ return cloned
+}
+
+func cloneProviderToolCalls(calls []providers.ToolCall) []providers.ToolCall {
+ if len(calls) == 0 {
+ return nil
+ }
+
+ cloned := make([]providers.ToolCall, len(calls))
+ for i, call := range calls {
+ cloned[i] = call
+ if call.Function != nil {
+ fn := *call.Function
+ cloned[i].Function = &fn
+ }
+ if call.Arguments != nil {
+ cloned[i].Arguments = cloneStringAnyMap(call.Arguments)
+ }
+ if call.ExtraContent != nil {
+ extra := *call.ExtraContent
+ if call.ExtraContent.Google != nil {
+ google := *call.ExtraContent.Google
+ extra.Google = &google
+ }
+ cloned[i].ExtraContent = &extra
+ }
+ }
+ return cloned
+}
+
+func cloneToolDefinitions(defs []providers.ToolDefinition) []providers.ToolDefinition {
+ if len(defs) == 0 {
+ return nil
+ }
+
+ cloned := make([]providers.ToolDefinition, len(defs))
+ for i, def := range defs {
+ cloned[i] = def
+ cloned[i].Function.Parameters = cloneStringAnyMap(def.Function.Parameters)
+ }
+ return cloned
+}
+
+func cloneLLMResponse(resp *providers.LLMResponse) *providers.LLMResponse {
+ if resp == nil {
+ return nil
+ }
+ cloned := *resp
+ cloned.ToolCalls = cloneProviderToolCalls(resp.ToolCalls)
+ if len(resp.ReasoningDetails) > 0 {
+ cloned.ReasoningDetails = append(cloned.ReasoningDetails[:0:0], resp.ReasoningDetails...)
+ }
+ if resp.Usage != nil {
+ usage := *resp.Usage
+ cloned.Usage = &usage
+ }
+ return &cloned
+}
+
+func cloneStringAnyMap(src map[string]any) map[string]any {
+ if len(src) == 0 {
+ return nil
+ }
+
+ cloned := make(map[string]any, len(src))
+ for k, v := range src {
+ cloned[k] = v
+ }
+ return cloned
+}
+
+func cloneToolResult(result *tools.ToolResult) *tools.ToolResult {
+ if result == nil {
+ return nil
+ }
+
+ cloned := *result
+ if len(result.Media) > 0 {
+ cloned.Media = append([]string(nil), result.Media...)
+ }
+ return &cloned
+}
+
+func closeHookIfPossible(hook any) {
+ closer, ok := hook.(io.Closer)
+ if !ok {
+ return
+ }
+ if err := closer.Close(); err != nil {
+ logger.WarnCF("hooks", "Failed to close hook", map[string]any{
+ "error": err.Error(),
+ })
+ }
+}
diff --git a/pkg/agent/hooks_test.go b/pkg/agent/hooks_test.go
new file mode 100644
index 000000000..49e1b1784
--- /dev/null
+++ b/pkg/agent/hooks_test.go
@@ -0,0 +1,345 @@
+package agent
+
+import (
+ "context"
+ "os"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/tools"
+)
+
+func newHookTestLoop(
+ t *testing.T,
+ provider providers.LLMProvider,
+) (*AgentLoop, *AgentInstance, func()) {
+ t.Helper()
+
+ tmpDir, err := os.MkdirTemp("", "agent-hooks-*")
+ if err != nil {
+ t.Fatalf("failed to create temp dir: %v", err)
+ }
+
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Workspace: tmpDir,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ al := NewAgentLoop(cfg, bus.NewMessageBus(), provider)
+ agent := al.registry.GetDefaultAgent()
+ if agent == nil {
+ t.Fatal("expected default agent")
+ }
+
+ return al, agent, func() {
+ al.Close()
+ _ = os.RemoveAll(tmpDir)
+ }
+}
+
+func TestHookManager_SortsInProcessBeforeProcess(t *testing.T) {
+ hm := NewHookManager(nil)
+ defer hm.Close()
+
+ if err := hm.Mount(HookRegistration{
+ Name: "process",
+ Priority: -10,
+ Source: HookSourceProcess,
+ Hook: struct{}{},
+ }); err != nil {
+ t.Fatalf("mount process hook: %v", err)
+ }
+ if err := hm.Mount(HookRegistration{
+ Name: "in-process",
+ Priority: 100,
+ Source: HookSourceInProcess,
+ Hook: struct{}{},
+ }); err != nil {
+ t.Fatalf("mount in-process hook: %v", err)
+ }
+
+ ordered := hm.snapshotHooks()
+ if len(ordered) != 2 {
+ t.Fatalf("expected 2 hooks, got %d", len(ordered))
+ }
+ if ordered[0].Name != "in-process" {
+ t.Fatalf("expected in-process hook first, got %q", ordered[0].Name)
+ }
+ if ordered[1].Name != "process" {
+ t.Fatalf("expected process hook second, got %q", ordered[1].Name)
+ }
+}
+
+type llmHookTestProvider struct {
+ mu sync.Mutex
+ lastModel string
+}
+
+func (p *llmHookTestProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ p.mu.Lock()
+ p.lastModel = model
+ p.mu.Unlock()
+
+ return &providers.LLMResponse{
+ Content: "provider content",
+ }, nil
+}
+
+func (p *llmHookTestProvider) GetDefaultModel() string {
+ return "llm-hook-provider"
+}
+
+type llmObserverHook struct {
+ eventCh chan Event
+}
+
+func (h *llmObserverHook) OnEvent(ctx context.Context, evt Event) error {
+ if evt.Kind == EventKindTurnEnd {
+ select {
+ case h.eventCh <- evt:
+ default:
+ }
+ }
+ return nil
+}
+
+func (h *llmObserverHook) BeforeLLM(
+ ctx context.Context,
+ req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+ next := req.Clone()
+ next.Model = "hook-model"
+ return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmObserverHook) AfterLLM(
+ ctx context.Context,
+ resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+ next := resp.Clone()
+ next.Response.Content = "hooked content"
+ return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func TestAgentLoop_Hooks_ObserverAndLLMInterceptor(t *testing.T) {
+ provider := &llmHookTestProvider{}
+ al, agent, cleanup := newHookTestLoop(t, provider)
+ defer cleanup()
+
+ hook := &llmObserverHook{eventCh: make(chan Event, 1)}
+ if err := al.MountHook(NamedHook("llm-observer", hook)); err != nil {
+ t.Fatalf("MountHook failed: %v", err)
+ }
+
+ resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "hello",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+ if resp != "hooked content" {
+ t.Fatalf("expected hooked content, got %q", resp)
+ }
+
+ provider.mu.Lock()
+ lastModel := provider.lastModel
+ provider.mu.Unlock()
+ if lastModel != "hook-model" {
+ t.Fatalf("expected model hook-model, got %q", lastModel)
+ }
+
+ select {
+ case evt := <-hook.eventCh:
+ if evt.Kind != EventKindTurnEnd {
+ t.Fatalf("expected turn end event, got %v", evt.Kind)
+ }
+ case <-time.After(2 * time.Second):
+ t.Fatal("timed out waiting for hook observer event")
+ }
+}
+
+type toolHookProvider struct {
+ mu sync.Mutex
+ calls int
+}
+
+func (p *toolHookProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ p.mu.Lock()
+ defer p.mu.Unlock()
+
+ p.calls++
+ if p.calls == 1 {
+ return &providers.LLMResponse{
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "call-1",
+ Name: "echo_text",
+ Arguments: map[string]any{"text": "original"},
+ },
+ },
+ }, nil
+ }
+
+ last := messages[len(messages)-1]
+ return &providers.LLMResponse{
+ Content: last.Content,
+ }, nil
+}
+
+func (p *toolHookProvider) GetDefaultModel() string {
+ return "tool-hook-provider"
+}
+
+type echoTextTool struct{}
+
+func (t *echoTextTool) Name() string {
+ return "echo_text"
+}
+
+func (t *echoTextTool) Description() string {
+ return "echo a text argument"
+}
+
+func (t *echoTextTool) Parameters() map[string]any {
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "text": map[string]any{
+ "type": "string",
+ },
+ },
+ }
+}
+
+func (t *echoTextTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+ text, _ := args["text"].(string)
+ return tools.SilentResult(text)
+}
+
+type toolRewriteHook struct{}
+
+func (h *toolRewriteHook) BeforeTool(
+ ctx context.Context,
+ call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision, error) {
+ next := call.Clone()
+ next.Arguments["text"] = "modified"
+ return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *toolRewriteHook) AfterTool(
+ ctx context.Context,
+ result *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision, error) {
+ next := result.Clone()
+ next.Result.ForLLM = "after:" + next.Result.ForLLM
+ return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func TestAgentLoop_Hooks_ToolInterceptorCanRewrite(t *testing.T) {
+ provider := &toolHookProvider{}
+ al, agent, cleanup := newHookTestLoop(t, provider)
+ defer cleanup()
+
+ al.RegisterTool(&echoTextTool{})
+ if err := al.MountHook(NamedHook("tool-rewrite", &toolRewriteHook{})); err != nil {
+ t.Fatalf("MountHook failed: %v", err)
+ }
+
+ resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "run tool",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+ if resp != "after:modified" {
+ t.Fatalf("expected rewritten tool result, got %q", resp)
+ }
+}
+
+type denyApprovalHook struct{}
+
+func (h *denyApprovalHook) ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error) {
+ return ApprovalDecision{
+ Approved: false,
+ Reason: "blocked",
+ }, nil
+}
+
+func TestAgentLoop_Hooks_ToolApproverCanDeny(t *testing.T) {
+ provider := &toolHookProvider{}
+ al, agent, cleanup := newHookTestLoop(t, provider)
+ defer cleanup()
+
+ al.RegisterTool(&echoTextTool{})
+ if err := al.MountHook(NamedHook("deny-approval", &denyApprovalHook{})); err != nil {
+ t.Fatalf("MountHook failed: %v", err)
+ }
+
+ sub := al.SubscribeEvents(16)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+ SessionKey: "session-1",
+ Channel: "cli",
+ ChatID: "direct",
+ UserMessage: "run tool",
+ DefaultResponse: defaultResponse,
+ EnableSummary: false,
+ SendResponse: false,
+ })
+ if err != nil {
+ t.Fatalf("runAgentLoop failed: %v", err)
+ }
+ expected := "Tool execution denied by approval hook: blocked"
+ if resp != expected {
+ t.Fatalf("expected %q, got %q", expected, resp)
+ }
+
+ events := collectEventStream(sub.C)
+ skippedEvt, ok := findEvent(events, EventKindToolExecSkipped)
+ if !ok {
+ t.Fatal("expected tool skipped event")
+ }
+ payload, ok := skippedEvt.Payload.(ToolExecSkippedPayload)
+ if !ok {
+ t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload)
+ }
+ if payload.Reason != expected {
+ t.Fatalf("expected skipped reason %q, got %q", expected, payload.Reason)
+ }
+}
diff --git a/pkg/agent/instance.go b/pkg/agent/instance.go
index d2a4f81a4..34d401186 100644
--- a/pkg/agent/instance.go
+++ b/pkg/agent/instance.go
@@ -130,6 +130,17 @@ func NewAgentInstance(
maxTokens = 8192
}
+ contextWindow := defaults.ContextWindow
+ if contextWindow == 0 {
+ // Default heuristic: 4x the output token limit.
+ // Most models have context windows well above their output limits
+ // (e.g., GPT-4o 128k ctx / 16k out, Claude 200k ctx / 8k out).
+ // 4x is a conservative lower bound that avoids premature
+ // summarization while remaining safe — the reactive
+ // forceCompression handles any overshoot.
+ contextWindow = maxTokens * 4
+ }
+
temperature := 0.7
if defaults.Temperature != nil {
temperature = *defaults.Temperature
@@ -152,59 +163,14 @@ func NewAgentInstance(
}
// Resolve fallback candidates
- modelCfg := providers.ModelConfig{
- Primary: model,
- Fallbacks: fallbacks,
- }
- 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)
+ candidates := resolveModelCandidates(cfg, defaults.Provider, model, fallbacks)
// Model routing setup: pre-resolve light model candidates at creation time
// to avoid repeated model_list lookups on every incoming message.
var router *routing.Router
var lightCandidates []providers.FallbackCandidate
if rc := defaults.Routing; rc != nil && rc.Enabled && rc.LightModel != "" {
- lightModelCfg := providers.ModelConfig{Primary: rc.LightModel}
- resolved := providers.ResolveCandidatesWithLookup(lightModelCfg, defaults.Provider, resolveFromModelList)
+ resolved := resolveModelCandidates(cfg, defaults.Provider, rc.LightModel, nil)
if len(resolved) > 0 {
router = routing.New(routing.RouterConfig{
LightModel: rc.LightModel,
@@ -227,7 +193,7 @@ func NewAgentInstance(
MaxTokens: maxTokens,
Temperature: temperature,
ThinkingLevel: thinkingLevel,
- ContextWindow: maxTokens,
+ ContextWindow: contextWindow,
SummarizeMessageThreshold: summarizeMessageThreshold,
SummarizeTokenPercent: summarizeTokenPercent,
Provider: provider,
diff --git a/pkg/agent/instance_test.go b/pkg/agent/instance_test.go
index b3318ad1f..e073cb929 100644
--- a/pkg/agent/instance_test.go
+++ b/pkg/agent/instance_test.go
@@ -22,7 +22,7 @@ func TestNewAgentInstance_UsesDefaultsTemperatureAndMaxTokens(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 1234,
MaxToolIterations: 5,
},
@@ -54,7 +54,7 @@ func TestNewAgentInstance_DefaultsTemperatureWhenZero(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 1234,
MaxToolIterations: 5,
},
@@ -83,7 +83,7 @@ func TestNewAgentInstance_DefaultsTemperatureWhenUnset(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 1234,
MaxToolIterations: 5,
},
@@ -137,10 +137,10 @@ func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: tt.aliasName,
+ ModelName: tt.aliasName,
},
},
- ModelList: []config.ModelConfig{
+ ModelList: []*config.ModelConfig{
{
ModelName: tt.aliasName,
Model: tt.modelName,
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index edb0994c2..72c78c729 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -17,7 +17,6 @@ import (
"sync"
"sync/atomic"
"time"
- "unicode/utf8"
"github.com/sipeed/picoclaw/pkg/bus"
"github.com/sipeed/picoclaw/pkg/channels"
@@ -36,10 +35,17 @@ import (
)
type AgentLoop struct {
- bus *bus.MessageBus
- cfg *config.Config
- registry *AgentRegistry
- state *state.Manager
+ // Core dependencies
+ bus *bus.MessageBus
+ cfg *config.Config
+ registry *AgentRegistry
+ state *state.Manager
+
+ // Event system (from Incoming)
+ eventBus *EventBus
+ hooks *HookManager
+
+ // Runtime state
running atomic.Bool
summarizing sync.Map
fallback *providers.FallbackChain
@@ -48,29 +54,50 @@ type AgentLoop struct {
transcriber voice.Transcriber
cmdRegistry *commands.Registry
mcp mcpRuntime
+ hookRuntime hookRuntime
+ steering *steeringQueue
+ pendingSkills sync.Map
mu sync.RWMutex
- reloadFunc func() error
- // Track active requests for safe provider cleanup
+
+ // Concurrent turn management (from HEAD)
+ activeTurnStates sync.Map // key: sessionKey (string), value: *turnState
+ subTurnCounter atomic.Int64 // Counter for generating unique SubTurn IDs
+
+ // Turn tracking (from Incoming)
+ turnSeq atomic.Uint64
activeRequests sync.WaitGroup
+
+ reloadFunc func() error
}
// processOptions configures how a message is processed
type processOptions struct {
- SessionKey string // Session identifier for history/context
- Channel string // Target channel for tool execution
- ChatID string // Target chat ID for tool execution
- SenderID string // Current sender ID for dynamic context
- SenderDisplayName string // Current sender display name for dynamic context
- UserMessage string // User message content (may include prefix)
- Media []string // media:// refs from inbound message
- DefaultResponse string // Response when LLM returns empty
- EnableSummary bool // Whether to trigger summarization
- SendResponse bool // Whether to send response via bus
- NoHistory bool // If true, don't load session history (for heartbeat)
+ SessionKey string // Session identifier for history/context
+ Channel string // Target channel for tool execution
+ ChatID string // Target chat ID for tool execution
+ SenderID string // Current sender ID for dynamic context
+ SenderDisplayName string // Current sender display name for dynamic context
+ UserMessage string // User message content (may include prefix)
+ ForcedSkills []string // Skills explicitly requested for this message
+ SystemPromptOverride string // Override the default system prompt (Used by SubTurns)
+ Media []string // media:// refs from inbound message
+ InitialSteeringMessages []providers.Message // Steering messages from refactor/agent
+ DefaultResponse string // Response when LLM returns empty
+ EnableSummary bool // Whether to trigger summarization
+ SendResponse bool // Whether to send response via bus
+ NoHistory bool // If true, don't load session history (for heartbeat)
+ SkipInitialSteeringPoll bool // If true, skip the steering poll at loop start (used by Continue)
+}
+
+type continuationTarget struct {
+ SessionKey string
+ Channel string
+ ChatID string
}
const (
- defaultResponse = "I've completed processing but have no response to give. Increase `max_tool_iterations` in config.json."
+ defaultResponse = "The model returned an empty response. This may indicate a provider error or token limit."
+ toolLimitResponse = "I've reached `max_tool_iterations` without a final response. Increase `max_tool_iterations` in config.json if this task needs more tool steps."
sessionKeyAgentPrefix = "agent:"
metadataKeyAccountID = "account_id"
metadataKeyGuildID = "guild_id"
@@ -86,9 +113,6 @@ func NewAgentLoop(
) *AgentLoop {
registry := NewAgentRegistry(cfg, provider)
- // Register shared tools to all agents
- registerSharedTools(cfg, msgBus, registry, provider)
-
// Set up shared fallback chain
cooldown := providers.NewCooldownTracker()
fallbackChain := providers.NewFallbackChain(cooldown)
@@ -100,21 +124,30 @@ func NewAgentLoop(
stateManager = state.NewManager(defaultAgent.Workspace)
}
+ eventBus := NewEventBus()
al := &AgentLoop{
bus: msgBus,
cfg: cfg,
registry: registry,
state: stateManager,
+ eventBus: eventBus,
summarizing: sync.Map{},
fallback: fallbackChain,
cmdRegistry: commands.NewRegistry(commands.BuiltinDefinitions()),
+ steering: newSteeringQueue(parseSteeringMode(cfg.Agents.Defaults.SteeringMode)),
}
+ al.hooks = NewHookManager(eventBus)
+ configureHookManagerFromConfig(al.hooks, cfg)
+
+ // Register shared tools to all agents (now that al is created)
+ registerSharedTools(al, cfg, msgBus, registry, provider)
return al
}
// registerSharedTools registers tools that are shared across all agents (web, message, spawn).
func registerSharedTools(
+ al *AgentLoop,
cfg *config.Config,
msgBus *bus.MessageBus,
registry *AgentRegistry,
@@ -130,30 +163,37 @@ func registerSharedTools(
if cfg.Tools.IsToolEnabled("web") {
searchTool, err := tools.NewWebSearchTool(tools.WebSearchToolOptions{
- BraveAPIKeys: config.MergeAPIKeys(cfg.Tools.Web.Brave.APIKey, cfg.Tools.Web.Brave.APIKeys),
- BraveMaxResults: cfg.Tools.Web.Brave.MaxResults,
- BraveEnabled: cfg.Tools.Web.Brave.Enabled,
- TavilyAPIKeys: config.MergeAPIKeys(cfg.Tools.Web.Tavily.APIKey, cfg.Tools.Web.Tavily.APIKeys),
+ BraveAPIKeys: config.MergeAPIKeys(cfg.Tools.Web.Brave.APIKey(), cfg.Tools.Web.Brave.APIKeys()),
+ BraveMaxResults: cfg.Tools.Web.Brave.MaxResults,
+ BraveEnabled: cfg.Tools.Web.Brave.Enabled,
+ TavilyAPIKeys: config.MergeAPIKeys(
+ cfg.Tools.Web.Tavily.APIKey(),
+ cfg.Tools.Web.Tavily.APIKeys(),
+ ),
TavilyBaseURL: cfg.Tools.Web.Tavily.BaseURL,
TavilyMaxResults: cfg.Tools.Web.Tavily.MaxResults,
TavilyEnabled: cfg.Tools.Web.Tavily.Enabled,
DuckDuckGoMaxResults: cfg.Tools.Web.DuckDuckGo.MaxResults,
DuckDuckGoEnabled: cfg.Tools.Web.DuckDuckGo.Enabled,
PerplexityAPIKeys: config.MergeAPIKeys(
- cfg.Tools.Web.Perplexity.APIKey,
- cfg.Tools.Web.Perplexity.APIKeys,
+ cfg.Tools.Web.Perplexity.APIKey(),
+ cfg.Tools.Web.Perplexity.APIKeys(),
),
- PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults,
- PerplexityEnabled: cfg.Tools.Web.Perplexity.Enabled,
- SearXNGBaseURL: cfg.Tools.Web.SearXNG.BaseURL,
- SearXNGMaxResults: cfg.Tools.Web.SearXNG.MaxResults,
- SearXNGEnabled: cfg.Tools.Web.SearXNG.Enabled,
- GLMSearchAPIKey: cfg.Tools.Web.GLMSearch.APIKey,
- GLMSearchBaseURL: cfg.Tools.Web.GLMSearch.BaseURL,
- GLMSearchEngine: cfg.Tools.Web.GLMSearch.SearchEngine,
- GLMSearchMaxResults: cfg.Tools.Web.GLMSearch.MaxResults,
- GLMSearchEnabled: cfg.Tools.Web.GLMSearch.Enabled,
- Proxy: cfg.Tools.Web.Proxy,
+ PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults,
+ PerplexityEnabled: cfg.Tools.Web.Perplexity.Enabled,
+ SearXNGBaseURL: cfg.Tools.Web.SearXNG.BaseURL,
+ SearXNGMaxResults: cfg.Tools.Web.SearXNG.MaxResults,
+ SearXNGEnabled: cfg.Tools.Web.SearXNG.Enabled,
+ GLMSearchAPIKey: cfg.Tools.Web.GLMSearch.APIKey(),
+ GLMSearchBaseURL: cfg.Tools.Web.GLMSearch.BaseURL,
+ GLMSearchEngine: cfg.Tools.Web.GLMSearch.SearchEngine,
+ GLMSearchMaxResults: cfg.Tools.Web.GLMSearch.MaxResults,
+ GLMSearchEnabled: cfg.Tools.Web.GLMSearch.Enabled,
+ BaiduSearchAPIKey: cfg.Tools.Web.BaiduSearch.APIKey(),
+ BaiduSearchBaseURL: cfg.Tools.Web.BaiduSearch.BaseURL,
+ BaiduSearchMaxResults: cfg.Tools.Web.BaiduSearch.MaxResults,
+ BaiduSearchEnabled: cfg.Tools.Web.BaiduSearch.Enabled,
+ Proxy: cfg.Tools.Web.Proxy,
})
if err != nil {
logger.ErrorCF("agent", "Failed to create web search tool", map[string]any{"error": err.Error()})
@@ -215,9 +255,20 @@ func registerSharedTools(
find_skills_enable := cfg.Tools.IsToolEnabled("find_skills")
install_skills_enable := cfg.Tools.IsToolEnabled("install_skill")
if skills_enabled && (find_skills_enable || install_skills_enable) {
+ clawHubConfig := cfg.Tools.Skills.Registries.ClawHub
registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
- ClawHub: skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+ ClawHub: skills.ClawHubConfig{
+ Enabled: clawHubConfig.Enabled,
+ BaseURL: clawHubConfig.BaseURL,
+ AuthToken: clawHubConfig.AuthToken(),
+ SearchPath: clawHubConfig.SearchPath,
+ SkillsPath: clawHubConfig.SkillsPath,
+ DownloadPath: clawHubConfig.DownloadPath,
+ Timeout: clawHubConfig.Timeout,
+ MaxZipSize: clawHubConfig.MaxZipSize,
+ MaxResponseSize: clawHubConfig.MaxResponseSize,
+ },
})
if find_skills_enable {
@@ -240,6 +291,67 @@ func registerSharedTools(
if (spawnEnabled || spawnStatusEnabled) && cfg.Tools.IsToolEnabled("subagent") {
subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace)
subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature)
+
+ // Set the spawner that links into AgentLoop's turnState
+ subagentManager.SetSpawner(func(
+ ctx context.Context,
+ task, label, targetAgentID string,
+ tls *tools.ToolRegistry,
+ maxTokens int,
+ temperature float64,
+ hasMaxTokens, hasTemperature bool,
+ ) (*tools.ToolResult, error) {
+ // 1. Recover parent Turn State from Context
+ parentTS := turnStateFromContext(ctx)
+ if parentTS == nil {
+ // Fallback: If no turnState exists in context, create an isolated ad-hoc root turn state
+ // so that the tool can still function outside of an agent loop (e.g. tests, raw invocations).
+ parentTS = &turnState{
+ ctx: ctx,
+ turnID: "adhoc-root",
+ depth: 0,
+ session: nil, // Ephemeral session not needed for adhoc spawn
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, 5),
+ }
+ }
+
+ // 2. Build Tools slice from registry
+ var tlSlice []tools.Tool
+ for _, name := range tls.List() {
+ if t, ok := tls.Get(name); ok {
+ tlSlice = append(tlSlice, t)
+ }
+ }
+
+ // 3. System Prompt
+ systemPrompt := "You are a subagent. Complete the given task independently and report the result.\n" +
+ "You have access to tools - use them as needed to complete your task.\n" +
+ "After completing the task, provide a clear summary of what was done.\n\n" +
+ "Task: " + task
+
+ // 4. Resolve Model
+ modelToUse := agent.Model
+ if targetAgentID != "" {
+ if targetAgent, ok := al.GetRegistry().GetAgent(targetAgentID); ok {
+ modelToUse = targetAgent.Model
+ }
+ }
+
+ // 5. Build SubTurnConfig
+ cfg := SubTurnConfig{
+ Model: modelToUse,
+ Tools: tlSlice,
+ SystemPrompt: systemPrompt,
+ }
+ if hasMaxTokens {
+ cfg.MaxTokens = maxTokens
+ }
+
+ // 6. Spawn SubTurn
+ return spawnSubTurn(ctx, al, parentTS, cfg)
+ })
+
// Clone the parent's tool registry so subagents can use all
// tools registered so far (file, web, etc.) but NOT spawn/
// spawn_status which are added below — preventing recursive
@@ -247,11 +359,18 @@ func registerSharedTools(
subagentManager.SetTools(agent.Tools.Clone())
if spawnEnabled {
spawnTool := tools.NewSpawnTool(subagentManager)
+ spawnTool.SetSpawner(NewSubTurnSpawner(al))
currentAgentID := agentID
spawnTool.SetAllowlistChecker(func(targetAgentID string) bool {
return registry.CanSpawnSubagent(currentAgentID, targetAgentID)
})
+
agent.Tools.Register(spawnTool)
+
+ // Also register the synchronous subagent tool
+ subagentTool := tools.NewSubagentTool(subagentManager)
+ subagentTool.SetSpawner(NewSubTurnSpawner(al))
+ agent.Tools.Register(subagentTool)
}
if spawnStatusEnabled {
agent.Tools.Register(tools.NewSpawnStatusTool(subagentManager))
@@ -265,6 +384,9 @@ func registerSharedTools(
func (al *AgentLoop) Run(ctx context.Context) error {
al.running.Store(true)
+ if err := al.ensureHooksInitialized(ctx); err != nil {
+ return err
+ }
if err := al.ensureMCPInitialized(ctx); err != nil {
return err
}
@@ -277,59 +399,128 @@ func (al *AgentLoop) Run(ctx context.Context) error {
if !ok {
return nil
}
+
+ // Start a goroutine that drains the bus while processMessage is
+ // running. Only messages that resolve to the active turn scope are
+ // redirected into steering; other inbound messages are requeued.
+ drainCancel := func() {}
+ if activeScope, activeAgentID, ok := al.resolveSteeringTarget(msg); ok {
+ drainCtx, cancel := context.WithCancel(ctx)
+ drainCancel = cancel
+ go al.drainBusToSteering(drainCtx, activeScope, activeAgentID)
+ }
+
// Process message
- // TODO: Re-enable media cleanup after inbound media is properly consumed by the agent.
- // Currently disabled because files are deleted before the LLM can access their content.
- // defer func() {
- // if al.mediaStore != nil && msg.MediaScope != "" {
- // if releaseErr := al.mediaStore.ReleaseAll(msg.MediaScope); releaseErr != nil {
- // logger.WarnCF("agent", "Failed to release media", map[string]any{
- // "scope": msg.MediaScope,
- // "error": releaseErr.Error(),
- // })
- // }
- // }
- // }()
-
- response, err := al.processMessage(ctx, msg)
- if err != nil {
- response = fmt.Sprintf("Error processing message: %v", err)
- }
-
- if response != "" {
- // Check if the message tool already sent a response during this round.
- // If so, skip publishing to avoid duplicate messages to the user.
- // Use default agent's tools to check (message tool is shared).
- alreadySent := false
- defaultAgent := al.GetRegistry().GetDefaultAgent()
- if defaultAgent != nil {
- if tool, ok := defaultAgent.Tools.Get("message"); ok {
- if mt, ok := tool.(*tools.MessageTool); ok {
- alreadySent = mt.HasSentInRound()
- }
+ func() {
+ defer func() {
+ if al.channelManager != nil {
+ al.channelManager.InvokeTypingStop(msg.Channel, msg.ChatID)
}
+ }()
+ // TODO: Re-enable media cleanup after inbound media is properly consumed by the agent.
+ // Currently disabled because files are deleted before the LLM can access their content.
+ // defer func() {
+ // if al.mediaStore != nil && msg.MediaScope != "" {
+ // if releaseErr := al.mediaStore.ReleaseAll(msg.MediaScope); releaseErr != nil {
+ // logger.WarnCF("agent", "Failed to release media", map[string]any{
+ // "scope": msg.MediaScope,
+ // "error": releaseErr.Error(),
+ // })
+ // }
+ // }
+ // }()
+
+ drainCanceled := false
+ cancelDrain := func() {
+ if drainCanceled {
+ return
+ }
+ drainCancel()
+ drainCanceled = true
+ }
+ defer cancelDrain()
+
+ response, err := al.processMessage(ctx, msg)
+ if err != nil {
+ response = fmt.Sprintf("Error processing message: %v", err)
+ }
+ finalResponse := response
+
+ target, targetErr := al.buildContinuationTarget(msg)
+ if targetErr != nil {
+ logger.WarnCF("agent", "Failed to build steering continuation target",
+ map[string]any{
+ "channel": msg.Channel,
+ "error": targetErr.Error(),
+ })
+ return
+ }
+ if target == nil {
+ cancelDrain()
+ if finalResponse != "" {
+ al.publishResponseIfNeeded(ctx, msg.Channel, msg.ChatID, finalResponse)
+ }
+ return
}
- if !alreadySent {
- al.bus.PublishOutbound(ctx, bus.OutboundMessage{
- Channel: msg.Channel,
- ChatID: msg.ChatID,
- Content: response,
- })
- logger.InfoCF("agent", "Published outbound response",
+ for al.pendingSteeringCountForScope(target.SessionKey) > 0 {
+ logger.InfoCF("agent", "Continuing queued steering after turn end",
map[string]any{
- "channel": msg.Channel,
- "chat_id": msg.ChatID,
- "content_len": len(response),
+ "channel": target.Channel,
+ "chat_id": target.ChatID,
+ "session_key": target.SessionKey,
+ "queue_depth": al.pendingSteeringCountForScope(target.SessionKey),
})
- } else {
- logger.DebugCF(
- "agent",
- "Skipped outbound (message tool already sent)",
- map[string]any{"channel": msg.Channel},
- )
+
+ continued, continueErr := al.Continue(ctx, target.SessionKey, target.Channel, target.ChatID)
+ if continueErr != nil {
+ logger.WarnCF("agent", "Failed to continue queued steering",
+ map[string]any{
+ "channel": target.Channel,
+ "chat_id": target.ChatID,
+ "error": continueErr.Error(),
+ })
+ return
+ }
+ if continued == "" {
+ return
+ }
+
+ finalResponse = continued
}
- }
+
+ cancelDrain()
+
+ for al.pendingSteeringCountForScope(target.SessionKey) > 0 {
+ logger.InfoCF("agent", "Draining steering queued during turn shutdown",
+ map[string]any{
+ "channel": target.Channel,
+ "chat_id": target.ChatID,
+ "session_key": target.SessionKey,
+ "queue_depth": al.pendingSteeringCountForScope(target.SessionKey),
+ })
+
+ continued, continueErr := al.Continue(ctx, target.SessionKey, target.Channel, target.ChatID)
+ if continueErr != nil {
+ logger.WarnCF("agent", "Failed to continue queued steering after shutdown drain",
+ map[string]any{
+ "channel": target.Channel,
+ "chat_id": target.ChatID,
+ "error": continueErr.Error(),
+ })
+ return
+ }
+ if continued == "" {
+ break
+ }
+
+ finalResponse = continued
+ }
+
+ if finalResponse != "" {
+ al.publishResponseIfNeeded(ctx, target.Channel, target.ChatID, finalResponse)
+ }
+ }()
default:
time.Sleep(time.Microsecond * 200)
}
@@ -338,10 +529,135 @@ func (al *AgentLoop) Run(ctx context.Context) error {
return nil
}
+// drainBusToSteering consumes inbound messages and redirects messages from the
+// active scope into the steering queue. Messages from other scopes are requeued
+// so they can be processed normally after the active turn. It drains all
+// immediately available messages, blocking for the first one until ctx is done.
+func (al *AgentLoop) drainBusToSteering(ctx context.Context, activeScope, activeAgentID string) {
+ blocking := true
+ for {
+ var msg bus.InboundMessage
+
+ if blocking {
+ // Block waiting for the first available message or ctx cancellation.
+ select {
+ case <-ctx.Done():
+ return
+ case m, ok := <-al.bus.InboundChan():
+ if !ok {
+ return
+ }
+ msg = m
+ }
+ } else {
+ // Non-blocking: drain any remaining queued messages, return when empty.
+ select {
+ case m, ok := <-al.bus.InboundChan():
+ if !ok {
+ return
+ }
+ msg = m
+ default:
+ return
+ }
+ }
+ blocking = false
+
+ msgScope, _, scopeOK := al.resolveSteeringTarget(msg)
+ if !scopeOK || msgScope != activeScope {
+ if err := al.requeueInboundMessage(msg); err != nil {
+ logger.WarnCF("agent", "Failed to requeue non-steering inbound message", map[string]any{
+ "error": err.Error(),
+ "channel": msg.Channel,
+ "sender_id": msg.SenderID,
+ })
+ }
+ continue
+ }
+
+ // Transcribe audio if needed before steering, so the agent sees text.
+ msg, _ = al.transcribeAudioInMessage(ctx, msg)
+
+ logger.InfoCF("agent", "Redirecting inbound message to steering queue",
+ map[string]any{
+ "channel": msg.Channel,
+ "sender_id": msg.SenderID,
+ "content_len": len(msg.Content),
+ "scope": activeScope,
+ })
+
+ if err := al.enqueueSteeringMessage(activeScope, activeAgentID, providers.Message{
+ Role: "user",
+ Content: msg.Content,
+ Media: append([]string(nil), msg.Media...),
+ }); err != nil {
+ logger.WarnCF("agent", "Failed to steer message, will be lost",
+ map[string]any{
+ "error": err.Error(),
+ "channel": msg.Channel,
+ })
+ }
+ }
+}
+
func (al *AgentLoop) Stop() {
al.running.Store(false)
}
+func (al *AgentLoop) publishResponseIfNeeded(ctx context.Context, channel, chatID, response string) {
+ if response == "" {
+ return
+ }
+
+ alreadySent := false
+ defaultAgent := al.GetRegistry().GetDefaultAgent()
+ if defaultAgent != nil {
+ if tool, ok := defaultAgent.Tools.Get("message"); ok {
+ if mt, ok := tool.(*tools.MessageTool); ok {
+ alreadySent = mt.HasSentInRound()
+ }
+ }
+ }
+
+ if alreadySent {
+ logger.DebugCF(
+ "agent",
+ "Skipped outbound (message tool already sent)",
+ map[string]any{"channel": channel},
+ )
+ return
+ }
+
+ al.bus.PublishOutbound(ctx, bus.OutboundMessage{
+ Channel: channel,
+ ChatID: chatID,
+ Content: response,
+ })
+ logger.InfoCF("agent", "Published outbound response",
+ map[string]any{
+ "channel": channel,
+ "chat_id": chatID,
+ "content_len": len(response),
+ })
+}
+
+func (al *AgentLoop) buildContinuationTarget(msg bus.InboundMessage) (*continuationTarget, error) {
+ if msg.Channel == "system" {
+ return nil, nil
+ }
+
+ route, _, err := al.resolveMessageRoute(msg)
+ if err != nil {
+ return nil, err
+ }
+
+ return &continuationTarget{
+ SessionKey: resolveScopeKey(route, msg.SessionKey),
+ Channel: msg.Channel,
+ ChatID: msg.ChatID,
+ }, nil
+}
+
// Close releases resources held by agent session stores. Call after Stop.
func (al *AgentLoop) Close() {
mcpManager := al.mcp.takeManager()
@@ -356,6 +672,232 @@ func (al *AgentLoop) Close() {
}
al.GetRegistry().Close()
+ if al.hooks != nil {
+ al.hooks.Close()
+ }
+ if al.eventBus != nil {
+ al.eventBus.Close()
+ }
+}
+
+// MountHook registers an in-process hook on the agent loop.
+func (al *AgentLoop) MountHook(reg HookRegistration) error {
+ if al == nil || al.hooks == nil {
+ return fmt.Errorf("hook manager is not initialized")
+ }
+ return al.hooks.Mount(reg)
+}
+
+// UnmountHook removes a previously registered in-process hook.
+func (al *AgentLoop) UnmountHook(name string) {
+ if al == nil || al.hooks == nil {
+ return
+ }
+ al.hooks.Unmount(name)
+}
+
+// SubscribeEvents registers a subscriber for agent-loop events.
+func (al *AgentLoop) SubscribeEvents(buffer int) EventSubscription {
+ if al == nil || al.eventBus == nil {
+ ch := make(chan Event)
+ close(ch)
+ return EventSubscription{C: ch}
+ }
+ return al.eventBus.Subscribe(buffer)
+}
+
+// UnsubscribeEvents removes a previously registered event subscriber.
+func (al *AgentLoop) UnsubscribeEvents(id uint64) {
+ if al == nil || al.eventBus == nil {
+ return
+ }
+ al.eventBus.Unsubscribe(id)
+}
+
+// EventDrops returns the number of dropped events for the given kind.
+func (al *AgentLoop) EventDrops(kind EventKind) int64 {
+ if al == nil || al.eventBus == nil {
+ return 0
+ }
+ return al.eventBus.Dropped(kind)
+}
+
+type turnEventScope struct {
+ agentID string
+ sessionKey string
+ turnID string
+}
+
+func (al *AgentLoop) newTurnEventScope(agentID, sessionKey string) turnEventScope {
+ seq := al.turnSeq.Add(1)
+ return turnEventScope{
+ agentID: agentID,
+ sessionKey: sessionKey,
+ turnID: fmt.Sprintf("%s-turn-%d", agentID, seq),
+ }
+}
+
+func (ts turnEventScope) meta(iteration int, source, tracePath string) EventMeta {
+ return EventMeta{
+ AgentID: ts.agentID,
+ TurnID: ts.turnID,
+ SessionKey: ts.sessionKey,
+ Iteration: iteration,
+ Source: source,
+ TracePath: tracePath,
+ }
+}
+
+func (al *AgentLoop) emitEvent(kind EventKind, meta EventMeta, payload any) {
+ evt := Event{
+ Kind: kind,
+ Meta: meta,
+ Payload: payload,
+ }
+
+ if al == nil || al.eventBus == nil {
+ return
+ }
+
+ al.logEvent(evt)
+
+ al.eventBus.Emit(evt)
+}
+
+func cloneEventArguments(args map[string]any) map[string]any {
+ if len(args) == 0 {
+ return nil
+ }
+
+ cloned := make(map[string]any, len(args))
+ for k, v := range args {
+ cloned[k] = v
+ }
+ return cloned
+}
+
+func (al *AgentLoop) hookAbortError(ts *turnState, stage string, decision HookDecision) error {
+ reason := decision.Reason
+ if reason == "" {
+ reason = "hook requested turn abort"
+ }
+
+ err := fmt.Errorf("hook aborted turn during %s: %s", stage, reason)
+ al.emitEvent(
+ EventKindError,
+ ts.eventMeta("hooks", "turn.error"),
+ ErrorPayload{
+ Stage: "hook." + stage,
+ Message: err.Error(),
+ },
+ )
+ return err
+}
+
+func hookDeniedToolContent(prefix, reason string) string {
+ if reason == "" {
+ return prefix
+ }
+ return prefix + ": " + reason
+}
+
+func (al *AgentLoop) logEvent(evt Event) {
+ fields := map[string]any{
+ "event_kind": evt.Kind.String(),
+ "agent_id": evt.Meta.AgentID,
+ "turn_id": evt.Meta.TurnID,
+ "session_key": evt.Meta.SessionKey,
+ "iteration": evt.Meta.Iteration,
+ }
+
+ if evt.Meta.TracePath != "" {
+ fields["trace"] = evt.Meta.TracePath
+ }
+ if evt.Meta.Source != "" {
+ fields["source"] = evt.Meta.Source
+ }
+
+ switch payload := evt.Payload.(type) {
+ case TurnStartPayload:
+ fields["channel"] = payload.Channel
+ fields["chat_id"] = payload.ChatID
+ fields["user_len"] = len(payload.UserMessage)
+ fields["media_count"] = payload.MediaCount
+ case TurnEndPayload:
+ fields["status"] = payload.Status
+ fields["iterations_total"] = payload.Iterations
+ fields["duration_ms"] = payload.Duration.Milliseconds()
+ fields["final_len"] = payload.FinalContentLen
+ case LLMRequestPayload:
+ fields["model"] = payload.Model
+ fields["messages"] = payload.MessagesCount
+ fields["tools"] = payload.ToolsCount
+ fields["max_tokens"] = payload.MaxTokens
+ case LLMDeltaPayload:
+ fields["content_delta_len"] = payload.ContentDeltaLen
+ fields["reasoning_delta_len"] = payload.ReasoningDeltaLen
+ case LLMResponsePayload:
+ fields["content_len"] = payload.ContentLen
+ fields["tool_calls"] = payload.ToolCalls
+ fields["has_reasoning"] = payload.HasReasoning
+ case LLMRetryPayload:
+ fields["attempt"] = payload.Attempt
+ fields["max_retries"] = payload.MaxRetries
+ fields["reason"] = payload.Reason
+ fields["error"] = payload.Error
+ fields["backoff_ms"] = payload.Backoff.Milliseconds()
+ case ContextCompressPayload:
+ fields["reason"] = payload.Reason
+ fields["dropped_messages"] = payload.DroppedMessages
+ fields["remaining_messages"] = payload.RemainingMessages
+ case SessionSummarizePayload:
+ fields["summarized_messages"] = payload.SummarizedMessages
+ fields["kept_messages"] = payload.KeptMessages
+ fields["summary_len"] = payload.SummaryLen
+ fields["omitted_oversized"] = payload.OmittedOversized
+ case ToolExecStartPayload:
+ fields["tool"] = payload.Tool
+ fields["args_count"] = len(payload.Arguments)
+ case ToolExecEndPayload:
+ fields["tool"] = payload.Tool
+ fields["duration_ms"] = payload.Duration.Milliseconds()
+ fields["for_llm_len"] = payload.ForLLMLen
+ fields["for_user_len"] = payload.ForUserLen
+ fields["is_error"] = payload.IsError
+ fields["async"] = payload.Async
+ case ToolExecSkippedPayload:
+ fields["tool"] = payload.Tool
+ fields["reason"] = payload.Reason
+ case SteeringInjectedPayload:
+ fields["count"] = payload.Count
+ fields["total_content_len"] = payload.TotalContentLen
+ case FollowUpQueuedPayload:
+ fields["source_tool"] = payload.SourceTool
+ fields["channel"] = payload.Channel
+ fields["chat_id"] = payload.ChatID
+ fields["content_len"] = payload.ContentLen
+ case InterruptReceivedPayload:
+ fields["interrupt_kind"] = payload.Kind
+ fields["role"] = payload.Role
+ fields["content_len"] = payload.ContentLen
+ fields["queue_depth"] = payload.QueueDepth
+ fields["hint_len"] = payload.HintLen
+ case SubTurnSpawnPayload:
+ fields["child_agent_id"] = payload.AgentID
+ fields["label"] = payload.Label
+ case SubTurnEndPayload:
+ fields["child_agent_id"] = payload.AgentID
+ fields["status"] = payload.Status
+ case SubTurnResultDeliveredPayload:
+ fields["target_channel"] = payload.TargetChannel
+ fields["target_chat_id"] = payload.TargetChatID
+ fields["content_len"] = payload.ContentLen
+ case ErrorPayload:
+ fields["stage"] = payload.Stage
+ fields["error"] = payload.Message
+ }
+
+ logger.InfoCF("eventbus", fmt.Sprintf("Agent event: %s", evt.Kind.String()), fields)
}
func (al *AgentLoop) RegisterTool(tool tools.Tool) {
@@ -425,7 +967,7 @@ func (al *AgentLoop) ReloadProviderAndConfig(
}
// Ensure shared tools are re-registered on the new registry
- registerSharedTools(cfg, al.bus, registry, provider)
+ registerSharedTools(al, cfg, al.bus, registry, provider)
// Atomically swap the config and registry under write lock
// This ensures readers see a consistent pair
@@ -441,6 +983,9 @@ func (al *AgentLoop) ReloadProviderAndConfig(
al.mu.Unlock()
+ al.hookRuntime.reset(al)
+ configureHookManagerFromConfig(al.hooks, cfg)
+
// Close old provider after releasing the lock
// This prevents blocking readers while closing
if oldProvider, ok := extractProvider(oldRegistry); ok {
@@ -660,6 +1205,9 @@ func (al *AgentLoop) ProcessDirectWithChannel(
ctx context.Context,
content, sessionKey, channel, chatID string,
) (string, error) {
+ if err := al.ensureHooksInitialized(ctx); err != nil {
+ return "", err
+ }
if err := al.ensureMCPInitialized(ctx); err != nil {
return "", err
}
@@ -681,6 +1229,13 @@ func (al *AgentLoop) ProcessHeartbeat(
ctx context.Context,
content, channel, chatID string,
) (string, error) {
+ if err := al.ensureHooksInitialized(ctx); err != nil {
+ return "", err
+ }
+ if err := al.ensureMCPInitialized(ctx); err != nil {
+ return "", err
+ }
+
agent := al.GetRegistry().GetDefaultAgent()
if agent == nil {
return "", fmt.Errorf("no default agent for heartbeat")
@@ -775,6 +1330,15 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
return response, nil
}
+ if pending := al.takePendingSkills(opts.SessionKey); len(pending) > 0 {
+ opts.ForcedSkills = append(opts.ForcedSkills, pending...)
+ logger.InfoCF("agent", "Applying pending skill override",
+ map[string]any{
+ "session_key": opts.SessionKey,
+ "skills": strings.Join(pending, ","),
+ })
+ }
+
return al.runAgentLoop(ctx, agent, opts)
}
@@ -807,6 +1371,32 @@ func resolveScopeKey(route routing.ResolvedRoute, msgSessionKey string) string {
return route.SessionKey
}
+func (al *AgentLoop) resolveSteeringTarget(msg bus.InboundMessage) (string, string, bool) {
+ if msg.Channel == "system" {
+ return "", "", false
+ }
+
+ route, agent, err := al.resolveMessageRoute(msg)
+ if err != nil || agent == nil {
+ return "", "", false
+ }
+
+ return resolveScopeKey(route, msg.SessionKey), agent.ID, true
+}
+
+func (al *AgentLoop) requeueInboundMessage(msg bus.InboundMessage) error {
+ if al.bus == nil {
+ return nil
+ }
+ pubCtx, cancel := context.WithTimeout(context.Background(), time.Second)
+ defer cancel()
+ return al.bus.PublishOutbound(pubCtx, bus.OutboundMessage{
+ Channel: msg.Channel,
+ ChatID: msg.ChatID,
+ Content: msg.Content,
+ })
+}
+
func (al *AgentLoop) processSystemMessage(
ctx context.Context,
msg bus.InboundMessage,
@@ -872,95 +1462,64 @@ func (al *AgentLoop) processSystemMessage(
})
}
-// runAgentLoop is the core message processing logic.
+// runAgentLoop remains the top-level shell that starts a turn and publishes
+// any post-turn work. runTurn owns the full turn lifecycle.
func (al *AgentLoop) runAgentLoop(
ctx context.Context,
agent *AgentInstance,
opts processOptions,
) (string, error) {
- // 0. Record last channel for heartbeat notifications (skip internal channels and cli)
- if opts.Channel != "" && opts.ChatID != "" {
- if !constants.IsInternalChannel(opts.Channel) {
- channelKey := fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID)
- if err := al.RecordLastChannel(channelKey); err != nil {
- logger.WarnCF(
- "agent",
- "Failed to record last channel",
- map[string]any{"error": err.Error()},
- )
- }
+ // Record last channel for heartbeat notifications (skip internal channels and cli)
+ if opts.Channel != "" && opts.ChatID != "" && !constants.IsInternalChannel(opts.Channel) {
+ channelKey := fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID)
+ if err := al.RecordLastChannel(channelKey); err != nil {
+ logger.WarnCF(
+ "agent",
+ "Failed to record last channel",
+ map[string]any{"error": err.Error()},
+ )
}
}
- // 1. Build messages (skip history for heartbeat)
- var history []providers.Message
- var summary string
- if !opts.NoHistory {
- history = agent.Sessions.GetHistory(opts.SessionKey)
- summary = agent.Sessions.GetSummary(opts.SessionKey)
- }
- messages := agent.ContextBuilder.BuildMessages(
- history,
- summary,
- opts.UserMessage,
- opts.Media,
- opts.Channel,
- opts.ChatID,
- opts.SenderID,
- opts.SenderDisplayName,
- )
-
- // Resolve media:// refs: images→base64 data URLs, non-images→local paths in content
- cfg := al.GetConfig()
- maxMediaSize := cfg.Agents.Defaults.GetMaxMediaSize()
- messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize)
-
- // 2. Save user message to session
- agent.Sessions.AddMessage(opts.SessionKey, "user", opts.UserMessage)
-
- // 3. Run LLM iteration loop
- finalContent, iteration, err := al.runLLMIteration(ctx, agent, messages, opts)
+ ts := newTurnState(agent, opts, al.newTurnEventScope(agent.ID, opts.SessionKey))
+ result, err := al.runTurn(ctx, ts)
if err != nil {
return "", err
}
-
- // If last tool had ForUser content and we already sent it, we might not need to send final response
- // This is controlled by the tool's Silent flag and ForUser content
-
- // 4. Handle empty response
- if finalContent == "" {
- finalContent = opts.DefaultResponse
+ if result.status == TurnEndStatusAborted {
+ return "", nil
}
- // 5. Save final assistant message to session
- agent.Sessions.AddMessage(opts.SessionKey, "assistant", finalContent)
- agent.Sessions.Save(opts.SessionKey)
-
- // 6. Optional: summarization
- if opts.EnableSummary {
- al.maybeSummarize(agent, opts.SessionKey, opts.Channel, opts.ChatID)
+ for _, followUp := range result.followUps {
+ if pubErr := al.bus.PublishInbound(ctx, followUp); pubErr != nil {
+ logger.WarnCF("agent", "Failed to publish follow-up after turn",
+ map[string]any{
+ "turn_id": ts.turnID,
+ "error": pubErr.Error(),
+ })
+ }
}
- // 7. Optional: send response via bus
- if opts.SendResponse {
+ if opts.SendResponse && result.finalContent != "" {
al.bus.PublishOutbound(ctx, bus.OutboundMessage{
Channel: opts.Channel,
ChatID: opts.ChatID,
- Content: finalContent,
+ Content: result.finalContent,
})
}
- // 8. Log response
- responsePreview := utils.Truncate(finalContent, 120)
- logger.InfoCF("agent", fmt.Sprintf("Response: %s", responsePreview),
- map[string]any{
- "agent_id": agent.ID,
- "session_key": opts.SessionKey,
- "iterations": iteration,
- "final_length": len(finalContent),
- })
+ if result.finalContent != "" {
+ responsePreview := utils.Truncate(result.finalContent, 120)
+ logger.InfoCF("agent", fmt.Sprintf("Response: %s", responsePreview),
+ map[string]any{
+ "agent_id": agent.ID,
+ "session_key": opts.SessionKey,
+ "iterations": ts.currentIteration(),
+ "final_length": len(result.finalContent),
+ })
+ }
- return finalContent, nil
+ return result.finalContent, nil
}
func (al *AgentLoop) targetReasoningChannelID(channelName string) (chatID string) {
@@ -1019,103 +1578,333 @@ func (al *AgentLoop) handleReasoning(
}
}
-// runLLMIteration executes the LLM call loop with tool handling.
-func (al *AgentLoop) runLLMIteration(
- ctx context.Context,
- agent *AgentInstance,
- messages []providers.Message,
- opts processOptions,
-) (string, int, error) {
- iteration := 0
+func (al *AgentLoop) runTurn(ctx context.Context, ts *turnState) (turnResult, error) {
+ turnCtx, turnCancel := context.WithCancel(ctx)
+ defer turnCancel()
+ ts.setTurnCancel(turnCancel)
+
+ // Inject turnState and AgentLoop into context so tools (e.g. spawn) can retrieve them.
+ turnCtx = withTurnState(turnCtx, ts)
+ turnCtx = WithAgentLoop(turnCtx, al)
+
+ al.registerActiveTurn(ts)
+ defer al.clearActiveTurn(ts)
+
+ turnStatus := TurnEndStatusCompleted
+ defer func() {
+ al.emitEvent(
+ EventKindTurnEnd,
+ ts.eventMeta("runTurn", "turn.end"),
+ TurnEndPayload{
+ Status: turnStatus,
+ Iterations: ts.currentIteration(),
+ Duration: time.Since(ts.startedAt),
+ FinalContentLen: ts.finalContentLen(),
+ },
+ )
+ }()
+
+ al.emitEvent(
+ EventKindTurnStart,
+ ts.eventMeta("runTurn", "turn.start"),
+ TurnStartPayload{
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ UserMessage: ts.userMessage,
+ MediaCount: len(ts.media),
+ },
+ )
+
+ var history []providers.Message
+ var summary string
+ if !ts.opts.NoHistory {
+ history = ts.agent.Sessions.GetHistory(ts.sessionKey)
+ summary = ts.agent.Sessions.GetSummary(ts.sessionKey)
+ }
+ ts.captureRestorePoint(history, summary)
+
+ messages := ts.agent.ContextBuilder.BuildMessages(
+ history,
+ summary,
+ ts.userMessage,
+ ts.media,
+ ts.channel,
+ ts.chatID,
+ ts.opts.SenderID,
+ ts.opts.SenderDisplayName,
+ activeSkillNames(ts.agent, ts.opts)...,
+ )
+
+ cfg := al.GetConfig()
+ maxMediaSize := cfg.Agents.Defaults.GetMaxMediaSize()
+ messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize)
+
+ if !ts.opts.NoHistory {
+ toolDefs := ts.agent.Tools.ToProviderDefs()
+ if isOverContextBudget(ts.agent.ContextWindow, messages, toolDefs, ts.agent.MaxTokens) {
+ logger.WarnCF("agent", "Proactive compression: context budget exceeded before LLM call",
+ map[string]any{"session_key": ts.sessionKey})
+ if compression, ok := al.forceCompression(ts.agent, ts.sessionKey); ok {
+ al.emitEvent(
+ EventKindContextCompress,
+ ts.eventMeta("runTurn", "turn.context.compress"),
+ ContextCompressPayload{
+ Reason: ContextCompressReasonProactive,
+ DroppedMessages: compression.DroppedMessages,
+ RemainingMessages: compression.RemainingMessages,
+ },
+ )
+ ts.refreshRestorePointFromSession(ts.agent)
+ }
+ newHistory := ts.agent.Sessions.GetHistory(ts.sessionKey)
+ newSummary := ts.agent.Sessions.GetSummary(ts.sessionKey)
+ messages = ts.agent.ContextBuilder.BuildMessages(
+ newHistory, newSummary, ts.userMessage,
+ ts.media, ts.channel, ts.chatID,
+ ts.opts.SenderID, ts.opts.SenderDisplayName,
+ activeSkillNames(ts.agent, ts.opts)...,
+ )
+ messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize)
+ }
+ }
+
+ // Save user message to session (from Incoming)
+ if !ts.opts.NoHistory && (strings.TrimSpace(ts.userMessage) != "" || len(ts.media) > 0) {
+ rootMsg := providers.Message{
+ Role: "user",
+ Content: ts.userMessage,
+ Media: append([]string(nil), ts.media...),
+ }
+ if len(rootMsg.Media) > 0 {
+ ts.agent.Sessions.AddFullMessage(ts.sessionKey, rootMsg)
+ } else {
+ ts.agent.Sessions.AddMessage(ts.sessionKey, rootMsg.Role, rootMsg.Content)
+ }
+ ts.recordPersistedMessage(rootMsg)
+ }
+
+ activeCandidates, activeModel := al.selectCandidates(ts.agent, ts.userMessage, messages)
+ pendingMessages := append([]providers.Message(nil), ts.opts.InitialSteeringMessages...)
var finalContent string
- // Determine effective model tier for this conversation turn.
- // selectCandidates evaluates routing once and the decision is sticky for
- // all tool-follow-up iterations within the same turn so that a multi-step
- // tool chain doesn't switch models mid-way through.
- activeCandidates, activeModel := al.selectCandidates(agent, opts.UserMessage, messages)
+turnLoop:
+ for ts.currentIteration() < ts.agent.MaxIterations || len(pendingMessages) > 0 || func() bool {
+ graceful, _ := ts.gracefulInterruptRequested()
+ return graceful
+ }() {
+ if ts.hardAbortRequested() {
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
- for iteration < agent.MaxIterations {
- iteration++
+ iteration := ts.currentIteration() + 1
+ ts.setIteration(iteration)
+ ts.setPhase(TurnPhaseRunning)
+
+ if iteration > 1 {
+ if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+ pendingMessages = append(pendingMessages, steerMsgs...)
+ }
+ } else if !ts.opts.SkipInitialSteeringPoll {
+ if steerMsgs := al.dequeueSteeringMessagesForScopeWithFallback(ts.sessionKey); len(steerMsgs) > 0 {
+ pendingMessages = append(pendingMessages, steerMsgs...)
+ }
+ }
+
+ // Check if parent turn has ended (SubTurn support from HEAD)
+ if ts.parentTurnState != nil && ts.IsParentEnded() {
+ if !ts.critical {
+ logger.InfoCF("agent", "Parent turn ended, non-critical SubTurn exiting gracefully", map[string]any{
+ "agent_id": ts.agentID,
+ "iteration": iteration,
+ "turn_id": ts.turnID,
+ })
+ break
+ }
+ logger.InfoCF("agent", "Parent turn ended, critical SubTurn continues running", map[string]any{
+ "agent_id": ts.agentID,
+ "iteration": iteration,
+ "turn_id": ts.turnID,
+ })
+ }
+
+ // Poll for pending SubTurn results (from HEAD)
+ if ts.pendingResults != nil {
+ select {
+ case result, ok := <-ts.pendingResults:
+ if ok && result != nil && result.ForLLM != "" {
+ msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", result.ForLLM)}
+ pendingMessages = append(pendingMessages, msg)
+ }
+ default:
+ // No results available
+ }
+ }
+
+ // Inject pending steering messages
+ if len(pendingMessages) > 0 {
+ resolvedPending := resolveMediaRefs(pendingMessages, al.mediaStore, maxMediaSize)
+ totalContentLen := 0
+ for i, pm := range pendingMessages {
+ messages = append(messages, resolvedPending[i])
+ totalContentLen += len(pm.Content)
+ if !ts.opts.NoHistory {
+ ts.agent.Sessions.AddFullMessage(ts.sessionKey, pm)
+ ts.recordPersistedMessage(pm)
+ }
+ logger.InfoCF("agent", "Injected steering message into context",
+ map[string]any{
+ "agent_id": ts.agent.ID,
+ "iteration": iteration,
+ "content_len": len(pm.Content),
+ "media_count": len(pm.Media),
+ })
+ }
+ al.emitEvent(
+ EventKindSteeringInjected,
+ ts.eventMeta("runTurn", "turn.steering.injected"),
+ SteeringInjectedPayload{
+ Count: len(pendingMessages),
+ TotalContentLen: totalContentLen,
+ },
+ )
+ pendingMessages = nil
+ }
logger.DebugCF("agent", "LLM iteration",
map[string]any{
- "agent_id": agent.ID,
+ "agent_id": ts.agent.ID,
"iteration": iteration,
- "max": agent.MaxIterations,
+ "max": ts.agent.MaxIterations,
})
- // Build tool definitions
- providerToolDefs := agent.Tools.ToProviderDefs()
+ gracefulTerminal, _ := ts.gracefulInterruptRequested()
+ providerToolDefs := ts.agent.Tools.ToProviderDefs()
- // Determine whether the provider's native web search should replace
- // the client-side web_search tool for this request. Only enable when web
- // search is actually enabled and registered (so users who disabled web
- // access do not get provider-side search or billing).
- _, hasWebSearch := agent.Tools.Get("web_search")
+ // Native web search support (from HEAD)
+ _, hasWebSearch := ts.agent.Tools.Get("web_search")
useNativeSearch := al.cfg.Tools.Web.PreferNative &&
- isNativeSearchProvider(agent.Provider) &&
- hasWebSearch
+ hasWebSearch &&
+ func() bool {
+ // Check if provider supports native search
+ if ns, ok := ts.agent.Provider.(interface{ SupportsNativeSearch() bool }); ok {
+ return ns.SupportsNativeSearch()
+ }
+ return false
+ }()
if useNativeSearch {
- providerToolDefs = filterClientWebSearch(providerToolDefs)
+ // Filter out client-side web_search tool
+ filtered := make([]providers.ToolDefinition, 0, len(providerToolDefs))
+ for _, td := range providerToolDefs {
+ if td.Function.Name != "web_search" {
+ filtered = append(filtered, td)
+ }
+ }
+ providerToolDefs = filtered
}
- // Log LLM request details
- logger.DebugCF("agent", "LLM request",
- map[string]any{
- "agent_id": agent.ID,
- "iteration": iteration,
- "model": activeModel,
- "messages_count": len(messages),
- "tools_count": len(providerToolDefs),
- "native_search": useNativeSearch,
- "max_tokens": agent.MaxTokens,
- "temperature": agent.Temperature,
- "system_prompt_len": len(messages[0].Content),
- })
-
- // Log full messages (detailed)
- logger.DebugCF("agent", "Full LLM request",
- map[string]any{
- "iteration": iteration,
- "messages_json": formatMessagesForLog(messages),
- "tools_json": formatToolsForLog(providerToolDefs),
- })
-
- // Call LLM with fallback chain if multiple candidates are configured.
- var response *providers.LLMResponse
- var err error
+ callMessages := messages
+ if gracefulTerminal {
+ callMessages = append(append([]providers.Message(nil), messages...), ts.interruptHintMessage())
+ providerToolDefs = nil
+ ts.markGracefulTerminalUsed()
+ }
llmOpts := map[string]any{
- "max_tokens": agent.MaxTokens,
- "temperature": agent.Temperature,
- "prompt_cache_key": agent.ID,
+ "max_tokens": ts.agent.MaxTokens,
+ "temperature": ts.agent.Temperature,
+ "prompt_cache_key": ts.agent.ID,
}
if useNativeSearch {
llmOpts["native_search"] = true
}
- // parseThinkingLevel guarantees ThinkingOff for empty/unknown values,
- // so checking != ThinkingOff is sufficient.
- if agent.ThinkingLevel != ThinkingOff {
- if tc, ok := agent.Provider.(providers.ThinkingCapable); ok && tc.SupportsThinking() {
- llmOpts["thinking_level"] = string(agent.ThinkingLevel)
+ if ts.agent.ThinkingLevel != ThinkingOff {
+ if tc, ok := ts.agent.Provider.(providers.ThinkingCapable); ok && tc.SupportsThinking() {
+ llmOpts["thinking_level"] = string(ts.agent.ThinkingLevel)
} else {
logger.WarnCF("agent", "thinking_level is set but current provider does not support it, ignoring",
- map[string]any{"agent_id": agent.ID, "thinking_level": string(agent.ThinkingLevel)})
+ map[string]any{"agent_id": ts.agent.ID, "thinking_level": string(ts.agent.ThinkingLevel)})
}
}
- callLLM := func() (*providers.LLMResponse, error) {
+ llmModel := activeModel
+ if al.hooks != nil {
+ llmReq, decision := al.hooks.BeforeLLM(turnCtx, &LLMHookRequest{
+ Meta: ts.eventMeta("runTurn", "turn.llm.request"),
+ Model: llmModel,
+ Messages: callMessages,
+ Tools: providerToolDefs,
+ Options: llmOpts,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ GracefulTerminal: gracefulTerminal,
+ })
+ switch decision.normalizedAction() {
+ case HookActionContinue, HookActionModify:
+ if llmReq != nil {
+ llmModel = llmReq.Model
+ callMessages = llmReq.Messages
+ providerToolDefs = llmReq.Tools
+ llmOpts = llmReq.Options
+ }
+ case HookActionAbortTurn:
+ turnStatus = TurnEndStatusError
+ return turnResult{}, al.hookAbortError(ts, "before_llm", decision)
+ case HookActionHardAbort:
+ _ = ts.requestHardAbort()
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
+ }
+
+ al.emitEvent(
+ EventKindLLMRequest,
+ ts.eventMeta("runTurn", "turn.llm.request"),
+ LLMRequestPayload{
+ Model: llmModel,
+ MessagesCount: len(callMessages),
+ ToolsCount: len(providerToolDefs),
+ MaxTokens: ts.agent.MaxTokens,
+ Temperature: ts.agent.Temperature,
+ },
+ )
+
+ logger.DebugCF("agent", "LLM request",
+ map[string]any{
+ "agent_id": ts.agent.ID,
+ "iteration": iteration,
+ "model": llmModel,
+ "messages_count": len(callMessages),
+ "tools_count": len(providerToolDefs),
+ "max_tokens": ts.agent.MaxTokens,
+ "temperature": ts.agent.Temperature,
+ "system_prompt_len": len(callMessages[0].Content),
+ })
+ logger.DebugCF("agent", "Full LLM request",
+ map[string]any{
+ "iteration": iteration,
+ "messages_json": formatMessagesForLog(callMessages),
+ "tools_json": formatToolsForLog(providerToolDefs),
+ })
+
+ callLLM := func(messagesForCall []providers.Message, toolDefsForCall []providers.ToolDefinition) (*providers.LLMResponse, error) {
+ providerCtx, providerCancel := context.WithCancel(turnCtx)
+ ts.setProviderCancel(providerCancel)
+ defer func() {
+ providerCancel()
+ ts.clearProviderCancel(providerCancel)
+ }()
+
al.activeRequests.Add(1)
defer al.activeRequests.Done()
if len(activeCandidates) > 1 && al.fallback != nil {
fbResult, fbErr := al.fallback.Execute(
- ctx,
+ providerCtx,
activeCandidates,
func(ctx context.Context, provider, model string) (*providers.LLMResponse, error) {
- return agent.Provider.Chat(ctx, messages, providerToolDefs, model, llmOpts)
+ return ts.agent.Provider.Chat(ctx, messagesForCall, toolDefsForCall, model, llmOpts)
},
)
if fbErr != nil {
@@ -1126,32 +1915,34 @@ func (al *AgentLoop) runLLMIteration(
"agent",
fmt.Sprintf("Fallback: succeeded with %s/%s after %d attempts",
fbResult.Provider, fbResult.Model, len(fbResult.Attempts)+1),
- map[string]any{"agent_id": agent.ID, "iteration": iteration},
+ map[string]any{"agent_id": ts.agent.ID, "iteration": iteration},
)
}
return fbResult.Response, nil
}
- return agent.Provider.Chat(ctx, messages, providerToolDefs, activeModel, llmOpts)
+ return ts.agent.Provider.Chat(providerCtx, messagesForCall, toolDefsForCall, llmModel, llmOpts)
}
- // Retry loop for context/token errors
+ var response *providers.LLMResponse
+ var err error
maxRetries := 2
for retry := 0; retry <= maxRetries; retry++ {
- response, err = callLLM()
+ response, err = callLLM(callMessages, providerToolDefs)
if err == nil {
break
}
+ if ts.hardAbortRequested() && errors.Is(err, context.Canceled) {
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
errMsg := strings.ToLower(err.Error())
-
- // 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") ||
@@ -1164,16 +1955,44 @@ func (al *AgentLoop) runLLMIteration(
if isTimeoutError && retry < maxRetries {
backoff := time.Duration(retry+1) * 5 * time.Second
+ al.emitEvent(
+ EventKindLLMRetry,
+ ts.eventMeta("runTurn", "turn.llm.retry"),
+ LLMRetryPayload{
+ Attempt: retry + 1,
+ MaxRetries: maxRetries,
+ Reason: "timeout",
+ Error: err.Error(),
+ Backoff: backoff,
+ },
+ )
logger.WarnCF("agent", "Timeout error, retrying after backoff", map[string]any{
"error": err.Error(),
"retry": retry,
"backoff": backoff.String(),
})
- time.Sleep(backoff)
+ if sleepErr := sleepWithContext(turnCtx, backoff); sleepErr != nil {
+ if ts.hardAbortRequested() {
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
+ err = sleepErr
+ break
+ }
continue
}
- if isContextError && retry < maxRetries {
+ if isContextError && retry < maxRetries && !ts.opts.NoHistory {
+ al.emitEvent(
+ EventKindLLMRetry,
+ ts.eventMeta("runTurn", "turn.llm.retry"),
+ LLMRetryPayload{
+ Attempt: retry + 1,
+ MaxRetries: maxRetries,
+ Reason: "context_limit",
+ Error: err.Error(),
+ },
+ )
logger.WarnCF(
"agent",
"Context window error detected, attempting compression",
@@ -1183,63 +2002,141 @@ func (al *AgentLoop) runLLMIteration(
},
)
- if retry == 0 && !constants.IsInternalChannel(opts.Channel) {
+ if retry == 0 && !constants.IsInternalChannel(ts.channel) {
al.bus.PublishOutbound(ctx, bus.OutboundMessage{
- Channel: opts.Channel,
- ChatID: opts.ChatID,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
Content: "Context window exceeded. Compressing history and retrying...",
})
}
- al.forceCompression(agent, opts.SessionKey)
- newHistory := agent.Sessions.GetHistory(opts.SessionKey)
- newSummary := agent.Sessions.GetSummary(opts.SessionKey)
- messages = agent.ContextBuilder.BuildMessages(
+ if compression, ok := al.forceCompression(ts.agent, ts.sessionKey); ok {
+ al.emitEvent(
+ EventKindContextCompress,
+ ts.eventMeta("runTurn", "turn.context.compress"),
+ ContextCompressPayload{
+ Reason: ContextCompressReasonRetry,
+ DroppedMessages: compression.DroppedMessages,
+ RemainingMessages: compression.RemainingMessages,
+ },
+ )
+ ts.refreshRestorePointFromSession(ts.agent)
+ }
+
+ newHistory := ts.agent.Sessions.GetHistory(ts.sessionKey)
+ newSummary := ts.agent.Sessions.GetSummary(ts.sessionKey)
+ messages = ts.agent.ContextBuilder.BuildMessages(
newHistory, newSummary, "",
- nil, opts.Channel, opts.ChatID, opts.SenderID, opts.SenderDisplayName,
+ nil, ts.channel, ts.chatID, ts.opts.SenderID, ts.opts.SenderDisplayName,
+ activeSkillNames(ts.agent, ts.opts)...,
)
+ callMessages = messages
+ if gracefulTerminal {
+ callMessages = append(append([]providers.Message(nil), messages...), ts.interruptHintMessage())
+ }
continue
}
break
}
if err != nil {
+ turnStatus = TurnEndStatusError
+ al.emitEvent(
+ EventKindError,
+ ts.eventMeta("runTurn", "turn.error"),
+ ErrorPayload{
+ Stage: "llm",
+ Message: err.Error(),
+ },
+ )
logger.ErrorCF("agent", "LLM call failed",
map[string]any{
- "agent_id": agent.ID,
+ "agent_id": ts.agent.ID,
"iteration": iteration,
- "model": activeModel,
+ "model": llmModel,
"error": err.Error(),
})
- return "", iteration, fmt.Errorf("LLM call failed after retries: %w", err)
+ return turnResult{}, fmt.Errorf("LLM call failed after retries: %w", err)
+ }
+
+ if al.hooks != nil {
+ llmResp, decision := al.hooks.AfterLLM(turnCtx, &LLMHookResponse{
+ Meta: ts.eventMeta("runTurn", "turn.llm.response"),
+ Model: llmModel,
+ Response: response,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ })
+ switch decision.normalizedAction() {
+ case HookActionContinue, HookActionModify:
+ if llmResp != nil && llmResp.Response != nil {
+ response = llmResp.Response
+ }
+ case HookActionAbortTurn:
+ turnStatus = TurnEndStatusError
+ return turnResult{}, al.hookAbortError(ts, "after_llm", decision)
+ case HookActionHardAbort:
+ _ = ts.requestHardAbort()
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
+ }
+
+ // Save finishReason to turnState for SubTurn truncation detection
+ if innerTS := turnStateFromContext(ctx); innerTS != nil {
+ innerTS.SetLastFinishReason(response.FinishReason)
+ // Save usage for token budget tracking
+ if response.Usage != nil {
+ innerTS.SetLastUsage(response.Usage)
+ }
}
go al.handleReasoning(
- ctx,
+ turnCtx,
response.Reasoning,
- opts.Channel,
- al.targetReasoningChannelID(opts.Channel),
+ ts.channel,
+ al.targetReasoningChannelID(ts.channel),
+ )
+ al.emitEvent(
+ EventKindLLMResponse,
+ ts.eventMeta("runTurn", "turn.llm.response"),
+ LLMResponsePayload{
+ ContentLen: len(response.Content),
+ ToolCalls: len(response.ToolCalls),
+ HasReasoning: response.Reasoning != "" || response.ReasoningContent != "",
+ },
)
logger.DebugCF("agent", "LLM response",
map[string]any{
- "agent_id": agent.ID,
+ "agent_id": ts.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,
+ "target_channel": al.targetReasoningChannelID(ts.channel),
+ "channel": ts.channel,
})
- // Check if no tool calls - then check reasoning content if any
- if len(response.ToolCalls) == 0 {
- finalContent = response.Content
- if finalContent == "" && response.ReasoningContent != "" {
- finalContent = response.ReasoningContent
+
+ if len(response.ToolCalls) == 0 || gracefulTerminal {
+ responseContent := response.Content
+ if responseContent == "" && response.ReasoningContent != "" {
+ responseContent = response.ReasoningContent
}
+ if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+ logger.InfoCF("agent", "Steering arrived after direct LLM response; continuing turn",
+ map[string]any{
+ "agent_id": ts.agent.ID,
+ "iteration": iteration,
+ "steering_count": len(steerMsgs),
+ })
+ pendingMessages = append(pendingMessages, steerMsgs...)
+ continue
+ }
+ finalContent = responseContent
logger.InfoCF("agent", "LLM response without tool calls (direct answer)",
map[string]any{
- "agent_id": agent.ID,
+ "agent_id": ts.agent.ID,
"iteration": iteration,
"content_chars": len(finalContent),
})
@@ -1251,20 +2148,18 @@ func (al *AgentLoop) runLLMIteration(
normalizedToolCalls = append(normalizedToolCalls, providers.NormalizeToolCall(tc))
}
- // Log tool calls
toolNames := make([]string, 0, len(normalizedToolCalls))
for _, tc := range normalizedToolCalls {
toolNames = append(toolNames, tc.Name)
}
logger.InfoCF("agent", "LLM requested tool calls",
map[string]any{
- "agent_id": agent.ID,
+ "agent_id": ts.agent.ID,
"tools": toolNames,
"count": len(normalizedToolCalls),
"iteration": iteration,
})
- // Build assistant message with tool calls
assistantMsg := providers.Message{
Role: "assistant",
Content: response.Content,
@@ -1272,13 +2167,11 @@ func (al *AgentLoop) runLLMIteration(
}
for _, tc := range normalizedToolCalls {
argumentsJSON, _ := json.Marshal(tc.Arguments)
- // Copy ExtraContent to ensure thought_signature is persisted for Gemini 3
extraContent := tc.ExtraContent
thoughtSignature := ""
if tc.Function != nil {
thoughtSignature = tc.Function.ThoughtSignature
}
-
assistantMsg.ToolCalls = append(assistantMsg.ToolCalls, providers.ToolCall{
ID: tc.ID,
Type: "function",
@@ -1293,127 +2186,249 @@ func (al *AgentLoop) runLLMIteration(
})
}
messages = append(messages, assistantMsg)
-
- // Save assistant message with tool calls to session
- agent.Sessions.AddFullMessage(opts.SessionKey, assistantMsg)
-
- // Execute tool calls in parallel
- type indexedAgentResult struct {
- result *tools.ToolResult
- tc providers.ToolCall
+ if !ts.opts.NoHistory {
+ ts.agent.Sessions.AddFullMessage(ts.sessionKey, assistantMsg)
+ ts.recordPersistedMessage(assistantMsg)
}
- agentResults := make([]indexedAgentResult, len(normalizedToolCalls))
- var wg sync.WaitGroup
-
+ ts.setPhase(TurnPhaseTools)
for i, tc := range normalizedToolCalls {
- agentResults[i].tc = tc
+ if ts.hardAbortRequested() {
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
- wg.Add(1)
- go func(idx int, tc providers.ToolCall) {
- defer wg.Done()
+ toolName := tc.Name
+ toolArgs := cloneStringAnyMap(tc.Arguments)
- argsJSON, _ := json.Marshal(tc.Arguments)
- argsPreview := utils.Truncate(string(argsJSON), 200)
- logger.InfoCF("agent", fmt.Sprintf("Tool call: %s(%s)", tc.Name, argsPreview),
- map[string]any{
- "agent_id": agent.ID,
- "tool": tc.Name,
- "iteration": iteration,
- })
-
- // Send tool feedback to chat channel if enabled
- if al.cfg.Agents.Defaults.IsToolFeedbackEnabled() && opts.Channel != "" {
- feedbackPreview := utils.Truncate(
- string(argsJSON),
- al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(),
+ if al.hooks != nil {
+ toolReq, decision := al.hooks.BeforeTool(turnCtx, &ToolCallHookRequest{
+ Meta: ts.eventMeta("runTurn", "turn.tool.before"),
+ Tool: toolName,
+ Arguments: toolArgs,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ })
+ switch decision.normalizedAction() {
+ case HookActionContinue, HookActionModify:
+ if toolReq != nil {
+ toolName = toolReq.Tool
+ toolArgs = toolReq.Arguments
+ }
+ case HookActionDenyTool:
+ denyContent := hookDeniedToolContent("Tool execution denied by hook", decision.Reason)
+ al.emitEvent(
+ EventKindToolExecSkipped,
+ ts.eventMeta("runTurn", "turn.tool.skipped"),
+ ToolExecSkippedPayload{
+ Tool: toolName,
+ Reason: denyContent,
+ },
)
- feedbackMsg := fmt.Sprintf("\U0001f527 `%s`\n```\n%s\n```", tc.Name, feedbackPreview)
- fbCtx, fbCancel := context.WithTimeout(ctx, 3*time.Second)
- _ = al.bus.PublishOutbound(fbCtx, bus.OutboundMessage{
- Channel: opts.Channel,
- ChatID: opts.ChatID,
- Content: feedbackMsg,
- })
- fbCancel()
+ deniedMsg := providers.Message{
+ Role: "tool",
+ Content: denyContent,
+ ToolCallID: tc.ID,
+ }
+ messages = append(messages, deniedMsg)
+ if !ts.opts.NoHistory {
+ ts.agent.Sessions.AddFullMessage(ts.sessionKey, deniedMsg)
+ ts.recordPersistedMessage(deniedMsg)
+ }
+ continue
+ case HookActionAbortTurn:
+ turnStatus = TurnEndStatusError
+ return turnResult{}, al.hookAbortError(ts, "before_tool", decision)
+ case HookActionHardAbort:
+ _ = ts.requestHardAbort()
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
}
+ }
- // Create async callback for tools that implement AsyncExecutor.
- // When the background work completes, this publishes the result
- // as an inbound system message so processSystemMessage routes it
- // back to the user via the normal agent loop.
- asyncCallback := func(_ context.Context, result *tools.ToolResult) {
- // Send ForUser content directly to the user (immediate feedback),
- // mirroring the synchronous tool execution path.
- if !result.Silent && result.ForUser != "" {
- outCtx, outCancel := context.WithTimeout(context.Background(), 5*time.Second)
- defer outCancel()
- _ = al.bus.PublishOutbound(outCtx, bus.OutboundMessage{
- Channel: opts.Channel,
- ChatID: opts.ChatID,
- Content: result.ForUser,
- })
+ if al.hooks != nil {
+ approval := al.hooks.ApproveTool(turnCtx, &ToolApprovalRequest{
+ Meta: ts.eventMeta("runTurn", "turn.tool.approve"),
+ Tool: toolName,
+ Arguments: toolArgs,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ })
+ if !approval.Approved {
+ denyContent := hookDeniedToolContent("Tool execution denied by approval hook", approval.Reason)
+ al.emitEvent(
+ EventKindToolExecSkipped,
+ ts.eventMeta("runTurn", "turn.tool.skipped"),
+ ToolExecSkippedPayload{
+ Tool: toolName,
+ Reason: denyContent,
+ },
+ )
+ deniedMsg := providers.Message{
+ Role: "tool",
+ Content: denyContent,
+ ToolCallID: tc.ID,
}
-
- // Determine content for the agent loop (ForLLM or error).
- content := result.ForLLM
- if content == "" && result.Err != nil {
- content = result.Err.Error()
+ messages = append(messages, deniedMsg)
+ if !ts.opts.NoHistory {
+ ts.agent.Sessions.AddFullMessage(ts.sessionKey, deniedMsg)
+ ts.recordPersistedMessage(deniedMsg)
}
- if content == "" {
- return
- }
-
- logger.InfoCF("agent", "Async tool completed, publishing result",
- map[string]any{
- "tool": tc.Name,
- "content_len": len(content),
- "channel": opts.Channel,
- })
-
- pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
- defer pubCancel()
- _ = al.bus.PublishInbound(pubCtx, bus.InboundMessage{
- Channel: "system",
- SenderID: fmt.Sprintf("async:%s", tc.Name),
- ChatID: fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID),
- Content: content,
- })
+ continue
}
+ }
- toolResult := agent.Tools.ExecuteWithContext(
- ctx,
- tc.Name,
- tc.Arguments,
- opts.Channel,
- opts.ChatID,
- asyncCallback,
+ argsJSON, _ := json.Marshal(toolArgs)
+ argsPreview := utils.Truncate(string(argsJSON), 200)
+ logger.InfoCF("agent", fmt.Sprintf("Tool call: %s(%s)", toolName, argsPreview),
+ map[string]any{
+ "agent_id": ts.agent.ID,
+ "tool": toolName,
+ "iteration": iteration,
+ })
+ al.emitEvent(
+ EventKindToolExecStart,
+ ts.eventMeta("runTurn", "turn.tool.start"),
+ ToolExecStartPayload{
+ Tool: toolName,
+ Arguments: cloneEventArguments(toolArgs),
+ },
+ )
+
+ // Send tool feedback to chat channel if enabled (from HEAD)
+ if al.cfg.Agents.Defaults.IsToolFeedbackEnabled() && ts.channel != "" {
+ feedbackPreview := utils.Truncate(
+ string(argsJSON),
+ al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(),
)
- agentResults[idx].result = toolResult
- }(i, tc)
- }
- wg.Wait()
+ feedbackMsg := fmt.Sprintf("\U0001f527 `%s`\n```\n%s\n```", tc.Name, feedbackPreview)
+ fbCtx, fbCancel := context.WithTimeout(turnCtx, 3*time.Second)
+ _ = al.bus.PublishOutbound(fbCtx, bus.OutboundMessage{
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ Content: feedbackMsg,
+ })
+ fbCancel()
+ }
- // Process results in original order (send to user, save to session)
- for _, r := range agentResults {
- // Send ForUser content to user immediately if not Silent
- if !r.result.Silent && r.result.ForUser != "" && opts.SendResponse {
+ toolCallID := tc.ID
+ toolIteration := iteration
+ asyncToolName := toolName
+ asyncCallback := func(_ context.Context, result *tools.ToolResult) {
+ // Send ForUser content directly to the user (immediate feedback),
+ // mirroring the synchronous tool execution path.
+ if !result.Silent && result.ForUser != "" {
+ outCtx, outCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer outCancel()
+ _ = al.bus.PublishOutbound(outCtx, bus.OutboundMessage{
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ Content: result.ForUser,
+ })
+ }
+
+ // Determine content for the agent loop (ForLLM or error).
+ content := result.ForLLM
+ if content == "" && result.Err != nil {
+ content = result.Err.Error()
+ }
+ if content == "" {
+ return
+ }
+
+ logger.InfoCF("agent", "Async tool completed, publishing result",
+ map[string]any{
+ "tool": asyncToolName,
+ "content_len": len(content),
+ "channel": ts.channel,
+ })
+ al.emitEvent(
+ EventKindFollowUpQueued,
+ ts.scope.meta(toolIteration, "runTurn", "turn.follow_up.queued"),
+ FollowUpQueuedPayload{
+ SourceTool: asyncToolName,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ ContentLen: len(content),
+ },
+ )
+
+ pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer pubCancel()
+ _ = al.bus.PublishInbound(pubCtx, bus.InboundMessage{
+ Channel: "system",
+ SenderID: fmt.Sprintf("async:%s", asyncToolName),
+ ChatID: fmt.Sprintf("%s:%s", ts.channel, ts.chatID),
+ Content: content,
+ })
+ }
+
+ toolStart := time.Now()
+ toolResult := ts.agent.Tools.ExecuteWithContext(
+ turnCtx,
+ toolName,
+ toolArgs,
+ ts.channel,
+ ts.chatID,
+ asyncCallback,
+ )
+ toolDuration := time.Since(toolStart)
+
+ if ts.hardAbortRequested() {
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
+
+ if al.hooks != nil {
+ toolResp, decision := al.hooks.AfterTool(turnCtx, &ToolResultHookResponse{
+ Meta: ts.eventMeta("runTurn", "turn.tool.after"),
+ Tool: toolName,
+ Arguments: toolArgs,
+ Result: toolResult,
+ Duration: toolDuration,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ })
+ switch decision.normalizedAction() {
+ case HookActionContinue, HookActionModify:
+ if toolResp != nil {
+ if toolResp.Tool != "" {
+ toolName = toolResp.Tool
+ }
+ if toolResp.Result != nil {
+ toolResult = toolResp.Result
+ }
+ }
+ case HookActionAbortTurn:
+ turnStatus = TurnEndStatusError
+ return turnResult{}, al.hookAbortError(ts, "after_tool", decision)
+ case HookActionHardAbort:
+ _ = ts.requestHardAbort()
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
+ }
+
+ if toolResult == nil {
+ toolResult = tools.ErrorResult("hook returned nil tool result")
+ }
+
+ if !toolResult.Silent && toolResult.ForUser != "" && ts.opts.SendResponse {
al.bus.PublishOutbound(ctx, bus.OutboundMessage{
- Channel: opts.Channel,
- ChatID: opts.ChatID,
- Content: r.result.ForUser,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ Content: toolResult.ForUser,
})
logger.DebugCF("agent", "Sent tool result to user",
map[string]any{
- "tool": r.tc.Name,
- "content_len": len(r.result.ForUser),
+ "tool": toolName,
+ "content_len": len(toolResult.ForUser),
})
}
- // If tool returned media refs, publish them as outbound media
- if len(r.result.Media) > 0 {
- parts := make([]bus.MediaPart, 0, len(r.result.Media))
- for _, ref := range r.result.Media {
+ if len(toolResult.Media) > 0 {
+ parts := make([]bus.MediaPart, 0, len(toolResult.Media))
+ for _, ref := range toolResult.Media {
part := bus.MediaPart{Ref: ref}
if al.mediaStore != nil {
if _, meta, err := al.mediaStore.ResolveWithMeta(ref); err == nil {
@@ -1425,42 +2440,195 @@ func (al *AgentLoop) runLLMIteration(
parts = append(parts, part)
}
al.bus.PublishOutboundMedia(ctx, bus.OutboundMediaMessage{
- Channel: opts.Channel,
- ChatID: opts.ChatID,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
Parts: parts,
})
}
- // Determine content for LLM based on tool result
- contentForLLM := r.result.ForLLM
- if contentForLLM == "" && r.result.Err != nil {
- contentForLLM = r.result.Err.Error()
+ contentForLLM := toolResult.ForLLM
+ if contentForLLM == "" && toolResult.Err != nil {
+ contentForLLM = toolResult.Err.Error()
}
toolResultMsg := providers.Message{
Role: "tool",
Content: contentForLLM,
- ToolCallID: r.tc.ID,
+ ToolCallID: toolCallID,
}
+ al.emitEvent(
+ EventKindToolExecEnd,
+ ts.eventMeta("runTurn", "turn.tool.end"),
+ ToolExecEndPayload{
+ Tool: toolName,
+ Duration: toolDuration,
+ ForLLMLen: len(contentForLLM),
+ ForUserLen: len(toolResult.ForUser),
+ IsError: toolResult.IsError,
+ Async: toolResult.Async,
+ },
+ )
messages = append(messages, toolResultMsg)
+ if !ts.opts.NoHistory {
+ ts.agent.Sessions.AddFullMessage(ts.sessionKey, toolResultMsg)
+ ts.recordPersistedMessage(toolResultMsg)
+ }
- // Save tool result message to session
- agent.Sessions.AddFullMessage(opts.SessionKey, toolResultMsg)
+ if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+ pendingMessages = append(pendingMessages, steerMsgs...)
+ }
+
+ skipReason := ""
+ skipMessage := ""
+ if len(pendingMessages) > 0 {
+ skipReason = "queued user steering message"
+ skipMessage = "Skipped due to queued user message."
+ } else if gracefulPending, _ := ts.gracefulInterruptRequested(); gracefulPending {
+ skipReason = "graceful interrupt requested"
+ skipMessage = "Skipped due to graceful interrupt."
+ }
+
+ if skipReason != "" {
+ remaining := len(normalizedToolCalls) - i - 1
+ if remaining > 0 {
+ logger.InfoCF("agent", "Turn checkpoint: skipping remaining tools",
+ map[string]any{
+ "agent_id": ts.agent.ID,
+ "completed": i + 1,
+ "skipped": remaining,
+ "reason": skipReason,
+ })
+ for j := i + 1; j < len(normalizedToolCalls); j++ {
+ skippedTC := normalizedToolCalls[j]
+ al.emitEvent(
+ EventKindToolExecSkipped,
+ ts.eventMeta("runTurn", "turn.tool.skipped"),
+ ToolExecSkippedPayload{
+ Tool: skippedTC.Name,
+ Reason: skipReason,
+ },
+ )
+ skippedMsg := providers.Message{
+ Role: "tool",
+ Content: skipMessage,
+ ToolCallID: skippedTC.ID,
+ }
+ messages = append(messages, skippedMsg)
+ if !ts.opts.NoHistory {
+ ts.agent.Sessions.AddFullMessage(ts.sessionKey, skippedMsg)
+ ts.recordPersistedMessage(skippedMsg)
+ }
+ }
+ }
+ break
+ }
+
+ // Also poll for any SubTurn results that arrived during tool execution.
+ if ts.pendingResults != nil {
+ select {
+ case result, ok := <-ts.pendingResults:
+ if ok && result != nil && result.ForLLM != "" {
+ msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", result.ForLLM)}
+ messages = append(messages, msg)
+ ts.agent.Sessions.AddFullMessage(ts.sessionKey, msg)
+ }
+ default:
+ // No results available
+ }
+ }
}
- // Tick down TTL of discovered tools after processing tool results.
- // Only reached when tool calls were made (the loop continues);
- // the break on no-tool-call responses skips this.
- // NOTE: This is safe because processMessage is sequential per agent.
- // If per-agent concurrency is added, TTL consistency between
- // ToProviderDefs and Get must be re-evaluated.
- agent.Tools.TickTTL()
+ ts.agent.Tools.TickTTL()
logger.DebugCF("agent", "TTL tick after tool execution", map[string]any{
- "agent_id": agent.ID, "iteration": iteration,
+ "agent_id": ts.agent.ID, "iteration": iteration,
})
}
- return finalContent, iteration, nil
+ if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+ logger.InfoCF("agent", "Steering arrived after turn completion; continuing turn before finalizing",
+ map[string]any{
+ "agent_id": ts.agent.ID,
+ "steering_count": len(steerMsgs),
+ "session_key": ts.sessionKey,
+ })
+ pendingMessages = append(pendingMessages, steerMsgs...)
+ finalContent = ""
+ goto turnLoop
+ }
+
+ if ts.hardAbortRequested() {
+ turnStatus = TurnEndStatusAborted
+ return al.abortTurn(ts)
+ }
+
+ if finalContent == "" {
+ if ts.currentIteration() >= ts.agent.MaxIterations && ts.agent.MaxIterations > 0 {
+ finalContent = toolLimitResponse
+ } else {
+ finalContent = ts.opts.DefaultResponse
+ }
+ }
+
+ ts.setPhase(TurnPhaseFinalizing)
+ ts.setFinalContent(finalContent)
+ if !ts.opts.NoHistory {
+ finalMsg := providers.Message{Role: "assistant", Content: finalContent}
+ ts.agent.Sessions.AddMessage(ts.sessionKey, finalMsg.Role, finalMsg.Content)
+ ts.recordPersistedMessage(finalMsg)
+ if err := ts.agent.Sessions.Save(ts.sessionKey); err != nil {
+ turnStatus = TurnEndStatusError
+ al.emitEvent(
+ EventKindError,
+ ts.eventMeta("runTurn", "turn.error"),
+ ErrorPayload{
+ Stage: "session_save",
+ Message: err.Error(),
+ },
+ )
+ return turnResult{}, err
+ }
+ }
+
+ if ts.opts.EnableSummary {
+ al.maybeSummarize(ts.agent, ts.sessionKey, ts.scope)
+ }
+
+ ts.setPhase(TurnPhaseCompleted)
+ return turnResult{
+ finalContent: finalContent,
+ status: turnStatus,
+ followUps: append([]bus.InboundMessage(nil), ts.followUps...),
+ }, nil
+}
+
+func (al *AgentLoop) abortTurn(ts *turnState) (turnResult, error) {
+ ts.setPhase(TurnPhaseAborted)
+ if !ts.opts.NoHistory {
+ if err := ts.restoreSession(ts.agent); err != nil {
+ al.emitEvent(
+ EventKindError,
+ ts.eventMeta("abortTurn", "turn.error"),
+ ErrorPayload{
+ Stage: "session_restore",
+ Message: err.Error(),
+ },
+ )
+ return turnResult{}, err
+ }
+ }
+ return turnResult{status: TurnEndStatusAborted}, nil
+}
+
+func sleepWithContext(ctx context.Context, d time.Duration) error {
+ timer := time.NewTimer(d)
+ defer timer.Stop()
+
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ case <-timer.C:
+ return nil
+ }
}
// selectCandidates returns the model candidates and resolved model name to use
@@ -1477,7 +2645,7 @@ func (al *AgentLoop) selectCandidates(
history []providers.Message,
) (candidates []providers.FallbackCandidate, model string) {
if agent.Router == nil || len(agent.LightCandidates) == 0 {
- return agent.Candidates, agent.Model
+ return agent.Candidates, resolvedCandidateModel(agent.Candidates, agent.Model)
}
_, usedLight, score := agent.Router.SelectModel(userMsg, history, agent.Model)
@@ -1488,7 +2656,7 @@ func (al *AgentLoop) selectCandidates(
"score": score,
"threshold": agent.Router.Threshold(),
})
- return agent.Candidates, agent.Model
+ return agent.Candidates, resolvedCandidateModel(agent.Candidates, agent.Model)
}
logger.InfoCF("agent", "Model routing: light model selected",
@@ -1498,11 +2666,11 @@ func (al *AgentLoop) selectCandidates(
"score": score,
"threshold": agent.Router.Threshold(),
})
- return agent.LightCandidates, agent.Router.LightModel()
+ return agent.LightCandidates, resolvedCandidateModel(agent.LightCandidates, agent.Router.LightModel())
}
// maybeSummarize triggers summarization if the session history exceeds thresholds.
-func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey, channel, chatID string) {
+func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey string, turnScope turnEventScope) {
newHistory := agent.Sessions.GetHistory(sessionKey)
tokenEstimate := al.estimateTokens(newHistory)
threshold := agent.ContextWindow * agent.SummarizeTokenPercent / 100
@@ -1513,63 +2681,91 @@ func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey, channel, c
go func() {
defer al.summarizing.Delete(summarizeKey)
logger.Debug("Memory threshold reached. Optimizing conversation history...")
- al.summarizeSession(agent, sessionKey)
+ al.summarizeSession(agent, sessionKey, turnScope)
}()
}
}
}
+type compressionResult struct {
+ DroppedMessages int
+ RemainingMessages int
+}
+
// forceCompression aggressively reduces context when the limit is hit.
-// It drops the oldest 50% of messages (keeping system prompt and last user message).
-func (al *AgentLoop) forceCompression(agent *AgentInstance, sessionKey string) {
+// It drops the oldest ~50% of Turns (a Turn is a complete user→LLM→response
+// cycle, as defined in #1316), so tool-call sequences are never split.
+//
+// If the history is a single Turn with no safe split point, the function
+// falls back to keeping only the most recent user message. This breaks
+// Turn atomicity as a last resort to avoid a context-exceeded loop.
+//
+// Session history contains only user/assistant/tool messages — the system
+// prompt is built dynamically by BuildMessages and is NOT stored here.
+// The compression note is recorded in the session summary so that
+// BuildMessages can include it in the next system prompt.
+func (al *AgentLoop) forceCompression(agent *AgentInstance, sessionKey string) (compressionResult, bool) {
history := agent.Sessions.GetHistory(sessionKey)
- if len(history) <= 4 {
- return
+ if len(history) <= 2 {
+ return compressionResult{}, false
}
- // Keep system prompt (usually [0]) and the very last message (user's trigger)
- // We want to drop the oldest half of the *conversation*
- // Assuming [0] is system, [1:] is conversation
- conversation := history[1 : len(history)-1]
- if len(conversation) == 0 {
- return
+ // Split at a Turn boundary so no tool-call sequence is torn apart.
+ // parseTurnBoundaries gives us the start of each Turn; we drop the
+ // oldest half of Turns and keep the most recent ones.
+ turns := parseTurnBoundaries(history)
+ var mid int
+ if len(turns) >= 2 {
+ mid = turns[len(turns)/2]
+ } else {
+ // Fewer than 2 Turns — fall back to message-level midpoint
+ // aligned to the nearest Turn boundary.
+ mid = findSafeBoundary(history, len(history)/2)
+ }
+ var keptHistory []providers.Message
+ if mid <= 0 {
+ // No safe Turn boundary — the entire history is a single Turn
+ // (e.g. one user message followed by a massive tool response).
+ // Keeping everything would leave the agent stuck in a context-
+ // exceeded loop, so fall back to keeping only the most recent
+ // user message. This breaks Turn atomicity as a last resort.
+ for i := len(history) - 1; i >= 0; i-- {
+ if history[i].Role == "user" {
+ keptHistory = []providers.Message{history[i]}
+ break
+ }
+ }
+ } else {
+ keptHistory = history[mid:]
}
- // Helper to find the mid-point of the conversation
- mid := len(conversation) / 2
+ droppedCount := len(history) - len(keptHistory)
- // New history structure:
- // 1. System Prompt (with compression note appended)
- // 2. Second half of conversation
- // 3. Last message
-
- droppedCount := mid
- keptConversation := conversation[mid:]
-
- 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
+ // Record compression in the session summary so BuildMessages includes it
+ // in the system prompt. We do not modify history messages themselves.
+ existingSummary := agent.Sessions.GetSummary(sessionKey)
compressionNote := fmt.Sprintf(
- "\n\n[System Note: Emergency compression dropped %d oldest messages due to context limit]",
+ "[Emergency compression dropped %d oldest messages due to context limit]",
droppedCount,
)
- enhancedSystemPrompt := history[0]
- enhancedSystemPrompt.Content = enhancedSystemPrompt.Content + compressionNote
- newHistory = append(newHistory, enhancedSystemPrompt)
+ if existingSummary != "" {
+ compressionNote = existingSummary + "\n\n" + compressionNote
+ }
+ agent.Sessions.SetSummary(sessionKey, compressionNote)
- newHistory = append(newHistory, keptConversation...)
- newHistory = append(newHistory, history[len(history)-1]) // Last message
-
- // Update session
- agent.Sessions.SetHistory(sessionKey, newHistory)
+ agent.Sessions.SetHistory(sessionKey, keptHistory)
agent.Sessions.Save(sessionKey)
logger.WarnCF("agent", "Forced compression executed", map[string]any{
"session_key": sessionKey,
"dropped_msgs": droppedCount,
- "new_count": len(newHistory),
+ "new_count": len(keptHistory),
})
+
+ return compressionResult{
+ DroppedMessages: droppedCount,
+ RemainingMessages: len(keptHistory),
+ }, true
}
// GetStartupInfo returns information about loaded tools and skills for logging.
@@ -1661,19 +2857,25 @@ func formatToolsForLog(toolDefs []providers.ToolDefinition) string {
}
// summarizeSession summarizes the conversation history for a session.
-func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
+func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string, turnScope turnEventScope) {
ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
defer cancel()
history := agent.Sessions.GetHistory(sessionKey)
summary := agent.Sessions.GetSummary(sessionKey)
- // Keep last 4 messages for continuity
+ // Keep the most recent Turns for continuity, aligned to a Turn boundary
+ // so that no tool-call sequence is split.
if len(history) <= 4 {
return
}
- toSummarize := history[:len(history)-4]
+ safeCut := findSafeBoundary(history, len(history)-4)
+ if safeCut <= 0 {
+ return
+ }
+ keepCount := len(history) - safeCut
+ toSummarize := history[:safeCut]
// Oversized Message Guard
maxMessageTokens := agent.ContextWindow / 2
@@ -1738,8 +2940,18 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
if finalSummary != "" {
agent.Sessions.SetSummary(sessionKey, finalSummary)
- agent.Sessions.TruncateHistory(sessionKey, 4)
+ agent.Sessions.TruncateHistory(sessionKey, keepCount)
agent.Sessions.Save(sessionKey)
+ al.emitEvent(
+ EventKindSessionSummarize,
+ turnScope.meta(0, "summarizeSession", "turn.session.summarize"),
+ SessionSummarizePayload{
+ SummarizedMessages: len(validMessages),
+ KeptMessages: keepCount,
+ SummaryLen: len(finalSummary),
+ OmittedOversized: omitted,
+ },
+ )
}
}
@@ -1876,15 +3088,14 @@ func (al *AgentLoop) summarizeBatch(
}
// estimateTokens estimates the number of tokens in a message list.
-// Uses a safe heuristic of 2.5 characters per token to account for CJK and other
-// overheads better than the previous 3 chars/token.
+// Counts Content, ToolCalls arguments, and ToolCallID metadata so that
+// tool-heavy conversations are not systematically undercounted.
func (al *AgentLoop) estimateTokens(messages []providers.Message) int {
- totalChars := 0
+ total := 0
for _, m := range messages {
- totalChars += utf8.RuneCountInString(m.Content)
+ total += estimateMessageTokens(m)
}
- // 2.5 chars per token = totalChars * 2 / 5
- return totalChars * 2 / 5
+ return total
}
func (al *AgentLoop) handleCommand(
@@ -1897,6 +3108,10 @@ func (al *AgentLoop) handleCommand(
return "", false
}
+ if matched, handled, reply := al.applyExplicitSkillCommand(msg.Content, agent, opts); matched {
+ return reply, handled
+ }
+
if al.cmdRegistry == nil {
return "", false
}
@@ -1943,6 +3158,13 @@ func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance, opts *processOpt
}
return al.channelManager.GetEnabledChannels()
},
+ GetActiveTurn: func() any {
+ info := al.GetActiveTurn()
+ if info == nil {
+ return nil
+ }
+ return info
+ },
SwitchChannel: func(value string) error {
if al.channelManager == nil {
return fmt.Errorf("channel manager not initialized")
@@ -1953,6 +3175,9 @@ func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance, opts *processOpt
return nil
},
}
+ if agent != nil && agent.ContextBuilder != nil {
+ rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
+ }
rt.ReloadConfig = func() error {
if al.reloadFunc == nil {
return fmt.Errorf("reload not configured")
@@ -1961,11 +3186,37 @@ func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance, opts *processOpt
}
if agent != nil {
rt.GetModelInfo = func() (string, string) {
- return agent.Model, cfg.Agents.Defaults.Provider
+ return agent.Model, resolvedCandidateProvider(agent.Candidates, cfg.Agents.Defaults.Provider)
}
rt.SwitchModel = func(value string) (string, error) {
+ value = strings.TrimSpace(value)
+ modelCfg, err := resolvedModelConfig(cfg, value, agent.Workspace)
+ if err != nil {
+ return "", err
+ }
+
+ nextProvider, _, err := providers.CreateProviderFromConfig(modelCfg)
+ if err != nil {
+ return "", fmt.Errorf("failed to initialize model %q: %w", value, err)
+ }
+
+ nextCandidates := resolveModelCandidates(cfg, cfg.Agents.Defaults.Provider, modelCfg.Model, agent.Fallbacks)
+ if len(nextCandidates) == 0 {
+ return "", fmt.Errorf("model %q did not resolve to any provider candidates", value)
+ }
+
oldModel := agent.Model
+ oldProvider := agent.Provider
agent.Model = value
+ agent.Provider = nextProvider
+ agent.Candidates = nextCandidates
+ agent.ThinkingLevel = parseThinkingLevel(modelCfg.ThinkingLevel)
+
+ if oldProvider != nil && oldProvider != nextProvider {
+ if stateful, ok := oldProvider.(providers.StatefulProvider); ok {
+ stateful.Close()
+ }
+ }
return oldModel, nil
}
@@ -1986,6 +3237,146 @@ func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance, opts *processOpt
return rt
}
+func activeSkillNames(agent *AgentInstance, opts processOptions) []string {
+ var out []string
+ seen := make(map[string]struct{})
+
+ appendNames := func(names []string) {
+ for _, name := range names {
+ name = strings.TrimSpace(name)
+ if name == "" {
+ continue
+ }
+ if _, exists := seen[name]; exists {
+ continue
+ }
+ seen[name] = struct{}{}
+ out = append(out, name)
+ }
+ }
+
+ if agent != nil {
+ appendNames(agent.SkillsFilter)
+ }
+ appendNames(opts.ForcedSkills)
+
+ return out
+}
+
+func (al *AgentLoop) applyExplicitSkillCommand(
+ raw string,
+ agent *AgentInstance,
+ opts *processOptions,
+) (matched bool, handled bool, reply string) {
+ commandName, ok := commands.CommandName(raw)
+ if !ok || commandName != "use" {
+ return false, false, ""
+ }
+
+ if agent == nil || agent.ContextBuilder == nil {
+ return true, true, commandsUnavailableSkillMessage()
+ }
+
+ fields := strings.Fields(strings.TrimSpace(raw))
+ if len(fields) < 2 {
+ return true, true, buildUseCommandHelp(agent)
+ }
+
+ if strings.EqualFold(fields[1], "clear") || strings.EqualFold(fields[1], "off") {
+ al.clearPendingSkills(opts.SessionKey)
+ return true, true, "Cleared pending skill override."
+ }
+
+ canonicalSkill, ok := agent.ContextBuilder.ResolveSkillName(fields[1])
+ if !ok {
+ return true, true, fmt.Sprintf("Unknown skill: %s\nUse /list skills to see installed skills.", fields[1])
+ }
+
+ if len(fields) == 2 {
+ al.setPendingSkills(opts.SessionKey, []string{canonicalSkill})
+ return true, true, fmt.Sprintf(
+ "Skill %q is armed for your next message.\nSend your next request normally, or use /use clear to cancel.",
+ canonicalSkill,
+ )
+ }
+
+ message := strings.TrimSpace(strings.Join(fields[2:], " "))
+ if message == "" {
+ return true, true, buildUseCommandHelp(agent)
+ }
+
+ opts.UserMessage = message
+ opts.ForcedSkills = append(opts.ForcedSkills, canonicalSkill)
+ return true, false, ""
+}
+
+func commandsUnavailableSkillMessage() string {
+ return "Skill selection is unavailable in the current context."
+}
+
+func buildUseCommandHelp(agent *AgentInstance) string {
+ if agent == nil || agent.ContextBuilder == nil {
+ return "Usage: /use [message]"
+ }
+
+ names := agent.ContextBuilder.ListSkillNames()
+ if len(names) == 0 {
+ return "Usage: /use [message]\nNo installed skills found."
+ }
+
+ return fmt.Sprintf(
+ "Usage: /use [message]\n\nInstalled Skills:\n- %s\n\nUse /use to apply a skill to your next message, or /use to force it immediately.",
+ strings.Join(names, "\n- "),
+ )
+}
+
+func (al *AgentLoop) setPendingSkills(sessionKey string, skillNames []string) {
+ sessionKey = strings.TrimSpace(sessionKey)
+ if sessionKey == "" || len(skillNames) == 0 {
+ return
+ }
+
+ filtered := make([]string, 0, len(skillNames))
+ for _, name := range skillNames {
+ name = strings.TrimSpace(name)
+ if name != "" {
+ filtered = append(filtered, name)
+ }
+ }
+ if len(filtered) == 0 {
+ return
+ }
+
+ al.pendingSkills.Store(sessionKey, filtered)
+}
+
+func (al *AgentLoop) takePendingSkills(sessionKey string) []string {
+ sessionKey = strings.TrimSpace(sessionKey)
+ if sessionKey == "" {
+ return nil
+ }
+
+ value, ok := al.pendingSkills.LoadAndDelete(sessionKey)
+ if !ok {
+ return nil
+ }
+
+ skills, ok := value.([]string)
+ if !ok {
+ return nil
+ }
+
+ return append([]string(nil), skills...)
+}
+
+func (al *AgentLoop) clearPendingSkills(sessionKey string) {
+ sessionKey = strings.TrimSpace(sessionKey)
+ if sessionKey == "" {
+ return
+ }
+ al.pendingSkills.Delete(sessionKey)
+}
+
func mapCommandError(result commands.ExecuteResult) string {
if result.Command == "" {
return fmt.Sprintf("Failed to execute command: %v", result.Err)
diff --git a/pkg/agent/loop_test.go b/pkg/agent/loop_test.go
index 8432ccac4..ad0022138 100644
--- a/pkg/agent/loop_test.go
+++ b/pkg/agent/loop_test.go
@@ -2,7 +2,10 @@ package agent
import (
"context"
+ "encoding/json"
"fmt"
+ "net/http"
+ "net/http/httptest"
"os"
"path/filepath"
"slices"
@@ -64,7 +67,7 @@ func newTestAgentLoop(
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -87,7 +90,7 @@ func TestProcessMessage_IncludesCurrentSenderInDynamicContext(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -129,6 +132,163 @@ func TestProcessMessage_IncludesCurrentSenderInDynamicContext(t *testing.T) {
}
}
+func TestProcessMessage_UseCommandLoadsRequestedSkill(t *testing.T) {
+ tmpDir := t.TempDir()
+ skillDir := filepath.Join(tmpDir, "skills", "shell")
+ if err := os.MkdirAll(skillDir, 0o755); err != nil {
+ t.Fatalf("mkdir skill dir: %v", err)
+ }
+ if err := os.WriteFile(
+ filepath.Join(skillDir, "SKILL.md"),
+ []byte("# shell\n\nPrefer concise shell commands and explain them briefly."),
+ 0o644,
+ ); err != nil {
+ t.Fatalf("write skill file: %v", err)
+ }
+
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Workspace: tmpDir,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &recordingProvider{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ response, err := al.processMessage(context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "telegram:123",
+ ChatID: "chat-1",
+ Content: "/use shell explain how to list files",
+ })
+ if err != nil {
+ t.Fatalf("processMessage() error = %v", err)
+ }
+ if response != "Mock response" {
+ t.Fatalf("processMessage() response = %q, want %q", response, "Mock response")
+ }
+ if len(provider.lastMessages) == 0 {
+ t.Fatal("provider did not receive any messages")
+ }
+
+ systemPrompt := provider.lastMessages[0].Content
+ if !strings.Contains(systemPrompt, "# Active Skills") {
+ t.Fatalf("system prompt missing active skills section:\n%s", systemPrompt)
+ }
+ if !strings.Contains(systemPrompt, "### Skill: shell") {
+ t.Fatalf("system prompt missing requested skill content:\n%s", systemPrompt)
+ }
+
+ lastMessage := provider.lastMessages[len(provider.lastMessages)-1]
+ if lastMessage.Role != "user" || lastMessage.Content != "explain how to list files" {
+ t.Fatalf("last provider message = %+v, want rewritten user message", lastMessage)
+ }
+}
+
+func TestHandleCommand_UseCommandRejectsUnknownSkill(t *testing.T) {
+ tmpDir := t.TempDir()
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Workspace: tmpDir,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &recordingProvider{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+ agent := al.GetRegistry().GetDefaultAgent()
+
+ opts := processOptions{}
+ reply, handled := al.handleCommand(context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "telegram:123",
+ ChatID: "chat-1",
+ Content: "/use missing explain how to list files",
+ }, agent, &opts)
+ if !handled {
+ t.Fatal("expected /use with unknown skill to be handled")
+ }
+ if !strings.Contains(reply, "Unknown skill: missing") {
+ t.Fatalf("reply = %q, want unknown skill error", reply)
+ }
+}
+
+func TestProcessMessage_UseCommandArmsSkillForNextMessage(t *testing.T) {
+ tmpDir := t.TempDir()
+ skillDir := filepath.Join(tmpDir, "skills", "shell")
+ if err := os.MkdirAll(skillDir, 0o755); err != nil {
+ t.Fatalf("mkdir skill dir: %v", err)
+ }
+ if err := os.WriteFile(
+ filepath.Join(skillDir, "SKILL.md"),
+ []byte("# shell\n\nPrefer concise shell commands and explain them briefly."),
+ 0o644,
+ ); err != nil {
+ t.Fatalf("write skill file: %v", err)
+ }
+
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Workspace: tmpDir,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &recordingProvider{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ response, err := al.processMessage(context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "telegram:123",
+ ChatID: "chat-1",
+ Content: "/use shell",
+ })
+ if err != nil {
+ t.Fatalf("processMessage() arm error = %v", err)
+ }
+ if !strings.Contains(response, `Skill "shell" is armed for your next message.`) {
+ t.Fatalf("arm response = %q, want armed confirmation", response)
+ }
+
+ response, err = al.processMessage(context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "telegram:123",
+ ChatID: "chat-1",
+ Content: "explain how to list files",
+ })
+ if err != nil {
+ t.Fatalf("processMessage() follow-up error = %v", err)
+ }
+ if response != "Mock response" {
+ t.Fatalf("follow-up response = %q, want %q", response, "Mock response")
+ }
+ if len(provider.lastMessages) == 0 {
+ t.Fatal("provider did not receive any messages")
+ }
+
+ systemPrompt := provider.lastMessages[0].Content
+ if !strings.Contains(systemPrompt, "### Skill: shell") {
+ t.Fatalf("system prompt missing pending skill content:\n%s", systemPrompt)
+ }
+ lastMessage := provider.lastMessages[len(provider.lastMessages)-1]
+ if lastMessage.Role != "user" || lastMessage.Content != "explain how to list files" {
+ t.Fatalf("last provider message = %+v, want unchanged follow-up user message", lastMessage)
+ }
+}
+
func TestRecordLastChannel(t *testing.T) {
al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
defer cleanup()
@@ -176,7 +336,7 @@ func TestNewAgentLoop_StateInitialized(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -212,7 +372,7 @@ func TestToolRegistry_ToolRegistration(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -269,7 +429,7 @@ func TestToolRegistry_GetDefinitions(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -305,7 +465,7 @@ func TestAgentLoop_GetStartupInfo(t *testing.T) {
cfg := config.DefaultConfig()
cfg.Agents.Defaults.Workspace = tmpDir
- cfg.Agents.Defaults.Model = "test-model"
+ cfg.Agents.Defaults.ModelName = "test-model"
cfg.Agents.Defaults.MaxTokens = 4096
cfg.Agents.Defaults.MaxToolIterations = 10
@@ -349,7 +509,7 @@ func TestAgentLoop_Stop(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -417,6 +577,29 @@ func (m *countingMockProvider) GetDefaultModel() string {
return "counting-mock-model"
}
+type toolLimitOnlyProvider struct{}
+
+func (m *toolLimitOnlyProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ return &providers.LLMResponse{
+ ToolCalls: []providers.ToolCall{{
+ ID: "call_tool_limit_test",
+ Type: "function",
+ Name: "tool_limit_test_tool",
+ Arguments: map[string]any{"value": "x"},
+ }},
+ }, nil
+}
+
+func (m *toolLimitOnlyProvider) GetDefaultModel() string {
+ return "tool-limit-only-model"
+}
+
// mockCustomTool is a simple mock tool for registration testing
type mockCustomTool struct{}
@@ -439,11 +622,74 @@ func (m *mockCustomTool) Execute(ctx context.Context, args map[string]any) *tool
return tools.SilentResult("Custom tool executed")
}
+type toolLimitTestTool struct{}
+
+func (m *toolLimitTestTool) Name() string {
+ return "tool_limit_test_tool"
+}
+
+func (m *toolLimitTestTool) Description() string {
+ return "Tool used to exhaust the iteration budget in tests"
+}
+
+func (m *toolLimitTestTool) Parameters() map[string]any {
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "value": map[string]any{"type": "string"},
+ },
+ }
+}
+
+func (m *toolLimitTestTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+ return tools.SilentResult("tool limit test result")
+}
+
// testHelper executes a message and returns the response
type testHelper struct {
al *AgentLoop
}
+func newChatCompletionTestServer(
+ t *testing.T,
+ label string,
+ response string,
+ calls *int,
+ model *string,
+) *httptest.Server {
+ t.Helper()
+
+ return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/chat/completions" {
+ t.Fatalf("%s server path = %q, want /chat/completions", label, r.URL.Path)
+ }
+ *calls = *calls + 1
+ defer r.Body.Close()
+
+ var req struct {
+ Model string `json:"model"`
+ }
+ decodeErr := json.NewDecoder(r.Body).Decode(&req)
+ if decodeErr != nil {
+ t.Fatalf("decode %s request: %v", label, decodeErr)
+ }
+ *model = req.Model
+
+ w.Header().Set("Content-Type", "application/json")
+ encodeErr := json.NewEncoder(w).Encode(map[string]any{
+ "choices": []map[string]any{
+ {
+ "message": map[string]any{"content": response},
+ "finish_reason": "stop",
+ },
+ },
+ })
+ if encodeErr != nil {
+ t.Fatalf("encode %s response: %v", label, encodeErr)
+ }
+ }))
+}
+
func (h testHelper) executeAndGetResponse(tb testing.TB, ctx context.Context, msg bus.InboundMessage) string {
// Use a short timeout to avoid hanging
timeoutCtx, cancel := context.WithTimeout(ctx, responseTimeout)
@@ -469,7 +715,7 @@ func TestProcessMessage_UsesRouteSessionKey(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -525,7 +771,7 @@ func TestProcessMessage_CommandOutcomes(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -605,12 +851,34 @@ func TestProcessMessage_SwitchModelShowModelConsistency(t *testing.T) {
Defaults: config.AgentDefaults{
Workspace: tmpDir,
Provider: "openai",
- Model: "before-switch",
+ ModelName: "local",
MaxTokens: 4096,
MaxToolIterations: 10,
},
},
+ ModelList: []*config.ModelConfig{
+ {
+ ModelName: "local",
+ Model: "openai/local-model",
+ APIBase: "https://local.example.invalid/v1",
+ },
+ {
+ ModelName: "deepseek",
+ Model: "openrouter/deepseek/deepseek-v3.2",
+ APIBase: "https://openrouter.ai/api/v1",
+ },
+ },
}
+ cfg.WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "local": {
+ APIKeys: []string{"test-key"},
+ },
+ "deepseek": {
+ APIKeys: []string{"test-key"},
+ },
+ },
+ })
msgBus := bus.NewMessageBus()
provider := &countingMockProvider{response: "LLM reply"}
@@ -621,13 +889,13 @@ func TestProcessMessage_SwitchModelShowModelConsistency(t *testing.T) {
Channel: "telegram",
SenderID: "user1",
ChatID: "chat1",
- Content: "/switch model to after-switch",
+ Content: "/switch model to deepseek",
Peer: bus.Peer{
Kind: "direct",
ID: "user1",
},
})
- if !strings.Contains(switchResp, "Switched model from before-switch to after-switch") {
+ if !strings.Contains(switchResp, "Switched model from local to deepseek") {
t.Fatalf("unexpected /switch reply: %q", switchResp)
}
@@ -641,7 +909,7 @@ func TestProcessMessage_SwitchModelShowModelConsistency(t *testing.T) {
ID: "user1",
},
})
- if !strings.Contains(showResp, "Current Model: after-switch (Provider: openai)") {
+ if !strings.Contains(showResp, "Current Model: deepseek (Provider: openrouter)") {
t.Fatalf("unexpected /show model reply after switch: %q", showResp)
}
@@ -650,6 +918,201 @@ func TestProcessMessage_SwitchModelShowModelConsistency(t *testing.T) {
}
}
+func TestProcessMessage_SwitchModelRejectsUnknownAlias(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,
+ Provider: "openai",
+ ModelName: "local",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ ModelList: []*config.ModelConfig{
+ {
+ ModelName: "local",
+ Model: "openai/local-model",
+ APIBase: "https://local.example.invalid/v1",
+ },
+ },
+ }
+ cfg.WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "local": {
+ APIKeys: []string{"test-key"},
+ },
+ },
+ })
+
+ msgBus := bus.NewMessageBus()
+ provider := &countingMockProvider{response: "LLM reply"}
+ al := NewAgentLoop(cfg, msgBus, provider)
+ helper := testHelper{al: al}
+
+ switchResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "user1",
+ ChatID: "chat1",
+ Content: "/switch model to missing",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user1",
+ },
+ })
+ if switchResp != `model "missing" not found in model_list or providers` {
+ t.Fatalf("unexpected /switch error reply: %q", switchResp)
+ }
+
+ showResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "user1",
+ ChatID: "chat1",
+ Content: "/show model",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user1",
+ },
+ })
+ if !strings.Contains(showResp, "Current Model: local (Provider: openai)") {
+ t.Fatalf("unexpected /show model reply after rejected switch: %q", showResp)
+ }
+
+ if provider.calls != 0 {
+ t.Fatalf("LLM should not be called for rejected /switch and /show, calls=%d", provider.calls)
+ }
+}
+
+func TestProcessMessage_SwitchModelRoutesSubsequentRequestsToSelectedProvider(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)
+
+ localCalls := 0
+ localModel := ""
+ localServer := newChatCompletionTestServer(t, "local", "local reply", &localCalls, &localModel)
+ defer localServer.Close()
+
+ remoteCalls := 0
+ remoteModel := ""
+ remoteServer := newChatCompletionTestServer(t, "remote", "remote reply", &remoteCalls, &remoteModel)
+ defer remoteServer.Close()
+
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Workspace: tmpDir,
+ Provider: "openai",
+ ModelName: "local",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ ModelList: []*config.ModelConfig{
+ {
+ ModelName: "local",
+ Model: "openai/Qwen3.5-35B-A3B",
+ APIBase: localServer.URL,
+ },
+ {
+ ModelName: "deepseek",
+ Model: "openrouter/deepseek/deepseek-v3.2",
+ APIBase: remoteServer.URL,
+ },
+ },
+ }
+ cfg.WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "local": {
+ APIKeys: []string{"local-key"},
+ },
+ "deepseek": {
+ APIKeys: []string{"remote-key"},
+ },
+ },
+ })
+
+ msgBus := bus.NewMessageBus()
+ provider, _, err := providers.CreateProvider(cfg)
+ if err != nil {
+ t.Fatalf("CreateProvider() error = %v", err)
+ }
+ al := NewAgentLoop(cfg, msgBus, provider)
+ helper := testHelper{al: al}
+
+ firstResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "user1",
+ ChatID: "chat1",
+ Content: "hello before switch",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user1",
+ },
+ })
+ if firstResp != "local reply" {
+ t.Fatalf("unexpected response before switch: %q", firstResp)
+ }
+ if localCalls != 1 {
+ t.Fatalf("local calls before switch = %d, want 1", localCalls)
+ }
+ if remoteCalls != 0 {
+ t.Fatalf("remote calls before switch = %d, want 0", remoteCalls)
+ }
+ if localModel != "Qwen3.5-35B-A3B" {
+ t.Fatalf("local model before switch = %q, want %q", localModel, "Qwen3.5-35B-A3B")
+ }
+
+ switchResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "user1",
+ ChatID: "chat1",
+ Content: "/switch model to deepseek",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user1",
+ },
+ })
+ if !strings.Contains(switchResp, "Switched model from local to deepseek") {
+ t.Fatalf("unexpected /switch reply: %q", switchResp)
+ }
+
+ secondResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "user1",
+ ChatID: "chat1",
+ Content: "hello after switch",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user1",
+ },
+ })
+ if secondResp != "remote reply" {
+ t.Fatalf("unexpected response after switch: %q", secondResp)
+ }
+ if localCalls != 1 {
+ t.Fatalf("local calls after switch = %d, want 1", localCalls)
+ }
+ if remoteCalls != 1 {
+ t.Fatalf("remote calls after switch = %d, want 1", remoteCalls)
+ }
+ if remoteModel != "deepseek-v3.2" {
+ t.Fatalf(
+ "remote model after switch = %q, want %q",
+ remoteModel,
+ "deepseek-v3.2",
+ )
+ }
+}
+
// TestToolResult_SilentToolDoesNotSendUserMessage verifies silent tools don't trigger outbound
func TestToolResult_SilentToolDoesNotSendUserMessage(t *testing.T) {
tmpDir, err := os.MkdirTemp("", "agent-test-*")
@@ -662,7 +1125,7 @@ func TestToolResult_SilentToolDoesNotSendUserMessage(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -704,7 +1167,7 @@ func TestToolResult_UserFacingToolDoesSendMessage(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -775,7 +1238,7 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -794,11 +1257,11 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) {
al := NewAgentLoop(cfg, msgBus, provider)
- // Inject some history to simulate a full context
+ // Inject some history to simulate a full context.
+ // Session history only stores user/assistant/tool messages — the system
+ // prompt is built dynamically by BuildMessages and is NOT stored here.
sessionKey := "test-session-context"
- // Create dummy history
history := []providers.Message{
- {Role: "system", Content: "System prompt"},
{Role: "user", Content: "Old message 1"},
{Role: "assistant", Content: "Old response 1"},
{Role: "user", Content: "Old message 2"},
@@ -836,12 +1299,94 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) {
// Check final history length
finalHistory := defaultAgent.Sessions.GetHistory(sessionKey)
// We verify that the history has been modified (compressed)
- // Original length: 6
- // Expected behavior: compression drops ~50% of history (mid slice)
- // We can assert that the length is NOT what it would be without compression.
- // Without compression: 6 + 1 (new user msg) + 1 (assistant msg) = 8
- if len(finalHistory) >= 8 {
- t.Errorf("Expected history to be compressed (len < 8), got %d", len(finalHistory))
+ // Original length: 5
+ // Expected behavior: compression drops ~50% of Turns
+ // Without compression: 5 + 1 (new user msg) + 1 (assistant msg) = 7
+ if len(finalHistory) >= 7 {
+ t.Errorf("Expected history to be compressed (len < 7), got %d", len(finalHistory))
+ }
+}
+
+func TestAgentLoop_EmptyModelResponseUsesAccurateFallback(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 3,
+ },
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ provider := &simpleMockProvider{response: ""}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ response, err := al.ProcessDirectWithChannel(context.Background(), "hello", "empty-response", "test", "chat1")
+ if err != nil {
+ t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+ }
+ if response != defaultResponse {
+ t.Fatalf("response = %q, want %q", response, defaultResponse)
+ }
+}
+
+func TestAgentLoop_ToolLimitUsesDedicatedFallback(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 1,
+ },
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ provider := &toolLimitOnlyProvider{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+ al.RegisterTool(&toolLimitTestTool{})
+
+ response, err := al.ProcessDirectWithChannel(context.Background(), "hello", "tool-limit", "test", "chat1")
+ if err != nil {
+ t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+ }
+ if response != toolLimitResponse {
+ t.Fatalf("response = %q, want %q", response, toolLimitResponse)
+ }
+
+ defaultAgent := al.registry.GetDefaultAgent()
+ if defaultAgent == nil {
+ t.Fatal("No default agent found")
+ }
+ route := al.registry.ResolveRoute(routing.RouteInput{
+ Channel: "test",
+ Peer: &routing.RoutePeer{
+ Kind: "direct",
+ ID: "cron",
+ },
+ })
+ history := defaultAgent.Sessions.GetHistory(route.SessionKey)
+ if len(history) != 4 {
+ t.Fatalf("history len = %d, want 4", len(history))
+ }
+ assertRoles(t, history, "user", "assistant", "tool", "assistant")
+ if history[3].Content != toolLimitResponse {
+ t.Fatalf("final assistant content = %q, want %q", history[3].Content, toolLimitResponse)
}
}
@@ -861,7 +1406,7 @@ func TestProcessDirectWithChannel_TriggersMCPInitialization(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -913,7 +1458,7 @@ func TestTargetReasoningChannelID_AllChannels(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
@@ -983,7 +1528,7 @@ func TestHandleReasoning(t *testing.T) {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: tmpDir,
- Model: "test-model",
+ ModelName: "test-model",
MaxTokens: 4096,
MaxToolIterations: 10,
},
diff --git a/pkg/agent/model_resolution.go b/pkg/agent/model_resolution.go
new file mode 100644
index 000000000..140cff718
--- /dev/null
+++ b/pkg/agent/model_resolution.go
@@ -0,0 +1,97 @@
+package agent
+
+import (
+ "fmt"
+ "strings"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func buildModelListResolver(cfg *config.Config) 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
+ }
+
+ return func(raw string) (string, bool) {
+ raw = strings.TrimSpace(raw)
+ if raw == "" || cfg == nil {
+ return "", false
+ }
+
+ 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
+ }
+}
+
+func resolveModelCandidates(
+ cfg *config.Config,
+ defaultProvider string,
+ primary string,
+ fallbacks []string,
+) []providers.FallbackCandidate {
+ return providers.ResolveCandidatesWithLookup(
+ providers.ModelConfig{
+ Primary: primary,
+ Fallbacks: fallbacks,
+ },
+ defaultProvider,
+ buildModelListResolver(cfg),
+ )
+}
+
+func resolvedCandidateModel(candidates []providers.FallbackCandidate, fallback string) string {
+ if len(candidates) > 0 && strings.TrimSpace(candidates[0].Model) != "" {
+ return candidates[0].Model
+ }
+ return fallback
+}
+
+func resolvedCandidateProvider(candidates []providers.FallbackCandidate, fallback string) string {
+ if len(candidates) > 0 && strings.TrimSpace(candidates[0].Provider) != "" {
+ return candidates[0].Provider
+ }
+ return fallback
+}
+
+func resolvedModelConfig(cfg *config.Config, modelName, workspace string) (*config.ModelConfig, error) {
+ if cfg == nil {
+ return nil, fmt.Errorf("config is nil")
+ }
+
+ modelCfg, err := cfg.GetModelConfig(strings.TrimSpace(modelName))
+ if err != nil {
+ return nil, err
+ }
+
+ clone := *modelCfg
+ if clone.Workspace == "" {
+ clone.Workspace = workspace
+ }
+
+ return &clone, nil
+}
diff --git a/pkg/agent/registry_test.go b/pkg/agent/registry_test.go
index 518bb441f..b173ef967 100644
--- a/pkg/agent/registry_test.go
+++ b/pkg/agent/registry_test.go
@@ -29,7 +29,7 @@ func testCfg(agents []config.AgentConfig) *config.Config {
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: "/tmp/picoclaw-test-registry",
- Model: "gpt-4",
+ ModelName: "gpt-4",
MaxTokens: 8192,
MaxToolIterations: 10,
},
diff --git a/pkg/agent/steering.go b/pkg/agent/steering.go
new file mode 100644
index 000000000..ad6613e8c
--- /dev/null
+++ b/pkg/agent/steering.go
@@ -0,0 +1,503 @@
+package agent
+
+import (
+ "context"
+ "fmt"
+ "strings"
+ "sync"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/routing"
+ "github.com/sipeed/picoclaw/pkg/tools"
+)
+
+// SteeringMode controls how queued steering messages are dequeued.
+type SteeringMode string
+
+const (
+ // SteeringOneAtATime dequeues only the first queued message per poll.
+ SteeringOneAtATime SteeringMode = "one-at-a-time"
+ // SteeringAll drains the entire queue in a single poll.
+ SteeringAll SteeringMode = "all"
+ // MaxQueueSize number of possible messages in the Steering Queue
+ MaxQueueSize = 10
+ // manualSteeringScope is the legacy fallback queue used when no active
+ // turn/session scope is available.
+ manualSteeringScope = "__manual__"
+)
+
+// parseSteeringMode normalizes a config string into a SteeringMode.
+func parseSteeringMode(s string) SteeringMode {
+ switch s {
+ case "all":
+ return SteeringAll
+ default:
+ return SteeringOneAtATime
+ }
+}
+
+// steeringQueue is a thread-safe queue of user messages that can be injected
+// into a running agent loop to interrupt it between tool calls.
+type steeringQueue struct {
+ mu sync.Mutex
+ queues map[string][]providers.Message
+ mode SteeringMode
+}
+
+func newSteeringQueue(mode SteeringMode) *steeringQueue {
+ return &steeringQueue{
+ queues: make(map[string][]providers.Message),
+ mode: mode,
+ }
+}
+
+func normalizeSteeringScope(scope string) string {
+ scope = strings.TrimSpace(scope)
+ if scope == "" {
+ return manualSteeringScope
+ }
+ return scope
+}
+
+// push enqueues a steering message in the legacy fallback scope.
+func (sq *steeringQueue) push(msg providers.Message) error {
+ return sq.pushScope(manualSteeringScope, msg)
+}
+
+// pushScope enqueues a steering message for the provided scope.
+func (sq *steeringQueue) pushScope(scope string, msg providers.Message) error {
+ sq.mu.Lock()
+ defer sq.mu.Unlock()
+
+ scope = normalizeSteeringScope(scope)
+ queue := sq.queues[scope]
+ if len(queue) >= MaxQueueSize {
+ return fmt.Errorf("steering queue is full")
+ }
+ sq.queues[scope] = append(queue, msg)
+ return nil
+}
+
+// dequeue removes and returns pending steering messages from the legacy
+// fallback scope according to the configured mode.
+func (sq *steeringQueue) dequeue() []providers.Message {
+ return sq.dequeueScope(manualSteeringScope)
+}
+
+// dequeueScope removes and returns pending steering messages for the provided
+// scope according to the configured mode.
+func (sq *steeringQueue) dequeueScope(scope string) []providers.Message {
+ sq.mu.Lock()
+ defer sq.mu.Unlock()
+
+ return sq.dequeueLocked(normalizeSteeringScope(scope))
+}
+
+// dequeueScopeWithFallback drains the scoped queue first and falls back to the
+// legacy manual scope for backwards compatibility.
+func (sq *steeringQueue) dequeueScopeWithFallback(scope string) []providers.Message {
+ sq.mu.Lock()
+ defer sq.mu.Unlock()
+
+ scope = strings.TrimSpace(scope)
+ if scope != "" {
+ if msgs := sq.dequeueLocked(scope); len(msgs) > 0 {
+ return msgs
+ }
+ }
+
+ return sq.dequeueLocked(manualSteeringScope)
+}
+
+func (sq *steeringQueue) dequeueLocked(scope string) []providers.Message {
+ queue := sq.queues[scope]
+ if len(queue) == 0 {
+ return nil
+ }
+
+ switch sq.mode {
+ case SteeringAll:
+ msgs := append([]providers.Message(nil), queue...)
+ delete(sq.queues, scope)
+ return msgs
+ default:
+ msg := queue[0]
+ queue[0] = providers.Message{} // Clear reference for GC
+ queue = queue[1:]
+ if len(queue) == 0 {
+ delete(sq.queues, scope)
+ } else {
+ sq.queues[scope] = queue
+ }
+ return []providers.Message{msg}
+ }
+}
+
+// len returns the number of queued messages across all scopes.
+func (sq *steeringQueue) len() int {
+ sq.mu.Lock()
+ defer sq.mu.Unlock()
+
+ total := 0
+ for _, queue := range sq.queues {
+ total += len(queue)
+ }
+ return total
+}
+
+// lenScope returns the number of queued messages for a specific scope.
+func (sq *steeringQueue) lenScope(scope string) int {
+ sq.mu.Lock()
+ defer sq.mu.Unlock()
+ return len(sq.queues[normalizeSteeringScope(scope)])
+}
+
+// setMode updates the steering mode.
+func (sq *steeringQueue) setMode(mode SteeringMode) {
+ sq.mu.Lock()
+ defer sq.mu.Unlock()
+ sq.mode = mode
+}
+
+// getMode returns the current steering mode.
+func (sq *steeringQueue) getMode() SteeringMode {
+ sq.mu.Lock()
+ defer sq.mu.Unlock()
+ return sq.mode
+}
+
+// Steer enqueues a user message to be injected into the currently running
+// agent loop. The message will be picked up after the current tool finishes
+// executing, causing any remaining tool calls in the batch to be skipped.
+func (al *AgentLoop) Steer(msg providers.Message) error {
+ scope := ""
+ agentID := ""
+ if ts := al.getAnyActiveTurnState(); ts != nil {
+ scope = ts.sessionKey
+ agentID = ts.agentID
+ }
+ return al.enqueueSteeringMessage(scope, agentID, msg)
+}
+
+func (al *AgentLoop) enqueueSteeringMessage(scope, agentID string, msg providers.Message) error {
+ if al.steering == nil {
+ return fmt.Errorf("steering queue is not initialized")
+ }
+
+ if err := al.steering.pushScope(scope, msg); err != nil {
+ logger.WarnCF("agent", "Failed to enqueue steering message", map[string]any{
+ "error": err.Error(),
+ "role": msg.Role,
+ "scope": normalizeSteeringScope(scope),
+ })
+ return err
+ }
+
+ queueDepth := al.steering.lenScope(scope)
+ logger.DebugCF("agent", "Steering message enqueued", map[string]any{
+ "role": msg.Role,
+ "content_len": len(msg.Content),
+ "media_count": len(msg.Media),
+ "queue_len": queueDepth,
+ "scope": normalizeSteeringScope(scope),
+ })
+
+ meta := EventMeta{
+ Source: "Steer",
+ TracePath: "turn.interrupt.received",
+ }
+ if ts := al.getAnyActiveTurnState(); ts != nil {
+ meta = ts.eventMeta("Steer", "turn.interrupt.received")
+ } else {
+ if strings.TrimSpace(agentID) != "" {
+ meta.AgentID = agentID
+ }
+ normalizedScope := normalizeSteeringScope(scope)
+ if normalizedScope != manualSteeringScope {
+ meta.SessionKey = normalizedScope
+ }
+ if meta.AgentID == "" {
+ if registry := al.GetRegistry(); registry != nil {
+ if agent := registry.GetDefaultAgent(); agent != nil {
+ meta.AgentID = agent.ID
+ }
+ }
+ }
+ }
+
+ al.emitEvent(
+ EventKindInterruptReceived,
+ meta,
+ InterruptReceivedPayload{
+ Kind: InterruptKindSteering,
+ Role: msg.Role,
+ ContentLen: len(msg.Content),
+ QueueDepth: queueDepth,
+ },
+ )
+
+ return nil
+}
+
+// SteeringMode returns the current steering mode.
+func (al *AgentLoop) SteeringMode() SteeringMode {
+ if al.steering == nil {
+ return SteeringOneAtATime
+ }
+ return al.steering.getMode()
+}
+
+// SetSteeringMode updates the steering mode.
+func (al *AgentLoop) SetSteeringMode(mode SteeringMode) {
+ if al.steering == nil {
+ return
+ }
+ al.steering.setMode(mode)
+}
+
+// dequeueSteeringMessages is the internal method called by the agent loop
+// to poll for steering messages in the legacy fallback scope.
+func (al *AgentLoop) dequeueSteeringMessages() []providers.Message {
+ if al.steering == nil {
+ return nil
+ }
+ return al.steering.dequeue()
+}
+
+func (al *AgentLoop) dequeueSteeringMessagesForScope(scope string) []providers.Message {
+ if al.steering == nil {
+ return nil
+ }
+ return al.steering.dequeueScope(scope)
+}
+
+func (al *AgentLoop) dequeueSteeringMessagesForScopeWithFallback(scope string) []providers.Message {
+ if al.steering == nil {
+ return nil
+ }
+ return al.steering.dequeueScopeWithFallback(scope)
+}
+
+func (al *AgentLoop) pendingSteeringCountForScope(scope string) int {
+ if al.steering == nil {
+ return 0
+ }
+ return al.steering.lenScope(scope)
+}
+
+func (al *AgentLoop) continueWithSteeringMessages(
+ ctx context.Context,
+ agent *AgentInstance,
+ sessionKey, channel, chatID string,
+ steeringMsgs []providers.Message,
+) (string, error) {
+ return al.runAgentLoop(ctx, agent, processOptions{
+ SessionKey: sessionKey,
+ Channel: channel,
+ ChatID: chatID,
+ DefaultResponse: defaultResponse,
+ EnableSummary: true,
+ SendResponse: false,
+ InitialSteeringMessages: steeringMsgs,
+ SkipInitialSteeringPoll: true,
+ })
+}
+
+func (al *AgentLoop) agentForSession(sessionKey string) *AgentInstance {
+ registry := al.GetRegistry()
+ if registry == nil {
+ return nil
+ }
+
+ if parsed := routing.ParseAgentSessionKey(sessionKey); parsed != nil {
+ if agent, ok := registry.GetAgent(parsed.AgentID); ok {
+ return agent
+ }
+ }
+
+ return registry.GetDefaultAgent()
+}
+
+// Continue resumes an idle agent by dequeuing any pending steering messages
+// and running them through the agent loop. This is used when the agent's last
+// message was from the assistant (i.e., it has stopped processing) and the
+// user has since enqueued steering messages.
+//
+// If no steering messages are pending, it returns an empty string.
+func (al *AgentLoop) Continue(ctx context.Context, sessionKey, channel, chatID string) (string, error) {
+ if active := al.GetActiveTurn(); active != nil {
+ return "", fmt.Errorf("turn %s is still active", active.TurnID)
+ }
+ if err := al.ensureHooksInitialized(ctx); err != nil {
+ return "", err
+ }
+ if err := al.ensureMCPInitialized(ctx); err != nil {
+ return "", err
+ }
+
+ steeringMsgs := al.dequeueSteeringMessagesForScopeWithFallback(sessionKey)
+ if len(steeringMsgs) == 0 {
+ return "", nil
+ }
+
+ agent := al.agentForSession(sessionKey)
+ if agent == nil {
+ return "", fmt.Errorf("no agent available for session %q", sessionKey)
+ }
+
+ if tool, ok := agent.Tools.Get("message"); ok {
+ if resetter, ok := tool.(interface{ ResetSentInRound() }); ok {
+ resetter.ResetSentInRound()
+ }
+ }
+
+ return al.continueWithSteeringMessages(ctx, agent, sessionKey, channel, chatID, steeringMsgs)
+}
+
+func (al *AgentLoop) InterruptGraceful(hint string) error {
+ ts := al.getAnyActiveTurnState()
+ if ts == nil {
+ return fmt.Errorf("no active turn")
+ }
+ if !ts.requestGracefulInterrupt(hint) {
+ return fmt.Errorf("turn %s cannot accept graceful interrupt", ts.turnID)
+ }
+
+ al.emitEvent(
+ EventKindInterruptReceived,
+ ts.eventMeta("InterruptGraceful", "turn.interrupt.received"),
+ InterruptReceivedPayload{
+ Kind: InterruptKindGraceful,
+ HintLen: len(hint),
+ },
+ )
+
+ return nil
+}
+
+func (al *AgentLoop) InterruptHard() error {
+ ts := al.getAnyActiveTurnState()
+ if ts == nil {
+ return fmt.Errorf("no active turn")
+ }
+ if !ts.requestHardAbort() {
+ return fmt.Errorf("turn %s is already aborting", ts.turnID)
+ }
+
+ al.emitEvent(
+ EventKindInterruptReceived,
+ ts.eventMeta("InterruptHard", "turn.interrupt.received"),
+ InterruptReceivedPayload{
+ Kind: InterruptKindHard,
+ },
+ )
+
+ return nil
+}
+
+// ====================== SubTurn Result Polling ======================
+
+// dequeuePendingSubTurnResults polls the SubTurn result channel for the given
+// session and returns all available results without blocking.
+// Returns nil if no active turn state exists for this session.
+func (al *AgentLoop) dequeuePendingSubTurnResults(sessionKey string) []*tools.ToolResult {
+ tsInterface, ok := al.activeTurnStates.Load(sessionKey)
+ if !ok {
+ return nil
+ }
+ ts, ok := tsInterface.(*turnState)
+ if !ok {
+ return nil
+ }
+
+ var results []*tools.ToolResult
+ for {
+ select {
+ case result, ok := <-ts.pendingResults:
+ if !ok {
+ return results
+ }
+ if result != nil {
+ results = append(results, result)
+ }
+ default:
+ return results
+ }
+ }
+}
+
+// ====================== Hard Abort ======================
+
+// HardAbort immediately cancels the running agent loop for the given session,
+// cascading the cancellation to all child SubTurns. This is a destructive operation
+// that terminates execution without waiting for graceful cleanup.
+//
+// Use this when the user explicitly requests immediate termination (e.g., "stop now", "abort").
+// For graceful interruption that allows the agent to finish the current tool and summarize,
+// use Steer() instead.
+func (al *AgentLoop) HardAbort(sessionKey string) error {
+ tsInterface, ok := al.activeTurnStates.Load(sessionKey)
+ if !ok {
+ return fmt.Errorf("no active turn state found for session %s", sessionKey)
+ }
+
+ ts, ok := tsInterface.(*turnState)
+ if !ok {
+ return fmt.Errorf("invalid turn state type for session %s", sessionKey)
+ }
+
+ logger.InfoCF("agent", "Hard abort triggered", map[string]any{
+ "session_key": sessionKey,
+ "turn_id": ts.turnID,
+ "depth": ts.depth,
+ "initial_history_length": ts.initialHistoryLength,
+ })
+
+ // IMPORTANT: Trigger cascading cancellation FIRST to stop all child SubTurns
+ // from adding more messages to the session. This prevents race conditions
+ // where rollback happens while children are still writing.
+ // Use isHardAbort=true for hard abort to immediately cancel all children.
+ ts.Finish(true)
+
+ // Roll back session history to the state before the turn started.
+ if ts.session != nil {
+ history := ts.session.GetHistory(sessionKey)
+ if ts.initialHistoryLength < len(history) {
+ ts.session.SetHistory(sessionKey, history[:ts.initialHistoryLength])
+ }
+ }
+
+ return nil
+}
+
+// ====================== Follow-Up Injection ======================
+
+// InjectFollowUp enqueues a message to be automatically processed after the current
+// turn completes. Unlike Steer(), which interrupts the current execution, InjectFollowUp
+// waits for the current turn to finish naturally before processing the message.
+//
+// This is useful for:
+// - Automated workflows that need to chain multiple turns
+// - Background tasks that should run after the main task completes
+// - Scheduled follow-up actions
+//
+// The message will be processed via Continue() when the agent becomes idle.
+func (al *AgentLoop) InjectFollowUp(msg providers.Message) error {
+ // InjectFollowUp uses the same steering queue mechanism as Steer(),
+ // but the semantic difference is in when it's called:
+ // - Steer() is called during active execution to interrupt
+ // - InjectFollowUp() is called when planning future work
+ //
+ // Both end up in the same queue and are processed by Continue()
+ // when the agent is idle.
+ return al.Steer(msg)
+}
+
+// ====================== API Aliases for Design Document Compatibility ======================
+
+// InjectSteering is an alias for Steer() to match the design document naming.
+// It injects a steering message into the currently running agent loop.
+func (al *AgentLoop) InjectSteering(msg providers.Message) error {
+ return al.Steer(msg)
+}
diff --git a/pkg/agent/steering_test.go b/pkg/agent/steering_test.go
new file mode 100644
index 000000000..75ba9861d
--- /dev/null
+++ b/pkg/agent/steering_test.go
@@ -0,0 +1,1591 @@
+package agent
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "reflect"
+ "strings"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/media"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/routing"
+ "github.com/sipeed/picoclaw/pkg/tools"
+)
+
+// --- steeringQueue unit tests ---
+
+func TestSteeringQueue_PushDequeue_OneAtATime(t *testing.T) {
+ sq := newSteeringQueue(SteeringOneAtATime)
+
+ sq.push(providers.Message{Role: "user", Content: "msg1"})
+ sq.push(providers.Message{Role: "user", Content: "msg2"})
+ sq.push(providers.Message{Role: "user", Content: "msg3"})
+
+ if sq.len() != 3 {
+ t.Fatalf("expected 3 messages, got %d", sq.len())
+ }
+
+ msgs := sq.dequeue()
+ if len(msgs) != 1 {
+ t.Fatalf("expected 1 message in one-at-a-time mode, got %d", len(msgs))
+ }
+ if msgs[0].Content != "msg1" {
+ t.Fatalf("expected 'msg1', got %q", msgs[0].Content)
+ }
+ if sq.len() != 2 {
+ t.Fatalf("expected 2 remaining, got %d", sq.len())
+ }
+
+ msgs = sq.dequeue()
+ if len(msgs) != 1 || msgs[0].Content != "msg2" {
+ t.Fatalf("expected 'msg2', got %v", msgs)
+ }
+
+ msgs = sq.dequeue()
+ if len(msgs) != 1 || msgs[0].Content != "msg3" {
+ t.Fatalf("expected 'msg3', got %v", msgs)
+ }
+
+ msgs = sq.dequeue()
+ if msgs != nil {
+ t.Fatalf("expected nil from empty queue, got %v", msgs)
+ }
+}
+
+func TestSteeringQueue_PushDequeue_All(t *testing.T) {
+ sq := newSteeringQueue(SteeringAll)
+
+ sq.push(providers.Message{Role: "user", Content: "msg1"})
+ sq.push(providers.Message{Role: "user", Content: "msg2"})
+ sq.push(providers.Message{Role: "user", Content: "msg3"})
+
+ msgs := sq.dequeue()
+ if len(msgs) != 3 {
+ t.Fatalf("expected 3 messages in all mode, got %d", len(msgs))
+ }
+ if msgs[0].Content != "msg1" || msgs[1].Content != "msg2" || msgs[2].Content != "msg3" {
+ t.Fatalf("unexpected messages: %v", msgs)
+ }
+
+ if sq.len() != 0 {
+ t.Fatalf("expected 0 remaining, got %d", sq.len())
+ }
+
+ msgs = sq.dequeue()
+ if msgs != nil {
+ t.Fatalf("expected nil from empty queue, got %v", msgs)
+ }
+}
+
+func TestSteeringQueue_EmptyDequeue(t *testing.T) {
+ sq := newSteeringQueue(SteeringOneAtATime)
+ if msgs := sq.dequeue(); msgs != nil {
+ t.Fatalf("expected nil, got %v", msgs)
+ }
+}
+
+func TestSteeringQueue_SetMode(t *testing.T) {
+ sq := newSteeringQueue(SteeringOneAtATime)
+ if sq.getMode() != SteeringOneAtATime {
+ t.Fatalf("expected one-at-a-time, got %v", sq.getMode())
+ }
+
+ sq.setMode(SteeringAll)
+ if sq.getMode() != SteeringAll {
+ t.Fatalf("expected all, got %v", sq.getMode())
+ }
+
+ // Push two messages and verify all-mode drains them
+ sq.push(providers.Message{Role: "user", Content: "a"})
+ sq.push(providers.Message{Role: "user", Content: "b"})
+
+ msgs := sq.dequeue()
+ if len(msgs) != 2 {
+ t.Fatalf("expected 2 messages after mode switch, got %d", len(msgs))
+ }
+}
+
+func TestSteeringQueue_ConcurrentAccess(t *testing.T) {
+ sq := newSteeringQueue(SteeringOneAtATime)
+
+ var wg sync.WaitGroup
+ const n = MaxQueueSize
+
+ // Push from multiple goroutines
+ for i := 0; i < n; i++ {
+ wg.Add(1)
+ go func(i int) {
+ defer wg.Done()
+ sq.push(providers.Message{Role: "user", Content: fmt.Sprintf("msg%d", i)})
+ }(i)
+ }
+ wg.Wait()
+
+ if sq.len() != n {
+ t.Fatalf("expected %d messages, got %d", n, sq.len())
+ }
+
+ // Drain from multiple goroutines
+ var drained int
+ var mu sync.Mutex
+ for i := 0; i < n; i++ {
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ if msgs := sq.dequeue(); len(msgs) > 0 {
+ mu.Lock()
+ drained += len(msgs)
+ mu.Unlock()
+ }
+ }()
+ }
+ wg.Wait()
+
+ if drained != n {
+ t.Fatalf("expected to drain %d messages, got %d", n, drained)
+ }
+}
+
+func TestSteeringQueue_Overflow(t *testing.T) {
+ sq := newSteeringQueue(SteeringOneAtATime)
+
+ // Fill the queue up to its maximum capacity
+ for i := 0; i < MaxQueueSize; i++ {
+ err := sq.push(providers.Message{Role: "user", Content: fmt.Sprintf("msg%d", i)})
+ if err != nil {
+ t.Fatalf("unexpected error pushing message %d: %v", i, err)
+ }
+ }
+
+ // Sanity check: ensure the queue is actually full
+ if sq.len() != MaxQueueSize {
+ t.Fatalf("expected queue length %d, got %d", MaxQueueSize, sq.len())
+ }
+
+ // Attempt to push one more message, which MUST fail
+ err := sq.push(providers.Message{Role: "user", Content: "overflow_msg"})
+
+ // Assert the error happened and is the exact one we expect
+ if err == nil {
+ t.Fatal("expected an error when pushing to a full queue, but got nil")
+ }
+
+ expectedErr := "steering queue is full"
+ if err.Error() != expectedErr {
+ t.Errorf("expected error message %q, got %q", expectedErr, err.Error())
+ }
+}
+
+func TestParseSteeringMode(t *testing.T) {
+ tests := []struct {
+ input string
+ expected SteeringMode
+ }{
+ {"", SteeringOneAtATime},
+ {"one-at-a-time", SteeringOneAtATime},
+ {"all", SteeringAll},
+ {"unknown", SteeringOneAtATime},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.input, func(t *testing.T) {
+ if got := parseSteeringMode(tt.input); got != tt.expected {
+ t.Fatalf("parseSteeringMode(%q) = %v, want %v", tt.input, got, tt.expected)
+ }
+ })
+ }
+}
+
+// --- AgentLoop steering integration tests ---
+
+func TestAgentLoop_Steer_Enqueues(t *testing.T) {
+ al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+ defer cleanup()
+
+ if cfg == nil {
+ t.Fatal("expected config to be initialized")
+ }
+ if msgBus == nil {
+ t.Fatal("expected message bus to be initialized")
+ }
+ if provider == nil {
+ t.Fatal("expected provider to be initialized")
+ }
+
+ al.Steer(providers.Message{Role: "user", Content: "interrupt me"})
+
+ if al.steering.len() != 1 {
+ t.Fatalf("expected 1 steering message, got %d", al.steering.len())
+ }
+
+ msgs := al.dequeueSteeringMessages()
+ if len(msgs) != 1 || msgs[0].Content != "interrupt me" {
+ t.Fatalf("unexpected dequeued message: %v", msgs)
+ }
+}
+
+func TestAgentLoop_SteeringMode_GetSet(t *testing.T) {
+ al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+ defer cleanup()
+
+ if cfg == nil {
+ t.Fatal("expected config to be initialized")
+ }
+ if msgBus == nil {
+ t.Fatal("expected message bus to be initialized")
+ }
+ if provider == nil {
+ t.Fatal("expected provider to be initialized")
+ }
+
+ if al.SteeringMode() != SteeringOneAtATime {
+ t.Fatalf("expected default mode one-at-a-time, got %v", al.SteeringMode())
+ }
+
+ al.SetSteeringMode(SteeringAll)
+ if al.SteeringMode() != SteeringAll {
+ t.Fatalf("expected all mode, got %v", al.SteeringMode())
+ }
+}
+
+func TestAgentLoop_SteeringMode_ConfiguredFromConfig(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ SteeringMode: "all",
+ },
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ provider := &mockProvider{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ if al.SteeringMode() != SteeringAll {
+ t.Fatalf("expected 'all' mode from config, got %v", al.SteeringMode())
+ }
+}
+
+func TestAgentLoop_Continue_NoMessages(t *testing.T) {
+ al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+ defer cleanup()
+
+ if cfg == nil {
+ t.Fatal("expected config to be initialized")
+ }
+ if msgBus == nil {
+ t.Fatal("expected message bus to be initialized")
+ }
+ if provider == nil {
+ t.Fatal("expected provider to be initialized")
+ }
+
+ resp, err := al.Continue(context.Background(), "test-session", "test", "chat1")
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if resp != "" {
+ t.Fatalf("expected empty response for no steering messages, got %q", resp)
+ }
+}
+
+func TestAgentLoop_Continue_WithMessages(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ provider := &simpleMockProvider{response: "continued response"}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ al.Steer(providers.Message{Role: "user", Content: "new direction"})
+
+ resp, err := al.Continue(context.Background(), "test-session", "test", "chat1")
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if resp != "continued response" {
+ t.Fatalf("expected 'continued response', got %q", resp)
+ }
+}
+
+func TestDrainBusToSteering_RequeuesDifferentScopeMessage(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ Session: config.SessionConfig{
+ DMScope: "per-peer",
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, &mockProvider{})
+
+ activeMsg := bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "user1",
+ ChatID: "chat1",
+ Content: "active turn",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user1",
+ },
+ }
+ activeScope, activeAgentID, ok := al.resolveSteeringTarget(activeMsg)
+ if !ok {
+ t.Fatal("expected active message to resolve to a steering scope")
+ }
+
+ otherMsg := bus.InboundMessage{
+ Channel: "telegram",
+ SenderID: "user2",
+ ChatID: "chat2",
+ Content: "other session",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user2",
+ },
+ }
+ otherScope, _, ok := al.resolveSteeringTarget(otherMsg)
+ if !ok {
+ t.Fatal("expected other message to resolve to a steering scope")
+ }
+ if otherScope == activeScope {
+ t.Fatalf("expected different steering scopes, got same scope %q", activeScope)
+ }
+
+ if err := msgBus.PublishInbound(context.Background(), otherMsg); err != nil {
+ t.Fatalf("PublishInbound failed: %v", err)
+ }
+
+ ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+ defer cancel()
+
+ done := make(chan struct{})
+ go func() {
+ al.drainBusToSteering(ctx, activeScope, activeAgentID)
+ close(done)
+ }()
+
+ select {
+ case <-done:
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for drainBusToSteering to stop")
+ }
+
+ if msgs := al.dequeueSteeringMessagesForScope(activeScope); len(msgs) != 0 {
+ t.Fatalf("expected no steering messages for active scope, got %v", msgs)
+ }
+
+ select {
+ case <-ctx.Done():
+ t.Fatalf("timeout waiting for requeued message on outbound bus")
+ case requeued := <-msgBus.OutboundChan():
+ if requeued.Channel != otherMsg.Channel || requeued.ChatID != otherMsg.ChatID ||
+ requeued.Content != otherMsg.Content {
+ t.Fatalf("requeued message mismatch: got %+v want %+v", requeued, otherMsg)
+ }
+ }
+}
+
+// slowTool simulates a tool that takes some time to execute.
+type slowTool struct {
+ name string
+ duration time.Duration
+ execCh chan struct{} // closed when Execute starts
+}
+
+func (t *slowTool) Name() string { return t.name }
+func (t *slowTool) Description() string { return "slow tool for testing" }
+func (t *slowTool) Parameters() map[string]any {
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{},
+ }
+}
+
+func (t *slowTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+ if t.execCh != nil {
+ close(t.execCh)
+ }
+ time.Sleep(t.duration)
+ return tools.SilentResult(fmt.Sprintf("executed %s", t.name))
+}
+
+// toolCallProvider returns an LLM response with tool calls on the first call,
+// then a direct response on subsequent calls.
+type toolCallProvider struct {
+ mu sync.Mutex
+ calls int
+ toolCalls []providers.ToolCall
+ finalResp string
+}
+
+func (m *toolCallProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ m.mu.Lock()
+ defer m.mu.Unlock()
+ m.calls++
+
+ if m.calls == 1 && len(m.toolCalls) > 0 {
+ return &providers.LLMResponse{
+ Content: "",
+ ToolCalls: m.toolCalls,
+ }, nil
+ }
+
+ return &providers.LLMResponse{
+ Content: m.finalResp,
+ ToolCalls: []providers.ToolCall{},
+ }, nil
+}
+
+func (m *toolCallProvider) GetDefaultModel() string {
+ return "tool-call-mock"
+}
+
+type gracefulCaptureProvider struct {
+ mu sync.Mutex
+ calls int
+ toolCalls []providers.ToolCall
+ finalResp string
+ terminalMessages []providers.Message
+ terminalToolsCount int
+}
+
+func (p *gracefulCaptureProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ p.mu.Lock()
+ defer p.mu.Unlock()
+ p.calls++
+
+ if p.calls == 1 {
+ return &providers.LLMResponse{
+ ToolCalls: p.toolCalls,
+ }, nil
+ }
+
+ p.terminalMessages = append([]providers.Message(nil), messages...)
+ p.terminalToolsCount = len(tools)
+ return &providers.LLMResponse{
+ Content: p.finalResp,
+ }, nil
+}
+
+func (p *gracefulCaptureProvider) GetDefaultModel() string {
+ return "graceful-capture-mock"
+}
+
+type lateSteeringProvider struct {
+ mu sync.Mutex
+ calls int
+ firstCallStarted chan struct{}
+ releaseFirstCall chan struct{}
+ firstStartOnce sync.Once
+ secondCallMessages []providers.Message
+}
+
+func (p *lateSteeringProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ p.mu.Lock()
+ p.calls++
+ call := p.calls
+ p.mu.Unlock()
+
+ if call == 1 {
+ p.firstStartOnce.Do(func() { close(p.firstCallStarted) })
+ <-p.releaseFirstCall
+ return &providers.LLMResponse{Content: "first response"}, nil
+ }
+
+ p.mu.Lock()
+ p.secondCallMessages = append([]providers.Message(nil), messages...)
+ p.mu.Unlock()
+ return &providers.LLMResponse{Content: "continued response"}, nil
+}
+
+func (p *lateSteeringProvider) GetDefaultModel() string {
+ return "late-steering-mock"
+}
+
+type blockingDirectProvider struct {
+ mu sync.Mutex
+ calls int
+ firstStarted chan struct{}
+ releaseFirst chan struct{}
+ firstResp string
+ finalResp string
+}
+
+func (p *blockingDirectProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ p.mu.Lock()
+ p.calls++
+ call := p.calls
+ firstStarted := p.firstStarted
+ releaseFirst := p.releaseFirst
+ firstResp := p.firstResp
+ finalResp := p.finalResp
+ if call == 1 && p.firstStarted != nil {
+ close(p.firstStarted)
+ p.firstStarted = nil
+ }
+ p.mu.Unlock()
+
+ if call == 1 {
+ select {
+ case <-releaseFirst:
+ case <-ctx.Done():
+ return nil, ctx.Err()
+ }
+ return &providers.LLMResponse{Content: firstResp}, nil
+ }
+
+ _ = firstStarted
+ return &providers.LLMResponse{Content: finalResp}, nil
+}
+
+func (p *blockingDirectProvider) GetDefaultModel() string {
+ return "blocking-direct-mock"
+}
+
+type interruptibleTool struct {
+ name string
+ started chan struct{}
+ once sync.Once
+}
+
+func (t *interruptibleTool) Name() string { return t.name }
+func (t *interruptibleTool) Description() string { return "interruptible tool for testing" }
+func (t *interruptibleTool) Parameters() map[string]any {
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{},
+ }
+}
+
+func (t *interruptibleTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+ if t.started != nil {
+ t.once.Do(func() { close(t.started) })
+ }
+ <-ctx.Done()
+ return tools.ErrorResult(ctx.Err().Error()).WithError(ctx.Err())
+}
+
+func TestAgentLoop_Steering_SkipsRemainingTools(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ tool1ExecCh := make(chan struct{})
+ tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh}
+ tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond}
+
+ provider := &toolCallProvider{
+ toolCalls: []providers.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Name: "tool_one",
+ Function: &providers.FunctionCall{
+ Name: "tool_one",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ {
+ ID: "call_2",
+ Type: "function",
+ Name: "tool_two",
+ Function: &providers.FunctionCall{
+ Name: "tool_two",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ },
+ finalResp: "steered response",
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, provider)
+ al.RegisterTool(tool1)
+ al.RegisterTool(tool2)
+
+ // Start processing in a goroutine
+ type result struct {
+ resp string
+ err error
+ }
+ resultCh := make(chan result, 1)
+
+ go func() {
+ resp, err := al.ProcessDirectWithChannel(
+ context.Background(),
+ "do something",
+ "test-session",
+ "test",
+ "chat1",
+ )
+ resultCh <- result{resp, err}
+ }()
+
+ // Wait for tool_one to start executing, then enqueue a steering message
+ select {
+ case <-tool1ExecCh:
+ // tool_one has started executing
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for tool_one to start")
+ }
+
+ al.Steer(providers.Message{Role: "user", Content: "change course"})
+
+ // Get the result
+ select {
+ case r := <-resultCh:
+ if r.err != nil {
+ t.Fatalf("unexpected error: %v", r.err)
+ }
+ if r.resp != "steered response" {
+ t.Fatalf("expected 'steered response', got %q", r.resp)
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatal("timeout waiting for agent loop to complete")
+ }
+
+ // The provider should have been called twice:
+ // 1. first call returned tool calls
+ // 2. second call (after steering) returned the final response
+ provider.mu.Lock()
+ calls := provider.calls
+ provider.mu.Unlock()
+ if calls != 2 {
+ t.Fatalf("expected 2 provider calls, got %d", calls)
+ }
+}
+
+func TestAgentLoop_Steering_InitialPoll(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ // Provider that captures messages it receives
+ var capturedMessages []providers.Message
+ var capMu sync.Mutex
+ provider := &capturingMockProvider{
+ response: "ack",
+ captureFn: func(msgs []providers.Message) {
+ capMu.Lock()
+ capturedMessages = make([]providers.Message, len(msgs))
+ copy(capturedMessages, msgs)
+ capMu.Unlock()
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ // Enqueue a steering message before processing starts
+ al.Steer(providers.Message{Role: "user", Content: "pre-enqueued steering"})
+
+ // Process a normal message - the initial steering poll should inject the steering message
+ _, err = al.ProcessDirectWithChannel(
+ context.Background(),
+ "initial message",
+ "test-session",
+ "test",
+ "chat1",
+ )
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+
+ // The steering message should have been injected into the conversation
+ capMu.Lock()
+ msgs := capturedMessages
+ capMu.Unlock()
+
+ // Look for the steering message in the captured messages
+ found := false
+ for _, m := range msgs {
+ if m.Content == "pre-enqueued steering" {
+ found = true
+ break
+ }
+ }
+ if !found {
+ t.Fatal("expected steering message to be injected into conversation context")
+ }
+}
+
+func TestAgentLoop_Run_AutoContinuesLateSteeringMessage(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ provider := &lateSteeringProvider{
+ firstCallStarted: make(chan struct{}),
+ releaseFirstCall: make(chan struct{}),
+ }
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ runCtx, cancelRun := context.WithCancel(context.Background())
+ defer cancelRun()
+
+ runErrCh := make(chan error, 1)
+ go func() {
+ runErrCh <- al.Run(runCtx)
+ }()
+
+ first := bus.InboundMessage{
+ Channel: "test",
+ SenderID: "user1",
+ ChatID: "chat1",
+ Content: "first message",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user1",
+ },
+ }
+ late := bus.InboundMessage{
+ Channel: "test",
+ SenderID: "user1",
+ ChatID: "chat1",
+ Content: "late append",
+ Peer: bus.Peer{
+ Kind: "direct",
+ ID: "user1",
+ },
+ }
+
+ pubCtx, pubCancel := context.WithTimeout(context.Background(), 2*time.Second)
+ defer pubCancel()
+ if err := msgBus.PublishInbound(pubCtx, first); err != nil {
+ t.Fatalf("publish first inbound: %v", err)
+ }
+
+ select {
+ case <-provider.firstCallStarted:
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for first provider call to start")
+ }
+
+ if err := msgBus.PublishInbound(pubCtx, late); err != nil {
+ t.Fatalf("publish late inbound: %v", err)
+ }
+
+ close(provider.releaseFirstCall)
+
+ subCtx, subCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer subCancel()
+
+ var out1 bus.OutboundMessage
+ select {
+ case out1 = <-msgBus.OutboundChan():
+ case <-subCtx.Done():
+ t.Fatal("expected outbound response")
+ }
+ if out1.Content != "continued response" {
+ t.Fatalf("expected continued response, got %q", out1.Content)
+ }
+
+ noExtraCtx, cancelNoExtra := context.WithTimeout(context.Background(), 200*time.Millisecond)
+ defer cancelNoExtra()
+ select {
+ case out2 := <-msgBus.OutboundChan():
+ t.Fatalf("expected stale direct response to be suppressed, got extra outbound %q", out2.Content)
+ case <-noExtraCtx.Done():
+ }
+
+ cancelRun()
+ select {
+ case err := <-runErrCh:
+ if err != nil {
+ t.Fatalf("Run returned error: %v", err)
+ }
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for Run to stop")
+ }
+
+ provider.mu.Lock()
+ calls := provider.calls
+ secondMessages := append([]providers.Message(nil), provider.secondCallMessages...)
+ provider.mu.Unlock()
+
+ if calls != 2 {
+ t.Fatalf("expected 2 provider calls, got %d", calls)
+ }
+
+ foundLateMessage := false
+ for _, msg := range secondMessages {
+ if msg.Role == "user" && msg.Content == "late append" {
+ foundLateMessage = true
+ break
+ }
+ }
+ if !foundLateMessage {
+ t.Fatal("expected queued late message to be processed in an automatic follow-up turn")
+ }
+}
+
+func TestAgentLoop_Steering_DirectResponseContinuesWithQueuedMessage(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID)
+ provider := &blockingDirectProvider{
+ firstStarted: make(chan struct{}),
+ releaseFirst: make(chan struct{}),
+ firstResp: "stale direct response",
+ finalResp: "fresh response after steering",
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ resultCh := make(chan struct {
+ resp string
+ err error
+ }, 1)
+ go func() {
+ resp, err := al.ProcessDirectWithChannel(
+ context.Background(),
+ "initial request",
+ sessionKey,
+ "test",
+ "chat1",
+ )
+ resultCh <- struct {
+ resp string
+ err error
+ }{resp: resp, err: err}
+ }()
+
+ select {
+ case <-provider.firstStarted:
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for first LLM call to start")
+ }
+
+ if err := al.Steer(providers.Message{Role: "user", Content: "follow-up instruction"}); err != nil {
+ t.Fatalf("Steer failed: %v", err)
+ }
+ close(provider.releaseFirst)
+
+ select {
+ case result := <-resultCh:
+ if result.err != nil {
+ t.Fatalf("unexpected error: %v", result.err)
+ }
+ if result.resp != "fresh response after steering" {
+ t.Fatalf("expected refreshed response, got %q", result.resp)
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatal("timeout waiting for ProcessDirectWithChannel")
+ }
+
+ provider.mu.Lock()
+ calls := provider.calls
+ provider.mu.Unlock()
+ if calls != 2 {
+ t.Fatalf("expected 2 provider calls, got %d", calls)
+ }
+
+ if msgs := al.dequeueSteeringMessagesForScope(sessionKey); len(msgs) != 0 {
+ t.Fatalf("expected steering queue to be empty after continuation, got %v", msgs)
+ }
+}
+
+func TestAgentLoop_Continue_PreservesSteeringMedia(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ store := media.NewFileMediaStore()
+ pngPath := filepath.Join(tmpDir, "steer.png")
+ pngHeader := []byte{
+ 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,
+ 0x00, 0x00, 0x00, 0x0D,
+ 0x49, 0x48, 0x44, 0x52,
+ 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02,
+ 0x00, 0x00, 0x00,
+ 0x90, 0x77, 0x53, 0xDE,
+ }
+ if err = os.WriteFile(pngPath, pngHeader, 0o644); err != nil {
+ t.Fatalf("WriteFile failed: %v", err)
+ }
+ ref, err := store.Store(pngPath, media.MediaMeta{Filename: "steer.png", ContentType: "image/png"}, "test")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+
+ var capturedMessages []providers.Message
+ var capMu sync.Mutex
+ provider := &capturingMockProvider{
+ response: "ack",
+ captureFn: func(msgs []providers.Message) {
+ capMu.Lock()
+ defer capMu.Unlock()
+ capturedMessages = append([]providers.Message(nil), msgs...)
+ },
+ }
+
+ sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID)
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, provider)
+ al.SetMediaStore(store)
+
+ if err = al.Steer(providers.Message{
+ Role: "user",
+ Content: "describe this image",
+ Media: []string{ref},
+ }); err != nil {
+ t.Fatalf("Steer failed: %v", err)
+ }
+
+ resp, err := al.Continue(context.Background(), sessionKey, "test", "chat1")
+ if err != nil {
+ t.Fatalf("Continue failed: %v", err)
+ }
+ if resp != "ack" {
+ t.Fatalf("expected ack, got %q", resp)
+ }
+
+ capMu.Lock()
+ msgs := append([]providers.Message(nil), capturedMessages...)
+ capMu.Unlock()
+
+ foundResolvedMedia := false
+ for _, msg := range msgs {
+ if msg.Role != "user" || msg.Content != "describe this image" || len(msg.Media) != 1 {
+ continue
+ }
+ if strings.HasPrefix(msg.Media[0], "data:image/png;base64,") {
+ foundResolvedMedia = true
+ break
+ }
+ }
+ if !foundResolvedMedia {
+ t.Fatal("expected continue path to inject steering media into the provider request")
+ }
+
+ defaultAgent := al.registry.GetDefaultAgent()
+ if defaultAgent == nil {
+ t.Fatal("expected default agent")
+ }
+ history := defaultAgent.Sessions.GetHistory(sessionKey)
+ foundOriginalRef := false
+ for _, msg := range history {
+ if msg.Role == "user" && len(msg.Media) == 1 && msg.Media[0] == ref {
+ foundOriginalRef = true
+ break
+ }
+ }
+ if !foundOriginalRef {
+ t.Fatal("expected original steering media ref to be preserved in session history")
+ }
+}
+
+func TestAgentLoop_InterruptGraceful_UsesTerminalNoToolCall(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ tool1ExecCh := make(chan struct{})
+ tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh}
+ tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond}
+
+ provider := &gracefulCaptureProvider{
+ toolCalls: []providers.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Name: "tool_one",
+ Function: &providers.FunctionCall{
+ Name: "tool_one",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ {
+ ID: "call_2",
+ Type: "function",
+ Name: "tool_two",
+ Function: &providers.FunctionCall{
+ Name: "tool_two",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ },
+ finalResp: "graceful summary",
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, provider)
+ al.RegisterTool(tool1)
+ al.RegisterTool(tool2)
+ sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID)
+
+ sub := al.SubscribeEvents(32)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ type result struct {
+ resp string
+ err error
+ }
+ resultCh := make(chan result, 1)
+ go func() {
+ resp, err := al.ProcessDirectWithChannel(
+ context.Background(),
+ "do something",
+ sessionKey,
+ "test",
+ "chat1",
+ )
+ resultCh <- result{resp: resp, err: err}
+ }()
+
+ select {
+ case <-tool1ExecCh:
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for tool_one to start")
+ }
+
+ active := al.GetActiveTurn()
+ if active == nil {
+ t.Fatal("expected active turn while tool is running")
+ }
+ if active.SessionKey != sessionKey {
+ t.Fatalf("expected active session %q, got %q", sessionKey, active.SessionKey)
+ }
+ if active.Channel != "test" || active.ChatID != "chat1" {
+ t.Fatalf("unexpected active turn target: %#v", active)
+ }
+
+ if err := al.InterruptGraceful("wrap it up"); err != nil {
+ t.Fatalf("InterruptGraceful failed: %v", err)
+ }
+
+ select {
+ case r := <-resultCh:
+ if r.err != nil {
+ t.Fatalf("unexpected error: %v", r.err)
+ }
+ if r.resp != "graceful summary" {
+ t.Fatalf("expected graceful summary, got %q", r.resp)
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatal("timeout waiting for graceful interrupt result")
+ }
+
+ if active := al.GetActiveTurn(); active != nil {
+ t.Fatalf("expected no active turn after completion, got %#v", active)
+ }
+
+ provider.mu.Lock()
+ terminalMessages := append([]providers.Message(nil), provider.terminalMessages...)
+ terminalToolsCount := provider.terminalToolsCount
+ calls := provider.calls
+ provider.mu.Unlock()
+
+ if calls != 2 {
+ t.Fatalf("expected 2 provider calls, got %d", calls)
+ }
+ if terminalToolsCount != 0 {
+ t.Fatalf("expected graceful terminal call to disable tools, got %d tool defs", terminalToolsCount)
+ }
+
+ foundHint := false
+ foundSkipped := false
+ expectedHint := "Interrupt requested. Stop scheduling tools and provide a short final summary.\n\n" +
+ "Interrupt hint: wrap it up"
+ for _, msg := range terminalMessages {
+ if msg.Role == "user" && msg.Content == expectedHint {
+ foundHint = true
+ }
+ if msg.Role == "tool" && msg.ToolCallID == "call_2" && msg.Content == "Skipped due to graceful interrupt." {
+ foundSkipped = true
+ }
+ }
+ if !foundHint {
+ t.Fatal("expected graceful terminal call to include interrupt hint message")
+ }
+ if !foundSkipped {
+ t.Fatal("expected remaining tool to be marked as skipped after graceful interrupt")
+ }
+
+ events := collectEventStream(sub.C)
+ interruptEvt, ok := findEvent(events, EventKindInterruptReceived)
+ if !ok {
+ t.Fatal("expected interrupt received event")
+ }
+ interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload)
+ if !ok {
+ t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload)
+ }
+ if interruptPayload.Kind != InterruptKindGraceful {
+ t.Fatalf("expected graceful interrupt payload, got %q", interruptPayload.Kind)
+ }
+
+ turnEndEvt, ok := findEvent(events, EventKindTurnEnd)
+ if !ok {
+ t.Fatal("expected turn end event")
+ }
+ turnEndPayload, ok := turnEndEvt.Payload.(TurnEndPayload)
+ if !ok {
+ t.Fatalf("expected TurnEndPayload, got %T", turnEndEvt.Payload)
+ }
+ if turnEndPayload.Status != TurnEndStatusCompleted {
+ t.Fatalf("expected completed turn after graceful interrupt, got %q", turnEndPayload.Status)
+ }
+}
+
+func TestAgentLoop_InterruptHard_RestoresSession(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ provider := &toolCallProvider{
+ toolCalls: []providers.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Name: "cancel_tool",
+ Function: &providers.FunctionCall{
+ Name: "cancel_tool",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ },
+ finalResp: "should not happen",
+ }
+
+ al := NewAgentLoop(cfg, msgBus, provider)
+ started := make(chan struct{})
+ al.RegisterTool(&interruptibleTool{name: "cancel_tool", started: started})
+ sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID)
+
+ defaultAgent := al.registry.GetDefaultAgent()
+ if defaultAgent == nil {
+ t.Fatal("expected default agent")
+ }
+
+ originalHistory := []providers.Message{
+ {Role: "user", Content: "before"},
+ {Role: "assistant", Content: "after"},
+ }
+ defaultAgent.Sessions.SetHistory(sessionKey, originalHistory)
+
+ sub := al.SubscribeEvents(16)
+ defer al.UnsubscribeEvents(sub.ID)
+
+ type result struct {
+ resp string
+ err error
+ }
+ resultCh := make(chan result, 1)
+ go func() {
+ resp, err := al.ProcessDirectWithChannel(
+ context.Background(),
+ "do work",
+ sessionKey,
+ "test",
+ "chat1",
+ )
+ resultCh <- result{resp: resp, err: err}
+ }()
+
+ select {
+ case <-started:
+ case <-time.After(2 * time.Second):
+ t.Fatal("timeout waiting for interruptible tool to start")
+ }
+
+ if active := al.GetActiveTurn(); active == nil {
+ t.Fatal("expected active turn before hard abort")
+ }
+
+ if err := al.InterruptHard(); err != nil {
+ t.Fatalf("InterruptHard failed: %v", err)
+ }
+
+ select {
+ case r := <-resultCh:
+ if r.err != nil {
+ t.Fatalf("unexpected error: %v", r.err)
+ }
+ if r.resp != "" {
+ t.Fatalf("expected no final response after hard abort, got %q", r.resp)
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatal("timeout waiting for hard abort result")
+ }
+
+ if active := al.GetActiveTurn(); active != nil {
+ t.Fatalf("expected no active turn after hard abort, got %#v", active)
+ }
+
+ finalHistory := defaultAgent.Sessions.GetHistory(sessionKey)
+ if !reflect.DeepEqual(finalHistory, originalHistory) {
+ t.Fatalf("expected history rollback after hard abort, got %#v", finalHistory)
+ }
+
+ events := collectEventStream(sub.C)
+ interruptEvt, ok := findEvent(events, EventKindInterruptReceived)
+ if !ok {
+ t.Fatal("expected interrupt received event")
+ }
+ interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload)
+ if !ok {
+ t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload)
+ }
+ if interruptPayload.Kind != InterruptKindHard {
+ t.Fatalf("expected hard interrupt payload, got %q", interruptPayload.Kind)
+ }
+
+ turnEndEvt, ok := findEvent(events, EventKindTurnEnd)
+ if !ok {
+ t.Fatal("expected turn end event")
+ }
+ turnEndPayload, ok := turnEndEvt.Payload.(TurnEndPayload)
+ if !ok {
+ t.Fatalf("expected TurnEndPayload, got %T", turnEndEvt.Payload)
+ }
+ if turnEndPayload.Status != TurnEndStatusAborted {
+ t.Fatalf("expected aborted turn, got %q", turnEndPayload.Status)
+ }
+}
+
+// capturingMockProvider captures messages sent to Chat for inspection.
+type capturingMockProvider struct {
+ response string
+ calls int
+ captureFn func([]providers.Message)
+}
+
+func (m *capturingMockProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ m.calls++
+ if m.captureFn != nil {
+ m.captureFn(messages)
+ }
+ return &providers.LLMResponse{
+ Content: m.response,
+ ToolCalls: []providers.ToolCall{},
+ }, nil
+}
+
+func (m *capturingMockProvider) GetDefaultModel() string {
+ return "capturing-mock"
+}
+
+func TestAgentLoop_Steering_SkippedToolsHaveErrorResults(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,
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+
+ execCh := make(chan struct{})
+ tool1 := &slowTool{name: "slow_tool", duration: 50 * time.Millisecond, execCh: execCh}
+ tool2 := &slowTool{name: "skipped_tool", duration: 50 * time.Millisecond}
+
+ // Provider that captures messages on the second call (after tools)
+ var secondCallMessages []providers.Message
+ var capMu sync.Mutex
+ callCount := 0
+
+ provider := &toolCallProvider{
+ toolCalls: []providers.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Name: "slow_tool",
+ Function: &providers.FunctionCall{
+ Name: "slow_tool",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ {
+ ID: "call_2",
+ Type: "function",
+ Name: "skipped_tool",
+ Function: &providers.FunctionCall{
+ Name: "skipped_tool",
+ Arguments: "{}",
+ },
+ Arguments: map[string]any{},
+ },
+ },
+ finalResp: "done",
+ }
+
+ // Wrap provider to capture messages on second call
+ wrappedProvider := &wrappingProvider{
+ inner: provider,
+ onChat: func(msgs []providers.Message) {
+ capMu.Lock()
+ callCount++
+ if callCount >= 2 {
+ secondCallMessages = make([]providers.Message, len(msgs))
+ copy(secondCallMessages, msgs)
+ }
+ capMu.Unlock()
+ },
+ }
+
+ msgBus := bus.NewMessageBus()
+ al := NewAgentLoop(cfg, msgBus, wrappedProvider)
+ al.RegisterTool(tool1)
+ al.RegisterTool(tool2)
+
+ resultCh := make(chan string, 1)
+ go func() {
+ resp, _ := al.ProcessDirectWithChannel(
+ context.Background(), "go", "test-session", "test", "chat1",
+ )
+ resultCh <- resp
+ }()
+
+ <-execCh
+ al.Steer(providers.Message{Role: "user", Content: "interrupt!"})
+
+ select {
+ case <-resultCh:
+ case <-time.After(5 * time.Second):
+ t.Fatal("timeout")
+ }
+
+ // Check that the skipped tool result message is in the conversation
+ capMu.Lock()
+ msgs := secondCallMessages
+ capMu.Unlock()
+
+ foundSkipped := false
+ for _, m := range msgs {
+ if m.Role == "tool" && m.ToolCallID == "call_2" && m.Content == "Skipped due to queued user message." {
+ foundSkipped = true
+ break
+ }
+ }
+ if !foundSkipped {
+ // Log what we actually got
+ for i, m := range msgs {
+ t.Logf("msg[%d]: role=%s toolCallID=%s content=%s", i, m.Role, m.ToolCallID, truncate(m.Content, 80))
+ }
+ t.Fatal("expected skipped tool result for call_2")
+ }
+}
+
+func truncate(s string, n int) string {
+ if len(s) <= n {
+ return s
+ }
+ return s[:n] + "..."
+}
+
+// wrappingProvider wraps another provider to hook into Chat calls.
+type wrappingProvider struct {
+ inner providers.LLMProvider
+ onChat func([]providers.Message)
+}
+
+func (w *wrappingProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ if w.onChat != nil {
+ w.onChat(messages)
+ }
+ return w.inner.Chat(ctx, messages, tools, model, opts)
+}
+
+func (w *wrappingProvider) GetDefaultModel() string {
+ return w.inner.GetDefaultModel()
+}
+
+// Ensure NormalizeToolCall handles our test tool calls.
+func init() {
+ // This is a no-op init; we just need the tool call tests to work
+ // with the proper argument serialization.
+ _ = json.Marshal
+}
diff --git a/pkg/agent/subturn.go b/pkg/agent/subturn.go
new file mode 100644
index 000000000..f5ba412ab
--- /dev/null
+++ b/pkg/agent/subturn.go
@@ -0,0 +1,671 @@
+package agent
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/tools"
+)
+
+// ====================== Config & Constants ======================
+const (
+ // Default values for SubTurn configuration (used when config is not set or is zero)
+ defaultMaxSubTurnDepth = 3
+ defaultMaxConcurrentSubTurns = 5
+ defaultConcurrencyTimeout = 30 * time.Second
+ defaultSubTurnTimeout = 5 * time.Minute
+ // maxEphemeralHistorySize limits the number of messages stored in ephemeral sessions.
+ // This prevents memory accumulation in long-running sub-turns.
+ maxEphemeralHistorySize = 50
+)
+
+var (
+ ErrDepthLimitExceeded = errors.New("sub-turn depth limit exceeded")
+ ErrInvalidSubTurnConfig = errors.New("invalid sub-turn config")
+ ErrConcurrencyTimeout = errors.New("timeout waiting for concurrency slot")
+)
+
+// getSubTurnConfig returns the effective SubTurn configuration with defaults applied.
+func (al *AgentLoop) getSubTurnConfig() subTurnRuntimeConfig {
+ cfg := al.cfg.Agents.Defaults.SubTurn
+
+ maxDepth := cfg.MaxDepth
+ if maxDepth <= 0 {
+ maxDepth = defaultMaxSubTurnDepth
+ }
+
+ maxConcurrent := cfg.MaxConcurrent
+ if maxConcurrent <= 0 {
+ maxConcurrent = defaultMaxConcurrentSubTurns
+ }
+
+ concurrencyTimeout := time.Duration(cfg.ConcurrencyTimeoutSec) * time.Second
+ if concurrencyTimeout <= 0 {
+ concurrencyTimeout = defaultConcurrencyTimeout
+ }
+
+ defaultTimeout := time.Duration(cfg.DefaultTimeoutMinutes) * time.Minute
+ if defaultTimeout <= 0 {
+ defaultTimeout = defaultSubTurnTimeout
+ }
+
+ return subTurnRuntimeConfig{
+ maxDepth: maxDepth,
+ maxConcurrent: maxConcurrent,
+ concurrencyTimeout: concurrencyTimeout,
+ defaultTimeout: defaultTimeout,
+ defaultTokenBudget: cfg.DefaultTokenBudget,
+ }
+}
+
+// subTurnRuntimeConfig holds the effective runtime configuration for SubTurn execution.
+type subTurnRuntimeConfig struct {
+ maxDepth int
+ maxConcurrent int
+ concurrencyTimeout time.Duration
+ defaultTimeout time.Duration
+ defaultTokenBudget int
+}
+
+// ====================== SubTurn Config ======================
+
+// SubTurnConfig configures the execution of a child sub-turn.
+//
+// Usage Examples:
+//
+// Synchronous sub-turn (Async=false):
+//
+// cfg := SubTurnConfig{
+// Model: "gpt-4o-mini",
+// SystemPrompt: "Analyze this code",
+// Async: false, // Result returned immediately
+// }
+// result, err := SpawnSubTurn(ctx, cfg)
+// // Use result directly here
+// processResult(result)
+//
+// Asynchronous sub-turn (Async=true):
+//
+// cfg := SubTurnConfig{
+// Model: "gpt-4o-mini",
+// SystemPrompt: "Background analysis",
+// Async: true, // Result delivered to channel
+// }
+// result, err := SpawnSubTurn(ctx, cfg)
+// // Result also available in parent's pendingResults channel
+// // Parent turn will poll and process it in a later iteration
+type SubTurnConfig struct {
+ Model string
+ Tools []tools.Tool
+ SystemPrompt string
+ MaxTokens int
+
+ // Async controls the result delivery mechanism:
+ //
+ // When Async = false (synchronous sub-turn):
+ // - The caller blocks until the sub-turn completes
+ // - The result is ONLY returned via the function return value
+ // - The result is NOT delivered to the parent's pendingResults channel
+ // - This prevents double delivery: caller gets result immediately, no need for channel
+ // - Use case: When the caller needs the result immediately to continue execution
+ // - Example: A tool that needs to process the sub-turn result before returning
+ //
+ // When Async = true (asynchronous sub-turn):
+ // - The sub-turn runs in the background (still blocks the caller, but semantically async)
+ // - The result is delivered to the parent's pendingResults channel
+ // - The result is ALSO returned via the function return value (for consistency)
+ // - The parent turn can poll pendingResults in later iterations to process results
+ // - Use case: Fire-and-forget operations, or when results are processed in batches
+ // - Example: Spawning multiple sub-turns in parallel and collecting results later
+ //
+ // IMPORTANT: The Async flag does NOT make the call non-blocking. It only controls
+ // whether the result is delivered via the channel. For true non-blocking execution,
+ // the caller must spawn the sub-turn in a separate goroutine.
+ Async bool
+
+ // Critical indicates this SubTurn's result is important and should continue
+ // running even after the parent turn finishes gracefully.
+ //
+ // When parent finishes gracefully (Finish(false)):
+ // - Critical=true: SubTurn continues running, delivers result as orphan
+ // - Critical=false: SubTurn exits gracefully without error
+ //
+ // When parent finishes with hard abort (Finish(true)):
+ // - All SubTurns are canceled regardless of Critical flag
+ Critical bool
+
+ // Timeout is the maximum duration for this SubTurn.
+ // If the SubTurn runs longer than this, it will be canceled.
+ // Default is 5 minutes (defaultSubTurnTimeout) if not specified.
+ Timeout time.Duration
+
+ // MaxContextRunes limits the context size (in runes) passed to the SubTurn.
+ // This prevents context window overflow by truncating message history before LLM calls.
+ //
+ // Values:
+ // 0 = Auto-calculate based on model's ContextWindow * 0.75 (default, recommended)
+ // -1 = No limit (disable soft truncation, rely only on hard context errors)
+ // >0 = Use specified rune limit
+ //
+ // The soft limit acts as a first line of defense before hitting the provider's
+ // hard context window limit. When exceeded, older messages are intelligently
+ // truncated while preserving system messages and recent context.
+ MaxContextRunes int
+
+ // ActualSystemPrompt is injected as the true 'system' role message for the childAgent.
+ // The legacy SystemPrompt field is actually used as the first 'user' message (task description).
+ ActualSystemPrompt string
+
+ // InitialMessages preloads the ephemeral session history before the agent loop starts.
+ // Used by evaluator-optimizer patterns to pass the full worker context across multiple iterations.
+ InitialMessages []providers.Message
+
+ // InitialTokenBudget is a shared atomic counter for tracking remaining tokens.
+ // If set, the SubTurn will inherit this budget and deduct tokens after each LLM call.
+ // If nil, the SubTurn will inherit the parent's tokenBudget (if any).
+ // Used by team tool to enforce token limits across all team members.
+ InitialTokenBudget *atomic.Int64
+
+ // Can be extended with temperature, topP, etc.
+}
+
+// ====================== Context Keys ======================
+type agentLoopKeyType struct{}
+
+var agentLoopKey = agentLoopKeyType{}
+
+// WithAgentLoop injects AgentLoop into context for tool access
+func WithAgentLoop(ctx context.Context, al *AgentLoop) context.Context {
+ return context.WithValue(ctx, agentLoopKey, al)
+}
+
+// AgentLoopFromContext retrieves AgentLoop from context
+func AgentLoopFromContext(ctx context.Context) *AgentLoop {
+ al, _ := ctx.Value(agentLoopKey).(*AgentLoop)
+ return al
+}
+
+// ====================== Helper Functions ======================
+
+func (al *AgentLoop) generateSubTurnID() string {
+ return fmt.Sprintf("subturn-%d", al.subTurnCounter.Add(1))
+}
+
+// ====================== Core Function: spawnSubTurn ======================
+
+// AgentLoopSpawner implements tools.SubTurnSpawner interface.
+// This allows tools to spawn sub-turns without circular dependency.
+type AgentLoopSpawner struct {
+ al *AgentLoop
+}
+
+// SpawnSubTurn implements tools.SubTurnSpawner interface.
+func (s *AgentLoopSpawner) SpawnSubTurn(
+ ctx context.Context,
+ cfg tools.SubTurnConfig,
+) (*tools.ToolResult, error) {
+ parentTS := turnStateFromContext(ctx)
+ if parentTS == nil {
+ return nil, errors.New(
+ "parent turnState not found in context - cannot spawn sub-turn outside of a turn",
+ )
+ }
+
+ // Convert tools.SubTurnConfig to agent.SubTurnConfig
+ agentCfg := SubTurnConfig{
+ Model: cfg.Model,
+ Tools: cfg.Tools,
+ SystemPrompt: cfg.SystemPrompt,
+ ActualSystemPrompt: cfg.ActualSystemPrompt,
+ InitialMessages: cfg.InitialMessages,
+ InitialTokenBudget: cfg.InitialTokenBudget,
+ MaxTokens: cfg.MaxTokens,
+ Async: cfg.Async,
+ Critical: cfg.Critical,
+ Timeout: cfg.Timeout,
+ MaxContextRunes: cfg.MaxContextRunes,
+ }
+
+ return spawnSubTurn(ctx, s.al, parentTS, agentCfg)
+}
+
+// NewSubTurnSpawner creates a SubTurnSpawner for the given AgentLoop.
+func NewSubTurnSpawner(al *AgentLoop) *AgentLoopSpawner {
+ return &AgentLoopSpawner{al: al}
+}
+
+// SpawnSubTurn is the exported entry point for tools to spawn sub-turns.
+// It retrieves AgentLoop and parent turnState from context and delegates to spawnSubTurn.
+func SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*tools.ToolResult, error) {
+ al := AgentLoopFromContext(ctx)
+ if al == nil {
+ return nil, errors.New(
+ "AgentLoop not found in context - ensure context is properly initialized",
+ )
+ }
+
+ parentTS := turnStateFromContext(ctx)
+ if parentTS == nil {
+ return nil, errors.New(
+ "parent turnState not found in context - cannot spawn sub-turn outside of a turn",
+ )
+ }
+
+ return spawnSubTurn(ctx, al, parentTS, cfg)
+}
+
+func spawnSubTurn(
+ ctx context.Context,
+ al *AgentLoop,
+ parentTS *turnState,
+ cfg SubTurnConfig,
+) (result *tools.ToolResult, err error) {
+ // Get effective SubTurn configuration
+ rtCfg := al.getSubTurnConfig()
+
+ // 0. Acquire concurrency semaphore FIRST to ensure it's released even if early validation fails.
+ // Blocks if parent already has maxConcurrentSubTurns running, with a timeout to prevent indefinite blocking.
+ // Also respects context cancellation so we don't block forever if parent is aborted.
+ // NOTE: The semaphore is released immediately after runTurn completes (not in a defer) to
+ // ensure it is freed before the cleanup phase (async result delivery), which may block on
+ // a full pendingResults channel. Holding the semaphore through cleanup would allow the
+ // parent's goroutine to be blocked waiting for a semaphore slot while child turns are
+ // blocked delivering results — a deadlock.
+ var semAcquired bool
+ if parentTS.concurrencySem != nil {
+ // Create a timeout context for semaphore acquisition
+ timeoutCtx, cancel := context.WithTimeout(ctx, rtCfg.concurrencyTimeout)
+ defer cancel()
+
+ select {
+ case parentTS.concurrencySem <- struct{}{}:
+ semAcquired = true
+ defer func() {
+ if semAcquired {
+ <-parentTS.concurrencySem
+ }
+ }()
+ case <-timeoutCtx.Done():
+ // Check parent context first - if it was canceled, propagate that error
+ if ctx.Err() != nil {
+ return nil, ctx.Err()
+ }
+ // Otherwise it's our timeout
+ return nil, fmt.Errorf("%w: all %d slots occupied for %v",
+ ErrConcurrencyTimeout, rtCfg.maxConcurrent, rtCfg.concurrencyTimeout)
+ }
+ }
+
+ // 1. Depth limit check
+ if parentTS.depth >= rtCfg.maxDepth {
+ logger.WarnCF("subturn", "Depth limit exceeded", map[string]any{
+ "parent_id": parentTS.turnID,
+ "depth": parentTS.depth,
+ "max_depth": rtCfg.maxDepth,
+ })
+ return nil, ErrDepthLimitExceeded
+ }
+
+ // 2. Config validation
+ if cfg.Model == "" {
+ return nil, ErrInvalidSubTurnConfig
+ }
+
+ // 3. Determine timeout for child SubTurn
+ timeout := cfg.Timeout
+ if timeout <= 0 {
+ timeout = rtCfg.defaultTimeout
+ }
+
+ // 4. Create INDEPENDENT child context (not derived from parent ctx).
+ // This allows the child to continue running after parent finishes gracefully.
+ // The child has its own timeout for self-protection.
+ childCtx, cancel := context.WithTimeout(context.Background(), timeout)
+ defer cancel()
+
+ childID := al.generateSubTurnID()
+
+ // Get the agent instance from parent, falling back to the default agent.
+ // Wrap it in a shallow copy that uses an ephemeral (in-memory only) session store
+ // so that child turns never pollute or persist to the parent's session history.
+ baseAgent := parentTS.agent
+ if baseAgent == nil {
+ baseAgent = al.registry.GetDefaultAgent()
+ }
+ if baseAgent == nil {
+ return nil, errors.New("parent turnState has no agent instance")
+ }
+ ephemeralStore := newEphemeralSession(nil)
+ agent := *baseAgent // shallow copy
+ agent.Sessions = ephemeralStore
+ // Clone the tool registry so child turn's tool registrations
+ // don't pollute the parent's registry.
+ if baseAgent.Tools != nil {
+ agent.Tools = baseAgent.Tools.Clone()
+ }
+
+ // Create processOptions for the child turn
+ opts := processOptions{
+ SessionKey: childID,
+ Channel: parentTS.channel,
+ ChatID: parentTS.chatID,
+ SenderID: parentTS.opts.SenderID,
+ SenderDisplayName: parentTS.opts.SenderDisplayName,
+ UserMessage: cfg.SystemPrompt, // Task description becomes the first user message
+ SystemPromptOverride: cfg.ActualSystemPrompt,
+ Media: nil,
+ InitialSteeringMessages: cfg.InitialMessages,
+ DefaultResponse: "",
+ EnableSummary: false,
+ SendResponse: false,
+ NoHistory: true, // SubTurns don't use session history
+ SkipInitialSteeringPoll: true,
+ }
+
+ // Create event scope for the child turn
+ scope := al.newTurnEventScope(agent.ID, childID)
+
+ // Create child turnState using the new API
+ childTS := newTurnState(&agent, opts, scope)
+
+ // Set SubTurn-specific fields
+ childTS.cancelFunc = cancel
+ childTS.critical = cfg.Critical
+ childTS.depth = parentTS.depth + 1
+ childTS.parentTurnID = parentTS.turnID
+ childTS.parentTurnState = parentTS
+ childTS.pendingResults = make(chan *tools.ToolResult, 16)
+ childTS.concurrencySem = make(chan struct{}, rtCfg.maxConcurrent)
+ childTS.al = al // back-ref for hard abort cascade
+ childTS.session = ephemeralStore // same store as agent.Sessions
+
+ // Token budget initialization/inheritance
+ // If InitialTokenBudget is explicitly provided (e.g., by team tool), use it.
+ // Otherwise, inherit from parent's tokenBudget (for nested SubTurns).
+ if cfg.InitialTokenBudget != nil {
+ childTS.tokenBudget = cfg.InitialTokenBudget
+ } else if parentTS.tokenBudget != nil {
+ childTS.tokenBudget = parentTS.tokenBudget
+ } else if rtCfg.defaultTokenBudget > 0 {
+ // Apply default token budget from config if no budget is set
+ budget := &atomic.Int64{}
+ budget.Store(int64(rtCfg.defaultTokenBudget))
+ childTS.tokenBudget = budget
+ }
+
+ // IMPORTANT: Put childTS into childCtx so that code inside runTurn can retrieve it
+ childCtx = withTurnState(childCtx, childTS)
+ childCtx = WithAgentLoop(childCtx, al) // Propagate AgentLoop to child turn
+
+ childTS.ctx = childCtx
+
+ // Register child turn state so GetAllActiveTurns/Subagents can find it
+ al.activeTurnStates.Store(childID, childTS)
+ defer al.activeTurnStates.Delete(childID)
+
+ // 5. Establish parent-child relationship (thread-safe)
+ parentTS.mu.Lock()
+ parentTS.childTurnIDs = append(parentTS.childTurnIDs, childID)
+ parentTS.mu.Unlock()
+
+ // 6. Emit Spawn event
+ al.emitEvent(EventKindSubTurnSpawn,
+ childTS.eventMeta("spawnSubTurn", "subturn.spawn"),
+ SubTurnSpawnPayload{
+ AgentID: childTS.agentID,
+ Label: childID,
+ ParentTurnID: parentTS.turnID,
+ },
+ )
+
+ // 7. Defer cleanup: deliver result (for async), emit End event, and recover from panics
+ defer func() {
+ if r := recover(); r != nil {
+ err = fmt.Errorf("subturn panicked: %v", r)
+ result = nil
+ logger.ErrorCF("subturn", "SubTurn panicked", map[string]any{
+ "child_id": childID,
+ "parent_id": parentTS.turnID,
+ "panic": r,
+ })
+ }
+
+ // Result Delivery Strategy (Async vs Sync)
+ if cfg.Async {
+ deliverSubTurnResult(al, parentTS, childID, result)
+ }
+
+ status := "completed"
+ if err != nil {
+ status = "error"
+ }
+ al.emitEvent(EventKindSubTurnEnd,
+ childTS.eventMeta("spawnSubTurn", "subturn.end"),
+ SubTurnEndPayload{
+ AgentID: childTS.agentID,
+ Status: status,
+ },
+ )
+ }()
+
+ // 8. Execute sub-turn via the real agent loop.
+ turnRes, turnErr := al.runTurn(childCtx, childTS)
+
+ // Release the concurrency semaphore immediately after runTurn completes,
+ // before the cleanup defer runs. This prevents a deadlock where:
+ // - All semaphore slots are held by sub-turns in their cleanup phase
+ // - Cleanup blocks on a full pendingResults channel
+ // - The parent goroutine is blocked waiting for a semaphore slot
+ // - The parent cannot consume pendingResults because it is blocked on the semaphore
+ if semAcquired {
+ <-parentTS.concurrencySem
+ semAcquired = false // prevent the defer from double-releasing
+ }
+
+ // Convert turnResult to tools.ToolResult
+ if turnErr != nil {
+ err = turnErr
+ result = &tools.ToolResult{
+ Err: turnErr,
+ ForLLM: fmt.Sprintf("SubTurn failed: %v", turnErr),
+ }
+ } else {
+ result = &tools.ToolResult{
+ ForLLM: turnRes.finalContent,
+ ForUser: turnRes.finalContent,
+ }
+ }
+
+ return result, err
+}
+
+// ====================== Result Delivery ======================
+
+// deliverSubTurnResult delivers a sub-turn result to the parent turn's pendingResults channel.
+//
+// IMPORTANT: This function is ONLY called for asynchronous sub-turns (Async=true).
+// For synchronous sub-turns (Async=false), results are returned directly via the function
+// return value to avoid double delivery.
+//
+// Delivery behavior:
+// - If parent turn is still running: attempts to deliver to pendingResults channel
+// - If channel is full: emits SubTurnOrphanResultEvent (result is lost from channel but tracked)
+// - If parent turn has finished: emits SubTurnOrphanResultEvent (late arrival)
+//
+// Thread safety:
+// - Reads parent state under lock, then releases lock before channel send
+// - Small race window exists but is acceptable (worst case: result becomes orphan)
+//
+// Event emissions:
+// - SubTurnResultDeliveredEvent: successful delivery to channel
+// - SubTurnOrphanResultEvent: delivery failed (parent finished or channel full)
+func deliverSubTurnResult(al *AgentLoop, parentTS *turnState, childID string, result *tools.ToolResult) {
+ // Let GC clean up the pendingResults channel; parent Finish will no longer close it.
+ // We use defer/recover to catch any unlikely channel panics if it were ever closed.
+ defer func() {
+ if r := recover(); r != nil {
+ logger.WarnCF("subturn", "recovered panic sending to pendingResults", map[string]any{
+ "parent_id": parentTS.turnID,
+ "child_id": childID,
+ "recover": r,
+ })
+ if result != nil && al != nil {
+ al.emitEvent(EventKindSubTurnOrphan,
+ parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"),
+ SubTurnOrphanPayload{ParentTurnID: parentTS.turnID, ChildTurnID: childID, Reason: "panic"},
+ )
+ }
+ }
+ }()
+ parentTS.mu.Lock()
+ isFinished := parentTS.isFinished.Load()
+ resultChan := parentTS.pendingResults
+ parentTS.mu.Unlock()
+
+ // If parent turn has already finished, treat this as an orphan result
+ if isFinished || resultChan == nil {
+ if result != nil && al != nil {
+ al.emitEvent(EventKindSubTurnOrphan,
+ parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"),
+ SubTurnOrphanPayload{ParentTurnID: parentTS.turnID, ChildTurnID: childID, Reason: "parent_finished"},
+ )
+ }
+ return
+ }
+
+ // Parent Turn is still running → attempt to deliver result
+ // We use a select statement with parentTS.Finished() to ensure that if the
+ // parent turn finishes while we are waiting to send the result (e.g. channel
+ // is full), we don't leak this goroutine by blocking forever.
+ select {
+ case resultChan <- result:
+ // Successfully delivered
+ if al != nil {
+ al.emitEvent(EventKindSubTurnResultDelivered,
+ parentTS.eventMeta("deliverSubTurnResult", "subturn.result_delivered"),
+ SubTurnResultDeliveredPayload{ContentLen: len(result.ForLLM)},
+ )
+ }
+ case <-parentTS.Finished():
+ // Parent finished while we were waiting to deliver.
+ // The result cannot be delivered to the LLM, so it becomes an orphan.
+ logger.WarnCF("subturn", "parent finished before result could be delivered", map[string]any{
+ "parent_id": parentTS.turnID,
+ "child_id": childID,
+ })
+ if result != nil && al != nil {
+ al.emitEvent(
+ EventKindSubTurnOrphan,
+ parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"),
+ SubTurnOrphanPayload{
+ ParentTurnID: parentTS.turnID,
+ ChildTurnID: childID,
+ Reason: "parent_finished_waiting",
+ },
+ )
+ }
+ }
+}
+
+// ====================== Other Types ======================
+
+// ephemeralSessionStore is an in-memory session.SessionStore used by SubTurns.
+// It does not persist to disk and auto-truncates history to maxEphemeralHistorySize.
+type ephemeralSessionStore struct {
+ mu sync.Mutex
+ history []providers.Message
+ summary string
+}
+
+func newEphemeralSession(initial []providers.Message) ephemeralSessionStoreIface {
+ s := &ephemeralSessionStore{}
+ if len(initial) > 0 {
+ s.history = append(s.history, initial...)
+ }
+ return s
+}
+
+// ephemeralSessionStoreIface is satisfied by *ephemeralSessionStore.
+// Declared so newEphemeralSession can return a typed interface.
+type ephemeralSessionStoreIface interface {
+ AddMessage(sessionKey, role, content string)
+ AddFullMessage(sessionKey string, msg providers.Message)
+ GetHistory(key string) []providers.Message
+ GetSummary(key string) string
+ SetSummary(key, summary string)
+ SetHistory(key string, history []providers.Message)
+ TruncateHistory(key string, keepLast int)
+ Save(key string) error
+ Close() error
+}
+
+func (e *ephemeralSessionStore) AddMessage(_, role, content string) {
+ e.mu.Lock()
+ defer e.mu.Unlock()
+ e.history = append(e.history, providers.Message{Role: role, Content: content})
+ e.truncateLocked()
+}
+
+func (e *ephemeralSessionStore) AddFullMessage(_ string, msg providers.Message) {
+ e.mu.Lock()
+ defer e.mu.Unlock()
+ e.history = append(e.history, msg)
+ e.truncateLocked()
+}
+
+func (e *ephemeralSessionStore) GetHistory(_ string) []providers.Message {
+ e.mu.Lock()
+ defer e.mu.Unlock()
+ out := make([]providers.Message, len(e.history))
+ copy(out, e.history)
+ return out
+}
+
+func (e *ephemeralSessionStore) GetSummary(_ string) string {
+ e.mu.Lock()
+ defer e.mu.Unlock()
+ return e.summary
+}
+
+func (e *ephemeralSessionStore) SetSummary(_, summary string) {
+ e.mu.Lock()
+ defer e.mu.Unlock()
+ e.summary = summary
+}
+
+func (e *ephemeralSessionStore) SetHistory(_ string, history []providers.Message) {
+ e.mu.Lock()
+ defer e.mu.Unlock()
+ e.history = make([]providers.Message, len(history))
+ copy(e.history, history)
+ e.truncateLocked()
+}
+
+func (e *ephemeralSessionStore) TruncateHistory(_ string, keepLast int) {
+ e.mu.Lock()
+ defer e.mu.Unlock()
+ if keepLast <= 0 {
+ e.history = nil
+ return
+ }
+
+ if keepLast >= len(e.history) {
+ return
+ }
+ e.history = e.history[len(e.history)-keepLast:]
+}
+
+func (e *ephemeralSessionStore) Save(_ string) error { return nil }
+func (e *ephemeralSessionStore) Close() error { return nil }
+
+func (e *ephemeralSessionStore) truncateLocked() {
+ if len(e.history) > maxEphemeralHistorySize {
+ e.history = e.history[len(e.history)-maxEphemeralHistorySize:]
+ }
+}
diff --git a/pkg/agent/subturn_test.go b/pkg/agent/subturn_test.go
new file mode 100644
index 000000000..6a2ba835d
--- /dev/null
+++ b/pkg/agent/subturn_test.go
@@ -0,0 +1,2067 @@
+package agent
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/tools"
+)
+
+// Test constants (use defaults from subturn.go)
+const (
+ testMaxConcurrentSubTurns = defaultMaxConcurrentSubTurns
+)
+
+// ====================== Test Helper: Event Collector ======================
+type eventCollector struct {
+ mu sync.Mutex
+ events []Event
+}
+
+func newEventCollector(t *testing.T, al *AgentLoop) (*eventCollector, func()) {
+ t.Helper()
+ c := &eventCollector{}
+ sub := al.SubscribeEvents(16)
+ done := make(chan struct{})
+ go func() {
+ defer close(done)
+ for evt := range sub.C {
+ c.mu.Lock()
+ c.events = append(c.events, evt)
+ c.mu.Unlock()
+ }
+ }()
+ cleanup := func() {
+ al.UnsubscribeEvents(sub.ID)
+ <-done
+ }
+ return c, cleanup
+}
+
+func (c *eventCollector) hasEventOfKind(kind EventKind) bool {
+ c.mu.Lock()
+ defer c.mu.Unlock()
+ for _, e := range c.events {
+ if e.Kind == kind {
+ return true
+ }
+ }
+ return false
+}
+
+// ====================== Main Test Function ======================
+func TestSpawnSubTurn(t *testing.T) {
+ tests := []struct {
+ name string
+ parentDepth int
+ config SubTurnConfig
+ wantErr error
+ wantSpawn bool
+ wantEnd bool
+ wantDepthFail bool
+ }{
+ {
+ name: "Basic success path - Single layer sub-turn",
+ parentDepth: 0,
+ config: SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Tools: []tools.Tool{}, // At least one tool
+ },
+ wantErr: nil,
+ wantSpawn: true,
+ wantEnd: true,
+ },
+ {
+ name: "Nested 2 layers - Normal",
+ parentDepth: 1,
+ config: SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Tools: []tools.Tool{},
+ },
+ wantErr: nil,
+ wantSpawn: true,
+ wantEnd: true,
+ },
+ {
+ name: "Depth limit triggered - 4th layer fails",
+ parentDepth: 3,
+ config: SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Tools: []tools.Tool{},
+ },
+ wantErr: ErrDepthLimitExceeded,
+ wantSpawn: false,
+ wantEnd: false,
+ wantDepthFail: true,
+ },
+ {
+ name: "Invalid config - Empty Model",
+ parentDepth: 0,
+ config: SubTurnConfig{
+ Model: "",
+ Tools: []tools.Tool{},
+ },
+ wantErr: ErrInvalidSubTurnConfig,
+ wantSpawn: false,
+ wantEnd: false,
+ },
+ }
+
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ // Prepare parent Turn
+ parent := &turnState{
+ ctx: context.Background(),
+ turnID: "parent-1",
+ depth: tt.parentDepth,
+ childTurnIDs: []string{},
+ pendingResults: make(chan *tools.ToolResult, 10),
+ session: &ephemeralSessionStore{},
+ agent: al.registry.GetDefaultAgent(),
+ }
+
+ // Subscribe to real EventBus to capture events
+ collector, collectCleanup := newEventCollector(t, al)
+ defer collectCleanup()
+
+ // Execute spawnSubTurn
+ result, err := spawnSubTurn(context.Background(), al, parent, tt.config)
+
+ // Assert errors
+ if tt.wantErr != nil {
+ if err == nil || err != tt.wantErr {
+ t.Errorf("expected error %v, got %v", tt.wantErr, err)
+ }
+ return
+ }
+ if err != nil {
+ t.Errorf("unexpected error: %v", err)
+ return
+ }
+
+ // Verify result
+ if result == nil {
+ t.Error("expected non-nil result")
+ }
+
+ // Verify event emission
+ time.Sleep(10 * time.Millisecond) // let event goroutine flush
+ if tt.wantSpawn {
+ if !collector.hasEventOfKind(EventKindSubTurnSpawn) {
+ t.Error("SubTurnSpawnEvent not emitted")
+ }
+ }
+ if tt.wantEnd {
+ if !collector.hasEventOfKind(EventKindSubTurnEnd) {
+ t.Error("SubTurnEndEvent not emitted")
+ }
+ }
+
+ // Verify turn tree
+ if len(parent.childTurnIDs) == 0 && !tt.wantDepthFail {
+ t.Error("child Turn not added to parent.childTurnIDs")
+ }
+
+ // For synchronous calls (Async=false, the default), result is returned directly
+ // and should NOT be in pendingResults. The result was already verified above.
+ // Only async calls (Async=true) would place results in pendingResults.
+ })
+ }
+}
+
+// ====================== Extra Independent Test: Ephemeral Session Isolation ======================
+func TestSpawnSubTurn_EphemeralSessionIsolation(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ // Parent uses its own ephemeral store pre-seeded with one message
+ parentSession := &ephemeralSessionStore{}
+ parentSession.AddMessage("", "user", "parent msg")
+ parent := &turnState{
+ ctx: context.Background(),
+ turnID: "parent-1",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 4),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ session: parentSession,
+ }
+
+ cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}}
+
+ originalParentLen := len(parentSession.GetHistory(""))
+
+ _, _ = spawnSubTurn(context.Background(), al, parent, cfg)
+
+ // Parent session must be untouched — child used its own store
+ if got := len(parentSession.GetHistory("")); got != originalParentLen {
+ t.Errorf("parent session polluted: expected %d messages, got %d", originalParentLen, got)
+ }
+
+ // The child's agent.Sessions must NOT be the same pointer as the parent's session.
+ // We verify this indirectly: spawnSubTurn stores childTS in activeTurnStates during
+ // execution (deleted on return), so we can't easily grab childTS after the call.
+ // Instead, confirm that the child session is a distinct ephemeralSessionStore by
+ // checking the parent session key is only used by the parent store.
+ // If isolation is correct, parent.session.GetHistory(childID) is always empty
+ // (the child never wrote to the parent store).
+ al.activeTurnStates.Range(func(k, v any) bool {
+ // No active turns should remain after spawnSubTurn returns
+ t.Errorf("unexpected active turn state left after spawnSubTurn: key=%v", k)
+ return true
+ })
+}
+
+// ====================== Extra Independent Test: Result Delivery Path (Async) ======================
+func TestSpawnSubTurn_ResultDelivery(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ parent := &turnState{
+ ctx: context.Background(),
+ turnID: "parent-1",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 1),
+ session: &ephemeralSessionStore{},
+ }
+
+ // Set Async=true to test async result delivery via pendingResults channel
+ cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: true}
+
+ _, _ = spawnSubTurn(context.Background(), al, parent, cfg)
+
+ // Check if pendingResults received the result (only for async calls)
+ select {
+ case res := <-parent.pendingResults:
+ if res == nil {
+ t.Error("received nil result in pendingResults")
+ }
+ default:
+ t.Error("result did not enter pendingResults for async call")
+ }
+}
+
+// ====================== Extra Independent Test: Result Delivery Path (Sync) ======================
+func TestSpawnSubTurn_ResultDeliverySync(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ parent := &turnState{
+ ctx: context.Background(),
+ turnID: "parent-sync-1",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 1),
+ session: &ephemeralSessionStore{},
+ }
+
+ // Sync call (Async=false, the default) - result should be returned directly
+ cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: false}
+
+ result, err := spawnSubTurn(context.Background(), al, parent, cfg)
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+
+ // Result should be returned directly
+ if result == nil {
+ t.Error("expected non-nil result from sync call")
+ }
+
+ // pendingResults should NOT contain the result (no double delivery)
+ select {
+ case <-parent.pendingResults:
+ t.Error("sync call should not place result in pendingResults (double delivery)")
+ default:
+ // Expected - channel should be empty
+ }
+}
+
+// ====================== Extra Independent Test: Orphan Result Routing ======================
+func TestSpawnSubTurn_OrphanResultRouting(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ collector, collectCleanup := newEventCollector(t, al)
+ defer collectCleanup()
+
+ parentCtx, cancelParent := context.WithCancel(context.Background())
+ parent := &turnState{
+ ctx: parentCtx,
+ cancelFunc: cancelParent,
+ turnID: "parent-1",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 1),
+ session: &ephemeralSessionStore{},
+ }
+
+ // Simulate parent finishing before child delivers result
+ parent.Finish(false)
+
+ // Call deliverSubTurnResult directly to simulate a delayed child
+ deliverSubTurnResult(al, parent, "delayed-child", &tools.ToolResult{ForLLM: "late result"})
+
+ time.Sleep(10 * time.Millisecond) // let event goroutine flush
+ // Verify Orphan event is emitted
+ if !collector.hasEventOfKind(EventKindSubTurnOrphan) {
+ t.Error("SubTurnOrphanResultEvent not emitted for finished parent")
+ }
+
+ // Verify history is NOT polluted
+ if len(parent.session.GetHistory("")) != 0 {
+ t.Error("Parent history was polluted by orphan result")
+ }
+}
+
+// ====================== Extra Independent Test: Result Channel Registration ======================
+func TestSubTurnResultChannelRegistration(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ parent := &turnState{
+ ctx: context.Background(),
+ turnID: "parent-reg-1",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 4),
+ session: &ephemeralSessionStore{},
+ }
+
+ cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}}
+
+ // Before spawn: channel should not be registered
+ if results := al.dequeuePendingSubTurnResults(parent.turnID); results != nil {
+ t.Error("expected no channel before spawnSubTurn")
+ }
+
+ _, _ = spawnSubTurn(context.Background(), al, parent, cfg)
+}
+
+// ====================== Extra Independent Test: Dequeue Pending SubTurn Results ======================
+func TestDequeuePendingSubTurnResults(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ sessionKey := "test-session-dequeue"
+
+ // Empty (no turnState registered) returns nil
+ if results := al.dequeuePendingSubTurnResults(sessionKey); len(results) != 0 {
+ t.Errorf("expected empty results, got %d", len(results))
+ }
+
+ // Register a turnState so dequeuePendingSubTurnResults can find it
+ ts := &turnState{
+ ctx: context.Background(),
+ turnID: sessionKey,
+ depth: 0,
+ session: &ephemeralSessionStore{},
+ pendingResults: make(chan *tools.ToolResult, 4),
+ }
+ al.activeTurnStates.Store(sessionKey, ts)
+ defer al.activeTurnStates.Delete(sessionKey)
+
+ // Put 3 results in
+ ts.pendingResults <- &tools.ToolResult{ForLLM: "result-1"}
+ ts.pendingResults <- &tools.ToolResult{ForLLM: "result-2"}
+ ts.pendingResults <- &tools.ToolResult{ForLLM: "result-3"}
+
+ results := al.dequeuePendingSubTurnResults(sessionKey)
+ if len(results) != 3 {
+ t.Errorf("expected 3 results, got %d", len(results))
+ }
+ if results[0].ForLLM != "result-1" || results[2].ForLLM != "result-3" {
+ t.Error("results order or content mismatch")
+ }
+
+ // Channel should be drained now
+ if results := al.dequeuePendingSubTurnResults(sessionKey); len(results) != 0 {
+ t.Errorf("expected empty after drain, got %d", len(results))
+ }
+
+ // After removing from activeTurnStates, returns nil
+ al.activeTurnStates.Delete(sessionKey)
+ if results := al.dequeuePendingSubTurnResults(sessionKey); results != nil {
+ t.Error("expected nil for unregistered session")
+ }
+}
+
+// ====================== Extra Independent Test: Concurrency Semaphore ======================
+func TestSubTurnConcurrencySemaphore(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ parent := &turnState{
+ ctx: context.Background(),
+ turnID: "parent-concurrency",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 10),
+ session: &ephemeralSessionStore{},
+ concurrencySem: make(chan struct{}, 2), // Only allow 2 concurrent children
+ }
+
+ cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}}
+
+ // Spawn 2 children — should succeed immediately
+ done := make(chan bool, 3)
+ for i := 0; i < 2; i++ {
+ go func() {
+ _, _ = spawnSubTurn(context.Background(), al, parent, cfg)
+ done <- true
+ }()
+ }
+
+ // Wait a bit to ensure the first 2 are running
+ // (In real scenario they'd be blocked in runTurn, but mockProvider returns immediately)
+ // So we just verify the semaphore doesn't block when under limit
+ <-done
+ <-done
+
+ // Verify semaphore is now full (2/2 slots used, but they already released)
+ // Since mockProvider returns immediately, semaphore is already released
+ // So we can't easily test blocking without a real long-running operation
+
+ // Instead, verify that semaphore exists and has correct capacity
+ if cap(parent.concurrencySem) != 2 {
+ t.Errorf("expected semaphore capacity 2, got %d", cap(parent.concurrencySem))
+ }
+}
+
+// ====================== Extra Independent Test: Hard Abort Cascading ======================
+func TestHardAbortCascading(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ sessionKey := "test-session-abort"
+
+ // Root turn with its own independent context (not derived from child)
+ rootCtx, rootCancel := context.WithCancel(context.Background())
+ rootTS := &turnState{
+ ctx: rootCtx,
+ cancelFunc: rootCancel,
+ turnID: sessionKey,
+ depth: 0,
+ session: &ephemeralSessionStore{},
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, 5),
+ al: al,
+ }
+ al.activeTurnStates.Store(sessionKey, rootTS)
+ defer al.activeTurnStates.Delete(sessionKey)
+
+ // Child turn with an INDEPENDENT context (simulates spawnSubTurn behavior:
+ // context.WithTimeout(context.Background(), ...) — NOT derived from parent).
+ // Cascade must therefore happen via childTurnIDs traversal, not Go context tree.
+ childCtx, childCancel := context.WithCancel(context.Background())
+ childID := "child-independent"
+ childTS := &turnState{
+ ctx: childCtx,
+ cancelFunc: childCancel,
+ turnID: childID,
+ pendingResults: make(chan *tools.ToolResult, 4),
+ al: al,
+ }
+ al.activeTurnStates.Store(childID, childTS)
+ defer al.activeTurnStates.Delete(childID)
+
+ // Wire child into root's childTurnIDs (as spawnSubTurn would do)
+ rootTS.childTurnIDs = append(rootTS.childTurnIDs, childID)
+
+ // Verify neither context is canceled yet
+ select {
+ case <-rootTS.ctx.Done():
+ t.Fatal("root context should not be canceled yet")
+ default:
+ }
+ select {
+ case <-childTS.ctx.Done():
+ t.Fatal("child context should not be canceled yet (independent context)")
+ default:
+ }
+
+ // Trigger Hard Abort via al.HardAbort (goes through steering.go → Finish(true))
+ err := al.HardAbort(sessionKey)
+ if err != nil {
+ t.Fatalf("HardAbort failed: %v", err)
+ }
+
+ // Root context must be canceled
+ select {
+ case <-rootTS.ctx.Done():
+ default:
+ t.Error("root context should be canceled after HardAbort")
+ }
+
+ // Child context must be canceled via childTurnIDs cascade, NOT via Go context tree
+ select {
+ case <-childTS.ctx.Done():
+ default:
+ t.Error("child context should be canceled via childTurnIDs cascade")
+ }
+
+ // HardAbort on non-existent session should return an error
+ if err := al.HardAbort("non-existent-session"); err == nil {
+ t.Error("expected error for non-existent session")
+ }
+}
+
+// TestHardAbortSessionRollback verifies that HardAbort rolls back session history
+// to the state before the turn started, discarding all messages added during the turn.
+func TestHardAbortSessionRollback(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ // Create a session with initial history
+ sess := &ephemeralSessionStore{
+ history: []providers.Message{
+ {Role: "user", Content: "initial message 1"},
+ {Role: "assistant", Content: "initial response 1"},
+ },
+ }
+
+ // Create a root turnState with initialHistoryLength = 2
+ rootTS := &turnState{
+ ctx: context.Background(),
+ turnID: "test-session",
+ depth: 0,
+ session: sess,
+ initialHistoryLength: 2, // Snapshot: 2 messages
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, 5),
+ }
+
+ // Register the turn state
+ al.activeTurnStates.Store("test-session", rootTS)
+
+ // Simulate adding messages during the turn (e.g., user input + assistant response)
+ sess.AddMessage("", "user", "new user message")
+ sess.AddMessage("", "assistant", "new assistant response")
+
+ // Verify history grew to 4 messages
+ if len(sess.GetHistory("")) != 4 {
+ t.Fatalf("expected 4 messages before abort, got %d", len(sess.GetHistory("")))
+ }
+
+ // Trigger HardAbort
+ err := al.HardAbort("test-session")
+ if err != nil {
+ t.Fatalf("HardAbort failed: %v", err)
+ }
+
+ // Verify history rolled back to initial 2 messages
+ finalHistory := sess.GetHistory("")
+ if len(finalHistory) != 2 {
+ t.Errorf("expected history to rollback to 2 messages, got %d", len(finalHistory))
+ }
+
+ // Verify the content matches the initial state
+ if finalHistory[0].Content != "initial message 1" || finalHistory[1].Content != "initial response 1" {
+ t.Error("history content does not match initial state after rollback")
+ }
+}
+
+// TestNestedSubTurnHierarchy verifies that nested SubTurns maintain correct
+// parent-child relationships and depth tracking when recursively calling runAgentLoop.
+func TestNestedSubTurnHierarchy(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ // Track spawned turns and their depths
+ type turnInfo struct {
+ parentID string
+ childID string
+ }
+ var spawnedTurns []turnInfo
+ var mu sync.Mutex
+
+ // Subscribe to real EventBus to capture spawn events
+ sub := al.SubscribeEvents(16)
+ defer al.UnsubscribeEvents(sub.ID)
+ go func() {
+ for evt := range sub.C {
+ if evt.Kind == EventKindSubTurnSpawn {
+ p, _ := evt.Payload.(SubTurnSpawnPayload)
+ mu.Lock()
+ spawnedTurns = append(spawnedTurns, turnInfo{
+ parentID: p.ParentTurnID,
+ childID: p.Label,
+ })
+ mu.Unlock()
+ }
+ }
+ }()
+
+ // Create a root turn
+ rootSession := &ephemeralSessionStore{}
+ rootTS := &turnState{
+ ctx: context.Background(),
+ turnID: "root-turn",
+ depth: 0,
+ session: rootSession,
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, 5),
+ }
+
+ // Spawn a child (depth 1)
+ childCfg := SubTurnConfig{Model: "gpt-4o-mini"}
+ _, err := spawnSubTurn(context.Background(), al, rootTS, childCfg)
+ if err != nil {
+ t.Fatalf("failed to spawn child: %v", err)
+ }
+
+ time.Sleep(10 * time.Millisecond) // let event goroutine flush
+
+ // Verify we captured the spawn event
+ mu.Lock()
+ if len(spawnedTurns) != 1 {
+ t.Fatalf("expected 1 spawn event, got %d", len(spawnedTurns))
+ }
+ if spawnedTurns[0].parentID != "root-turn" {
+ t.Errorf("expected parent ID 'root-turn', got %s", spawnedTurns[0].parentID)
+ }
+ mu.Unlock()
+
+ // Verify root turn has the child in its childTurnIDs
+ rootTS.mu.Lock()
+ if len(rootTS.childTurnIDs) != 1 {
+ t.Errorf("expected root to have 1 child, got %d", len(rootTS.childTurnIDs))
+ }
+ rootTS.mu.Unlock()
+}
+
+// TestDeliverSubTurnResultNoDeadlock verifies that deliverSubTurnResult doesn't
+// deadlock when multiple goroutines are accessing the parent turnState concurrently.
+func TestDeliverSubTurnResultNoDeadlock(t *testing.T) {
+ parent := &turnState{
+ ctx: context.Background(),
+ turnID: "parent-deadlock-test",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 2), // Small buffer to test blocking
+ }
+
+ // Simulate multiple child turns delivering results concurrently
+ var wg sync.WaitGroup
+ numChildren := 10
+
+ for i := 0; i < numChildren; i++ {
+ wg.Add(1)
+ go func(id int) {
+ defer wg.Done()
+ result := &tools.ToolResult{ForLLM: fmt.Sprintf("result-%d", id)}
+ deliverSubTurnResult(nil, parent, fmt.Sprintf("child-%d", id), result)
+ }(i)
+ }
+
+ // Concurrently read from the channel to prevent blocking
+ // and to actually retrieve the matched number of results
+ go func() {
+ for i := 0; i < numChildren; i++ {
+ select {
+ case <-parent.pendingResults:
+ case <-time.After(5 * time.Second):
+ t.Error("timeout waiting for result")
+ return
+ }
+ }
+ }()
+
+ // Wait for all deliveries to complete (with timeout)
+ done := make(chan struct{})
+ go func() {
+ wg.Wait()
+ close(done)
+ }()
+
+ select {
+ case <-done:
+ // Success - no deadlock
+ case <-time.After(3 * time.Second):
+ t.Fatal("deadlock detected: deliverSubTurnResult blocked")
+ }
+}
+
+// TestHardAbortOrderOfOperations verifies that HardAbort calls Finish() before
+// rolling back session history, minimizing the race window where new messages
+// could be added after rollback.
+func TestHardAbortOrderOfOperations(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ sess := &ephemeralSessionStore{
+ history: []providers.Message{
+ {Role: "user", Content: "initial message"},
+ {Role: "assistant", Content: "response 1"},
+ {Role: "user", Content: "follow-up"},
+ },
+ }
+
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+
+ rootTS := &turnState{
+ ctx: ctx,
+ cancelFunc: cancel,
+ turnID: "test-session-order",
+ depth: 0,
+ session: sess,
+ initialHistoryLength: 1, // Snapshot: 1 message
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, 5),
+ }
+
+ al.activeTurnStates.Store("test-session-order", rootTS)
+
+ // Trigger HardAbort
+ err := al.HardAbort("test-session-order")
+ if err != nil {
+ t.Fatalf("HardAbort failed: %v", err)
+ }
+
+ // Verify context was canceled (Finish() was called)
+ select {
+ case <-rootTS.ctx.Done():
+ // Good - context was canceled
+ default:
+ t.Error("expected context to be canceled after HardAbort")
+ }
+
+ // Verify history was rolled back
+ finalHistory := sess.GetHistory("")
+ if len(finalHistory) != 1 {
+ t.Errorf("expected history to rollback to 1 message, got %d", len(finalHistory))
+ }
+
+ if finalHistory[0].Content != "initial message" {
+ t.Error("history content does not match initial state after rollback")
+ }
+}
+
+// TestFinishedChannelClosedState verifies that Finish() closes the Finished() channel
+// so that child turns can safely abort waiting.
+func TestFinishedChannelClosedState(t *testing.T) {
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+
+ ts := &turnState{
+ ctx: ctx,
+ cancelFunc: cancel,
+ turnID: "test-finished-channel",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 2),
+ }
+
+ // Verify Finished channel is blocking initially
+ select {
+ case <-ts.Finished():
+ t.Fatal("finished channel should block initially")
+ default:
+ // Good
+ }
+
+ // Call Finish() with graceful finish
+ ts.Finish(false)
+
+ // Verify Finished channel is closed
+ select {
+ case _, ok := <-ts.Finished():
+ if ok {
+ t.Error("expected Finished() channel to be closed after Finish()")
+ }
+ default:
+ t.Fatal("expected <-ts.Finished() to not block")
+ }
+
+ // Verify Finish() is idempotent
+ ts.Finish(false) // Should not panic
+
+ // Verify deliverSubTurnResult correctly uses Finished() channel and treats as orphan
+ result := &tools.ToolResult{ForLLM: "late result"}
+ deliverSubTurnResult(nil, ts, "child-1", result) // Will emit orphan due to <-ts.Finished() case
+}
+
+// TestFinalPollCapturesLateResults verifies that the final poll before Finish()
+// captures results that arrive after the last iteration poll.
+func TestFinalPollCapturesLateResults(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ sessionKey := "test-session-final-poll"
+
+ // Register a turnState
+ ts := &turnState{
+ ctx: context.Background(),
+ turnID: sessionKey,
+ depth: 0,
+ session: &ephemeralSessionStore{},
+ pendingResults: make(chan *tools.ToolResult, 4),
+ }
+ al.activeTurnStates.Store(sessionKey, ts)
+ defer al.activeTurnStates.Delete(sessionKey)
+
+ // Simulate results arriving after last iteration poll
+ ts.pendingResults <- &tools.ToolResult{ForLLM: "result 1"}
+ ts.pendingResults <- &tools.ToolResult{ForLLM: "result 2"}
+
+ // Dequeue should capture both results
+ results := al.dequeuePendingSubTurnResults(sessionKey)
+
+ if len(results) != 2 {
+ t.Errorf("expected 2 results, got %d", len(results))
+ }
+
+ // Verify channel is now empty
+ results = al.dequeuePendingSubTurnResults(sessionKey)
+ if len(results) != 0 {
+ t.Errorf("expected 0 results on second poll, got %d", len(results))
+ }
+}
+
+// TestSpawnSubTurn_PanicRecovery verifies that even if runTurn panics,
+// the result is still delivered for async calls and SubTurnEndEvent is emitted.
+func TestSpawnSubTurn_PanicRecovery(t *testing.T) {
+ // Create a panic provider
+ panicProvider := &panicMockProvider{}
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Workspace: t.TempDir(),
+ ModelName: "test-model",
+ MaxTokens: 4096,
+ MaxToolIterations: 10,
+ },
+ },
+ }
+ al := NewAgentLoop(cfg, bus.NewMessageBus(), panicProvider)
+
+ parent := &turnState{
+ ctx: context.Background(),
+ turnID: "parent-panic",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 1),
+ session: &ephemeralSessionStore{},
+ }
+
+ collector, collectCleanup := newEventCollector(t, al)
+ defer collectCleanup()
+
+ // Test async call - result should still be delivered via channel
+ asyncCfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: true}
+ result, err := spawnSubTurn(context.Background(), al, parent, asyncCfg)
+
+ // Should return error from panic recovery
+ if err == nil {
+ t.Error("expected error from panic recovery")
+ }
+
+ // Result should be nil because panic occurred before runTurn could return
+ if result != nil {
+ t.Error("expected nil result after panic")
+ }
+
+ time.Sleep(10 * time.Millisecond) // let event goroutine flush
+ // SubTurnEndEvent should still be emitted
+ if !collector.hasEventOfKind(EventKindSubTurnEnd) {
+ t.Error("SubTurnEndEvent not emitted after panic")
+ }
+
+ // For async call, result should still be delivered to channel (even if nil)
+ select {
+ case res := <-parent.pendingResults:
+ // Result was delivered (nil due to panic)
+ _ = res
+ default:
+ t.Error("async result should be delivered to channel even after panic")
+ }
+}
+
+// panicMockProvider is a mock provider that always panics
+type panicMockProvider struct{}
+
+func (m *panicMockProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ opts map[string]any,
+) (*providers.LLMResponse, error) {
+ panic("intentional panic for testing")
+}
+
+func (m *panicMockProvider) GetDefaultModel() string {
+ return "panic-model"
+}
+
+// ====================== Public API Tests ======================
+
+// simpleMockProviderAPI for testing public APIs
+type simpleMockProviderAPI struct {
+ response string
+}
+
+func (m *simpleMockProviderAPI) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ toolDefs []providers.ToolDefinition,
+ model string,
+ options map[string]any,
+) (*providers.LLMResponse, error) {
+ return &providers.LLMResponse{
+ Content: m.response,
+ }, nil
+}
+
+func (m *simpleMockProviderAPI) GetDefaultModel() string {
+ return "gpt-4o-mini"
+}
+
+// TestGetActiveTurn verifies that GetActiveTurn returns correct turn information
+func TestGetActiveTurn(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ ModelName: "gpt-4o-mini",
+ Provider: "mock",
+ },
+ },
+ }
+ al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+ // Create a root turn state
+ rootCtx := context.Background()
+ rootTS := &turnState{
+ ctx: rootCtx,
+ turnID: "root-turn",
+ parentTurnID: "",
+ depth: 0,
+ childTurnIDs: []string{},
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+
+ sessionKey := "test-session"
+ al.activeTurnStates.Store(sessionKey, rootTS)
+ defer al.activeTurnStates.Delete(sessionKey)
+
+ // Test: GetActiveTurn should return turn info
+ info := al.GetActiveTurnBySession(sessionKey)
+ if info == nil {
+ t.Fatal("GetActiveTurn returned nil for active session")
+ }
+
+ if info.TurnID != "root-turn" {
+ t.Errorf("Expected TurnID 'root-turn', got %q", info.TurnID)
+ }
+
+ if info.Depth != 0 {
+ t.Errorf("Expected Depth 0, got %d", info.Depth)
+ }
+
+ if info.ParentTurnID != "" {
+ t.Errorf("Expected empty ParentTurnID, got %q", info.ParentTurnID)
+ }
+
+ if len(info.ChildTurnIDs) != 0 {
+ t.Errorf("Expected 0 child turns, got %d", len(info.ChildTurnIDs))
+ }
+
+ // Test: GetActiveTurn should return nil for non-existent session
+ nonExistentInfo := al.GetActiveTurnBySession("non-existent-session")
+ if nonExistentInfo != nil {
+ t.Error("GetActiveTurn should return nil for non-existent session")
+ }
+}
+
+// TestGetActiveTurn_WithChildren verifies that child turn IDs are correctly reported
+func TestGetActiveTurn_WithChildren(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ ModelName: "gpt-4o-mini",
+ Provider: "mock",
+ },
+ },
+ }
+ al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+ rootCtx := context.Background()
+ rootTS := &turnState{
+ ctx: rootCtx,
+ turnID: "root-turn",
+ parentTurnID: "",
+ depth: 0,
+ childTurnIDs: []string{"child-1", "child-2"},
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+
+ sessionKey := "test-session-with-children"
+ al.activeTurnStates.Store(sessionKey, rootTS)
+ defer al.activeTurnStates.Delete(sessionKey)
+
+ info := al.GetActiveTurnBySession(sessionKey)
+ if info == nil {
+ t.Fatal("GetActiveTurn returned nil")
+ }
+
+ if len(info.ChildTurnIDs) != 2 {
+ t.Fatalf("Expected 2 child turns, got %d", len(info.ChildTurnIDs))
+ }
+
+ if info.ChildTurnIDs[0] != "child-1" || info.ChildTurnIDs[1] != "child-2" {
+ t.Errorf("Child turn IDs mismatch: got %v", info.ChildTurnIDs)
+ }
+}
+
+// TestTurnStateInfo_ThreadSafety verifies that Info() is thread-safe
+func TestTurnStateInfo_ThreadSafety(t *testing.T) {
+ rootCtx := context.Background()
+ ts := &turnState{
+ ctx: rootCtx,
+ turnID: "test-turn",
+ parentTurnID: "parent",
+ depth: 1,
+ childTurnIDs: []string{},
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+
+ // Concurrently read Info() and modify childTurnIDs
+ done := make(chan bool)
+ go func() {
+ for i := 0; i < 100; i++ {
+ ts.mu.Lock()
+ ts.childTurnIDs = append(ts.childTurnIDs, "child")
+ ts.mu.Unlock()
+ }
+ done <- true
+ }()
+
+ go func() {
+ for i := 0; i < 100; i++ {
+ info := ts.snapshot()
+ if info.TurnID == "" {
+ t.Error("snapshot() returned empty TurnID")
+ }
+ }
+ done <- true
+ }()
+
+ <-done
+ <-done
+}
+
+// TestInjectFollowUp verifies that InjectFollowUp enqueues messages
+func TestInjectFollowUp(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ ModelName: "gpt-4o-mini",
+ Provider: "mock",
+ },
+ },
+ }
+
+ al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+ msg := providers.Message{
+ Role: "user",
+ Content: "Follow-up task",
+ }
+
+ err := al.InjectFollowUp(msg)
+ if err != nil {
+ t.Fatalf("InjectFollowUp failed: %v", err)
+ }
+
+ // Verify message was enqueued
+ if al.steering.len() != 1 {
+ t.Errorf("Expected 1 message in queue, got %d", al.steering.len())
+ }
+}
+
+// TestAPIAliases verifies that API aliases work correctly
+func TestAPIAliases(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ ModelName: "gpt-4o-mini",
+ Provider: "mock",
+ },
+ },
+ }
+
+ al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+ msg := providers.Message{
+ Role: "user",
+ Content: "Test message",
+ }
+
+ // Test InterruptGraceful: requires active turn, so error is expected here
+ _ = al.InterruptGraceful(msg.Content)
+
+ // Test InjectSteering (enqueues a steering message)
+ err := al.InjectSteering(msg)
+ if err != nil {
+ t.Errorf("InjectSteering failed: %v", err)
+ }
+
+ // Also enqueue via Steer to verify second message
+ err = al.Steer(msg)
+ if err != nil {
+ t.Errorf("Steer failed: %v", err)
+ }
+
+ // Verify both messages were enqueued
+ if al.steering.len() != 2 {
+ t.Errorf("Expected 2 messages in queue, got %d", al.steering.len())
+ }
+}
+
+// TestInterruptHard_Alias verifies that InterruptHard is an alias for HardAbort
+func TestInterruptHard_Alias(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ ModelName: "gpt-4o-mini",
+ Provider: "mock",
+ },
+ },
+ }
+ al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+ rootCtx := context.Background()
+ rootTS := &turnState{
+ ctx: rootCtx,
+ turnID: "test-turn",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ initialHistoryLength: 0,
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+
+ sessionKey := "test-session-interrupt"
+ al.activeTurnStates.Store(sessionKey, rootTS)
+
+ // Test InterruptHard (alias for HardAbort)
+ err := al.InterruptHard()
+ if err != nil {
+ t.Errorf("InterruptHard failed: %v", err)
+ }
+
+ // Verify turn was finished (removed from activeTurnStates)
+ info := al.GetActiveTurnBySession(sessionKey)
+ _ = info // turn may still be in map briefly; hard abort sets isFinished on the state
+}
+
+// TestFinish_ConcurrentCalls verifies that calling Finish() concurrently from multiple
+// goroutines is safe and doesn't cause panics or double-close errors.
+func TestFinish_ConcurrentCalls(t *testing.T) {
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-concurrent-finish",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+ // Launch multiple goroutines that all call Finish() concurrently
+ const numGoroutines = 10
+ var wg sync.WaitGroup
+ wg.Add(numGoroutines)
+
+ for i := 0; i < numGoroutines; i++ {
+ go func() {
+ defer wg.Done()
+ // This should not panic, even when called concurrently
+ parentTS.Finish(false)
+ }()
+ }
+
+ wg.Wait()
+
+ // Verify the Finished() channel is closed
+ select {
+ case _, ok := <-parentTS.Finished():
+ if ok {
+ t.Error("Expected Finished() channel to be closed")
+ }
+ default:
+ t.Error("Expected Finished() channel to be closed and readable without blocking")
+ }
+
+ // Verify isFinished is set
+ parentTS.mu.Lock()
+ if !parentTS.isFinished.Load() {
+ t.Error("Expected isFinished to be true")
+ }
+ parentTS.mu.Unlock()
+}
+
+// TestDeliverSubTurnResult_RaceWithFinish verifies that deliverSubTurnResult handles
+// the race condition where Finish() is called while results are being delivered.
+func TestDeliverSubTurnResult_RaceWithFinish(t *testing.T) {
+ al, _, _, _, cleanup := newTestAgentLoop(t) //nolint:dogsled
+ defer cleanup()
+
+ // Collect events via real EventBus
+ var mu sync.Mutex
+ var deliveredCount, orphanCount int
+ sub := al.SubscribeEvents(64)
+ defer al.UnsubscribeEvents(sub.ID)
+ go func() {
+ for evt := range sub.C {
+ mu.Lock()
+ switch evt.Kind {
+ case EventKindSubTurnResultDelivered:
+ deliveredCount++
+ case EventKindSubTurnOrphan:
+ orphanCount++
+ }
+ mu.Unlock()
+ }
+ }()
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-race-test",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+ // Launch goroutines that deliver results while another goroutine calls Finish()
+ const numResults = 20
+ var wg sync.WaitGroup
+ wg.Add(numResults + 1)
+
+ // Goroutine that calls Finish() after a short delay
+ go func() {
+ defer wg.Done()
+ time.Sleep(5 * time.Millisecond)
+ parentTS.Finish(false)
+ }()
+
+ // Goroutines that deliver results
+ for i := 0; i < numResults; i++ {
+ go func(id int) {
+ defer wg.Done()
+ result := &tools.ToolResult{
+ ForLLM: fmt.Sprintf("result-%d", id),
+ }
+ // This should not panic, even if Finish() is called concurrently
+ deliverSubTurnResult(al, parentTS, fmt.Sprintf("child-%d", id), result)
+ }(i)
+ }
+
+ wg.Wait()
+ time.Sleep(20 * time.Millisecond) // let event goroutine flush
+
+ // Get final counts
+ mu.Lock()
+ finalDelivered := deliveredCount
+ finalOrphan := orphanCount
+ mu.Unlock()
+
+ t.Logf("Delivered: %d, Orphan: %d, Total: %d", finalDelivered, finalOrphan, finalDelivered+finalOrphan)
+
+ // With the new drainPendingResults behavior, the total events may be >= numResults
+ // because Finish() drains remaining results from the channel and emits them as orphans.
+ // So we expect:
+ // - Some results were delivered successfully (before Finish())
+ // - Some results became orphans (after Finish() or channel full)
+ // - Some results were in the channel when Finish() was called and got drained as orphans
+ // The total should be at least numResults (could be more due to drain)
+ if finalDelivered+finalOrphan < numResults {
+ t.Errorf("Expected at least %d total events, got %d delivered + %d orphan = %d",
+ numResults, finalDelivered, finalOrphan, finalDelivered+finalOrphan)
+ }
+
+ // Should have at least some orphan results (those that arrived after Finish() or were drained)
+ if finalOrphan == 0 {
+ t.Error("Expected at least some orphan results after Finish()")
+ }
+}
+
+// TestConcurrencySemaphore_Timeout verifies that spawning sub-turns times out
+// when all concurrency slots are occupied for too long.
+// Note: This test uses a shorter timeout by temporarily modifying the constant.
+func TestConcurrencySemaphore_Timeout(t *testing.T) {
+ // This test would take 30 seconds with the default timeout.
+ // Instead, we'll test the mechanism by verifying the timeout context is created correctly.
+ // A full integration test with actual timeout would be too slow for unit tests.
+
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Provider: "mock",
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &simpleMockProviderAPI{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-timeout-test",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+ defer parentTS.Finish(false)
+
+ // Fill all concurrency slots
+ for i := 0; i < testMaxConcurrentSubTurns; i++ {
+ parentTS.concurrencySem <- struct{}{}
+ }
+
+ // Create a context with a very short timeout for testing
+ testCtx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
+ defer cancel()
+
+ // Now try to spawn a sub-turn with the short timeout context
+ subTurnCfg := SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Async: false,
+ }
+
+ start := time.Now()
+ _, err := spawnSubTurn(testCtx, al, parentTS, subTurnCfg)
+ elapsed := time.Since(start)
+
+ // Should get a timeout error (either from our timeout context or the internal one)
+ if err == nil {
+ t.Error("Expected timeout error, got nil")
+ }
+
+ // The error should be related to context cancellation or timeout
+ if !errors.Is(err, context.DeadlineExceeded) && !errors.Is(err, ErrConcurrencyTimeout) {
+ t.Logf("Got error: %v (type: %T)", err, err)
+ // This is acceptable - the error might be wrapped
+ }
+
+ // Should timeout quickly (within a reasonable margin)
+ if elapsed > 2*time.Second {
+ t.Errorf("Timeout took too long: %v", elapsed)
+ }
+
+ t.Logf("Timeout occurred after %v with error: %v", elapsed, err)
+
+ // Clean up - drain the semaphore
+ for i := 0; i < testMaxConcurrentSubTurns; i++ {
+ <-parentTS.concurrencySem
+ }
+}
+
+// TestEphemeralSession_AutoTruncate verifies that ephemeral sessions automatically
+// truncate their history to prevent memory accumulation.
+func TestEphemeralSession_AutoTruncate(t *testing.T) {
+ store := newEphemeralSession(nil).(*ephemeralSessionStore)
+
+ // Add more messages than the limit
+ for i := 0; i < maxEphemeralHistorySize+20; i++ {
+ store.AddMessage("test", "user", fmt.Sprintf("message-%d", i))
+ }
+
+ // Verify history is truncated to the limit
+ history := store.GetHistory("test")
+ if len(history) != maxEphemeralHistorySize {
+ t.Errorf("Expected history length %d, got %d", maxEphemeralHistorySize, len(history))
+ }
+
+ // Verify we kept the most recent messages
+ lastMsg := history[len(history)-1]
+ expectedContent := fmt.Sprintf("message-%d", maxEphemeralHistorySize+20-1)
+ if lastMsg.Content != expectedContent {
+ t.Errorf("Expected last message to be %q, got %q", expectedContent, lastMsg.Content)
+ }
+
+ // Verify the oldest messages were discarded
+ firstMsg := history[0]
+ expectedFirstContent := fmt.Sprintf("message-%d", 20) // First 20 were discarded
+ if firstMsg.Content != expectedFirstContent {
+ t.Errorf("Expected first message to be %q, got %q", expectedFirstContent, firstMsg.Content)
+ }
+}
+
+// TestContextWrapping_SingleLayer verifies that we only create one context layer
+// in spawnSubTurn, not multiple redundant layers.
+func TestContextWrapping_SingleLayer(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Provider: "mock",
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &simpleMockProviderAPI{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-context-test",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+ defer parentTS.Finish(false)
+
+ // Spawn a sub-turn
+ subTurnCfg := SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Async: false,
+ }
+
+ result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg)
+ if err != nil {
+ t.Fatalf("spawnSubTurn failed: %v", err)
+ }
+
+ if result == nil {
+ t.Error("Expected non-nil result")
+ }
+
+ // Verify the child turn was created with a cancel function
+ // (This is implicit - if the test passes without hanging, the context management is correct)
+ t.Log("Context wrapping test passed - no redundant layers detected")
+}
+
+// TestSyncSubTurn_NoChannelDelivery verifies that synchronous sub-turns
+// do NOT deliver results to the pendingResults channel (only return directly).
+func TestSyncSubTurn_NoChannelDelivery(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Provider: "mock",
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &simpleMockProviderAPI{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-sync-test",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+ defer parentTS.Finish(false)
+
+ // Spawn a SYNCHRONOUS sub-turn (Async=false)
+ subTurnCfg := SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Async: false, // Synchronous - should NOT deliver to channel
+ }
+
+ result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg)
+ if err != nil {
+ t.Fatalf("spawnSubTurn failed: %v", err)
+ }
+
+ if result == nil {
+ t.Error("Expected non-nil result from synchronous sub-turn")
+ }
+
+ // Verify the pendingResults channel is EMPTY
+ // (synchronous sub-turns should not deliver to channel)
+ select {
+ case r := <-parentTS.pendingResults:
+ t.Errorf("Expected empty channel for sync sub-turn, but got result: %v", r)
+ default:
+ // Expected: channel is empty
+ t.Log("Verified: synchronous sub-turn did not deliver to channel")
+ }
+
+ // Verify channel length is 0
+ if len(parentTS.pendingResults) != 0 {
+ t.Errorf("Expected channel length 0, got %d", len(parentTS.pendingResults))
+ }
+}
+
+// TestAsyncSubTurn_ChannelDelivery verifies that asynchronous sub-turns
+// DO deliver results to the pendingResults channel.
+func TestAsyncSubTurn_ChannelDelivery(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Provider: "mock",
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &simpleMockProviderAPI{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-async-test",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+ defer parentTS.Finish(false)
+
+ // Spawn an ASYNCHRONOUS sub-turn (Async=true)
+ subTurnCfg := SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Async: true, // Asynchronous - SHOULD deliver to channel
+ }
+
+ result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg)
+ if err != nil {
+ t.Fatalf("spawnSubTurn failed: %v", err)
+ }
+
+ if result == nil {
+ t.Error("Expected non-nil result from asynchronous sub-turn")
+ }
+
+ // Verify the pendingResults channel has the result
+ select {
+ case r := <-parentTS.pendingResults:
+ if r == nil {
+ t.Error("Expected non-nil result from channel")
+ }
+ t.Log("Verified: asynchronous sub-turn delivered to channel")
+ case <-time.After(100 * time.Millisecond):
+ t.Error("Expected result in channel for async sub-turn, but channel was empty")
+ }
+}
+
+// TestGrandchildAbort_CascadingCancellation verifies that when a grandparent turn
+// is hard aborted, the cancellation cascades down to grandchild turns.
+func TestGrandchildAbort_CascadingCancellation(t *testing.T) {
+ al, _, _, provider, cleanup := newTestAgentLoop(t)
+ _ = provider
+ defer cleanup()
+
+ // Three independent contexts — none derived from another.
+ // Cascade must happen exclusively through childTurnIDs traversal in Finish(true).
+ gpCtx, gpCancel := context.WithCancel(context.Background())
+ parentCtx, parentCancel := context.WithCancel(context.Background())
+ childCtx, childCancel := context.WithCancel(context.Background())
+
+ childTS := &turnState{
+ ctx: childCtx,
+ cancelFunc: childCancel,
+ turnID: "grandchild",
+ al: al,
+ }
+ parentTS := &turnState{
+ ctx: parentCtx,
+ cancelFunc: parentCancel,
+ turnID: "parent",
+ childTurnIDs: []string{"grandchild"},
+ al: al,
+ }
+ grandparentTS := &turnState{
+ ctx: gpCtx,
+ cancelFunc: gpCancel,
+ turnID: "grandparent",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ childTurnIDs: []string{"parent"},
+ al: al,
+ }
+
+ al.activeTurnStates.Store("grandparent", grandparentTS)
+ al.activeTurnStates.Store("parent", parentTS)
+ al.activeTurnStates.Store("grandchild", childTS)
+ defer al.activeTurnStates.Delete("grandparent")
+ defer al.activeTurnStates.Delete("parent")
+ defer al.activeTurnStates.Delete("grandchild")
+
+ // All contexts must be active before the abort
+ for _, ctx := range []context.Context{gpCtx, parentCtx, childCtx} {
+ select {
+ case <-ctx.Done():
+ t.Fatal("context should not be canceled yet")
+ default:
+ }
+ }
+
+ // Hard abort the grandparent — should cascade to parent and grandchild
+ grandparentTS.Finish(true)
+
+ time.Sleep(10 * time.Millisecond)
+
+ select {
+ case <-gpCtx.Done():
+ t.Log("Grandparent context canceled (expected)")
+ default:
+ t.Error("Grandparent context should be canceled")
+ }
+ select {
+ case <-parentCtx.Done():
+ t.Log("Parent context canceled via cascade (expected)")
+ default:
+ t.Error("Parent context should be canceled via childTurnIDs cascade")
+ }
+ select {
+ case <-childCtx.Done():
+ t.Log("Grandchild context canceled via cascade (expected)")
+ default:
+ t.Error("Grandchild context should be canceled via childTurnIDs cascade")
+ }
+}
+
+// TestSpawnDuringAbort_RaceCondition verifies behavior when trying to spawn
+// a sub-turn while the parent is being aborted.
+func TestSpawnDuringAbort_RaceCondition(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Provider: "mock",
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &simpleMockProviderAPI{}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-abort-race",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+ var wg sync.WaitGroup
+ wg.Add(2)
+
+ var spawnErr error
+
+ // Goroutine 1: Try to spawn a sub-turn
+ go func() {
+ defer wg.Done()
+ subTurnCfg := SubTurnConfig{
+ Model: "gpt-4o-mini",
+ Async: false,
+ }
+ _, err := spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg)
+ spawnErr = err
+ }()
+
+ // Goroutine 2: Abort the parent almost immediately
+ go func() {
+ defer wg.Done()
+ time.Sleep(1 * time.Millisecond)
+ parentTS.Finish(false)
+ }()
+
+ wg.Wait()
+
+ // The spawn should either succeed (if it started before abort)
+ // or fail with context canceled error (if abort happened first)
+ if spawnErr != nil {
+ if errors.Is(spawnErr, context.Canceled) {
+ t.Logf("Spawn failed with expected context cancellation: %v", spawnErr)
+ } else {
+ t.Logf("Spawn failed with error: %v", spawnErr)
+ }
+ } else {
+ t.Log("Spawn succeeded before abort")
+ }
+
+ // The important thing is that it doesn't panic or deadlock
+ t.Log("Race condition handled gracefully - no panic or deadlock")
+}
+
+// ====================== Slow SubTurn Cancellation Test ======================
+
+// slowMockProvider simulates a slow LLM call that takes a long time to complete.
+// This is used to test the scenario where a parent turn finishes before the child SubTurn.
+type slowMockProvider struct {
+ delay time.Duration
+}
+
+func (m *slowMockProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ toolDefs []providers.ToolDefinition,
+ model string,
+ options map[string]any,
+) (*providers.LLMResponse, error) {
+ select {
+ case <-time.After(m.delay):
+ // Completed normally after delay
+ return &providers.LLMResponse{
+ Content: "slow response completed",
+ }, nil
+ case <-ctx.Done():
+ // Context was canceled while waiting
+ return nil, ctx.Err()
+ }
+}
+
+func (m *slowMockProvider) GetDefaultModel() string {
+ return "slow-model"
+}
+
+// TestAsyncSubTurn_ParentFinishesEarly simulates the scenario where:
+// 1. Parent spawns an async SubTurn that takes a long time
+// 2. Parent finishes quickly
+// 3. SubTurn should be canceled with context canceled error
+func TestAsyncSubTurn_ParentFinishesEarly(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Provider: "mock",
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &slowMockProvider{delay: 5 * time.Second} // SubTurn takes 5 seconds
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ // Capture events via real EventBus
+ var mu sync.Mutex
+ var events []Event
+ sub := al.SubscribeEvents(32)
+ defer al.UnsubscribeEvents(sub.ID)
+ go func() {
+ for evt := range sub.C {
+ mu.Lock()
+ events = append(events, evt)
+ mu.Unlock()
+ }
+ }()
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-fast",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+ var subTurnErr error
+ var subTurnResult *tools.ToolResult
+ var wg sync.WaitGroup
+
+ // Spawn async SubTurn in a goroutine (it will be slow)
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ subTurnCfg := SubTurnConfig{
+ Model: "slow-model",
+ Async: true, // Asynchronous SubTurn
+ }
+ subTurnResult, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg)
+ }()
+
+ // Parent finishes quickly (after 100ms), while SubTurn is still running
+ time.Sleep(100 * time.Millisecond)
+ t.Log("Parent finishing early...")
+ parentTS.Finish(false)
+
+ // Wait for SubTurn to complete (or be canceled)
+ wg.Wait()
+
+ // Check the result
+ t.Logf("SubTurn error: %v", subTurnErr)
+ t.Logf("SubTurn result: %v", subTurnResult)
+
+ if subTurnErr != nil {
+ if errors.Is(subTurnErr, context.Canceled) {
+ t.Log("✓ SubTurn was canceled as expected (context canceled)")
+ } else {
+ t.Logf("SubTurn failed with other error: %v", subTurnErr)
+ }
+ } else {
+ t.Log("SubTurn completed before parent finished (unlikely but possible)")
+ }
+
+ // Log captured events
+ mu.Lock()
+ t.Logf("Captured %d events:", len(events))
+ for i, e := range events {
+ t.Logf(" Event %d: %s", i+1, e.Kind)
+ }
+ mu.Unlock()
+}
+
+// TestAsyncSubTurn_ParentWaitsForChild simulates the scenario where:
+// 1. Parent spawns an async SubTurn that takes some time
+// 2. Parent WAITS for SubTurn to complete before finishing
+// 3. Both should complete successfully
+func TestAsyncSubTurn_ParentWaitsForChild(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Provider: "mock",
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &slowMockProvider{delay: 200 * time.Millisecond} // SubTurn takes 200ms
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-wait",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+ var subTurnErr error
+ var subTurnResult *tools.ToolResult
+ var wg sync.WaitGroup
+
+ // Spawn async SubTurn in a goroutine
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ subTurnCfg := SubTurnConfig{
+ Model: "slow-model",
+ Async: true,
+ }
+ subTurnResult, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg)
+ }()
+
+ // Parent WAITS for SubTurn to complete
+ t.Log("Parent waiting for SubTurn...")
+ wg.Wait()
+ t.Log("SubTurn completed, parent now finishing")
+
+ // Now parent can finish safely
+ parentTS.Finish(false)
+
+ // Check the result
+ if subTurnErr != nil {
+ if errors.Is(subTurnErr, context.Canceled) {
+ t.Errorf("SubTurn should NOT have been canceled: %v", subTurnErr)
+ } else {
+ t.Logf("SubTurn failed with error: %v", subTurnErr)
+ }
+ } else {
+ t.Log("✓ SubTurn completed successfully")
+ if subTurnResult != nil {
+ t.Logf("SubTurn result: %s", subTurnResult.ForLLM)
+ }
+ }
+
+ // Check channel delivery
+ select {
+ case r := <-parentTS.pendingResults:
+ if r != nil {
+ t.Logf("✓ Result delivered to channel: %s", r.ForLLM)
+ }
+ case <-time.After(100 * time.Millisecond):
+ t.Log("No result in channel (expected since we waited)")
+ }
+}
+
+// ====================== Graceful vs Hard Finish Tests ======================
+
+// TestFinish_GracefulVsHard verifies the behavior difference between:
+// - Finish(false): graceful finish, signals parentEnded but doesn't cancel children
+// - Finish(true): hard abort, immediately cancels all children
+func TestFinish_GracefulVsHard(t *testing.T) {
+ // Test 1: Graceful finish should set parentEnded but not cancel context
+ t.Run("Graceful_SetsParentEnded", func(t *testing.T) {
+ ctx, cancel := context.WithCancel(context.Background())
+ defer cancel()
+
+ ts := &turnState{
+ ctx: ctx,
+ turnID: "graceful-test",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 16),
+ }
+ ts.ctx, ts.cancelFunc = context.WithCancel(ctx)
+
+ // Finish gracefully
+ ts.Finish(false)
+
+ // Verify parentEnded is set
+ if !ts.parentEnded.Load() {
+ t.Error("parentEnded should be true after graceful finish")
+ }
+
+ // Verify context is NOT canceled (for graceful finish, children continue)
+ // Note: In graceful mode, we don't call cancelFunc()
+ // But since we're using WithCancel on the same ctx, it might be canceled
+ // Let's check that the context is still valid for a moment
+ time.Sleep(10 * time.Millisecond)
+ // Context might be canceled by the deferred cancel() in test, which is fine
+ })
+
+ // Test 2: Hard abort should cancel context immediately
+ t.Run("Hard_CancelsContext", func(t *testing.T) {
+ ctx := context.Background()
+
+ ts := &turnState{
+ ctx: ctx,
+ turnID: "hard-test",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 16),
+ }
+ ts.ctx, ts.cancelFunc = context.WithCancel(ctx)
+
+ // Finish with hard abort
+ ts.Finish(true)
+
+ // Verify context is canceled
+ select {
+ case <-ts.ctx.Done():
+ t.Log("✓ Context canceled after hard abort")
+ default:
+ t.Error("Context should be canceled after hard abort")
+ }
+ })
+
+ // Test 3: IsParentEnded returns correct value
+ t.Run("IsParentEnded", func(t *testing.T) {
+ ctx := context.Background()
+
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-isended-test",
+ depth: 0,
+ pendingResults: make(chan *tools.ToolResult, 16),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+ childTS := &turnState{
+ ctx: ctx,
+ turnID: "child-isended-test",
+ depth: 1,
+ parentTurnState: parentTS,
+ pendingResults: make(chan *tools.ToolResult, 16),
+ }
+
+ // Before parent finishes
+ if childTS.IsParentEnded() {
+ t.Error("IsParentEnded should be false before parent finishes")
+ }
+
+ // Finish parent gracefully
+ parentTS.Finish(false)
+
+ // After parent finishes
+ if !childTS.IsParentEnded() {
+ t.Error("IsParentEnded should be true after parent finishes gracefully")
+ }
+ })
+}
+
+// TestSubTurn_IndependentContext verifies that SubTurns use independent contexts
+// that don't get canceled when the parent finishes gracefully.
+func TestSubTurn_IndependentContext(t *testing.T) {
+ cfg := &config.Config{
+ Agents: config.AgentsConfig{
+ Defaults: config.AgentDefaults{
+ Provider: "mock",
+ },
+ },
+ }
+ msgBus := bus.NewMessageBus()
+ provider := &slowMockProvider{delay: 500 * time.Millisecond}
+ al := NewAgentLoop(cfg, msgBus, provider)
+
+ ctx := context.Background()
+ parentTS := &turnState{
+ ctx: ctx,
+ turnID: "parent-independent",
+ depth: 0,
+ session: newEphemeralSession(nil),
+ pendingResults: make(chan *tools.ToolResult, 16),
+ concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+ }
+ parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+ var subTurnErr error
+ var wg sync.WaitGroup
+
+ // Spawn SubTurn with Critical=true (should continue after parent finishes)
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ subTurnCfg := SubTurnConfig{
+ Model: "slow-model",
+ Async: true,
+ Critical: true, // Critical SubTurn should continue
+ }
+ _, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg)
+ }()
+
+ // Let SubTurn start
+ time.Sleep(50 * time.Millisecond)
+
+ // Parent finishes gracefully (should NOT cancel SubTurn)
+ parentTS.Finish(false)
+ t.Log("Parent finished gracefully, SubTurn should continue")
+
+ // Wait for SubTurn to complete
+ wg.Wait()
+
+ // SubTurn should complete without context canceled error
+ // (because it uses independent context now)
+ if subTurnErr != nil {
+ t.Logf("SubTurn error: %v", subTurnErr)
+ // The error might be context.DeadlineExceeded if timeout is too short
+ // but should NOT be context.Canceled from parent
+ if errors.Is(subTurnErr, context.Canceled) {
+ t.Error("SubTurn should not be canceled by parent's graceful finish")
+ }
+ } else {
+ t.Log("✓ SubTurn completed successfully (independent context)")
+ }
+}
diff --git a/pkg/agent/turn.go b/pkg/agent/turn.go
new file mode 100644
index 000000000..e4970c519
--- /dev/null
+++ b/pkg/agent/turn.go
@@ -0,0 +1,481 @@
+package agent
+
+import (
+ "context"
+ "reflect"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/session"
+ "github.com/sipeed/picoclaw/pkg/tools"
+)
+
+type TurnPhase string
+
+const (
+ TurnPhaseSetup TurnPhase = "setup"
+ TurnPhaseRunning TurnPhase = "running"
+ TurnPhaseTools TurnPhase = "tools"
+ TurnPhaseFinalizing TurnPhase = "finalizing"
+ TurnPhaseCompleted TurnPhase = "completed"
+ TurnPhaseAborted TurnPhase = "aborted"
+)
+
+type ActiveTurnInfo struct {
+ TurnID string
+ AgentID string
+ SessionKey string
+ Channel string
+ ChatID string
+ UserMessage string
+ Phase TurnPhase
+ Iteration int
+ StartedAt time.Time
+ Depth int
+ ParentTurnID string
+ ChildTurnIDs []string
+}
+
+type turnResult struct {
+ finalContent string
+ status TurnEndStatus
+ followUps []bus.InboundMessage
+}
+
+type turnState struct {
+ mu sync.RWMutex
+
+ agent *AgentInstance
+ opts processOptions
+ scope turnEventScope
+
+ turnID string
+ agentID string
+ sessionKey string
+
+ channel string
+ chatID string
+ userMessage string
+ media []string
+
+ phase TurnPhase
+ iteration int
+ startedAt time.Time
+ finalContent string
+
+ followUps []bus.InboundMessage
+
+ gracefulInterrupt bool
+ gracefulInterruptHint string
+ gracefulTerminalUsed bool
+ hardAbort bool
+ providerCancel context.CancelFunc
+ turnCancel context.CancelFunc
+
+ restorePointHistory []providers.Message
+ restorePointSummary string
+ persistedMessages []providers.Message
+
+ // SubTurn support (from HEAD)
+ depth int // SubTurn depth (0 for root turn)
+ parentTurnID string // Parent turn ID (empty for root turn)
+ childTurnIDs []string // Child turn IDs
+ pendingResults chan *tools.ToolResult // Channel for SubTurn results
+ concurrencySem chan struct{} // Semaphore for limiting concurrent SubTurns
+ isFinished atomic.Bool // Whether this turn has finished
+ session session.SessionStore // Session store reference
+ initialHistoryLength int // Snapshot of history length at turn start
+
+ // Additional SubTurn fields
+ ctx context.Context // Context for this turn
+ cancelFunc context.CancelFunc // Cancel function for this turn's context
+ critical bool // Whether this SubTurn should continue after parent ends
+ parentTurnState *turnState // Reference to parent turnState
+ parentEnded atomic.Bool // Whether parent has ended
+ closeOnce sync.Once // Ensures pendingResults channel is closed once
+ finishedChan chan struct{} // Closed when turn finishes
+
+ // Token budget tracking
+ tokenBudget *atomic.Int64 // Shared token budget counter
+ lastFinishReason string // Last LLM finish_reason
+ lastUsage *providers.UsageInfo // Last LLM usage info
+
+ // Back-reference to the owning AgentLoop (set for SubTurns only, used for hard abort cascade)
+ al *AgentLoop
+}
+
+func newTurnState(agent *AgentInstance, opts processOptions, scope turnEventScope) *turnState {
+ ts := &turnState{
+ agent: agent,
+ opts: opts,
+ scope: scope,
+ turnID: scope.turnID,
+ agentID: agent.ID,
+ sessionKey: opts.SessionKey,
+ channel: opts.Channel,
+ chatID: opts.ChatID,
+ userMessage: opts.UserMessage,
+ media: append([]string(nil), opts.Media...),
+ phase: TurnPhaseSetup,
+ startedAt: time.Now(),
+ }
+
+ // Bind session store and capture initial history length for rollback logic
+ if agent != nil && agent.Sessions != nil {
+ ts.session = agent.Sessions
+ ts.initialHistoryLength = len(agent.Sessions.GetHistory(opts.SessionKey))
+ }
+
+ return ts
+}
+
+func (al *AgentLoop) registerActiveTurn(ts *turnState) {
+ al.activeTurnStates.Store(ts.sessionKey, ts)
+}
+
+func (al *AgentLoop) clearActiveTurn(ts *turnState) {
+ al.activeTurnStates.Delete(ts.sessionKey)
+}
+
+func (al *AgentLoop) getActiveTurnState(sessionKey string) *turnState {
+ if val, ok := al.activeTurnStates.Load(sessionKey); ok {
+ return val.(*turnState)
+ }
+ return nil
+}
+
+// getAnyActiveTurnState returns any active turn state (for backward compatibility)
+func (al *AgentLoop) getAnyActiveTurnState() *turnState {
+ var firstTS *turnState
+ al.activeTurnStates.Range(func(key, value any) bool {
+ firstTS = value.(*turnState)
+ return false // stop after first
+ })
+ return firstTS
+}
+
+func (al *AgentLoop) GetActiveTurn() *ActiveTurnInfo {
+ // For backward compatibility, return the first active turn found
+ // In the new architecture, there can be multiple concurrent turns
+ var firstTS *turnState
+ al.activeTurnStates.Range(func(key, value any) bool {
+ firstTS = value.(*turnState)
+ return false // stop after first
+ })
+ if firstTS == nil {
+ return nil
+ }
+ info := firstTS.snapshot()
+ return &info
+}
+
+func (al *AgentLoop) GetActiveTurnBySession(sessionKey string) *ActiveTurnInfo {
+ ts := al.getActiveTurnState(sessionKey)
+ if ts == nil {
+ return nil
+ }
+ info := ts.snapshot()
+ return &info
+}
+
+func (ts *turnState) snapshot() ActiveTurnInfo {
+ ts.mu.RLock()
+ defer ts.mu.RUnlock()
+
+ return ActiveTurnInfo{
+ TurnID: ts.turnID,
+ AgentID: ts.agentID,
+ SessionKey: ts.sessionKey,
+ Channel: ts.channel,
+ ChatID: ts.chatID,
+ UserMessage: ts.userMessage,
+ Phase: ts.phase,
+ Iteration: ts.iteration,
+ StartedAt: ts.startedAt,
+ Depth: ts.depth,
+ ParentTurnID: ts.parentTurnID,
+ ChildTurnIDs: append([]string(nil), ts.childTurnIDs...),
+ }
+}
+
+func (ts *turnState) setPhase(phase TurnPhase) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.phase = phase
+}
+
+func (ts *turnState) setIteration(iteration int) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.iteration = iteration
+}
+
+func (ts *turnState) currentIteration() int {
+ ts.mu.RLock()
+ defer ts.mu.RUnlock()
+ return ts.iteration
+}
+
+func (ts *turnState) setFinalContent(content string) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.finalContent = content
+}
+
+func (ts *turnState) finalContentLen() int {
+ ts.mu.RLock()
+ defer ts.mu.RUnlock()
+ return len(ts.finalContent)
+}
+
+func (ts *turnState) setTurnCancel(cancel context.CancelFunc) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.turnCancel = cancel
+}
+
+func (ts *turnState) setProviderCancel(cancel context.CancelFunc) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.providerCancel = cancel
+}
+
+func (ts *turnState) clearProviderCancel(_ context.CancelFunc) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.providerCancel = nil
+}
+
+func (ts *turnState) requestGracefulInterrupt(hint string) bool {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ if ts.hardAbort {
+ return false
+ }
+ ts.gracefulInterrupt = true
+ ts.gracefulInterruptHint = hint
+ return true
+}
+
+func (ts *turnState) gracefulInterruptRequested() (bool, string) {
+ ts.mu.RLock()
+ defer ts.mu.RUnlock()
+ return ts.gracefulInterrupt && !ts.gracefulTerminalUsed, ts.gracefulInterruptHint
+}
+
+func (ts *turnState) markGracefulTerminalUsed() {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.gracefulTerminalUsed = true
+}
+
+func (ts *turnState) requestHardAbort() bool {
+ ts.mu.Lock()
+ if ts.hardAbort {
+ ts.mu.Unlock()
+ return false
+ }
+ ts.hardAbort = true
+ turnCancel := ts.turnCancel
+ providerCancel := ts.providerCancel
+ ts.mu.Unlock()
+
+ if providerCancel != nil {
+ providerCancel()
+ }
+ if turnCancel != nil {
+ turnCancel()
+ }
+ return true
+}
+
+func (ts *turnState) hardAbortRequested() bool {
+ ts.mu.RLock()
+ defer ts.mu.RUnlock()
+ return ts.hardAbort
+}
+
+func (ts *turnState) eventMeta(source, tracePath string) EventMeta {
+ snap := ts.snapshot()
+ return EventMeta{
+ AgentID: snap.AgentID,
+ TurnID: snap.TurnID,
+ SessionKey: snap.SessionKey,
+ Iteration: snap.Iteration,
+ Source: source,
+ TracePath: tracePath,
+ }
+}
+
+func (ts *turnState) captureRestorePoint(history []providers.Message, summary string) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.restorePointHistory = append([]providers.Message(nil), history...)
+ ts.restorePointSummary = summary
+}
+
+func (ts *turnState) recordPersistedMessage(msg providers.Message) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.persistedMessages = append(ts.persistedMessages, msg)
+}
+
+func (ts *turnState) refreshRestorePointFromSession(agent *AgentInstance) {
+ history := agent.Sessions.GetHistory(ts.sessionKey)
+ summary := agent.Sessions.GetSummary(ts.sessionKey)
+
+ ts.mu.RLock()
+ persisted := append([]providers.Message(nil), ts.persistedMessages...)
+ ts.mu.RUnlock()
+
+ if matched := matchingTurnMessageTail(history, persisted); matched > 0 {
+ history = append([]providers.Message(nil), history[:len(history)-matched]...)
+ }
+
+ ts.captureRestorePoint(history, summary)
+}
+
+func (ts *turnState) restoreSession(agent *AgentInstance) error {
+ ts.mu.RLock()
+ history := append([]providers.Message(nil), ts.restorePointHistory...)
+ summary := ts.restorePointSummary
+ ts.mu.RUnlock()
+
+ agent.Sessions.SetHistory(ts.sessionKey, history)
+ agent.Sessions.SetSummary(ts.sessionKey, summary)
+ return agent.Sessions.Save(ts.sessionKey)
+}
+
+func matchingTurnMessageTail(history, persisted []providers.Message) int {
+ maxMatch := min(len(history), len(persisted))
+ for size := maxMatch; size > 0; size-- {
+ if reflect.DeepEqual(history[len(history)-size:], persisted[len(persisted)-size:]) {
+ return size
+ }
+ }
+ return 0
+}
+
+func (ts *turnState) interruptHintMessage() providers.Message {
+ _, hint := ts.gracefulInterruptRequested()
+ content := "Interrupt requested. Stop scheduling tools and provide a short final summary."
+ if hint != "" {
+ content += "\n\nInterrupt hint: " + hint
+ }
+ return providers.Message{
+ Role: "user",
+ Content: content,
+ }
+}
+
+// SubTurn-related methods
+
+// Finish marks the turn as finished and closes the pendingResults channel
+func (ts *turnState) Finish(isHardAbort bool) {
+ ts.isFinished.Store(true)
+
+ // Close pendingResults channel exactly once
+ ts.closeOnce.Do(func() {
+ if ts.pendingResults != nil {
+ close(ts.pendingResults)
+ }
+ ts.mu.Lock()
+ if ts.finishedChan == nil {
+ ts.finishedChan = make(chan struct{})
+ }
+ close(ts.finishedChan)
+ ts.mu.Unlock()
+ })
+
+ // If this is a graceful finish (not hard abort), signal to children
+ if !isHardAbort && ts.parentTurnState == nil {
+ // This is a root turn finishing gracefully
+ ts.parentEnded.Store(true)
+ }
+
+ // Cancel the turn context
+ if ts.cancelFunc != nil {
+ ts.cancelFunc()
+ }
+
+ // Hard abort cascades to all child turns
+ if isHardAbort && ts.al != nil {
+ ts.mu.RLock()
+ children := append([]string(nil), ts.childTurnIDs...)
+ ts.mu.RUnlock()
+ for _, childID := range children {
+ if val, ok := ts.al.activeTurnStates.Load(childID); ok {
+ val.(*turnState).Finish(true)
+ }
+ }
+ }
+}
+
+// Finished returns whether the turn has finished
+func (ts *turnState) Finished() chan struct{} {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ if ts.finishedChan == nil {
+ ts.finishedChan = make(chan struct{})
+ }
+ return ts.finishedChan
+}
+
+// IsParentEnded checks if the parent turn has ended
+func (ts *turnState) IsParentEnded() bool {
+ if ts.parentTurnState == nil {
+ return false
+ }
+ return ts.parentTurnState.parentEnded.Load()
+}
+
+// GetLastFinishReason returns the last LLM finish_reason
+func (ts *turnState) GetLastFinishReason() string {
+ ts.mu.RLock()
+ defer ts.mu.RUnlock()
+ return ts.lastFinishReason
+}
+
+// SetLastFinishReason sets the last LLM finish_reason
+func (ts *turnState) SetLastFinishReason(reason string) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.lastFinishReason = reason
+}
+
+// GetLastUsage returns the last LLM usage info
+func (ts *turnState) GetLastUsage() *providers.UsageInfo {
+ ts.mu.RLock()
+ defer ts.mu.RUnlock()
+ return ts.lastUsage
+}
+
+// SetLastUsage sets the last LLM usage info
+func (ts *turnState) SetLastUsage(usage *providers.UsageInfo) {
+ ts.mu.Lock()
+ defer ts.mu.Unlock()
+ ts.lastUsage = usage
+}
+
+// Context helper functions for SubTurn
+
+type turnStateKeyType struct{}
+
+var turnStateKey = turnStateKeyType{}
+
+func withTurnState(ctx context.Context, ts *turnState) context.Context {
+ return context.WithValue(ctx, turnStateKey, ts)
+}
+
+func turnStateFromContext(ctx context.Context) *turnState {
+ ts, _ := ctx.Value(turnStateKey).(*turnState)
+ return ts
+}
+
+// TurnStateFromContext retrieves turnState from context (exported for tools)
+func TurnStateFromContext(ctx context.Context) *turnState {
+ return turnStateFromContext(ctx)
+}
diff --git a/pkg/auth/store.go b/pkg/auth/store.go
index f7813ca57..8a878d553 100644
--- a/pkg/auth/store.go
+++ b/pkg/auth/store.go
@@ -6,6 +6,7 @@ import (
"path/filepath"
"time"
+ "github.com/sipeed/picoclaw/pkg"
"github.com/sipeed/picoclaw/pkg/config"
"github.com/sipeed/picoclaw/pkg/fileutil"
)
@@ -44,7 +45,7 @@ func authFilePath() string {
return filepath.Join(home, "auth.json")
}
home, _ := os.UserHomeDir()
- return filepath.Join(home, ".picoclaw", "auth.json")
+ return filepath.Join(home, pkg.DefaultPicoClawHome, "auth.json")
}
func LoadStore() (*AuthStore, error) {
diff --git a/pkg/bus/bus.go b/pkg/bus/bus.go
index 3d08bda4f..37fcb74c5 100644
--- a/pkg/bus/bus.go
+++ b/pkg/bus/bus.go
@@ -14,15 +14,32 @@ var ErrBusClosed = errors.New("message bus closed")
const defaultBusBufferSize = 64
+// StreamDelegate is implemented by the channel Manager to provide streaming
+// capabilities to the agent loop without tight coupling.
+type StreamDelegate interface {
+ // GetStreamer returns a Streamer for the given channel+chatID if the channel
+ // supports streaming. Returns nil, false if streaming is unavailable.
+ GetStreamer(ctx context.Context, channel, chatID string) (Streamer, bool)
+}
+
+// Streamer pushes incremental content to a streaming-capable channel.
+// Defined here so the agent loop can use it without importing pkg/channels.
+type Streamer interface {
+ Update(ctx context.Context, content string) error
+ Finalize(ctx context.Context, content string) error
+ Cancel(ctx context.Context)
+}
+
type MessageBus struct {
inbound chan InboundMessage
outbound chan OutboundMessage
outboundMedia chan OutboundMediaMessage
- closeOnce sync.Once
- done chan struct{}
- closed atomic.Bool
- wg sync.WaitGroup
+ closeOnce sync.Once
+ done chan struct{}
+ closed atomic.Bool
+ wg sync.WaitGroup
+ streamDelegate atomic.Value // stores StreamDelegate
}
func NewMessageBus() *MessageBus {
@@ -86,6 +103,19 @@ func (mb *MessageBus) OutboundMediaChan() <-chan OutboundMediaMessage {
return mb.outboundMedia
}
+// SetStreamDelegate registers a StreamDelegate (typically the channel Manager).
+func (mb *MessageBus) SetStreamDelegate(d StreamDelegate) {
+ mb.streamDelegate.Store(d)
+}
+
+// GetStreamer returns a Streamer for the given channel+chatID via the delegate.
+func (mb *MessageBus) GetStreamer(ctx context.Context, channel, chatID string) (Streamer, bool) {
+ if d, ok := mb.streamDelegate.Load().(StreamDelegate); ok && d != nil {
+ return d.GetStreamer(ctx, channel, chatID)
+ }
+ return nil, false
+}
+
func (mb *MessageBus) Close() {
mb.closeOnce.Do(func() {
// notify all blocked publishers to exit
diff --git a/pkg/channels/base.go b/pkg/channels/base.go
index edb5b6f08..882e72d08 100644
--- a/pkg/channels/base.go
+++ b/pkg/channels/base.go
@@ -275,14 +275,18 @@ func (c *BaseChannel) HandleMessage(
// Auto-trigger typing indicator, message reaction, and placeholder before publishing.
// Each capability is independent — all three may fire for the same message.
+ // Note: even when streaming is available, we still show typing + placeholder on inbound.
+ // If streaming actually activates, preSend will skip the placeholder edit (streamActive map)
+ // and the typing stop will still be called. This avoids the problem of compile-time interface
+ // checks incorrectly skipping indicators when streaming may not work at runtime.
if c.owner != nil && c.placeholderRecorder != nil {
- // Typing — independent pipeline
+ // Typing
if tc, ok := c.owner.(TypingCapable); ok {
if stop, err := tc.StartTyping(ctx, chatID); err == nil {
c.placeholderRecorder.RecordTypingStop(c.name, chatID, stop)
}
}
- // Reaction — independent pipeline
+ // Reaction
if rc, ok := c.owner.(ReactionCapable); ok && messageID != "" {
if undo, err := rc.ReactToMessage(ctx, chatID, messageID); err == nil {
c.placeholderRecorder.RecordReactionUndo(c.name, chatID, undo)
diff --git a/pkg/channels/dingtalk/dingtalk.go b/pkg/channels/dingtalk/dingtalk.go
index c03122892..7ac2c073f 100644
--- a/pkg/channels/dingtalk/dingtalk.go
+++ b/pkg/channels/dingtalk/dingtalk.go
@@ -36,7 +36,7 @@ type DingTalkChannel struct {
// NewDingTalkChannel creates a new DingTalk channel instance
func NewDingTalkChannel(cfg config.DingTalkConfig, messageBus *bus.MessageBus) (*DingTalkChannel, error) {
- if cfg.ClientID == "" || cfg.ClientSecret == "" {
+ if cfg.ClientID == "" || cfg.ClientSecret() == "" {
return nil, fmt.Errorf("dingtalk client_id and client_secret are required")
}
@@ -53,7 +53,7 @@ func NewDingTalkChannel(cfg config.DingTalkConfig, messageBus *bus.MessageBus) (
BaseChannel: base,
config: cfg,
clientID: cfg.ClientID,
- clientSecret: cfg.ClientSecret,
+ clientSecret: cfg.ClientSecret(),
}, nil
}
diff --git a/pkg/channels/discord/discord.go b/pkg/channels/discord/discord.go
index 83a04907c..3b5b4f8bb 100644
--- a/pkg/channels/discord/discord.go
+++ b/pkg/channels/discord/discord.go
@@ -53,7 +53,7 @@ func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordC
discordgo.LogDebug: logger.DEBUG,
}).Log
- session, err := discordgo.New("Bot " + cfg.Token)
+ session, err := discordgo.New("Bot " + cfg.Token())
if err != nil {
return nil, fmt.Errorf("failed to create discord session: %w", err)
}
@@ -396,8 +396,9 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
storeMedia := func(localPath, filename string) string {
if store := c.GetMediaStore(); store != nil {
ref, err := store.Store(localPath, media.MediaMeta{
- Filename: filename,
- Source: "discord",
+ Filename: filename,
+ Source: "discord",
+ CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
}, scope)
if err == nil {
return ref
diff --git a/pkg/channels/feishu/common.go b/pkg/channels/feishu/common.go
index fbe085b73..4952394b7 100644
--- a/pkg/channels/feishu/common.go
+++ b/pkg/channels/feishu/common.go
@@ -84,3 +84,64 @@ func stripMentionPlaceholders(content string, mentions []*larkim.MentionEvent) s
content = mentionPlaceholderRegex.ReplaceAllString(content, "")
return strings.TrimSpace(content)
}
+
+// extractCardImageKeys recursively extracts all image keys from a Feishu interactive card.
+// Image keys are used to download images from Feishu API.
+// Returns two slices: Feishu-hosted keys and external URLs.
+func extractCardImageKeys(rawContent string) (feishuKeys []string, externalURLs []string) {
+ if rawContent == "" {
+ return nil, nil
+ }
+
+ var card map[string]any
+ if err := json.Unmarshal([]byte(rawContent), &card); err != nil {
+ return nil, nil
+ }
+
+ extractImageKeysRecursive(card, &feishuKeys, &externalURLs)
+ return feishuKeys, externalURLs
+}
+
+// isExternalURL returns true if the string is an external HTTP/HTTPS URL.
+func isExternalURL(s string) bool {
+ return strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://")
+}
+
+// extractImageKeysRecursive traverses card structure to find all image keys.
+// Collects both Feishu-hosted keys and external URLs separately.
+func extractImageKeysRecursive(v any, feishuKeys, externalURLs *[]string) {
+ switch val := v.(type) {
+ case map[string]any:
+ // Check if this is an img element
+ if tag, ok := val["tag"].(string); ok {
+ switch tag {
+ case "img":
+ // Try img_key first (always Feishu-hosted)
+ if imgKey, ok := val["img_key"].(string); ok && imgKey != "" {
+ *feishuKeys = append(*feishuKeys, imgKey)
+ }
+ // Check src - could be Feishu key or external URL
+ if src, ok := val["src"].(string); ok && src != "" {
+ if isExternalURL(src) {
+ *externalURLs = append(*externalURLs, src)
+ } else {
+ *feishuKeys = append(*feishuKeys, src)
+ }
+ }
+ case "icon":
+ // Icon elements use icon_key
+ if iconKey, ok := val["icon_key"].(string); ok && iconKey != "" {
+ *feishuKeys = append(*feishuKeys, iconKey)
+ }
+ }
+ }
+ // Recurse into all nested structures
+ for _, child := range val {
+ extractImageKeysRecursive(child, feishuKeys, externalURLs)
+ }
+ case []any:
+ for _, item := range val {
+ extractImageKeysRecursive(item, feishuKeys, externalURLs)
+ }
+ }
+}
diff --git a/pkg/channels/feishu/common_test.go b/pkg/channels/feishu/common_test.go
index fefc9f7c1..ff4af0148 100644
--- a/pkg/channels/feishu/common_test.go
+++ b/pkg/channels/feishu/common_test.go
@@ -290,3 +290,119 @@ func TestStripMentionPlaceholders(t *testing.T) {
})
}
}
+
+func TestExtractCardImageKeys(t *testing.T) {
+ tests := []struct {
+ name string
+ content string
+ wantFeishuKeys []string
+ wantExternalURLs []string
+ }{
+ {
+ name: "empty content",
+ content: "",
+ wantFeishuKeys: nil,
+ wantExternalURLs: nil,
+ },
+ {
+ name: "invalid JSON",
+ content: "not json",
+ wantFeishuKeys: nil,
+ wantExternalURLs: nil,
+ },
+ {
+ name: "card with no images",
+ content: `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"text"}]}}`,
+ wantFeishuKeys: nil,
+ wantExternalURLs: nil,
+ },
+ {
+ name: "single image with img_key",
+ content: `{"elements":[{"tag":"img","img_key":"img_abc123"}]}`,
+ wantFeishuKeys: []string{"img_abc123"},
+ wantExternalURLs: nil,
+ },
+ {
+ name: "single image with src as Feishu key",
+ content: `{"elements":[{"tag":"img","src":"img_xyz789"}]}`,
+ wantFeishuKeys: []string{"img_xyz789"},
+ wantExternalURLs: nil,
+ },
+ {
+ name: "multiple images",
+ content: `{"elements":[{"tag":"img","img_key":"img_1"},{"tag":"div","text":{"content":"text"}},{"tag":"img","img_key":"img_2"}]}`,
+ wantFeishuKeys: []string{"img_1", "img_2"},
+ wantExternalURLs: nil,
+ },
+ {
+ name: "nested image in columns",
+ content: `{"elements":[{"tag":"div","columns":[{"tag":"img","img_key":"img_col1"},{"tag":"img","img_key":"img_col2"}]}]}`,
+ wantFeishuKeys: []string{"img_col1", "img_col2"},
+ wantExternalURLs: nil,
+ },
+ {
+ name: "image in action",
+ content: `{"elements":[{"tag":"action","actions":[{"tag":"img","img_key":"img_action"}]}]}`,
+ wantFeishuKeys: []string{"img_action"},
+ wantExternalURLs: nil,
+ },
+ {
+ name: "icon element",
+ content: `{"elements":[{"tag":"icon","icon_key":"icon_123"}]}`,
+ wantFeishuKeys: []string{"icon_123"},
+ wantExternalURLs: nil,
+ },
+ {
+ name: "complex card with text and images",
+ content: `{"header":{"title":{"content":"Title"}},"elements":[{"tag":"div","text":{"content":"Description"}},{"tag":"img","img_key":"img_main"}]}`,
+ wantFeishuKeys: []string{"img_main"},
+ wantExternalURLs: nil,
+ },
+ {
+ name: "external URL in src",
+ content: `{"elements":[{"tag":"img","src":"https://example.com/image.png"}]}`,
+ wantFeishuKeys: nil,
+ wantExternalURLs: []string{"https://example.com/image.png"},
+ },
+ {
+ name: "mixed Feishu keys and external URLs",
+ content: `{"elements":[{"tag":"img","img_key":"img_feishu"},{"tag":"img","src":"https://cdn.example.com/external.jpg"},{"tag":"img","src":"img_another"}]}`,
+ wantFeishuKeys: []string{"img_feishu", "img_another"},
+ wantExternalURLs: []string{"https://cdn.example.com/external.jpg"},
+ },
+ {
+ name: "multiple external URLs",
+ content: `{"elements":[{"tag":"img","src":"https://a.com/1.png"},{"tag":"img","src":"http://b.com/2.jpg"}]}`,
+ wantFeishuKeys: nil,
+ wantExternalURLs: []string{"https://a.com/1.png", "http://b.com/2.jpg"},
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ gotFeishuKeys, gotExternalURLs := extractCardImageKeys(tt.content)
+
+ // Compare Feishu keys
+ if len(gotFeishuKeys) != len(tt.wantFeishuKeys) {
+ t.Errorf("extractCardImageKeys() feishuKeys = %v, want %v", gotFeishuKeys, tt.wantFeishuKeys)
+ return
+ }
+ for i, v := range gotFeishuKeys {
+ if v != tt.wantFeishuKeys[i] {
+ t.Errorf("extractCardImageKeys() feishuKeys[%d] = %q, want %q", i, v, tt.wantFeishuKeys[i])
+ }
+ }
+
+ // Compare external URLs
+ if len(gotExternalURLs) != len(tt.wantExternalURLs) {
+ t.Errorf("extractCardImageKeys() externalURLs = %v, want %v", gotExternalURLs, tt.wantExternalURLs)
+ return
+ }
+ for i, v := range gotExternalURLs {
+ if v != tt.wantExternalURLs[i] {
+ t.Errorf("extractCardImageKeys() externalURLs[%d] = %q, want %q", i, v, tt.wantExternalURLs[i])
+ }
+ }
+ })
+ }
+}
diff --git a/pkg/channels/feishu/feishu_64.go b/pkg/channels/feishu/feishu_64.go
index 3aea67b12..0ab70649f 100644
--- a/pkg/channels/feishu/feishu_64.go
+++ b/pkg/channels/feishu/feishu_64.go
@@ -11,6 +11,7 @@ import (
"net/http"
"os"
"path/filepath"
+ "strings"
"sync"
"sync/atomic"
@@ -62,14 +63,14 @@ func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChan
BaseChannel: base,
config: cfg,
tokenCache: tc,
- client: lark.NewClient(cfg.AppID, cfg.AppSecret, opts...),
+ client: lark.NewClient(cfg.AppID, cfg.AppSecret(), opts...),
}
ch.SetOwner(ch)
return ch, nil
}
func (c *FeishuChannel) Start(ctx context.Context) error {
- if c.config.AppID == "" || c.config.AppSecret == "" {
+ if c.config.AppID == "" || c.config.AppSecret() == "" {
return fmt.Errorf("feishu app_id or app_secret is empty")
}
@@ -80,7 +81,7 @@ func (c *FeishuChannel) Start(ctx context.Context) error {
})
}
- dispatcher := larkdispatcher.NewEventDispatcher(c.config.VerificationToken, c.config.EncryptKey).
+ dispatcher := larkdispatcher.NewEventDispatcher(c.config.VerificationToken(), c.config.EncryptKey()).
OnP2MessageReceiveV1(c.handleMessageReceive)
runCtx, cancel := context.WithCancel(ctx)
@@ -93,7 +94,7 @@ func (c *FeishuChannel) Start(ctx context.Context) error {
}
c.wsClient = larkws.NewClient(
c.config.AppID,
- c.config.AppSecret,
+ c.config.AppSecret(),
larkws.WithEventHandler(dispatcher),
larkws.WithDomain(domain),
)
@@ -129,6 +130,7 @@ func (c *FeishuChannel) Stop(ctx context.Context) error {
}
// Send sends a message using Interactive Card format for markdown rendering.
+// Falls back to plain text message if card sending fails (e.g., table limit exceeded).
func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
if !c.IsRunning() {
return channels.ErrNotRunning
@@ -141,9 +143,38 @@ func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error
// Build interactive card with markdown content
cardContent, err := buildMarkdownCard(msg.Content)
if err != nil {
- return fmt.Errorf("feishu send: card build failed: %w", err)
+ // If card build fails, fall back to plain text
+ return c.sendText(ctx, msg.ChatID, msg.Content)
}
- return c.sendCard(ctx, msg.ChatID, cardContent)
+
+ // First attempt: try sending as interactive card
+ err = c.sendCard(ctx, msg.ChatID, cardContent)
+ if err == nil {
+ return nil
+ }
+
+ // Check if error is due to card table limit (error code 11310)
+ // See: https://open.feishu.cn/document/server-docs/im-api/message-content-description/create_json
+ errMsg := err.Error()
+ isCardLimitError := strings.Contains(errMsg, "11310")
+
+ if isCardLimitError {
+ logger.WarnCF("feishu", "Card send failed (table limit), falling back to text message", map[string]any{
+ "chat_id": msg.ChatID,
+ "error": errMsg,
+ })
+
+ // Second attempt: fall back to plain text message
+ textErr := c.sendText(ctx, msg.ChatID, msg.Content)
+ if textErr == nil {
+ return nil
+ }
+ // If text also fails, return the text error
+ return textErr
+ }
+
+ // For other errors, return the original card error
+ return err
}
// EditMessage implements channels.MessageEditor.
@@ -393,6 +424,15 @@ func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim.
mediaRefs = c.downloadInboundMedia(ctx, chatID, messageID, messageType, rawContent, store)
}
+ // For interactive cards, pass external image URLs via media refs.
+ // Keep content as valid raw JSON for downstream parsing.
+ if messageType == larkim.MsgTypeInteractive {
+ _, externalURLs := extractCardImageKeys(rawContent)
+ if len(externalURLs) > 0 {
+ mediaRefs = append(mediaRefs, externalURLs...)
+ }
+ }
+
// Append media tags to content (like Telegram does)
content = appendMediaTags(content, messageType, mediaRefs)
@@ -528,6 +568,10 @@ func extractContent(messageType, rawContent string) string {
// Pass raw JSON to LLM — structured rich text is more informative than flattened plain text
return rawContent
+ case larkim.MsgTypeInteractive:
+ // Pass raw JSON to LLM — structured card is more informative than flattened text
+ return rawContent
+
case larkim.MsgTypeImage:
// Image messages don't have text content
return ""
@@ -565,6 +609,18 @@ func (c *FeishuChannel) downloadInboundMedia(
refs = append(refs, ref)
}
+ case larkim.MsgTypeInteractive:
+ // Extract and download images embedded in interactive cards
+ feishuKeys, _ := extractCardImageKeys(rawContent)
+ // Download Feishu-hosted images via API
+ for _, imageKey := range feishuKeys {
+ ref := c.downloadResource(ctx, messageID, imageKey, "image", ".jpg", store, scope)
+ if ref != "" {
+ refs = append(refs, ref)
+ }
+ }
+ // External URLs are passed directly to LLM, not downloaded
+
case larkim.MsgTypeFile, larkim.MsgTypeAudio, larkim.MsgTypeMedia:
fileKey := extractFileKey(rawContent)
if fileKey == "" {
@@ -669,8 +725,9 @@ func (c *FeishuChannel) downloadResource(
out.Close()
ref, err := store.Store(localPath, media.MediaMeta{
- Filename: filename,
- Source: "feishu",
+ Filename: filename,
+ Source: "feishu",
+ CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
}, scope)
if err != nil {
logger.ErrorCF("feishu", "Failed to store downloaded resource", map[string]any{
@@ -685,11 +742,18 @@ func (c *FeishuChannel) downloadResource(
}
// appendMediaTags appends media type tags to content (like Telegram's "[image: photo]").
+// For interactive cards, media tags are not appended because content is raw JSON
+// and appending would produce invalid JSON format.
func appendMediaTags(content, messageType string, mediaRefs []string) string {
if len(mediaRefs) == 0 {
return content
}
+ // Don't append tags to JSON content (interactive cards) - would produce invalid JSON
+ if messageType == larkim.MsgTypeInteractive {
+ return content
+ }
+
var tag string
switch messageType {
case larkim.MsgTypeImage:
@@ -738,6 +802,35 @@ func (c *FeishuChannel) sendCard(ctx context.Context, chatID, cardContent string
return nil
}
+// sendText sends a plain text message to a chat (fallback when card fails).
+func (c *FeishuChannel) sendText(ctx context.Context, chatID, text string) error {
+ content, _ := json.Marshal(map[string]string{"text": text})
+
+ req := larkim.NewCreateMessageReqBuilder().
+ ReceiveIdType(larkim.ReceiveIdTypeChatId).
+ Body(larkim.NewCreateMessageReqBodyBuilder().
+ ReceiveId(chatID).
+ MsgType(larkim.MsgTypeText).
+ Content(string(content)).
+ Build()).
+ Build()
+
+ resp, err := c.client.Im.V1.Message.Create(ctx, req)
+ if err != nil {
+ return fmt.Errorf("feishu send text: %w", channels.ErrTemporary)
+ }
+
+ if !resp.Success() {
+ return fmt.Errorf("feishu text api error (code=%d msg=%s): %w", resp.Code, resp.Msg, channels.ErrTemporary)
+ }
+
+ logger.DebugCF("feishu", "Feishu text message sent (fallback)", map[string]any{
+ "chat_id": chatID,
+ })
+
+ return nil
+}
+
// sendImage uploads an image and sends it as a message.
func (c *FeishuChannel) sendImage(ctx context.Context, chatID string, file *os.File) error {
// Upload image to get image_key
diff --git a/pkg/channels/feishu/feishu_64_test.go b/pkg/channels/feishu/feishu_64_test.go
index dc3eab2e7..9010abf69 100644
--- a/pkg/channels/feishu/feishu_64_test.go
+++ b/pkg/channels/feishu/feishu_64_test.go
@@ -75,6 +75,24 @@ func TestExtractContent(t *testing.T) {
rawContent: "",
want: "",
},
+ {
+ name: "interactive card returns raw JSON",
+ messageType: "interactive",
+ rawContent: `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"Hello from card"}]}}`,
+ want: `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"Hello from card"}]}}`,
+ },
+ {
+ name: "interactive card with complex structure returns raw JSON",
+ messageType: "interactive",
+ rawContent: `{"header":{"title":{"tag":"plain_text","content":"Title"}},"elements":[{"tag":"div","text":{"tag":"lark_md","content":"Card content"}}]}`,
+ want: `{"header":{"title":{"tag":"plain_text","content":"Title"}},"elements":[{"tag":"div","text":{"tag":"lark_md","content":"Card content"}}]}`,
+ },
+ {
+ name: "interactive card invalid JSON returns as-is",
+ messageType: "interactive",
+ rawContent: `not valid json`,
+ want: `not valid json`,
+ },
}
for _, tt := range tests {
@@ -151,6 +169,13 @@ func TestAppendMediaTags(t *testing.T) {
mediaRefs: []string{"ref1"},
want: "something [attachment]",
},
+ {
+ name: "interactive card with images returns content unchanged",
+ content: `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`,
+ messageType: "interactive",
+ mediaRefs: []string{"ref1"},
+ want: `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`,
+ },
}
for _, tt := range tests {
diff --git a/pkg/channels/interfaces.go b/pkg/channels/interfaces.go
index b3a493761..0cfd435b0 100644
--- a/pkg/channels/interfaces.go
+++ b/pkg/channels/interfaces.go
@@ -3,6 +3,7 @@ package channels
import (
"context"
+ "github.com/sipeed/picoclaw/pkg/bus"
"github.com/sipeed/picoclaw/pkg/commands"
)
@@ -19,6 +20,11 @@ type MessageEditor interface {
EditMessage(ctx context.Context, chatID string, messageID string, content string) error
}
+// MessageDeleter — channels that can delete a message by ID.
+type MessageDeleter interface {
+ DeleteMessage(ctx context.Context, chatID string, messageID string) error
+}
+
// ReactionCapable — channels that can add a reaction (e.g. 👀) to an inbound message.
// ReactToMessage adds a reaction and returns an undo function to remove it.
// The undo function MUST be idempotent and safe to call multiple times.
@@ -35,6 +41,18 @@ type PlaceholderCapable interface {
SendPlaceholder(ctx context.Context, chatID string) (messageID string, err error)
}
+// StreamingCapable — channels that can show partial LLM output in real-time.
+// The channel SHOULD gracefully degrade if the platform rejects streaming
+// (e.g. Telegram bot without forum mode). In that case, Update becomes a no-op
+// and Finalize still delivers the final message.
+type StreamingCapable interface {
+ BeginStream(ctx context.Context, chatID string) (Streamer, error)
+}
+
+// Streamer is defined in pkg/bus to avoid circular imports.
+// This alias keeps channel implementations using channels.Streamer unchanged.
+type Streamer = bus.Streamer
+
// PlaceholderRecorder is injected into channels by Manager.
// Channels call these methods on inbound to register typing/placeholder state.
// Manager uses the registered state on outbound to stop typing and edit placeholders.
diff --git a/pkg/channels/irc/handler.go b/pkg/channels/irc/handler.go
index aca4ddd11..3fe9548f4 100644
--- a/pkg/channels/irc/handler.go
+++ b/pkg/channels/irc/handler.go
@@ -17,8 +17,8 @@ import (
// onConnect is called after a successful connection (and on reconnect).
func (c *IRCChannel) onConnect(conn *ircevent.Connection) {
// NickServ auth (only if SASL is not configured)
- if c.config.NickServPassword != "" && c.config.SASLUser == "" {
- conn.Privmsg("NickServ", "IDENTIFY "+c.config.NickServPassword)
+ if c.config.NickServPassword() != "" && c.config.SASLUser == "" {
+ conn.Privmsg("NickServ", "IDENTIFY "+c.config.NickServPassword())
}
// Join configured channels
diff --git a/pkg/channels/irc/irc.go b/pkg/channels/irc/irc.go
index 28c59b540..289ce2c9b 100644
--- a/pkg/channels/irc/irc.go
+++ b/pkg/channels/irc/irc.go
@@ -68,7 +68,7 @@ func (c *IRCChannel) Start(ctx context.Context) error {
Nick: c.config.Nick,
User: user,
RealName: realName,
- Password: c.config.Password,
+ Password: c.config.Password(),
UseTLS: c.config.TLS,
RequestCaps: caps,
QuitMessage: "Goodbye",
@@ -83,9 +83,9 @@ func (c *IRCChannel) Start(ctx context.Context) error {
}
// SASL auth (takes priority over NickServ)
- if c.config.SASLUser != "" && c.config.SASLPassword != "" {
+ if c.config.SASLUser != "" && c.config.SASLPassword() != "" {
conn.SASLLogin = c.config.SASLUser
- conn.SASLPassword = c.config.SASLPassword
+ conn.SASLPassword = c.config.SASLPassword()
}
// Register event handlers
diff --git a/pkg/channels/line/line.go b/pkg/channels/line/line.go
index 56ba02183..4eaadae70 100644
--- a/pkg/channels/line/line.go
+++ b/pkg/channels/line/line.go
@@ -62,7 +62,7 @@ type LINEChannel struct {
// NewLINEChannel creates a new LINE channel instance.
func NewLINEChannel(cfg config.LINEConfig, messageBus *bus.MessageBus) (*LINEChannel, error) {
- if cfg.ChannelSecret == "" || cfg.ChannelAccessToken == "" {
+ if cfg.ChannelSecret() == "" || cfg.ChannelAccessToken() == "" {
return nil, fmt.Errorf("line channel_secret and channel_access_token are required")
}
@@ -110,7 +110,7 @@ func (c *LINEChannel) fetchBotInfo() error {
if err != nil {
return err
}
- req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken)
+ req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken())
resp, err := c.infoClient.Do(req)
if err != nil {
@@ -216,7 +216,7 @@ func (c *LINEChannel) verifySignature(body []byte, signature string) bool {
return false
}
- mac := hmac.New(sha256.New, []byte(c.config.ChannelSecret))
+ mac := hmac.New(sha256.New, []byte(c.config.ChannelSecret()))
mac.Write(body)
expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
@@ -301,8 +301,9 @@ func (c *LINEChannel) processEvent(event lineEvent) {
storeMedia := func(localPath, filename string) string {
if store := c.GetMediaStore(); store != nil {
ref, err := store.Store(localPath, media.MediaMeta{
- Filename: filename,
- Source: "line",
+ Filename: filename,
+ Source: "line",
+ CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
}, scope)
if err == nil {
return ref
@@ -654,7 +655,7 @@ func (c *LINEChannel) callAPI(ctx context.Context, endpoint string, payload any)
}
req.Header.Set("Content-Type", "application/json")
- req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken)
+ req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken())
resp, err := c.apiClient.Do(req)
if err != nil {
@@ -679,7 +680,7 @@ func (c *LINEChannel) downloadContent(messageID, filename string) string {
return utils.DownloadFile(url, filename, utils.DownloadOptions{
LoggerPrefix: "line",
ExtraHeaders: map[string]string{
- "Authorization": "Bearer " + c.config.ChannelAccessToken,
+ "Authorization": "Bearer " + c.config.ChannelAccessToken(),
},
})
}
diff --git a/pkg/channels/manager.go b/pkg/channels/manager.go
index 2e1e12ded..f04d989a3 100644
--- a/pkg/channels/manager.go
+++ b/pkg/channels/manager.go
@@ -89,6 +89,7 @@ type Manager struct {
placeholders sync.Map // "channel:chatID" → placeholderID (string)
typingStops sync.Map // "channel:chatID" → func()
reactionUndos sync.Map // "channel:chatID" → reactionEntry
+ streamActive sync.Map // "channel:chatID" → true (set when streamer.Finalize sent the message)
channelHashes map[string]string // channel name → config hash
}
@@ -136,6 +137,19 @@ func (m *Manager) RecordTypingStop(channel, chatID string, stop func()) {
}
}
+// InvokeTypingStop invokes the registered typing stop function for the given channel and chatID.
+// It is safe to call even when no typing indicator is active (no-op).
+// Used by the agent loop to stop typing when processing completes (success, error, or panic),
+// regardless of whether an outbound message is published.
+func (m *Manager) InvokeTypingStop(channel, chatID string) {
+ key := channel + ":" + chatID
+ if v, loaded := m.typingStops.LoadAndDelete(key); loaded {
+ if entry, ok := v.(typingEntry); ok {
+ entry.stop()
+ }
+ }
+}
+
// RecordReactionUndo registers a reaction undo function for later invocation.
// Implements PlaceholderRecorder.
func (m *Manager) RecordReactionUndo(channel, chatID string, undo func()) {
@@ -144,7 +158,7 @@ func (m *Manager) RecordReactionUndo(channel, chatID string, undo func()) {
}
// preSend handles typing stop, reaction undo, and placeholder editing before sending a message.
-// Returns true if the message was edited into a placeholder (skip Send).
+// Returns true if the message was already delivered (skip Send).
func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMessage, ch Channel) bool {
key := name + ":" + msg.ChatID
@@ -162,7 +176,22 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess
}
}
- // 3. Try editing placeholder
+ // 3. If a stream already finalized this message, delete the placeholder and skip send
+ if _, loaded := m.streamActive.LoadAndDelete(key); loaded {
+ if v, loaded := m.placeholders.LoadAndDelete(key); loaded {
+ if entry, ok := v.(placeholderEntry); ok && entry.id != "" {
+ // Prefer deleting the placeholder (cleaner UX than editing to same content)
+ if deleter, ok := ch.(MessageDeleter); ok {
+ deleter.DeleteMessage(ctx, msg.ChatID, entry.id) // best effort
+ } else if editor, ok := ch.(MessageEditor); ok {
+ editor.EditMessage(ctx, msg.ChatID, entry.id, msg.Content) // fallback
+ }
+ }
+ }
+ return true
+ }
+
+ // 4. Try editing placeholder
if v, loaded := m.placeholders.LoadAndDelete(key); loaded {
if entry, ok := v.(placeholderEntry); ok && entry.id != "" {
if editor, ok := ch.(MessageEditor); ok {
@@ -187,6 +216,9 @@ func NewManager(cfg *config.Config, messageBus *bus.MessageBus, store media.Medi
channelHashes: make(map[string]string),
}
+ // Register as streaming delegate so the agent loop can obtain streamers
+ messageBus.SetStreamDelegate(m)
+
if err := m.initChannels(&cfg.Channels); err != nil {
return nil, err
}
@@ -197,6 +229,53 @@ func NewManager(cfg *config.Config, messageBus *bus.MessageBus, store media.Medi
return m, nil
}
+// GetStreamer implements bus.StreamDelegate.
+// It checks if the named channel supports streaming and returns a Streamer.
+func (m *Manager) GetStreamer(ctx context.Context, channelName, chatID string) (bus.Streamer, bool) {
+ m.mu.RLock()
+ ch, exists := m.channels[channelName]
+ m.mu.RUnlock()
+
+ if !exists {
+ return nil, false
+ }
+
+ sc, ok := ch.(StreamingCapable)
+ if !ok {
+ return nil, false
+ }
+
+ streamer, err := sc.BeginStream(ctx, chatID)
+ if err != nil {
+ logger.DebugCF("channels", "Streaming unavailable, falling back to placeholder", map[string]any{
+ "channel": channelName,
+ "error": err.Error(),
+ })
+ return nil, false
+ }
+
+ // Mark streamActive on Finalize so preSend knows to clean up the placeholder
+ key := channelName + ":" + chatID
+ return &finalizeHookStreamer{
+ Streamer: streamer,
+ onFinalize: func() { m.streamActive.Store(key, true) },
+ }, true
+}
+
+// finalizeHookStreamer wraps a Streamer to run a hook on Finalize.
+type finalizeHookStreamer struct {
+ Streamer
+ onFinalize func()
+}
+
+func (s *finalizeHookStreamer) Finalize(ctx context.Context, content string) error {
+ if err := s.Streamer.Finalize(ctx, content); err != nil {
+ return err
+ }
+ s.onFinalize()
+ return nil
+}
+
// initChannel is a helper that looks up a factory by name and creates the channel.
func (m *Manager) initChannel(name, displayName string) {
f, ok := getFactory(name)
@@ -240,7 +319,7 @@ func (m *Manager) initChannel(name, displayName string) {
func (m *Manager) initChannels(channels *config.ChannelsConfig) error {
logger.InfoC("channels", "Initializing channel manager")
- if channels.Telegram.Enabled && channels.Telegram.Token != "" {
+ if channels.Telegram.Enabled && channels.Telegram.Token() != "" {
m.initChannel("telegram", "Telegram")
}
@@ -257,7 +336,7 @@ func (m *Manager) initChannels(channels *config.ChannelsConfig) error {
m.initChannel("feishu", "Feishu")
}
- if channels.Discord.Enabled && channels.Discord.Token != "" {
+ if channels.Discord.Enabled && channels.Discord.Token() != "" {
m.initChannel("discord", "Discord")
}
@@ -273,18 +352,18 @@ func (m *Manager) initChannels(channels *config.ChannelsConfig) error {
m.initChannel("dingtalk", "DingTalk")
}
- if channels.Slack.Enabled && channels.Slack.BotToken != "" {
+ if channels.Slack.Enabled && channels.Slack.BotToken() != "" {
m.initChannel("slack", "Slack")
}
if channels.Matrix.Enabled &&
m.config.Channels.Matrix.Homeserver != "" &&
m.config.Channels.Matrix.UserID != "" &&
- m.config.Channels.Matrix.AccessToken != "" {
+ m.config.Channels.Matrix.AccessToken() != "" {
m.initChannel("matrix", "Matrix")
}
- if channels.LINE.Enabled && channels.LINE.ChannelAccessToken != "" {
+ if channels.LINE.Enabled && channels.LINE.ChannelAccessToken() != "" {
m.initChannel("line", "LINE")
}
@@ -292,13 +371,12 @@ func (m *Manager) initChannels(channels *config.ChannelsConfig) error {
m.initChannel("onebot", "OneBot")
}
- if channels.WeCom.Enabled && channels.WeCom.Token != "" {
+ if channels.WeCom.Enabled && channels.WeCom.Token() != "" {
m.initChannel("wecom", "WeCom")
}
- if m.config.Channels.WeComAIBot.Enabled &&
- ((m.config.Channels.WeComAIBot.BotID != "" && m.config.Channels.WeComAIBot.Secret != "") ||
- m.config.Channels.WeComAIBot.Token != "") {
+ if channels.WeComAIBot.Enabled && (channels.WeComAIBot.Token() != "" ||
+ (channels.WeComAIBot.Secret() != "" && channels.WeComAIBot.BotID != "")) {
m.initChannel("wecom_aibot", "WeCom AI Bot")
}
@@ -306,10 +384,18 @@ func (m *Manager) initChannels(channels *config.ChannelsConfig) error {
m.initChannel("wecom_app", "WeCom App")
}
- if channels.Pico.Enabled && channels.Pico.Token != "" {
+ if channels.Weixin.Enabled && channels.Weixin.Token() != "" {
+ m.initChannel("weixin", "Weixin")
+ }
+
+ if channels.Pico.Enabled && channels.Pico.Token() != "" {
m.initChannel("pico", "Pico")
}
+ if channels.PicoClient.Enabled && channels.PicoClient.URL != "" {
+ m.initChannel("pico_client", "Pico Client")
+ }
+
if channels.IRC.Enabled && channels.IRC.Server != "" {
m.initChannel("irc", "IRC")
}
diff --git a/pkg/channels/manager_channel.go b/pkg/channels/manager_channel.go
index 57cb05412..86572e336 100644
--- a/pkg/channels/manager_channel.go
+++ b/pkg/channels/manager_channel.go
@@ -21,6 +21,7 @@ func toChannelHashes(cfg *config.Config) map[string]string {
if !value["enabled"].(bool) {
continue
}
+ hiddenValues(key, value, ch)
valueBytes, _ := json.Marshal(value)
hash := md5.Sum(valueBytes)
result[key] = hex.EncodeToString(hash[:])
@@ -29,6 +30,49 @@ func toChannelHashes(cfg *config.Config) map[string]string {
return result
}
+func hiddenValues(key string, value map[string]any, ch config.ChannelsConfig) {
+ switch key {
+ case "pico":
+ value["token"] = ch.Pico.Token()
+ case "telegram":
+ value["token"] = ch.Telegram.Token()
+ case "discord":
+ value["token"] = ch.Discord.Token()
+ case "slack":
+ value["bot_token"] = ch.Slack.BotToken()
+ value["app_token"] = ch.Slack.AppToken()
+ case "matrix":
+ value["token"] = ch.Matrix.AccessToken()
+ case "onebot":
+ value["token"] = ch.OneBot.AccessToken()
+ case "line":
+ value["token"] = ch.LINE.ChannelAccessToken()
+ value["secret"] = ch.LINE.ChannelSecret()
+ case "wecom":
+ value["token"] = ch.WeCom.Token()
+ value["key"] = ch.WeCom.EncodingAESKey()
+ case "wecom_app":
+ value["token"] = ch.WeComApp.Token()
+ value["secret"] = ch.WeComApp.CorpSecret()
+ case "wecom_aibot":
+ value["token"] = ch.WeComAIBot.Token()
+ value["key"] = ch.WeComAIBot.EncodingAESKey()
+ value["secret"] = ch.WeComAIBot.Secret()
+ case "dingtalk":
+ value["secret"] = ch.QQ.AppSecret()
+ case "qq":
+ value["secret"] = ch.DingTalk.ClientSecret()
+ case "irc":
+ value["password"] = ch.IRC.Password()
+ value["serv_password"] = ch.IRC.NickServPassword()
+ value["sasl_password"] = ch.IRC.SASLPassword()
+ case "feishu":
+ value["app_secret"] = ch.Feishu.AppSecret()
+ value["encrypt_key"] = ch.Feishu.EncryptKey()
+ value["verification_token"] = ch.Feishu.VerificationToken()
+ }
+}
+
func compareChannels(old, news map[string]string) (added, removed []string) {
for key, newHash := range news {
if oldHash, ok := old[key]; ok {
@@ -82,5 +126,61 @@ func toChannelConfig(cfg *config.Config, list []string) (*config.ChannelsConfig,
return nil, err
}
+ updateKeys(result, &ch)
+
return result, nil
}
+
+func updateKeys(newcfg, old *config.ChannelsConfig) {
+ if newcfg.Pico.Enabled {
+ newcfg.Pico.SetToken(old.Pico.Token())
+ }
+ if newcfg.Telegram.Enabled {
+ newcfg.Telegram.SetToken(old.Telegram.Token())
+ }
+ if newcfg.Discord.Enabled {
+ newcfg.Discord.SetToken(old.Discord.Token())
+ }
+ if newcfg.Slack.Enabled {
+ newcfg.Slack.SetBotToken(old.Slack.BotToken())
+ newcfg.Slack.SetAppToken(old.Slack.AppToken())
+ }
+ if newcfg.Matrix.Enabled {
+ newcfg.Matrix.SetAccessToken(old.Matrix.AccessToken())
+ }
+ if newcfg.OneBot.Enabled {
+ newcfg.OneBot.SetAccessToken(old.OneBot.AccessToken())
+ }
+ if newcfg.LINE.Enabled {
+ newcfg.LINE.SetChannelAccessToken(old.LINE.ChannelAccessToken())
+ newcfg.LINE.SetChannelSecret(old.LINE.ChannelSecret())
+ }
+ if newcfg.WeCom.Enabled {
+ newcfg.WeCom.SetToken(old.WeCom.Token())
+ newcfg.WeCom.SetEncodingAESKey(old.WeCom.EncodingAESKey())
+ }
+ if newcfg.WeComApp.Enabled {
+ newcfg.WeComApp.SetToken(old.WeComApp.Token())
+ newcfg.WeComApp.SetCorpSecret(old.WeComApp.CorpSecret())
+ }
+ if newcfg.WeComAIBot.Enabled {
+ newcfg.WeComAIBot.SetToken(old.WeComAIBot.Token())
+ newcfg.WeComAIBot.SetEncodingAESKey(old.WeComAIBot.EncodingAESKey())
+ }
+ if newcfg.DingTalk.Enabled {
+ newcfg.DingTalk.SetClientSecret(old.DingTalk.ClientSecret())
+ }
+ if newcfg.QQ.Enabled {
+ newcfg.QQ.SetAppSecret(old.QQ.AppSecret())
+ }
+ if newcfg.IRC.Enabled {
+ newcfg.IRC.SetPassword(old.IRC.Password())
+ newcfg.IRC.SetNickServPassword(old.IRC.NickServPassword())
+ newcfg.IRC.SetSASLPassword(old.IRC.SASLPassword())
+ }
+ if newcfg.Feishu.Enabled {
+ newcfg.Feishu.SetAppSecret(old.Feishu.AppSecret())
+ newcfg.Feishu.SetEncryptKey(old.Feishu.EncryptKey())
+ newcfg.Feishu.SetVerificationToken(old.Feishu.VerificationToken())
+ }
+}
diff --git a/pkg/channels/manager_channel_test.go b/pkg/channels/manager_channel_test.go
index 651764c4f..e17dcf17d 100644
--- a/pkg/channels/manager_channel_test.go
+++ b/pkg/channels/manager_channel_test.go
@@ -31,7 +31,7 @@ func TestToChannelHashes(t *testing.T) {
added, removed = compareChannels(results2, results3)
assert.EqualValues(t, []string{"dingtalk"}, removed)
assert.EqualValues(t, []string{"telegram"}, added)
- cfg3.Channels.Telegram.Token = "114314"
+ cfg3.Channels.Telegram.SetToken("114314")
results4 := toChannelHashes(cfg3)
assert.Equal(t, 1, len(results4))
logger.Debugf("results4: %v", results4)
@@ -41,11 +41,11 @@ func TestToChannelHashes(t *testing.T) {
cc, err := toChannelConfig(cfg3, added)
assert.NoError(t, err)
logger.Debugf("cc: %#v", cc.Telegram)
- assert.Equal(t, "114314", cc.Telegram.Token)
+ assert.Equal(t, "114314", cc.Telegram.Token())
assert.Equal(t, true, cc.Telegram.Enabled)
cc, err = toChannelConfig(cfg2, added)
assert.NoError(t, err)
logger.Debugf("cc: %#v", cc.Telegram)
- assert.Equal(t, "", cc.Telegram.Token)
+ assert.Equal(t, "", cc.Telegram.Token())
assert.Equal(t, false, cc.Telegram.Enabled)
}
diff --git a/pkg/channels/manager_test.go b/pkg/channels/manager_test.go
index e0f55288a..7dfec9ebf 100644
--- a/pkg/channels/manager_test.go
+++ b/pkg/channels/manager_test.go
@@ -511,6 +511,43 @@ func TestPreSend_PlaceholderEditFails_FallsThrough(t *testing.T) {
}
}
+func TestInvokeTypingStop_CallsRegisteredStop(t *testing.T) {
+ m := newTestManager()
+ var stopCalled bool
+
+ m.RecordTypingStop("telegram", "chat123", func() {
+ stopCalled = true
+ })
+
+ m.InvokeTypingStop("telegram", "chat123")
+
+ if !stopCalled {
+ t.Fatal("expected typing stop func to be called")
+ }
+}
+
+func TestInvokeTypingStop_NoOpWhenNoEntry(t *testing.T) {
+ m := newTestManager()
+ // Should not panic
+ m.InvokeTypingStop("telegram", "nonexistent")
+}
+
+func TestInvokeTypingStop_Idempotent(t *testing.T) {
+ m := newTestManager()
+ var callCount int
+
+ m.RecordTypingStop("telegram", "chat123", func() {
+ callCount++
+ })
+
+ m.InvokeTypingStop("telegram", "chat123")
+ m.InvokeTypingStop("telegram", "chat123") // Second call: entry already removed, no-op
+
+ if callCount != 1 {
+ t.Fatalf("expected stop to be called once, got %d", callCount)
+ }
+}
+
func TestPreSend_TypingStopCalled(t *testing.T) {
m := newTestManager()
var stopCalled bool
diff --git a/pkg/channels/matrix/matrix.go b/pkg/channels/matrix/matrix.go
index 4cbe95c5c..98c607d0b 100644
--- a/pkg/channels/matrix/matrix.go
+++ b/pkg/channels/matrix/matrix.go
@@ -186,7 +186,7 @@ type MatrixChannel struct {
func NewMatrixChannel(cfg config.MatrixConfig, messageBus *bus.MessageBus) (*MatrixChannel, error) {
homeserver := strings.TrimSpace(cfg.Homeserver)
userID := strings.TrimSpace(cfg.UserID)
- accessToken := strings.TrimSpace(cfg.AccessToken)
+ accessToken := strings.TrimSpace(cfg.AccessToken())
if homeserver == "" {
return nil, fmt.Errorf("matrix homeserver is required")
}
@@ -692,6 +692,9 @@ func (c *MatrixChannel) extractInboundMedia(
func (c *MatrixChannel) storeMedia(localPath string, meta media.MediaMeta, scope string) string {
if store := c.GetMediaStore(); store != nil {
+ if meta.CleanupPolicy == "" {
+ meta.CleanupPolicy = media.CleanupPolicyDeleteOnCleanup
+ }
ref, err := store.Store(localPath, meta, scope)
if err == nil {
return ref
diff --git a/pkg/channels/onebot/onebot.go b/pkg/channels/onebot/onebot.go
index 62a9eb34a..048be48eb 100644
--- a/pkg/channels/onebot/onebot.go
+++ b/pkg/channels/onebot/onebot.go
@@ -184,8 +184,8 @@ func (c *OneBotChannel) connect() error {
dialer.HandshakeTimeout = 10 * time.Second
header := make(map[string][]string)
- if c.config.AccessToken != "" {
- header["Authorization"] = []string{"Bearer " + c.config.AccessToken}
+ if c.config.AccessToken() != "" {
+ header["Authorization"] = []string{"Bearer " + c.config.AccessToken()}
}
conn, resp, err := dialer.Dial(c.config.WSUrl, header)
@@ -749,8 +749,9 @@ func (c *OneBotChannel) parseMessageSegments(
storeFile := func(localPath, filename string) string {
if store != nil {
ref, err := store.Store(localPath, media.MediaMeta{
- Filename: filename,
- Source: "onebot",
+ Filename: filename,
+ Source: "onebot",
+ CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
}, scope)
if err == nil {
return ref
diff --git a/pkg/channels/pico/client.go b/pkg/channels/pico/client.go
new file mode 100644
index 000000000..2c335050d
--- /dev/null
+++ b/pkg/channels/pico/client.go
@@ -0,0 +1,319 @@
+package pico
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/google/uuid"
+ "github.com/gorilla/websocket"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/channels"
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/identity"
+ "github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// PicoClientChannel connects to a remote Pico Protocol WebSocket server.
+type PicoClientChannel struct {
+ *channels.BaseChannel
+ config config.PicoClientConfig
+ conn *picoConn
+ mu sync.Mutex
+ ctx context.Context
+ cancel context.CancelFunc
+}
+
+// NewPicoClientChannel creates a new Pico Protocol client channel.
+func NewPicoClientChannel(
+ cfg config.PicoClientConfig,
+ messageBus *bus.MessageBus,
+) (*PicoClientChannel, error) {
+ if cfg.URL == "" {
+ return nil, fmt.Errorf("pico_client url is required")
+ }
+
+ base := channels.NewBaseChannel("pico_client", cfg, messageBus, cfg.AllowFrom)
+
+ return &PicoClientChannel{
+ BaseChannel: base,
+ config: cfg,
+ }, nil
+}
+
+// Start dials the remote server and begins reading.
+func (c *PicoClientChannel) Start(ctx context.Context) error {
+ logger.InfoC("pico_client", "Starting Pico Client channel")
+ c.ctx, c.cancel = context.WithCancel(ctx)
+
+ if err := c.dial(); err != nil {
+ c.cancel()
+ return fmt.Errorf("pico_client initial connect: %w", err)
+ }
+
+ c.SetRunning(true)
+ go c.reconnectLoop()
+
+ logger.InfoCF("pico_client", "Connected", map[string]any{"url": c.config.URL})
+ return nil
+}
+
+// Stop closes the connection.
+func (c *PicoClientChannel) Stop(ctx context.Context) error {
+ logger.InfoC("pico_client", "Stopping Pico Client channel")
+ c.SetRunning(false)
+ if c.cancel != nil {
+ c.cancel()
+ }
+ c.mu.Lock()
+ if c.conn != nil {
+ c.conn.close()
+ }
+ c.mu.Unlock()
+ logger.InfoC("pico_client", "Pico Client channel stopped")
+ return nil
+}
+
+func (c *PicoClientChannel) dial() error {
+ header := http.Header{}
+ if c.config.Token != "" {
+ header.Set("Authorization", "Bearer "+c.config.Token)
+ }
+
+ ws, resp, err := websocket.DefaultDialer.DialContext(c.ctx, c.config.URL, header)
+ if resp != nil && resp.Body != nil {
+ resp.Body.Close()
+ }
+ if err != nil {
+ return err
+ }
+
+ connCtx, connCancel := context.WithCancel(c.ctx)
+
+ pc := &picoConn{
+ id: uuid.New().String(),
+ conn: ws,
+ sessionID: c.config.SessionID,
+ cancel: connCancel,
+ }
+ if pc.sessionID == "" {
+ pc.sessionID = uuid.New().String()
+ }
+
+ c.mu.Lock()
+ c.conn = pc
+ c.mu.Unlock()
+
+ go c.readLoop(connCtx, pc)
+ return nil
+}
+
+// reconnectLoop re-dials when the connection drops.
+func (c *PicoClientChannel) reconnectLoop() {
+ for {
+ select {
+ case <-c.ctx.Done():
+ return
+ default:
+ }
+
+ c.mu.Lock()
+ pc := c.conn
+ c.mu.Unlock()
+
+ if pc == nil || pc.closed.Load() {
+ backoff := 5 * time.Second
+ logger.InfoC("pico_client", "Reconnecting...")
+ if err := c.dial(); err != nil {
+ logger.WarnCF("pico_client", "Reconnect failed", map[string]any{
+ "error": err.Error(),
+ })
+ select {
+ case <-c.ctx.Done():
+ return
+ case <-time.After(backoff):
+ }
+ continue
+ }
+ logger.InfoC("pico_client", "Reconnected")
+ }
+
+ select {
+ case <-c.ctx.Done():
+ return
+ case <-time.After(1 * time.Second):
+ }
+ }
+}
+
+func (c *PicoClientChannel) readLoop(connCtx context.Context, pc *picoConn) {
+ defer pc.close()
+
+ readTimeout := time.Duration(c.config.ReadTimeout) * time.Second
+ if readTimeout <= 0 {
+ readTimeout = 60 * time.Second
+ }
+
+ _ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+ pc.conn.SetPongHandler(func(string) error {
+ return pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+ })
+
+ pingInterval := time.Duration(c.config.PingInterval) * time.Second
+ if pingInterval <= 0 {
+ pingInterval = 30 * time.Second
+ }
+ go c.pingLoop(connCtx, pc, pingInterval)
+
+ for {
+ select {
+ case <-connCtx.Done():
+ return
+ default:
+ }
+
+ _, raw, err := pc.conn.ReadMessage()
+ if err != nil {
+ if websocket.IsUnexpectedCloseError(
+ err,
+ websocket.CloseGoingAway,
+ websocket.CloseNormalClosure,
+ ) {
+ logger.DebugCF("pico_client", "Read error", map[string]any{
+ "error": err.Error(),
+ })
+ }
+ return
+ }
+
+ _ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+
+ var msg PicoMessage
+ if err := json.Unmarshal(raw, &msg); err != nil {
+ continue
+ }
+
+ c.handleInbound(pc, msg)
+ }
+}
+
+func (c *PicoClientChannel) pingLoop(connCtx context.Context, pc *picoConn, interval time.Duration) {
+ ticker := time.NewTicker(interval)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-connCtx.Done():
+ return
+ case <-ticker.C:
+ if pc.closed.Load() {
+ return
+ }
+ pc.writeMu.Lock()
+ err := pc.conn.WriteMessage(websocket.PingMessage, nil)
+ pc.writeMu.Unlock()
+ if err != nil {
+ return
+ }
+ }
+ }
+}
+
+// handleInbound processes messages from the remote server.
+// In client mode the server sends message.create (responses) and the client
+// sends message.send (user input). We treat message.create from the server
+// as inbound user messages to feed into the agent loop.
+func (c *PicoClientChannel) handleInbound(pc *picoConn, msg PicoMessage) {
+ switch msg.Type {
+ case TypePong:
+ // response to our ping, ignore
+ case TypeMessageCreate:
+ // Server sent us a message — treat as inbound
+ c.handleServerMessage(pc, msg)
+ default:
+ logger.DebugCF("pico_client", "Ignoring message type", map[string]any{
+ "type": msg.Type,
+ })
+ }
+}
+
+func (c *PicoClientChannel) handleServerMessage(pc *picoConn, msg PicoMessage) {
+ content, _ := msg.Payload["content"].(string)
+ if strings.TrimSpace(content) == "" {
+ return
+ }
+
+ sessionID := msg.SessionID
+ if sessionID == "" {
+ sessionID = pc.sessionID
+ }
+
+ chatID := "pico_client:" + sessionID
+ senderID := "pico-remote"
+ peer := bus.Peer{Kind: "direct", ID: chatID}
+
+ sender := bus.SenderInfo{
+ Platform: "pico_client",
+ PlatformID: senderID,
+ CanonicalID: identity.BuildCanonicalID("pico_client", senderID),
+ }
+
+ if !c.IsAllowedSender(sender) {
+ return
+ }
+
+ c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, nil, map[string]string{
+ "platform": "pico_client",
+ "session_id": sessionID,
+ }, sender)
+}
+
+// Send sends a message to the remote server.
+func (c *PicoClientChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+ if !c.IsRunning() {
+ return channels.ErrNotRunning
+ }
+ c.mu.Lock()
+ pc := c.conn
+ c.mu.Unlock()
+ if pc == nil || pc.closed.Load() {
+ return channels.ErrSendFailed
+ }
+
+ outMsg := newMessage(TypeMessageSend, map[string]any{
+ "content": msg.Content,
+ })
+ outMsg.SessionID = strings.TrimPrefix(msg.ChatID, "pico_client:")
+ return pc.writeJSON(outMsg)
+}
+
+// StartTyping implements channels.TypingCapable.
+func (c *PicoClientChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+ c.mu.Lock()
+ pc := c.conn
+ c.mu.Unlock()
+ if pc == nil || pc.closed.Load() {
+ return func() {}, nil
+ }
+
+ startMsg := newMessage(TypeTypingStart, nil)
+ startMsg.SessionID = strings.TrimPrefix(chatID, "pico_client:")
+ if err := pc.writeJSON(startMsg); err != nil {
+ return func() {}, err
+ }
+ return func() {
+ c.mu.Lock()
+ currentPC := c.conn
+ c.mu.Unlock()
+ if currentPC == nil {
+ return
+ }
+ stopMsg := newMessage(TypeTypingStop, nil)
+ stopMsg.SessionID = strings.TrimPrefix(chatID, "pico_client:")
+ currentPC.writeJSON(stopMsg)
+ }, nil
+}
diff --git a/pkg/channels/pico/client_test.go b/pkg/channels/pico/client_test.go
new file mode 100644
index 000000000..118c9abea
--- /dev/null
+++ b/pkg/channels/pico/client_test.go
@@ -0,0 +1,264 @@
+package pico
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/gorilla/websocket"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/channels"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestNewPicoClientChannel_MissingURL(t *testing.T) {
+ _, err := NewPicoClientChannel(config.PicoClientConfig{}, bus.NewMessageBus())
+ if err == nil {
+ t.Fatal("expected error for missing URL")
+ }
+ if !strings.Contains(err.Error(), "url is required") {
+ t.Fatalf("unexpected error: %v", err)
+ }
+}
+
+func TestNewPicoClientChannel_OK(t *testing.T) {
+ ch, err := NewPicoClientChannel(config.PicoClientConfig{
+ URL: "ws://localhost:9999/ws",
+ }, bus.NewMessageBus())
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if ch.Name() != "pico_client" {
+ t.Fatalf("name = %q, want pico_client", ch.Name())
+ }
+}
+
+func TestSend_NotRunning(t *testing.T) {
+ ch, err := NewPicoClientChannel(config.PicoClientConfig{
+ URL: "ws://localhost:9999/ws",
+ }, bus.NewMessageBus())
+ if err != nil {
+ t.Fatal(err)
+ }
+ err = ch.Send(context.Background(), bus.OutboundMessage{Content: "hi"})
+ if !errors.Is(err, channels.ErrNotRunning) {
+ t.Fatalf("expected ErrNotRunning, got %v", err)
+ }
+}
+
+// testServer starts a WS server that echoes message.send back as message.create.
+func testServer(t *testing.T, token string) *httptest.Server {
+ t.Helper()
+ upgrader := websocket.Upgrader{CheckOrigin: func(*http.Request) bool { return true }}
+
+ return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if token != "" {
+ auth := r.Header.Get("Authorization")
+ if auth != "Bearer "+token {
+ http.Error(w, "unauthorized", http.StatusUnauthorized)
+ return
+ }
+ }
+
+ conn, err := upgrader.Upgrade(w, r, nil)
+ if err != nil {
+ t.Logf("upgrade error: %v", err)
+ return
+ }
+ defer conn.Close()
+
+ for {
+ _, raw, err := conn.ReadMessage()
+ if err != nil {
+ return
+ }
+
+ var msg PicoMessage
+ if err := json.Unmarshal(raw, &msg); err != nil {
+ continue
+ }
+
+ if msg.Type == TypeMessageSend {
+ reply := newMessage(TypeMessageCreate, msg.Payload)
+ reply.SessionID = msg.SessionID
+ if err := conn.WriteJSON(reply); err != nil {
+ return
+ }
+ }
+ }
+ }))
+}
+
+func wsURL(httpURL string) string {
+ return "ws" + strings.TrimPrefix(httpURL, "http")
+}
+
+func TestClientChannel_ConnectAndSend(t *testing.T) {
+ srv := testServer(t, "test-token")
+ defer srv.Close()
+
+ mb := bus.NewMessageBus()
+ ch, err := NewPicoClientChannel(config.PicoClientConfig{
+ URL: wsURL(srv.URL),
+ Token: "test-token",
+ SessionID: "sess-1",
+ PingInterval: 60,
+ ReadTimeout: 10,
+ }, mb)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+
+ if err = ch.Start(ctx); err != nil {
+ t.Fatalf("Start: %v", err)
+ }
+ defer ch.Stop(ctx)
+
+ // Send a message
+ err = ch.Send(ctx, bus.OutboundMessage{
+ ChatID: "pico_client:sess-1",
+ Content: "hello",
+ })
+ if err != nil {
+ t.Fatalf("Send: %v", err)
+ }
+}
+
+func TestClientChannel_AuthFailure(t *testing.T) {
+ srv := testServer(t, "correct-token")
+ defer srv.Close()
+
+ ch, err := NewPicoClientChannel(config.PicoClientConfig{
+ URL: wsURL(srv.URL),
+ Token: "wrong-token",
+ }, bus.NewMessageBus())
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+ defer cancel()
+
+ err = ch.Start(ctx)
+ if err == nil {
+ ch.Stop(ctx)
+ t.Fatal("expected auth failure")
+ }
+}
+
+func TestClientChannel_ReceivesServerMessage(t *testing.T) {
+ srv := testServer(t, "")
+ defer srv.Close()
+
+ mb := bus.NewMessageBus()
+
+ ch, err := NewPicoClientChannel(config.PicoClientConfig{
+ URL: wsURL(srv.URL),
+ SessionID: "sess-echo",
+ ReadTimeout: 10,
+ }, mb)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+
+ if err = ch.Start(ctx); err != nil {
+ t.Fatalf("Start: %v", err)
+ }
+ defer ch.Stop(ctx)
+
+ // Send a message; the echo server replies with message.create
+ err = ch.Send(ctx, bus.OutboundMessage{
+ ChatID: "pico_client:sess-echo",
+ Content: "ping",
+ })
+ if err != nil {
+ t.Fatalf("Send: %v", err)
+ }
+
+ // The echoed message.create is processed by handleServerMessage which
+ // calls HandleMessage → PublishInbound. Consume it from the bus.
+ select {
+ case msg := <-mb.InboundChan():
+ if msg.Content != "ping" {
+ t.Fatalf("received = %q, want %q", msg.Content, "ping")
+ }
+ case <-ctx.Done():
+ t.Fatal("timed out waiting for echoed message")
+ }
+}
+
+func TestClientChannel_StartTyping(t *testing.T) {
+ srv := testServer(t, "")
+ defer srv.Close()
+
+ ch, err := NewPicoClientChannel(config.PicoClientConfig{
+ URL: wsURL(srv.URL),
+ SessionID: "sess-type",
+ ReadTimeout: 10,
+ }, bus.NewMessageBus())
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+
+ if err = ch.Start(ctx); err != nil {
+ t.Fatalf("Start: %v", err)
+ }
+ defer ch.Stop(ctx)
+
+ stop, err := ch.StartTyping(ctx, "pico_client:sess-type")
+ if err != nil {
+ t.Fatalf("StartTyping: %v", err)
+ }
+ stop() // should not panic
+}
+
+func TestSend_ClosedConnection(t *testing.T) {
+ srv := testServer(t, "")
+ defer srv.Close()
+
+ ch, err := NewPicoClientChannel(config.PicoClientConfig{
+ URL: wsURL(srv.URL),
+ SessionID: "sess-close",
+ ReadTimeout: 10,
+ }, bus.NewMessageBus())
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+
+ if err = ch.Start(ctx); err != nil {
+ t.Fatalf("Start: %v", err)
+ }
+
+ // Force close the underlying connection
+ ch.mu.Lock()
+ ch.conn.close()
+ ch.mu.Unlock()
+
+ err = ch.Send(ctx, bus.OutboundMessage{
+ ChatID: "pico_client:sess-close",
+ Content: "should fail",
+ })
+ if !errors.Is(err, channels.ErrSendFailed) {
+ t.Fatalf("expected ErrSendFailed, got %v", err)
+ }
+
+ ch.Stop(ctx)
+}
diff --git a/pkg/channels/pico/init.go b/pkg/channels/pico/init.go
index 96d764418..0319279d8 100644
--- a/pkg/channels/pico/init.go
+++ b/pkg/channels/pico/init.go
@@ -10,4 +10,7 @@ func init() {
channels.RegisterFactory("pico", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
return NewPicoChannel(cfg.Channels.Pico, b)
})
+ channels.RegisterFactory("pico_client", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+ return NewPicoClientChannel(cfg.Channels.PicoClient, b)
+ })
}
diff --git a/pkg/channels/pico/pico.go b/pkg/channels/pico/pico.go
index 206e71f92..86ce98b06 100644
--- a/pkg/channels/pico/pico.go
+++ b/pkg/channels/pico/pico.go
@@ -27,6 +27,7 @@ type picoConn struct {
sessionID string
writeMu sync.Mutex
closed atomic.Bool
+ cancel context.CancelFunc // cancels per-connection goroutines (e.g. pingLoop)
}
// writeJSON sends a JSON message to the connection with write locking.
@@ -42,6 +43,9 @@ func (pc *picoConn) writeJSON(v any) error {
// close closes the connection.
func (pc *picoConn) close() {
if pc.closed.CompareAndSwap(false, true) {
+ if pc.cancel != nil {
+ pc.cancel()
+ }
pc.conn.Close()
}
}
@@ -60,7 +64,7 @@ type PicoChannel struct {
// NewPicoChannel creates a new Pico Protocol channel.
func NewPicoChannel(cfg config.PicoConfig, messageBus *bus.MessageBus) (*PicoChannel, error) {
- if cfg.Token == "" {
+ if cfg.Token() == "" {
return nil, fmt.Errorf("pico token is required")
}
@@ -293,7 +297,7 @@ func (c *PicoChannel) handleWebSocket(w http.ResponseWriter, r *http.Request) {
// 2. Sec-WebSocket-Protocol "token." (for browsers that can't set headers)
// 3. Query parameter "token" (only when AllowTokenQuery is on)
func (c *PicoChannel) authenticate(r *http.Request) bool {
- token := c.config.Token
+ token := c.config.Token()
if token == "" {
return false
}
@@ -324,7 +328,7 @@ func (c *PicoChannel) authenticate(r *http.Request) bool {
// matchedSubprotocol returns the "token." subprotocol that matches
// the configured token, or "" if none do.
func (c *PicoChannel) matchedSubprotocol(r *http.Request) string {
- token := c.config.Token
+ token := c.config.Token()
for _, proto := range websocket.Subprotocols(r) {
if after, ok := strings.CutPrefix(proto, "token."); ok && after == token {
return proto
diff --git a/pkg/channels/qq/audio_duration.go b/pkg/channels/qq/audio_duration.go
new file mode 100644
index 000000000..28a9b2e83
--- /dev/null
+++ b/pkg/channels/qq/audio_duration.go
@@ -0,0 +1,231 @@
+package qq
+
+import (
+ "encoding/binary"
+ "io"
+ "os"
+ "path/filepath"
+ "strings"
+ "time"
+)
+
+const qqVoiceMaxDuration = 60 * time.Second
+
+func qqAudioDuration(localPath, filename, contentType string) (time.Duration, bool, error) {
+ if localPath == "" {
+ return 0, false, nil
+ }
+
+ switch qqAudioDurationFormat(localPath, filename, contentType) {
+ case "wav":
+ return qqWAVDuration(localPath)
+ case "ogg":
+ return qqOggDuration(localPath)
+ default:
+ return 0, false, nil
+ }
+}
+
+func qqAudioDurationFormat(localPath, filename, contentType string) string {
+ contentType = strings.ToLower(contentType)
+
+ switch {
+ case strings.HasPrefix(contentType, "audio/wav"), strings.HasPrefix(contentType, "audio/x-wav"):
+ return "wav"
+ case strings.HasPrefix(contentType, "audio/ogg"),
+ contentType == "application/ogg",
+ contentType == "application/x-ogg":
+ return "ogg"
+ }
+
+ switch filepath.Ext(strings.ToLower(filename)) {
+ case ".wav":
+ return "wav"
+ case ".ogg", ".opus":
+ return "ogg"
+ }
+
+ switch filepath.Ext(strings.ToLower(localPath)) {
+ case ".wav":
+ return "wav"
+ case ".ogg", ".opus":
+ return "ogg"
+ }
+
+ return ""
+}
+
+func qqWAVDuration(localPath string) (time.Duration, bool, error) {
+ file, err := os.Open(localPath)
+ if err != nil {
+ return 0, false, err
+ }
+ defer file.Close()
+
+ var header [12]byte
+ if _, err := io.ReadFull(file, header[:]); err != nil {
+ return 0, false, err
+ }
+
+ var order binary.ByteOrder
+ switch string(header[:4]) {
+ case "RIFF":
+ order = binary.LittleEndian
+ case "RIFX":
+ order = binary.BigEndian
+ default:
+ return 0, false, nil
+ }
+
+ if string(header[8:12]) != "WAVE" {
+ return 0, false, nil
+ }
+
+ var byteRate uint32
+ var dataSize uint32
+ var foundFmt bool
+ var foundData bool
+
+ for {
+ var chunkHeader [8]byte
+ if _, err := io.ReadFull(file, chunkHeader[:]); err != nil {
+ if err == io.EOF {
+ break
+ }
+ return 0, false, err
+ }
+
+ chunkSize := order.Uint32(chunkHeader[4:8])
+ switch string(chunkHeader[:4]) {
+ case "fmt ":
+ chunkData := make([]byte, chunkSize)
+ if _, err := io.ReadFull(file, chunkData); err != nil {
+ return 0, false, err
+ }
+ if len(chunkData) >= 12 {
+ byteRate = order.Uint32(chunkData[8:12])
+ foundFmt = true
+ }
+ case "data":
+ dataSize = chunkSize
+ foundData = true
+ if _, err := io.CopyN(io.Discard, file, int64(chunkSize)); err != nil {
+ return 0, false, err
+ }
+ default:
+ if _, err := io.CopyN(io.Discard, file, int64(chunkSize)); err != nil {
+ return 0, false, err
+ }
+ }
+
+ if chunkSize%2 == 1 {
+ if _, err := io.CopyN(io.Discard, file, 1); err != nil {
+ return 0, false, err
+ }
+ }
+
+ if foundFmt && foundData {
+ break
+ }
+ }
+
+ if !foundFmt || !foundData || byteRate == 0 {
+ return 0, false, nil
+ }
+
+ durationNS := int64(dataSize) * int64(time.Second) / int64(byteRate)
+ return time.Duration(durationNS), true, nil
+}
+
+func qqOggDuration(localPath string) (time.Duration, bool, error) {
+ file, err := os.Open(localPath)
+ if err != nil {
+ return 0, false, err
+ }
+ defer file.Close()
+
+ var firstPacket []byte
+ var codec string
+ var sampleRate uint32
+ var lastGranule uint64
+ var haveGranule bool
+
+ for {
+ var header [27]byte
+ if _, err := io.ReadFull(file, header[:]); err != nil {
+ if err == io.EOF {
+ break
+ }
+ return 0, false, err
+ }
+
+ if string(header[:4]) != "OggS" {
+ return 0, false, nil
+ }
+
+ pageSegments := int(header[26])
+ segments := make([]byte, pageSegments)
+ if _, err := io.ReadFull(file, segments); err != nil {
+ return 0, false, err
+ }
+
+ payloadLen := 0
+ for _, segLen := range segments {
+ payloadLen += int(segLen)
+ }
+
+ payload := make([]byte, payloadLen)
+ if _, err := io.ReadFull(file, payload); err != nil {
+ return 0, false, err
+ }
+
+ granule := binary.LittleEndian.Uint64(header[6:14])
+ if granule != ^uint64(0) {
+ lastGranule = granule
+ haveGranule = true
+ }
+
+ if codec == "" {
+ offset := 0
+ for _, segLen := range segments {
+ firstPacket = append(firstPacket, payload[offset:offset+int(segLen)]...)
+ offset += int(segLen)
+ if segLen < 255 {
+ codec, sampleRate = qqParseOggCodec(firstPacket)
+ break
+ }
+ }
+ }
+ }
+
+ if !haveGranule || codec == "" {
+ return 0, false, nil
+ }
+
+ switch codec {
+ case "opus":
+ return time.Duration(lastGranule) * time.Second / 48000, true, nil
+ case "vorbis":
+ if sampleRate == 0 {
+ return 0, false, nil
+ }
+ return time.Duration(lastGranule) * time.Second / time.Duration(sampleRate), true, nil
+ default:
+ return 0, false, nil
+ }
+}
+
+func qqParseOggCodec(packet []byte) (string, uint32) {
+ if len(packet) >= 8 && string(packet[:8]) == "OpusHead" {
+ return "opus", 48000
+ }
+
+ if len(packet) >= 16 && packet[0] == 0x01 && string(packet[1:7]) == "vorbis" {
+ sampleRate := binary.LittleEndian.Uint32(packet[12:16])
+ if sampleRate > 0 {
+ return "vorbis", sampleRate
+ }
+ }
+
+ return "", 0
+}
diff --git a/pkg/channels/qq/qq.go b/pkg/channels/qq/qq.go
index 1a48369f8..cd66964dd 100644
--- a/pkg/channels/qq/qq.go
+++ b/pkg/channels/qq/qq.go
@@ -98,7 +98,7 @@ func NewQQChannel(cfg config.QQConfig, messageBus *bus.MessageBus) (*QQChannel,
}
func (c *QQChannel) Start(ctx context.Context) error {
- if c.config.AppID == "" || c.config.AppSecret == "" {
+ if c.config.AppID == "" || c.config.AppSecret() == "" {
return fmt.Errorf("QQ app_id and app_secret not configured")
}
@@ -112,7 +112,7 @@ func (c *QQChannel) Start(ctx context.Context) error {
// create token source
credentials := &token.QQBotCredentials{
AppID: c.config.AppID,
- AppSecret: c.config.AppSecret,
+ AppSecret: c.config.AppSecret(),
}
c.tokenSource = token.NewQQBotTokenSource(credentials)
@@ -387,12 +387,11 @@ func (c *QQChannel) uploadMedia(
}
func (c *QQChannel) buildMediaUpload(part bus.MediaPart) (*qqMediaUpload, error) {
- payload := &qqMediaUpload{
- FileType: qqFileType(part.Type),
- }
+ payload := &qqMediaUpload{}
mediaRef := part.Ref
if isHTTPURL(mediaRef) {
+ payload.FileType = qqFileType(c.outboundMediaType(part, ""))
payload.URL = mediaRef
return payload, nil
}
@@ -402,15 +401,23 @@ func (c *QQChannel) buildMediaUpload(part bus.MediaPart) (*qqMediaUpload, error)
return nil, fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
}
- resolved, err := store.Resolve(part.Ref)
+ resolved, meta, err := store.ResolveWithMeta(part.Ref)
if err != nil {
return nil, fmt.Errorf("qq resolve media ref %q: %v: %w", part.Ref, err, channels.ErrSendFailed)
}
+ if part.Filename == "" {
+ part.Filename = meta.Filename
+ }
+ if part.ContentType == "" {
+ part.ContentType = meta.ContentType
+ }
if isHTTPURL(resolved) {
+ payload.FileType = qqFileType(c.outboundMediaType(part, ""))
payload.URL = resolved
return payload, nil
}
+ payload.FileType = qqFileType(c.outboundMediaType(part, resolved))
if limitBytes := c.maxBase64FileSizeBytes(); limitBytes > 0 {
info, statErr := os.Stat(resolved)
@@ -437,6 +444,48 @@ func (c *QQChannel) buildMediaUpload(part bus.MediaPart) (*qqMediaUpload, error)
return payload, nil
}
+func (c *QQChannel) outboundMediaType(part bus.MediaPart, localPath string) string {
+ if part.Type != "audio" {
+ return part.Type
+ }
+
+ if localPath == "" {
+ logger.InfoCF("qq", "Sending audio as file because duration is unavailable", map[string]any{
+ "ref": part.Ref,
+ "filename": part.Filename,
+ })
+ return "file"
+ }
+
+ duration, ok, err := qqAudioDuration(localPath, part.Filename, part.ContentType)
+ if err != nil {
+ logger.WarnCF("qq", "Failed to detect audio duration, sending as file", map[string]any{
+ "ref": part.Ref,
+ "filename": part.Filename,
+ "error": err.Error(),
+ })
+ return "file"
+ }
+ if !ok {
+ logger.InfoCF("qq", "Sending audio as file because duration is unavailable", map[string]any{
+ "ref": part.Ref,
+ "filename": part.Filename,
+ })
+ return "file"
+ }
+ if duration > qqVoiceMaxDuration {
+ logger.InfoCF("qq", "Sending audio as file because it exceeds QQ voice limit", map[string]any{
+ "ref": part.Ref,
+ "filename": part.Filename,
+ "duration_seconds": duration.Seconds(),
+ "limit_seconds": qqVoiceMaxDuration.Seconds(),
+ })
+ return "file"
+ }
+
+ return "audio"
+}
+
func (c *QQChannel) sendUploadedMedia(
ctx context.Context,
chatKind, chatID string,
@@ -670,9 +719,10 @@ func (c *QQChannel) extractInboundAttachments(
storeMedia := func(localPath string, attachment *dto.MessageAttachment) string {
if store := c.GetMediaStore(); store != nil {
ref, err := store.Store(localPath, media.MediaMeta{
- Filename: qqAttachmentFilename(attachment),
- ContentType: attachment.ContentType,
- Source: "qq",
+ Filename: qqAttachmentFilename(attachment),
+ ContentType: attachment.ContentType,
+ Source: "qq",
+ CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
}, scope)
if err == nil {
return ref
diff --git a/pkg/channels/qq/qq_test.go b/pkg/channels/qq/qq_test.go
index 3cb3d39bd..108965c00 100644
--- a/pkg/channels/qq/qq_test.go
+++ b/pkg/channels/qq/qq_test.go
@@ -1,8 +1,10 @@
package qq
import (
+ "bytes"
"context"
"encoding/base64"
+ "encoding/binary"
"encoding/json"
"errors"
"os"
@@ -264,6 +266,142 @@ func TestSendMedia_UploadsLocalFileAsBase64(t *testing.T) {
}
}
+func TestSendMedia_AudioAt60SecondsUsesVoiceUpload(t *testing.T) {
+ assertAudioWAVUploadType(t, 60*time.Second, 3)
+}
+
+func TestSendMedia_AudioOver60SecondsFallsBackToFileUpload(t *testing.T) {
+ assertAudioWAVUploadType(t, 61*time.Second, 4)
+}
+
+func assertAudioWAVUploadType(t *testing.T, duration time.Duration, wantFileType uint64) {
+ t.Helper()
+
+ messageBus := bus.NewMessageBus()
+ store := media.NewFileMediaStore()
+
+ localPath := writeWAVFile(t, t.TempDir(), "voice.wav", duration)
+ ref, err := store.Store(localPath, media.MediaMeta{
+ Filename: "voice.wav",
+ ContentType: "audio/wav",
+ }, "qq:test")
+ if err != nil {
+ t.Fatalf("Store() error = %v", err)
+ }
+
+ api := &fakeQQAPI{
+ transportResp: mustJSON(t, dto.Message{FileInfo: []byte("file-info")}),
+ }
+ ch := &QQChannel{
+ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+ api: api,
+ dedup: make(map[string]time.Time),
+ done: make(chan struct{}),
+ ctx: context.Background(),
+ }
+ ch.SetRunning(true)
+ ch.SetMediaStore(store)
+ ch.chatType.Store("group-1", "group")
+
+ err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+ ChatID: "group-1",
+ Parts: []bus.MediaPart{{
+ Type: "audio",
+ Ref: ref,
+ }},
+ })
+ if err != nil {
+ t.Fatalf("SendMedia() error = %v", err)
+ }
+
+ if len(api.transportCalls) != 1 {
+ t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+ }
+ if api.transportCalls[0].body.FileType != wantFileType {
+ t.Fatalf("upload file_type = %d, want %d", api.transportCalls[0].body.FileType, wantFileType)
+ }
+}
+
+func TestSendMedia_RemoteAudioFallsBackToFileUpload(t *testing.T) {
+ messageBus := bus.NewMessageBus()
+ api := &fakeQQAPI{
+ transportResp: mustJSON(t, dto.Message{FileInfo: []byte("remote-file-info")}),
+ }
+ ch := &QQChannel{
+ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+ api: api,
+ dedup: make(map[string]time.Time),
+ done: make(chan struct{}),
+ ctx: context.Background(),
+ }
+ ch.SetRunning(true)
+ ch.chatType.Store("user-1", "direct")
+
+ err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+ ChatID: "user-1",
+ Parts: []bus.MediaPart{{
+ Type: "audio",
+ Ref: "https://cdn.example.com/voice.ogg",
+ }},
+ })
+ if err != nil {
+ t.Fatalf("SendMedia() error = %v", err)
+ }
+
+ if len(api.transportCalls) != 1 {
+ t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+ }
+ if api.transportCalls[0].body.FileType != 4 {
+ t.Fatalf("upload file_type = %d, want 4", api.transportCalls[0].body.FileType)
+ }
+}
+
+func TestSendMedia_LocalAudioWithUnknownDurationFallsBackToFileUpload(t *testing.T) {
+ messageBus := bus.NewMessageBus()
+ store := media.NewFileMediaStore()
+
+ localPath := writeTempFile(t, t.TempDir(), "voice.mp3", []byte("not-a-real-mp3"))
+ ref, err := store.Store(localPath, media.MediaMeta{
+ Filename: "voice.mp3",
+ ContentType: "audio/mpeg",
+ }, "qq:test")
+ if err != nil {
+ t.Fatalf("Store() error = %v", err)
+ }
+
+ api := &fakeQQAPI{
+ transportResp: mustJSON(t, dto.Message{FileInfo: []byte("file-info")}),
+ }
+ ch := &QQChannel{
+ BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+ api: api,
+ dedup: make(map[string]time.Time),
+ done: make(chan struct{}),
+ ctx: context.Background(),
+ }
+ ch.SetRunning(true)
+ ch.SetMediaStore(store)
+ ch.chatType.Store("group-1", "group")
+
+ err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+ ChatID: "group-1",
+ Parts: []bus.MediaPart{{
+ Type: "audio",
+ Ref: ref,
+ }},
+ })
+ if err != nil {
+ t.Fatalf("SendMedia() error = %v", err)
+ }
+
+ if len(api.transportCalls) != 1 {
+ t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+ }
+ if api.transportCalls[0].body.FileType != 4 {
+ t.Fatalf("upload file_type = %d, want 4", api.transportCalls[0].body.FileType)
+ }
+}
+
func TestSendMedia_UsesRemoteURLUploadForC2C(t *testing.T) {
messageBus := bus.NewMessageBus()
api := &fakeQQAPI{
@@ -494,3 +632,53 @@ func writeTempFile(t *testing.T, dir, name string, content []byte) string {
}
return path
}
+
+func writeWAVFile(t *testing.T, dir, name string, duration time.Duration) string {
+ t.Helper()
+
+ const (
+ sampleRate = 8000
+ numChannels = 1
+ bitsPerSample = 8
+ )
+
+ dataSize := uint32(duration / time.Second * sampleRate * numChannels * (bitsPerSample / 8))
+ byteRate := uint32(sampleRate * numChannels * (bitsPerSample / 8))
+ blockAlign := uint16(numChannels * (bitsPerSample / 8))
+
+ var buf bytes.Buffer
+ buf.WriteString("RIFF")
+ if err := binary.Write(&buf, binary.LittleEndian, uint32(36)+dataSize); err != nil {
+ t.Fatalf("binary.Write(riff size) error = %v", err)
+ }
+ buf.WriteString("WAVE")
+ buf.WriteString("fmt ")
+ if err := binary.Write(&buf, binary.LittleEndian, uint32(16)); err != nil {
+ t.Fatalf("binary.Write(fmt chunk size) error = %v", err)
+ }
+ if err := binary.Write(&buf, binary.LittleEndian, uint16(1)); err != nil {
+ t.Fatalf("binary.Write(audio format) error = %v", err)
+ }
+ if err := binary.Write(&buf, binary.LittleEndian, uint16(numChannels)); err != nil {
+ t.Fatalf("binary.Write(channels) error = %v", err)
+ }
+ if err := binary.Write(&buf, binary.LittleEndian, uint32(sampleRate)); err != nil {
+ t.Fatalf("binary.Write(sample rate) error = %v", err)
+ }
+ if err := binary.Write(&buf, binary.LittleEndian, byteRate); err != nil {
+ t.Fatalf("binary.Write(byte rate) error = %v", err)
+ }
+ if err := binary.Write(&buf, binary.LittleEndian, blockAlign); err != nil {
+ t.Fatalf("binary.Write(block align) error = %v", err)
+ }
+ if err := binary.Write(&buf, binary.LittleEndian, uint16(bitsPerSample)); err != nil {
+ t.Fatalf("binary.Write(bits per sample) error = %v", err)
+ }
+ buf.WriteString("data")
+ if err := binary.Write(&buf, binary.LittleEndian, dataSize); err != nil {
+ t.Fatalf("binary.Write(data size) error = %v", err)
+ }
+ buf.Write(make([]byte, dataSize))
+
+ return writeTempFile(t, dir, name, buf.Bytes())
+}
diff --git a/pkg/channels/slack/slack.go b/pkg/channels/slack/slack.go
index 3ee849621..f03283ea4 100644
--- a/pkg/channels/slack/slack.go
+++ b/pkg/channels/slack/slack.go
@@ -37,13 +37,13 @@ type slackMessageRef struct {
}
func NewSlackChannel(cfg config.SlackConfig, messageBus *bus.MessageBus) (*SlackChannel, error) {
- if cfg.BotToken == "" || cfg.AppToken == "" {
+ if cfg.BotToken() == "" || cfg.AppToken() == "" {
return nil, fmt.Errorf("slack bot_token and app_token are required")
}
api := slack.New(
- cfg.BotToken,
- slack.OptionAppLevelToken(cfg.AppToken),
+ cfg.BotToken(),
+ slack.OptionAppLevelToken(cfg.AppToken()),
)
socketClient := socketmode.New(api)
@@ -327,8 +327,9 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
storeMedia := func(localPath, filename string) string {
if store := c.GetMediaStore(); store != nil {
ref, err := store.Store(localPath, media.MediaMeta{
- Filename: filename,
- Source: "slack",
+ Filename: filename,
+ Source: "slack",
+ CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
}, scope)
if err == nil {
return ref
@@ -515,7 +516,7 @@ func (c *SlackChannel) downloadSlackFile(file slack.File) string {
return utils.DownloadFile(downloadURL, file.Name, utils.DownloadOptions{
LoggerPrefix: "slack",
ExtraHeaders: map[string]string{
- "Authorization": "Bearer " + c.config.BotToken,
+ "Authorization": "Bearer " + c.config.BotToken(),
},
})
}
diff --git a/pkg/channels/slack/slack_test.go b/pkg/channels/slack/slack_test.go
index 30e0d2d73..23a7ee5c4 100644
--- a/pkg/channels/slack/slack_test.go
+++ b/pkg/channels/slack/slack_test.go
@@ -102,10 +102,8 @@ func TestNewSlackChannel(t *testing.T) {
msgBus := bus.NewMessageBus()
t.Run("missing bot token", func(t *testing.T) {
- cfg := config.SlackConfig{
- BotToken: "",
- AppToken: "xapp-test",
- }
+ cfg := config.SlackConfig{}
+ cfg.SetAppToken("xapp-test")
_, err := NewSlackChannel(cfg, msgBus)
if err == nil {
t.Error("expected error for missing bot_token, got nil")
@@ -113,10 +111,8 @@ func TestNewSlackChannel(t *testing.T) {
})
t.Run("missing app token", func(t *testing.T) {
- cfg := config.SlackConfig{
- BotToken: "xoxb-test",
- AppToken: "",
- }
+ cfg := config.SlackConfig{}
+ cfg.SetBotToken("xoxb-test")
_, err := NewSlackChannel(cfg, msgBus)
if err == nil {
t.Error("expected error for missing app_token, got nil")
@@ -125,10 +121,10 @@ func TestNewSlackChannel(t *testing.T) {
t.Run("valid config", func(t *testing.T) {
cfg := config.SlackConfig{
- BotToken: "xoxb-test",
- AppToken: "xapp-test",
AllowFrom: []string{"U123"},
}
+ cfg.SetBotToken("xoxb-test")
+ cfg.SetAppToken("xapp-test")
ch, err := NewSlackChannel(cfg, msgBus)
if err != nil {
t.Fatalf("unexpected error: %v", err)
@@ -147,10 +143,10 @@ func TestSlackChannelIsAllowed(t *testing.T) {
t.Run("empty allowlist allows all", func(t *testing.T) {
cfg := config.SlackConfig{
- BotToken: "xoxb-test",
- AppToken: "xapp-test",
AllowFrom: []string{},
}
+ cfg.SetBotToken("xoxb-test")
+ cfg.SetAppToken("xapp-test")
ch, _ := NewSlackChannel(cfg, msgBus)
if !ch.IsAllowed("U_ANYONE") {
t.Error("empty allowlist should allow all users")
@@ -159,10 +155,10 @@ func TestSlackChannelIsAllowed(t *testing.T) {
t.Run("allowlist restricts users", func(t *testing.T) {
cfg := config.SlackConfig{
- BotToken: "xoxb-test",
- AppToken: "xapp-test",
AllowFrom: []string{"U_ALLOWED"},
}
+ cfg.SetBotToken("xoxb-test")
+ cfg.SetAppToken("xapp-test")
ch, _ := NewSlackChannel(cfg, msgBus)
if !ch.IsAllowed("U_ALLOWED") {
t.Error("allowed user should pass allowlist check")
diff --git a/pkg/channels/telegram/telegram.go b/pkg/channels/telegram/telegram.go
index 9d0325093..f62d6d008 100644
--- a/pkg/channels/telegram/telegram.go
+++ b/pkg/channels/telegram/telegram.go
@@ -2,6 +2,8 @@ package telegram
import (
"context"
+ "crypto/rand"
+ "encoding/binary"
"fmt"
"io"
"net/http"
@@ -10,6 +12,7 @@ import (
"regexp"
"strconv"
"strings"
+ "sync"
"time"
"github.com/mymmrac/telego"
@@ -80,7 +83,7 @@ func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChann
}
opts = append(opts, telego.WithLogger(logger.NewLogger("telego")))
- bot, err := telego.NewBot(telegramCfg.Token, opts...)
+ bot, err := telego.NewBot(telegramCfg.Token(), opts...)
if err != nil {
return nil, fmt.Errorf("failed to create telegram bot: %w", err)
}
@@ -302,10 +305,17 @@ func (c *TelegramChannel) sendChunk(
return nil
}
+// maxTypingDuration limits how long the typing indicator can run.
+// Prevents endless typing when the LLM fails/hangs and preSend never invokes cancel.
+// Matches channels.Manager's typingStopTTL (5 min) so behavior is consistent.
+const maxTypingDuration = 5 * time.Minute
+
// StartTyping implements channels.TypingCapable.
// It sends ChatAction(typing) immediately and then repeats every 4 seconds
// (Telegram's typing indicator expires after ~5s) in a background goroutine.
// The returned stop function is idempotent and cancels the goroutine.
+// The goroutine also exits automatically after maxTypingDuration if cancel is
+// never called (e.g. when the LLM fails or times out without publishing).
func (c *TelegramChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
cid, threadID, err := parseTelegramChatID(chatID)
if err != nil {
@@ -319,12 +329,15 @@ func (c *TelegramChannel) StartTyping(ctx context.Context, chatID string) (func(
_ = c.bot.SendChatAction(ctx, action)
typingCtx, cancel := context.WithCancel(ctx)
+ // Cap lifetime so the goroutine cannot run indefinitely if cancel is never called
+ maxCtx, maxCancel := context.WithTimeout(typingCtx, maxTypingDuration)
go func() {
+ defer maxCancel()
ticker := time.NewTicker(4 * time.Second)
defer ticker.Stop()
for {
select {
- case <-typingCtx.Done():
+ case <-maxCtx.Done():
return
case <-ticker.C:
a := tu.ChatAction(tu.ID(cid), telego.ChatActionTyping)
@@ -364,6 +377,22 @@ func (c *TelegramChannel) EditMessage(ctx context.Context, chatID string, messag
return err
}
+// DeleteMessage implements channels.MessageDeleter.
+func (c *TelegramChannel) DeleteMessage(ctx context.Context, chatID string, messageID string) error {
+ cid, _, err := parseTelegramChatID(chatID)
+ if err != nil {
+ return err
+ }
+ mid, err := strconv.Atoi(messageID)
+ if err != nil {
+ return err
+ }
+ return c.bot.DeleteMessage(ctx, &telego.DeleteMessageParams{
+ ChatID: tu.ID(cid),
+ MessageID: mid,
+ })
+}
+
// SendPlaceholder implements channels.PlaceholderCapable.
// It sends a placeholder message (e.g. "Thinking... 💭") that will later be
// edited to the actual response via EditMessage (channels.MessageEditor).
@@ -532,8 +561,9 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
storeMedia := func(localPath, filename string) string {
if store := c.GetMediaStore(); store != nil {
ref, err := store.Store(localPath, media.MediaMeta{
- Filename: filename,
- Source: "telegram",
+ Filename: filename,
+ Source: "telegram",
+ CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
}, scope)
if err == nil {
return ref
@@ -837,3 +867,107 @@ func (c *TelegramChannel) stripBotMention(content string) string {
content = re.ReplaceAllString(content, "")
return strings.TrimSpace(content)
}
+
+// BeginStream implements channels.StreamingCapable.
+func (c *TelegramChannel) BeginStream(ctx context.Context, chatID string) (channels.Streamer, error) {
+ if !c.config.Channels.Telegram.Streaming.Enabled {
+ return nil, fmt.Errorf("streaming disabled in config")
+ }
+
+ cid, _, err := parseTelegramChatID(chatID)
+ if err != nil {
+ return nil, err
+ }
+
+ streamCfg := c.config.Channels.Telegram.Streaming
+ return &telegramStreamer{
+ bot: c.bot,
+ chatID: cid,
+ draftID: cryptoRandInt(),
+ throttleInterval: time.Duration(streamCfg.ThrottleSeconds) * time.Second,
+ minGrowth: streamCfg.MinGrowthChars,
+ }, nil
+}
+
+// telegramStreamer streams partial LLM output via Telegram's sendMessageDraft API.
+// On first API error (e.g. bot lacks forum mode), it silently degrades: Update
+// becomes a no-op, while Finalize still delivers the final message.
+type telegramStreamer struct {
+ bot *telego.Bot
+ chatID int64
+ draftID int
+ throttleInterval time.Duration
+ minGrowth int
+ lastLen int
+ lastAt time.Time
+ failed bool
+ mu sync.Mutex
+}
+
+func (s *telegramStreamer) Update(ctx context.Context, content string) error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ if s.failed {
+ return nil
+ }
+
+ // Throttle: skip if not enough time or content has passed
+ now := time.Now()
+ growth := len(content) - s.lastLen
+ if s.lastLen > 0 && now.Sub(s.lastAt) < s.throttleInterval && growth < s.minGrowth {
+ return nil
+ }
+
+ htmlContent := markdownToTelegramHTML(content)
+
+ err := s.bot.SendMessageDraft(ctx, &telego.SendMessageDraftParams{
+ ChatID: s.chatID,
+ DraftID: s.draftID,
+ Text: htmlContent,
+ ParseMode: telego.ModeHTML,
+ })
+ if err != nil {
+ // First error → degrade silently (e.g. no forum mode)
+ logger.WarnCF("telegram", "sendMessageDraft failed, disabling streaming", map[string]any{
+ "error": err.Error(),
+ })
+ s.failed = true
+ return nil // don't propagate — Finalize will still deliver
+ }
+
+ s.lastLen = len(content)
+ s.lastAt = now
+ return nil
+}
+
+func (s *telegramStreamer) Finalize(ctx context.Context, content string) error {
+ htmlContent := markdownToTelegramHTML(content)
+ tgMsg := tu.Message(tu.ID(s.chatID), htmlContent)
+ tgMsg.ParseMode = telego.ModeHTML
+
+ if _, err := s.bot.SendMessage(ctx, tgMsg); err != nil {
+ // Fallback to plain text
+ tgMsg.ParseMode = ""
+ if _, err = s.bot.SendMessage(ctx, tgMsg); err != nil {
+ logger.ErrorCF("telegram", "Finalize failed after HTML and plain-text attempts", map[string]any{
+ "chat_id": s.chatID,
+ "error": err.Error(),
+ "len": len(content),
+ })
+ return fmt.Errorf("telegram finalize: %w", err)
+ }
+ }
+ return nil
+}
+
+func (s *telegramStreamer) Cancel(ctx context.Context) {
+ // Draft auto-expires on Telegram's side; nothing to clean up.
+}
+
+// cryptoRandInt returns a non-zero random int using crypto/rand.
+func cryptoRandInt() int {
+ var b [4]byte
+ _, _ = rand.Read(b[:])
+ return int(binary.BigEndian.Uint32(b[:])) | 1 // ensure non-zero
+}
diff --git a/pkg/channels/wecom/aibot.go b/pkg/channels/wecom/aibot.go
index 999f4f13b..c5e148185 100644
--- a/pkg/channels/wecom/aibot.go
+++ b/pkg/channels/wecom/aibot.go
@@ -139,7 +139,7 @@ type WeComAIBotEncryptedResponse struct {
}
// NewWeComAIBotChannel creates a WeCom AI Bot channel instance.
-// If cfg.BotID and cfg.Secret are both set, it returns a WeComAIBotWSChannel
+// If cfg.BotID and cfg.secret are both set, it returns a WeComAIBotWSChannel
// using the WebSocket long-connection API.
// Otherwise it returns the webhook-mode WeComAIBotChannel (requires Token +
// EncodingAESKey).
@@ -147,17 +147,20 @@ func NewWeComAIBotChannel(
cfg config.WeComAIBotConfig,
messageBus *bus.MessageBus,
) (channels.Channel, error) {
- // WebSocket long-connection mode takes priority when BotID + Secret are set.
- if cfg.BotID != "" && cfg.Secret != "" {
- logger.InfoC("wecom_aibot", "BotID and Secret provided, using WebSocket mode")
+ // WebSocket long-connection mode takes priority when BotID + secret are set.
+ if cfg.BotID != "" && cfg.Secret() != "" {
+ logger.InfoC("wecom_aibot", "BotID and secret provided, using WebSocket mode")
return newWeComAIBotWSChannel(cfg, messageBus)
}
// Webhook (short-connection) mode.
- if cfg.Token == "" || cfg.EncodingAESKey == "" {
+ if cfg.Token() == "" || cfg.EncodingAESKey() == "" {
return nil, fmt.Errorf(
"WeCom AI Bot requires either (bot_id + secret) for WebSocket mode " +
"or (token + encoding_aes_key) for webhook mode")
}
+ if cfg.ProcessingMessage == "" {
+ cfg.ProcessingMessage = config.DefaultWeComAIBotProcessingMessage
+ }
base := channels.NewBaseChannel("wecom_aibot", cfg, messageBus, cfg.AllowFrom,
channels.WithMaxMessageLength(2048),
@@ -347,7 +350,7 @@ func (c *WeComAIBotChannel) handleVerification(
})
// Verify signature
- if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
+ if !verifySignature(c.config.Token(), msgSignature, timestamp, nonce, echostr) {
logger.ErrorC("wecom_aibot", "Signature verification failed")
http.Error(w, "Signature verification failed", http.StatusUnauthorized)
return
@@ -355,7 +358,7 @@ func (c *WeComAIBotChannel) handleVerification(
// Decrypt echostr
// For WeCom AI Bot (智能机器人), receiveid should be empty string
- decrypted, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
+ decrypted, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey(), "")
if err != nil {
logger.ErrorCF("wecom_aibot", "Failed to decrypt echostr", map[string]any{
"error": err,
@@ -414,7 +417,7 @@ func (c *WeComAIBotChannel) handleMessageCallback(
}
// Verify signature
- if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
+ if !verifySignature(c.config.Token(), msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
logger.ErrorC("wecom_aibot", "Signature verification failed")
http.Error(w, "Signature verification failed", http.StatusUnauthorized)
return
@@ -422,7 +425,7 @@ func (c *WeComAIBotChannel) handleMessageCallback(
// Decrypt message
// For WeCom AI Bot (智能机器人), receiveid is empty string
- decrypted, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
+ decrypted, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey(), "")
if err != nil {
logger.ErrorCF("wecom_aibot", "Failed to decrypt message", map[string]any{
"error": err,
@@ -709,7 +712,7 @@ func (c *WeComAIBotChannel) getStreamResponse(task *streamTask, timestamp, nonce
default:
if time.Now().After(task.Deadline) {
// Deadline reached: close the stream with a notice, then wait for agent via response_url.
- content = "⏳ Processing, please wait. The results will be sent shortly."
+ content = c.config.ProcessingMessage
finish = true
closeStreamOnly = true
logger.InfoCF(
@@ -856,7 +859,7 @@ func (c *WeComAIBotChannel) encryptResponse(
}
// Generate signature
- signature := computeSignature(c.config.Token, timestamp, nonce, encrypted)
+ signature := computeSignature(c.config.Token(), timestamp, nonce, encrypted)
// Build encrypted response
encryptedResp := WeComAIBotEncryptedResponse{
@@ -891,7 +894,7 @@ func (c *WeComAIBotChannel) encryptEmptyResponse(timestamp, nonce string) string
// encryptMessage encrypts a plain text message for WeCom AI Bot
func (c *WeComAIBotChannel) encryptMessage(plaintext, receiveid string) (string, error) {
- aesKey, err := decodeWeComAESKey(c.config.EncodingAESKey)
+ aesKey, err := decodeWeComAESKey(c.config.EncodingAESKey())
if err != nil {
return "", err
}
diff --git a/pkg/channels/wecom/aibot_test.go b/pkg/channels/wecom/aibot_test.go
index 7c5ae67b1..11c4393d6 100644
--- a/pkg/channels/wecom/aibot_test.go
+++ b/pkg/channels/wecom/aibot_test.go
@@ -2,6 +2,7 @@ package wecom
import (
"context"
+ "encoding/json"
"testing"
"time"
@@ -14,12 +15,11 @@ import (
func TestNewWeComAIBotChannel_WebhookMode(t *testing.T) {
t.Run("success with valid config", func(t *testing.T) {
- cfg := config.WeComAIBotConfig{
- Enabled: true,
- Token: "test_token",
- EncodingAESKey: "testkey1234567890123456789012345678901234567",
- WebhookPath: "/webhook/test",
- }
+ cfg := config.WeComAIBotConfig{}
+ cfg.Enabled = true
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey("testkey1234567890123456789012345678901234567")
+ cfg.WebhookPath = "/webhook/test"
messageBus := bus.NewMessageBus()
ch, err := NewWeComAIBotChannel(cfg, messageBus)
@@ -39,10 +39,10 @@ func TestNewWeComAIBotChannel_WebhookMode(t *testing.T) {
})
t.Run("error with missing token", func(t *testing.T) {
- cfg := config.WeComAIBotConfig{
- Enabled: true,
- EncodingAESKey: "testkey1234567890123456789012345678901234567",
- }
+ cfg := config.WeComAIBotConfig{}
+ cfg.Enabled = true
+ cfg.SetEncodingAESKey("testkey1234567890123456789012345678901234567")
+
messageBus := bus.NewMessageBus()
_, err := NewWeComAIBotChannel(cfg, messageBus)
if err == nil {
@@ -51,10 +51,10 @@ func TestNewWeComAIBotChannel_WebhookMode(t *testing.T) {
})
t.Run("error with missing encoding key", func(t *testing.T) {
- cfg := config.WeComAIBotConfig{
- Enabled: true,
- Token: "test_token",
- }
+ cfg := config.WeComAIBotConfig{}
+ cfg.Enabled = true
+ cfg.SetToken("test_token")
+
messageBus := bus.NewMessageBus()
_, err := NewWeComAIBotChannel(cfg, messageBus)
if err == nil {
@@ -65,10 +65,10 @@ func TestNewWeComAIBotChannel_WebhookMode(t *testing.T) {
func TestWeComAIBotWebhookChannelStartStop(t *testing.T) {
cfg := config.WeComAIBotConfig{
- Enabled: true,
- Token: "test_token",
- EncodingAESKey: "testkey1234567890123456789012345678901234567",
+ Enabled: true,
}
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey("testkey1234567890123456789012345678901234567")
messageBus := bus.NewMessageBus()
ch, err := NewWeComAIBotChannel(cfg, messageBus)
@@ -95,11 +95,11 @@ func TestWeComAIBotWebhookChannelStartStop(t *testing.T) {
func TestWeComAIBotChannelWebhookPath(t *testing.T) {
t.Run("default path", func(t *testing.T) {
- cfg := config.WeComAIBotConfig{
- Enabled: true,
- Token: "test_token",
- EncodingAESKey: "testkey1234567890123456789012345678901234567",
- }
+ cfg := config.WeComAIBotConfig{}
+ cfg.Enabled = true
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey("testkey1234567890123456789012345678901234567")
+
messageBus := bus.NewMessageBus()
ch, _ := NewWeComAIBotChannel(cfg, messageBus)
@@ -115,12 +115,12 @@ func TestWeComAIBotChannelWebhookPath(t *testing.T) {
t.Run("custom path", func(t *testing.T) {
customPath := "/custom/webhook"
- cfg := config.WeComAIBotConfig{
- Enabled: true,
- Token: "test_token",
- EncodingAESKey: "testkey1234567890123456789012345678901234567",
- WebhookPath: customPath,
- }
+ cfg := config.WeComAIBotConfig{}
+ cfg.Enabled = true
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey("testkey1234567890123456789012345678901234567")
+ cfg.WebhookPath = customPath
+
messageBus := bus.NewMessageBus()
ch, _ := NewWeComAIBotChannel(cfg, messageBus)
@@ -134,12 +134,93 @@ func TestWeComAIBotChannelWebhookPath(t *testing.T) {
})
}
+func TestWeComAIBotChannelGetStreamResponseProcessingMessage(t *testing.T) {
+ validAESKey := "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"
+
+ t.Run("uses default processing message", func(t *testing.T) {
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ }
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey(validAESKey)
+
+ messageBus := bus.NewMessageBus()
+ channel, err := NewWeComAIBotChannel(cfg, messageBus)
+ if err != nil {
+ t.Fatalf("Failed to create channel: %v", err)
+ }
+ ch, ok := channel.(*WeComAIBotChannel)
+ if !ok {
+ t.Fatal("Expected webhook mode channel")
+ }
+
+ task := &streamTask{
+ StreamID: "stream-default",
+ ChatID: "chat-default",
+ Deadline: time.Now().Add(-time.Second),
+ }
+ ch.streamTasks[task.StreamID] = task
+ ch.chatTasks[task.ChatID] = []*streamTask{task}
+
+ resp := decodeStreamResponse(t, ch, ch.getStreamResponse(task, "1234567890", "nonce"))
+
+ if !resp.Stream.Finish {
+ t.Fatal("Expected finished stream response after deadline")
+ }
+ if resp.Stream.Content != config.DefaultWeComAIBotProcessingMessage {
+ t.Fatalf("Expected default processing message %q, got %q",
+ config.DefaultWeComAIBotProcessingMessage, resp.Stream.Content)
+ }
+ if !task.StreamClosed {
+ t.Fatal("Expected task stream to be marked closed")
+ }
+ if _, ok := ch.streamTasks[task.StreamID]; ok {
+ t.Fatal("Expected closed stream task to be removed from streamTasks")
+ }
+ if len(ch.chatTasks[task.ChatID]) != 1 {
+ t.Fatalf("Expected task to remain queued for response_url delivery, got %d entries",
+ len(ch.chatTasks[task.ChatID]))
+ }
+ })
+
+ t.Run("uses custom processing message", func(t *testing.T) {
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ ProcessingMessage: "Please wait a moment. The result will be delivered in a follow-up message.",
+ }
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey(validAESKey)
+
+ messageBus := bus.NewMessageBus()
+ channel, err := NewWeComAIBotChannel(cfg, messageBus)
+ if err != nil {
+ t.Fatalf("Failed to create channel: %v", err)
+ }
+ ch, ok := channel.(*WeComAIBotChannel)
+ if !ok {
+ t.Fatal("Expected webhook mode channel")
+ }
+
+ task := &streamTask{
+ StreamID: "stream-custom",
+ ChatID: "chat-custom",
+ Deadline: time.Now().Add(-time.Second),
+ }
+
+ resp := decodeStreamResponse(t, ch, ch.getStreamResponse(task, "1234567890", "nonce"))
+
+ if resp.Stream.Content != cfg.ProcessingMessage {
+ t.Fatalf("Expected custom processing message %q, got %q", cfg.ProcessingMessage, resp.Stream.Content)
+ }
+ })
+}
+
func TestGenerateStreamID(t *testing.T) {
- cfg := config.WeComAIBotConfig{
- Enabled: true,
- Token: "test_token",
- EncodingAESKey: "testkey1234567890123456789012345678901234567",
- }
+ cfg := config.WeComAIBotConfig{}
+ cfg.Enabled = true
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey("testkey1234567890123456789012345678901234567")
+
messageBus := bus.NewMessageBus()
ch, _ := NewWeComAIBotChannel(cfg, messageBus)
webhookCh, ok := ch.(*WeComAIBotChannel)
@@ -161,11 +242,12 @@ func TestGenerateStreamID(t *testing.T) {
}
func TestEncryptDecrypt(t *testing.T) {
- cfg := config.WeComAIBotConfig{
- Enabled: true,
- Token: "test_token",
- EncodingAESKey: "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG", // 43 characters
- }
+ // Use a valid 43-character base64 key (企业微信标准格式)
+ cfg := config.WeComAIBotConfig{}
+ cfg.Enabled = true
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey("abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG") // 43 characters
+
messageBus := bus.NewMessageBus()
ch, _ := NewWeComAIBotChannel(cfg, messageBus)
webhookCh, ok := ch.(*WeComAIBotChannel)
@@ -184,7 +266,8 @@ func TestEncryptDecrypt(t *testing.T) {
t.Fatal("Encrypted message is empty")
}
- decrypted, err := decryptMessageWithVerify(encrypted, cfg.EncodingAESKey, receiveid)
+ // Decrypt
+ decrypted, err := decryptMessageWithVerify(encrypted, cfg.EncodingAESKey(), receiveid)
if err != nil {
t.Fatalf("Failed to decrypt message: %v", err)
}
@@ -208,6 +291,27 @@ func TestGenerateSignature(t *testing.T) {
}
}
+func decodeStreamResponse(t *testing.T, ch *WeComAIBotChannel, encryptedResponse string) WeComAIBotStreamResponse {
+ t.Helper()
+
+ var wrapped WeComAIBotEncryptedResponse
+ if err := json.Unmarshal([]byte(encryptedResponse), &wrapped); err != nil {
+ t.Fatalf("Failed to unmarshal encrypted response: %v", err)
+ }
+
+ plaintext, err := decryptMessageWithVerify(wrapped.Encrypt, ch.config.EncodingAESKey(), "")
+ if err != nil {
+ t.Fatalf("Failed to decrypt response: %v", err)
+ }
+
+ var resp WeComAIBotStreamResponse
+ if err := json.Unmarshal([]byte(plaintext), &resp); err != nil {
+ t.Fatalf("Failed to unmarshal decrypted response: %v", err)
+ }
+
+ return resp
+}
+
// ---- WebSocket long-connection mode tests ----
func TestNewWeComAIBotChannel_WSMode(t *testing.T) {
@@ -215,8 +319,8 @@ func TestNewWeComAIBotChannel_WSMode(t *testing.T) {
cfg := config.WeComAIBotConfig{
Enabled: true,
BotID: "test_bot_id",
- Secret: "test_secret",
}
+ cfg.SetSecret("test_secret")
messageBus := bus.NewMessageBus()
ch, err := NewWeComAIBotChannel(cfg, messageBus)
if err != nil {
@@ -236,27 +340,27 @@ func TestNewWeComAIBotChannel_WSMode(t *testing.T) {
t.Run("ws mode takes priority over webhook fields", func(t *testing.T) {
cfg := config.WeComAIBotConfig{
- Enabled: true,
- BotID: "test_bot_id",
- Secret: "test_secret",
- Token: "also_set",
- EncodingAESKey: "testkey1234567890123456789012345678901234567",
+ Enabled: true,
+ BotID: "test_bot_id",
}
+ cfg.SetSecret("test_secret")
+ cfg.SetToken("also_set")
+ cfg.SetEncodingAESKey("testkey1234567890123456789012345678901234567")
messageBus := bus.NewMessageBus()
ch, err := NewWeComAIBotChannel(cfg, messageBus)
if err != nil {
t.Fatalf("Expected no error, got %v", err)
}
if _, ok := ch.(*WeComAIBotWSChannel); !ok {
- t.Error("Expected WebSocket mode channel when both BotID+Secret and Token+Key are set")
+ t.Error("Expected WebSocket mode channel when both BotID+secret and Token+Key are set")
}
})
t.Run("error with missing bot_id", func(t *testing.T) {
cfg := config.WeComAIBotConfig{
Enabled: true,
- Secret: "test_secret",
}
+ cfg.SetSecret("test_secret")
messageBus := bus.NewMessageBus()
_, err := NewWeComAIBotChannel(cfg, messageBus)
// Missing bot_id alone means neither WS mode nor webhook mode is fully configured.
@@ -282,8 +386,8 @@ func TestWeComAIBotWSChannelStartStop(t *testing.T) {
cfg := config.WeComAIBotConfig{
Enabled: true,
BotID: "test_bot_id",
- Secret: "test_secret",
}
+ cfg.SetSecret("test_secret")
messageBus := bus.NewMessageBus()
ch, err := NewWeComAIBotChannel(cfg, messageBus)
if err != nil {
@@ -343,10 +447,10 @@ func TestWSGenerateID(t *testing.T) {
func makeWebhookChannel(t *testing.T) *WeComAIBotChannel {
t.Helper()
cfg := config.WeComAIBotConfig{
- Enabled: true,
- Token: "test_token",
- EncodingAESKey: "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG",
+ Enabled: true,
}
+ cfg.SetToken("test_token")
+ cfg.SetEncodingAESKey("abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG")
ch, err := NewWeComAIBotChannel(cfg, bus.NewMessageBus())
if err != nil {
t.Fatalf("create channel: %v", err)
diff --git a/pkg/channels/wecom/aibot_ws.go b/pkg/channels/wecom/aibot_ws.go
index 830e763b9..53dd7071f 100644
--- a/pkg/channels/wecom/aibot_ws.go
+++ b/pkg/channels/wecom/aibot_ws.go
@@ -225,7 +225,7 @@ func newWeComAIBotWSChannel(
cfg config.WeComAIBotConfig,
messageBus *bus.MessageBus,
) (*WeComAIBotWSChannel, error) {
- if cfg.BotID == "" || cfg.Secret == "" {
+ if cfg.BotID == "" || cfg.Secret() == "" {
return nil, fmt.Errorf("bot_id and secret are required for WeCom AI Bot WebSocket mode")
}
@@ -433,7 +433,7 @@ func (c *WeComAIBotWSChannel) runConnection() error {
Headers: wsHeaders{ReqID: reqID},
Body: map[string]string{
"bot_id": c.config.BotID,
- "secret": c.config.Secret,
+ "secret": c.config.Secret(),
},
}, wsSubscribeTimeout)
if err != nil {
@@ -1218,8 +1218,9 @@ func (c *WeComAIBotWSChannel) storeWSMedia(
scope := channels.BuildMediaScope("wecom_aibot", chatID, msgID)
ref, err := store.Store(tmpPath, media.MediaMeta{
- Filename: msgID + ext,
- Source: "wecom_aibot",
+ Filename: msgID + ext,
+ Source: "wecom_aibot",
+ CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
}, scope)
if err != nil {
os.Remove(tmpPath)
diff --git a/pkg/channels/wecom/aibot_ws_test.go b/pkg/channels/wecom/aibot_ws_test.go
index 0a533da5d..f2f8833a1 100644
--- a/pkg/channels/wecom/aibot_ws_test.go
+++ b/pkg/channels/wecom/aibot_ws_test.go
@@ -21,8 +21,8 @@ func newTestWSChannel(t *testing.T) *WeComAIBotWSChannel {
cfg := config.WeComAIBotConfig{
Enabled: true,
BotID: "test_bot_id",
- Secret: "test_secret",
}
+ cfg.SetSecret("test_secret")
ch, err := newWeComAIBotWSChannel(cfg, bus.NewMessageBus())
if err != nil {
t.Fatalf("create WS channel: %v", err)
diff --git a/pkg/channels/wecom/app.go b/pkg/channels/wecom/app.go
index 2098fcd4e..fccfc60a3 100644
--- a/pkg/channels/wecom/app.go
+++ b/pkg/channels/wecom/app.go
@@ -119,7 +119,7 @@ type PKCS7Padding struct{}
// NewWeComAppChannel creates a new WeCom App channel instance
func NewWeComAppChannel(cfg config.WeComAppConfig, messageBus *bus.MessageBus) (*WeComAppChannel, error) {
- if cfg.CorpID == "" || cfg.CorpSecret == "" || cfg.AgentID == 0 {
+ if cfg.CorpID == "" || cfg.CorpSecret() == "" || cfg.AgentID == 0 {
return nil, fmt.Errorf("wecom_app corp_id, corp_secret and agent_id are required")
}
@@ -497,9 +497,9 @@ func (c *WeComAppChannel) handleVerification(ctx context.Context, w http.Respons
}
// Verify signature
- if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
+ if !verifySignature(c.config.Token(), msgSignature, timestamp, nonce, echostr) {
logger.WarnCF("wecom_app", "Signature verification failed", map[string]any{
- "token": c.config.Token,
+ "token": c.config.Token(),
"msg_signature": msgSignature,
"timestamp": timestamp,
"nonce": nonce,
@@ -513,10 +513,10 @@ func (c *WeComAppChannel) handleVerification(ctx context.Context, w http.Respons
// Decrypt echostr with CorpID verification
// For WeCom App (自建应用), receiveid should be corp_id
logger.DebugCF("wecom_app", "Attempting to decrypt echostr", map[string]any{
- "encoding_aes_key": c.config.EncodingAESKey,
+ "encoding_aes_key": c.config.EncodingAESKey(),
"corp_id": c.config.CorpID,
})
- decryptedEchoStr, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey, c.config.CorpID)
+ decryptedEchoStr, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey(), c.config.CorpID)
if err != nil {
logger.ErrorCF("wecom_app", "Failed to decrypt echostr", map[string]any{
"error": err.Error(),
@@ -575,7 +575,7 @@ func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.Resp
}
// Verify signature
- if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
+ if !verifySignature(c.config.Token(), msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
logger.WarnC("wecom_app", "Message signature verification failed")
http.Error(w, "Invalid signature", http.StatusForbidden)
return
@@ -583,7 +583,7 @@ func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.Resp
// Decrypt message with CorpID verification
// For WeCom App (自建应用), receiveid should be corp_id
- decryptedMsg, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, c.config.CorpID)
+ decryptedMsg, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey(), c.config.CorpID)
if err != nil {
logger.ErrorCF("wecom_app", "Failed to decrypt message", map[string]any{
"error": err.Error(),
@@ -689,7 +689,7 @@ func (c *WeComAppChannel) tokenRefreshLoop() {
// refreshAccessToken gets a new access token from WeCom API
func (c *WeComAppChannel) refreshAccessToken() error {
apiURL := fmt.Sprintf("%s/cgi-bin/gettoken?corpid=%s&corpsecret=%s",
- wecomAPIBase, url.QueryEscape(c.config.CorpID), url.QueryEscape(c.config.CorpSecret))
+ wecomAPIBase, url.QueryEscape(c.config.CorpID), url.QueryEscape(c.config.CorpSecret()))
resp, err := http.Get(apiURL)
if err != nil {
diff --git a/pkg/channels/wecom/app_test.go b/pkg/channels/wecom/app_test.go
index 7d07041ad..502544441 100644
--- a/pkg/channels/wecom/app_test.go
+++ b/pkg/channels/wecom/app_test.go
@@ -91,10 +91,10 @@ func TestNewWeComAppChannel(t *testing.T) {
t.Run("missing corp_id", func(t *testing.T) {
cfg := config.WeComAppConfig{
- CorpID: "",
- CorpSecret: "test_secret",
- AgentID: 1000002,
+ CorpID: "",
+ AgentID: 1000002,
}
+ cfg.SetCorpSecret("test_secret")
_, err := NewWeComAppChannel(cfg, msgBus)
if err == nil {
t.Error("expected error for missing corp_id, got nil")
@@ -103,9 +103,8 @@ func TestNewWeComAppChannel(t *testing.T) {
t.Run("missing corp_secret", func(t *testing.T) {
cfg := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "",
- AgentID: 1000002,
+ CorpID: "test_corp_id",
+ AgentID: 1000002,
}
_, err := NewWeComAppChannel(cfg, msgBus)
if err == nil {
@@ -115,10 +114,10 @@ func TestNewWeComAppChannel(t *testing.T) {
t.Run("missing agent_id", func(t *testing.T) {
cfg := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "test_secret",
- AgentID: 0,
+ CorpID: "test_corp_id",
+ AgentID: 0,
}
+ cfg.SetCorpSecret("test_secret")
_, err := NewWeComAppChannel(cfg, msgBus)
if err == nil {
t.Error("expected error for missing agent_id, got nil")
@@ -127,11 +126,11 @@ func TestNewWeComAppChannel(t *testing.T) {
t.Run("valid config", func(t *testing.T) {
cfg := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "test_secret",
- AgentID: 1000002,
- AllowFrom: []string{"user1", "user2"},
+ CorpID: "test_corp_id",
+ AgentID: 1000002,
+ AllowFrom: []string{"user1", "user2"},
}
+ cfg.SetCorpSecret("test_secret")
ch, err := NewWeComAppChannel(cfg, msgBus)
if err != nil {
t.Fatalf("unexpected error: %v", err)
@@ -150,11 +149,11 @@ func TestWeComAppChannelIsAllowed(t *testing.T) {
t.Run("empty allowlist allows all", func(t *testing.T) {
cfg := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "test_secret",
- AgentID: 1000002,
- AllowFrom: []string{},
+ CorpID: "test_corp_id",
+ AgentID: 1000002,
+ AllowFrom: []string{},
}
+ cfg.SetCorpSecret("test_secret")
ch, _ := NewWeComAppChannel(cfg, msgBus)
if !ch.IsAllowed("any_user") {
t.Error("empty allowlist should allow all users")
@@ -163,11 +162,11 @@ func TestWeComAppChannelIsAllowed(t *testing.T) {
t.Run("allowlist restricts users", func(t *testing.T) {
cfg := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "test_secret",
- AgentID: 1000002,
- AllowFrom: []string{"allowed_user"},
+ CorpID: "test_corp_id",
+ AgentID: 1000002,
+ AllowFrom: []string{"allowed_user"},
}
+ cfg.SetCorpSecret("test_secret")
ch, _ := NewWeComAppChannel(cfg, msgBus)
if !ch.IsAllowed("allowed_user") {
t.Error("allowed user should pass allowlist check")
@@ -180,12 +179,11 @@ func TestWeComAppChannelIsAllowed(t *testing.T) {
func TestWeComAppVerifySignature(t *testing.T) {
msgBus := bus.NewMessageBus()
- cfg := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "test_secret",
- AgentID: 1000002,
- Token: "test_token",
- }
+ cfg := config.WeComAppConfig{}
+ cfg.CorpID = "test_corp_id"
+ cfg.SetCorpSecret("test_secret")
+ cfg.AgentID = 1000002
+ cfg.SetToken("test_token")
ch, _ := NewWeComAppChannel(cfg, msgBus)
t.Run("valid signature", func(t *testing.T) {
@@ -194,7 +192,7 @@ func TestWeComAppVerifySignature(t *testing.T) {
msgEncrypt := "test_message"
expectedSig := generateSignatureApp("test_token", timestamp, nonce, msgEncrypt)
- if !verifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
+ if !verifySignature(ch.config.Token(), expectedSig, timestamp, nonce, msgEncrypt) {
t.Error("valid signature should pass verification")
}
})
@@ -204,21 +202,20 @@ func TestWeComAppVerifySignature(t *testing.T) {
nonce := "test_nonce"
msgEncrypt := "test_message"
- if verifySignature(ch.config.Token, "invalid_sig", timestamp, nonce, msgEncrypt) {
+ if verifySignature(ch.config.Token(), "invalid_sig", timestamp, nonce, msgEncrypt) {
t.Error("invalid signature should fail verification")
}
})
t.Run("empty token rejects verification (fail-closed)", func(t *testing.T) {
- cfgEmpty := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "test_secret",
- AgentID: 1000002,
- Token: "",
- }
+ cfgEmpty := config.WeComAppConfig{}
+ cfgEmpty.CorpID = "test_corp_id"
+ cfgEmpty.SetCorpSecret("test_secret")
+ cfgEmpty.AgentID = 1000002
+ cfgEmpty.SetToken("")
chEmpty, _ := NewWeComAppChannel(cfgEmpty, msgBus)
- if verifySignature(chEmpty.config.Token, "any_sig", "any_ts", "any_nonce", "any_msg") {
+ if verifySignature(chEmpty.config.Token(), "any_sig", "any_ts", "any_nonce", "any_msg") {
t.Error("empty token should reject verification (fail-closed)")
}
})
@@ -228,19 +225,18 @@ func TestWeComAppDecryptMessage(t *testing.T) {
msgBus := bus.NewMessageBus()
t.Run("decrypt without AES key", func(t *testing.T) {
- cfg := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "test_secret",
- AgentID: 1000002,
- EncodingAESKey: "",
- }
+ cfg := config.WeComAppConfig{}
+ cfg.CorpID = "test_corp_id"
+ cfg.SetCorpSecret("test_secret")
+ cfg.AgentID = 1000002
+ cfg.SetEncodingAESKey("")
ch, _ := NewWeComAppChannel(cfg, msgBus)
// Without AES key, message should be base64 decoded only
plainText := "hello world"
encoded := base64.StdEncoding.EncodeToString([]byte(plainText))
- result, err := decryptMessage(encoded, ch.config.EncodingAESKey)
+ result, err := decryptMessage(encoded, ch.config.EncodingAESKey())
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -252,11 +248,11 @@ func TestWeComAppDecryptMessage(t *testing.T) {
t.Run("decrypt with AES key", func(t *testing.T) {
aesKey := generateTestAESKeyApp()
cfg := config.WeComAppConfig{
- CorpID: "test_corp_id",
- CorpSecret: "test_secret",
- AgentID: 1000002,
- EncodingAESKey: aesKey,
+ CorpID: "test_corp_id",
+ AgentID: 1000002,
}
+ cfg.SetCorpSecret("test_secret")
+ cfg.SetEncodingAESKey(aesKey)
ch, _ := NewWeComAppChannel(cfg, msgBus)
originalMsg := "Hello Hello ") {
+ if !strings.Contains(reply, "/use [message]") {
+ t.Fatalf("/help reply missing /use usage, got %q", reply)
+ }
+ }
}
func TestBuiltinShowChannel_PreservesUserVisibleBehavior(t *testing.T) {
@@ -143,3 +148,43 @@ func TestBuiltinListAgents_RestoresOldBehavior(t *testing.T) {
t.Fatalf("/list agents reply=%q, want agent IDs", reply)
}
}
+
+func TestBuiltinListSkills_UsesRuntimeSkillNames(t *testing.T) {
+ rt := &Runtime{
+ ListSkillNames: func() []string {
+ return []string{"shell", "git"}
+ },
+ }
+ defs := BuiltinDefinitions()
+ ex := NewExecutor(NewRegistry(defs), rt)
+
+ var reply string
+ res := ex.Execute(context.Background(), Request{
+ Text: "/list skills",
+ Reply: func(text string) error {
+ reply = text
+ return nil
+ },
+ })
+ if res.Outcome != OutcomeHandled {
+ t.Fatalf("/list skills: outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+ }
+ if !strings.Contains(reply, "shell") || !strings.Contains(reply, "git") {
+ t.Fatalf("/list skills reply=%q, want installed skill names", reply)
+ }
+}
+
+func TestBuiltinUseCommand_PassthroughsToAgentLogic(t *testing.T) {
+ defs := BuiltinDefinitions()
+ ex := NewExecutor(NewRegistry(defs), nil)
+
+ res := ex.Execute(context.Background(), Request{
+ Text: "/use shell run ls",
+ })
+ if res.Outcome != OutcomePassthrough {
+ t.Fatalf("/use outcome=%v, want=%v", res.Outcome, OutcomePassthrough)
+ }
+ if res.Command != "use" {
+ t.Fatalf("/use command=%q, want=%q", res.Command, "use")
+ }
+}
diff --git a/pkg/commands/cmd_list.go b/pkg/commands/cmd_list.go
index bf47b6e9c..7186a6c25 100644
--- a/pkg/commands/cmd_list.go
+++ b/pkg/commands/cmd_list.go
@@ -47,6 +47,23 @@ func listCommand() Definition {
Description: "Registered agents",
Handler: agentsHandler(),
},
+ {
+ Name: "skills",
+ Description: "Installed skills",
+ Handler: func(_ context.Context, req Request, rt *Runtime) error {
+ if rt == nil || rt.ListSkillNames == nil {
+ return req.Reply(unavailableMsg)
+ }
+ names := rt.ListSkillNames()
+ if len(names) == 0 {
+ return req.Reply("No installed skills")
+ }
+ return req.Reply(fmt.Sprintf(
+ "Installed Skills:\n- %s\n\nUse /use to force one for a single request, or /use to apply it to your next message.",
+ strings.Join(names, "\n- "),
+ ))
+ },
+ },
},
}
}
diff --git a/pkg/commands/cmd_subagents.go b/pkg/commands/cmd_subagents.go
new file mode 100644
index 000000000..29321823c
--- /dev/null
+++ b/pkg/commands/cmd_subagents.go
@@ -0,0 +1,42 @@
+package commands
+
+import (
+ "context"
+ "fmt"
+)
+
+// TurnInfo is a mirrored struct from agent.TurnInfo to avoid circular dependencies.
+type TurnInfo struct {
+ TurnID string
+ ParentTurnID string
+ Depth int
+ ChildTurnIDs []string
+ IsFinished bool
+}
+
+func subagentsCommand() Definition {
+ return Definition{
+ Name: "subagents",
+ Description: "Show running subagents and task tree",
+ Handler: func(ctx context.Context, req Request, rt *Runtime) error {
+ getTurnFn := rt.GetActiveTurn
+ if getTurnFn == nil {
+ return req.Reply("Runtime does not support querying active turns.")
+ }
+
+ turnRaw := getTurnFn()
+ if turnRaw == nil {
+ return req.Reply("No active tasks running in this session.")
+ }
+
+ if treeStr, ok := turnRaw.(string); ok {
+ if treeStr == "" {
+ return req.Reply("No active tasks running in this session.")
+ }
+ return req.Reply(fmt.Sprintf("🤖 **Active Subagents Tree**\n```text\n%s\n```", treeStr))
+ }
+
+ return req.Reply(fmt.Sprintf("🤖 **Active Subagents List**\n```text\n%+v\n```", turnRaw))
+ },
+ }
+}
diff --git a/pkg/commands/cmd_use.go b/pkg/commands/cmd_use.go
new file mode 100644
index 000000000..4698f5f5e
--- /dev/null
+++ b/pkg/commands/cmd_use.go
@@ -0,0 +1,9 @@
+package commands
+
+func useCommand() Definition {
+ return Definition{
+ Name: "use",
+ Description: "Force a specific installed skill for one request",
+ Usage: "/use [message]",
+ }
+}
diff --git a/pkg/commands/request.go b/pkg/commands/request.go
index 62ee600f2..233b3ef9c 100644
--- a/pkg/commands/request.go
+++ b/pkg/commands/request.go
@@ -41,6 +41,11 @@ func parseCommandName(input string) (string, bool) {
return name, true
}
+// CommandName returns the normalized command name for an input if present.
+func CommandName(input string) (string, bool) {
+ return parseCommandName(input)
+}
+
func trimCommandPrefix(token string) (string, bool) {
for _, prefix := range commandPrefixes {
if strings.HasPrefix(token, prefix) {
diff --git a/pkg/commands/runtime.go b/pkg/commands/runtime.go
index 84f775808..5ba6a1bd2 100644
--- a/pkg/commands/runtime.go
+++ b/pkg/commands/runtime.go
@@ -10,7 +10,9 @@ type Runtime struct {
GetModelInfo func() (name, provider string)
ListAgentIDs func() []string
ListDefinitions func() []Definition
+ ListSkillNames func() []string
GetEnabledChannels func() []string
+ GetActiveTurn func() any // Returning any to avoid circular dependency with agent package
SwitchModel func(value string) (oldModel string, err error)
SwitchChannel func(value string) error
ClearHistory func() error
diff --git a/pkg/commands/show_list_handlers_test.go b/pkg/commands/show_list_handlers_test.go
index 047708f0f..28d481b67 100644
--- a/pkg/commands/show_list_handlers_test.go
+++ b/pkg/commands/show_list_handlers_test.go
@@ -61,6 +61,9 @@ func TestShowListHandlers_ListHandledOnAllChannels(t *testing.T) {
GetEnabledChannels: func() []string {
return []string{"telegram"}
},
+ ListSkillNames: func() []string {
+ return []string{"shell"}
+ },
}
ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
@@ -82,4 +85,20 @@ func TestShowListHandlers_ListHandledOnAllChannels(t *testing.T) {
if !strings.Contains(reply, "telegram") {
t.Fatalf("whatsapp /list reply=%q, expected enabled channels content", reply)
}
+
+ reply = ""
+ res = ex.Execute(context.Background(), Request{
+ Channel: "whatsapp",
+ Text: "/list skills",
+ Reply: func(text string) error {
+ reply = text
+ return nil
+ },
+ })
+ if res.Outcome != OutcomeHandled {
+ t.Fatalf("whatsapp /list skills outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+ }
+ if !strings.Contains(reply, "shell") {
+ t.Fatalf("whatsapp /list skills reply=%q, expected installed skills content", reply)
+ }
}
diff --git a/pkg/config/SECURITY_CONFIG.md b/pkg/config/SECURITY_CONFIG.md
new file mode 100644
index 000000000..c5aed54ae
--- /dev/null
+++ b/pkg/config/SECURITY_CONFIG.md
@@ -0,0 +1,551 @@
+# Security Configuration Refactoring
+
+## Overview
+
+This refactoring introduces a `.security.yml` file to store all sensitive data (API keys, tokens, secrets, passwords) separately from the main configuration. This improves security by:
+
+1. **Separation of concerns**: Configuration settings and secrets are in separate files
+2. **Easier sharing**: The main config can be shared without exposing sensitive data
+3. **Better version control**: `.security.yml` can be added to `.gitignore`
+4. **Flexible deployment**: Different environments can use different security files
+
+## File Structure
+
+```
+~/.picoclaw/
+├── config.json # Main configuration (safe to share)
+└── .security.yml # Security data (never share)
+```
+
+## Usage
+
+### Basic Configuration
+
+In your `config.json`, use `ref:` references to point to values in `.security.yml`:
+
+```json
+{
+ "version": 1,
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_base": "https://api.openai.com/v1",
+ "api_key": "ref:model_list.gpt-5.4.api_key"
+ }
+ ],
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "ref:channels.telegram.token"
+ }
+ }
+}
+```
+
+### Security Configuration
+
+In your `.security.yml`, store the actual values:
+
+```yaml
+model_list:
+ gpt-5.4:
+ api_keys:
+ - "sk-your-actual-api-key-1"
+ - "sk-your-actual-api-key-2" # Optional: Multiple keys for failover
+ claude-sonnet-4.6:
+ api_keys:
+ - "sk-your-actual-anthropic-key" # Single key in array format
+
+channels:
+ telegram:
+ token: "your-telegram-bot-token"
+
+web:
+ brave:
+ api_keys:
+ - "BSAyour-brave-api-key-1"
+ - "BSAyour-brave-api-key-2" # Optional: Multiple keys for failover
+ tavily:
+ api_keys:
+ - "tvly-your-tavily-api-key" # Single key in array format
+ glm_search:
+ api_key: "your-glm-search-api-key" # GLMSearch uses single key format
+```
+
+## Reference Format
+
+### Model API Keys
+
+Format: `ref:model_list..api_key`
+
+Example: `ref:model_list.gpt-5.4.api_key`
+
+### Channel Tokens/Secrets
+
+Format: `ref:channels..`
+
+Examples:
+- `ref:channels.telegram.token`
+- `ref:channels.feishu.app_secret`
+- `ref:channels.feishu.encrypt_key`
+- `ref:channels.feishu.verification_token`
+- `ref:channels.discord.token`
+- `ref:channels.qq.app_secret`
+- `ref:channels.dingtalk.client_secret`
+- `ref:channels.slack.bot_token`
+- `ref:channels.slack.app_token`
+- `ref:channels.matrix.access_token`
+- `ref:channels.line.channel_secret`
+- `ref:channels.line.channel_access_token`
+- `ref:channels.onebot.access_token`
+- `ref:channels.wecom.token`
+- `ref:channels.wecom.encoding_aes_key`
+- `ref:channels.wecom_app.corp_secret`
+- `ref:channels.wecom_app.token`
+- `ref:channels.wecom_app.encoding_aes_key`
+- `ref:channels.wecom_aibot.token`
+- `ref:channels.wecom_aibot.encoding_aes_key`
+- `ref:channels.pico.token`
+- `ref:channels.irc.password`
+- `ref:channels.irc.nickserv_password`
+- `ref:channels.irc.sasl_password`
+
+### Web Tool API Keys
+
+Format: `ref:web..`
+
+Examples:
+- `ref:web.brave.api_key`
+- `ref:web.tavily.api_key`
+- `ref:web.perplexity.api_key`
+- `ref:web.glm_search.api_key`
+
+### Skills Registry Tokens
+
+Format: `ref:skills..`
+
+Examples:
+- `ref:skills.github.token`
+- `ref:skills.clawhub.auth_token`
+
+## Backward Compatibility
+
+The refactoring maintains full backward compatibility:
+
+1. **Direct values**: You can still use direct values in `config.json` (not recommended for production)
+2. **Mixed usage**: You can mix `ref:` references and direct values
+3. **Optional security file**: If `.security.yml` doesn't exist, all references will fail (but direct values still work)
+
+### API Key Formats in .security.yml
+
+**Models (gpt-5.4, claude-sonnet-4.6, etc.):**
+- Must use `api_keys` (array) format
+- Both single and multiple keys use array format
+
+**Web Tools (Brave, Tavily, Perplexity):**
+- Must use `api_keys` (array) format
+- Both single and multiple keys use array format
+
+**Web Tools (GLMSearch):**
+- Must use `api_key` (single string) format
+- Does NOT support array format
+
+**Channels (Telegram, Discord, etc.):**
+- Use single field names (e.g., `token`, `app_secret`)
+- Each channel uses its specific field names
+
+### Single Key (Models)
+
+Use array format with one element:
+```yaml
+model_list:
+ gpt-5.4:
+ api_keys:
+ - "sk-your-key"
+```
+
+In `config.json`:
+```json
+{
+ "api_key": "ref:model_list.gpt-5.4.api_key"
+}
+```
+
+### Single Key (GLMSearch)
+
+Use single string format:
+```yaml
+web:
+ glm_search:
+ api_key: "your-glm-key"
+```
+
+In `config.json`:
+```json
+{
+ "api_key": "ref:web.glm_search.api_key"
+}
+```
+
+## Migration Guide
+
+### Step 1: Create .security.yml
+
+Copy the example template:
+```bash
+cp security.example.yml ~/.picoclaw/.security.yml
+```
+
+### Step 2: Fill in your actual values
+
+Edit `~/.picoclaw/.security.yml` and replace placeholder values with your actual API keys and tokens.
+
+### Step 3: Update config.json
+
+Replace sensitive values in `~/.picoclaw/config.json` with `ref:` references:
+
+**Before:**
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_key": "sk-your-actual-api-key-here"
+ }
+ ]
+}
+```
+
+**After:**
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_key": "ref:model_list.gpt-5.4.api_key"
+ }
+ ]
+}
+```
+
+### Step 4: Verify
+
+Restart PicoClaw and verify it loads correctly:
+```bash
+picoclaw --version
+```
+
+## Security Best Practices
+
+1. **Never commit `.security.yml`** to version control
+2. **Set file permissions**: `chmod 600 ~/.picoclaw/.security.yml`
+3. **Use different keys** for different environments (dev, staging, production)
+4. **Rotate keys regularly** and update `.security.yml`
+5. **Backup securely**: Encrypt backups containing `.security.yml`
+
+## API
+
+### LoadSecurityConfig
+
+```go
+func LoadSecurityConfig(securityPath string) (*SecurityConfig, error)
+```
+
+Loads the security configuration from `.security.yml`. Returns an empty `SecurityConfig` if the file doesn't exist.
+
+### SaveSecurityConfig
+
+```go
+func SaveSecurityConfig(securityPath string, sec *SecurityConfig) error
+```
+
+Saves the security configuration to `.security.yml` with `0o600` permissions.
+
+### ResolveReference
+
+```go
+func (sec *SecurityConfig) ResolveReference(ref string) (string, error)
+```
+
+Resolves a reference string (e.g., `"ref:model_list.test.api_key"`) and returns the actual value.
+
+### SecurityPath
+
+```go
+func SecurityPath(configPath string) string
+```
+
+Returns the path to `.security.yml` relative to the config file.
+
+## Example: Complete Configuration
+
+### config.json
+```json
+{
+ "version": 1,
+ "agents": {
+ "defaults": {
+ "workspace": "~/picoclaw-workspace",
+ "model_name": "gpt-5.4"
+ }
+ },
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_base": "https://api.openai.com/v1",
+ "api_key": "ref:model_list.gpt-5.4.api_key"
+ },
+ {
+ "model_name": "claude-sonnet-4.6",
+ "model": "anthropic/claude-sonnet-4.6",
+ "api_base": "https://api.anthropic.com/v1",
+ "api_key": "ref:model_list.claude-sonnet-4.6.api_key"
+ }
+ ],
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "ref:channels.telegram.token"
+ }
+ },
+ "tools": {
+ "web": {
+ "brave": {
+ "enabled": true,
+ "api_key": "ref:web.brave.api_key"
+ }
+ }
+ }
+}
+```
+
+### .security.yml
+```yaml
+model_list:
+ gpt-5.4:
+ api_keys:
+ - "sk-proj-actual-openai-key-1"
+ - "sk-proj-actual-openai-key-2"
+ claude-sonnet-4.6:
+ api_keys:
+ - "sk-ant-actual-anthropic-key" # Single key in array format
+
+channels:
+ telegram:
+ token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
+
+web:
+ brave:
+ api_keys:
+ - "BSAactualbravekey-1"
+ - "BSAactualbravekey-2"
+ tavily:
+ api_keys:
+ - "tvly-your-tavily-key" # Single key in array format
+ glm_search:
+ api_key: "your-glm-key" # GLMSearch uses single key format
+```
+
+## Testing
+
+The refactoring includes comprehensive tests:
+
+```bash
+go test ./pkg/config -run TestSecurityConfig
+```
+
+## Troubleshooting
+
+### Error: "model security entry not found"
+
+- Ensure the model name in your reference matches exactly in `.security.yml`
+- Check that the `model_list` section exists in `.security.yml`
+- For models with indexed names (e.g., "gpt-5.4:0"), ensure the exact name is used or check the base name without index
+
+### Error: "failed to load security config"
+
+- Verify `.security.yml` exists in the same directory as `config.json`
+- Check the YAML syntax is valid (use a YAML validator)
+- Ensure file permissions allow reading
+
+### Error: "unknown reference path"
+
+- Verify the reference format is correct
+- Check the path structure matches the examples above
+- Ensure all required sections exist in `.security.yml`
+
+## Advanced Features
+
+### Multiple API Keys (Load Balancing & Failover)
+
+Both models and web tools support multiple API keys for improved reliability:
+
+**Benefits:**
+- **Load balancing**: Requests are distributed across multiple keys
+- **Failover**: Automatic switching to another key if one fails
+- **Rate limit management**: Distribute usage across multiple keys
+- **High availability**: Reduce downtime during API provider issues
+
+#### Example: Model with Multiple Keys
+
+**.security.yml:**
+```yaml
+model_list:
+ gpt-5.4:
+ api_keys:
+ - "sk-proj-key-1"
+ - "sk-proj-key-2"
+ - "sk-proj-key-3"
+```
+
+**config.json:**
+```json
+{
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_key": "ref:model_list.gpt-5.4.api_key"
+ }
+ ]
+}
+```
+
+#### Example: Web Tool with Multiple Keys
+
+**.security.yml:**
+```yaml
+web:
+ brave:
+ api_keys:
+ - "BSA-key-1"
+ - "BSA-key-2"
+ tavily:
+ api_keys:
+ - "tvly-your-key" # Single key in array format
+ glm_search:
+ api_key: "your-glm-key" # GLMSearch uses single key format
+```
+
+**config.json:**
+```json
+{
+ "tools": {
+ "web": {
+ "brave": {
+ "enabled": true,
+ "api_key": "ref:web.brave.api_key"
+ },
+ "tavily": {
+ "enabled": true,
+ "api_key": "ref:web.tavily.api_key"
+ }
+ }
+ }
+}
+```
+
+#### Supported Formats
+
+**Models - Single key:**
+```yaml
+model_list:
+ gpt-5.4:
+ api_keys:
+ - "sk-your-key" # Array with one element
+```
+
+**Models - Multiple keys:**
+```yaml
+model_list:
+ gpt-5.4:
+ api_keys:
+ - "sk-your-key-1"
+ - "sk-your-key-2"
+ - "sk-your-key-3"
+```
+
+**Web Tools (Brave/Tavily/Perplexity) - Single key:**
+```yaml
+web:
+ brave:
+ api_keys:
+ - "BSA-your-key" # Array with one element
+```
+
+**Web Tools (Brave/Tavily/Perplexity) - Multiple keys:**
+```yaml
+web:
+ brave:
+ api_keys:
+ - "BSA-key-1"
+ - "BSA-key-2"
+```
+
+**Web Tool (GLMSearch) - Single key only:**
+```yaml
+web:
+ glm_search:
+ api_key: "your-glm-key" # Single string (NOT array)
+```
+
+All formats work identically in `config.json` - you always use the same reference format:
+```json
+{
+ "api_key": "ref:model_list.gpt-5.4.api_key"
+}
+```
+
+### Model Indexing for Load Balancing
+
+When you have multiple models with the same base name but different API keys, you can use indexed names:
+
+**.security.yml:**
+```yaml
+model_list:
+ gpt-5.4:
+ api_keys:
+ - "sk-proj-key-1"
+ - "sk-proj-key-2"
+```
+
+The system will automatically expand this into multiple model entries with fallback support.
+
+### Environment Variables
+
+You can override any security value using environment variables:
+
+**For models:**
+```bash
+export PICOCLAW_MODEL_LIST_GPT-5.4_API_KEY="sk-from-env"
+```
+
+**For channels:**
+```bash
+export PICOCLAW_CHANNELS_TELEGRAM_TOKEN="token-from-env"
+```
+
+**For web tools:**
+```bash
+export PICOCLAW_WEB_BRAVE_API_KEY="key-from-env"
+```
+
+Environment variables follow this pattern: `PICOCLAW____` with dots replaced by underscores and converted to uppercase.
+
+### Multiple API Keys Not Working
+
+- Ensure you're using `api_keys` (plural) in `.security.yml` for models and web tools (except GLMSearch)
+- Check that the array format is correct in YAML (proper indentation)
+- Remember: Models, Brave, Tavily, Perplexity MUST use `api_keys` (array format)
+- GLMSearch MUST use `api_key` (single string format)
+- The reference in `config.json` is the same regardless of single or multiple keys
+
+### Load Balancing/Failover Issues
+
+- Verify all API keys in the `api_keys` array are valid
+- Check that all keys have the same rate limits and permissions
+- Monitor logs to see which keys are being used and failing
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 4f8026d27..33919d9d7 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -10,8 +10,10 @@ import (
"github.com/caarlos0/env/v11"
+ "github.com/sipeed/picoclaw/pkg"
"github.com/sipeed/picoclaw/pkg/credential"
"github.com/sipeed/picoclaw/pkg/fileutil"
+ "github.com/sipeed/picoclaw/pkg/logger"
)
// rrCounter is a global counter for round-robin load balancing across models.
@@ -76,20 +78,70 @@ func (f *FlexibleStringSlice) UnmarshalText(text []byte) error {
return nil
}
+// CurrentVersion is the latest config schema version
+const CurrentVersion = 1
+
+// Config is the current config structure with version support
type Config struct {
+ Version int `json:"version"` // Config schema version for migration
Agents AgentsConfig `json:"agents"`
Bindings []AgentBinding `json:"bindings,omitempty"`
Session SessionConfig `json:"session,omitempty"`
Channels ChannelsConfig `json:"channels"`
- Providers ProvidersConfig `json:"providers,omitempty"`
- ModelList []ModelConfig `json:"model_list"` // New model-centric provider configuration
+ ModelList []*ModelConfig `json:"model_list"` // New model-centric provider configuration
Gateway GatewayConfig `json:"gateway"`
+ Hooks HooksConfig `json:"hooks,omitempty"`
Tools ToolsConfig `json:"tools"`
Heartbeat HeartbeatConfig `json:"heartbeat"`
Devices DevicesConfig `json:"devices"`
Voice VoiceConfig `json:"voice"`
// BuildInfo contains build-time version information
BuildInfo BuildInfo `json:"build_info,omitempty"`
+
+ security *SecurityConfig
+}
+
+func (c *Config) WithSecurity(sec *SecurityConfig) *Config {
+ if sec == nil {
+ c.security = sec
+ return c
+ }
+ err := applySecurityConfig(c, sec)
+ if err != nil {
+ return nil
+ }
+ c.security = sec
+ return c
+}
+
+type HooksConfig struct {
+ Enabled bool `json:"enabled"`
+ Defaults HookDefaultsConfig `json:"defaults,omitempty"`
+ Builtins map[string]BuiltinHookConfig `json:"builtins,omitempty"`
+ Processes map[string]ProcessHookConfig `json:"processes,omitempty"`
+}
+
+type HookDefaultsConfig struct {
+ ObserverTimeoutMS int `json:"observer_timeout_ms,omitempty"`
+ InterceptorTimeoutMS int `json:"interceptor_timeout_ms,omitempty"`
+ ApprovalTimeoutMS int `json:"approval_timeout_ms,omitempty"`
+}
+
+type BuiltinHookConfig struct {
+ Enabled bool `json:"enabled"`
+ Priority int `json:"priority,omitempty"`
+ Config json.RawMessage `json:"config,omitempty"`
+}
+
+type ProcessHookConfig struct {
+ Enabled bool `json:"enabled"`
+ Priority int `json:"priority,omitempty"`
+ Transport string `json:"transport,omitempty"`
+ Command []string `json:"command,omitempty"`
+ Dir string `json:"dir,omitempty"`
+ Env map[string]string `json:"env,omitempty"`
+ Observe []string `json:"observe,omitempty"`
+ Intercept []string `json:"intercept,omitempty"`
}
// BuildInfo contains build-time version information
@@ -102,19 +154,13 @@ type BuildInfo struct {
// MarshalJSON implements custom JSON marshaling for Config
// to omit providers section when empty and session when empty
-func (c Config) MarshalJSON() ([]byte, error) {
+func (c *Config) MarshalJSON() ([]byte, error) {
type Alias Config
aux := &struct {
- Providers *ProvidersConfig `json:"providers,omitempty"`
- Session *SessionConfig `json:"session,omitempty"`
+ Session *SessionConfig `json:"session,omitempty"`
*Alias
}{
- Alias: (*Alias)(&c),
- }
-
- // Only include providers if not empty
- if !c.Providers.IsEmpty() {
- aux.Providers = &c.Providers
+ Alias: (*Alias)(c),
}
// Only include session if not empty
@@ -219,9 +265,15 @@ type RoutingConfig struct {
Threshold float64 `json:"threshold"` // complexity score in [0,1]; score >= threshold → primary model
}
-// ToolFeedbackConfig controls whether tool execution details are sent to the
-// chat channel as real-time feedback messages. When enabled, every tool call
-// produces a short notification with the tool name and its parameters.
+// SubTurnConfig configures the SubTurn execution system.
+type SubTurnConfig struct {
+ MaxDepth int `json:"max_depth" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_MAX_DEPTH"`
+ MaxConcurrent int `json:"max_concurrent" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_MAX_CONCURRENT"`
+ DefaultTimeoutMinutes int `json:"default_timeout_minutes" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_DEFAULT_TIMEOUT_MINUTES"`
+ DefaultTokenBudget int `json:"default_token_budget" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_DEFAULT_TOKEN_BUDGET"`
+ ConcurrencyTimeoutSec int `json:"concurrency_timeout_sec" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_CONCURRENCY_TIMEOUT_SEC"`
+}
+
type ToolFeedbackConfig struct {
Enabled bool `json:"enabled" env:"PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_ENABLED"`
MaxArgsLength int `json:"max_args_length" env:"PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_MAX_ARGS_LENGTH"`
@@ -233,21 +285,26 @@ type AgentDefaults struct {
AllowReadOutsideWorkspace bool `json:"allow_read_outside_workspace" env:"PICOCLAW_AGENTS_DEFAULTS_ALLOW_READ_OUTSIDE_WORKSPACE"`
Provider string `json:"provider" env:"PICOCLAW_AGENTS_DEFAULTS_PROVIDER"`
ModelName string `json:"model_name" env:"PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME"`
- Model string `json:"model,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_MODEL"` // Deprecated: use model_name instead
ModelFallbacks []string `json:"model_fallbacks,omitempty"`
ImageModel string `json:"image_model,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_IMAGE_MODEL"`
ImageModelFallbacks []string `json:"image_model_fallbacks,omitempty"`
MaxTokens int `json:"max_tokens" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOKENS"`
+ ContextWindow int `json:"context_window,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_CONTEXT_WINDOW"`
Temperature *float64 `json:"temperature,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE"`
MaxToolIterations int `json:"max_tool_iterations" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS"`
SummarizeMessageThreshold int `json:"summarize_message_threshold" env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_MESSAGE_THRESHOLD"`
SummarizeTokenPercent int `json:"summarize_token_percent" env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_TOKEN_PERCENT"`
MaxMediaSize int `json:"max_media_size,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_MEDIA_SIZE"`
Routing *RoutingConfig `json:"routing,omitempty"`
+ SteeringMode string `json:"steering_mode,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_STEERING_MODE"` // "one-at-a-time" (default) or "all"
+ SubTurn SubTurnConfig `json:"subturn" envPrefix:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_"`
ToolFeedback ToolFeedbackConfig `json:"tool_feedback,omitempty"`
}
-const DefaultMaxMediaSize = 20 * 1024 * 1024 // 20 MB
+const (
+ DefaultMaxMediaSize = 20 * 1024 * 1024 // 20 MB
+ DefaultWeComAIBotProcessingMessage = "⏳ Processing, please wait. The results will be sent shortly."
+)
func (d *AgentDefaults) GetMaxMediaSize() int {
if d.MaxMediaSize > 0 {
@@ -272,10 +329,7 @@ func (d *AgentDefaults) IsToolFeedbackEnabled() bool {
// GetModelName returns the effective model name for the agent defaults.
// It prefers the new "model_name" field but falls back to "model" for backward compatibility.
func (d *AgentDefaults) GetModelName() string {
- if d.ModelName != "" {
- return d.ModelName
- }
- return d.Model
+ return d.ModelName
}
type ChannelsConfig struct {
@@ -293,7 +347,9 @@ type ChannelsConfig struct {
WeCom WeComConfig `json:"wecom"`
WeComApp WeComAppConfig `json:"wecom_app"`
WeComAIBot WeComAIBotConfig `json:"wecom_aibot"`
+ Weixin WeixinConfig `json:"weixin"`
Pico PicoConfig `json:"pico"`
+ PicoClient PicoClientConfig `json:"pico_client"`
IRC IRCConfig `json:"irc"`
}
@@ -314,6 +370,12 @@ type PlaceholderConfig struct {
Text string `json:"text,omitempty"`
}
+type StreamingConfig struct {
+ Enabled bool `json:"enabled,omitempty" env:"PICOCLAW_CHANNELS_TELEGRAM_STREAMING_ENABLED"`
+ ThrottleSeconds int `json:"throttle_seconds,omitempty" env:"PICOCLAW_CHANNELS_TELEGRAM_STREAMING_THROTTLE_SECONDS"`
+ MinGrowthChars int `json:"min_growth_chars,omitempty" env:"PICOCLAW_CHANNELS_TELEGRAM_STREAMING_MIN_GROWTH_CHARS"`
+}
+
type WhatsAppConfig struct {
Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WHATSAPP_ENABLED"`
BridgeURL string `json:"bridge_url" env:"PICOCLAW_CHANNELS_WHATSAPP_BRIDGE_URL"`
@@ -324,35 +386,82 @@ type WhatsAppConfig struct {
}
type TelegramConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
- Token string `json:"token" env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
+ token string
BaseURL string `json:"base_url" env:"PICOCLAW_CHANNELS_TELEGRAM_BASE_URL"`
Proxy string `json:"proxy" env:"PICOCLAW_CHANNELS_TELEGRAM_PROXY"`
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_TELEGRAM_ALLOW_FROM"`
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
Typing TypingConfig `json:"typing,omitempty"`
Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ Streaming StreamingConfig `json:"streaming,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_TELEGRAM_REASONING_CHANNEL_ID"`
UseMarkdownV2 bool `json:"use_markdown_v2" env:"PICOCLAW_CHANNELS_TELEGRAM_USE_MARKDOWN_V2"`
+ secDirty bool
+}
+
+// Token returns the Telegram bot token
+func (c *TelegramConfig) Token() string {
+ return c.token
+}
+
+// SetToken sets the Telegram bot token
+func (c *TelegramConfig) SetToken(token string) {
+ c.token = token
+ c.secDirty = true
}
type FeishuConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
- AppID string `json:"app_id" env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
- AppSecret string `json:"app_secret" env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
- EncryptKey string `json:"encrypt_key" env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
- VerificationToken string `json:"verification_token" env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
+ AppID string `json:"app_id" env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
+ appSecret string
+ encryptKey string
+ verificationToken string
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_FEISHU_REASONING_CHANNEL_ID"`
RandomReactionEmoji FlexibleStringSlice `json:"random_reaction_emoji" env:"PICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJI"`
IsLark bool `json:"is_lark" env:"PICOCLAW_CHANNELS_FEISHU_IS_LARK"`
+ secDirty bool
+}
+
+// AppSecret returns the Feishu app secret
+func (c *FeishuConfig) AppSecret() string {
+ return c.appSecret
+}
+
+// SetAppSecret sets the Feishu app secret
+func (c *FeishuConfig) SetAppSecret(secret string) {
+ c.appSecret = secret
+ c.secDirty = true
+}
+
+// EncryptKey returns the Feishu encrypt key
+func (c *FeishuConfig) EncryptKey() string {
+ return c.encryptKey
+}
+
+// SetEncryptKey sets the Feishu encrypt key
+func (c *FeishuConfig) SetEncryptKey(key string) {
+ c.encryptKey = key
+ c.secDirty = true
+}
+
+// VerificationToken returns the Feishu verification token
+func (c *FeishuConfig) VerificationToken() string {
+ return c.verificationToken
+}
+
+// SetVerificationToken sets the Feishu verification token
+func (c *FeishuConfig) SetVerificationToken(token string) {
+ c.verificationToken = token
+ c.secDirty = true
}
type DiscordConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
- Token string `json:"token" env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
+ token string
Proxy string `json:"proxy" env:"PICOCLAW_CHANNELS_DISCORD_PROXY"`
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_DISCORD_ALLOW_FROM"`
MentionOnly bool `json:"mention_only" env:"PICOCLAW_CHANNELS_DISCORD_MENTION_ONLY"`
@@ -360,6 +469,18 @@ type DiscordConfig struct {
Typing TypingConfig `json:"typing,omitempty"`
Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_DISCORD_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// Token returns the Discord bot token
+func (c *DiscordConfig) Token() string {
+ return c.token
+}
+
+// SetToken sets the Discord bot token
+func (c *DiscordConfig) SetToken(token string) {
+ c.token = token
+ c.secDirty = true
}
type MaixCamConfig struct {
@@ -371,42 +492,89 @@ type MaixCamConfig struct {
}
type QQConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_QQ_ENABLED"`
- AppID string `json:"app_id" env:"PICOCLAW_CHANNELS_QQ_APP_ID"`
- AppSecret string `json:"app_secret" env:"PICOCLAW_CHANNELS_QQ_APP_SECRET"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_QQ_ENABLED"`
+ AppID string `json:"app_id" env:"PICOCLAW_CHANNELS_QQ_APP_ID"`
+ appSecret string
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_QQ_ALLOW_FROM"`
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
MaxMessageLength int `json:"max_message_length" env:"PICOCLAW_CHANNELS_QQ_MAX_MESSAGE_LENGTH"`
MaxBase64FileSizeMiB int64 `json:"max_base64_file_size_mib" env:"PICOCLAW_CHANNELS_QQ_MAX_BASE64_FILE_SIZE_MIB"`
SendMarkdown bool `json:"send_markdown" env:"PICOCLAW_CHANNELS_QQ_SEND_MARKDOWN"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_QQ_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// AppSecret returns the QQ app secret
+func (c *QQConfig) AppSecret() string {
+ return c.appSecret
+}
+
+// SetAppSecret sets the QQ app secret
+func (c *QQConfig) SetAppSecret(secret string) {
+ c.appSecret = secret
+ c.secDirty = true
}
type DingTalkConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_DINGTALK_ENABLED"`
- ClientID string `json:"client_id" env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_ID"`
- ClientSecret string `json:"client_secret" env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_SECRET"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_DINGTALK_ENABLED"`
+ ClientID string `json:"client_id" env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_ID"`
+ clientSecret string
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_DINGTALK_ALLOW_FROM"`
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_DINGTALK_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// ClientSecret returns the DingTalk client secret
+func (c *DingTalkConfig) ClientSecret() string {
+ return c.clientSecret
+}
+
+// SetClientSecret sets the DingTalk client secret
+func (c *DingTalkConfig) SetClientSecret(secret string) {
+ c.clientSecret = secret
+ c.secDirty = true
}
type SlackConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_SLACK_ENABLED"`
- BotToken string `json:"bot_token" env:"PICOCLAW_CHANNELS_SLACK_BOT_TOKEN"`
- AppToken string `json:"app_token" env:"PICOCLAW_CHANNELS_SLACK_APP_TOKEN"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_SLACK_ENABLED"`
+ botToken string
+ appToken string
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_SLACK_ALLOW_FROM"`
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
Typing TypingConfig `json:"typing,omitempty"`
Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_SLACK_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// BotToken returns the Slack bot token
+func (c *SlackConfig) BotToken() string {
+ return c.botToken
+}
+
+// SetBotToken sets the Slack bot token
+func (c *SlackConfig) SetBotToken(token string) {
+ c.botToken = token
+ c.secDirty = true
+}
+
+// AppToken returns the Slack app token
+func (c *SlackConfig) AppToken() string {
+ return c.appToken
+}
+
+// SetAppToken sets the Slack app token
+func (c *SlackConfig) SetAppToken(token string) {
+ c.appToken = token
+ c.secDirty = true
}
type MatrixConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_MATRIX_ENABLED"`
- Homeserver string `json:"homeserver" env:"PICOCLAW_CHANNELS_MATRIX_HOMESERVER"`
- UserID string `json:"user_id" env:"PICOCLAW_CHANNELS_MATRIX_USER_ID"`
- AccessToken string `json:"access_token" env:"PICOCLAW_CHANNELS_MATRIX_ACCESS_TOKEN"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_MATRIX_ENABLED"`
+ Homeserver string `json:"homeserver" env:"PICOCLAW_CHANNELS_MATRIX_HOMESERVER"`
+ UserID string `json:"user_id" env:"PICOCLAW_CHANNELS_MATRIX_USER_ID"`
+ accessToken string
DeviceID string `json:"device_id,omitempty" env:"PICOCLAW_CHANNELS_MATRIX_DEVICE_ID"`
JoinOnInvite bool `json:"join_on_invite" env:"PICOCLAW_CHANNELS_MATRIX_JOIN_ON_INVITE"`
MessageFormat string `json:"message_format,omitempty" env:"PICOCLAW_CHANNELS_MATRIX_MESSAGE_FORMAT"`
@@ -414,12 +582,24 @@ type MatrixConfig struct {
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_MATRIX_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// AccessToken returns the Matrix access token
+func (c *MatrixConfig) AccessToken() string {
+ return c.accessToken
+}
+
+// SetAccessToken sets the Matrix access token
+func (c *MatrixConfig) SetAccessToken(token string) {
+ c.accessToken = token
+ c.secDirty = true
}
type LINEConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_LINE_ENABLED"`
- ChannelSecret string `json:"channel_secret" env:"PICOCLAW_CHANNELS_LINE_CHANNEL_SECRET"`
- ChannelAccessToken string `json:"channel_access_token" env:"PICOCLAW_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_LINE_ENABLED"`
+ channelSecret string
+ channelAccessToken string
WebhookHost string `json:"webhook_host" env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_HOST"`
WebhookPort int `json:"webhook_port" env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_PORT"`
WebhookPath string `json:"webhook_path" env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_PATH"`
@@ -428,12 +608,35 @@ type LINEConfig struct {
Typing TypingConfig `json:"typing,omitempty"`
Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_LINE_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// ChannelSecret returns the LINE channel secret
+func (c *LINEConfig) ChannelSecret() string {
+ return c.channelSecret
+}
+
+// SetChannelSecret sets the LINE channel secret
+func (c *LINEConfig) SetChannelSecret(secret string) {
+ c.channelSecret = secret
+ c.secDirty = true
+}
+
+// ChannelAccessToken returns the LINE channel access token
+func (c *LINEConfig) ChannelAccessToken() string {
+ return c.channelAccessToken
+}
+
+// SetChannelAccessToken sets the LINE channel access token
+func (c *LINEConfig) SetChannelAccessToken(token string) {
+ c.channelAccessToken = token
+ c.secDirty = true
}
type OneBotConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_ONEBOT_ENABLED"`
- WSUrl string `json:"ws_url" env:"PICOCLAW_CHANNELS_ONEBOT_WS_URL"`
- AccessToken string `json:"access_token" env:"PICOCLAW_CHANNELS_ONEBOT_ACCESS_TOKEN"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_ONEBOT_ENABLED"`
+ WSUrl string `json:"ws_url" env:"PICOCLAW_CHANNELS_ONEBOT_WS_URL"`
+ accessToken string
ReconnectInterval int `json:"reconnect_interval" env:"PICOCLAW_CHANNELS_ONEBOT_RECONNECT_INTERVAL"`
GroupTriggerPrefix []string `json:"group_trigger_prefix" env:"PICOCLAW_CHANNELS_ONEBOT_GROUP_TRIGGER_PREFIX"`
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_ONEBOT_ALLOW_FROM"`
@@ -441,12 +644,24 @@ type OneBotConfig struct {
Typing TypingConfig `json:"typing,omitempty"`
Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_ONEBOT_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// AccessToken returns the OneBot access token
+func (c *OneBotConfig) AccessToken() string {
+ return c.accessToken
+}
+
+// SetAccessToken sets the OneBot access token
+func (c *OneBotConfig) SetAccessToken(token string) {
+ c.accessToken = token
+ c.secDirty = true
}
type WeComConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_ENABLED"`
- Token string `json:"token" env:"PICOCLAW_CHANNELS_WECOM_TOKEN"`
- EncodingAESKey string `json:"encoding_aes_key" env:"PICOCLAW_CHANNELS_WECOM_ENCODING_AES_KEY"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_ENABLED"`
+ token string
+ encodingAESKey string
WebhookURL string `json:"webhook_url" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_URL"`
WebhookHost string `json:"webhook_host" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_HOST"`
WebhookPort int `json:"webhook_port" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_PORT"`
@@ -455,15 +670,38 @@ type WeComConfig struct {
ReplyTimeout int `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_REPLY_TIMEOUT"`
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// Token returns the WeCom token
+func (c *WeComConfig) Token() string {
+ return c.token
+}
+
+// SetToken sets the WeCom token
+func (c *WeComConfig) SetToken(token string) {
+ c.token = token
+ c.secDirty = true
+}
+
+// EncodingAESKey returns the WeCom encoding AES key
+func (c *WeComConfig) EncodingAESKey() string {
+ return c.encodingAESKey
+}
+
+// SetEncodingAESKey sets the WeCom encoding AES key
+func (c *WeComConfig) SetEncodingAESKey(key string) {
+ c.encodingAESKey = key
+ c.secDirty = true
}
type WeComAppConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_APP_ENABLED"`
- CorpID string `json:"corp_id" env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_ID"`
- CorpSecret string `json:"corp_secret" env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_SECRET"`
- AgentID int64 `json:"agent_id" env:"PICOCLAW_CHANNELS_WECOM_APP_AGENT_ID"`
- Token string `json:"token" env:"PICOCLAW_CHANNELS_WECOM_APP_TOKEN"`
- EncodingAESKey string `json:"encoding_aes_key" env:"PICOCLAW_CHANNELS_WECOM_APP_ENCODING_AES_KEY"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_APP_ENABLED"`
+ CorpID string `json:"corp_id" env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_ID"`
+ corpSecret string
+ AgentID int64 `json:"agent_id" env:"PICOCLAW_CHANNELS_WECOM_APP_AGENT_ID"`
+ token string
+ encodingAESKey string
WebhookHost string `json:"webhook_host" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_HOST"`
WebhookPort int `json:"webhook_port" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_PORT"`
WebhookPath string `json:"webhook_path" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_PATH"`
@@ -471,25 +709,113 @@ type WeComAppConfig struct {
ReplyTimeout int `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_APP_REPLY_TIMEOUT"`
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_APP_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// CorpSecret returns the corporate secret for WeCom app
+func (c *WeComAppConfig) CorpSecret() string {
+ return c.corpSecret
+}
+
+// SetCorpSecret sets the corporate secret for WeCom app
+func (c *WeComAppConfig) SetCorpSecret(secret string) {
+ c.corpSecret = secret
+ c.secDirty = true
+}
+
+// Token returns the webhook token for WeCom app
+func (c *WeComAppConfig) Token() string {
+ return c.token
+}
+
+// SetToken sets the webhook token for WeCom app
+func (c *WeComAppConfig) SetToken(token string) {
+ c.token = token
+ c.secDirty = true
+}
+
+// EncodingAESKey returns the encoding AES key for WeCom app
+func (c *WeComAppConfig) EncodingAESKey() string {
+ return c.encodingAESKey
+}
+
+// SetEncodingAESKey sets the encoding AES key for WeCom app
+func (c *WeComAppConfig) SetEncodingAESKey(key string) {
+ c.encodingAESKey = key
+ c.secDirty = true
}
type WeComAIBotConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENABLED"`
- BotID string `json:"bot_id,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_BOT_ID"`
- Secret string `json:"secret,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_SECRET"`
- Token string `json:"token,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_TOKEN"`
- EncodingAESKey string `json:"encoding_aes_key,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENCODING_AES_KEY"`
- WebhookPath string `json:"webhook_path,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WEBHOOK_PATH"`
- AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ALLOW_FROM"`
- ReplyTimeout int `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REPLY_TIMEOUT"`
- MaxSteps int `json:"max_steps" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_MAX_STEPS"`
- WelcomeMessage string `json:"welcome_message" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WELCOME_MESSAGE"`
- ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REASONING_CHANNEL_ID"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENABLED"`
+ BotID string `json:"bot_id,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_BOT_ID"`
+ secret string
+ token string
+ encodingAESKey string
+ WebhookPath string `json:"webhook_path,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WEBHOOK_PATH"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ALLOW_FROM"`
+ ReplyTimeout int `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REPLY_TIMEOUT"`
+ MaxSteps int `json:"max_steps" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_MAX_STEPS"` // Maximum streaming steps
+ WelcomeMessage string `json:"welcome_message" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WELCOME_MESSAGE"` // Sent on enter_chat event; empty = no welcome
+ ProcessingMessage string `json:"processing_message,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_PROCESSING_MESSAGE"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// Token returns the webhook token for WeCom AI bot
+func (c *WeComAIBotConfig) Token() string {
+ return c.token
+}
+
+// EncodingAESKey returns the encoding AES key for WeCom AI bot
+func (c *WeComAIBotConfig) EncodingAESKey() string {
+ return c.encodingAESKey
+}
+
+// SetToken sets the token for WeCom AI bot
+func (c *WeComAIBotConfig) SetToken(token string) {
+ c.token = token
+ c.secDirty = true
+}
+
+// SetEncodingAESKey sets the encoding AES key for WeCom AI bot
+func (c *WeComAIBotConfig) SetEncodingAESKey(key string) {
+ c.encodingAESKey = key
+ c.secDirty = true
+}
+
+func (c *WeComAIBotConfig) Secret() string {
+ return c.secret
+}
+
+func (c *WeComAIBotConfig) SetSecret(secret string) {
+ c.secret = secret
+ c.secDirty = true
+}
+
+type WeixinConfig struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WEIXIN_ENABLED"`
+ token string
+ BaseURL string `json:"base_url" env:"PICOCLAW_CHANNELS_WEIXIN_BASE_URL"`
+ CDNBaseURL string `json:"cdn_base_url" env:"PICOCLAW_CHANNELS_WEIXIN_CDN_BASE_URL"`
+ Proxy string `json:"proxy" env:"PICOCLAW_CHANNELS_WEIXIN_PROXY"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WEIXIN_ALLOW_FROM"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WEIXIN_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+func (c *WeixinConfig) Token() string {
+ return c.token
+}
+
+func (c *WeixinConfig) SetToken(token string) *WeixinConfig {
+ c.token = token
+ c.secDirty = true
+ return c
}
type PicoConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_PICO_ENABLED"`
- Token string `json:"token" env:"PICOCLAW_CHANNELS_PICO_TOKEN"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_PICO_ENABLED"`
+ token string
AllowTokenQuery bool `json:"allow_token_query,omitempty"`
AllowOrigins []string `json:"allow_origins,omitempty"`
PingInterval int `json:"ping_interval,omitempty"`
@@ -498,25 +824,78 @@ type PicoConfig struct {
MaxConnections int `json:"max_connections,omitempty"`
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_PICO_ALLOW_FROM"`
Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ secDirty bool
+}
+
+// Token returns the Pico channel token
+func (c *PicoConfig) Token() string {
+ return c.token
+}
+
+// SetToken sets the Pico channel token
+func (c *PicoConfig) SetToken(token string) {
+ c.token = token
+ c.secDirty = true
+}
+
+type PicoClientConfig struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_PICO_CLIENT_ENABLED"`
+ URL string `json:"url" env:"PICOCLAW_CHANNELS_PICO_CLIENT_URL"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_PICO_CLIENT_TOKEN"`
+ SessionID string `json:"session_id,omitempty"`
+ PingInterval int `json:"ping_interval,omitempty"`
+ ReadTimeout int `json:"read_timeout,omitempty"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_PICO_CLIENT_ALLOW_FROM"`
}
type IRCConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_IRC_ENABLED"`
- Server string `json:"server" env:"PICOCLAW_CHANNELS_IRC_SERVER"`
- TLS bool `json:"tls" env:"PICOCLAW_CHANNELS_IRC_TLS"`
- Nick string `json:"nick" env:"PICOCLAW_CHANNELS_IRC_NICK"`
- User string `json:"user,omitempty" env:"PICOCLAW_CHANNELS_IRC_USER"`
- RealName string `json:"real_name,omitempty" env:"PICOCLAW_CHANNELS_IRC_REAL_NAME"`
- Password string `json:"password" env:"PICOCLAW_CHANNELS_IRC_PASSWORD"`
- NickServPassword string `json:"nickserv_password" env:"PICOCLAW_CHANNELS_IRC_NICKSERV_PASSWORD"`
- SASLUser string `json:"sasl_user" env:"PICOCLAW_CHANNELS_IRC_SASL_USER"`
- SASLPassword string `json:"sasl_password" env:"PICOCLAW_CHANNELS_IRC_SASL_PASSWORD"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_IRC_ENABLED"`
+ Server string `json:"server" env:"PICOCLAW_CHANNELS_IRC_SERVER"`
+ TLS bool `json:"tls" env:"PICOCLAW_CHANNELS_IRC_TLS"`
+ Nick string `json:"nick" env:"PICOCLAW_CHANNELS_IRC_NICK"`
+ User string `json:"user,omitempty" env:"PICOCLAW_CHANNELS_IRC_USER"`
+ RealName string `json:"real_name,omitempty" env:"PICOCLAW_CHANNELS_IRC_REAL_NAME"`
+ password string
+ nickServPassword string
+ SASLUser string `json:"sasl_user" env:"PICOCLAW_CHANNELS_IRC_SASL_USER"`
+ saslPassword string
Channels FlexibleStringSlice `json:"channels" env:"PICOCLAW_CHANNELS_IRC_CHANNELS"`
RequestCaps FlexibleStringSlice `json:"request_caps,omitempty" env:"PICOCLAW_CHANNELS_IRC_REQUEST_CAPS"`
AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_IRC_ALLOW_FROM"`
GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
Typing TypingConfig `json:"typing,omitempty"`
ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_IRC_REASONING_CHANNEL_ID"`
+ secDirty bool
+}
+
+// Password returns the IRC password
+func (c *IRCConfig) Password() string {
+ return c.password
+}
+
+// NickServPassword returns the NickServ password
+func (c *IRCConfig) NickServPassword() string {
+ return c.nickServPassword
+}
+
+// SASLPassword returns the SASL password
+func (c *IRCConfig) SASLPassword() string {
+ return c.saslPassword
+}
+
+func (c *IRCConfig) SetPassword(password string) {
+ c.password = password
+ c.secDirty = true
+}
+
+func (c *IRCConfig) SetNickServPassword(password string) {
+ c.nickServPassword = password
+ c.secDirty = true
+}
+
+func (c *IRCConfig) SetSASLPassword(password string) {
+ c.saslPassword = password
+ c.secDirty = true
}
type HeartbeatConfig struct {
@@ -530,89 +909,8 @@ type DevicesConfig struct {
}
type VoiceConfig struct {
- EchoTranscription bool `json:"echo_transcription" env:"PICOCLAW_VOICE_ECHO_TRANSCRIPTION"`
-}
-
-type ProvidersConfig struct {
- Anthropic ProviderConfig `json:"anthropic"`
- OpenAI OpenAIProviderConfig `json:"openai"`
- LiteLLM ProviderConfig `json:"litellm"`
- OpenRouter ProviderConfig `json:"openrouter"`
- Groq ProviderConfig `json:"groq"`
- Zhipu ProviderConfig `json:"zhipu"`
- VLLM ProviderConfig `json:"vllm"`
- Gemini ProviderConfig `json:"gemini"`
- Nvidia ProviderConfig `json:"nvidia"`
- Ollama ProviderConfig `json:"ollama"`
- Moonshot ProviderConfig `json:"moonshot"`
- ShengSuanYun ProviderConfig `json:"shengsuanyun"`
- DeepSeek ProviderConfig `json:"deepseek"`
- Cerebras ProviderConfig `json:"cerebras"`
- Vivgrid ProviderConfig `json:"vivgrid"`
- VolcEngine ProviderConfig `json:"volcengine"`
- GitHubCopilot ProviderConfig `json:"github_copilot"`
- Antigravity ProviderConfig `json:"antigravity"`
- Qwen ProviderConfig `json:"qwen"`
- Mistral ProviderConfig `json:"mistral"`
- Avian ProviderConfig `json:"avian"`
- Minimax ProviderConfig `json:"minimax"`
- LongCat ProviderConfig `json:"longcat"`
- ModelScope ProviderConfig `json:"modelscope"`
- Novita ProviderConfig `json:"novita"`
-}
-
-// IsEmpty checks if all provider configs are empty (no API keys or API bases set)
-// Note: WebSearch is an optimization option and doesn't count as "non-empty"
-func (p ProvidersConfig) IsEmpty() bool {
- return p.Anthropic.APIKey == "" && p.Anthropic.APIBase == "" &&
- p.OpenAI.APIKey == "" && p.OpenAI.APIBase == "" &&
- p.LiteLLM.APIKey == "" && p.LiteLLM.APIBase == "" &&
- p.OpenRouter.APIKey == "" && p.OpenRouter.APIBase == "" &&
- p.Groq.APIKey == "" && p.Groq.APIBase == "" &&
- p.Zhipu.APIKey == "" && p.Zhipu.APIBase == "" &&
- p.VLLM.APIKey == "" && p.VLLM.APIBase == "" &&
- p.Gemini.APIKey == "" && p.Gemini.APIBase == "" &&
- p.Nvidia.APIKey == "" && p.Nvidia.APIBase == "" &&
- p.Ollama.APIKey == "" && p.Ollama.APIBase == "" &&
- p.Moonshot.APIKey == "" && p.Moonshot.APIBase == "" &&
- p.ShengSuanYun.APIKey == "" && p.ShengSuanYun.APIBase == "" &&
- p.DeepSeek.APIKey == "" && p.DeepSeek.APIBase == "" &&
- p.Cerebras.APIKey == "" && p.Cerebras.APIBase == "" &&
- p.Vivgrid.APIKey == "" && p.Vivgrid.APIBase == "" &&
- p.VolcEngine.APIKey == "" && p.VolcEngine.APIBase == "" &&
- p.GitHubCopilot.APIKey == "" && p.GitHubCopilot.APIBase == "" &&
- p.Antigravity.APIKey == "" && p.Antigravity.APIBase == "" &&
- p.Qwen.APIKey == "" && p.Qwen.APIBase == "" &&
- p.Mistral.APIKey == "" && p.Mistral.APIBase == "" &&
- p.Avian.APIKey == "" && p.Avian.APIBase == "" &&
- p.Minimax.APIKey == "" && p.Minimax.APIBase == "" &&
- p.LongCat.APIKey == "" && p.LongCat.APIBase == "" &&
- p.ModelScope.APIKey == "" && p.ModelScope.APIBase == "" &&
- p.Novita.APIKey == "" && p.Novita.APIBase == ""
-}
-
-// MarshalJSON implements custom JSON marshaling for ProvidersConfig
-// to omit the entire section when empty
-func (p ProvidersConfig) MarshalJSON() ([]byte, error) {
- if p.IsEmpty() {
- return []byte("null"), nil
- }
- type Alias ProvidersConfig
- return json.Marshal((*Alias)(&p))
-}
-
-type ProviderConfig struct {
- APIKey string `json:"api_key" env:"PICOCLAW_PROVIDERS_{{.Name}}_API_KEY"`
- APIBase string `json:"api_base" env:"PICOCLAW_PROVIDERS_{{.Name}}_API_BASE"`
- Proxy string `json:"proxy,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_PROXY"`
- RequestTimeout int `json:"request_timeout,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_REQUEST_TIMEOUT"`
- AuthMethod string `json:"auth_method,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_AUTH_METHOD"`
- ConnectMode string `json:"connect_mode,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_CONNECT_MODE"` // only for Github Copilot, `stdio` or `grpc`
-}
-
-type OpenAIProviderConfig struct {
- ProviderConfig
- WebSearch bool `json:"web_search" env:"PICOCLAW_PROVIDERS_OPENAI_WEB_SEARCH"`
+ ModelName string `json:"model_name,omitempty" env:"PICOCLAW_VOICE_MODEL_NAME"`
+ EchoTranscription bool `json:"echo_transcription" env:"PICOCLAW_VOICE_ECHO_TRANSCRIPTION"`
}
// ModelConfig represents a model-centric provider configuration.
@@ -629,8 +927,6 @@ type ModelConfig struct {
// HTTP-based providers
APIBase string `json:"api_base,omitempty"` // API endpoint URL
- APIKey string `json:"api_key"` // API authentication key (single key)
- APIKeys []string `json:"api_keys,omitempty"` // API authentication keys (multiple keys for failover)
Proxy string `json:"proxy,omitempty"` // HTTP proxy URL
Fallbacks []string `json:"fallbacks,omitempty"` // Fallback model names for failover
@@ -640,10 +936,24 @@ type ModelConfig struct {
Workspace string `json:"workspace,omitempty"` // Workspace path for CLI-based providers
// Optional optimizations
- RPM int `json:"rpm,omitempty"` // Requests per minute limit
- MaxTokensField string `json:"max_tokens_field,omitempty"` // Field name for max tokens (e.g., "max_completion_tokens")
- RequestTimeout int `json:"request_timeout,omitempty"`
- ThinkingLevel string `json:"thinking_level,omitempty"` // Extended thinking: off|low|medium|high|xhigh|adaptive
+ RPM int `json:"rpm,omitempty"` // Requests per minute limit
+ MaxTokensField string `json:"max_tokens_field,omitempty"` // Field name for max tokens (e.g., "max_completion_tokens")
+ RequestTimeout int `json:"request_timeout,omitempty"`
+ ThinkingLevel string `json:"thinking_level,omitempty"` // Extended thinking: off|low|medium|high|xhigh|adaptive
+ ExtraBody map[string]any `json:"extra_body,omitempty"` // Additional fields to inject into request body
+
+ // from security
+ secModelName string
+ apiKeys []string
+ secDirty bool
+}
+
+// APIKey returns the first API key from apiKeys
+func (c *ModelConfig) APIKey() string {
+ if len(c.apiKeys) > 0 {
+ return c.apiKeys[0]
+ }
+ return ""
}
// Validate checks if the ModelConfig has all required fields.
@@ -657,10 +967,20 @@ func (c *ModelConfig) Validate() error {
return nil
}
+func (c *ModelConfig) SetAPIKey(value string) {
+ if len(c.apiKeys) > 0 {
+ c.apiKeys[0] = value
+ } else {
+ c.apiKeys = append(c.apiKeys, value)
+ }
+ c.secDirty = true
+}
+
type GatewayConfig struct {
- Host string `json:"host" env:"PICOCLAW_GATEWAY_HOST"`
- Port int `json:"port" env:"PICOCLAW_GATEWAY_PORT"`
- HotReload bool `json:"hot_reload" env:"PICOCLAW_GATEWAY_HOT_RELOAD"`
+ Host string `json:"host" env:"PICOCLAW_GATEWAY_HOST"`
+ Port int `json:"port" env:"PICOCLAW_GATEWAY_PORT"`
+ HotReload bool `json:"hot_reload" env:"PICOCLAW_GATEWAY_HOT_RELOAD"`
+ LogLevel string `json:"log_level,omitempty" env:"PICOCLAW_LOG_LEVEL"`
}
type ToolDiscoveryConfig struct {
@@ -676,18 +996,68 @@ type ToolConfig struct {
}
type BraveConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_BRAVE_ENABLED"`
- APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_BRAVE_API_KEY"`
- APIKeys []string `json:"api_keys" env:"PICOCLAW_TOOLS_WEB_BRAVE_API_KEYS"`
- MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BRAVE_MAX_RESULTS"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_BRAVE_ENABLED"`
+ apiKeys []string
+ secDirty bool
+ MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BRAVE_MAX_RESULTS"`
+}
+
+// APIKey returns the Brave API key
+func (c *BraveConfig) APIKey() string {
+ if len(c.apiKeys) == 0 {
+ return ""
+ }
+ return c.apiKeys[0]
+}
+
+// APIKeys returns the Brave API keys
+func (c *BraveConfig) APIKeys() []string {
+ return c.apiKeys
+}
+
+// SetAPIKey sets the Brave API key
+func (c *BraveConfig) SetAPIKey(key string) {
+ c.apiKeys = []string{key}
+ c.secDirty = true
+}
+
+// SetAPIKeys sets the Brave API keys
+func (c *BraveConfig) SetAPIKeys(keys []string) {
+ c.apiKeys = keys
+ c.secDirty = true
}
type TavilyConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_TAVILY_ENABLED"`
- APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_TAVILY_API_KEY"`
- APIKeys []string `json:"api_keys" env:"PICOCLAW_TOOLS_WEB_TAVILY_API_KEYS"`
- BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_TAVILY_BASE_URL"`
- MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_TAVILY_MAX_RESULTS"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_TAVILY_ENABLED"`
+ apiKeys []string
+ secDirty bool
+ BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_TAVILY_BASE_URL"`
+ MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_TAVILY_MAX_RESULTS"`
+}
+
+// APIKey returns the Tavily API key
+func (c *TavilyConfig) APIKey() string {
+ if len(c.apiKeys) == 0 {
+ return ""
+ }
+ return c.apiKeys[0]
+}
+
+// APIKeys returns the Tavily API keys
+func (c *TavilyConfig) APIKeys() []string {
+ return c.apiKeys
+}
+
+// SetAPIKey sets the Tavily API key
+func (c *TavilyConfig) SetAPIKey(key string) {
+ c.apiKeys = []string{key}
+ c.secDirty = true
+}
+
+// SetAPIKeys sets the Tavily API keys
+func (c *TavilyConfig) SetAPIKeys(keys []string) {
+ c.apiKeys = keys
+ c.secDirty = true
}
type DuckDuckGoConfig struct {
@@ -696,10 +1066,35 @@ type DuckDuckGoConfig struct {
}
type PerplexityConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_ENABLED"`
- APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_API_KEY"`
- APIKeys []string `json:"api_keys" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_API_KEYS"`
- MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_MAX_RESULTS"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_ENABLED"`
+ apiKeys []string
+ secDirty bool
+ MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_MAX_RESULTS"`
+}
+
+// APIKey returns the Perplexity API key
+func (c *PerplexityConfig) APIKey() string {
+ if len(c.apiKeys) == 0 {
+ return ""
+ }
+ return c.apiKeys[0]
+}
+
+// SetAPIKey sets the Perplexity API key
+func (c *PerplexityConfig) SetAPIKey(key string) {
+ c.apiKeys = []string{key}
+ c.secDirty = true
+}
+
+// APIKeys returns the Perplexity API keys
+func (c *PerplexityConfig) APIKeys() []string {
+ return c.apiKeys
+}
+
+// SetAPIKeys sets the Perplexity API keys
+func (c *PerplexityConfig) SetAPIKeys(keys []string) {
+ c.apiKeys = keys
+ c.secDirty = true
}
type SearXNGConfig struct {
@@ -709,23 +1104,54 @@ type SearXNGConfig struct {
}
type GLMSearchConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"`
- APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_GLM_API_KEY"`
- BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"`
+ apiKey string
+ secDirty bool
+ BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"`
// SearchEngine specifies the search backend: "search_std" (default),
// "search_pro", "search_pro_sogou", or "search_pro_quark".
SearchEngine string `json:"search_engine" env:"PICOCLAW_TOOLS_WEB_GLM_SEARCH_ENGINE"`
MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_GLM_MAX_RESULTS"`
}
+// APIKey returns the GLM search API key
+func (c *GLMSearchConfig) APIKey() string {
+ return c.apiKey
+}
+
+// SetAPIKey sets the GLM search API key (internal use only)
+func (c *GLMSearchConfig) SetAPIKey(key string) {
+ c.apiKey = key
+ c.secDirty = true
+}
+
+type BaiduSearchConfig struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_BAIDU_ENABLED"`
+ BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_BAIDU_BASE_URL"`
+ MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BAIDU_MAX_RESULTS"`
+ apiKey string
+ secDirty bool
+}
+
+// APIKey returns the Baidu search API key
+func (c *BaiduSearchConfig) APIKey() string {
+ return c.apiKey
+}
+
+func (c *BaiduSearchConfig) SetAPIKey(key string) {
+ c.apiKey = key
+ c.secDirty = true
+}
+
type WebToolsConfig struct {
- ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"`
- Brave BraveConfig ` json:"brave"`
- Tavily TavilyConfig ` json:"tavily"`
- DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"`
- Perplexity PerplexityConfig ` json:"perplexity"`
- SearXNG SearXNGConfig ` json:"searxng"`
- GLMSearch GLMSearchConfig ` json:"glm_search"`
+ ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"`
+ Brave BraveConfig ` json:"brave"`
+ Tavily TavilyConfig ` json:"tavily"`
+ DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"`
+ Perplexity PerplexityConfig ` json:"perplexity"`
+ SearXNG SearXNGConfig ` json:"searxng"`
+ GLMSearch GLMSearchConfig ` json:"glm_search"`
+ BaiduSearch BaiduSearchConfig ` json:"baidu_search"`
// PreferNative controls whether to use provider-native web search when
// the active LLM supports it (e.g. OpenAI web_search_preview). When true,
// the client-side web_search tool is hidden to avoid duplicate search surfaces,
@@ -810,14 +1236,27 @@ type SkillsRegistriesConfig struct {
}
type SkillsGithubConfig struct {
- Token string `json:"token,omitempty" env:"PICOCLAW_TOOLS_SKILLS_GITHUB_AUTH_TOKEN"`
- Proxy string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_SKILLS_GITHUB_PROXY"`
+ token string
+ secDirty bool
+ Proxy string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_SKILLS_GITHUB_PROXY"`
+}
+
+// Token returns the GitHub token
+func (c *SkillsGithubConfig) Token() string {
+ return c.token
+}
+
+// SetToken sets the GitHub token
+func (c *SkillsGithubConfig) SetToken(token string) {
+ c.token = token
+ c.secDirty = true
}
type ClawHubRegistryConfig struct {
Enabled bool `json:"enabled" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_ENABLED"`
BaseURL string `json:"base_url" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_BASE_URL"`
- AuthToken string `json:"auth_token" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_AUTH_TOKEN"`
+ authToken string
+ secDirty bool
SearchPath string `json:"search_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SEARCH_PATH"`
SkillsPath string `json:"skills_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SKILLS_PATH"`
DownloadPath string `json:"download_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_DOWNLOAD_PATH"`
@@ -826,6 +1265,17 @@ type ClawHubRegistryConfig struct {
MaxResponseSize int `json:"max_response_size" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_MAX_RESPONSE_SIZE"`
}
+// AuthToken returns the ClawHub auth token
+func (c *ClawHubRegistryConfig) AuthToken() string {
+ return c.authToken
+}
+
+// SetAuthToken sets the ClawHub auth token
+func (c *ClawHubRegistryConfig) SetAuthToken(token string) {
+ c.authToken = token
+ c.secDirty = true
+}
+
// MCPServerConfig defines configuration for a single MCP server
type MCPServerConfig struct {
// Enabled indicates whether this MCP server is active
@@ -859,40 +1309,76 @@ type MCPConfig struct {
}
func LoadConfig(path string) (*Config, error) {
- cfg := DefaultConfig()
-
data, err := os.ReadFile(path)
if err != nil {
if os.IsNotExist(err) {
- return cfg, nil
+ return DefaultConfig(), nil
}
return nil, err
}
- // Pre-scan the JSON to check how many model_list entries the user provided.
- // Go's JSON decoder reuses existing slice backing-array elements rather than
- // zero-initializing them, so fields absent from the user's JSON (e.g. api_base)
- // would silently inherit values from the DefaultConfig template at the same
- // index position. We only reset cfg.ModelList when the user actually provides
- // entries; when count is 0 we keep DefaultConfig's built-in list as fallback.
- var tmp Config
- if err := json.Unmarshal(data, &tmp); err != nil {
- return nil, err
+ // First, try to detect config version by reading the version field
+ var versionInfo struct {
+ Version int `json:"version"`
}
- if len(tmp.ModelList) > 0 {
- cfg.ModelList = nil
+ if e := json.Unmarshal(data, &versionInfo); e != nil {
+ return nil, fmt.Errorf("failed to detect config version: %w", e)
+ }
+ if len(data) <= 10 {
+ return DefaultConfig().WithSecurity(&SecurityConfig{}), nil
}
- if err := json.Unmarshal(data, cfg); err != nil {
- return nil, err
+ // Load config based on detected version
+ var cfg *Config
+ switch versionInfo.Version {
+ case 0:
+ logger.InfoF("config migrate start", map[string]any{"from": versionInfo.Version, "to": CurrentVersion})
+ // Legacy config (no version field)
+ v, e := loadConfigV0(data)
+ if e != nil {
+ return nil, e
+ }
+ cfg, e = v.Migrate()
+ if e != nil {
+ logger.DebugF("config migrate fail", map[string]any{"from": versionInfo.Version, "to": CurrentVersion})
+ return nil, e
+ }
+ logger.DebugF("config migrate success", map[string]any{"from": versionInfo.Version, "to": CurrentVersion})
+ defer func() {
+ _ = SaveConfig(path, cfg)
+ }()
+ case CurrentVersion:
+ // Current version
+ cfg, err = loadConfig(data)
+ if err != nil {
+ return nil, err
+ }
+ default:
+ return nil, fmt.Errorf("unsupported config version: %d", versionInfo.Version)
+ }
+
+ // Load security configuration
+ securityPath := securityPath(path)
+ sec, err := loadSecurityConfig(securityPath)
+ if err != nil {
+ return nil, fmt.Errorf("failed to load security config: %w", err)
+ }
+
+ // Apply security references from .security.yml BEFORE resolveAPIKeys
+ // This resolves ref: references to actual values
+ if err := applySecurityConfig(cfg, sec); err != nil {
+ return nil, fmt.Errorf("failed to apply security config: %w", err)
}
if passphrase := credential.PassphraseProvider(); passphrase != "" {
for _, m := range cfg.ModelList {
- if m.APIKey != "" && !strings.HasPrefix(m.APIKey, "enc://") && !strings.HasPrefix(m.APIKey, "file://") {
- fmt.Fprintf(os.Stderr,
- "picoclaw: warning: model %q has a plaintext api_key; call SaveConfig to encrypt it\n",
- m.ModelName)
+ for _, k := range m.apiKeys {
+ if k != "" && !strings.HasPrefix(k, "enc://") && !strings.HasPrefix(k, "file://") {
+ fmt.Fprintf(os.Stderr,
+ "picoclaw: warning: model %q has a plaintext api_key; call SaveConfig to encrypt it\n",
+ m.ModelName)
+ break // Only warn once per model
+ }
}
}
}
@@ -905,55 +1391,264 @@ func LoadConfig(path string) (*Config, error) {
return nil, err
}
+ // Resolve security fields like authToken that may contain file:// references
+ if err := resolveSecurityFields(cfg, filepath.Dir(path)); err != nil {
+ return nil, err
+ }
+
// Expand multi-key configs into separate entries for key-level failover
- cfg.ModelList = ExpandMultiKeyModels(cfg.ModelList)
+ cfg.ModelList = expandMultiKeyModels(cfg.ModelList)
// Migrate legacy channel config fields to new unified structures
cfg.migrateChannelConfigs()
- // Auto-migrate: if only legacy providers config exists, convert to model_list
- if len(cfg.ModelList) == 0 && cfg.HasProvidersConfig() {
- cfg.ModelList = ConvertProvidersToModelList(cfg)
- }
-
- // Inherit credentials from providers to model_list entries (#1635).
- // When both providers and model_list are present, model_list entries
- // whose api_key/api_base are empty will inherit from the matching
- // provider (matched by protocol prefix). Explicit model_list values
- // always take precedence.
- if cfg.HasProvidersConfig() {
- InheritProviderCredentials(cfg.ModelList, cfg.Providers)
- }
-
// Validate model_list for uniqueness and required fields
if err := cfg.ValidateModelList(); err != nil {
return nil, err
}
+ // Ensure Workspace has a default if not set
+ if cfg.Agents.Defaults.Workspace == "" {
+ homePath, _ := os.UserHomeDir()
+ if picoclawHome := os.Getenv(EnvHome); picoclawHome != "" {
+ homePath = picoclawHome
+ } else if homePath != "" {
+ homePath = filepath.Join(homePath, pkg.DefaultPicoClawHome)
+ }
+ cfg.Agents.Defaults.Workspace = filepath.Join(homePath, pkg.WorkspaceName)
+ }
+
return cfg, nil
}
+func copyArray[T any](dst, src *[]T) {
+ *dst = make([]T, len(*src))
+ copy(*dst, *src)
+}
+
+// applySecurityConfig resolves all security references in config
+// It checks each field for "ref:" prefixed values and resolves them from .security.yml
+func applySecurityConfig(cfg *Config, sec *SecurityConfig) error {
+ if sec == nil {
+ return nil
+ }
+
+ if sec.Web.Brave != nil && len(sec.Web.Brave.APIKeys) > 0 {
+ copyArray(&cfg.Tools.Web.Brave.apiKeys, &sec.Web.Brave.APIKeys)
+ }
+
+ if sec.Web.Tavily != nil && len(sec.Web.Tavily.APIKeys) > 0 {
+ copyArray(&cfg.Tools.Web.Tavily.apiKeys, &sec.Web.Tavily.APIKeys)
+ }
+
+ if sec.Web.Perplexity != nil && len(sec.Web.Perplexity.APIKeys) > 0 {
+ copyArray(&cfg.Tools.Web.Perplexity.apiKeys, &sec.Web.Perplexity.APIKeys)
+ }
+
+ if sec.Web.GLMSearch != nil && sec.Web.GLMSearch.APIKey != "" {
+ cfg.Tools.Web.GLMSearch.apiKey = sec.Web.GLMSearch.APIKey
+ }
+
+ if sec.Web.BaiduSearch != nil && sec.Web.BaiduSearch.APIKey != "" {
+ cfg.Tools.Web.BaiduSearch.apiKey = sec.Web.BaiduSearch.APIKey
+ }
+
+ if sec.Skills.Github != nil && sec.Skills.Github.Token != "" {
+ cfg.Tools.Skills.Github.token = sec.Skills.Github.Token
+ }
+
+ if sec.Skills.ClawHub != nil && sec.Skills.ClawHub.AuthToken != "" {
+ cfg.Tools.Skills.Registries.ClawHub.authToken = sec.Skills.ClawHub.AuthToken
+ }
+
+ names := toNameIndex(cfg.ModelList)
+ for i, model := range cfg.ModelList {
+ // Try exact match first (e.g., "abc:0" -> "abc:0")
+ if entry, exists := sec.ModelList[names[i]]; exists {
+ copyArray(&model.apiKeys, &entry.APIKeys)
+ model.secModelName = names[i]
+ continue
+ }
+
+ // Try match without index suffix (e.g., "abc" -> "abc")
+ // This allows .security.yml to use simpler keys like "test-model" instead of "test-model:0"
+ baseName := model.ModelName
+ if entry, exists := sec.ModelList[baseName]; exists {
+ copyArray(&model.apiKeys, &entry.APIKeys)
+ model.secModelName = baseName
+ continue
+ }
+ }
+
+ // Handle Telegram token
+ if sec.Channels.Telegram != nil && sec.Channels.Telegram.Token != "" {
+ cfg.Channels.Telegram.token = sec.Channels.Telegram.Token
+ }
+
+ // Handle Feishu credentials
+ if sec.Channels.Feishu != nil {
+ if sec.Channels.Feishu.AppSecret != "" {
+ cfg.Channels.Feishu.appSecret = sec.Channels.Feishu.AppSecret
+ }
+ if sec.Channels.Feishu.EncryptKey != "" {
+ cfg.Channels.Feishu.encryptKey = sec.Channels.Feishu.EncryptKey
+ }
+ if sec.Channels.Feishu.VerificationToken != "" {
+ cfg.Channels.Feishu.verificationToken = sec.Channels.Feishu.VerificationToken
+ }
+ }
+
+ // Handle Discord token
+ if sec.Channels.Discord != nil && sec.Channels.Discord.Token != "" {
+ cfg.Channels.Discord.token = sec.Channels.Discord.Token
+ }
+
+ // Handle Weixin token
+ if sec.Channels.Weixin != nil && sec.Channels.Weixin.Token != "" {
+ cfg.Channels.Discord.token = sec.Channels.Discord.Token
+ }
+
+ // Handle DingTalk client secret
+ if sec.Channels.DingTalk != nil && sec.Channels.DingTalk.ClientSecret != "" {
+ cfg.Channels.DingTalk.clientSecret = sec.Channels.DingTalk.ClientSecret
+ }
+
+ // Handle Slack tokens
+ if sec.Channels.Slack != nil {
+ if sec.Channels.Slack.BotToken != "" {
+ cfg.Channels.Slack.botToken = sec.Channels.Slack.BotToken
+ }
+ if sec.Channels.Slack.AppToken != "" {
+ cfg.Channels.Slack.appToken = sec.Channels.Slack.AppToken
+ }
+ }
+
+ // Handle Matrix access token
+ if sec.Channels.Matrix != nil && sec.Channels.Matrix.AccessToken != "" {
+ cfg.Channels.Matrix.accessToken = sec.Channels.Matrix.AccessToken
+ }
+
+ // Handle LINE credentials
+ if sec.Channels.LINE != nil {
+ if sec.Channels.LINE.ChannelSecret != "" {
+ cfg.Channels.LINE.channelSecret = sec.Channels.LINE.ChannelSecret
+ }
+ if sec.Channels.LINE.ChannelAccessToken != "" {
+ cfg.Channels.LINE.channelAccessToken = sec.Channels.LINE.ChannelAccessToken
+ }
+ }
+
+ // Handle OneBot access token
+ if sec.Channels.OneBot != nil && sec.Channels.OneBot.AccessToken != "" {
+ cfg.Channels.OneBot.accessToken = sec.Channels.OneBot.AccessToken
+ }
+
+ // Handle WeCom token and encoding key
+ if sec.Channels.WeCom != nil {
+ if sec.Channels.WeCom.Token != "" {
+ cfg.Channels.WeCom.token = sec.Channels.WeCom.Token
+ }
+ if sec.Channels.WeCom.EncodingAESKey != "" {
+ cfg.Channels.WeCom.encodingAESKey = sec.Channels.WeCom.EncodingAESKey
+ }
+ }
+
+ // Handle WeCom App credentials
+ if sec.Channels.WeComApp != nil {
+ if sec.Channels.WeComApp.CorpSecret != "" {
+ cfg.Channels.WeComApp.corpSecret = sec.Channels.WeComApp.CorpSecret
+ }
+ if sec.Channels.WeComApp.Token != "" {
+ cfg.Channels.WeComApp.token = sec.Channels.WeComApp.Token
+ }
+ if sec.Channels.WeComApp.EncodingAESKey != "" {
+ cfg.Channels.WeComApp.encodingAESKey = sec.Channels.WeComApp.EncodingAESKey
+ }
+ }
+
+ // Handle WeCom AI Bot credentials
+ if sec.Channels.WeComAIBot != nil {
+ if sec.Channels.WeComAIBot.Token != "" {
+ cfg.Channels.WeComAIBot.token = sec.Channels.WeComAIBot.Token
+ }
+ if sec.Channels.WeComAIBot.EncodingAESKey != "" {
+ cfg.Channels.WeComAIBot.encodingAESKey = sec.Channels.WeComAIBot.EncodingAESKey
+ }
+ if sec.Channels.WeComAIBot.Secret != "" {
+ cfg.Channels.WeComAIBot.secret = sec.Channels.WeComAIBot.Secret
+ }
+ }
+
+ // Handle Pico channel token
+ if sec.Channels.Pico != nil && sec.Channels.Pico.Token != "" {
+ cfg.Channels.Pico.token = sec.Channels.Pico.Token
+ }
+
+ // Handle IRC passwords
+ if sec.Channels.IRC != nil {
+ if sec.Channels.IRC.Password != "" {
+ cfg.Channels.IRC.password = sec.Channels.IRC.Password
+ }
+ if sec.Channels.IRC.NickServPassword != "" {
+ cfg.Channels.IRC.nickServPassword = sec.Channels.IRC.NickServPassword
+ }
+ if sec.Channels.IRC.SASLPassword != "" {
+ cfg.Channels.IRC.saslPassword = sec.Channels.IRC.SASLPassword
+ }
+ }
+
+ // Handle QQ app secret
+ if sec.Channels.QQ != nil && sec.Channels.QQ.AppSecret != "" {
+ cfg.Channels.QQ.appSecret = sec.Channels.QQ.AppSecret
+ }
+
+ cfg.security = sec
+
+ return nil
+}
+
+func toNameIndex(list []*ModelConfig) []string {
+ nameList := make([]string, 0, len(list))
+ countMap := make(map[string]int)
+ for _, model := range list {
+ name := model.ModelName
+ index := countMap[name]
+ nameList = append(nameList, fmt.Sprintf("%s:%d", name, index))
+ countMap[name]++
+ }
+ return nameList
+}
+
// encryptPlaintextAPIKeys returns a copy of models with plaintext api_key values
// encrypted. Returns (nil, nil) when nothing changed (all keys already sealed or
// empty). Returns (nil, error) if any key fails to encrypt — callers must treat
// this as a hard failure to prevent a mixed plaintext/ciphertext state on disk.
// Symmetric counterpart of resolveAPIKeys: both operate purely on []ModelConfig
// and leave JSON marshaling to the caller.
-func encryptPlaintextAPIKeys(models []ModelConfig, passphrase string) ([]ModelConfig, error) {
- sealed := make([]ModelConfig, len(models))
- copy(sealed, models)
+func encryptPlaintextAPIKeys(
+ models map[string]ModelSecurityEntry,
+ passphrase string,
+) (map[string]ModelSecurityEntry, error) {
+ sealed := make(map[string]ModelSecurityEntry, len(models))
changed := false
- for i := range sealed {
- m := &sealed[i]
- if m.APIKey == "" || strings.HasPrefix(m.APIKey, "enc://") || strings.HasPrefix(m.APIKey, "file://") {
- continue
+ for k, m := range models {
+ sealedEntry := ModelSecurityEntry{APIKeys: make([]string, len(m.APIKeys))}
+
+ // Encrypt each key in APIKeys
+ for i, key := range m.APIKeys {
+ if key == "" || strings.HasPrefix(key, "enc://") || strings.HasPrefix(key, "file://") {
+ sealedEntry.APIKeys[i] = key
+ continue
+ }
+ encrypted, err := credential.Encrypt(passphrase, "", key)
+ if err != nil {
+ return nil, fmt.Errorf("cannot seal api_key for model %q: %w", k, err)
+ }
+ sealedEntry.APIKeys[i] = encrypted
+ changed = true
}
- encrypted, err := credential.Encrypt(passphrase, "", m.APIKey)
- if err != nil {
- return nil, fmt.Errorf("cannot seal api_key for model %q: %w", m.ModelName, err)
- }
- m.APIKey = encrypted
- changed = true
+
+ sealed[k] = sealedEntry
}
if !changed {
return nil, nil
@@ -963,24 +1658,22 @@ func encryptPlaintextAPIKeys(models []ModelConfig, passphrase string) ([]ModelCo
// resolveAPIKeys decrypts or dereferences each api_key in models in-place.
// Supports plaintext (no-op), file:// (read from configDir), and enc:// (AES-GCM decrypt).
-// Also resolves api_keys array if present.
-func resolveAPIKeys(models []ModelConfig, configDir string) error {
+func resolveAPIKeys(models []*ModelConfig, configDir string) error {
cr := credential.NewResolver(configDir)
for i := range models {
- // Resolve single APIKey
- resolved, err := cr.Resolve(models[i].APIKey)
- if err != nil {
- return fmt.Errorf("model_list[%d] (%s): %w", i, models[i].ModelName, err)
- }
- models[i].APIKey = resolved
-
// Resolve APIKeys array
- for j, key := range models[i].APIKeys {
+ for j, key := range models[i].apiKeys {
resolved, err := cr.Resolve(key)
if err != nil {
- return fmt.Errorf("model_list[%d] (%s): api_keys[%d]: %w", i, models[i].ModelName, j, err)
+ return fmt.Errorf(
+ "model_list[%d] (%s): api_keys[%d]: %w",
+ i,
+ models[i].ModelName,
+ j,
+ err,
+ )
}
- models[i].APIKeys[j] = resolved
+ models[i].apiKeys[j] = resolved
}
}
return nil
@@ -1000,17 +1693,187 @@ func (c *Config) migrateChannelConfigs() {
}
func SaveConfig(path string, cfg *Config) error {
+ if cfg.security == nil {
+ logger.Errorf("config %#v", *cfg)
+ if len(cfg.ModelList) > 0 {
+ logger.Errorf("model[0] %#v", cfg.ModelList[0])
+ }
+ logger.ErrorC("config", "security is nil")
+ return fmt.Errorf("security is nil")
+ }
+ // Ensure version is always set when saving
+ if cfg.Version == 0 {
+ cfg.Version = CurrentVersion
+ }
+ names := toNameIndex(cfg.ModelList)
+ for i, m := range cfg.ModelList {
+ if m.secDirty {
+ if m.secModelName == "" {
+ m.secModelName = names[i]
+ }
+ cfg.security.ModelList[m.secModelName] = ModelSecurityEntry{
+ APIKeys: m.apiKeys,
+ }
+ m.secDirty = false
+ }
+ }
+ if cfg.Channels.Pico.secDirty {
+ cfg.security.Channels.Pico = &PicoSecurity{
+ Token: cfg.Channels.Pico.Token(),
+ }
+ cfg.Channels.Pico.secDirty = false
+ }
+ if cfg.Channels.IRC.secDirty {
+ cfg.security.Channels.IRC = &IRCSecurity{
+ Password: cfg.Channels.IRC.password,
+ NickServPassword: cfg.Channels.IRC.nickServPassword,
+ SASLPassword: cfg.Channels.IRC.saslPassword,
+ }
+ cfg.Channels.IRC.secDirty = false
+ }
+ if cfg.Channels.Telegram.secDirty {
+ cfg.security.Channels.Telegram = &TelegramSecurity{
+ Token: cfg.Channels.Telegram.Token(),
+ }
+ cfg.Channels.Telegram.secDirty = false
+ }
+ if cfg.Channels.Feishu.secDirty {
+ cfg.security.Channels.Feishu = &FeishuSecurity{
+ AppSecret: cfg.Channels.Feishu.AppSecret(),
+ EncryptKey: cfg.Channels.Feishu.EncryptKey(),
+ VerificationToken: cfg.Channels.Feishu.VerificationToken(),
+ }
+ cfg.Channels.Feishu.secDirty = false
+ }
+ if cfg.Channels.Discord.secDirty {
+ cfg.security.Channels.Discord = &DiscordSecurity{
+ Token: cfg.Channels.Discord.Token(),
+ }
+ cfg.Channels.Discord.secDirty = false
+ }
+ if cfg.Channels.Weixin.secDirty {
+ cfg.security.Channels.Weixin = &WeixinSecurity{
+ Token: cfg.Channels.Weixin.Token(),
+ }
+ cfg.Channels.Discord.secDirty = false
+ }
+ if cfg.Channels.QQ.secDirty {
+ cfg.security.Channels.QQ = &QQSecurity{
+ AppSecret: cfg.Channels.QQ.AppSecret(),
+ }
+ cfg.Channels.QQ.secDirty = false
+ }
+ if cfg.Channels.DingTalk.secDirty {
+ cfg.security.Channels.DingTalk = &DingTalkSecurity{
+ ClientSecret: cfg.Channels.DingTalk.ClientSecret(),
+ }
+ cfg.Channels.DingTalk.secDirty = false
+ }
+ if cfg.Channels.Slack.secDirty {
+ cfg.security.Channels.Slack = &SlackSecurity{
+ BotToken: cfg.Channels.Slack.BotToken(),
+ AppToken: cfg.Channels.Slack.AppToken(),
+ }
+ cfg.Channels.Slack.secDirty = false
+ }
+ if cfg.Channels.Matrix.secDirty {
+ cfg.security.Channels.Matrix = &MatrixSecurity{
+ AccessToken: cfg.Channels.Matrix.AccessToken(),
+ }
+ cfg.Channels.Matrix.secDirty = false
+ }
+ if cfg.Channels.LINE.secDirty {
+ cfg.security.Channels.LINE = &LINESecurity{
+ ChannelSecret: cfg.Channels.LINE.ChannelSecret(),
+ ChannelAccessToken: cfg.Channels.LINE.ChannelAccessToken(),
+ }
+ cfg.Channels.LINE.secDirty = false
+ }
+ if cfg.Channels.OneBot.secDirty {
+ cfg.security.Channels.OneBot = &OneBotSecurity{
+ AccessToken: cfg.Channels.OneBot.AccessToken(),
+ }
+ cfg.Channels.OneBot.secDirty = false
+ }
+ if cfg.Channels.WeCom.secDirty {
+ cfg.security.Channels.WeCom = &WeComSecurity{
+ Token: cfg.Channels.WeCom.Token(),
+ EncodingAESKey: cfg.Channels.WeCom.EncodingAESKey(),
+ }
+ cfg.Channels.WeCom.secDirty = false
+ }
+ if cfg.Channels.WeComApp.secDirty {
+ cfg.security.Channels.WeComApp = &WeComAppSecurity{
+ CorpSecret: cfg.Channels.WeComApp.CorpSecret(),
+ Token: cfg.Channels.WeComApp.Token(),
+ EncodingAESKey: cfg.Channels.WeComApp.EncodingAESKey(),
+ }
+ cfg.Channels.WeComApp.secDirty = false
+ }
+ if cfg.Channels.WeComAIBot.secDirty {
+ cfg.security.Channels.WeComAIBot = &WeComAIBotSecurity{
+ Token: cfg.Channels.WeComAIBot.Token(),
+ EncodingAESKey: cfg.Channels.WeComAIBot.EncodingAESKey(),
+ Secret: cfg.Channels.WeComAIBot.Secret(),
+ }
+ cfg.Channels.WeComAIBot.secDirty = false
+ }
+ if cfg.Tools.Web.Brave.secDirty {
+ cfg.security.Web.Brave = &BraveSecurity{
+ APIKeys: cfg.Tools.Web.Brave.APIKeys(),
+ }
+ cfg.Tools.Web.Brave.secDirty = false
+ }
+ if cfg.Tools.Web.Tavily.secDirty {
+ cfg.security.Web.Tavily = &TavilySecurity{
+ APIKeys: cfg.Tools.Web.Tavily.APIKeys(),
+ }
+ cfg.Tools.Web.Tavily.secDirty = false
+ }
+ if cfg.Tools.Web.Perplexity.secDirty {
+ cfg.security.Web.Perplexity = &PerplexitySecurity{
+ APIKeys: cfg.Tools.Web.Perplexity.APIKeys(),
+ }
+ cfg.Tools.Web.Perplexity.secDirty = false
+ }
+ if cfg.Tools.Web.GLMSearch.secDirty {
+ cfg.security.Web.GLMSearch = &GLMSearchSecurity{
+ APIKey: cfg.Tools.Web.GLMSearch.APIKey(),
+ }
+ cfg.Tools.Web.GLMSearch.secDirty = false
+ }
+ if cfg.Tools.Web.BaiduSearch.secDirty {
+ cfg.security.Web.BaiduSearch = &BaiduSearchSecurity{
+ APIKey: cfg.Tools.Web.BaiduSearch.APIKey(),
+ }
+ cfg.Tools.Web.BaiduSearch.secDirty = false
+ }
+ if cfg.Tools.Skills.Github.secDirty {
+ cfg.security.Skills.Github = &GithubSecurity{
+ Token: cfg.Tools.Skills.Github.Token(),
+ }
+ cfg.Tools.Skills.Github.secDirty = false
+ }
+ if cfg.Tools.Skills.Registries.ClawHub.secDirty {
+ cfg.security.Skills.ClawHub = &ClawHubSecurity{
+ AuthToken: cfg.Tools.Skills.Registries.ClawHub.AuthToken(),
+ }
+ cfg.Tools.Skills.Registries.ClawHub.secDirty = false
+ }
+
if passphrase := credential.PassphraseProvider(); passphrase != "" {
- sealed, err := encryptPlaintextAPIKeys(cfg.ModelList, passphrase)
+ sealed, err := encryptPlaintextAPIKeys(cfg.security.ModelList, passphrase)
if err != nil {
return err
}
if sealed != nil {
- tmp := *cfg
- tmp.ModelList = sealed
- cfg = &tmp
+ cfg.security.ModelList = sealed
}
}
+ if err := saveSecurityConfig(securityPath(path), cfg.security); err != nil {
+ logger.ErrorCF("config", "cannot save .security.yml", map[string]any{"error": err})
+ return err
+ }
data, err := json.MarshalIndent(cfg, "", " ")
if err != nil {
@@ -1023,53 +1886,6 @@ func (c *Config) WorkspacePath() string {
return expandHome(c.Agents.Defaults.Workspace)
}
-func (c *Config) GetAPIKey() string {
- if c.Providers.OpenRouter.APIKey != "" {
- return c.Providers.OpenRouter.APIKey
- }
- if c.Providers.Anthropic.APIKey != "" {
- return c.Providers.Anthropic.APIKey
- }
- if c.Providers.OpenAI.APIKey != "" {
- return c.Providers.OpenAI.APIKey
- }
- if c.Providers.Gemini.APIKey != "" {
- return c.Providers.Gemini.APIKey
- }
- if c.Providers.Zhipu.APIKey != "" {
- return c.Providers.Zhipu.APIKey
- }
- if c.Providers.Groq.APIKey != "" {
- return c.Providers.Groq.APIKey
- }
- if c.Providers.VLLM.APIKey != "" {
- return c.Providers.VLLM.APIKey
- }
- if c.Providers.ShengSuanYun.APIKey != "" {
- return c.Providers.ShengSuanYun.APIKey
- }
- if c.Providers.Cerebras.APIKey != "" {
- return c.Providers.Cerebras.APIKey
- }
- return ""
-}
-
-func (c *Config) GetAPIBase() string {
- if c.Providers.OpenRouter.APIKey != "" {
- if c.Providers.OpenRouter.APIBase != "" {
- return c.Providers.OpenRouter.APIBase
- }
- return "https://openrouter.ai/api/v1"
- }
- if c.Providers.Zhipu.APIKey != "" {
- return c.Providers.Zhipu.APIBase
- }
- if c.Providers.VLLM.APIKey != "" && c.Providers.VLLM.APIBase != "" {
- return c.Providers.VLLM.APIBase
- }
- return ""
-}
-
func expandHome(path string) string {
if path == "" {
return path
@@ -1093,17 +1909,17 @@ func (c *Config) GetModelConfig(modelName string) (*ModelConfig, error) {
return nil, fmt.Errorf("model %q not found in model_list or providers", modelName)
}
if len(matches) == 1 {
- return &matches[0], nil
+ return matches[0], nil
}
// Multiple configs - use round-robin for load balancing
idx := (rrCounter.Add(1) - 1) % uint64(len(matches))
- return &matches[idx], nil
+ return matches[idx], nil
}
// findMatches finds all ModelConfig entries with the given model_name.
-func (c *Config) findMatches(modelName string) []ModelConfig {
- var matches []ModelConfig
+func (c *Config) findMatches(modelName string) []*ModelConfig {
+ var matches []*ModelConfig
for i := range c.ModelList {
if c.ModelList[i].ModelName == modelName {
matches = append(matches, c.ModelList[i])
@@ -1112,11 +1928,6 @@ func (c *Config) findMatches(modelName string) []ModelConfig {
return matches
}
-// HasProvidersConfig checks if any provider in the old providers config has configuration.
-func (c *Config) HasProvidersConfig() bool {
- return !c.Providers.IsEmpty()
-}
-
// ValidateModelList validates all ModelConfig entries in the model_list.
// It checks that each model config is valid.
// Note: Multiple entries with the same model_name are allowed for load balancing.
@@ -1129,6 +1940,10 @@ func (c *Config) ValidateModelList() error {
return nil
}
+func (c *Config) SecurityCopyFrom(cfg *Config) {
+ c.security = cfg.security
+}
+
func MergeAPIKeys(apiKey string, apiKeys []string) []string {
seen := make(map[string]struct{})
var all []string
@@ -1152,28 +1967,92 @@ func MergeAPIKeys(apiKey string, apiKeys []string) []string {
return all
}
-// ExpandMultiKeyModels expands ModelConfig entries with multiple API keys into
+// resolveSecurityFields resolves file:// and enc:// references in security-sensitive fields
+// like authToken and token that are not part of ModelConfig's apiKeys
+func resolveSecurityFields(cfg *Config, configDir string) error {
+ cr := credential.NewResolver(configDir)
+
+ // Resolve Web tool API keys - set apiKey field to first resolved apiKeys entry
+ if len(cfg.Tools.Web.Brave.apiKeys) > 0 {
+ keys := cfg.Tools.Web.Brave.apiKeys
+ for i, key := range keys {
+ resolved, err := cr.Resolve(key)
+ if err != nil {
+ return fmt.Errorf("brave api_keys[%d]: %w", i, err)
+ }
+ keys[i] = resolved
+ }
+ }
+
+ if len(cfg.Tools.Web.Tavily.apiKeys) > 0 {
+ keys := cfg.Tools.Web.Tavily.apiKeys
+ for i, key := range keys {
+ resolved, err := cr.Resolve(key)
+ if err != nil {
+ return fmt.Errorf("tavily api_keys[%d]: %w", i, err)
+ }
+ keys[i] = resolved
+ }
+ }
+
+ if len(cfg.Tools.Web.Perplexity.apiKeys) > 0 {
+ keys := cfg.Tools.Web.Perplexity.apiKeys
+ for i, key := range keys {
+ resolved, err := cr.Resolve(key)
+ if err != nil {
+ return fmt.Errorf("perplexity api_keys[%d]: %w", i, err)
+ }
+ keys[i] = resolved
+ }
+ }
+
+ // GLMSearch has a private apiKey field
+ if cfg.Tools.Web.GLMSearch.apiKey != "" {
+ resolved, err := cr.Resolve(cfg.Tools.Web.GLMSearch.apiKey)
+ if err != nil {
+ return fmt.Errorf("glm api_key: %w", err)
+ }
+ cfg.Tools.Web.GLMSearch.apiKey = resolved
+ }
+
+ // Resolve Skills tokens
+ if cfg.Tools.Skills.Github.token != "" {
+ resolved, err := cr.Resolve(cfg.Tools.Skills.Github.token)
+ if err != nil {
+ return fmt.Errorf("github token: %w", err)
+ }
+ cfg.Tools.Skills.Github.token = resolved
+ }
+
+ if cfg.Tools.Skills.Registries.ClawHub.authToken != "" {
+ resolved, err := cr.Resolve(cfg.Tools.Skills.Registries.ClawHub.authToken)
+ if err != nil {
+ return fmt.Errorf("clawhub auth_token: %w", err)
+ }
+ cfg.Tools.Skills.Registries.ClawHub.authToken = resolved
+ }
+
+ return nil
+}
+
+// expandMultiKeyModels expands ModelConfig entries with multiple API keys into
// separate entries for key-level failover. Each key gets its own ModelConfig entry,
// and the original entry's fallbacks are set up to chain through the expanded entries.
//
// Example: {"model_name": "gpt-4", "api_keys": ["k1", "k2", "k3"]}
// Becomes:
-// - {"model_name": "gpt-4", "api_key": "k1", "fallbacks": ["gpt-4__key_1", "gpt-4__key_2"]}
-// - {"model_name": "gpt-4__key_1", "api_key": "k2"}
-// - {"model_name": "gpt-4__key_2", "api_key": "k3"}
-func ExpandMultiKeyModels(models []ModelConfig) []ModelConfig {
- var expanded []ModelConfig
+// - {"model_name": "gpt-4", "api_keys": ["k1"], "fallbacks": ["gpt-4__key_1", "gpt-4__key_2"]}
+// - {"model_name": "gpt-4__key_1", "api_keys": {"k2"}}
+// - {"model_name": "gpt-4__key_2", "api_keys": {"k3"}}
+func expandMultiKeyModels(models []*ModelConfig) []*ModelConfig {
+ var expanded []*ModelConfig
for _, m := range models {
- keys := MergeAPIKeys(m.APIKey, m.APIKeys)
+ keys := MergeAPIKeys("", m.apiKeys)
// Single key or no keys: keep as-is
if len(keys) <= 1 {
- // Ensure APIKey is set from APIKeys if needed
- if m.APIKey == "" && len(keys) == 1 {
- m.APIKey = keys[0]
- }
- m.APIKeys = nil // Clear APIKeys to avoid confusion
+ m.apiKeys = keys
expanded = append(expanded, m)
continue
}
@@ -1188,11 +2067,11 @@ func ExpandMultiKeyModels(models []ModelConfig) []ModelConfig {
expandedName := originalName + suffix
// Create a copy for the additional key
- additionalEntry := ModelConfig{
+ additionalEntry := &ModelConfig{
ModelName: expandedName,
Model: m.Model,
APIBase: m.APIBase,
- APIKey: keys[i],
+ apiKeys: []string{keys[i]},
Proxy: m.Proxy,
AuthMethod: m.AuthMethod,
ConnectMode: m.ConnectMode,
@@ -1201,17 +2080,17 @@ func ExpandMultiKeyModels(models []ModelConfig) []ModelConfig {
MaxTokensField: m.MaxTokensField,
RequestTimeout: m.RequestTimeout,
ThinkingLevel: m.ThinkingLevel,
+ ExtraBody: m.ExtraBody,
}
expanded = append(expanded, additionalEntry)
fallbackNames = append(fallbackNames, expandedName)
}
// Create the primary entry with first key and fallbacks
- primaryEntry := ModelConfig{
+ primaryEntry := &ModelConfig{
ModelName: originalName,
Model: m.Model,
APIBase: m.APIBase,
- APIKey: keys[0],
Proxy: m.Proxy,
AuthMethod: m.AuthMethod,
ConnectMode: m.ConnectMode,
@@ -1220,6 +2099,8 @@ func ExpandMultiKeyModels(models []ModelConfig) []ModelConfig {
MaxTokensField: m.MaxTokensField,
RequestTimeout: m.RequestTimeout,
ThinkingLevel: m.ThinkingLevel,
+ ExtraBody: m.ExtraBody,
+ apiKeys: []string{keys[0]},
}
// Prepend new fallbacks to existing ones
diff --git a/pkg/config/config_old.go b/pkg/config/config_old.go
new file mode 100644
index 000000000..c7c7f0028
--- /dev/null
+++ b/pkg/config/config_old.go
@@ -0,0 +1,1032 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import "encoding/json"
+
+type agentDefaultsV0 struct {
+ Workspace string `json:"workspace" env:"PICOCLAW_AGENTS_DEFAULTS_WORKSPACE"`
+ RestrictToWorkspace bool `json:"restrict_to_workspace" env:"PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE"`
+ AllowReadOutsideWorkspace bool `json:"allow_read_outside_workspace" env:"PICOCLAW_AGENTS_DEFAULTS_ALLOW_READ_OUTSIDE_WORKSPACE"`
+ Provider string `json:"provider" env:"PICOCLAW_AGENTS_DEFAULTS_PROVIDER"`
+ ModelName string `json:"model_name,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME"`
+ Model string `json:"model" env:"PICOCLAW_AGENTS_DEFAULTS_MODEL"` // Deprecated: use model_name instead
+ ModelFallbacks []string `json:"model_fallbacks,omitempty"`
+ ImageModel string `json:"image_model,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_IMAGE_MODEL"`
+ ImageModelFallbacks []string `json:"image_model_fallbacks,omitempty"`
+ MaxTokens int `json:"max_tokens" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOKENS"`
+ Temperature *float64 `json:"temperature,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE"`
+ MaxToolIterations int `json:"max_tool_iterations" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS"`
+ SummarizeMessageThreshold int `json:"summarize_message_threshold" env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_MESSAGE_THRESHOLD"`
+ SummarizeTokenPercent int `json:"summarize_token_percent" env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_TOKEN_PERCENT"`
+ MaxMediaSize int `json:"max_media_size,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_MEDIA_SIZE"`
+ Routing *RoutingConfig `json:"routing,omitempty"`
+}
+
+// GetModelName returns the effective model name for the agent defaults.
+// It prefers the new "model_name" field but falls back to "model" for backward compatibility.
+func (d *agentDefaultsV0) GetModelName() string {
+ if d.ModelName != "" {
+ return d.ModelName
+ }
+ return d.Model
+}
+
+type agentsConfigV0 struct {
+ Defaults agentDefaultsV0 `json:"defaults"`
+ List []AgentConfig `json:"list,omitempty"`
+}
+
+// configV0 represents the config structure before versioning was introduced.
+// This struct is used for loading legacy config files (version 0).
+// It is unexported since it's only used internally for migration.
+type configV0 struct {
+ Agents agentsConfigV0 `json:"agents"`
+ Bindings []AgentBinding `json:"bindings,omitempty"`
+ Session SessionConfig `json:"session,omitempty"`
+ Channels channelsConfigV0 `json:"channels"`
+ Providers providersConfigV0 `json:"providers,omitempty"`
+ ModelList []modelConfigV0 `json:"model_list"`
+ Gateway GatewayConfig `json:"gateway"`
+ Tools toolsConfigV0 `json:"tools"`
+ Heartbeat HeartbeatConfig `json:"heartbeat"`
+ Devices DevicesConfig `json:"devices"`
+}
+
+type toolsConfigV0 struct {
+ AllowReadPaths []string `json:"allow_read_paths" env:"PICOCLAW_TOOLS_ALLOW_READ_PATHS"`
+ AllowWritePaths []string `json:"allow_write_paths" env:"PICOCLAW_TOOLS_ALLOW_WRITE_PATHS"`
+ Web webToolsConfigV0 `json:"web"`
+ Cron CronToolsConfig `json:"cron"`
+ Exec ExecConfig `json:"exec"`
+ Skills skillsToolsConfigV0 `json:"skills"`
+ MediaCleanup MediaCleanupConfig `json:"media_cleanup"`
+ MCP MCPConfig `json:"mcp"`
+ AppendFile ToolConfig `json:"append_file" envPrefix:"PICOCLAW_TOOLS_APPEND_FILE_"`
+ EditFile ToolConfig `json:"edit_file" envPrefix:"PICOCLAW_TOOLS_EDIT_FILE_"`
+ FindSkills ToolConfig `json:"find_skills" envPrefix:"PICOCLAW_TOOLS_FIND_SKILLS_"`
+ I2C ToolConfig `json:"i2c" envPrefix:"PICOCLAW_TOOLS_I2C_"`
+ InstallSkill ToolConfig `json:"install_skill" envPrefix:"PICOCLAW_TOOLS_INSTALL_SKILL_"`
+ ListDir ToolConfig `json:"list_dir" envPrefix:"PICOCLAW_TOOLS_LIST_DIR_"`
+ Message ToolConfig `json:"message" envPrefix:"PICOCLAW_TOOLS_MESSAGE_"`
+ ReadFile ReadFileToolConfig `json:"read_file" envPrefix:"PICOCLAW_TOOLS_READ_FILE_"`
+ SendFile ToolConfig `json:"send_file" envPrefix:"PICOCLAW_TOOLS_SEND_FILE_"`
+ Spawn ToolConfig `json:"spawn" envPrefix:"PICOCLAW_TOOLS_SPAWN_"`
+ SpawnStatus ToolConfig `json:"spawn_status" envPrefix:"PICOCLAW_TOOLS_SPAWN_STATUS_"`
+ SPI ToolConfig `json:"spi" envPrefix:"PICOCLAW_TOOLS_SPI_"`
+ Subagent ToolConfig `json:"subagent" envPrefix:"PICOCLAW_TOOLS_SUBAGENT_"`
+ WebFetch ToolConfig `json:"web_fetch" envPrefix:"PICOCLAW_TOOLS_WEB_FETCH_"`
+ WriteFile ToolConfig `json:"write_file" envPrefix:"PICOCLAW_TOOLS_WRITE_FILE_"`
+}
+
+type channelsConfigV0 struct {
+ WhatsApp WhatsAppConfig `json:"whatsapp"`
+ Telegram telegramConfigV0 `json:"telegram"`
+ Feishu feishuConfigV0 `json:"feishu"`
+ Discord discordConfigV0 `json:"discord"`
+ MaixCam maixcamConfigV0 `json:"maixcam"`
+ Weixin weixinConfigV0 `json:"weixin"`
+ QQ qqConfigV0 `json:"qq"`
+ DingTalk dingtalkConfigV0 `json:"dingtalk"`
+ Slack slackConfigV0 `json:"slack"`
+ Matrix matrixConfigV0 `json:"matrix"`
+ LINE lineConfigV0 `json:"line"`
+ OneBot onebotConfigV0 `json:"onebot"`
+ WeCom wecomConfigV0 `json:"wecom"`
+ WeComApp wecomappConfigV0 `json:"wecom_app"`
+ WeComAIBot wecomaibotConfigV0 `json:"wecom_aibot"`
+ Pico picoConfigV0 `json:"pico"`
+ IRC ircConfigV0 `json:"irc"`
+}
+
+func (v *channelsConfigV0) ToChannelsConfig() (ChannelsConfig, ChannelsSecurity) {
+ telegram, telegramSecurity := v.Telegram.ToTelegramConfig()
+ feishu, feishuSecurity := v.Feishu.ToFeishuConfig()
+ discord, discordSecurity := v.Discord.ToDiscordConfig()
+ maixcam := v.MaixCam.ToMaixCamConfig()
+ qq, qqSecurity := v.QQ.ToQQConfig()
+ weixin, weixinSecurity := v.Weixin.ToWeiXinConfig()
+ dingtalk, dingtalkSecurity := v.DingTalk.ToDingTalkConfig()
+ slack, slackSecurity := v.Slack.ToSlackConfig()
+ matrix, matrixSecurity := v.Matrix.ToMatrixConfig()
+ line, lineSecurity := v.LINE.ToLINEConfig()
+ onebot, onebotSecurity := v.OneBot.ToOneBotConfig()
+ wecom, wecomSecurity := v.WeCom.ToWeComConfig()
+ wecomapp, wecomappSecurity := v.WeComApp.ToWeComAppConfig()
+ wecomaibot, wecomaibotSecurity := v.WeComAIBot.ToWeComAIBotConfig()
+ pico, picoSecurity := v.Pico.ToPicoConfig()
+ irc, ircSecurity := v.IRC.ToIRCConfig()
+
+ return ChannelsConfig{
+ WhatsApp: v.WhatsApp,
+ Telegram: telegram,
+ Feishu: feishu,
+ Discord: discord,
+ MaixCam: maixcam,
+ QQ: qq,
+ Weixin: weixin,
+ DingTalk: dingtalk,
+ Slack: slack,
+ Matrix: matrix,
+ LINE: line,
+ OneBot: onebot,
+ WeCom: wecom,
+ WeComApp: wecomapp,
+ WeComAIBot: wecomaibot,
+ Pico: pico,
+ IRC: irc,
+ }, ChannelsSecurity{
+ Telegram: &telegramSecurity,
+ Feishu: &feishuSecurity,
+ Discord: &discordSecurity,
+ QQ: &qqSecurity,
+ Weixin: &weixinSecurity,
+ DingTalk: &dingtalkSecurity,
+ Slack: &slackSecurity,
+ Matrix: &matrixSecurity,
+ LINE: &lineSecurity,
+ OneBot: &onebotSecurity,
+ WeCom: &wecomSecurity,
+ WeComApp: &wecomappSecurity,
+ WeComAIBot: &wecomaibotSecurity,
+ Pico: &picoSecurity,
+ IRC: &ircSecurity,
+ }
+}
+
+type qqConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_QQ_ENABLED"`
+ AppID string `json:"app_id" env:"PICOCLAW_CHANNELS_QQ_APP_ID"`
+ AppSecret string `json:"app_secret" env:"PICOCLAW_CHANNELS_QQ_APP_SECRET"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_QQ_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ MaxMessageLength int `json:"max_message_length" env:"PICOCLAW_CHANNELS_QQ_MAX_MESSAGE_LENGTH"`
+ MaxBase64FileSizeMiB int64 `json:"max_base64_file_size_mib" env:"PICOCLAW_CHANNELS_QQ_MAX_BASE64_FILE_SIZE_MIB"`
+ SendMarkdown bool `json:"send_markdown" env:"PICOCLAW_CHANNELS_QQ_SEND_MARKDOWN"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_QQ_REASONING_CHANNEL_ID"`
+}
+
+func (v *qqConfigV0) ToQQConfig() (QQConfig, QQSecurity) {
+ return QQConfig{
+ Enabled: v.Enabled,
+ AppID: v.AppID,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ MaxMessageLength: v.MaxMessageLength,
+ MaxBase64FileSizeMiB: v.MaxBase64FileSizeMiB,
+ SendMarkdown: v.SendMarkdown,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, QQSecurity{
+ AppSecret: v.AppSecret,
+ }
+}
+
+type telegramConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
+ BaseURL string `json:"base_url" env:"PICOCLAW_CHANNELS_TELEGRAM_BASE_URL"`
+ Proxy string `json:"proxy" env:"PICOCLAW_CHANNELS_TELEGRAM_PROXY"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_TELEGRAM_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ Typing TypingConfig `json:"typing,omitempty"`
+ Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_TELEGRAM_REASONING_CHANNEL_ID"`
+ UseMarkdownV2 bool `json:"use_markdown_v2" env:"PICOCLAW_CHANNELS_TELEGRAM_USE_MARKDOWN_V2"`
+}
+
+func (v *telegramConfigV0) ToTelegramConfig() (TelegramConfig, TelegramSecurity) {
+ return TelegramConfig{
+ Enabled: v.Enabled,
+ token: v.Token,
+ BaseURL: v.BaseURL,
+ Proxy: v.Proxy,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ Typing: v.Typing,
+ Placeholder: v.Placeholder,
+ ReasoningChannelID: v.ReasoningChannelID,
+ UseMarkdownV2: v.UseMarkdownV2,
+ }, TelegramSecurity{
+ Token: v.Token,
+ }
+}
+
+type feishuConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
+ AppID string `json:"app_id" env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
+ AppSecret string `json:"app_secret" env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
+ EncryptKey string `json:"encrypt_key" env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
+ VerificationToken string `json:"verification_token" env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_FEISHU_REASONING_CHANNEL_ID"`
+ RandomReactionEmoji FlexibleStringSlice `json:"random_reaction_emoji" env:"PICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJI"`
+ IsLark bool `json:"is_lark" env:"PICOCLAW_CHANNELS_FEISHU_IS_LARK"`
+}
+
+func (v *feishuConfigV0) ToFeishuConfig() (FeishuConfig, FeishuSecurity) {
+ return FeishuConfig{
+ Enabled: v.Enabled,
+ AppID: v.AppID,
+ appSecret: v.AppSecret,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ Placeholder: v.Placeholder,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, FeishuSecurity{
+ AppSecret: v.AppSecret,
+ EncryptKey: v.EncryptKey,
+ VerificationToken: v.VerificationToken,
+ }
+}
+
+type discordConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
+ Proxy string `json:"proxy" env:"PICOCLAW_CHANNELS_DISCORD_PROXY"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_DISCORD_ALLOW_FROM"`
+ MentionOnly bool `json:"mention_only" env:"PICOCLAW_CHANNELS_DISCORD_MENTION_ONLY"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ Typing TypingConfig `json:"typing,omitempty"`
+ Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_DISCORD_REASONING_CHANNEL_ID"`
+}
+
+func (v *discordConfigV0) ToDiscordConfig() (DiscordConfig, DiscordSecurity) {
+ return DiscordConfig{
+ Enabled: v.Enabled,
+ token: v.Token,
+ Proxy: v.Proxy,
+ AllowFrom: v.AllowFrom,
+ MentionOnly: v.MentionOnly,
+ GroupTrigger: v.GroupTrigger,
+ Typing: v.Typing,
+ Placeholder: v.Placeholder,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, DiscordSecurity{
+ Token: v.Token,
+ }
+}
+
+type maixcamConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_MAIXCAM_ENABLED"`
+ Host string `json:"host" env:"PICOCLAW_CHANNELS_MAIXCAM_HOST"`
+ Port int `json:"port" env:"PICOCLAW_CHANNELS_MAIXCAM_PORT"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_MAIXCAM_ALLOW_FROM"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_MAIXCAM_REASONING_CHANNEL_ID"`
+}
+
+func (v *maixcamConfigV0) ToMaixCamConfig() MaixCamConfig {
+ return MaixCamConfig{
+ Enabled: v.Enabled,
+ Host: v.Host,
+ Port: v.Port,
+ AllowFrom: v.AllowFrom,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }
+}
+
+type dingtalkConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_DINGTALK_ENABLED"`
+ ClientID string `json:"client_id" env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_ID"`
+ ClientSecret string `json:"client_secret" env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_SECRET"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_DINGTALK_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_DINGTALK_REASONING_CHANNEL_ID"`
+}
+
+func (v *dingtalkConfigV0) ToDingTalkConfig() (DingTalkConfig, DingTalkSecurity) {
+ return DingTalkConfig{
+ Enabled: v.Enabled,
+ ClientID: v.ClientID,
+ clientSecret: v.ClientSecret,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, DingTalkSecurity{
+ ClientSecret: v.ClientSecret,
+ }
+}
+
+type slackConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_SLACK_ENABLED"`
+ BotToken string `json:"bot_token" env:"PICOCLAW_CHANNELS_SLACK_BOT_TOKEN"`
+ AppToken string `json:"app_token" env:"PICOCLAW_CHANNELS_SLACK_APP_TOKEN"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_SLACK_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ Typing TypingConfig `json:"typing,omitempty"`
+ Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_SLACK_REASONING_CHANNEL_ID"`
+}
+
+func (v *slackConfigV0) ToSlackConfig() (SlackConfig, SlackSecurity) {
+ return SlackConfig{
+ Enabled: v.Enabled,
+ botToken: v.BotToken,
+ appToken: v.AppToken,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ Typing: v.Typing,
+ Placeholder: v.Placeholder,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, SlackSecurity{
+ BotToken: v.BotToken,
+ AppToken: v.AppToken,
+ }
+}
+
+type matrixConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_MATRIX_ENABLED"`
+ Homeserver string `json:"homeserver" env:"PICOCLAW_CHANNELS_MATRIX_HOMESERVER"`
+ UserID string `json:"user_id" env:"PICOCLAW_CHANNELS_MATRIX_USER_ID"`
+ AccessToken string `json:"access_token" env:"PICOCLAW_CHANNELS_MATRIX_ACCESS_TOKEN"`
+ DeviceID string `json:"device_id,omitempty" env:"PICOCLAW_CHANNELS_MATRIX_DEVICE_ID"`
+ JoinOnInvite bool `json:"join_on_invite" env:"PICOCLAW_CHANNELS_MATRIX_JOIN_ON_INVITE"`
+ MessageFormat string `json:"message_format,omitempty" env:"PICOCLAW_CHANNELS_MATRIX_MESSAGE_FORMAT"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_MATRIX_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_MATRIX_REASONING_CHANNEL_ID"`
+}
+
+func (v *matrixConfigV0) ToMatrixConfig() (MatrixConfig, MatrixSecurity) {
+ return MatrixConfig{
+ Enabled: v.Enabled,
+ Homeserver: v.Homeserver,
+ UserID: v.UserID,
+ accessToken: v.AccessToken,
+ DeviceID: v.DeviceID,
+ JoinOnInvite: v.JoinOnInvite,
+ MessageFormat: v.MessageFormat,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ Placeholder: v.Placeholder,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, MatrixSecurity{
+ AccessToken: v.AccessToken,
+ }
+}
+
+type lineConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_LINE_ENABLED"`
+ ChannelSecret string `json:"channel_secret" env:"PICOCLAW_CHANNELS_LINE_CHANNEL_SECRET"`
+ ChannelAccessToken string `json:"channel_access_token" env:"PICOCLAW_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN"`
+ WebhookHost string `json:"webhook_host" env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_HOST"`
+ WebhookPort int `json:"webhook_port" env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_PORT"`
+ WebhookPath string `json:"webhook_path" env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_PATH"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_LINE_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ Typing TypingConfig `json:"typing,omitempty"`
+ Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_LINE_REASONING_CHANNEL_ID"`
+}
+
+func (v *lineConfigV0) ToLINEConfig() (LINEConfig, LINESecurity) {
+ return LINEConfig{
+ Enabled: v.Enabled,
+ channelSecret: v.ChannelSecret,
+ channelAccessToken: v.ChannelAccessToken,
+ WebhookHost: v.WebhookHost,
+ WebhookPort: v.WebhookPort,
+ WebhookPath: v.WebhookPath,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ Typing: v.Typing,
+ Placeholder: v.Placeholder,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, LINESecurity{
+ ChannelSecret: v.ChannelSecret,
+ ChannelAccessToken: v.ChannelAccessToken,
+ }
+}
+
+type onebotConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_ONEBOT_ENABLED"`
+ WSUrl string `json:"ws_url" env:"PICOCLAW_CHANNELS_ONEBOT_WS_URL"`
+ AccessToken string `json:"access_token" env:"PICOCLAW_CHANNELS_ONEBOT_ACCESS_TOKEN"`
+ ReconnectInterval int `json:"reconnect_interval" env:"PICOCLAW_CHANNELS_ONEBOT_RECONNECT_INTERVAL"`
+ GroupTriggerPrefix []string `json:"group_trigger_prefix" env:"PICOCLAW_CHANNELS_ONEBOT_GROUP_TRIGGER_PREFIX"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_ONEBOT_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ Typing TypingConfig `json:"typing,omitempty"`
+ Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_ONEBOT_REASONING_CHANNEL_ID"`
+}
+
+func (v *onebotConfigV0) ToOneBotConfig() (OneBotConfig, OneBotSecurity) {
+ return OneBotConfig{
+ Enabled: v.Enabled,
+ WSUrl: v.WSUrl,
+ accessToken: v.AccessToken,
+ ReconnectInterval: v.ReconnectInterval,
+ GroupTriggerPrefix: v.GroupTriggerPrefix,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ Typing: v.Typing,
+ Placeholder: v.Placeholder,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, OneBotSecurity{
+ AccessToken: v.AccessToken,
+ }
+}
+
+type wecomConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_ENABLED"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_WECOM_TOKEN"`
+ EncodingAESKey string `json:"encoding_aes_key" env:"PICOCLAW_CHANNELS_WECOM_ENCODING_AES_KEY"`
+ WebhookURL string `json:"webhook_url" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_URL"`
+ WebhookHost string `json:"webhook_host" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_HOST"`
+ WebhookPort int `json:"webhook_port" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_PORT"`
+ WebhookPath string `json:"webhook_path" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_PATH"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WECOM_ALLOW_FROM"`
+ ReplyTimeout int `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_REPLY_TIMEOUT"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_REASONING_CHANNEL_ID"`
+}
+
+func (v *wecomConfigV0) ToWeComConfig() (WeComConfig, WeComSecurity) {
+ return WeComConfig{
+ Enabled: v.Enabled,
+ token: v.Token,
+ encodingAESKey: v.EncodingAESKey,
+ WebhookURL: v.WebhookURL,
+ WebhookHost: v.WebhookHost,
+ WebhookPort: v.WebhookPort,
+ WebhookPath: v.WebhookPath,
+ AllowFrom: v.AllowFrom,
+ ReplyTimeout: v.ReplyTimeout,
+ GroupTrigger: v.GroupTrigger,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, WeComSecurity{
+ Token: v.Token,
+ EncodingAESKey: v.EncodingAESKey,
+ }
+}
+
+type weixinConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WEIXIN_ENABLED"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_WEIXIN_TOKEN"`
+ BaseURL string `json:"base_url" env:"PICOCLAW_CHANNELS_WEIXIN_BASE_URL"`
+ CDNBaseURL string `json:"cdn_base_url" env:"PICOCLAW_CHANNELS_WEIXIN_CDN_BASE_URL"`
+ Proxy string `json:"proxy" env:"PICOCLAW_CHANNELS_WEIXIN_PROXY"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WEIXIN_ALLOW_FROM"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WEIXIN_REASONING_CHANNEL_ID"`
+}
+
+func (v *weixinConfigV0) ToWeiXinConfig() (WeixinConfig, WeixinSecurity) {
+ return WeixinConfig{
+ Enabled: v.Enabled,
+ token: v.Token,
+ BaseURL: v.BaseURL,
+ CDNBaseURL: v.CDNBaseURL,
+ Proxy: v.Proxy,
+ AllowFrom: v.AllowFrom,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, WeixinSecurity{
+ Token: v.Token,
+ }
+}
+
+type wecomappConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_APP_ENABLED"`
+ CorpID string `json:"corp_id" env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_ID"`
+ CorpSecret string `json:"corp_secret" env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_SECRET"`
+ AgentID int64 `json:"agent_id" env:"PICOCLAW_CHANNELS_WECOM_APP_AGENT_ID"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_WECOM_APP_TOKEN"`
+ EncodingAESKey string `json:"encoding_aes_key" env:"PICOCLAW_CHANNELS_WECOM_APP_ENCODING_AES_KEY"`
+ WebhookHost string `json:"webhook_host" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_HOST"`
+ WebhookPort int `json:"webhook_port" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_PORT"`
+ WebhookPath string `json:"webhook_path" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_PATH"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WECOM_APP_ALLOW_FROM"`
+ ReplyTimeout int `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_APP_REPLY_TIMEOUT"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_APP_REASONING_CHANNEL_ID"`
+}
+
+func (v *wecomappConfigV0) ToWeComAppConfig() (WeComAppConfig, WeComAppSecurity) {
+ return WeComAppConfig{
+ Enabled: v.Enabled,
+ CorpID: v.CorpID,
+ corpSecret: v.CorpSecret,
+ AgentID: v.AgentID,
+ token: v.Token,
+ encodingAESKey: v.EncodingAESKey,
+ WebhookHost: v.WebhookHost,
+ WebhookPort: v.WebhookPort,
+ WebhookPath: v.WebhookPath,
+ AllowFrom: v.AllowFrom,
+ ReplyTimeout: v.ReplyTimeout,
+ GroupTrigger: v.GroupTrigger,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, WeComAppSecurity{
+ CorpSecret: v.CorpSecret,
+ Token: v.Token,
+ EncodingAESKey: v.EncodingAESKey,
+ }
+}
+
+type wecomaibotConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENABLED"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_TOKEN"`
+ Secret string `json:"secret" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_SECRET"`
+ EncodingAESKey string `json:"encoding_aes_key" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENCODING_AES_KEY"`
+ WebhookPath string `json:"webhook_path" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WEBHOOK_PATH"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ALLOW_FROM"`
+ ReplyTimeout int `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REPLY_TIMEOUT"`
+ MaxSteps int `json:"max_steps" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_MAX_STEPS"`
+ WelcomeMessage string `json:"welcome_message" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WELCOME_MESSAGE"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REASONING_CHANNEL_ID"`
+}
+
+func (v *wecomaibotConfigV0) ToWeComAIBotConfig() (WeComAIBotConfig, WeComAIBotSecurity) {
+ return WeComAIBotConfig{
+ Enabled: v.Enabled,
+ WebhookPath: v.WebhookPath,
+ AllowFrom: v.AllowFrom,
+ ReplyTimeout: v.ReplyTimeout,
+ MaxSteps: v.MaxSteps,
+ WelcomeMessage: v.WelcomeMessage,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, WeComAIBotSecurity{
+ Token: v.Token,
+ Secret: v.Secret,
+ EncodingAESKey: v.EncodingAESKey,
+ }
+}
+
+type picoConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_PICO_ENABLED"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_PICO_TOKEN"`
+ AllowTokenQuery bool `json:"allow_token_query,omitempty"`
+ AllowOrigins []string `json:"allow_origins,omitempty"`
+ PingInterval int `json:"ping_interval,omitempty"`
+ ReadTimeout int `json:"read_timeout,omitempty"`
+ WriteTimeout int `json:"write_timeout,omitempty"`
+ MaxConnections int `json:"max_connections,omitempty"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_PICO_ALLOW_FROM"`
+ Placeholder PlaceholderConfig `json:"placeholder,omitempty"`
+}
+
+func (v *picoConfigV0) ToPicoConfig() (PicoConfig, PicoSecurity) {
+ return PicoConfig{
+ Enabled: v.Enabled,
+ token: v.Token,
+ AllowTokenQuery: v.AllowTokenQuery,
+ AllowOrigins: v.AllowOrigins,
+ PingInterval: v.PingInterval,
+ ReadTimeout: v.ReadTimeout,
+ WriteTimeout: v.WriteTimeout,
+ MaxConnections: v.MaxConnections,
+ AllowFrom: v.AllowFrom,
+ Placeholder: v.Placeholder,
+ }, PicoSecurity{
+ Token: v.Token,
+ }
+}
+
+type ircConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_IRC_ENABLED"`
+ Server string `json:"server" env:"PICOCLAW_CHANNELS_IRC_SERVER"`
+ TLS bool `json:"tls" env:"PICOCLAW_CHANNELS_IRC_TLS"`
+ Nick string `json:"nick" env:"PICOCLAW_CHANNELS_IRC_NICK"`
+ User string `json:"user,omitempty" env:"PICOCLAW_CHANNELS_IRC_USER"`
+ RealName string `json:"real_name,omitempty" env:"PICOCLAW_CHANNELS_IRC_REAL_NAME"`
+ Password string `json:"password" env:"PICOCLAW_CHANNELS_IRC_PASSWORD"`
+ NickServPassword string `json:"nickserv_password" env:"PICOCLAW_CHANNELS_IRC_NICKSERV_PASSWORD"`
+ SASLUser string `json:"sasl_user" env:"PICOCLAW_CHANNELS_IRC_SASL_USER"`
+ SASLPassword string `json:"sasl_password" env:"PICOCLAW_CHANNELS_IRC_SASL_PASSWORD"`
+ Channels FlexibleStringSlice `json:"channels" env:"PICOCLAW_CHANNELS_IRC_CHANNELS"`
+ RequestCaps FlexibleStringSlice `json:"request_caps,omitempty" env:"PICOCLAW_CHANNELS_IRC_REQUEST_CAPS"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_IRC_ALLOW_FROM"`
+ GroupTrigger GroupTriggerConfig `json:"group_trigger,omitempty"`
+ Typing TypingConfig `json:"typing,omitempty"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_IRC_REASONING_CHANNEL_ID"`
+}
+
+func (v *ircConfigV0) ToIRCConfig() (IRCConfig, IRCSecurity) {
+ return IRCConfig{
+ Enabled: v.Enabled,
+ Server: v.Server,
+ TLS: v.TLS,
+ Nick: v.Nick,
+ User: v.User,
+ RealName: v.RealName,
+ password: v.Password,
+ nickServPassword: v.NickServPassword,
+ SASLUser: v.SASLUser,
+ saslPassword: v.SASLPassword,
+ Channels: v.Channels,
+ RequestCaps: v.RequestCaps,
+ AllowFrom: v.AllowFrom,
+ GroupTrigger: v.GroupTrigger,
+ Typing: v.Typing,
+ ReasoningChannelID: v.ReasoningChannelID,
+ }, IRCSecurity{
+ Password: v.Password,
+ NickServPassword: v.NickServPassword,
+ SASLPassword: v.SASLPassword,
+ }
+}
+
+type providersConfigV0 struct {
+ Anthropic providerConfigV0 `json:"anthropic"`
+ OpenAI openAIProviderConfigV0 `json:"openai"`
+ LiteLLM providerConfigV0 `json:"litellm"`
+ OpenRouter providerConfigV0 `json:"openrouter"`
+ Groq providerConfigV0 `json:"groq"`
+ Zhipu providerConfigV0 `json:"zhipu"`
+ VLLM providerConfigV0 `json:"vllm"`
+ Gemini providerConfigV0 `json:"gemini"`
+ Nvidia providerConfigV0 `json:"nvidia"`
+ Ollama providerConfigV0 `json:"ollama"`
+ Moonshot providerConfigV0 `json:"moonshot"`
+ ShengSuanYun providerConfigV0 `json:"shengsuanyun"`
+ DeepSeek providerConfigV0 `json:"deepseek"`
+ Cerebras providerConfigV0 `json:"cerebras"`
+ Vivgrid providerConfigV0 `json:"vivgrid"`
+ VolcEngine providerConfigV0 `json:"volcengine"`
+ GitHubCopilot providerConfigV0 `json:"github_copilot"`
+ Antigravity providerConfigV0 `json:"antigravity"`
+ Qwen providerConfigV0 `json:"qwen"`
+ Mistral providerConfigV0 `json:"mistral"`
+ Avian providerConfigV0 `json:"avian"`
+ Minimax providerConfigV0 `json:"minimax"`
+ LongCat providerConfigV0 `json:"longcat"`
+ ModelScope providerConfigV0 `json:"modelscope"`
+ Novita providerConfigV0 `json:"novita"`
+}
+
+// IsEmpty checks if all provider configs are empty (no API keys or API bases set)
+// Note: WebSearch is an optimization option and doesn't count as "non-empty"
+func (p providersConfigV0) IsEmpty() bool {
+ return p.Anthropic.APIKey == "" && p.Anthropic.APIBase == "" &&
+ p.OpenAI.APIKey == "" && p.OpenAI.APIBase == "" &&
+ p.LiteLLM.APIKey == "" && p.LiteLLM.APIBase == "" &&
+ p.OpenRouter.APIKey == "" && p.OpenRouter.APIBase == "" &&
+ p.Groq.APIKey == "" && p.Groq.APIBase == "" &&
+ p.Zhipu.APIKey == "" && p.Zhipu.APIBase == "" &&
+ p.VLLM.APIKey == "" && p.VLLM.APIBase == "" &&
+ p.Gemini.APIKey == "" && p.Gemini.APIBase == "" &&
+ p.Nvidia.APIKey == "" && p.Nvidia.APIBase == "" &&
+ p.Ollama.APIKey == "" && p.Ollama.APIBase == "" &&
+ p.Moonshot.APIKey == "" && p.Moonshot.APIBase == "" &&
+ p.ShengSuanYun.APIKey == "" && p.ShengSuanYun.APIBase == "" &&
+ p.DeepSeek.APIKey == "" && p.DeepSeek.APIBase == "" &&
+ p.Cerebras.APIKey == "" && p.Cerebras.APIBase == "" &&
+ p.Vivgrid.APIKey == "" && p.Vivgrid.APIBase == "" &&
+ p.VolcEngine.APIKey == "" && p.VolcEngine.APIBase == "" &&
+ p.GitHubCopilot.APIKey == "" && p.GitHubCopilot.APIBase == "" &&
+ p.Antigravity.APIKey == "" && p.Antigravity.APIBase == "" &&
+ p.Qwen.APIKey == "" && p.Qwen.APIBase == "" &&
+ p.Mistral.APIKey == "" && p.Mistral.APIBase == "" &&
+ p.Avian.APIKey == "" && p.Avian.APIBase == "" &&
+ p.Minimax.APIKey == "" && p.Minimax.APIBase == "" &&
+ p.LongCat.APIKey == "" && p.LongCat.APIBase == "" &&
+ p.ModelScope.APIKey == "" && p.ModelScope.APIBase == "" &&
+ p.Novita.APIKey == "" && p.Novita.APIBase == ""
+}
+
+type providerConfigV0 struct {
+ APIKey string `json:"api_key" env:"PICOCLAW_PROVIDERS_{{.Name}}_API_KEY"`
+ APIBase string `json:"api_base" env:"PICOCLAW_PROVIDERS_{{.Name}}_API_BASE"`
+ Proxy string `json:"proxy,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_PROXY"`
+ RequestTimeout int `json:"request_timeout,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_REQUEST_TIMEOUT"`
+ AuthMethod string `json:"auth_method,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_AUTH_METHOD"`
+ ConnectMode string `json:"connect_mode,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_CONNECT_MODE"` // only for Github Copilot, `stdio` or `grpc`
+}
+
+// MarshalJSON implements custom JSON marshaling for providersConfig
+// to omit the entire section when empty
+func (p providersConfigV0) MarshalJSON() ([]byte, error) {
+ if p.IsEmpty() {
+ return []byte("null"), nil
+ }
+ type Alias providersConfigV0
+ return json.Marshal((*Alias)(&p))
+}
+
+type openAIProviderConfigV0 struct {
+ providerConfigV0
+ WebSearch bool `json:"web_search" env:"PICOCLAW_PROVIDERS_OPENAI_WEB_SEARCH"`
+}
+
+type modelConfigV0 struct {
+ // Required fields
+ ModelName string `json:"model_name"` // User-facing alias for the model
+ Model string `json:"model"` // Protocol/model-identifier (e.g., "openai/gpt-4o", "anthropic/claude-sonnet-4.6")
+
+ // HTTP-based providers
+ APIBase string `json:"api_base,omitempty"` // API endpoint URL
+ APIKey string `json:"api_key"` // API authentication key (single key)
+ APIKeys []string `json:"api_keys,omitempty"` // API authentication keys (multiple keys for failover)
+ Proxy string `json:"proxy,omitempty"` // HTTP proxy URL
+ Fallbacks []string `json:"fallbacks,omitempty"` // Fallback model names for failover
+
+ // Special providers (CLI-based, OAuth, etc.)
+ AuthMethod string `json:"auth_method,omitempty"` // Authentication method: oauth, token
+ ConnectMode string `json:"connect_mode,omitempty"` // Connection mode: stdio, grpc
+ Workspace string `json:"workspace,omitempty"` // Workspace path for CLI-based providers
+
+ // Optional optimizations
+ RPM int `json:"rpm,omitempty"` // Requests per minute limit
+ MaxTokensField string `json:"max_tokens_field,omitempty"` // Field name for max tokens (e.g., "max_completion_tokens")
+ RequestTimeout int `json:"request_timeout,omitempty"`
+ ThinkingLevel string `json:"thinking_level,omitempty"` // Extended thinking: off|low|medium|high|xhigh|adaptive
+}
+
+func (c *configV0) migrateChannelConfigs() {
+ // Discord: mention_only -> group_trigger.mention_only
+ if c.Channels.Discord.MentionOnly && !c.Channels.Discord.GroupTrigger.MentionOnly {
+ c.Channels.Discord.GroupTrigger.MentionOnly = true
+ }
+
+ // OneBot: group_trigger_prefix -> group_trigger.prefixes
+ if len(c.Channels.OneBot.GroupTriggerPrefix) > 0 &&
+ len(c.Channels.OneBot.GroupTrigger.Prefixes) == 0 {
+ c.Channels.OneBot.GroupTrigger.Prefixes = c.Channels.OneBot.GroupTriggerPrefix
+ }
+}
+
+func (c *configV0) Migrate() (*Config, error) {
+ // Migrate legacy channel config fields to new unified structures
+ cfg := DefaultConfig()
+
+ // Always copy user's Agents config to preserve settings like Provider, Model, MaxTokens
+ cfg.Agents.List = c.Agents.List
+ cfg.Agents.Defaults.Workspace = c.Agents.Defaults.Workspace
+ cfg.Agents.Defaults.RestrictToWorkspace = c.Agents.Defaults.RestrictToWorkspace
+ cfg.Agents.Defaults.AllowReadOutsideWorkspace = c.Agents.Defaults.AllowReadOutsideWorkspace
+ cfg.Agents.Defaults.Provider = c.Agents.Defaults.Provider
+ cfg.Agents.Defaults.ModelName = c.Agents.Defaults.GetModelName()
+ cfg.Agents.Defaults.ModelFallbacks = c.Agents.Defaults.ModelFallbacks
+ cfg.Agents.Defaults.ImageModel = c.Agents.Defaults.ImageModel
+ cfg.Agents.Defaults.ImageModelFallbacks = c.Agents.Defaults.ImageModelFallbacks
+ cfg.Agents.Defaults.MaxTokens = c.Agents.Defaults.MaxTokens
+ cfg.Agents.Defaults.Temperature = c.Agents.Defaults.Temperature
+ cfg.Agents.Defaults.MaxToolIterations = c.Agents.Defaults.MaxToolIterations
+ cfg.Agents.Defaults.SummarizeMessageThreshold = c.Agents.Defaults.SummarizeMessageThreshold
+ cfg.Agents.Defaults.SummarizeTokenPercent = c.Agents.Defaults.SummarizeTokenPercent
+ cfg.Agents.Defaults.MaxMediaSize = c.Agents.Defaults.MaxMediaSize
+ cfg.Agents.Defaults.Routing = c.Agents.Defaults.Routing
+
+ // Copy other top-level fields
+ cfg.Bindings = c.Bindings
+ cfg.Session = c.Session
+ var secChannels ChannelsSecurity
+ cfg.Channels, secChannels = c.Channels.ToChannelsConfig()
+ cfg.Gateway = c.Gateway
+ var secWeb WebToolsSecurity
+ cfg.Tools.Web, secWeb = c.Tools.Web.ToWebToolsConfig()
+ cfg.Tools.Cron = c.Tools.Cron
+ cfg.Tools.Exec = c.Tools.Exec
+ var secSkills SkillsSecurity
+ cfg.Tools.Skills, secSkills = c.Tools.Skills.ToSkillsToolsConfig()
+ cfg.Tools.MediaCleanup = c.Tools.MediaCleanup
+ cfg.Tools.MCP = c.Tools.MCP
+ cfg.Tools.AppendFile = c.Tools.AppendFile
+ cfg.Tools.EditFile = c.Tools.EditFile
+ cfg.Tools.FindSkills = c.Tools.FindSkills
+ cfg.Tools.I2C = c.Tools.I2C
+ cfg.Tools.InstallSkill = c.Tools.InstallSkill
+ cfg.Tools.ListDir = c.Tools.ListDir
+ cfg.Tools.Message = c.Tools.Message
+ cfg.Tools.ReadFile = c.Tools.ReadFile
+ cfg.Tools.SendFile = c.Tools.SendFile
+ cfg.Tools.Spawn = c.Tools.Spawn
+ cfg.Tools.SpawnStatus = c.Tools.SpawnStatus
+ cfg.Tools.SPI = c.Tools.SPI
+ cfg.Tools.Subagent = c.Tools.Subagent
+ cfg.Tools.WebFetch = c.Tools.WebFetch
+ cfg.Tools.AllowReadPaths = c.Tools.AllowReadPaths
+ cfg.Tools.AllowWritePaths = c.Tools.AllowWritePaths
+ cfg.Heartbeat = c.Heartbeat
+ cfg.Devices = c.Devices
+
+ secModels := make(map[string]ModelSecurityEntry, 0)
+ // Only override ModelList if user provided values
+ if len(c.ModelList) > 0 {
+ // Convert []modelConfigV0 to []ModelConfig
+ cfg.ModelList = make([]*ModelConfig, len(c.ModelList))
+ for i, m := range c.ModelList {
+ // Merge APIKey and APIKeys, deduplicating
+ mergedKeys := MergeAPIKeys(m.APIKey, m.APIKeys)
+
+ cfg.ModelList[i] = &ModelConfig{
+ ModelName: m.ModelName,
+ Model: m.Model,
+ APIBase: m.APIBase,
+ Proxy: m.Proxy,
+ Fallbacks: m.Fallbacks,
+ AuthMethod: m.AuthMethod,
+ ConnectMode: m.ConnectMode,
+ Workspace: m.Workspace,
+ RPM: m.RPM,
+ MaxTokensField: m.MaxTokensField,
+ RequestTimeout: m.RequestTimeout,
+ ThinkingLevel: m.ThinkingLevel,
+ apiKeys: mergedKeys,
+ }
+ }
+ names := toNameIndex(cfg.ModelList)
+ for i, m := range c.ModelList {
+ // Merge APIKey and APIKeys, deduplicating
+ mergedKeys := MergeAPIKeys(m.APIKey, m.APIKeys)
+ secModels[names[i]] = ModelSecurityEntry{
+ APIKeys: mergedKeys,
+ }
+ }
+ }
+
+ cfg.WithSecurity(&SecurityConfig{
+ ModelList: secModels,
+ Channels: secChannels,
+ Web: secWeb,
+ Skills: secSkills,
+ })
+ cfg.Version = CurrentVersion
+ return cfg, nil
+}
+
+type webToolsConfigV0 struct {
+ ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"`
+ Brave braveConfigV0 ` json:"brave"`
+ Tavily tavilyConfigV0 ` json:"tavily"`
+ DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"`
+ Perplexity perplexityConfigV0 ` json:"perplexity"`
+ SearXNG SearXNGConfig ` json:"searxng"`
+ GLMSearch glmSearchConfigV0 ` json:"glm_search"`
+ PreferNative bool ` json:"prefer_native" env:"PICOCLAW_TOOLS_WEB_PREFER_NATIVE"`
+ Proxy string ` json:"proxy,omitempty" env:"PICOCLAW_TOOLS_WEB_PROXY"`
+ FetchLimitBytes int64 ` json:"fetch_limit_bytes,omitempty" env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"`
+ Format string ` json:"format,omitempty" env:"PICOCLAW_TOOLS_WEB_FORMAT"`
+ PrivateHostWhitelist FlexibleStringSlice ` json:"private_host_whitelist,omitempty" env:"PICOCLAW_TOOLS_WEB_PRIVATE_HOST_WHITELIST"`
+}
+
+type braveConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_BRAVE_ENABLED"`
+ APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_BRAVE_API_KEY"`
+ APIKeys []string `json:"api_keys" env:"PICOCLAW_TOOLS_WEB_BRAVE_API_KEYS"`
+ MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BRAVE_MAX_RESULTS"`
+}
+
+func (v *braveConfigV0) ToBraveConfig() (BraveConfig, BraveSecurity) {
+ return BraveConfig{
+ Enabled: v.Enabled,
+ MaxResults: v.MaxResults,
+ }, BraveSecurity{
+ APIKeys: MergeAPIKeys(v.APIKey, v.APIKeys),
+ }
+}
+
+type tavilyConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_TAVILY_ENABLED"`
+ APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_TAVILY_API_KEY"`
+ APIKeys []string `json:"api_keys" env:"PICOCLAW_TOOLS_WEB_TAVILY_API_KEYS"`
+ BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_TAVILY_BASE_URL"`
+ MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_TAVILY_MAX_RESULTS"`
+}
+
+func (v *tavilyConfigV0) ToTavilyConfig() (TavilyConfig, TavilySecurity) {
+ return TavilyConfig{
+ Enabled: v.Enabled,
+ BaseURL: v.BaseURL,
+ MaxResults: v.MaxResults,
+ }, TavilySecurity{
+ APIKeys: MergeAPIKeys(v.APIKey, v.APIKeys),
+ }
+}
+
+type perplexityConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_ENABLED"`
+ APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_API_KEY"`
+ APIKeys []string `json:"api_keys" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_API_KEYS"`
+ MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_MAX_RESULTS"`
+}
+
+func (v *perplexityConfigV0) ToPerplexityConfig() (PerplexityConfig, PerplexitySecurity) {
+ return PerplexityConfig{
+ Enabled: v.Enabled,
+ MaxResults: v.MaxResults,
+ }, PerplexitySecurity{
+ APIKeys: MergeAPIKeys(v.APIKey, v.APIKeys),
+ }
+}
+
+type glmSearchConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"`
+ APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_GLM_API_KEY"`
+ BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"`
+ SearchEngine string `json:"search_engine" env:"PICOCLAW_TOOLS_WEB_GLM_SEARCH_ENGINE"`
+}
+
+func (v *glmSearchConfigV0) ToGLMSearchConfig() (GLMSearchConfig, GLMSearchSecurity) {
+ return GLMSearchConfig{
+ Enabled: v.Enabled,
+ apiKey: v.APIKey,
+ BaseURL: v.BaseURL,
+ SearchEngine: v.SearchEngine,
+ }, GLMSearchSecurity{
+ APIKey: v.APIKey,
+ }
+}
+
+func (v *webToolsConfigV0) ToWebToolsConfig() (WebToolsConfig, WebToolsSecurity) {
+ brave, braveSecurity := v.Brave.ToBraveConfig()
+ tavily, tavilySecurity := v.Tavily.ToTavilyConfig()
+ perplexity, perplexitySecurity := v.Perplexity.ToPerplexityConfig()
+ glmSearch, glmSearchSecurity := v.GLMSearch.ToGLMSearchConfig()
+
+ return WebToolsConfig{
+ ToolConfig: v.ToolConfig,
+ Brave: brave,
+ Tavily: tavily,
+ DuckDuckGo: v.DuckDuckGo,
+ Perplexity: perplexity,
+ SearXNG: v.SearXNG,
+ GLMSearch: glmSearch,
+ PreferNative: v.PreferNative,
+ Proxy: v.Proxy,
+ FetchLimitBytes: v.FetchLimitBytes,
+ Format: v.Format,
+ PrivateHostWhitelist: v.PrivateHostWhitelist,
+ }, WebToolsSecurity{
+ Brave: &braveSecurity,
+ Tavily: &tavilySecurity,
+ Perplexity: &perplexitySecurity,
+ GLMSearch: &glmSearchSecurity,
+ }
+}
+
+type skillsToolsConfigV0 struct {
+ ToolConfig ` envPrefix:"PICOCLAW_TOOLS_SKILLS_"`
+ Registries skillsRegistriesConfigV0 ` json:"registries"`
+ Github skillsGithubConfigV0 ` json:"github"`
+ MaxConcurrentSearches int ` json:"max_concurrent_searches" env:"PICOCLAW_TOOLS_SKILLS_MAX_CONCURRENT_SEARCHES"`
+ SearchCache SearchCacheConfig ` json:"search_cache"`
+}
+
+type skillsRegistriesConfigV0 struct {
+ ClawHub clawHubRegistryConfigV0 `json:"clawhub"`
+}
+
+type clawHubRegistryConfigV0 struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_ENABLED"`
+ BaseURL string `json:"base_url" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_BASE_URL"`
+ AuthToken string `json:"auth_token" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_AUTH_TOKEN"`
+ SearchPath string `json:"search_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SEARCH_PATH"`
+ SkillsPath string `json:"skills_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SKILLS_PATH"`
+}
+
+func (v *clawHubRegistryConfigV0) ToClawHubRegistryConfig() (ClawHubRegistryConfig, ClawHubSecurity) {
+ return ClawHubRegistryConfig{
+ Enabled: v.Enabled,
+ BaseURL: v.BaseURL,
+ authToken: v.AuthToken,
+ SearchPath: v.SearchPath,
+ SkillsPath: v.SkillsPath,
+ }, ClawHubSecurity{
+ AuthToken: v.AuthToken,
+ }
+}
+
+type skillsGithubConfigV0 struct {
+ Token string `json:"token" env:"PICOCLAW_TOOLS_SKILLS_GITHUB_TOKEN"`
+ Proxy string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_SKILLS_GITHUB_PROXY"`
+}
+
+func (v *skillsGithubConfigV0) ToSkillsGithubConfig() (SkillsGithubConfig, GithubSecurity) {
+ return SkillsGithubConfig{
+ token: v.Token,
+ Proxy: v.Proxy,
+ }, GithubSecurity{
+ Token: v.Token,
+ }
+}
+
+func (v *skillsRegistriesConfigV0) ToSkillsRegistriesConfig() (SkillsRegistriesConfig, *ClawHubSecurity) {
+ clawHub, clawHubSecurity := v.ClawHub.ToClawHubRegistryConfig()
+
+ return SkillsRegistriesConfig{
+ ClawHub: clawHub,
+ }, &clawHubSecurity
+}
+
+func (v *skillsToolsConfigV0) ToSkillsToolsConfig() (SkillsToolsConfig, SkillsSecurity) {
+ registries, registriesSecurity := v.Registries.ToSkillsRegistriesConfig()
+ github, githubSecurity := v.Github.ToSkillsGithubConfig()
+
+ return SkillsToolsConfig{
+ ToolConfig: v.ToolConfig,
+ Registries: registries,
+ Github: github,
+ MaxConcurrentSearches: v.MaxConcurrentSearches,
+ SearchCache: v.SearchCache,
+ }, SkillsSecurity{
+ Github: &githubSecurity,
+ ClawHub: registriesSecurity,
+ }
+}
diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go
index 588c04645..3f8ec6150 100644
--- a/pkg/config/config_test.go
+++ b/pkg/config/config_test.go
@@ -8,6 +8,9 @@ import (
"strings"
"testing"
+ "github.com/stretchr/testify/assert"
+ "gopkg.in/yaml.v3"
+
"github.com/sipeed/picoclaw/pkg/credential"
)
@@ -78,18 +81,19 @@ func TestAgentModelConfig_MarshalObject(t *testing.T) {
}
func TestProvidersConfig_IsEmpty(t *testing.T) {
- var empty ProvidersConfig
+ var empty providersConfigV0
+ t.Logf("empty: %+v", empty)
if !empty.IsEmpty() {
- t.Fatal("empty ProvidersConfig should report empty")
+ t.Fatal("empty providersConfig should report empty")
}
- novita := ProvidersConfig{
- Novita: ProviderConfig{
+ novita := providersConfigV0{
+ Novita: providerConfigV0{
APIKey: "test-key",
},
}
if novita.IsEmpty() {
- t.Fatal("ProvidersConfig with novita settings should not report empty")
+ t.Fatal("providersConfig with novita settings should not report empty")
}
}
@@ -237,15 +241,6 @@ func TestDefaultConfig_WorkspacePath(t *testing.T) {
}
}
-// TestDefaultConfig_Model verifies model is set
-func TestDefaultConfig_Model(t *testing.T) {
- cfg := DefaultConfig()
-
- if cfg.Agents.Defaults.Model != "" {
- t.Error("Model should be empty")
- }
-}
-
// TestDefaultConfig_MaxTokens verifies max tokens has default value
func TestDefaultConfig_MaxTokens(t *testing.T) {
cfg := DefaultConfig()
@@ -288,21 +283,6 @@ func TestDefaultConfig_Gateway(t *testing.T) {
}
}
-// TestDefaultConfig_Providers verifies provider structure
-func TestDefaultConfig_Providers(t *testing.T) {
- cfg := DefaultConfig()
-
- if cfg.Providers.Anthropic.APIKey != "" {
- t.Error("Anthropic API key should be empty by default")
- }
- if cfg.Providers.OpenAI.APIKey != "" {
- t.Error("OpenAI API key should be empty by default")
- }
- if cfg.Providers.OpenRouter.APIKey != "" {
- t.Error("OpenRouter API key should be empty by default")
- }
-}
-
// TestDefaultConfig_Channels verifies channels are disabled by default
func TestDefaultConfig_Channels(t *testing.T) {
cfg := DefaultConfig()
@@ -329,7 +309,7 @@ func TestDefaultConfig_WebTools(t *testing.T) {
if cfg.Tools.Web.Brave.MaxResults != 5 {
t.Error("Expected Brave MaxResults 5, got ", cfg.Tools.Web.Brave.MaxResults)
}
- if len(cfg.Tools.Web.Brave.APIKeys) != 0 {
+ if len(cfg.Tools.Web.Brave.APIKeys()) != 0 {
t.Error("Brave API key should be empty by default")
}
if cfg.Tools.Web.DuckDuckGo.MaxResults != 5 {
@@ -387,9 +367,6 @@ func TestConfig_Complete(t *testing.T) {
if cfg.Agents.Defaults.Workspace == "" {
t.Error("Workspace should not be empty")
}
- if cfg.Agents.Defaults.Model != "" {
- t.Error("Model should be empty")
- }
if cfg.Agents.Defaults.Temperature != nil {
t.Error("Temperature should be nil when not provided")
}
@@ -408,12 +385,8 @@ func TestConfig_Complete(t *testing.T) {
if !cfg.Heartbeat.Enabled {
t.Error("Heartbeat should be enabled by default")
}
-}
-
-func TestDefaultConfig_OpenAIWebSearchEnabled(t *testing.T) {
- cfg := DefaultConfig()
- if !cfg.Providers.OpenAI.WebSearch {
- t.Fatal("DefaultConfig().Providers.OpenAI.WebSearch should be true")
+ if !cfg.Tools.Exec.AllowRemote {
+ t.Error("Exec.AllowRemote should be true by default")
}
}
@@ -427,7 +400,7 @@ func TestDefaultConfig_WebPreferNativeEnabled(t *testing.T) {
func TestLoadConfig_WebPreferNativeDefaultsTrueWhenUnset(t *testing.T) {
dir := t.TempDir()
configPath := filepath.Join(dir, "config.json")
- if err := os.WriteFile(configPath, []byte(`{"tools":{"web":{"enabled":true}}}`), 0o600); err != nil {
+ if err := os.WriteFile(configPath, []byte(`{"version":1,"tools":{"web":{"enabled":true}}}`), 0o600); err != nil {
t.Fatalf("WriteFile() error: %v", err)
}
@@ -470,26 +443,34 @@ func TestDefaultConfig_CronAllowCommandEnabled(t *testing.T) {
}
}
-func TestLoadConfig_OpenAIWebSearchDefaultsTrueWhenUnset(t *testing.T) {
- dir := t.TempDir()
- configPath := filepath.Join(dir, "config.json")
- if err := os.WriteFile(configPath, []byte(`{"providers":{"openai":{"api_base":""}}}`), 0o600); err != nil {
- t.Fatalf("WriteFile() error: %v", err)
+func TestDefaultConfig_HooksDefaults(t *testing.T) {
+ cfg := DefaultConfig()
+ if !cfg.Hooks.Enabled {
+ t.Fatal("DefaultConfig().Hooks.Enabled should be true")
}
+ if cfg.Hooks.Defaults.ObserverTimeoutMS != 500 {
+ t.Fatalf("ObserverTimeoutMS = %d, want 500", cfg.Hooks.Defaults.ObserverTimeoutMS)
+ }
+ if cfg.Hooks.Defaults.InterceptorTimeoutMS != 5000 {
+ t.Fatalf("InterceptorTimeoutMS = %d, want 5000", cfg.Hooks.Defaults.InterceptorTimeoutMS)
+ }
+ if cfg.Hooks.Defaults.ApprovalTimeoutMS != 60000 {
+ t.Fatalf("ApprovalTimeoutMS = %d, want 60000", cfg.Hooks.Defaults.ApprovalTimeoutMS)
+ }
+}
- cfg, err := LoadConfig(configPath)
- if err != nil {
- t.Fatalf("LoadConfig() error: %v", err)
- }
- if !cfg.Providers.OpenAI.WebSearch {
- t.Fatal("OpenAI codex web search should remain true when unset in config file")
+func TestDefaultConfig_LogLevel(t *testing.T) {
+ cfg := DefaultConfig()
+ if cfg.Gateway.LogLevel != "fatal" {
+ t.Errorf("LogLevel = %q, want \"fatal\"", cfg.Gateway.LogLevel)
}
}
func TestLoadConfig_ExecAllowRemoteDefaultsTrueWhenUnset(t *testing.T) {
dir := t.TempDir()
configPath := filepath.Join(dir, "config.json")
- if err := os.WriteFile(configPath, []byte(`{"tools":{"exec":{"enable_deny_patterns":true}}}`), 0o600); err != nil {
+ if err := os.WriteFile(configPath, []byte(`{"version":1,"tools":{"exec":{"enable_deny_patterns":true}}}`),
+ 0o600); err != nil {
t.Fatalf("WriteFile() error: %v", err)
}
@@ -505,7 +486,11 @@ func TestLoadConfig_ExecAllowRemoteDefaultsTrueWhenUnset(t *testing.T) {
func TestLoadConfig_CronAllowCommandDefaultsTrueWhenUnset(t *testing.T) {
dir := t.TempDir()
configPath := filepath.Join(dir, "config.json")
- if err := os.WriteFile(configPath, []byte(`{"tools":{"cron":{"exec_timeout_minutes":5}}}`), 0o600); err != nil {
+ if err := os.WriteFile(
+ configPath,
+ []byte(`{"version":1,"tools":{"cron":{"exec_timeout_minutes":5}}}`),
+ 0o600,
+ ); err != nil {
t.Fatalf("WriteFile() error: %v", err)
}
@@ -518,22 +503,6 @@ func TestLoadConfig_CronAllowCommandDefaultsTrueWhenUnset(t *testing.T) {
}
}
-func TestLoadConfig_OpenAIWebSearchCanBeDisabled(t *testing.T) {
- dir := t.TempDir()
- configPath := filepath.Join(dir, "config.json")
- if err := os.WriteFile(configPath, []byte(`{"providers":{"openai":{"web_search":false}}}`), 0o600); err != nil {
- t.Fatalf("WriteFile() error: %v", err)
- }
-
- cfg, err := LoadConfig(configPath)
- if err != nil {
- t.Fatalf("LoadConfig() error: %v", err)
- }
- if cfg.Providers.OpenAI.WebSearch {
- t.Fatal("OpenAI codex web search should be false when disabled in config file")
- }
-}
-
func TestLoadConfig_WebToolsProxy(t *testing.T) {
tmpDir := t.TempDir()
configPath := filepath.Join(tmpDir, "config.json")
@@ -555,6 +524,89 @@ func TestLoadConfig_WebToolsProxy(t *testing.T) {
}
}
+func TestLoadConfig_HooksProcessConfig(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+ configJSON := `{
+ "version": 1,
+ "hooks": {
+ "processes": {
+ "review-gate": {
+ "enabled": true,
+ "transport": "stdio",
+ "command": ["uvx", "picoclaw-hook-reviewer"],
+ "dir": "/tmp/hooks",
+ "env": {
+ "HOOK_MODE": "rewrite"
+ },
+ "observe": ["turn_start", "turn_end"],
+ "intercept": ["before_tool", "approve_tool"]
+ }
+ },
+ "builtins": {
+ "audit": {
+ "enabled": true,
+ "priority": 5,
+ "config": {
+ "label": "audit"
+ }
+ }
+ }
+ }
+}`
+ if err := os.WriteFile(configPath, []byte(configJSON), 0o600); err != nil {
+ t.Fatalf("os.WriteFile() error: %v", err)
+ }
+
+ cfg, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("LoadConfig() error: %v", err)
+ }
+
+ processCfg, ok := cfg.Hooks.Processes["review-gate"]
+ if !ok {
+ t.Fatal("expected review-gate process hook")
+ }
+ if !processCfg.Enabled {
+ t.Fatal("expected review-gate process hook to be enabled")
+ }
+ if processCfg.Transport != "stdio" {
+ t.Fatalf("Transport = %q, want stdio", processCfg.Transport)
+ }
+ if len(processCfg.Command) != 2 || processCfg.Command[0] != "uvx" {
+ t.Fatalf("Command = %v", processCfg.Command)
+ }
+ if processCfg.Dir != "/tmp/hooks" {
+ t.Fatalf("Dir = %q, want /tmp/hooks", processCfg.Dir)
+ }
+ if processCfg.Env["HOOK_MODE"] != "rewrite" {
+ t.Fatalf("HOOK_MODE = %q, want rewrite", processCfg.Env["HOOK_MODE"])
+ }
+ if len(processCfg.Observe) != 2 || processCfg.Observe[1] != "turn_end" {
+ t.Fatalf("Observe = %v", processCfg.Observe)
+ }
+ if len(processCfg.Intercept) != 2 || processCfg.Intercept[1] != "approve_tool" {
+ t.Fatalf("Intercept = %v", processCfg.Intercept)
+ }
+
+ builtinCfg, ok := cfg.Hooks.Builtins["audit"]
+ if !ok {
+ t.Fatal("expected audit builtin hook")
+ }
+ if !builtinCfg.Enabled {
+ t.Fatal("expected audit builtin hook to be enabled")
+ }
+ if builtinCfg.Priority != 5 {
+ t.Fatalf("Priority = %d, want 5", builtinCfg.Priority)
+ }
+ if !strings.Contains(string(builtinCfg.Config), `"audit"`) {
+ t.Fatalf("Config = %s", string(builtinCfg.Config))
+ }
+ if cfg.Hooks.Defaults.ApprovalTimeoutMS != 60000 {
+ t.Fatalf("ApprovalTimeoutMS = %d, want 60000", cfg.Hooks.Defaults.ApprovalTimeoutMS)
+ }
+}
+
// TestDefaultConfig_DMScope verifies the default dm_scope value
// TestDefaultConfig_SummarizationThresholds verifies summarization defaults
func TestDefaultConfig_SummarizationThresholds(t *testing.T) {
@@ -729,7 +781,20 @@ func TestFlexibleStringSlice_UnmarshalText_EmptySliceConsistency(t *testing.T) {
func TestLoadConfig_WarnsForPlaintextAPIKey(t *testing.T) {
dir := t.TempDir()
cfgPath := filepath.Join(dir, "config.json")
- const original = `{"model_list":[{"model_name":"test","model":"openai/gpt-4","api_key":"sk-plaintext"}]}`
+ const original = `{"version":1,"model_list":[{"model_name":"test","model":"openai/gpt-4","api_key":"sk-plaintext"}]}`
+ if err := os.WriteFile(cfgPath, []byte(original), 0o600); err != nil {
+ t.Fatalf("setup: %v", err)
+ }
+ secPath := filepath.Join(dir, SecurityConfigFile)
+ const securityConfig = `
+model_list:
+ test:0:
+ api_keys:
+ - "sk-plaintext"
+`
+ if err := os.WriteFile(secPath, []byte(securityConfig), 0o600); err != nil {
+ t.Fatalf("setup: %v", err)
+ }
if err := os.WriteFile(cfgPath, []byte(original), 0o600); err != nil {
t.Fatalf("setup: %v", err)
}
@@ -742,10 +807,10 @@ func TestLoadConfig_WarnsForPlaintextAPIKey(t *testing.T) {
t.Fatalf("LoadConfig: %v", err)
}
// In-memory value must be the resolved plaintext.
- if cfg.ModelList[0].APIKey != "sk-plaintext" {
- t.Errorf("in-memory api_key = %q, want %q", cfg.ModelList[0].APIKey, "sk-plaintext")
+ if cfg.ModelList[0].APIKey() != "sk-plaintext" {
+ t.Errorf("in-memory api_key = %q, want %q", cfg.ModelList[0].APIKey(), "sk-plaintext")
}
- // The file on disk must remain unchanged — LoadConfig must not write anything.
+ // The file on disk must remain unchanged — no need upgrade version
raw, _ := os.ReadFile(cfgPath)
if string(raw) != original {
t.Errorf("LoadConfig must not modify the config file; got:\n%s", string(raw))
@@ -762,15 +827,19 @@ func TestSaveConfig_EncryptsPlaintextAPIKey(t *testing.T) {
mustSetupSSHKey(t)
cfg := DefaultConfig()
- cfg.ModelList = []ModelConfig{
- {ModelName: "test", Model: "openai/gpt-4", APIKey: "sk-plaintext"},
+ cfg.ModelList = []*ModelConfig{
+ {ModelName: "test", Model: "openai/gpt-4", apiKeys: []string{"sk-plaintext"}},
+ }
+ cfg.security = &SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{"test:0": {APIKeys: []string{"sk-plaintext"}}},
}
if err := SaveConfig(cfgPath, cfg); err != nil {
t.Fatalf("SaveConfig: %v", err)
}
// Disk must contain enc://, not the raw key.
- raw, _ := os.ReadFile(cfgPath)
+ secPath := filepath.Join(dir, SecurityConfigFile)
+ raw, _ := os.ReadFile(secPath)
if !strings.Contains(string(raw), "enc://") {
t.Errorf("saved file should contain enc://, got:\n%s", string(raw))
}
@@ -783,8 +852,8 @@ func TestSaveConfig_EncryptsPlaintextAPIKey(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig after SaveConfig: %v", err)
}
- if cfg2.ModelList[0].APIKey != "sk-plaintext" {
- t.Errorf("loaded api_key = %q, want %q", cfg2.ModelList[0].APIKey, "sk-plaintext")
+ if cfg2.ModelList[0].APIKey() != "sk-plaintext" {
+ t.Errorf("loaded api_key = %q, want %q", cfg2.ModelList[0].APIKey(), "sk-plaintext")
}
}
@@ -820,10 +889,17 @@ func TestLoadConfig_FileRefNotSealed(t *testing.T) {
if err := os.WriteFile(keyFile, []byte("sk-from-file"), 0o600); err != nil {
t.Fatalf("setup: %v", err)
}
- data := `{"model_list":[{"model_name":"test","model":"openai/gpt-4","api_key":"file://openai.key"}]}`
+ data := `{"version":1,"model_list":[{"model_name":"test","model":"openai/gpt-4"}]}`
if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil {
t.Fatalf("setup: %v", err)
}
+ secPath := filepath.Join(dir, SecurityConfigFile)
+ if err := saveSecurityConfig(
+ secPath,
+ &SecurityConfig{ModelList: map[string]ModelSecurityEntry{"test:0": {APIKeys: []string{"file://openai.key"}}}},
+ ); err != nil {
+ t.Fatalf("saveSecurityConfig: %v", err)
+ }
t.Setenv("PICOCLAW_KEY_PASSPHRASE", "test-passphrase")
t.Setenv("PICOCLAW_SSH_KEY_PATH", "")
@@ -832,7 +908,7 @@ func TestLoadConfig_FileRefNotSealed(t *testing.T) {
t.Fatalf("LoadConfig: %v", err)
}
- raw, _ := os.ReadFile(cfgPath)
+ raw, _ := os.ReadFile(secPath)
if !strings.Contains(string(raw), "file://openai.key") {
t.Error("file:// reference should be preserved unchanged in the config file")
}
@@ -852,23 +928,28 @@ func TestSaveConfig_MixedKeys(t *testing.T) {
// Pre-encrypt one key so we have a genuine enc:// value to put in the config.
if err := SaveConfig(cfgPath, &Config{
- ModelList: []ModelConfig{
- {ModelName: "pre", Model: "openai/gpt-4", APIKey: "sk-already-plain"},
+ ModelList: []*ModelConfig{
+ {ModelName: "pre", Model: "openai/gpt-4"},
+ },
+ security: &SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{
+ "pre:0": {APIKeys: []string{"sk-already-plain"}},
+ },
},
}); err != nil {
t.Fatalf("setup SaveConfig: %v", err)
}
- raw, _ := os.ReadFile(cfgPath)
+ raw, _ := os.ReadFile(filepath.Join(dir, SecurityConfigFile))
// Extract the enc:// value from the saved file.
var tmp struct {
- ModelList []struct {
- APIKey string `json:"api_key"`
- } `json:"model_list"`
+ ModelList map[string]struct {
+ APIKeys []string `yaml:"api_keys"`
+ } `yaml:"model_list"`
}
- if err := json.Unmarshal(raw, &tmp); err != nil || len(tmp.ModelList) == 0 {
+ if err := yaml.Unmarshal(raw, &tmp); err != nil || len(tmp.ModelList) == 0 {
t.Fatalf("setup: could not parse saved config: %v", err)
}
- alreadyEncrypted := tmp.ModelList[0].APIKey
+ alreadyEncrypted := tmp.ModelList["pre:0"].APIKeys[0]
if !strings.HasPrefix(alreadyEncrypted, "enc://") {
t.Fatalf("setup: expected enc:// key, got %q", alreadyEncrypted)
}
@@ -882,19 +963,28 @@ func TestSaveConfig_MixedKeys(t *testing.T) {
t.Fatalf("setup: %v", err)
}
cfg := &Config{
- ModelList: []ModelConfig{
- {ModelName: "plain", Model: "openai/gpt-4", APIKey: "sk-new-plaintext"},
- {ModelName: "enc", Model: "openai/gpt-4", APIKey: alreadyEncrypted},
- {ModelName: "file", Model: "openai/gpt-4", APIKey: "file://api.key"},
+ ModelList: []*ModelConfig{
+ {ModelName: "plain", Model: "openai/gpt-4", apiKeys: []string{"sk-new-plaintext"}},
+ {ModelName: "enc", Model: "openai/gpt-4", apiKeys: []string{alreadyEncrypted}},
+ {ModelName: "file", Model: "openai/gpt-4", apiKeys: []string{"file://api.key"}},
+ },
+ security: &SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{
+ "plain:0": {APIKeys: []string{"sk-new-plaintext"}},
+ "enc:0": {APIKeys: []string{alreadyEncrypted}},
+ "file:0": {APIKeys: []string{"file://api.key"}},
+ },
},
}
if err := SaveConfig(cfgPath, cfg); err != nil {
t.Fatalf("SaveConfig: %v", err)
}
- raw, _ = os.ReadFile(cfgPath)
+ raw, _ = os.ReadFile(filepath.Join(dir, SecurityConfigFile))
s := string(raw)
+ t.Logf("saved file:\n%s", s)
+
// 1. Plaintext must be encrypted.
if strings.Contains(s, "sk-new-plaintext") {
t.Error("plaintext key must not appear in saved file")
@@ -915,7 +1005,7 @@ func TestSaveConfig_MixedKeys(t *testing.T) {
}
byName := make(map[string]string)
for _, m := range cfg2.ModelList {
- byName[m.ModelName] = m.APIKey
+ byName[m.ModelName] = m.APIKey()
}
if byName["plain"] != "sk-new-plaintext" {
t.Errorf("plain model api_key = %q, want %q", byName["plain"], "sk-new-plaintext")
@@ -939,26 +1029,26 @@ func TestLoadConfig_MixedKeys_NoPassphrase(t *testing.T) {
t.Setenv("PICOCLAW_KEY_PASSPHRASE", "test-passphrase")
mustSetupSSHKey(t)
if err := SaveConfig(cfgPath, &Config{
- ModelList: []ModelConfig{
- {ModelName: "m", Model: "openai/gpt-4", APIKey: "sk-secret"},
+ ModelList: []*ModelConfig{
+ {ModelName: "m", Model: "openai/gpt-4", apiKeys: []string{"sk-secret"}},
+ },
+ security: &SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{
+ "m:0": {APIKeys: []string{"sk-secret"}},
+ },
},
}); err != nil {
t.Fatalf("setup SaveConfig: %v", err)
}
- raw, _ := os.ReadFile(cfgPath)
- var tmp struct {
- ModelList []struct {
- APIKey string `json:"api_key"`
- } `json:"model_list"`
- }
- if err := json.Unmarshal(raw, &tmp); err != nil {
- t.Fatalf("setup parse: %v", err)
- }
- encValue := tmp.ModelList[0].APIKey
+ raw, err := LoadConfig(cfgPath)
+ assert.NoError(t, err)
+ encValue := raw.security.ModelList["m:0"].APIKeys[0]
+ assert.NotEmpty(t, encValue)
+ assert.Equal(t, "enc://", encValue[:6])
// Write a mixed config: enc:// + plaintext + file://
keyFile := filepath.Join(dir, "api.key")
- if err := os.WriteFile(keyFile, []byte("sk-from-file"), 0o600); err != nil {
+ if err = os.WriteFile(keyFile, []byte("sk-from-file"), 0o600); err != nil {
t.Fatalf("setup: %v", err)
}
mixed, _ := json.Marshal(map[string]any{
@@ -968,14 +1058,24 @@ func TestLoadConfig_MixedKeys_NoPassphrase(t *testing.T) {
{"model_name": "file", "model": "openai/gpt-4", "api_key": "file://api.key"},
},
})
- if err := os.WriteFile(cfgPath, mixed, 0o600); err != nil {
+ if err = os.WriteFile(cfgPath, mixed, 0o600); err != nil {
t.Fatalf("setup write: %v", err)
}
+ secs, _ := yaml.Marshal(map[string]any{
+ "model_list": map[string]map[string]any{
+ "enc:0": {"api_keys": []string{encValue}},
+ "plain:0": {"api_keys": []string{"sk-plain"}},
+ "file:0": {"api_keys": []string{"file://api.key"}},
+ },
+ })
+ if err = os.WriteFile(filepath.Join(dir, SecurityConfigFile), secs, 0o600); err != nil {
+ t.Fatalf("security write: %v", err)
+ }
// Now clear the passphrase — LoadConfig must fail because enc:// cannot be decrypted.
t.Setenv("PICOCLAW_KEY_PASSPHRASE", "")
- _, err := LoadConfig(cfgPath)
+ _, err = LoadConfig(cfgPath)
if err == nil {
t.Fatal("LoadConfig should fail when enc:// key is present and no passphrase is set")
}
@@ -1003,14 +1103,15 @@ func TestSaveConfig_UsesPassphraseProvider(t *testing.T) {
t.Cleanup(func() { credential.PassphraseProvider = orig })
cfg := DefaultConfig()
- cfg.ModelList = []ModelConfig{
- {ModelName: "test", Model: "openai/gpt-4", APIKey: "sk-plaintext"},
+ cfg.ModelList = []*ModelConfig{
+ {ModelName: "test", Model: "openai/gpt-4"},
}
+ cfg.security.ModelList["test:0"] = ModelSecurityEntry{APIKeys: []string{"sk-plaintext"}}
if err := SaveConfig(cfgPath, cfg); err != nil {
t.Fatalf("SaveConfig: %v", err)
}
- raw, _ := os.ReadFile(cfgPath)
+ raw, _ := os.ReadFile(filepath.Join(dir, SecurityConfigFile))
if !strings.Contains(string(raw), "enc://") {
t.Errorf("SaveConfig should have encrypted plaintext key via PassphraseProvider; got:\n%s", raw)
}
@@ -1053,7 +1154,101 @@ func TestLoadConfig_UsesPassphraseProvider(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig: %v", err)
}
- if cfg.ModelList[0].APIKey != plainKey {
- t.Errorf("api_key = %q, want %q", cfg.ModelList[0].APIKey, plainKey)
+ if cfg.ModelList[0].APIKey() != plainKey {
+ t.Errorf("api_key = %q, want %q", cfg.ModelList[0].APIKey(), plainKey)
+ }
+}
+
+func TestConfigParsesLogLevel(t *testing.T) {
+ dir := t.TempDir()
+ cfgPath := filepath.Join(dir, "config.json")
+ data := `{"version":1,"gateway":{"log_level":"debug"}}`
+ if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil {
+ t.Fatalf("setup: %v", err)
+ }
+
+ cfg, err := LoadConfig(cfgPath)
+ if err != nil {
+ t.Fatalf("LoadConfig: %v", err)
+ }
+ if cfg.Gateway.LogLevel != "debug" {
+ t.Errorf("LogLevel = %q, want \"debug\"", cfg.Gateway.LogLevel)
+ }
+}
+
+func TestConfigLogLevelEmpty(t *testing.T) {
+ dir := t.TempDir()
+ cfgPath := filepath.Join(dir, "config.json")
+ data := `{"version":1}`
+ if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil {
+ t.Fatalf("setup: %v", err)
+ }
+
+ cfg, err := LoadConfig(cfgPath)
+ if err != nil {
+ t.Fatalf("LoadConfig: %v", err)
+ }
+ // When config omits log_level, the DefaultConfig value ("fatal") is preserved.
+ if cfg.Gateway.LogLevel != "fatal" {
+ t.Errorf("LogLevel = %q, want \"fatal\"", cfg.Gateway.LogLevel)
+ }
+}
+
+func TestModelConfig_ExtraBodyRoundTrip(t *testing.T) {
+ dir := t.TempDir()
+ cfgPath := filepath.Join(dir, "config.json")
+
+ cfg := &Config{
+ ModelList: []*ModelConfig{
+ {
+ ModelName: "test-model",
+ Model: "openai/test",
+ apiKeys: []string{"sk-test"},
+ ExtraBody: map[string]any{"custom_field": "value", "num_field": 42},
+ },
+ },
+ security: &SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{"test-model:0": {APIKeys: []string{"sk-test"}}},
+ },
+ }
+
+ if err := SaveConfig(cfgPath, cfg); err != nil {
+ t.Fatalf("SaveConfig error: %v", err)
+ }
+
+ loaded, err := LoadConfig(cfgPath)
+ if err != nil {
+ t.Fatalf("LoadConfig error: %v", err)
+ }
+
+ if loaded.ModelList[0].ExtraBody == nil {
+ t.Fatal("ExtraBody should not be nil after round-trip")
+ }
+ if got := loaded.ModelList[0].ExtraBody["custom_field"]; got != "value" {
+ t.Errorf("ExtraBody[custom_field] = %v, want value", got)
+ }
+ if got := loaded.ModelList[0].ExtraBody["num_field"]; got != float64(42) {
+ t.Errorf("ExtraBody[num_field] = %v, want 42", got)
+ }
+}
+
+func TestDefaultConfig_MinimaxExtraBody(t *testing.T) {
+ cfg := DefaultConfig()
+
+ var minimaxCfg *ModelConfig
+ for i := range cfg.ModelList {
+ if cfg.ModelList[i].Model == "minimax/MiniMax-M2.5" {
+ minimaxCfg = cfg.ModelList[i]
+ break
+ }
+ }
+ if minimaxCfg == nil {
+ t.Fatal("Minimax model not found in ModelList")
+ }
+ if minimaxCfg.ExtraBody == nil {
+ t.Fatal("Minimax ExtraBody should not be nil")
+ }
+ if got, ok := minimaxCfg.ExtraBody["reasoning_split"]; !ok || got != true {
+ t.Fatalf("Minimax ExtraBody[reasoning_split] = %v, want true", got)
}
}
diff --git a/pkg/config/defaults.go b/pkg/config/defaults.go
index 4038696c4..ccfd5732a 100644
--- a/pkg/config/defaults.go
+++ b/pkg/config/defaults.go
@@ -8,6 +8,8 @@ package config
import (
"os"
"path/filepath"
+
+ "github.com/sipeed/picoclaw/pkg"
)
// DefaultConfig returns the default configuration for PicoClaw.
@@ -19,22 +21,23 @@ func DefaultConfig() *Config {
homePath = picoclawHome
} else {
userHome, _ := os.UserHomeDir()
- homePath = filepath.Join(userHome, ".picoclaw")
+ homePath = filepath.Join(userHome, pkg.DefaultPicoClawHome)
}
- workspacePath := filepath.Join(homePath, "workspace")
+ workspacePath := filepath.Join(homePath, pkg.WorkspaceName)
return &Config{
+ Version: CurrentVersion,
Agents: AgentsConfig{
Defaults: AgentDefaults{
Workspace: workspacePath,
RestrictToWorkspace: true,
Provider: "",
- Model: "",
MaxTokens: 32768,
Temperature: nil, // nil means use provider default
MaxToolIterations: 50,
SummarizeMessageThreshold: 20,
SummarizeTokenPercent: 75,
+ SteeringMode: "one-at-a-time",
ToolFeedback: ToolFeedbackConfig{
Enabled: true,
MaxArgsLength: 300,
@@ -55,26 +58,22 @@ func DefaultConfig() *Config {
},
Telegram: TelegramConfig{
Enabled: false,
- Token: "",
AllowFrom: FlexibleStringSlice{},
Typing: TypingConfig{Enabled: true},
Placeholder: PlaceholderConfig{
Enabled: true,
Text: "Thinking... 💭",
},
+ Streaming: StreamingConfig{Enabled: true, ThrottleSeconds: 3, MinGrowthChars: 200},
UseMarkdownV2: false,
},
Feishu: FeishuConfig{
- Enabled: false,
- AppID: "",
- AppSecret: "",
- EncryptKey: "",
- VerificationToken: "",
- AllowFrom: FlexibleStringSlice{},
+ Enabled: false,
+ AppID: "",
+ AllowFrom: FlexibleStringSlice{},
},
Discord: DiscordConfig{
Enabled: false,
- Token: "",
AllowFrom: FlexibleStringSlice{},
MentionOnly: false,
},
@@ -87,28 +86,23 @@ func DefaultConfig() *Config {
QQ: QQConfig{
Enabled: false,
AppID: "",
- AppSecret: "",
AllowFrom: FlexibleStringSlice{},
MaxMessageLength: 2000,
MaxBase64FileSizeMiB: 0,
},
DingTalk: DingTalkConfig{
- Enabled: false,
- ClientID: "",
- ClientSecret: "",
- AllowFrom: FlexibleStringSlice{},
+ Enabled: false,
+ ClientID: "",
+ AllowFrom: FlexibleStringSlice{},
},
Slack: SlackConfig{
Enabled: false,
- BotToken: "",
- AppToken: "",
AllowFrom: FlexibleStringSlice{},
},
Matrix: MatrixConfig{
Enabled: false,
Homeserver: "https://matrix.org",
UserID: "",
- AccessToken: "",
DeviceID: "",
JoinOnInvite: true,
AllowFrom: FlexibleStringSlice{},
@@ -121,60 +115,56 @@ func DefaultConfig() *Config {
},
},
LINE: LINEConfig{
- Enabled: false,
- ChannelSecret: "",
- ChannelAccessToken: "",
- WebhookHost: "0.0.0.0",
- WebhookPort: 18791,
- WebhookPath: "/webhook/line",
- AllowFrom: FlexibleStringSlice{},
- GroupTrigger: GroupTriggerConfig{MentionOnly: true},
+ Enabled: false,
+ WebhookHost: "0.0.0.0",
+ WebhookPort: 18791,
+ WebhookPath: "/webhook/line",
+ AllowFrom: FlexibleStringSlice{},
+ GroupTrigger: GroupTriggerConfig{MentionOnly: true},
},
OneBot: OneBotConfig{
- Enabled: false,
- WSUrl: "ws://127.0.0.1:3001",
- AccessToken: "",
- ReconnectInterval: 5,
- GroupTriggerPrefix: []string{},
- AllowFrom: FlexibleStringSlice{},
+ Enabled: false,
+ WSUrl: "ws://127.0.0.1:3001",
+ ReconnectInterval: 5,
+ AllowFrom: FlexibleStringSlice{},
},
WeCom: WeComConfig{
- Enabled: false,
- Token: "",
- EncodingAESKey: "",
- WebhookURL: "",
- WebhookHost: "0.0.0.0",
- WebhookPort: 18793,
- WebhookPath: "/webhook/wecom",
- AllowFrom: FlexibleStringSlice{},
- ReplyTimeout: 5,
+ Enabled: false,
+ WebhookURL: "",
+ WebhookHost: "0.0.0.0",
+ WebhookPort: 18793,
+ WebhookPath: "/webhook/wecom",
+ AllowFrom: FlexibleStringSlice{},
+ ReplyTimeout: 5,
},
WeComApp: WeComAppConfig{
- Enabled: false,
- CorpID: "",
- CorpSecret: "",
- AgentID: 0,
- Token: "",
- EncodingAESKey: "",
- WebhookHost: "0.0.0.0",
- WebhookPort: 18792,
- WebhookPath: "/webhook/wecom-app",
- AllowFrom: FlexibleStringSlice{},
- ReplyTimeout: 5,
+ Enabled: false,
+ CorpID: "",
+ AgentID: 0,
+ WebhookHost: "0.0.0.0",
+ WebhookPort: 18792,
+ WebhookPath: "/webhook/wecom-app",
+ AllowFrom: FlexibleStringSlice{},
+ ReplyTimeout: 5,
},
WeComAIBot: WeComAIBotConfig{
- Enabled: false,
- Token: "",
- EncodingAESKey: "",
- WebhookPath: "/webhook/wecom-aibot",
- AllowFrom: FlexibleStringSlice{},
- ReplyTimeout: 5,
- MaxSteps: 10,
- WelcomeMessage: "Hello! I'm your AI assistant. How can I help you today?",
+ Enabled: false,
+ WebhookPath: "/webhook/wecom-aibot",
+ AllowFrom: FlexibleStringSlice{},
+ ReplyTimeout: 5,
+ MaxSteps: 10,
+ WelcomeMessage: "Hello! I'm your AI assistant. How can I help you today?",
+ ProcessingMessage: DefaultWeComAIBotProcessingMessage,
+ },
+ Weixin: WeixinConfig{
+ Enabled: false,
+ BaseURL: "https://ilinkai.weixin.qq.com/",
+ CDNBaseURL: "https://novac2c.cdn.weixin.qq.com/c2c",
+ AllowFrom: FlexibleStringSlice{},
+ Proxy: "",
},
Pico: PicoConfig{
Enabled: false,
- Token: "",
PingInterval: 30,
ReadTimeout: 60,
WriteTimeout: 10,
@@ -182,10 +172,15 @@ func DefaultConfig() *Config {
AllowFrom: FlexibleStringSlice{},
},
},
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{WebSearch: true},
+ Hooks: HooksConfig{
+ Enabled: true,
+ Defaults: HookDefaultsConfig{
+ ObserverTimeoutMS: 500,
+ InterceptorTimeoutMS: 5000,
+ ApprovalTimeoutMS: 60000,
+ },
},
- ModelList: []ModelConfig{
+ ModelList: []*ModelConfig{
// ============================================
// Add your API key to the model you want to use
// ============================================
@@ -195,7 +190,6 @@ func DefaultConfig() *Config {
ModelName: "glm-4.7",
Model: "zhipu/glm-4.7",
APIBase: "https://open.bigmodel.cn/api/paas/v4",
- APIKey: "",
},
// OpenAI - https://platform.openai.com/api-keys
@@ -203,7 +197,6 @@ func DefaultConfig() *Config {
ModelName: "gpt-5.4",
Model: "openai/gpt-5.4",
APIBase: "https://api.openai.com/v1",
- APIKey: "",
},
// Anthropic Claude - https://console.anthropic.com/settings/keys
@@ -211,7 +204,6 @@ func DefaultConfig() *Config {
ModelName: "claude-sonnet-4.6",
Model: "anthropic/claude-sonnet-4.6",
APIBase: "https://api.anthropic.com/v1",
- APIKey: "",
},
// DeepSeek - https://platform.deepseek.com/
@@ -219,7 +211,6 @@ func DefaultConfig() *Config {
ModelName: "deepseek-chat",
Model: "deepseek/deepseek-chat",
APIBase: "https://api.deepseek.com/v1",
- APIKey: "",
},
// Google Gemini - https://ai.google.dev/
@@ -227,7 +218,6 @@ func DefaultConfig() *Config {
ModelName: "gemini-2.0-flash",
Model: "gemini/gemini-2.0-flash-exp",
APIBase: "https://generativelanguage.googleapis.com/v1beta",
- APIKey: "",
},
// Qwen (通义千问) - https://dashscope.console.aliyun.com/apiKey
@@ -235,7 +225,6 @@ func DefaultConfig() *Config {
ModelName: "qwen-plus",
Model: "qwen/qwen-plus",
APIBase: "https://dashscope.aliyuncs.com/compatible-mode/v1",
- APIKey: "",
},
// Moonshot (月之暗面) - https://platform.moonshot.cn/console/api-keys
@@ -243,7 +232,6 @@ func DefaultConfig() *Config {
ModelName: "moonshot-v1-8k",
Model: "moonshot/moonshot-v1-8k",
APIBase: "https://api.moonshot.cn/v1",
- APIKey: "",
},
// Groq - https://console.groq.com/keys
@@ -251,7 +239,6 @@ func DefaultConfig() *Config {
ModelName: "llama-3.3-70b",
Model: "groq/llama-3.3-70b-versatile",
APIBase: "https://api.groq.com/openai/v1",
- APIKey: "",
},
// OpenRouter (100+ models) - https://openrouter.ai/keys
@@ -259,13 +246,11 @@ func DefaultConfig() *Config {
ModelName: "openrouter-auto",
Model: "openrouter/auto",
APIBase: "https://openrouter.ai/api/v1",
- APIKey: "",
},
{
ModelName: "openrouter-gpt-5.4",
Model: "openrouter/openai/gpt-5.4",
APIBase: "https://openrouter.ai/api/v1",
- APIKey: "",
},
// NVIDIA - https://build.nvidia.com/
@@ -273,7 +258,6 @@ func DefaultConfig() *Config {
ModelName: "nemotron-4-340b",
Model: "nvidia/nemotron-4-340b-instruct",
APIBase: "https://integrate.api.nvidia.com/v1",
- APIKey: "",
},
// Cerebras - https://inference.cerebras.ai/
@@ -281,7 +265,6 @@ func DefaultConfig() *Config {
ModelName: "cerebras-llama-3.3-70b",
Model: "cerebras/llama-3.3-70b",
APIBase: "https://api.cerebras.ai/v1",
- APIKey: "",
},
// Vivgrid - https://vivgrid.com
@@ -289,7 +272,6 @@ func DefaultConfig() *Config {
ModelName: "vivgrid-auto",
Model: "vivgrid/auto",
APIBase: "https://api.vivgrid.com/v1",
- APIKey: "",
},
// Volcengine (火山引擎) - https://console.volcengine.com/ark
@@ -297,13 +279,11 @@ func DefaultConfig() *Config {
ModelName: "ark-code-latest",
Model: "volcengine/ark-code-latest",
APIBase: "https://ark.cn-beijing.volces.com/api/v3",
- APIKey: "",
},
{
ModelName: "doubao-pro",
Model: "volcengine/doubao-pro-32k",
APIBase: "https://ark.cn-beijing.volces.com/api/v3",
- APIKey: "",
},
// ShengsuanYun (神算云)
@@ -311,7 +291,6 @@ func DefaultConfig() *Config {
ModelName: "deepseek-v3",
Model: "shengsuanyun/deepseek-v3",
APIBase: "https://api.shengsuanyun.com/v1",
- APIKey: "",
},
// Antigravity (Google Cloud Code Assist) - OAuth only
@@ -334,7 +313,6 @@ func DefaultConfig() *Config {
ModelName: "llama3",
Model: "ollama/llama3",
APIBase: "http://localhost:11434/v1",
- APIKey: "ollama",
},
// Mistral AI - https://console.mistral.ai/api-keys
@@ -342,7 +320,6 @@ func DefaultConfig() *Config {
ModelName: "mistral-small",
Model: "mistral/mistral-small-latest",
APIBase: "https://api.mistral.ai/v1",
- APIKey: "",
},
// Avian - https://avian.io
@@ -350,13 +327,11 @@ func DefaultConfig() *Config {
ModelName: "deepseek-v3.2",
Model: "avian/deepseek/deepseek-v3.2",
APIBase: "https://api.avian.io/v1",
- APIKey: "",
},
{
ModelName: "kimi-k2.5",
Model: "avian/moonshotai/kimi-k2.5",
APIBase: "https://api.avian.io/v1",
- APIKey: "",
},
// Minimax - https://api.minimaxi.com/
@@ -364,7 +339,7 @@ func DefaultConfig() *Config {
ModelName: "MiniMax-M2.5",
Model: "minimax/MiniMax-M2.5",
APIBase: "https://api.minimaxi.com/v1",
- APIKey: "",
+ ExtraBody: map[string]any{"reasoning_split": true},
},
// LongCat - https://longcat.chat/platform
@@ -372,7 +347,6 @@ func DefaultConfig() *Config {
ModelName: "LongCat-Flash-Thinking",
Model: "longcat/LongCat-Flash-Thinking",
APIBase: "https://api.longcat.chat/openai",
- APIKey: "",
},
// ModelScope (魔搭社区) - https://modelscope.cn/my/tokens
@@ -380,7 +354,6 @@ func DefaultConfig() *Config {
ModelName: "modelscope-qwen",
Model: "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
APIBase: "https://api-inference.modelscope.cn/v1",
- APIKey: "",
},
// VLLM (local) - http://localhost:8000
@@ -388,7 +361,6 @@ func DefaultConfig() *Config {
ModelName: "local-model",
Model: "vllm/custom-model",
APIBase: "http://localhost:8000/v1",
- APIKey: "",
},
// Azure OpenAI - https://portal.azure.com
@@ -397,13 +369,13 @@ func DefaultConfig() *Config {
ModelName: "azure-gpt5",
Model: "azure/my-gpt5-deployment",
APIBase: "https://your-resource.openai.azure.com",
- APIKey: "",
},
},
Gateway: GatewayConfig{
Host: "127.0.0.1",
Port: 18790,
HotReload: false,
+ LogLevel: "fatal",
},
Tools: ToolsConfig{
MediaCleanup: MediaCleanupConfig{
@@ -423,14 +395,10 @@ func DefaultConfig() *Config {
Format: "plaintext",
Brave: BraveConfig{
Enabled: false,
- APIKey: "",
- APIKeys: nil,
MaxResults: 5,
},
Tavily: TavilyConfig{
Enabled: false,
- APIKey: "",
- APIKeys: nil,
MaxResults: 5,
},
DuckDuckGo: DuckDuckGoConfig{
@@ -439,8 +407,6 @@ func DefaultConfig() *Config {
},
Perplexity: PerplexityConfig{
Enabled: false,
- APIKey: "",
- APIKeys: nil,
MaxResults: 5,
},
SearXNG: SearXNGConfig{
@@ -450,11 +416,15 @@ func DefaultConfig() *Config {
},
GLMSearch: GLMSearchConfig{
Enabled: false,
- APIKey: "",
BaseURL: "https://open.bigmodel.cn/api/paas/v4/web_search",
SearchEngine: "search_std",
MaxResults: 5,
},
+ BaiduSearch: BaiduSearchConfig{
+ Enabled: false,
+ BaseURL: "https://qianfan.baidubce.com/v2/ai_search/web_search",
+ MaxResults: 10,
+ },
},
Cron: CronToolsConfig{
ToolConfig: ToolConfig{
@@ -556,6 +526,7 @@ func DefaultConfig() *Config {
MonitorUSB: true,
},
Voice: VoiceConfig{
+ ModelName: "",
EchoTranscription: false,
},
BuildInfo: BuildInfo{
@@ -564,5 +535,10 @@ func DefaultConfig() *Config {
BuildTime: BuildTime,
GoVersion: GoVersion,
},
+ security: &SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{},
+ Channels: ChannelsSecurity{},
+ Web: WebToolsSecurity{},
+ },
}
}
diff --git a/pkg/config/example_security_usage.go b/pkg/config/example_security_usage.go
new file mode 100644
index 000000000..cba76c6bc
--- /dev/null
+++ b/pkg/config/example_security_usage.go
@@ -0,0 +1,423 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+// This file demonstrates how to use the security configuration feature
+// It's not meant to be compiled, just for documentation purposes
+
+/*
+Package config
+
+# Example: Using Security Configuration
+
+## 1. Create security.yml
+
+File: ~/.picoclaw/security.yml
+
+```yaml
+# Model API Keys
+# Note: Use 'api_keys' array for multiple keys (load balancing/failover)
+# Single key should be provided as an array with one element
+model_list:
+
+ gpt-5.4:
+ api_keys:
+ - "sk-proj-your-actual-openai-key-1"
+ - "sk-proj-your-actual-openai-key-2" # Failover key
+ claude-sonnet-4.6:
+ api_keys:
+ - "sk-ant-your-actual-anthropic-key" # Single key in array format
+
+# Channel Tokens
+channels:
+
+ telegram:
+ token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
+ discord:
+ token: "your-discord-bot-token"
+
+# Web Tool Keys
+# Note: Use 'api_keys' array for multiple keys (load balancing/failover)
+# For GLMSearch, use 'api_key' (single string)
+web:
+
+ brave:
+ api_keys:
+ - "BSAyour-brave-api-key-1"
+ - "BSAyour-brave-api-key-2" # Failover key
+ tavily:
+ api_keys:
+ - "tvly-your-tavily-api-key" # Single key in array format
+ glm_search:
+ api_key: "your-glm-search-api-key" # Single key (not array)
+
+```
+
+## 2. Update config.json to use references
+
+File: ~/.picoclaw/config.json
+
+```json
+
+ {
+ "version": 1,
+ "agents": {
+ "defaults": {
+ "workspace": "~/picoclaw-workspace",
+ "model_name": "gpt-5.4"
+ }
+ },
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_base": "https://api.openai.com/v1",
+ "api_key": "ref:model_list.gpt-5.4.api_key"
+ },
+ {
+ "model_name": "claude-sonnet-4.6",
+ "model": "anthropic/claude-sonnet-4.6",
+ "api_base": "https://api.anthropic.com/v1",
+ "api_key": "ref:model_list.claude-sonnet-4.6.api_key"
+ }
+ ],
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "ref:channels.telegram.token"
+ },
+ "discord": {
+ "enabled": true,
+ "token": "ref:channels.discord.token"
+ }
+ },
+ "tools": {
+ "web": {
+ "brave": {
+ "enabled": true,
+ "api_key": "ref:web.brave.api_key"
+ },
+ "tavily": {
+ "enabled": true,
+ "api_key": "ref:web.tavily.api_key"
+ }
+ }
+ }
+ }
+
+```
+
+## 3. Set proper permissions
+
+```bash
+chmod 600 ~/.picoclaw/security.yml
+```
+
+## 4. Add to .gitignore
+
+```gitignore
+# Security configuration
+.security.yml
+```
+
+## 5. Verify it works
+
+```bash
+picoclaw --version
+```
+
+# Available Reference Paths
+
+## Model API Keys
+- ref:model_list..api_key
+
+Examples:
+- ref:model_list.gpt-5.4.api_key
+- ref:model_list.claude-sonnet-4.6.api_key
+
+**Note:** In .security.yml, use `api_keys` (array) format for models.
+Both single and multiple keys should use the array format.
+
+## Channel Tokens/Secrets
+- ref:channels.telegram.token
+- ref:channels.feishu.app_secret
+- ref:channels.feishu.encrypt_key
+- ref:channels.feishu.verification_token
+- ref:channels.discord.token
+- ref:channels.qq.app_secret
+- ref:channels.dingtalk.client_secret
+- ref:channels.slack.bot_token
+- ref:channels.slack.app_token
+- ref:channels.matrix.access_token
+- ref:channels.line.channel_secret
+- ref:channels.line.channel_access_token
+- ref:channels.onebot.access_token
+- ref:channels.wecom.token
+- ref:channels.wecom.encoding_aes_key
+- ref:channels.wecom_app.corp_secret
+- ref:channels.wecom_app.token
+- ref:channels.wecom_app.encoding_aes_key
+- ref:channels.wecom_aibot.token
+- ref:channels.wecom_aibot.encoding_aes_key
+- ref:channels.pico.token
+- ref:channels.irc.password
+- ref:channels.irc.nickserv_password
+- ref:channels.irc.sasl_password
+
+## Web Tool API Keys
+- ref:web.brave.api_key
+- ref:web.tavily.api_key
+- ref:web.perplexity.api_key
+- ref:web.glm_search.api_key
+
+**Note:**
+- Brave, Tavily, Perplexity: Use `api_keys` (array) format in .security.yml
+- GLMSearch: Use `api_key` (single string) format in .security.yml
+
+## Skills Registry Tokens
+- ref:skills.github.token
+- ref:skills.clawhub.auth_token
+
+# Backward Compatibility
+
+You can still use direct values in config.json if needed:
+
+```json
+
+ {
+ "model_list": [
+ {
+ "model_name": "local-model",
+ "model": "ollama/llama3",
+ "api_base": "http://localhost:11434/v1",
+ "api_key": "ollama" // Direct value (no reference)
+ }
+ ]
+ }
+
+```
+
+You can also mix references and direct values:
+
+```json
+
+ {
+ "model_list": [
+ {
+ "model_name": "cloud-model",
+ "api_key": "ref:model_list.cloud-model.api_key" // From .security.yml
+ },
+ {
+ "model_name": "local-model",
+ "api_key": "ollama" // Direct value
+ }
+ ]
+ }
+
+```
+
+# Migration from Old Config
+
+## Step 1: Backup your config
+```bash
+cp ~/.picoclaw/config.json ~/.picoclaw/config.json.backup
+```
+
+## Step 2: Copy the example security file
+```bash
+cp security.example.yml ~/.picoclaw/.security.yml
+```
+
+## Step 3: Fill in your API keys
+Edit ~/.picoclaw/.security.yml and replace placeholders with your actual keys.
+
+## Step 4: Update config.json references
+Replace sensitive values in ~/.picoclaw/config.json with ref: references.
+
+## Step 5: Test
+```bash
+picoclaw --version
+```
+
+If everything works, you can delete the backup:
+```bash
+rm ~/.picoclaw/config.json.backup
+```
+
+# Advanced Features
+
+## Multiple API Keys (Load Balancing & Failover)
+
+You can configure multiple API keys for both models and web tools to enable:
+- **Load balancing**: Requests are distributed across multiple keys
+- **Failover**: If a key fails, the system automatically switches to another key
+
+### Example: Model with Multiple Keys
+
+**.security.yml:**
+```yaml
+model_list:
+
+ gpt-5.4:
+ api_keys:
+ - "sk-proj-key-1"
+ - "sk-proj-key-2"
+ - "sk-proj-key-3"
+
+```
+
+**config.json:**
+```json
+
+ {
+ "model_list": [
+ {
+ "model_name": "gpt-5.4",
+ "model": "openai/gpt-5.4",
+ "api_key": "ref:model_list.gpt-5.4.api_key"
+ }
+ ]
+ }
+
+```
+
+### Example: Web Tool with Multiple Keys
+
+**.security.yml:**
+```yaml
+web:
+
+ brave:
+ api_keys:
+ - "BSA-key-1"
+ - "BSA-key-2"
+ tavily:
+ api_keys:
+ - "tvly-your-key" # Single key in array format
+ glm_search:
+ api_key: "your-glm-key" # GLMSearch uses single key format
+
+```
+
+**config.json:**
+```json
+
+ {
+ "tools": {
+ "web": {
+ "brave": {
+ "enabled": true,
+ "api_key": "ref:web.brave.api_key"
+ }
+ }
+ }
+ }
+
+```
+
+### Single Key
+
+Use array format with one element:
+```yaml
+model_list:
+
+ gpt-5.4:
+ api_keys:
+ - "sk-proj-your-key" # Single key in array format
+
+```
+
+### Multiple Keys (Load Balancing & Failover)
+
+Use array format with multiple elements:
+```yaml
+model_list:
+
+ gpt-5.4:
+ api_keys:
+ - "sk-proj-key-1"
+ - "sk-proj-key-2"
+ - "sk-proj-key-3"
+
+```
+
+**Important:** All model keys in .security.yml must use the `api_keys` (plural) array format.
+The single `api_key` (singular) format is NOT supported for models.
+
+### Model Index Matching
+
+The system supports intelligent model name matching in .security.yml:
+
+**Example 1: Exact Match**
+```yaml
+# config.json
+
+ {
+ "model_name": "gpt-5.4:0"
+ }
+
+# .security.yml (exact match with index)
+model_list:
+
+ gpt-5.4:0:
+ api_keys: ["key-1"]
+
+```
+
+**Example 2: Base Name Match**
+```yaml
+# config.json
+
+ {
+ "model_name": "gpt-5.4:0"
+ }
+
+# .security.yml (base name without index)
+model_list:
+
+ gpt-5.4:
+ api_keys: ["key-1"]
+
+```
+
+Both methods work. The base name match allows you to use simpler keys in .security.yml
+even when your config uses indexed model names for load balancing.
+
+### Security File Permissions
+
+The security file should have restricted permissions:
+
+```bash
+chmod 600 ~/.picoclaw/.security.yml
+```
+
+This ensures only the owner can read and write the file.
+
+# Security Best Practices
+
+1. Never commit .security.yml to version control
+2. Set file permissions: chmod 600 ~/.picoclaw/.security.yml
+3. Use different keys for different environments
+4. Rotate keys regularly and update .security.yml
+5. Encrypt backups containing .security.yml
+
+# Troubleshooting
+
+## Error: "model security entry not found"
+- Check that the model name in config.json matches exactly in .security.yml
+- Verify the model_list section exists in .security.yml
+
+## Error: "failed to load security config"
+- Ensure .security.yml exists in the same directory as config.json
+- Check YAML syntax is valid
+- Verify file permissions allow reading
+
+## Error: "unknown reference path"
+- Verify the reference format is correct
+- Check the path structure matches the examples above
+- Ensure all required sections exist in .security.yml
+*/
+package config
+
+// This file is documentation only
diff --git a/pkg/config/migration.go b/pkg/config/migration.go
index 832d8bf17..fee800a76 100644
--- a/pkg/config/migration.go
+++ b/pkg/config/migration.go
@@ -6,10 +6,15 @@
package config
import (
+ "encoding/json"
"slices"
"strings"
)
+type migratable interface {
+ Migrate() (*Config, error)
+}
+
// buildModelWithProtocol constructs a model string with protocol prefix.
// If the model already contains a "/" (indicating it has a protocol prefix), it is returned as-is.
// Otherwise, the protocol prefix is added.
@@ -21,31 +26,31 @@ func buildModelWithProtocol(protocol, model string) string {
return protocol + "/" + model
}
-// providerMigrationConfig defines how to migrate a provider from old config to new format.
-type providerMigrationConfig struct {
- // providerNames are the possible names used in agents.defaults.provider
- providerNames []string
- // protocol is the protocol prefix for the model field
- protocol string
- // buildConfig creates the ModelConfig from ProviderConfig
- buildConfig func(p ProvidersConfig) (ModelConfig, bool)
-}
-
-// ConvertProvidersToModelList converts the old ProvidersConfig to a slice of ModelConfig.
+// v0ConvertProvidersToModelList converts the old providersConfigV0 to a slice of ModelConfig.
// This enables backward compatibility with existing configurations.
// It preserves the user's configured model from agents.defaults.model when possible.
-func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
+func v0ConvertProvidersToModelList(cfg *configV0) []modelConfigV0 {
if cfg == nil {
return nil
}
+ // providerMigrationConfig defines how to migrate a provider from old config to new format.
+ type providerMigrationConfig struct {
+ // providerNames are the possible names used in agents.defaults.provider
+ providerNames []string
+ // protocol is the protocol prefix for the model field
+ protocol string
+ // buildConfig creates the ModelConfig from ProviderConfig
+ buildConfig func(p providersConfigV0) (modelConfigV0, bool)
+ }
+
// Get user's configured provider and model
userProvider := strings.ToLower(cfg.Agents.Defaults.Provider)
userModel := cfg.Agents.Defaults.GetModelName()
p := cfg.Providers
- var result []ModelConfig
+ var result []modelConfigV0
// Track if we've applied the legacy model name fix (only for first provider)
legacyModelNameApplied := false
@@ -55,11 +60,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"openai", "gpt"},
protocol: "openai",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.OpenAI.APIKey == "" && p.OpenAI.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "openai",
Model: "openai/gpt-5.4",
APIKey: p.OpenAI.APIKey,
@@ -73,11 +78,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"anthropic", "claude"},
protocol: "anthropic",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Anthropic.APIKey == "" && p.Anthropic.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "anthropic",
Model: "anthropic/claude-sonnet-4.6",
APIKey: p.Anthropic.APIKey,
@@ -91,11 +96,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"litellm"},
protocol: "litellm",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.LiteLLM.APIKey == "" && p.LiteLLM.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "litellm",
Model: "litellm/auto",
APIKey: p.LiteLLM.APIKey,
@@ -108,11 +113,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"openrouter"},
protocol: "openrouter",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.OpenRouter.APIKey == "" && p.OpenRouter.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "openrouter",
Model: "openrouter/auto",
APIKey: p.OpenRouter.APIKey,
@@ -125,11 +130,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"groq"},
protocol: "groq",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Groq.APIKey == "" && p.Groq.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "groq",
Model: "groq/llama-3.1-70b-versatile",
APIKey: p.Groq.APIKey,
@@ -142,11 +147,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"zhipu", "glm"},
protocol: "zhipu",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Zhipu.APIKey == "" && p.Zhipu.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "zhipu",
Model: "zhipu/glm-4",
APIKey: p.Zhipu.APIKey,
@@ -159,11 +164,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"vllm"},
protocol: "vllm",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.VLLM.APIKey == "" && p.VLLM.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "vllm",
Model: "vllm/auto",
APIKey: p.VLLM.APIKey,
@@ -176,11 +181,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"gemini", "google"},
protocol: "gemini",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Gemini.APIKey == "" && p.Gemini.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "gemini",
Model: "gemini/gemini-pro",
APIKey: p.Gemini.APIKey,
@@ -193,11 +198,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"nvidia"},
protocol: "nvidia",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Nvidia.APIKey == "" && p.Nvidia.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "nvidia",
Model: "nvidia/meta/llama-3.1-8b-instruct",
APIKey: p.Nvidia.APIKey,
@@ -210,11 +215,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"ollama"},
protocol: "ollama",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Ollama.APIKey == "" && p.Ollama.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "ollama",
Model: "ollama/llama3",
APIKey: p.Ollama.APIKey,
@@ -227,11 +232,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"moonshot", "kimi"},
protocol: "moonshot",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Moonshot.APIKey == "" && p.Moonshot.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "moonshot",
Model: "moonshot/kimi",
APIKey: p.Moonshot.APIKey,
@@ -244,11 +249,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"shengsuanyun"},
protocol: "shengsuanyun",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.ShengSuanYun.APIKey == "" && p.ShengSuanYun.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "shengsuanyun",
Model: "shengsuanyun/auto",
APIKey: p.ShengSuanYun.APIKey,
@@ -261,11 +266,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"deepseek"},
protocol: "deepseek",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.DeepSeek.APIKey == "" && p.DeepSeek.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "deepseek",
Model: "deepseek/deepseek-chat",
APIKey: p.DeepSeek.APIKey,
@@ -278,11 +283,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"cerebras"},
protocol: "cerebras",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Cerebras.APIKey == "" && p.Cerebras.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "cerebras",
Model: "cerebras/llama-3.3-70b",
APIKey: p.Cerebras.APIKey,
@@ -295,11 +300,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"vivgrid"},
protocol: "vivgrid",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Vivgrid.APIKey == "" && p.Vivgrid.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "vivgrid",
Model: "vivgrid/auto",
APIKey: p.Vivgrid.APIKey,
@@ -312,11 +317,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"volcengine", "doubao"},
protocol: "volcengine",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.VolcEngine.APIKey == "" && p.VolcEngine.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "volcengine",
Model: "volcengine/doubao-pro",
APIKey: p.VolcEngine.APIKey,
@@ -329,11 +334,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"github_copilot", "copilot"},
protocol: "github-copilot",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.GitHubCopilot.APIKey == "" && p.GitHubCopilot.APIBase == "" && p.GitHubCopilot.ConnectMode == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "github-copilot",
Model: "github-copilot/gpt-5.4",
APIBase: p.GitHubCopilot.APIBase,
@@ -344,11 +349,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"antigravity"},
protocol: "antigravity",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Antigravity.APIKey == "" && p.Antigravity.AuthMethod == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "antigravity",
Model: "antigravity/gemini-2.0-flash",
APIKey: p.Antigravity.APIKey,
@@ -359,11 +364,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"qwen", "tongyi"},
protocol: "qwen",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Qwen.APIKey == "" && p.Qwen.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "qwen",
Model: "qwen/qwen-max",
APIKey: p.Qwen.APIKey,
@@ -376,11 +381,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"mistral"},
protocol: "mistral",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Mistral.APIKey == "" && p.Mistral.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "mistral",
Model: "mistral/mistral-small-latest",
APIKey: p.Mistral.APIKey,
@@ -393,11 +398,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"avian"},
protocol: "avian",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.Avian.APIKey == "" && p.Avian.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "avian",
Model: "avian/deepseek/deepseek-v3.2",
APIKey: p.Avian.APIKey,
@@ -410,11 +415,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"longcat"},
protocol: "longcat",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.LongCat.APIKey == "" && p.LongCat.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "longcat",
Model: "longcat/LongCat-Flash-Thinking",
APIKey: p.LongCat.APIKey,
@@ -427,11 +432,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
{
providerNames: []string{"modelscope"},
protocol: "modelscope",
- buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
if p.ModelScope.APIKey == "" && p.ModelScope.APIBase == "" {
- return ModelConfig{}, false
+ return modelConfigV0{}, false
}
- return ModelConfig{
+ return modelConfigV0{
ModelName: "modelscope",
Model: "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
APIKey: p.ModelScope.APIKey,
@@ -469,83 +474,63 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return result
}
-// protocolProviderMapping maps a model protocol prefix (the part before "/" in
-// the Model field) to a function that extracts the corresponding ProviderConfig
-// from the legacy ProvidersConfig. Used by InheritProviderCredentials.
-var protocolProviderMapping = map[string]func(p ProvidersConfig) ProviderConfig{
- "openai": func(p ProvidersConfig) ProviderConfig { return p.OpenAI.ProviderConfig },
- "anthropic": func(p ProvidersConfig) ProviderConfig { return p.Anthropic },
- "litellm": func(p ProvidersConfig) ProviderConfig { return p.LiteLLM },
- "openrouter": func(p ProvidersConfig) ProviderConfig { return p.OpenRouter },
- "groq": func(p ProvidersConfig) ProviderConfig { return p.Groq },
- "zhipu": func(p ProvidersConfig) ProviderConfig { return p.Zhipu },
- "vllm": func(p ProvidersConfig) ProviderConfig { return p.VLLM },
- "gemini": func(p ProvidersConfig) ProviderConfig { return p.Gemini },
- "nvidia": func(p ProvidersConfig) ProviderConfig { return p.Nvidia },
- "ollama": func(p ProvidersConfig) ProviderConfig { return p.Ollama },
- "moonshot": func(p ProvidersConfig) ProviderConfig { return p.Moonshot },
- "shengsuanyun": func(p ProvidersConfig) ProviderConfig { return p.ShengSuanYun },
- "deepseek": func(p ProvidersConfig) ProviderConfig { return p.DeepSeek },
- "cerebras": func(p ProvidersConfig) ProviderConfig { return p.Cerebras },
- "vivgrid": func(p ProvidersConfig) ProviderConfig { return p.Vivgrid },
- "volcengine": func(p ProvidersConfig) ProviderConfig { return p.VolcEngine },
- "github-copilot": func(p ProvidersConfig) ProviderConfig { return p.GitHubCopilot },
- "antigravity": func(p ProvidersConfig) ProviderConfig { return p.Antigravity },
- "qwen": func(p ProvidersConfig) ProviderConfig { return p.Qwen },
- "mistral": func(p ProvidersConfig) ProviderConfig { return p.Mistral },
- "avian": func(p ProvidersConfig) ProviderConfig { return p.Avian },
- "minimax": func(p ProvidersConfig) ProviderConfig { return p.Minimax },
- "longcat": func(p ProvidersConfig) ProviderConfig { return p.LongCat },
- "modelscope": func(p ProvidersConfig) ProviderConfig { return p.ModelScope },
- "novita": func(p ProvidersConfig) ProviderConfig { return p.Novita },
-}
-
-// InheritProviderCredentials fills in missing api_key, api_base, proxy, and
-// request_timeout on model_list entries from the matching legacy providers
-// configuration. The match is determined by the protocol prefix in the Model
-// field (e.g. "deepseek/deepseek-chat" matches providers.deepseek).
-//
-// Only empty fields are filled — any value explicitly set on a model_list entry
-// takes precedence. This function modifies the slice in place.
-//
-// This bridges the gap described in issue #1635: users who configure
-// credentials once in the providers section expect model_list entries using
-// the same protocol to "just work" without duplicating credentials.
-func InheritProviderCredentials(models []ModelConfig, providers ProvidersConfig) {
- if providers.IsEmpty() {
- return
+// loadConfigV0 loads a legacy config (no version field)
+func loadConfigV0(data []byte) (migratable, error) {
+ var v0 configV0
+ if err := json.Unmarshal(data, &v0); err != nil {
+ return nil, err
}
- for i := range models {
- m := &models[i]
+ v0.migrateChannelConfigs()
- // Extract protocol prefix from Model field
- protocol := ""
- if idx := strings.Index(m.Model, "/"); idx > 0 {
- protocol = strings.ToLower(m.Model[:idx])
- }
- if protocol == "" {
- continue
- }
-
- getProvider, ok := protocolProviderMapping[protocol]
- if !ok {
- continue
- }
- pc := getProvider(providers)
-
- // Only fill empty fields — explicit model_list values win
- if m.APIKey == "" && pc.APIKey != "" {
- m.APIKey = pc.APIKey
- }
- if m.APIBase == "" && pc.APIBase != "" {
- m.APIBase = pc.APIBase
- }
- if m.Proxy == "" && pc.Proxy != "" {
- m.Proxy = pc.Proxy
- }
- if m.RequestTimeout == 0 && pc.RequestTimeout != 0 {
- m.RequestTimeout = pc.RequestTimeout
+ // Auto-migrate: if only legacy providers config exists, convert to model_list
+ if len(v0.ModelList) == 0 && !v0.Providers.IsEmpty() {
+ newModelList := v0ConvertProvidersToModelList(&v0)
+ // Convert []ModelConfig to []modelConfigV0
+ v0.ModelList = make([]modelConfigV0, len(newModelList))
+ for i, m := range newModelList {
+ v0.ModelList[i] = modelConfigV0{
+ ModelName: m.ModelName,
+ Model: m.Model,
+ APIBase: m.APIBase,
+ Proxy: m.Proxy,
+ Fallbacks: m.Fallbacks,
+ AuthMethod: m.AuthMethod,
+ ConnectMode: m.ConnectMode,
+ Workspace: m.Workspace,
+ RPM: m.RPM,
+ MaxTokensField: m.MaxTokensField,
+ RequestTimeout: m.RequestTimeout,
+ ThinkingLevel: m.ThinkingLevel,
+ APIKey: m.APIKey,
+ APIKeys: m.APIKeys,
+ }
}
}
+
+ return &v0, nil
+}
+
+// loadConfigV1 loads a version 1 config (current schema)
+func loadConfig(data []byte) (*Config, error) {
+ cfg := DefaultConfig()
+
+ // Pre-scan the JSON to check how many model_list entries the user provided.
+ // Go's JSON decoder reuses existing slice backing-array elements rather than
+ // zero-initializing them, so fields absent from the user's JSON (e.g. api_base)
+ // would silently inherit values from the DefaultConfig template at the same
+ // index position. We only reset cfg.ModelList when the user actually provides
+ // entries; when count is 0 we keep DefaultConfig's built-in list as fallback.
+ var tmp Config
+ if err := json.Unmarshal(data, &tmp); err != nil {
+ return nil, err
+ }
+ if len(tmp.ModelList) > 0 {
+ cfg.ModelList = nil
+ }
+
+ if err := json.Unmarshal(data, cfg); err != nil {
+ return nil, err
+ }
+ return cfg, nil
}
diff --git a/pkg/config/migration_integration_test.go b/pkg/config/migration_integration_test.go
new file mode 100644
index 000000000..c884a6b5d
--- /dev/null
+++ b/pkg/config/migration_integration_test.go
@@ -0,0 +1,568 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+// TestMigration_Integration_LegacyConfigWithoutWorkspace tests the issue reported:
+// User configured Model and Provider but no Workspace - settings should not be lost
+func TestMigration_Integration_LegacyConfigWithoutWorkspace(t *testing.T) {
+ // Create a temporary directory for test config files
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+
+ // Create a legacy config (version 0) with Model and Provider but NO Workspace
+ // This simulates the real-world scenario where user settings would be lost
+ legacyConfig := `{
+ "agents": {
+ "defaults": {
+ "provider": "openai",
+ "model": "gpt-4o",
+ "max_tokens": 8192,
+ "temperature": 0.7
+ }
+ },
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "test-token"
+ }
+ },
+ "gateway": {
+ "host": "127.0.0.1",
+ "port": 18790
+ },
+ "tools": {
+ "web": {
+ "enabled": true
+ }
+ },
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ },
+ "devices": {
+ "enabled": false
+ }
+ }`
+
+ if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+ t.Fatalf("Failed to write legacy config: %v", err)
+ }
+
+ // Load the config - this should trigger migration
+ cfg, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("LoadConfig failed: %v", err)
+ }
+
+ // Verify version is updated
+ if cfg.Version != CurrentVersion {
+ t.Errorf("Version = %d, want %d", cfg.Version, CurrentVersion)
+ }
+
+ // CRITICAL: Verify that user's settings are preserved
+ // This was the bug - these settings were lost when Workspace was empty
+ if cfg.Agents.Defaults.Provider != "openai" {
+ t.Errorf("Provider = %q, want %q (user's setting should be preserved)", cfg.Agents.Defaults.Provider, "openai")
+ }
+ // Old "model" field is migrated to "model_name" field
+ if cfg.Agents.Defaults.ModelName != "gpt-4o" {
+ t.Errorf(
+ "ModelName = %q, want %q (user's setting should be preserved)",
+ cfg.Agents.Defaults.ModelName, "gpt-4o",
+ )
+ }
+ // GetModelName() should also return the migrated value
+ if cfg.Agents.Defaults.GetModelName() != "gpt-4o" {
+ t.Errorf("GetModelName() = %q, want %q", cfg.Agents.Defaults.GetModelName(), "gpt-4o")
+ }
+ if cfg.Agents.Defaults.MaxTokens != 8192 {
+ t.Errorf("MaxTokens = %d, want %d", cfg.Agents.Defaults.MaxTokens, 8192)
+ }
+ if cfg.Agents.Defaults.Temperature == nil {
+ t.Error("Temperature should not be nil")
+ } else if *cfg.Agents.Defaults.Temperature != 0.7 {
+ t.Errorf("Temperature = %v, want %v", *cfg.Agents.Defaults.Temperature, 0.7)
+ }
+
+ // Verify Workspace has a default value (should not be empty)
+ if cfg.Agents.Defaults.Workspace == "" {
+ t.Error("Workspace should have a default value, not be empty")
+ }
+
+ // Verify other config sections are preserved
+ if !cfg.Channels.Telegram.Enabled {
+ t.Error("Telegram.Enabled should be true")
+ }
+ if cfg.Channels.Telegram.Token() != "test-token" {
+ t.Errorf("Telegram.Token = %q, want %q", cfg.Channels.Telegram.Token(), "test-token")
+ }
+ if cfg.Gateway.Port != 18790 {
+ t.Errorf("Gateway.Port = %d, want %d", cfg.Gateway.Port, 18790)
+ }
+}
+
+// TestMigration_Integration_LegacyConfigWithWorkspace tests migration with Workspace set
+func TestMigration_Integration_LegacyConfigWithWorkspace(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+
+ legacyConfig := `{
+ "agents": {
+ "defaults": {
+ "workspace": "/custom/workspace",
+ "provider": "deepseek",
+ "model": "deepseek-chat",
+ "max_tokens": 16384
+ }
+ },
+ "channels": {
+ "telegram": {
+ "enabled": false
+ }
+ },
+ "gateway": {
+ "host": "0.0.0.0",
+ "port": 8080
+ },
+ "tools": {
+ "web": {
+ "enabled": false
+ }
+ },
+ "heartbeat": {
+ "enabled": false
+ },
+ "devices": {
+ "enabled": true
+ }
+ }`
+
+ if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+ t.Fatalf("Failed to write legacy config: %v", err)
+ }
+
+ cfg, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("LoadConfig failed: %v", err)
+ }
+
+ // All user settings should be preserved
+ if cfg.Agents.Defaults.Workspace != "/custom/workspace" {
+ t.Errorf("Workspace = %q, want %q", cfg.Agents.Defaults.Workspace, "/custom/workspace")
+ }
+ if cfg.Agents.Defaults.Provider != "deepseek" {
+ t.Errorf("Provider = %q, want %q", cfg.Agents.Defaults.Provider, "deepseek")
+ }
+ if cfg.Agents.Defaults.ModelName != "deepseek-chat" {
+ t.Errorf("ModelName = %q, want %q", cfg.Agents.Defaults.ModelName, "deepseek-chat")
+ }
+ if cfg.Agents.Defaults.MaxTokens != 16384 {
+ t.Errorf("MaxTokens = %d, want %d", cfg.Agents.Defaults.MaxTokens, 16384)
+ }
+
+ // Verify other settings
+ if cfg.Gateway.Port != 8080 {
+ t.Errorf("Gateway.Port = %d, want %d", cfg.Gateway.Port, 8080)
+ }
+ if !cfg.Devices.Enabled {
+ t.Error("Devices.Enabled should be true")
+ }
+}
+
+// TestMigration_Integration_PreservesAllAgentsFields tests that ALL Agents fields are preserved
+func TestMigration_Integration_PreservesAllAgentsFields(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+
+ legacyConfig := `{
+ "agents": {
+ "defaults": {
+ "workspace": "",
+ "restrict_to_workspace": false,
+ "allow_read_outside_workspace": true,
+ "provider": "anthropic",
+ "model": "claude-opus-4",
+ "model_fallbacks": ["claude-sonnet-4", "claude-haiku-4"],
+ "image_model": "claude-opus-4-vision",
+ "image_model_fallbacks": ["claude-sonnet-4-vision"],
+ "max_tokens": 4096,
+ "temperature": 0.5,
+ "max_tool_iterations": 100,
+ "summarize_message_threshold": 30,
+ "summarize_token_percent": 80,
+ "max_media_size": 10485760
+ },
+ "list": [
+ {
+ "id": "special-agent",
+ "default": false,
+ "name": "Special Agent",
+ "workspace": "/special/workspace"
+ }
+ ]
+ },
+ "channels": {
+ "telegram": {"enabled": false}
+ },
+ "gateway": {
+ "host": "127.0.0.1",
+ "port": 18790
+ },
+ "tools": {
+ "web": {"enabled": true}
+ },
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ },
+ "devices": {
+ "enabled": false
+ }
+ }`
+
+ if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+ t.Fatalf("Failed to write legacy config: %v", err)
+ }
+
+ cfg, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("LoadConfig failed: %v", err)
+ }
+
+ // Verify ALL defaults fields are preserved
+ d := cfg.Agents.Defaults
+
+ if d.RestrictToWorkspace != false {
+ t.Errorf("RestrictToWorkspace = %v, want false", d.RestrictToWorkspace)
+ }
+ if d.AllowReadOutsideWorkspace != true {
+ t.Errorf("AllowReadOutsideWorkspace = %v, want true", d.AllowReadOutsideWorkspace)
+ }
+ if d.Provider != "anthropic" {
+ t.Errorf("Provider = %q, want %q", d.Provider, "anthropic")
+ }
+ if d.ModelName != "claude-opus-4" {
+ t.Errorf("ModelName = %q, want %q", d.ModelName, "claude-opus-4")
+ }
+ if len(d.ModelFallbacks) != 2 {
+ t.Errorf("len(ModelFallbacks) = %d, want 2", len(d.ModelFallbacks))
+ } else {
+ if d.ModelFallbacks[0] != "claude-sonnet-4" {
+ t.Errorf("ModelFallbacks[0] = %q, want %q", d.ModelFallbacks[0], "claude-sonnet-4")
+ }
+ if d.ModelFallbacks[1] != "claude-haiku-4" {
+ t.Errorf("ModelFallbacks[1] = %q, want %q", d.ModelFallbacks[1], "claude-haiku-4")
+ }
+ }
+ if d.ImageModel != "claude-opus-4-vision" {
+ t.Errorf("ImageModel = %q, want %q", d.ImageModel, "claude-opus-4-vision")
+ }
+ if len(d.ImageModelFallbacks) != 1 {
+ t.Errorf("len(ImageModelFallbacks) = %d, want 1", len(d.ImageModelFallbacks))
+ } else if d.ImageModelFallbacks[0] != "claude-sonnet-4-vision" {
+ t.Errorf("ImageModelFallbacks[0] = %q, want %q", d.ImageModelFallbacks[0], "claude-sonnet-4-vision")
+ }
+ if d.MaxTokens != 4096 {
+ t.Errorf("MaxTokens = %d, want %d", d.MaxTokens, 4096)
+ }
+ if d.Temperature == nil || *d.Temperature != 0.5 {
+ t.Errorf("Temperature = %v, want 0.5", d.Temperature)
+ }
+ if d.MaxToolIterations != 100 {
+ t.Errorf("MaxToolIterations = %d, want %d", d.MaxToolIterations, 100)
+ }
+ if d.SummarizeMessageThreshold != 30 {
+ t.Errorf("SummarizeMessageThreshold = %d, want %d", d.SummarizeMessageThreshold, 30)
+ }
+ if d.SummarizeTokenPercent != 80 {
+ t.Errorf("SummarizeTokenPercent = %d, want %d", d.SummarizeTokenPercent, 80)
+ }
+ if d.MaxMediaSize != 10485760 {
+ t.Errorf("MaxMediaSize = %d, want %d", d.MaxMediaSize, 10485760)
+ }
+
+ // Verify agent list is preserved
+ if len(cfg.Agents.List) != 1 {
+ t.Fatalf("len(Agents.List) = %d, want 1", len(cfg.Agents.List))
+ }
+ if cfg.Agents.List[0].ID != "special-agent" {
+ t.Errorf("Agent.ID = %q, want %q", cfg.Agents.List[0].ID, "special-agent")
+ }
+ if cfg.Agents.List[0].Workspace != "/special/workspace" {
+ t.Errorf("Agent.Workspace = %q, want %q", cfg.Agents.List[0].Workspace, "/special/workspace")
+ }
+
+ // Workspace should have default since it was empty in legacy config
+ if d.Workspace == "" {
+ t.Error("Workspace should have a default value, not be empty")
+ }
+}
+
+// TestMigration_Integration_ChannelsConfigMigrated tests channel config migration
+func TestMigration_Integration_ChannelsConfigMigrated(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+
+ // Legacy config with old channel field formats
+ legacyConfig := `{
+ "agents": {
+ "defaults": {}
+ },
+ "channels": {
+ "discord": {
+ "enabled": true,
+ "token": "discord-token",
+ "mention_only": true
+ },
+ "onebot": {
+ "enabled": true,
+ "ws_url": "ws://127.0.0.1:3001",
+ "group_trigger_prefix": ["/", "!"]
+ }
+ },
+ "gateway": {
+ "host": "127.0.0.1",
+ "port": 18790
+ },
+ "tools": {
+ "web": {"enabled": true}
+ },
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ },
+ "devices": {
+ "enabled": false
+ }
+ }`
+
+ if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+ t.Fatalf("Failed to write legacy config: %v", err)
+ }
+
+ cfg, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("LoadConfig failed: %v", err)
+ }
+
+ // Discord: mention_only should be migrated to group_trigger.mention_only
+ if cfg.Channels.Discord.GroupTrigger.MentionOnly != true {
+ t.Error("Discord.GroupTrigger.MentionOnly should be true after migration")
+ }
+
+ // OneBot: group_trigger_prefix should be migrated to group_trigger.prefixes
+ if len(cfg.Channels.OneBot.GroupTrigger.Prefixes) != 2 {
+ t.Errorf("len(OneBot.GroupTrigger.Prefixes) = %d, want 2", len(cfg.Channels.OneBot.GroupTrigger.Prefixes))
+ } else {
+ if cfg.Channels.OneBot.GroupTrigger.Prefixes[0] != "/" {
+ t.Errorf("Prefixes[0] = %q, want %q", cfg.Channels.OneBot.GroupTrigger.Prefixes[0], "/")
+ }
+ if cfg.Channels.OneBot.GroupTrigger.Prefixes[1] != "!" {
+ t.Errorf("Prefixes[1] = %q, want %q", cfg.Channels.OneBot.GroupTrigger.Prefixes[1], "!")
+ }
+ }
+}
+
+// TestMigration_Integration_RoundTrip_SerializeAndLoad tests that migrated config can be saved and reloaded
+func TestMigration_Integration_RoundTrip_SerializeAndLoad(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+
+ legacyConfig := `{
+ "agents": {
+ "defaults": {
+ "provider": "openai",
+ "model": "gpt-4o",
+ "max_tokens": 8192
+ }
+ },
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "test-token"
+ }
+ },
+ "gateway": {
+ "host": "127.0.0.1",
+ "port": 18790
+ },
+ "tools": {
+ "web": {"enabled": true}
+ },
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ },
+ "devices": {
+ "enabled": false
+ }
+ }`
+
+ if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+ t.Fatalf("Failed to write legacy config: %v", err)
+ }
+
+ // First load - triggers migration and saves
+ cfg1, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("First LoadConfig failed: %v", err)
+ }
+
+ // Read the migrated config from disk
+ migratedData, err := os.ReadFile(configPath)
+ if err != nil {
+ t.Fatalf("Failed to read migrated config: %v", err)
+ }
+
+ // Verify it has the current version
+ var versionCheck struct {
+ Version int `json:"version"`
+ }
+ if err = json.Unmarshal(migratedData, &versionCheck); err != nil {
+ t.Fatalf("Failed to parse migrated config version: %v", err)
+ }
+ if versionCheck.Version != CurrentVersion {
+ t.Errorf("Migrated config version = %d, want %d", versionCheck.Version, CurrentVersion)
+ }
+
+ // Second load - should load the migrated config without changes
+ cfg2, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("Second LoadConfig failed: %v", err)
+ }
+
+ // Verify configs are identical
+ if cfg2.Agents.Defaults.Provider != cfg1.Agents.Defaults.Provider {
+ t.Errorf("Provider changed from %q to %q", cfg1.Agents.Defaults.Provider, cfg2.Agents.Defaults.Provider)
+ }
+ if cfg2.Agents.Defaults.ModelName != cfg1.Agents.Defaults.ModelName {
+ t.Errorf("ModelName changed from %q to %q", cfg1.Agents.Defaults.ModelName, cfg2.Agents.Defaults.ModelName)
+ }
+ if cfg2.Agents.Defaults.MaxTokens != cfg1.Agents.Defaults.MaxTokens {
+ t.Errorf("MaxTokens changed from %d to %d", cfg1.Agents.Defaults.MaxTokens, cfg2.Agents.Defaults.MaxTokens)
+ }
+}
+
+// TestMigration_Integration_EmptyAgentsDefaults tests migration with completely empty agents config
+func TestMigration_Integration_EmptyAgentsDefaults(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+
+ // Legacy config with empty agents defaults
+ legacyConfig := `{
+ "agents": {
+ "defaults": {}
+ },
+ "channels": {
+ "telegram": {"enabled": false}
+ },
+ "gateway": {
+ "host": "127.0.0.1",
+ "port": 18790
+ },
+ "tools": {
+ "web": {"enabled": true}
+ },
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ },
+ "devices": {
+ "enabled": false
+ }
+ }`
+
+ if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+ t.Fatalf("Failed to write legacy config: %v", err)
+ }
+
+ cfg, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("LoadConfig failed: %v", err)
+ }
+
+ // Workspace should have default value
+ if cfg.Agents.Defaults.Workspace == "" {
+ t.Error("Workspace should have a default value")
+ }
+
+ // Note: When fields are explicitly set in config (even to zero values),
+ // they override defaults. This is correct JSON unmarshaling behavior.
+ // Users should set values they want; defaults are for unspecified fields.
+ if cfg.Agents.Defaults.MaxTokens == 0 {
+ // This is expected when users don't set max_tokens in their config
+ // The zero value (0) from the legacy config is preserved
+ }
+ if cfg.Agents.Defaults.MaxToolIterations == 0 {
+ // Same as above - zero value is preserved if it was in the config
+ }
+}
+
+// TestMigration_Integration_ModelNameField tests migration using new model_name field
+func TestMigration_Integration_ModelNameField(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+
+ // Legacy config using the new model_name field
+ legacyConfig := `{
+ "agents": {
+ "defaults": {
+ "provider": "deepseek",
+ "model_name": "deepseek-reasoner",
+ "model_fallbacks": ["deepseek-chat"]
+ }
+ },
+ "channels": {
+ "telegram": {"enabled": false}
+ },
+ "gateway": {
+ "host": "127.0.0.1",
+ "port": 18790
+ },
+ "tools": {
+ "web": {"enabled": true}
+ },
+ "heartbeat": {
+ "enabled": true,
+ "interval": 30
+ },
+ "devices": {
+ "enabled": false
+ }
+ }`
+
+ if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+ t.Fatalf("Failed to write legacy config: %v", err)
+ }
+
+ cfg, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("LoadConfig failed: %v", err)
+ }
+
+ // model_name field should be preserved
+ if cfg.Agents.Defaults.ModelName != "deepseek-reasoner" {
+ t.Errorf("ModelName = %q, want %q", cfg.Agents.Defaults.ModelName, "deepseek-reasoner")
+ }
+
+ // GetModelName() should return model_name, not model (deprecated)
+ if cfg.Agents.Defaults.GetModelName() != "deepseek-reasoner" {
+ t.Errorf("GetModelName() = %q, want %q", cfg.Agents.Defaults.GetModelName(), "deepseek-reasoner")
+ }
+
+ if len(cfg.Agents.Defaults.ModelFallbacks) != 1 {
+ t.Errorf("len(ModelFallbacks) = %d, want 1", len(cfg.Agents.Defaults.ModelFallbacks))
+ } else if cfg.Agents.Defaults.ModelFallbacks[0] != "deepseek-chat" {
+ t.Errorf("ModelFallbacks[0] = %q, want %q", cfg.Agents.Defaults.ModelFallbacks[0], "deepseek-chat")
+ }
+}
diff --git a/pkg/config/migration_test.go b/pkg/config/migration_test.go
index bea5b9034..aeabe9730 100644
--- a/pkg/config/migration_test.go
+++ b/pkg/config/migration_test.go
@@ -11,10 +11,10 @@ import (
)
func TestConvertProvidersToModelList_OpenAI(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{
- ProviderConfig: ProviderConfig{
+ cfg := &configV0{
+ Providers: providersConfigV0{
+ OpenAI: openAIProviderConfigV0{
+ providerConfigV0: providerConfigV0{
APIKey: "sk-test-key",
APIBase: "https://custom.api.com/v1",
},
@@ -22,7 +22,7 @@ func TestConvertProvidersToModelList_OpenAI(t *testing.T) {
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -40,16 +40,15 @@ func TestConvertProvidersToModelList_OpenAI(t *testing.T) {
}
func TestConvertProvidersToModelList_Anthropic(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{
- Anthropic: ProviderConfig{
- APIKey: "ant-key",
+ cfg := &configV0{
+ Providers: providersConfigV0{
+ Anthropic: providerConfigV0{
APIBase: "https://custom.anthropic.com",
},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -64,16 +63,15 @@ func TestConvertProvidersToModelList_Anthropic(t *testing.T) {
}
func TestConvertProvidersToModelList_LiteLLM(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{
- LiteLLM: ProviderConfig{
- APIKey: "litellm-key",
+ cfg := &configV0{
+ Providers: providersConfigV0{
+ LiteLLM: providerConfigV0{
APIBase: "http://localhost:4000/v1",
},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -91,15 +89,15 @@ func TestConvertProvidersToModelList_LiteLLM(t *testing.T) {
}
func TestConvertProvidersToModelList_Multiple(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "openai-key"}},
- Groq: ProviderConfig{APIKey: "groq-key"},
- Zhipu: ProviderConfig{APIKey: "zhipu-key"},
+ cfg := &configV0{
+ Providers: providersConfigV0{
+ OpenAI: openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "openai-key"}},
+ Groq: providerConfigV0{APIKey: "groq-key"},
+ Zhipu: providerConfigV0{APIKey: "zhipu-key"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 3 {
t.Fatalf("len(result) = %d, want 3", len(result))
@@ -119,11 +117,11 @@ func TestConvertProvidersToModelList_Multiple(t *testing.T) {
}
func TestConvertProvidersToModelList_Empty(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{},
+ cfg := &configV0{
+ Providers: providersConfigV0{},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 0 {
t.Errorf("len(result) = %d, want 0", len(result))
@@ -131,7 +129,7 @@ func TestConvertProvidersToModelList_Empty(t *testing.T) {
}
func TestConvertProvidersToModelList_Nil(t *testing.T) {
- result := ConvertProvidersToModelList(nil)
+ result := v0ConvertProvidersToModelList(nil)
if result != nil {
t.Errorf("result = %v, want nil", result)
@@ -139,35 +137,38 @@ func TestConvertProvidersToModelList_Nil(t *testing.T) {
}
func TestConvertProvidersToModelList_AllProviders(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "key1"}},
- LiteLLM: ProviderConfig{APIKey: "key-litellm", APIBase: "http://localhost:4000/v1"},
- Anthropic: ProviderConfig{APIKey: "key2"},
- OpenRouter: ProviderConfig{APIKey: "key3"},
- Groq: ProviderConfig{APIKey: "key4"},
- Zhipu: ProviderConfig{APIKey: "key5"},
- VLLM: ProviderConfig{APIKey: "key6"},
- Gemini: ProviderConfig{APIKey: "key7"},
- Nvidia: ProviderConfig{APIKey: "key8"},
- Ollama: ProviderConfig{APIKey: "key9"},
- Moonshot: ProviderConfig{APIKey: "key10"},
- ShengSuanYun: ProviderConfig{APIKey: "key11"},
- DeepSeek: ProviderConfig{APIKey: "key12"},
- Cerebras: ProviderConfig{APIKey: "key13"},
- Vivgrid: ProviderConfig{APIKey: "key14"},
- VolcEngine: ProviderConfig{APIKey: "key15"},
- GitHubCopilot: ProviderConfig{ConnectMode: "grpc"},
- Antigravity: ProviderConfig{AuthMethod: "oauth"},
- Qwen: ProviderConfig{APIKey: "key17"},
- Mistral: ProviderConfig{APIKey: "key18"},
- Avian: ProviderConfig{APIKey: "key19"},
- LongCat: ProviderConfig{APIKey: "key-longcat"},
- ModelScope: ProviderConfig{APIKey: "key-modelscope"},
+ // This test verifies that when providers have at least one configured field,
+ // they are converted. GitHubCopilot has ConnectMode set, Antigravity has AuthMethod.
+ // Other providers have no configuration, so they won't be converted.
+ cfg := &configV0{
+ Providers: providersConfigV0{
+ OpenAI: openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "key1"}},
+ LiteLLM: providerConfigV0{APIKey: "key-litellm", APIBase: "http://localhost:4000/v1"},
+ Anthropic: providerConfigV0{APIKey: "key2"},
+ OpenRouter: providerConfigV0{APIKey: "key3"},
+ Groq: providerConfigV0{APIKey: "key4"},
+ Zhipu: providerConfigV0{APIKey: "key5"},
+ VLLM: providerConfigV0{APIKey: "key6"},
+ Gemini: providerConfigV0{APIKey: "key7"},
+ Nvidia: providerConfigV0{APIKey: "key8"},
+ Ollama: providerConfigV0{APIKey: "key9"},
+ Moonshot: providerConfigV0{APIKey: "key10"},
+ ShengSuanYun: providerConfigV0{APIKey: "key11"},
+ DeepSeek: providerConfigV0{APIKey: "key12"},
+ Cerebras: providerConfigV0{APIKey: "key13"},
+ Vivgrid: providerConfigV0{APIKey: "key14"},
+ VolcEngine: providerConfigV0{APIKey: "key15"},
+ GitHubCopilot: providerConfigV0{ConnectMode: "grpc"},
+ Antigravity: providerConfigV0{AuthMethod: "oauth"},
+ Qwen: providerConfigV0{APIKey: "key17"},
+ Mistral: providerConfigV0{APIKey: "key18"},
+ Avian: providerConfigV0{APIKey: "key19"},
+ LongCat: providerConfigV0{APIKey: "key-longcat"},
+ ModelScope: providerConfigV0{APIKey: "key-modelscope"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
// All 23 providers should be converted
if len(result) != 23 {
@@ -176,10 +177,10 @@ func TestConvertProvidersToModelList_AllProviders(t *testing.T) {
}
func TestConvertProvidersToModelList_Proxy(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{
- ProviderConfig: ProviderConfig{
+ cfg := &configV0{
+ Providers: providersConfigV0{
+ OpenAI: openAIProviderConfigV0{
+ providerConfigV0: providerConfigV0{
APIKey: "key",
Proxy: "http://proxy:8080",
},
@@ -187,7 +188,7 @@ func TestConvertProvidersToModelList_Proxy(t *testing.T) {
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -199,16 +200,16 @@ func TestConvertProvidersToModelList_Proxy(t *testing.T) {
}
func TestConvertProvidersToModelList_RequestTimeout(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{
- Ollama: ProviderConfig{
- APIKey: "ollama-key",
+ cfg := &configV0{
+ Providers: providersConfigV0{
+ Ollama: providerConfigV0{
+ APIBase: "http://localhost:11434",
RequestTimeout: 300,
},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -220,17 +221,17 @@ func TestConvertProvidersToModelList_RequestTimeout(t *testing.T) {
}
func TestConvertProvidersToModelList_AuthMethod(t *testing.T) {
- cfg := &Config{
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{
- ProviderConfig: ProviderConfig{
+ cfg := &configV0{
+ Providers: providersConfigV0{
+ OpenAI: openAIProviderConfigV0{
+ providerConfigV0: providerConfigV0{
AuthMethod: "oauth",
},
},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 0 {
t.Errorf("len(result) = %d, want 0 (AuthMethod alone should not create entry)", len(result))
@@ -240,19 +241,19 @@ func TestConvertProvidersToModelList_AuthMethod(t *testing.T) {
// Tests for preserving user's configured model during migration
func TestConvertProvidersToModelList_PreservesUserModel_DeepSeek(t *testing.T) {
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "deepseek",
Model: "deepseek-reasoner",
},
},
- Providers: ProvidersConfig{
- DeepSeek: ProviderConfig{APIKey: "sk-deepseek"},
+ Providers: providersConfigV0{
+ DeepSeek: providerConfigV0{APIKey: "sk-deepseek"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -265,19 +266,19 @@ func TestConvertProvidersToModelList_PreservesUserModel_DeepSeek(t *testing.T) {
}
func TestConvertProvidersToModelList_PreservesUserModel_OpenAI(t *testing.T) {
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "openai",
Model: "gpt-4-turbo",
},
},
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "sk-openai"}},
+ Providers: providersConfigV0{
+ OpenAI: openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "sk-openai"}},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -289,19 +290,19 @@ func TestConvertProvidersToModelList_PreservesUserModel_OpenAI(t *testing.T) {
}
func TestConvertProvidersToModelList_PreservesUserModel_Anthropic(t *testing.T) {
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "claude", // alternative name
Model: "claude-opus-4-20250514",
},
},
- Providers: ProvidersConfig{
- Anthropic: ProviderConfig{APIKey: "sk-ant"},
+ Providers: providersConfigV0{
+ Anthropic: providerConfigV0{APIKey: "sk-ant"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -313,19 +314,19 @@ func TestConvertProvidersToModelList_PreservesUserModel_Anthropic(t *testing.T)
}
func TestConvertProvidersToModelList_PreservesUserModel_Qwen(t *testing.T) {
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "qwen",
Model: "qwen-plus",
},
},
- Providers: ProvidersConfig{
- Qwen: ProviderConfig{APIKey: "sk-qwen"},
+ Providers: providersConfigV0{
+ Qwen: providerConfigV0{APIKey: "sk-qwen"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -337,19 +338,19 @@ func TestConvertProvidersToModelList_PreservesUserModel_Qwen(t *testing.T) {
}
func TestConvertProvidersToModelList_UsesDefaultWhenNoUserModel(t *testing.T) {
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "deepseek",
Model: "", // no model specified
},
},
- Providers: ProvidersConfig{
- DeepSeek: ProviderConfig{APIKey: "sk-deepseek"},
+ Providers: providersConfigV0{
+ DeepSeek: providerConfigV0{APIKey: "sk-deepseek"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -362,20 +363,20 @@ func TestConvertProvidersToModelList_UsesDefaultWhenNoUserModel(t *testing.T) {
}
func TestConvertProvidersToModelList_MultipleProviders_PreservesUserModel(t *testing.T) {
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "deepseek",
Model: "deepseek-reasoner",
},
},
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "sk-openai"}},
- DeepSeek: ProviderConfig{APIKey: "sk-deepseek"},
+ Providers: providersConfigV0{
+ OpenAI: openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "sk-openai"}},
+ DeepSeek: providerConfigV0{APIKey: "sk-deepseek"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 2 {
t.Fatalf("len(result) = %d, want 2", len(result))
@@ -400,20 +401,20 @@ func TestConvertProvidersToModelList_ProviderNameAliases(t *testing.T) {
tests := []struct {
providerAlias string
expectedModel string
- provider ProviderConfig
+ provider providerConfigV0
}{
- {"gpt", "openai/gpt-4-custom", ProviderConfig{APIKey: "key"}},
- {"claude", "anthropic/claude-custom", ProviderConfig{APIKey: "key"}},
- {"doubao", "volcengine/doubao-custom", ProviderConfig{APIKey: "key"}},
- {"tongyi", "qwen/qwen-custom", ProviderConfig{APIKey: "key"}},
- {"kimi", "moonshot/kimi-custom", ProviderConfig{APIKey: "key"}},
+ {"gpt", "openai/gpt-4-custom", providerConfigV0{APIKey: "key"}},
+ {"claude", "anthropic/claude-custom", providerConfigV0{APIKey: "key"}},
+ {"doubao", "volcengine/doubao-custom", providerConfigV0{APIKey: "key"}},
+ {"tongyi", "qwen/qwen-custom", providerConfigV0{APIKey: "key"}},
+ {"kimi", "moonshot/kimi-custom", providerConfigV0{APIKey: "key"}},
}
for _, tt := range tests {
t.Run(tt.providerAlias, func(t *testing.T) {
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: tt.providerAlias,
Model: strings.TrimPrefix(
tt.expectedModel,
@@ -421,13 +422,13 @@ func TestConvertProvidersToModelList_ProviderNameAliases(t *testing.T) {
),
},
},
- Providers: ProvidersConfig{},
+ Providers: providersConfigV0{},
}
// Set the appropriate provider config
switch tt.providerAlias {
case "gpt":
- cfg.Providers.OpenAI = OpenAIProviderConfig{ProviderConfig: tt.provider}
+ cfg.Providers.OpenAI = openAIProviderConfigV0{providerConfigV0: tt.provider}
case "claude":
cfg.Providers.Anthropic = tt.provider
case "doubao":
@@ -444,7 +445,7 @@ func TestConvertProvidersToModelList_ProviderNameAliases(t *testing.T) {
tt.expectedModel[:strings.Index(tt.expectedModel, "/")+1],
)
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
}
@@ -466,19 +467,21 @@ func TestConvertProvidersToModelList_NoProviderField_SingleProvider(t *testing.T
// - No provider field set
// - model = "glm-4.7"
// - Only zhipu has API key configured
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "", // Not set
Model: "glm-4.7",
},
},
- Providers: ProvidersConfig{
- Zhipu: ProviderConfig{APIKey: "test-zhipu-key"},
+ Providers: providersConfigV0{
+ Zhipu: providerConfigV0{
+ APIKey: "test-zhipu-key",
+ },
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -499,20 +502,20 @@ func TestConvertProvidersToModelList_NoProviderField_MultipleProviders(t *testin
// When multiple providers are configured but no provider field is set,
// the FIRST provider (in migration order) will use userModel as ModelName
// for backward compatibility with legacy implicit provider selection
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "", // Not set
Model: "some-model",
},
},
- Providers: ProvidersConfig{
- OpenAI: OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "openai-key"}},
- Zhipu: ProviderConfig{APIKey: "zhipu-key"},
+ Providers: providersConfigV0{
+ OpenAI: openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "openai-key"}},
+ Zhipu: providerConfigV0{APIKey: "zhipu-key"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 2 {
t.Fatalf("len(result) = %d, want 2", len(result))
@@ -532,19 +535,19 @@ func TestConvertProvidersToModelList_NoProviderField_MultipleProviders(t *testin
func TestConvertProvidersToModelList_NoProviderField_NoModel(t *testing.T) {
// Edge case: no provider, no model
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "",
Model: "",
},
},
- Providers: ProvidersConfig{
- Zhipu: ProviderConfig{APIKey: "zhipu-key"},
+ Providers: providersConfigV0{
+ Zhipu: providerConfigV0{APIKey: "zhipu-key"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) != 1 {
t.Fatalf("len(result) = %d, want 1", len(result))
@@ -585,19 +588,19 @@ func TestBuildModelWithProtocol_DifferentPrefix(t *testing.T) {
// Test for legacy config with protocol prefix in model name
func TestConvertProvidersToModelList_LegacyModelWithProtocolPrefix(t *testing.T) {
- cfg := &Config{
- Agents: AgentsConfig{
- Defaults: AgentDefaults{
+ cfg := &configV0{
+ Agents: agentsConfigV0{
+ Defaults: agentDefaultsV0{
Provider: "", // No explicit provider
Model: "openrouter/auto", // Model already has protocol prefix
},
},
- Providers: ProvidersConfig{
- OpenRouter: ProviderConfig{APIKey: "sk-or-test"},
+ Providers: providersConfigV0{
+ OpenRouter: providerConfigV0{APIKey: "sk-or-test"},
},
}
- result := ConvertProvidersToModelList(cfg)
+ result := v0ConvertProvidersToModelList(cfg)
if len(result) < 1 {
t.Fatalf("len(result) = %d, want at least 1", len(result))
@@ -613,143 +616,3 @@ func TestConvertProvidersToModelList_LegacyModelWithProtocolPrefix(t *testing.T)
t.Errorf("Model = %q, want %q (should not duplicate prefix)", result[0].Model, "openrouter/auto")
}
}
-
-// ---------- InheritProviderCredentials tests ----------
-
-func TestInheritProviderCredentials_FillsMissingAPIKey(t *testing.T) {
- models := []ModelConfig{
- {ModelName: "my-deepseek", Model: "deepseek/deepseek-chat"},
- }
- providers := ProvidersConfig{
- DeepSeek: ProviderConfig{
- APIKey: "sk-deepseek-from-providers",
- APIBase: "https://api.deepseek.com/v1",
- },
- }
-
- InheritProviderCredentials(models, providers)
-
- if models[0].APIKey != "sk-deepseek-from-providers" {
- t.Errorf("APIKey = %q, want %q", models[0].APIKey, "sk-deepseek-from-providers")
- }
- if models[0].APIBase != "https://api.deepseek.com/v1" {
- t.Errorf("APIBase = %q, want %q", models[0].APIBase, "https://api.deepseek.com/v1")
- }
-}
-
-func TestInheritProviderCredentials_ExplicitValuesTakePrecedence(t *testing.T) {
- models := []ModelConfig{
- {
- ModelName: "my-openai",
- Model: "openai/gpt-5.4",
- APIKey: "sk-explicit-model-key",
- APIBase: "https://my-custom-endpoint.com/v1",
- },
- }
- providers := ProvidersConfig{
- OpenAI: OpenAIProviderConfig{
- ProviderConfig: ProviderConfig{
- APIKey: "sk-provider-key",
- APIBase: "https://api.openai.com/v1",
- },
- },
- }
-
- InheritProviderCredentials(models, providers)
-
- if models[0].APIKey != "sk-explicit-model-key" {
- t.Errorf("APIKey = %q, want %q (explicit should win)", models[0].APIKey, "sk-explicit-model-key")
- }
- if models[0].APIBase != "https://my-custom-endpoint.com/v1" {
- t.Errorf("APIBase = %q, want %q (explicit should win)", models[0].APIBase, "https://my-custom-endpoint.com/v1")
- }
-}
-
-func TestInheritProviderCredentials_MultipleModels(t *testing.T) {
- models := []ModelConfig{
- {ModelName: "groq-llama", Model: "groq/llama-3.1-70b"},
- {ModelName: "zhipu-glm", Model: "zhipu/glm-4"},
- {ModelName: "custom-openai", Model: "openai/gpt-5.4", APIKey: "sk-already-set"},
- }
- providers := ProvidersConfig{
- Groq: ProviderConfig{APIKey: "gsk-groq-key", Proxy: "http://proxy:8080"},
- Zhipu: ProviderConfig{APIKey: "zhipu-key-123", APIBase: "https://zhipu.example.com"},
- OpenAI: OpenAIProviderConfig{
- ProviderConfig: ProviderConfig{APIKey: "sk-should-not-override"},
- },
- }
-
- InheritProviderCredentials(models, providers)
-
- // groq model should inherit
- if models[0].APIKey != "gsk-groq-key" {
- t.Errorf("groq APIKey = %q, want %q", models[0].APIKey, "gsk-groq-key")
- }
- if models[0].Proxy != "http://proxy:8080" {
- t.Errorf("groq Proxy = %q, want %q", models[0].Proxy, "http://proxy:8080")
- }
-
- // zhipu model should inherit
- if models[1].APIKey != "zhipu-key-123" {
- t.Errorf("zhipu APIKey = %q, want %q", models[1].APIKey, "zhipu-key-123")
- }
- if models[1].APIBase != "https://zhipu.example.com" {
- t.Errorf("zhipu APIBase = %q, want %q", models[1].APIBase, "https://zhipu.example.com")
- }
-
- // openai model already has key — should NOT be overridden
- if models[2].APIKey != "sk-already-set" {
- t.Errorf("openai APIKey = %q, want %q (should not be overridden)", models[2].APIKey, "sk-already-set")
- }
-}
-
-func TestInheritProviderCredentials_NoMatchingProvider(t *testing.T) {
- models := []ModelConfig{
- {ModelName: "my-model", Model: "novelai/some-model"},
- }
- providers := ProvidersConfig{
- DeepSeek: ProviderConfig{APIKey: "sk-deepseek"},
- }
-
- InheritProviderCredentials(models, providers)
-
- // No matching provider for "novelai" protocol — should stay empty
- if models[0].APIKey != "" {
- t.Errorf("APIKey = %q, want empty (no matching provider)", models[0].APIKey)
- }
-}
-
-func TestInheritProviderCredentials_EmptyProviders(t *testing.T) {
- models := []ModelConfig{
- {ModelName: "my-model", Model: "openai/gpt-5.4"},
- }
- providers := ProvidersConfig{} // all empty
-
- InheritProviderCredentials(models, providers)
-
- // Empty providers — nothing to inherit
- if models[0].APIKey != "" {
- t.Errorf("APIKey = %q, want empty", models[0].APIKey)
- }
-}
-
-func TestInheritProviderCredentials_InheritsRequestTimeout(t *testing.T) {
- models := []ModelConfig{
- {ModelName: "my-ollama", Model: "ollama/llama3.2:3b"},
- }
- providers := ProvidersConfig{
- Ollama: ProviderConfig{
- APIBase: "http://localhost:11434",
- RequestTimeout: 120,
- },
- }
-
- InheritProviderCredentials(models, providers)
-
- if models[0].APIBase != "http://localhost:11434" {
- t.Errorf("APIBase = %q, want %q", models[0].APIBase, "http://localhost:11434")
- }
- if models[0].RequestTimeout != 120 {
- t.Errorf("RequestTimeout = %d, want 120", models[0].RequestTimeout)
- }
-}
diff --git a/pkg/config/model_config_test.go b/pkg/config/model_config_test.go
index 9bc600ed9..3252d2f26 100644
--- a/pkg/config/model_config_test.go
+++ b/pkg/config/model_config_test.go
@@ -13,12 +13,20 @@ import (
)
func TestGetModelConfig_Found(t *testing.T) {
- cfg := &Config{
- ModelList: []ModelConfig{
- {ModelName: "test-model", Model: "openai/gpt-4o", APIKey: "key1"},
- {ModelName: "other-model", Model: "anthropic/claude", APIKey: "key2"},
+ cfg := (&Config{
+ Version: CurrentVersion,
+ ModelList: []*ModelConfig{
+ {ModelName: "test-model", Model: "openai/gpt-4o"},
+ {ModelName: "other-model", Model: "anthropic/claude"},
},
- }
+ }).WithSecurity(&SecurityConfig{ModelList: map[string]ModelSecurityEntry{
+ "test-model:0": {
+ APIKeys: []string{"key1"},
+ },
+ "other-model:0": {
+ APIKeys: []string{"key2"},
+ },
+ }})
result, err := cfg.GetModelConfig("test-model")
if err != nil {
@@ -30,11 +38,17 @@ func TestGetModelConfig_Found(t *testing.T) {
}
func TestGetModelConfig_NotFound(t *testing.T) {
- cfg := &Config{
- ModelList: []ModelConfig{
- {ModelName: "test-model", Model: "openai/gpt-4o", APIKey: "key1"},
+ cfg := (&Config{
+ ModelList: []*ModelConfig{
+ {ModelName: "test-model", Model: "openai/gpt-4o"},
},
- }
+ }).WithSecurity(&SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{
+ "test-model:0": {
+ APIKeys: []string{"key1"},
+ },
+ },
+ })
_, err := cfg.GetModelConfig("nonexistent")
if err == nil {
@@ -44,7 +58,7 @@ func TestGetModelConfig_NotFound(t *testing.T) {
func TestGetModelConfig_EmptyList(t *testing.T) {
cfg := &Config{
- ModelList: []ModelConfig{},
+ ModelList: []*ModelConfig{},
}
_, err := cfg.GetModelConfig("any-model")
@@ -54,13 +68,25 @@ func TestGetModelConfig_EmptyList(t *testing.T) {
}
func TestGetModelConfig_RoundRobin(t *testing.T) {
- cfg := &Config{
- ModelList: []ModelConfig{
- {ModelName: "lb-model", Model: "openai/gpt-4o-1", APIKey: "key1"},
- {ModelName: "lb-model", Model: "openai/gpt-4o-2", APIKey: "key2"},
- {ModelName: "lb-model", Model: "openai/gpt-4o-3", APIKey: "key3"},
+ cfg := (&Config{
+ ModelList: []*ModelConfig{
+ {ModelName: "lb-model", Model: "openai/gpt-4o-1"},
+ {ModelName: "lb-model", Model: "openai/gpt-4o-2"},
+ {ModelName: "lb-model", Model: "openai/gpt-4o-3"},
},
- }
+ }).WithSecurity(&SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{
+ "lb-model:0": {
+ APIKeys: []string{"key1"},
+ },
+ "lb-model:1": {
+ APIKeys: []string{"key2"},
+ },
+ "lb-model:2": {
+ APIKeys: []string{"key3"},
+ },
+ },
+ })
// Test round-robin distribution
results := make(map[string]int)
@@ -84,10 +110,10 @@ func TestGetModelConfig_RoundRobinStartsFromFirstMatch(t *testing.T) {
rrCounter.Store(0)
cfg := &Config{
- ModelList: []ModelConfig{
- {ModelName: "lb-model", Model: "openai/gpt-4o-1", APIKey: "key1"},
- {ModelName: "lb-model", Model: "openai/gpt-4o-2", APIKey: "key2"},
- {ModelName: "lb-model", Model: "openai/gpt-4o-3", APIKey: "key3"},
+ ModelList: []*ModelConfig{
+ {ModelName: "lb-model", Model: "openai/gpt-4o-1", apiKeys: []string{"key1"}},
+ {ModelName: "lb-model", Model: "openai/gpt-4o-2", apiKeys: []string{"key2"}},
+ {ModelName: "lb-model", Model: "openai/gpt-4o-3", apiKeys: []string{"key3"}},
},
}
@@ -112,9 +138,9 @@ func TestGetModelConfig_RoundRobinStartsFromFirstMatch(t *testing.T) {
func TestGetModelConfig_Concurrent(t *testing.T) {
cfg := &Config{
- ModelList: []ModelConfig{
- {ModelName: "concurrent-model", Model: "openai/gpt-4o-1", APIKey: "key1"},
- {ModelName: "concurrent-model", Model: "openai/gpt-4o-2", APIKey: "key2"},
+ ModelList: []*ModelConfig{
+ {ModelName: "concurrent-model", Model: "openai/gpt-4o-1", apiKeys: []string{"key1"}},
+ {ModelName: "concurrent-model", Model: "openai/gpt-4o-2", apiKeys: []string{"key2"}},
},
}
@@ -143,39 +169,7 @@ func TestGetModelConfig_Concurrent(t *testing.T) {
}
}
-func TestAgentDefaults_GetModelName_BackwardCompat(t *testing.T) {
- tests := []struct {
- name string
- defaults AgentDefaults
- wantName string
- }{
- {
- name: "new model_name field only",
- defaults: AgentDefaults{ModelName: "new-model"},
- wantName: "new-model",
- },
- {
- name: "old model field only",
- defaults: AgentDefaults{Model: "legacy-model"},
- wantName: "legacy-model",
- },
- {
- name: "both fields - model_name takes precedence",
- defaults: AgentDefaults{ModelName: "new-model", Model: "old-model"},
- wantName: "new-model",
- },
- }
-
- for _, tt := range tests {
- t.Run(tt.name, func(t *testing.T) {
- if got := tt.defaults.GetModelName(); got != tt.wantName {
- t.Errorf("GetModelName() = %q, want %q", got, tt.wantName)
- }
- })
- }
-}
-
-func TestAgentDefaults_JSON_BackwardCompat(t *testing.T) {
+func TestAgentDefaultsV0_JSON_BackwardCompat(t *testing.T) {
tests := []struct {
name string
json string
@@ -200,7 +194,7 @@ func TestAgentDefaults_JSON_BackwardCompat(t *testing.T) {
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
- var defaults AgentDefaults
+ var defaults agentDefaultsV0
if err := json.Unmarshal([]byte(tt.json), &defaults); err != nil {
t.Fatalf("Unmarshal error: %v", err)
}
@@ -211,69 +205,6 @@ func TestAgentDefaults_JSON_BackwardCompat(t *testing.T) {
}
}
-func TestFullConfig_JSON_BackwardCompat(t *testing.T) {
- // Test complete config with both old and new formats
- oldFormat := `{
- "agents": {
- "defaults": {
- "workspace": "~/.picoclaw/workspace",
- "model": "gpt4",
- "max_tokens": 4096
- }
- },
- "model_list": [
- {
- "model_name": "gpt4",
- "model": "openai/gpt-4o",
- "api_key": "test-key"
- }
- ]
- }`
-
- newFormat := `{
- "agents": {
- "defaults": {
- "workspace": "~/.picoclaw/workspace",
- "model_name": "gpt4",
- "max_tokens": 4096
- }
- },
- "model_list": [
- {
- "model_name": "gpt4",
- "model": "openai/gpt-4o",
- "api_key": "test-key"
- }
- ]
- }`
-
- for name, jsonStr := range map[string]string{
- "old format (model)": oldFormat,
- "new format (model_name)": newFormat,
- } {
- t.Run(name, func(t *testing.T) {
- cfg := &Config{}
- if err := json.Unmarshal([]byte(jsonStr), cfg); err != nil {
- t.Fatalf("Unmarshal error: %v", err)
- }
-
- // Check that GetModelName returns correct value
- if got := cfg.Agents.Defaults.GetModelName(); got != "gpt4" {
- t.Errorf("GetModelName() = %q, want %q", got, "gpt4")
- }
-
- // Check that GetModelConfig works
- modelCfg, err := cfg.GetModelConfig("gpt4")
- if err != nil {
- t.Fatalf("GetModelConfig error: %v", err)
- }
- if modelCfg.Model != "openai/gpt-4o" {
- t.Errorf("Model = %q, want %q", modelCfg.Model, "openai/gpt-4o")
- }
- })
- }
-}
-
func TestModelConfig_Validate(t *testing.T) {
tests := []struct {
name string
@@ -329,7 +260,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
{
name: "valid list",
config: &Config{
- ModelList: []ModelConfig{
+ ModelList: []*ModelConfig{
{ModelName: "test1", Model: "openai/gpt-4o"},
{ModelName: "test2", Model: "anthropic/claude"},
},
@@ -339,7 +270,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
{
name: "invalid entry",
config: &Config{
- ModelList: []ModelConfig{
+ ModelList: []*ModelConfig{
{ModelName: "test1", Model: "openai/gpt-4o"},
{ModelName: "", Model: "anthropic/claude"}, // missing model_name
},
@@ -350,7 +281,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
{
name: "empty list",
config: &Config{
- ModelList: []ModelConfig{},
+ ModelList: []*ModelConfig{},
},
wantErr: false,
},
@@ -358,10 +289,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
// Load balancing: multiple entries with same model_name are allowed
name: "duplicate model_name for load balancing",
config: &Config{
- ModelList: []ModelConfig{
- {ModelName: "gpt-4", Model: "openai/gpt-4o", APIKey: "key1"},
- {ModelName: "gpt-4", Model: "openai/gpt-4-turbo", APIKey: "key2"},
- },
+ ModelList: []*ModelConfig{},
},
wantErr: false, // Changed: duplicates are allowed for load balancing
},
@@ -369,7 +297,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
// Load balancing: non-adjacent entries with same model_name are also allowed
name: "duplicate model_name non-adjacent for load balancing",
config: &Config{
- ModelList: []ModelConfig{
+ ModelList: []*ModelConfig{
{ModelName: "model-a", Model: "openai/gpt-4o"},
{ModelName: "model-b", Model: "anthropic/claude"},
{ModelName: "model-a", Model: "openai/gpt-4-turbo"},
diff --git a/pkg/config/multikey_test.go b/pkg/config/multikey_test.go
index b899b991c..cc529905c 100644
--- a/pkg/config/multikey_test.go
+++ b/pkg/config/multikey_test.go
@@ -5,15 +5,15 @@ import (
)
func TestExpandMultiKeyModels_SingleKey(t *testing.T) {
- models := []ModelConfig{
+ models := []*ModelConfig{
{
ModelName: "gpt-4",
Model: "openai/gpt-4o",
- APIKey: "single-key",
+ apiKeys: []string{"single-key"},
},
}
- result := ExpandMultiKeyModels(models)
+ result := expandMultiKeyModels(models)
if len(result) != 1 {
t.Fatalf("expected 1 model, got %d", len(result))
@@ -23,8 +23,8 @@ func TestExpandMultiKeyModels_SingleKey(t *testing.T) {
t.Errorf("expected model_name 'gpt-4', got %q", result[0].ModelName)
}
- if result[0].APIKey != "single-key" {
- t.Errorf("expected api_key 'single-key', got %q", result[0].APIKey)
+ if result[0].APIKey() != "single-key" {
+ t.Errorf("expected api_key 'single-key', got %q", result[0].APIKey())
}
if len(result[0].Fallbacks) != 0 {
@@ -33,16 +33,16 @@ func TestExpandMultiKeyModels_SingleKey(t *testing.T) {
}
func TestExpandMultiKeyModels_APIKeysOnly(t *testing.T) {
- models := []ModelConfig{
+ models := []*ModelConfig{
{
ModelName: "glm-4.7",
Model: "zhipu/glm-4.7",
APIBase: "https://api.example.com",
- APIKeys: []string{"key1", "key2", "key3"},
+ apiKeys: []string{"key1", "key2", "key3"},
},
}
- result := ExpandMultiKeyModels(models)
+ result := expandMultiKeyModels(models)
// Should expand to 3 models
if len(result) != 3 {
@@ -54,8 +54,8 @@ func TestExpandMultiKeyModels_APIKeysOnly(t *testing.T) {
if primary.ModelName != "glm-4.7" {
t.Errorf("expected primary model_name 'glm-4.7', got %q", primary.ModelName)
}
- if primary.APIKey != "key1" {
- t.Errorf("expected primary api_key 'key1', got %q", primary.APIKey)
+ if primary.APIKey() != "key1" {
+ t.Errorf("expected primary api_key 'key1', got %q", primary.APIKey())
}
if len(primary.Fallbacks) != 2 {
t.Errorf("expected 2 fallbacks, got %d", len(primary.Fallbacks))
@@ -72,8 +72,8 @@ func TestExpandMultiKeyModels_APIKeysOnly(t *testing.T) {
if second.ModelName != "glm-4.7__key_1" {
t.Errorf("expected second model_name 'glm-4.7__key_1', got %q", second.ModelName)
}
- if second.APIKey != "key2" {
- t.Errorf("expected second api_key 'key2', got %q", second.APIKey)
+ if second.APIKey() != "key2" {
+ t.Errorf("expected second api_key 'key2', got %q", second.APIKey())
}
// Third entry should be key3
@@ -81,22 +81,21 @@ func TestExpandMultiKeyModels_APIKeysOnly(t *testing.T) {
if third.ModelName != "glm-4.7__key_2" {
t.Errorf("expected third model_name 'glm-4.7__key_2', got %q", third.ModelName)
}
- if third.APIKey != "key3" {
- t.Errorf("expected third api_key 'key3', got %q", third.APIKey)
+ if third.APIKey() != "key3" {
+ t.Errorf("expected third api_key 'key3', got %q", third.APIKey())
}
}
func TestExpandMultiKeyModels_APIKeyAndAPIKeys(t *testing.T) {
- models := []ModelConfig{
+ models := []*ModelConfig{
{
ModelName: "gpt-4",
Model: "openai/gpt-4o",
- APIKey: "key0",
- APIKeys: []string{"key1", "key2"},
+ apiKeys: []string{"key0", "key1", "key2"},
},
}
- result := ExpandMultiKeyModels(models)
+ result := expandMultiKeyModels(models)
// Should expand to 3 models (key0 from APIKey + key1, key2 from APIKeys)
if len(result) != 3 {
@@ -105,8 +104,8 @@ func TestExpandMultiKeyModels_APIKeyAndAPIKeys(t *testing.T) {
// Primary should use key0
primary := result[2]
- if primary.APIKey != "key0" {
- t.Errorf("expected primary api_key 'key0', got %q", primary.APIKey)
+ if primary.APIKey() != "key0" {
+ t.Errorf("expected primary api_key 'key0', got %q", primary.APIKey())
}
if len(primary.Fallbacks) != 2 {
t.Errorf("expected 2 fallbacks, got %d", len(primary.Fallbacks))
@@ -114,16 +113,15 @@ func TestExpandMultiKeyModels_APIKeyAndAPIKeys(t *testing.T) {
}
func TestExpandMultiKeyModels_WithExistingFallbacks(t *testing.T) {
- models := []ModelConfig{
- {
- ModelName: "gpt-4",
- Model: "openai/gpt-4o",
- APIKeys: []string{"key1", "key2"},
- Fallbacks: []string{"claude-3"},
- },
+ modelCfg := &ModelConfig{
+ ModelName: "gpt-4",
+ Model: "openai/gpt-4o",
}
+ modelCfg.apiKeys = []string{"key0", "key1"} // Use internal field for multi-key testing
+ modelCfg.Fallbacks = []string{"claude-3"}
+ models := []*ModelConfig{modelCfg}
- result := ExpandMultiKeyModels(models)
+ result := expandMultiKeyModels(models)
primary := result[1]
// With 2 keys, we get 1 key fallback + 1 existing fallback = 2 total
@@ -141,16 +139,15 @@ func TestExpandMultiKeyModels_WithExistingFallbacks(t *testing.T) {
}
func TestExpandMultiKeyModels_EmptyAPIKeys(t *testing.T) {
- models := []ModelConfig{
+ models := []*ModelConfig{
{
ModelName: "gpt-4",
Model: "openai/gpt-4o",
- APIKey: "",
- APIKeys: []string{},
+ apiKeys: []string{},
},
}
- result := ExpandMultiKeyModels(models)
+ result := expandMultiKeyModels(models)
// Should keep as-is with no changes
if len(result) != 1 {
@@ -163,25 +160,25 @@ func TestExpandMultiKeyModels_EmptyAPIKeys(t *testing.T) {
}
func TestExpandMultiKeyModels_Deduplication(t *testing.T) {
- models := []ModelConfig{
+ models := []*ModelConfig{
{
ModelName: "gpt-4",
Model: "openai/gpt-4o",
- APIKey: "key1",
- APIKeys: []string{"key1", "key2", "key1"}, // Duplicate key1
+ apiKeys: []string{"key1", "key2", "key1"}, // Duplicate key1
},
}
- result := ExpandMultiKeyModels(models)
+ result := expandMultiKeyModels(models)
+ t.Logf("result: %#v", result)
// Should only create 2 models (deduplicated keys)
if len(result) != 2 {
t.Fatalf("expected 2 models (deduplicated), got %d", len(result))
}
primary := result[1]
- if primary.APIKey != "key1" {
- t.Errorf("expected primary api_key 'key1', got %q", primary.APIKey)
+ if primary.APIKey() != "key1" {
+ t.Errorf("expected primary api_key 'key1', got %q", primary.APIKey())
}
if len(primary.Fallbacks) != 1 {
t.Errorf("expected 1 fallback, got %d", len(primary.Fallbacks))
@@ -189,21 +186,20 @@ func TestExpandMultiKeyModels_Deduplication(t *testing.T) {
}
func TestExpandMultiKeyModels_PreservesOtherFields(t *testing.T) {
- models := []ModelConfig{
- {
- ModelName: "gpt-4",
- Model: "openai/gpt-4o",
- APIBase: "https://api.example.com",
- APIKeys: []string{"key1", "key2"},
- Proxy: "http://proxy:8080",
- RPM: 60,
- MaxTokensField: "max_completion_tokens",
- RequestTimeout: 30,
- ThinkingLevel: "high",
- },
+ modelCfg := &ModelConfig{
+ ModelName: "gpt-4",
+ Model: "openai/gpt-4o",
+ APIBase: "https://api.example.com",
+ Proxy: "http://proxy:8080",
+ RPM: 60,
+ MaxTokensField: "max_completion_tokens",
+ RequestTimeout: 30,
+ ThinkingLevel: "high",
}
+ modelCfg.apiKeys = []string{"key0", "key1"} // Use internal field for multi-key testing
+ models := []*ModelConfig{modelCfg}
- result := ExpandMultiKeyModels(models)
+ result := expandMultiKeyModels(models)
// Check primary entry preserves all fields
primary := result[1]
@@ -250,13 +246,13 @@ func TestMergeAPIKeys(t *testing.T) {
expected: nil,
},
{
- name: "only apiKey",
+ name: "only ApiKey",
apiKey: "key1",
apiKeys: nil,
expected: []string{"key1"},
},
{
- name: "only apiKeys",
+ name: "only ApiKeys",
apiKey: "",
apiKeys: []string{"key1", "key2"},
expected: []string{"key1", "key2"},
diff --git a/pkg/config/security.go b/pkg/config/security.go
new file mode 100644
index 000000000..fe2111280
--- /dev/null
+++ b/pkg/config/security.go
@@ -0,0 +1,220 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+ "bytes"
+ "fmt"
+ "os"
+ "path/filepath"
+
+ "github.com/caarlos0/env/v11"
+ "github.com/tencent-connect/botgo/log"
+ "gopkg.in/yaml.v3"
+
+ "github.com/sipeed/picoclaw/pkg/fileutil"
+)
+
+const (
+ SecurityConfigFile = ".security.yml"
+)
+
+// SecurityConfig stores all sensitive data (API keys, tokens, secrets, passwords)
+// This data is loaded from security.yml and kept separate from the main config
+type SecurityConfig struct {
+ // Model API keys. Map key is model_name, can include suffix like "abc:0", "abc:1"
+ // for load balancing with same model_name. The suffix ":N" is used to distinguish
+ // multiple configs that share the same base model_name.
+ ModelList map[string]ModelSecurityEntry `yaml:"model_list,omitempty"`
+
+ // Channel tokens/secrets
+ Channels ChannelsSecurity `yaml:"channels,omitempty"`
+
+ Web WebToolsSecurity `yaml:"web,omitempty"`
+ Skills SkillsSecurity `yaml:"skills,omitempty"`
+}
+
+// ModelSecurityEntry stores security data for a model
+type ModelSecurityEntry struct {
+ APIKeys []string `yaml:"api_keys,omitempty"` // API authentication keys (multiple keys for failover)
+}
+
+// ChannelsSecurity stores channel-related security data
+type ChannelsSecurity struct {
+ Telegram *TelegramSecurity `yaml:"telegram,omitempty"`
+ Feishu *FeishuSecurity `yaml:"feishu,omitempty"`
+ Discord *DiscordSecurity `yaml:"discord,omitempty"`
+ Weixin *WeixinSecurity `yaml:"weixin,omitempty"`
+ QQ *QQSecurity `yaml:"qq,omitempty"`
+ DingTalk *DingTalkSecurity `yaml:"dingtalk,omitempty"`
+ Slack *SlackSecurity `yaml:"slack,omitempty"`
+ Matrix *MatrixSecurity `yaml:"matrix,omitempty"`
+ LINE *LINESecurity `yaml:"line,omitempty"`
+ OneBot *OneBotSecurity `yaml:"onebot,omitempty"`
+ WeCom *WeComSecurity `yaml:"wecom,omitempty"`
+ WeComApp *WeComAppSecurity `yaml:"wecom_app,omitempty"`
+ WeComAIBot *WeComAIBotSecurity `yaml:"wecom_aibot,omitempty"`
+ Pico *PicoSecurity `yaml:"pico,omitempty"`
+ IRC *IRCSecurity `yaml:"irc,omitempty"`
+}
+
+type TelegramSecurity struct {
+ Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
+}
+
+type FeishuSecurity struct {
+ AppSecret string `yaml:"app_secret,omitempty" env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
+ EncryptKey string `yaml:"encrypt_key,omitempty" env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
+ VerificationToken string `yaml:"verification_token,omitempty" env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
+}
+
+type DiscordSecurity struct {
+ Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
+}
+
+type WeixinSecurity struct {
+ Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_WEIXIN_TOKEN"`
+}
+
+type QQSecurity struct {
+ AppSecret string `yaml:"app_secret,omitempty" env:"PICOCLAW_CHANNELS_QQ_APP_SECRET"`
+}
+
+type DingTalkSecurity struct {
+ ClientSecret string `yaml:"client_secret,omitempty" env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_SECRET"`
+}
+
+type SlackSecurity struct {
+ BotToken string `yaml:"bot_token,omitempty" env:"PICOCLAW_CHANNELS_SLACK_BOT_TOKEN"`
+ AppToken string `yaml:"app_token,omitempty" env:"PICOCLAW_CHANNELS_SLACK_APP_TOKEN"`
+}
+
+type MatrixSecurity struct {
+ AccessToken string `yaml:"access_token,omitempty" env:"PICOCLAW_CHANNELS_MATRIX_ACCESS_TOKEN"`
+}
+
+type LINESecurity struct {
+ ChannelSecret string `yaml:"channel_secret,omitempty" env:"PICOCLAW_CHANNELS_LINE_CHANNEL_SECRET"`
+ ChannelAccessToken string `yaml:"channel_access_token,omitempty" env:"PICOCLAW_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN"`
+}
+
+type OneBotSecurity struct {
+ AccessToken string `yaml:"access_token,omitempty" env:"PICOCLAW_CHANNELS_ONEBOT_ACCESS_TOKEN"`
+}
+
+type WeComSecurity struct {
+ Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_WECOM_TOKEN"`
+ EncodingAESKey string `yaml:"encoding_aes_key,omitempty" env:"PICOCLAW_CHANNELS_WECOM_ENCODING_AES_KEY"`
+}
+
+type WeComAppSecurity struct {
+ CorpSecret string `yaml:"corp_secret,omitempty" env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_SECRET"`
+ Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_WECOM_APP_TOKEN"`
+ EncodingAESKey string `yaml:"encoding_aes_key,omitempty" env:"PICOCLAW_CHANNELS_WECOM_APP_ENCODING_AES_KEY"`
+}
+
+type WeComAIBotSecurity struct {
+ Secret string `yaml:"secret,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_SECRET"`
+ Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_TOKEN"`
+ EncodingAESKey string `yaml:"encoding_aes_key,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENCODING_AES_KEY"`
+}
+
+type PicoSecurity struct {
+ Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_PICO_TOKEN"`
+}
+
+type IRCSecurity struct {
+ Password string `yaml:"password,omitempty" env:"PICOCLAW_CHANNELS_IRC_PASSWORD"`
+ NickServPassword string `yaml:"nickserv_password,omitempty" env:"PICOCLAW_CHANNELS_IRC_NICKSERV_PASSWORD"`
+ SASLPassword string `yaml:"sasl_password,omitempty" env:"PICOCLAW_CHANNELS_IRC_SASL_PASSWORD"`
+}
+
+type WebToolsSecurity struct {
+ Brave *BraveSecurity `yaml:"brave,omitempty"`
+ Tavily *TavilySecurity `yaml:"tavily,omitempty"`
+ Perplexity *PerplexitySecurity `yaml:"perplexity,omitempty"`
+ GLMSearch *GLMSearchSecurity `yaml:"glm_search,omitempty"`
+ BaiduSearch *BaiduSearchSecurity `yaml:"baidu_search,omitempty"`
+}
+
+type BraveSecurity struct {
+ APIKeys []string `yaml:"api_keys,omitempty"`
+}
+
+type TavilySecurity struct {
+ APIKeys []string `yaml:"api_keys,omitempty"`
+}
+
+type PerplexitySecurity struct {
+ APIKeys []string `yaml:"api_keys,omitempty"`
+}
+
+type GLMSearchSecurity struct {
+ APIKey string `yaml:"api_key,omitempty"`
+}
+
+type BaiduSearchSecurity struct {
+ APIKey string `yaml:"api_key,omitempty" env:"PICOCLAW_TOOLS_WEB_BAIDU_API_KEY"`
+}
+
+type SkillsSecurity struct {
+ Github *GithubSecurity `yaml:"github,omitempty"`
+ ClawHub *ClawHubSecurity `yaml:"clawhub,omitempty"`
+}
+
+type GithubSecurity struct {
+ Token string `yaml:"token,omitempty"`
+}
+
+type ClawHubSecurity struct {
+ AuthToken string `yaml:"auth_token,omitempty"`
+}
+
+// securityPath returns the path to security.yml relative to the config file
+func securityPath(configPath string) string {
+ configDir := filepath.Dir(configPath)
+ return filepath.Join(configDir, SecurityConfigFile)
+}
+
+// loadSecurityConfig loads the security configuration from security.yml
+// Returns an empty SecurityConfig if the file doesn't exist
+func loadSecurityConfig(securityPath string) (*SecurityConfig, error) {
+ data, err := os.ReadFile(securityPath)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return &SecurityConfig{}, nil
+ }
+ return nil, fmt.Errorf("failed to read security config: %w", err)
+ }
+
+ var sec SecurityConfig
+ if err := yaml.Unmarshal(data, &sec); err != nil {
+ return nil, fmt.Errorf("failed to parse security config: %w", err)
+ }
+
+ // No need to validate model_name format here - both formats are supported:
+ // - "model-name:0" (with index for multiple entries)
+ // - "model-name" (without index for single entry or default to index 0)
+
+ if err := env.Parse(&sec); err != nil {
+ log.Errorf("failed to parse environment variables: %v", err)
+ return nil, err
+ }
+
+ return &sec, nil
+}
+
+// saveSecurityConfig saves the security configuration to security.yml
+func saveSecurityConfig(securityPath string, sec *SecurityConfig) error {
+ var buf bytes.Buffer
+ enc := yaml.NewEncoder(&buf)
+ enc.SetIndent(2)
+ err := enc.Encode(sec)
+ if err != nil {
+ return fmt.Errorf("failed to marshal security config: %w", err)
+ }
+ return fileutil.WriteFileAtomic(securityPath, buf.Bytes(), 0o600)
+}
diff --git a/pkg/config/security_integration_test.go b/pkg/config/security_integration_test.go
new file mode 100644
index 000000000..c1e1a2340
--- /dev/null
+++ b/pkg/config/security_integration_test.go
@@ -0,0 +1,472 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// Test JSON unmarshal of private fields
+func TestJSONUnmarshalPrivateFields(t *testing.T) {
+ //nolint: govet
+ type testStruct struct {
+ PublicField string `json:"public"`
+ privateField string `json:"private"`
+ }
+
+ data := `{"public": "pub", "private": "priv"}`
+ var s testStruct
+ if err := json.Unmarshal([]byte(data), &s); err != nil {
+ t.Fatalf("JSON unmarshal failed: %v", err)
+ }
+
+ t.Logf("PublicField: %s", s.PublicField)
+ t.Logf("privateField: %s", s.privateField)
+
+ if s.PublicField != "pub" {
+ t.Errorf("PublicField = %q, want 'pub'", s.PublicField)
+ }
+ // This should fail because privateField is unexported
+ if s.privateField != "priv" {
+ t.Logf("privateField = %q, want 'priv' - THIS IS EXPECTED TO FAIL", s.privateField)
+ }
+}
+
+func TestSecurityConfigIntegration(t *testing.T) {
+ t.Run("Full workflow with security references", func(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ // Create config.json with references
+ configPath := filepath.Join(tmpDir, "config.json")
+ configContent := `{
+ "version": 1,
+ "model_list": [
+ {
+ "model_name": "test-model",
+ "model": "openai/test-model",
+ "api_base": "https://api.openai.com/v1",
+ "api_key": "ref:model_list.test-model.api_key"
+ }
+ ],
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "token": "ref:channels.telegram.token"
+ }
+ },
+ "tools": {
+ "web": {
+ "brave": {
+ "enabled": true,
+ "api_key": "ref:web.brave.api_key"
+ }
+ },
+ "skills": {
+ "github": {
+ "token": "ref:skills.github.token"
+ }
+ }
+ }
+}`
+ err := os.WriteFile(configPath, []byte(configContent), 0o644)
+ require.NoError(t, err)
+
+ // Create .security.yml with actual values
+ securityPath := filepath.Join(tmpDir, SecurityConfigFile)
+ securityContent := `model_list:
+ test-model:
+ api_keys:
+ - "sk-test-api-key-12345"
+
+channels:
+ telegram:
+ token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
+
+web:
+ brave:
+ api_keys:
+ - "BSAbrave-api-key-67890"
+
+skills:
+ github:
+ token: "ghp_github-token-abc123"`
+ err = os.WriteFile(securityPath, []byte(securityContent), 0o600)
+ require.NoError(t, err)
+
+ // Load config and verify references are resolved
+ cfg, err := LoadConfig(configPath)
+ require.NoError(t, err)
+ require.NotNil(t, cfg)
+
+ // Verify model API key is resolved
+ assert.Equal(t, 1, len(cfg.ModelList))
+ assert.Equal(t, "test-model", cfg.ModelList[0].ModelName)
+ assert.Equal(t, "sk-test-api-key-12345", cfg.ModelList[0].apiKeys[0])
+
+ // Verify channel token is resolved
+ assert.Equal(t, "123456789:ABCdefGHIjklMNOpqrsTUVwxyz", cfg.Channels.Telegram.token)
+
+ // Verify web tool API key is resolved
+ assert.Equal(t, "BSAbrave-api-key-67890", cfg.Tools.Web.Brave.APIKey())
+
+ // Verify skills token is resolved
+ assert.Equal(t, "ghp_github-token-abc123", cfg.Tools.Skills.Github.token)
+ })
+}
+
+func TestSecurityConfigWithAPIKeysArray(t *testing.T) {
+ t.Run("Multiple API keys via security", func(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ // Create config with APIKeys array
+ configPath := filepath.Join(tmpDir, "config.json")
+ configContent := `{
+ "version": 1,
+ "model_list": [
+ {
+ "model_name": "multi-key-model",
+ "model": "openai/multi-key-model"
+ }
+ ]
+}`
+ err := os.WriteFile(configPath, []byte(configContent), 0o644)
+ require.NoError(t, err)
+
+ // Create .security.yml
+ securityPath := filepath.Join(tmpDir, SecurityConfigFile)
+ securityContent := `model_list:
+ multi-key-model:0:
+ api_key: "sk-key-1"
+ api_keys:
+ - "sk-key-1"
+ - "sk-key-2"
+ - "sk-key-3"
+`
+ err = os.WriteFile(securityPath, []byte(securityContent), 0o600)
+ require.NoError(t, err)
+
+ // Load config
+ cfg, err := LoadConfig(configPath)
+ require.NoError(t, err)
+
+ t.Logf("Config: %+v", cfg.ModelList)
+ for _, m := range cfg.ModelList {
+ t.Logf("Model: %+v", m)
+ }
+ // Verify multi-key expansion works
+ assert.Equal(t, 3, len(cfg.ModelList))
+ assert.Equal(t, "multi-key-model", cfg.ModelList[2].ModelName)
+ })
+}
+
+func TestAllSecurityKeysAccessible(t *testing.T) {
+ t.Run("All security keys accessible via Key() methods including file://", func(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ // Create test files for file:// references
+ modelAPIKeyFile := filepath.Join(tmpDir, "model_api_key.txt")
+ err := os.WriteFile(modelAPIKeyFile, []byte("sk-model-from-file-12345"), 0o600)
+ require.NoError(t, err)
+
+ braveAPIKeyFile := filepath.Join(tmpDir, "brave_api_key.txt")
+ err = os.WriteFile(braveAPIKeyFile, []byte("BSA-brave-from-file-67890"), 0o600)
+ require.NoError(t, err)
+
+ tavilyAPIKeyFile := filepath.Join(tmpDir, "tavily_api_key.txt")
+ err = os.WriteFile(tavilyAPIKeyFile, []byte("tvly-tavily-from-file-11111"), 0o600)
+ require.NoError(t, err)
+
+ perplexityAPIKeyFile := filepath.Join(tmpDir, "perplexity_api_key.txt")
+ err = os.WriteFile(perplexityAPIKeyFile, []byte("pplx-perplexity-from-file-22222"), 0o600)
+ require.NoError(t, err)
+
+ githubTokenFile := filepath.Join(tmpDir, "github_token.txt")
+ err = os.WriteFile(githubTokenFile, []byte("ghp-github-from-file-abc123"), 0o600)
+ require.NoError(t, err)
+
+ clawhubAuthTokenFile := filepath.Join(tmpDir, "clawhub_auth_token.txt")
+ err = os.WriteFile(clawhubAuthTokenFile, []byte("clawhub-auth-token-from-file"), 0o600)
+ require.NoError(t, err)
+
+ // Create config.json without sensitive values (they'll be in .security.yml)
+ configPath := filepath.Join(tmpDir, "config.json")
+ configContent := `{
+ "version": 1,
+ "model_list": [
+ {
+ "model_name": "test-model-1",
+ "model": "openai/test-model-1"
+ }
+ ],
+ "channels": {
+ "telegram": {
+ "enabled": true
+ },
+ "feishu": {
+ "enabled": true,
+ "app_id": "test_app_id"
+ },
+ "discord": {
+ "enabled": true
+ },
+ "dingtalk": {
+ "enabled": true,
+ "client_id": "test_client_id"
+ },
+ "slack": {
+ "enabled": true
+ },
+ "matrix": {
+ "enabled": true,
+ "homeserver": "https://matrix.org",
+ "user_id": "@test:matrix.org"
+ },
+ "line": {
+ "enabled": true,
+ "webhook_host": "localhost",
+ "webhook_port": 8080,
+ "webhook_path": "/webhook"
+ },
+ "onebot": {
+ "enabled": true,
+ "ws_url": "ws://localhost:8080"
+ },
+ "wecom": {
+ "enabled": true,
+ "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook"
+ },
+ "wecom_app": {
+ "enabled": true,
+ "corp_id": "test_corp_id",
+ "agent_id": 123456
+ },
+ "wecom_aibot": {
+ "enabled": true
+ },
+ "pico": {
+ "enabled": true
+ },
+ "irc": {
+ "enabled": true,
+ "server": "irc.example.com",
+ "nick": "testbot"
+ },
+ "qq": {
+ "enabled": true,
+ "app_id": "test_qq_app_id"
+ }
+ },
+ "tools": {
+ "web": {
+ "brave": {
+ "enabled": true
+ },
+ "tavily": {
+ "enabled": true
+ },
+ "perplexity": {
+ "enabled": true
+ },
+ "glm_search": {
+ "enabled": true
+ }
+ },
+ "skills": {
+ "github": {}
+ }
+ }
+}`
+ err = os.WriteFile(configPath, []byte(configContent), 0o644)
+ require.NoError(t, err)
+
+ // Create .security.yml with file:// references and plaintext values
+ securityPath := filepath.Join(tmpDir, SecurityConfigFile)
+ securityContent := `model_list:
+ test-model-1:
+ api_keys:
+ - "file://model_api_key.txt"
+
+channels:
+ telegram:
+ token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
+ feishu:
+ app_secret: "feishu_test_app_secret"
+ encrypt_key: "feishu_test_encrypt_key"
+ verification_token: "feishu_test_verification_token"
+ discord:
+ token: "discord_test_bot_token_xyz"
+ dingtalk:
+ client_secret: "dingtalk_test_client_secret"
+ slack:
+ bot_token: "xoxb-slack-bot-token-123"
+ app_token: "xapp-slack-app-token-456"
+ matrix:
+ access_token: "matrix_test_access_token"
+ line:
+ channel_secret: "line_test_channel_secret"
+ channel_access_token: "line_test_channel_access_token"
+ onebot:
+ access_token: "onebot_test_access_token"
+ wecom:
+ token: "wecom_test_webhook_token"
+ encoding_aes_key: "wecom_test_aes_key"
+ wecom_app:
+ corp_secret: "wecom_app_test_corp_secret"
+ token: "wecom_app_test_token"
+ encoding_aes_key: "wecom_app_test_aes_key"
+ wecom_aibot:
+ token: "wecom_aibot_test_token"
+ encoding_aes_key: "wecom_aibot_test_aes_key"
+ pico:
+ token: "pico_test_token"
+ irc:
+ password: "irc_test_password"
+ nickserv_password: "irc_test_nickserv_password"
+ sasl_password: "irc_test_sasl_password"
+ qq:
+ app_secret: "qq_test_app_secret"
+
+web:
+ brave:
+ api_keys:
+ - "file://brave_api_key.txt"
+ tavily:
+ api_keys:
+ - "file://tavily_api_key.txt"
+ perplexity:
+ api_keys:
+ - "file://perplexity_api_key.txt"
+ glm_search:
+ api_key: "glm-test-glm-search-key"
+
+skills:
+ github:
+ token: "file://github_token.txt"
+ clawhub:
+ auth_token: "file://clawhub_auth_token.txt"
+`
+ err = os.WriteFile(securityPath, []byte(securityContent), 0o600)
+ require.NoError(t, err)
+
+ // Load config and verify all security keys are accessible
+ cfg, err := LoadConfig(configPath)
+ require.NoError(t, err)
+ require.NotNil(t, cfg)
+
+ // Verify Model API keys
+ assert.Equal(t, 1, len(cfg.ModelList))
+ assert.Equal(t, "test-model-1", cfg.ModelList[0].ModelName)
+ // file:// reference should be resolved
+ assert.Equal(t, "sk-model-from-file-12345", cfg.ModelList[0].APIKey())
+ t.Logf("Model APIKey(): %s", cfg.ModelList[0].APIKey())
+
+ // Verify Channel tokens via Key() methods
+ // Telegram
+ assert.Equal(t, "123456789:ABCdefGHIjklMNOpqrsTUVwxyz", cfg.Channels.Telegram.Token())
+ t.Logf("Telegram Token(): %s", cfg.Channels.Telegram.Token())
+
+ // Feishu
+ assert.Equal(t, "feishu_test_app_secret", cfg.Channels.Feishu.AppSecret())
+ assert.Equal(t, "feishu_test_encrypt_key", cfg.Channels.Feishu.EncryptKey())
+ assert.Equal(t, "feishu_test_verification_token", cfg.Channels.Feishu.VerificationToken())
+ t.Logf("Feishu AppSecret(): %s", cfg.Channels.Feishu.AppSecret())
+ t.Logf("Feishu EncryptKey(): %s", cfg.Channels.Feishu.EncryptKey())
+ t.Logf("Feishu VerificationToken(): %s", cfg.Channels.Feishu.VerificationToken())
+
+ // Discord
+ assert.Equal(t, "discord_test_bot_token_xyz", cfg.Channels.Discord.Token())
+ t.Logf("Discord Token(): %s", cfg.Channels.Discord.Token())
+
+ // DingTalk
+ assert.Equal(t, "dingtalk_test_client_secret", cfg.Channels.DingTalk.ClientSecret())
+ t.Logf("DingTalk ClientSecret(): %s", cfg.Channels.DingTalk.ClientSecret())
+
+ // Slack
+ assert.Equal(t, "xoxb-slack-bot-token-123", cfg.Channels.Slack.BotToken())
+ assert.Equal(t, "xapp-slack-app-token-456", cfg.Channels.Slack.AppToken())
+ t.Logf("Slack BotToken(): %s", cfg.Channels.Slack.BotToken())
+ t.Logf("Slack AppToken(): %s", cfg.Channels.Slack.AppToken())
+
+ // Matrix
+ assert.Equal(t, "matrix_test_access_token", cfg.Channels.Matrix.AccessToken())
+ t.Logf("Matrix AccessToken(): %s", cfg.Channels.Matrix.AccessToken())
+
+ // LINE
+ assert.Equal(t, "line_test_channel_secret", cfg.Channels.LINE.ChannelSecret())
+ assert.Equal(t, "line_test_channel_access_token", cfg.Channels.LINE.ChannelAccessToken())
+ t.Logf("LINE ChannelSecret(): %s", cfg.Channels.LINE.ChannelSecret())
+ t.Logf("LINE ChannelAccessToken(): %s", cfg.Channels.LINE.ChannelAccessToken())
+
+ // OneBot
+ assert.Equal(t, "onebot_test_access_token", cfg.Channels.OneBot.AccessToken())
+ t.Logf("OneBot AccessToken(): %s", cfg.Channels.OneBot.AccessToken())
+
+ // WeCom
+ assert.Equal(t, "wecom_test_webhook_token", cfg.Channels.WeCom.Token())
+ assert.Equal(t, "wecom_test_aes_key", cfg.Channels.WeCom.EncodingAESKey())
+ t.Logf("WeCom Token(): %s", cfg.Channels.WeCom.Token())
+ t.Logf("WeCom EncodingAESKey(): %s", cfg.Channels.WeCom.EncodingAESKey())
+
+ // WeCom App
+ assert.Equal(t, "wecom_app_test_corp_secret", cfg.Channels.WeComApp.CorpSecret())
+ assert.Equal(t, "wecom_app_test_token", cfg.Channels.WeComApp.Token())
+ assert.Equal(t, "wecom_app_test_aes_key", cfg.Channels.WeComApp.EncodingAESKey())
+ t.Logf("WeComApp CorpSecret(): %s", cfg.Channels.WeComApp.CorpSecret())
+ t.Logf("WeComApp Token(): %s", cfg.Channels.WeComApp.Token())
+ t.Logf("WeComApp EncodingAESKey(): %s", cfg.Channels.WeComApp.EncodingAESKey())
+
+ // WeCom AI Bot
+ assert.Equal(t, "wecom_aibot_test_token", cfg.Channels.WeComAIBot.Token())
+ assert.Equal(t, "wecom_aibot_test_aes_key", cfg.Channels.WeComAIBot.EncodingAESKey())
+ t.Logf("WeComAIBot Token(): %s", cfg.Channels.WeComAIBot.Token())
+ t.Logf("WeComAIBot EncodingAESKey(): %s", cfg.Channels.WeComAIBot.EncodingAESKey())
+
+ // Pico
+ assert.Equal(t, "pico_test_token", cfg.Channels.Pico.Token())
+ t.Logf("Pico Token(): %s", cfg.Channels.Pico.Token())
+
+ // IRC
+ assert.Equal(t, "irc_test_password", cfg.Channels.IRC.Password())
+ assert.Equal(t, "irc_test_nickserv_password", cfg.Channels.IRC.NickServPassword())
+ assert.Equal(t, "irc_test_sasl_password", cfg.Channels.IRC.SASLPassword())
+ t.Logf("IRC Password(): %s", cfg.Channels.IRC.Password())
+ t.Logf("IRC NickServPassword(): %s", cfg.Channels.IRC.NickServPassword())
+ t.Logf("IRC SASLPassword(): %s", cfg.Channels.IRC.SASLPassword())
+
+ // QQ
+ assert.Equal(t, "qq_test_app_secret", cfg.Channels.QQ.AppSecret())
+ t.Logf("QQ AppSecret(): %s", cfg.Channels.QQ.AppSecret())
+
+ // Verify Web tool API keys
+ assert.Equal(t, "BSA-brave-from-file-67890", cfg.Tools.Web.Brave.APIKey())
+ t.Logf("Brave APIKey(): %s", cfg.Tools.Web.Brave.APIKey())
+
+ assert.Equal(t, "tvly-tavily-from-file-11111", cfg.Tools.Web.Tavily.APIKey())
+ t.Logf("Tavily APIKey(): %s", cfg.Tools.Web.Tavily.APIKey())
+
+ assert.Equal(t, "pplx-perplexity-from-file-22222", cfg.Tools.Web.Perplexity.APIKey())
+ t.Logf("Perplexity APIKey(): %s", cfg.Tools.Web.Perplexity.APIKey())
+
+ // GLM Search - Note: GLM uses SetAPIKey (lowercase) internally
+ t.Logf("GLMSearch APIKey(): %s", cfg.Tools.Web.GLMSearch.APIKey())
+ assert.Equal(t, "glm-test-glm-search-key", cfg.Tools.Web.GLMSearch.APIKey())
+
+ // Verify Skills tokens
+ assert.Equal(t, "ghp-github-from-file-abc123", cfg.Tools.Skills.Github.Token())
+ t.Logf("Github Token(): %s", cfg.Tools.Skills.Github.Token())
+
+ assert.Equal(t, "clawhub-auth-token-from-file", cfg.Tools.Skills.Registries.ClawHub.AuthToken())
+ t.Logf("ClawHub AuthToken(): %s", cfg.Tools.Skills.Registries.ClawHub.AuthToken())
+
+ t.Log("All security keys are successfully accessible via their respective Key() methods")
+ })
+}
diff --git a/pkg/config/security_test.go b/pkg/config/security_test.go
new file mode 100644
index 000000000..74e765f6b
--- /dev/null
+++ b/pkg/config/security_test.go
@@ -0,0 +1,90 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestSecurityConfig(t *testing.T) {
+ t.Run("LoadNonExistent", func(t *testing.T) {
+ sec, err := loadSecurityConfig("/nonexistent/.security.yml")
+ require.NoError(t, err)
+ assert.NotNil(t, sec)
+ assert.Empty(t, sec.ModelList)
+ })
+}
+
+func TestSecurityPath(t *testing.T) {
+ tests := []struct {
+ name string
+ configDir string
+ want string
+ }{
+ {
+ name: "standard path",
+ configDir: "/home/user/.picoclaw/config.json",
+ want: "/home/user/.picoclaw/.security.yml",
+ },
+ {
+ name: "nested path",
+ configDir: "/path/to/config/myconfig.json",
+ want: "/path/to/config/.security.yml",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := securityPath(tt.configDir)
+ assert.Equal(t, tt.want, got)
+ })
+ }
+}
+
+func TestSaveAndLoadSecurityConfig(t *testing.T) {
+ tmpDir := t.TempDir()
+ secPath := filepath.Join(tmpDir, SecurityConfigFile)
+
+ original := &SecurityConfig{
+ ModelList: map[string]ModelSecurityEntry{
+ "model1:0": {
+ APIKeys: []string{"key1", "key2"},
+ },
+ },
+ Channels: ChannelsSecurity{
+ Telegram: &TelegramSecurity{
+ Token: "telegram-token",
+ },
+ },
+ Web: WebToolsSecurity{
+ Brave: &BraveSecurity{
+ APIKeys: []string{"brave-api-key"},
+ },
+ },
+ }
+
+ // Save
+ err := saveSecurityConfig(secPath, original)
+ require.NoError(t, err)
+
+ // Verify file was created with correct permissions
+ info, err := os.Stat(secPath)
+ require.NoError(t, err)
+ assert.Equal(t, os.FileMode(0o600), info.Mode())
+
+ // Load
+ loaded, err := loadSecurityConfig(secPath)
+ require.NoError(t, err)
+
+ assert.Equal(t, original.ModelList, loaded.ModelList)
+ assert.Equal(t, original.Channels.Telegram.Token, loaded.Channels.Telegram.Token)
+ assert.EqualValues(t, original.Web.Brave.APIKeys, loaded.Web.Brave.APIKeys)
+}
diff --git a/pkg/env.go b/pkg/env.go
new file mode 100644
index 000000000..b9a77dab2
--- /dev/null
+++ b/pkg/env.go
@@ -0,0 +1,12 @@
+// all environment variables including default values put here
+
+package pkg
+
+const (
+ Logo = "🦞"
+ // AppName is the name of the app
+ AppName = "PicoClaw"
+
+ DefaultPicoClawHome = ".picoclaw"
+ WorkspaceName = "workspace"
+)
diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go
index 9a2706b3b..fc2465747 100644
--- a/pkg/gateway/gateway.go
+++ b/pkg/gateway/gateway.go
@@ -27,6 +27,7 @@ import (
_ "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/weixin"
_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp"
_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp_native"
"github.com/sipeed/picoclaw/pkg/config"
@@ -46,6 +47,10 @@ const (
serviceShutdownTimeout = 30 * time.Second
providerReloadTimeout = 30 * time.Second
gracefulShutdownTimeout = 15 * time.Second
+
+ logPath = "logs"
+ panicFile = "gateway_panic.log"
+ logFile = "gateway.log"
)
type services struct {
@@ -78,17 +83,31 @@ func (p *startupBlockedProvider) GetDefaultModel() string {
}
// Run starts the gateway runtime using the configuration loaded from configPath.
-func Run(debug bool, configPath string, allowEmptyStartup bool) error {
- if debug {
- logger.SetLevel(logger.DEBUG)
- fmt.Println("🔍 Debug mode enabled")
+func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error {
+ panicPath := filepath.Join(homePath, logPath, panicFile)
+ panicFunc, err := logger.InitPanic(panicPath)
+ if err != nil {
+ return fmt.Errorf("error initializing panic log: %w", err)
}
+ defer panicFunc()
+
+ if err = logger.EnableFileLogging(filepath.Join(homePath, logPath, logFile)); err != nil {
+ panic(fmt.Sprintf("error enabling file logging: %v", err))
+ }
+ defer logger.DisableFileLogging()
cfg, err := config.LoadConfig(configPath)
if err != nil {
return fmt.Errorf("error loading config: %w", err)
}
+ logger.SetLevelFromString(cfg.Gateway.LogLevel)
+
+ if debug {
+ logger.SetLevel(logger.DEBUG)
+ fmt.Println("🔍 Debug mode enabled")
+ }
+
provider, modelID, err := createStartupProvider(cfg, allowEmptyStartup)
if err != nil {
return fmt.Errorf("error creating provider: %w", err)
@@ -378,9 +397,6 @@ func handleConfigReload(
logger.Info("🔄 Config file changed, reloading...")
newModel := newCfg.Agents.Defaults.ModelName
- if newModel == "" {
- newModel = newCfg.Agents.Defaults.Model
- }
logger.Infof(" New model is '%s', recreating provider...", newModel)
diff --git a/pkg/heartbeat/service.go b/pkg/heartbeat/service.go
index 09c93fc6b..5dda78ea9 100644
--- a/pkg/heartbeat/service.go
+++ b/pkg/heartbeat/service.go
@@ -26,6 +26,7 @@ import (
const (
minIntervalMinutes = 5
defaultIntervalMinutes = 30
+ userTasksMarker = "Add your heartbeat tasks below this line:"
)
// HeartbeatHandler is the function type for handling heartbeat.
@@ -232,7 +233,7 @@ func (hs *HeartbeatService) buildPrompt() string {
}
content := string(data)
- if len(content) == 0 {
+ if !heartbeatHasUserTasks(content) {
return ""
}
@@ -284,6 +285,32 @@ Add your heartbeat tasks below this line:
}
}
+func heartbeatHasUserTasks(content string) bool {
+ trimmed := strings.TrimSpace(content)
+ if trimmed == "" {
+ return false
+ }
+
+ markerIdx := strings.Index(content, userTasksMarker)
+ if markerIdx < 0 {
+ return true
+ }
+
+ tasksSection := content[markerIdx+len(userTasksMarker):]
+ for _, line := range strings.Split(tasksSection, "\n") {
+ trimmedLine := strings.TrimSpace(line)
+ if trimmedLine == "" {
+ continue
+ }
+ if strings.HasPrefix(trimmedLine, "#") {
+ continue
+ }
+ return true
+ }
+
+ return false
+}
+
// sendResponse sends the heartbeat response to the last channel
func (hs *HeartbeatService) sendResponse(response string) {
hs.mu.RLock()
diff --git a/pkg/heartbeat/service_test.go b/pkg/heartbeat/service_test.go
index 3b7eeeefb..309b4378f 100644
--- a/pkg/heartbeat/service_test.go
+++ b/pkg/heartbeat/service_test.go
@@ -3,6 +3,7 @@ package heartbeat
import (
"os"
"path/filepath"
+ "strings"
"testing"
"time"
@@ -203,3 +204,47 @@ func TestHeartbeatFilePath(t *testing.T) {
t.Errorf("Expected HEARTBEAT.md at %s, but it doesn't exist", expectedPath)
}
}
+
+func TestBuildPrompt_DefaultTemplateStaysIdle(t *testing.T) {
+ tmpDir, err := os.MkdirTemp("", "heartbeat-test-*")
+ if err != nil {
+ t.Fatalf("Failed to create temp dir: %v", err)
+ }
+ defer os.RemoveAll(tmpDir)
+
+ hs := NewHeartbeatService(tmpDir, 30, true)
+ hs.createDefaultHeartbeatTemplate()
+
+ if prompt := hs.buildPrompt(); prompt != "" {
+ t.Fatalf("buildPrompt() = %q, want empty prompt for untouched default template", prompt)
+ }
+}
+
+func TestBuildPrompt_UserTasksAfterMarkerProducePrompt(t *testing.T) {
+ tmpDir, err := os.MkdirTemp("", "heartbeat-test-*")
+ if err != nil {
+ t.Fatalf("Failed to create temp dir: %v", err)
+ }
+ defer os.RemoveAll(tmpDir)
+
+ hs := NewHeartbeatService(tmpDir, 30, true)
+ hs.createDefaultHeartbeatTemplate()
+
+ path := filepath.Join(tmpDir, "HEARTBEAT.md")
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("Failed to read HEARTBEAT.md: %v", err)
+ }
+ updated := string(data) + "\n- Check unread Feishu messages\n"
+ if err := os.WriteFile(path, []byte(updated), 0o644); err != nil {
+ t.Fatalf("Failed to update HEARTBEAT.md: %v", err)
+ }
+
+ prompt := hs.buildPrompt()
+ if prompt == "" {
+ t.Fatal("buildPrompt() = empty, want non-empty prompt when user tasks are present")
+ }
+ if !strings.Contains(prompt, "Check unread Feishu messages") {
+ t.Fatalf("prompt = %q, want user task content", prompt)
+ }
+}
diff --git a/pkg/identity/identity.go b/pkg/identity/identity.go
index 372bbe38b..045725a8d 100644
--- a/pkg/identity/identity.go
+++ b/pkg/identity/identity.go
@@ -94,13 +94,18 @@ func MatchAllowed(sender bus.SenderInfo, allowed string) bool {
return false
}
-// isNumeric returns true if s consists entirely of digits.
+// isNumeric returns true if s consists entirely of digits, allowing for an optional leading minus sign
+// (required for Telegram group/channel IDs like -1001234567890).
func isNumeric(s string) bool {
if s == "" {
return false
}
- for _, r := range s {
- if r < '0' || r > '9' {
+ start := 0
+ if s[0] == '-' && len(s) > 1 {
+ start = 1
+ }
+ for i := start; i < len(s); i++ {
+ if s[i] < '0' || s[i] > '9' {
return false
}
}
diff --git a/pkg/identity/identity_test.go b/pkg/identity/identity_test.go
index a588f1484..c60402d19 100644
--- a/pkg/identity/identity_test.go
+++ b/pkg/identity/identity_test.go
@@ -97,6 +97,15 @@ func TestMatchAllowed(t *testing.T) {
allowed: "654321",
want: false,
},
+ {
+ name: "negative numeric ID matches PlatformID",
+ sender: bus.SenderInfo{
+ Platform: "telegram",
+ PlatformID: "-1001234567890",
+ },
+ allowed: "-1001234567890",
+ want: true,
+ },
// Username matching
{
name: "@username matches Username",
@@ -238,6 +247,9 @@ func TestIsNumeric(t *testing.T) {
{"abc", false},
{"12a34", false},
{"telegram", false},
+ {"-1001234567890", true},
+ {"-", false},
+ {"-12a34", false},
}
for _, tt := range tests {
diff --git a/pkg/logger/logger.go b/pkg/logger/logger.go
index c5a1f895a..eeb1436de 100644
--- a/pkg/logger/logger.go
+++ b/pkg/logger/logger.go
@@ -106,6 +106,36 @@ func GetLevel() LogLevel {
return currentLevel
}
+// ParseLevel converts a case-insensitive level name to a LogLevel.
+// Returns the level and true if valid, or (INFO, false) if unrecognized.
+func ParseLevel(s string) (LogLevel, bool) {
+ switch strings.ToLower(strings.TrimSpace(s)) {
+ case "debug":
+ return DEBUG, true
+ case "info":
+ return INFO, true
+ case "warn", "warning":
+ return WARN, true
+ case "error":
+ return ERROR, true
+ case "fatal":
+ return FATAL, true
+ default:
+ return INFO, false
+ }
+}
+
+// SetLevelFromString sets the log level from a string value.
+// If the string is empty or not a recognized level name, the current level is kept.
+func SetLevelFromString(s string) {
+ if s == "" {
+ return
+ }
+ if level, ok := ParseLevel(s); ok {
+ SetLevel(level)
+ }
+}
+
func EnableFileLogging(filePath string) error {
mu.Lock()
defer mu.Unlock()
@@ -226,6 +256,8 @@ func appendFields(event *zerolog.Event, fields map[string]any) {
for k, v := range fields {
// Type switch to avoid double JSON serialization of strings
switch val := v.(type) {
+ case error:
+ event.Str(k, val.Error())
case string:
event.Str(k, val)
case int:
diff --git a/pkg/logger/logger_test.go b/pkg/logger/logger_test.go
index 31b40484c..6ad3a8dd6 100644
--- a/pkg/logger/logger_test.go
+++ b/pkg/logger/logger_test.go
@@ -1,7 +1,12 @@
package logger
import (
+ "bytes"
+ "encoding/json"
+ "errors"
"testing"
+
+ "github.com/rs/zerolog"
)
func TestLogLevelFiltering(t *testing.T) {
@@ -252,3 +257,111 @@ func TestFormatFieldValue(t *testing.T) {
})
}
}
+
+func TestDefaultLevelIsInfo(t *testing.T) {
+ // The package-level default (before any SetLevel call) should be INFO.
+ // Because earlier tests may have changed it, we just verify the constant is wired correctly.
+ if logLevelNames[INFO] != "INFO" {
+ t.Errorf("INFO constant mapped to %q, want \"INFO\"", logLevelNames[INFO])
+ }
+}
+
+func TestParseLevelValid(t *testing.T) {
+ tests := []struct {
+ input string
+ want LogLevel
+ }{
+ {"debug", DEBUG},
+ {"DEBUG", DEBUG},
+ {"Debug", DEBUG},
+ {"info", INFO},
+ {"INFO", INFO},
+ {"warn", WARN},
+ {"WARN", WARN},
+ {"warning", WARN},
+ {"WARNING", WARN},
+ {"error", ERROR},
+ {"ERROR", ERROR},
+ {"fatal", FATAL},
+ {"FATAL", FATAL},
+ {" info ", INFO},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.input, func(t *testing.T) {
+ got, ok := ParseLevel(tt.input)
+ if !ok {
+ t.Fatalf("ParseLevel(%q) returned ok=false, want true", tt.input)
+ }
+ if got != tt.want {
+ t.Errorf("ParseLevel(%q) = %v, want %v", tt.input, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestParseLevelInvalid(t *testing.T) {
+ tests := []string{"", "garbage", "verbose", "trace", "critical"}
+
+ for _, input := range tests {
+ t.Run(input, func(t *testing.T) {
+ _, ok := ParseLevel(input)
+ if ok {
+ t.Errorf("ParseLevel(%q) returned ok=true, want false", input)
+ }
+ })
+ }
+}
+
+func TestSetLevelFromString(t *testing.T) {
+ initialLevel := GetLevel()
+ defer SetLevel(initialLevel)
+
+ // Valid string changes the level
+ SetLevel(INFO)
+ SetLevelFromString("error")
+ if got := GetLevel(); got != ERROR {
+ t.Errorf("after SetLevelFromString(\"error\"): GetLevel() = %v, want ERROR", got)
+ }
+
+ // Empty string is a no-op
+ SetLevelFromString("")
+ if got := GetLevel(); got != ERROR {
+ t.Errorf("after SetLevelFromString(\"\"): GetLevel() = %v, want ERROR (unchanged)", got)
+ }
+
+ // Invalid string is a no-op
+ SetLevelFromString("garbage")
+ if got := GetLevel(); got != ERROR {
+ t.Errorf("after SetLevelFromString(\"garbage\"): GetLevel() = %v, want ERROR (unchanged)", got)
+ }
+
+ // Case-insensitive
+ SetLevelFromString("FATAL")
+ if got := GetLevel(); got != FATAL {
+ t.Errorf("after SetLevelFromString(\"FATAL\"): GetLevel() = %v, want FATAL", got)
+ }
+}
+
+func TestAppendFields_ErrorUsesErrorString(t *testing.T) {
+ var buf bytes.Buffer
+ l := zerolog.New(&buf)
+
+ event := l.Info()
+ appendFields(event, map[string]any{"error": errors.New("transcription request failed")})
+ event.Msg("test")
+
+ lines := bytes.Split(bytes.TrimSpace(buf.Bytes()), []byte("\n"))
+ if len(lines) == 0 {
+ t.Fatal("expected log output, got none")
+ }
+
+ var got map[string]any
+ if err := json.Unmarshal(lines[0], &got); err != nil {
+ t.Fatalf("unmarshal log line: %v", err)
+ }
+
+ if got["error"] != "transcription request failed" {
+ t.Fatalf("error field = %#v, want %q", got["error"], "transcription request failed")
+ }
+}
diff --git a/pkg/logger/panic.go b/pkg/logger/panic.go
new file mode 100644
index 000000000..e53e4351a
--- /dev/null
+++ b/pkg/logger/panic.go
@@ -0,0 +1,36 @@
+package logger
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "runtime/debug"
+ "time"
+)
+
+func InitPanic(filePath string) (func(), error) {
+ if err := os.MkdirAll(filepath.Dir(filePath), 0o755); err != nil {
+ return nil, fmt.Errorf("failed to create log directory: %w", err)
+ }
+ writer := initPanicFile(filePath)
+ if writer == nil {
+ return nil, fmt.Errorf("failed to create log file: %s", filePath)
+ }
+ return func() {
+ defer writer.Close()
+ if err := recover(); err != nil {
+ now := time.Now().Format("2006-01-02 15:04:05")
+ stack := debug.Stack()
+ logMsg := "\n\n====================\n[" + now + "] PANIC OCCURRED: " + fmt.Sprintf(
+ "%v",
+ err,
+ ) + "\n" + string(
+ stack,
+ )
+
+ writer.Write([]byte(logMsg))
+
+ os.Exit(1)
+ }
+ }, nil
+}
diff --git a/pkg/logger/panic_unix.go b/pkg/logger/panic_unix.go
new file mode 100644
index 000000000..48f393b45
--- /dev/null
+++ b/pkg/logger/panic_unix.go
@@ -0,0 +1,22 @@
+//go:build !windows
+
+package logger
+
+import (
+ "fmt"
+ "io"
+ "os"
+
+ "golang.org/x/sys/unix"
+)
+
+func initPanicFile(panicFile string) io.WriteCloser {
+ file, err := os.OpenFile(panicFile, os.O_WRONLY|os.O_CREATE|os.O_APPEND|os.O_SYNC, 0o600)
+ if err != nil {
+ panic(fmt.Sprintf("error in open panic: %v", err))
+ }
+ if err = unix.Dup2(int(file.Fd()), int(os.Stderr.Fd())); err != nil {
+ panic(fmt.Sprintf("error in syscall.Dup2: %v", err))
+ }
+ return file
+}
diff --git a/pkg/logger/panic_win.go b/pkg/logger/panic_win.go
new file mode 100644
index 000000000..29d3f21d8
--- /dev/null
+++ b/pkg/logger/panic_win.go
@@ -0,0 +1,25 @@
+//go:build windows
+// +build windows
+
+package logger
+
+import (
+ "fmt"
+ "io"
+ "os"
+
+ "golang.org/x/sys/windows"
+)
+
+func initPanicFile(panicFile string) io.WriteCloser {
+ file, err := os.OpenFile(panicFile, os.O_WRONLY|os.O_CREATE|os.O_SYNC|os.O_APPEND, 0600)
+ if err != nil {
+ panic(fmt.Sprintf("error in open panic: %v", err))
+ }
+ err = windows.SetStdHandle(windows.STD_ERROR_HANDLE, windows.Handle(file.Fd()))
+ if err != nil {
+ panic(fmt.Sprintf("Failed to redirect stderr to file: %v", err))
+ }
+ os.Stderr = file
+ return file
+}
diff --git a/pkg/media/store.go b/pkg/media/store.go
index 30220986c..78cff8bb6 100644
--- a/pkg/media/store.go
+++ b/pkg/media/store.go
@@ -11,11 +11,25 @@ import (
"github.com/sipeed/picoclaw/pkg/logger"
)
+// CleanupPolicy controls how the MediaStore treats the underlying file when
+// a ref is released or expires.
+type CleanupPolicy string
+
+const (
+ // CleanupPolicyDeleteOnCleanup means the file is store-managed and may be
+ // deleted once the final ref for that path is gone.
+ CleanupPolicyDeleteOnCleanup CleanupPolicy = "delete_on_cleanup"
+ // CleanupPolicyForgetOnly means the store should only drop ref mappings and
+ // must never delete the underlying file.
+ CleanupPolicyForgetOnly CleanupPolicy = "forget_only"
+)
+
// MediaMeta holds metadata about a stored media file.
type MediaMeta struct {
- Filename string
- ContentType string
- Source string // "telegram", "discord", "tool:image-gen", etc.
+ Filename string
+ ContentType string
+ Source string // "telegram", "discord", "tool:image-gen", etc.
+ CleanupPolicy CleanupPolicy // defaults to CleanupPolicyDeleteOnCleanup
}
// MediaStore manages the lifecycle of media files associated with processing scopes.
@@ -23,6 +37,7 @@ type MediaStore interface {
// Store registers an existing local file under the given scope.
// Returns a ref identifier (e.g. "media://").
// Store does not move or copy the file; it only records the mapping.
+ // If meta.CleanupPolicy is empty, CleanupPolicyDeleteOnCleanup is assumed.
Store(localPath string, meta MediaMeta, scope string) (ref string, err error)
// Resolve returns the local file path for a given ref.
@@ -43,6 +58,11 @@ type mediaEntry struct {
storedAt time.Time
}
+type pathRefState struct {
+ refCount int
+ deleteEligible bool
+}
+
// MediaCleanerConfig configures the background TTL cleanup.
type MediaCleanerConfig struct {
Enabled bool
@@ -57,6 +77,8 @@ type FileMediaStore struct {
refs map[string]mediaEntry
scopeToRefs map[string]map[string]struct{}
refToScope map[string]string
+ refToPath map[string]string
+ pathStates map[string]pathRefState
cleanerCfg MediaCleanerConfig
stop chan struct{}
@@ -71,6 +93,8 @@ func NewFileMediaStore() *FileMediaStore {
refs: make(map[string]mediaEntry),
scopeToRefs: make(map[string]map[string]struct{}),
refToScope: make(map[string]string),
+ refToPath: make(map[string]string),
+ pathStates: make(map[string]pathRefState),
nowFunc: time.Now,
}
}
@@ -81,6 +105,8 @@ func NewFileMediaStoreWithCleanup(cfg MediaCleanerConfig) *FileMediaStore {
refs: make(map[string]mediaEntry),
scopeToRefs: make(map[string]map[string]struct{}),
refToScope: make(map[string]string),
+ refToPath: make(map[string]string),
+ pathStates: make(map[string]pathRefState),
cleanerCfg: cfg,
stop: make(chan struct{}),
nowFunc: time.Now,
@@ -94,6 +120,7 @@ func (s *FileMediaStore) Store(localPath string, meta MediaMeta, scope string) (
}
ref := "media://" + uuid.New().String()
+ meta.CleanupPolicy = normalizeCleanupPolicy(meta.CleanupPolicy)
s.mu.Lock()
defer s.mu.Unlock()
@@ -104,6 +131,18 @@ func (s *FileMediaStore) Store(localPath string, meta MediaMeta, scope string) (
}
s.scopeToRefs[scope][ref] = struct{}{}
s.refToScope[ref] = scope
+ s.refToPath[ref] = localPath
+
+ pathState := s.pathStates[localPath]
+ if pathState.refCount == 0 {
+ pathState.deleteEligible = meta.CleanupPolicy == CleanupPolicyDeleteOnCleanup
+ } else if meta.CleanupPolicy == CleanupPolicyForgetOnly {
+ // Be conservative: once a path is borrowed externally, never let this
+ // lifecycle auto-delete it even if store-managed refs also exist.
+ pathState.deleteEligible = false
+ }
+ pathState.refCount++
+ s.pathStates[localPath] = pathState
return ref, nil
}
@@ -134,7 +173,8 @@ func (s *FileMediaStore) ResolveWithMeta(ref string) (string, MediaMeta, error)
// ReleaseAll removes all files under the given scope and cleans up mappings.
// Phase 1 (under lock): remove entries from maps.
-// Phase 2 (no lock): delete files from disk.
+// Phase 2 (no lock): delete store-managed files from disk once their final
+// path ref is gone.
func (s *FileMediaStore) ReleaseAll(scope string) error {
// Phase 1: collect paths and remove from maps under lock
var paths []string
@@ -147,11 +187,13 @@ func (s *FileMediaStore) ReleaseAll(scope string) error {
}
for ref := range refs {
+ fallbackPath := ""
if entry, exists := s.refs[ref]; exists {
- paths = append(paths, entry.path)
+ fallbackPath = entry.path
+ }
+ if removablePath, shouldDelete := s.releaseRefLocked(ref, fallbackPath); shouldDelete {
+ paths = append(paths, removablePath)
}
- delete(s.refs, ref)
- delete(s.refToScope, ref)
}
delete(s.scopeToRefs, scope)
s.mu.Unlock()
@@ -171,7 +213,7 @@ func (s *FileMediaStore) ReleaseAll(scope string) error {
// CleanExpired removes all entries older than MaxAge.
// Phase 1 (under lock): identify expired entries and remove from maps.
-// Phase 2 (no lock): delete files from disk to minimize lock contention.
+// Phase 2 (no lock): delete store-managed files from disk to minimize lock contention.
func (s *FileMediaStore) CleanExpired() int {
if s.cleanerCfg.MaxAge <= 0 {
return 0
@@ -179,8 +221,8 @@ func (s *FileMediaStore) CleanExpired() int {
// Phase 1: collect expired entries under lock
type expiredEntry struct {
- ref string
- path string
+ ref string
+ deletePath string
}
s.mu.Lock()
@@ -189,8 +231,6 @@ func (s *FileMediaStore) CleanExpired() int {
for ref, entry := range s.refs {
if entry.storedAt.Before(cutoff) {
- expired = append(expired, expiredEntry{ref: ref, path: entry.path})
-
if scope, ok := s.refToScope[ref]; ok {
if scopeRefs, ok := s.scopeToRefs[scope]; ok {
delete(scopeRefs, ref)
@@ -200,17 +240,23 @@ func (s *FileMediaStore) CleanExpired() int {
}
}
- delete(s.refs, ref)
- delete(s.refToScope, ref)
+ expiredItem := expiredEntry{ref: ref}
+ if deletePath, shouldDelete := s.releaseRefLocked(ref, entry.path); shouldDelete {
+ expiredItem.deletePath = deletePath
+ }
+ expired = append(expired, expiredItem)
}
}
s.mu.Unlock()
// Phase 2: delete files without holding the lock
for _, e := range expired {
- if err := os.Remove(e.path); err != nil && !os.IsNotExist(err) {
+ if e.deletePath == "" {
+ continue
+ }
+ if err := os.Remove(e.deletePath); err != nil && !os.IsNotExist(err) {
logger.WarnCF("media", "cleanup: failed to remove file", map[string]any{
- "path": e.path,
+ "path": e.deletePath,
"error": err.Error(),
})
}
@@ -219,6 +265,45 @@ func (s *FileMediaStore) CleanExpired() int {
return len(expired)
}
+func normalizeCleanupPolicy(policy CleanupPolicy) CleanupPolicy {
+ switch policy {
+ case "", CleanupPolicyDeleteOnCleanup:
+ return CleanupPolicyDeleteOnCleanup
+ case CleanupPolicyForgetOnly:
+ return CleanupPolicyForgetOnly
+ default:
+ return CleanupPolicyDeleteOnCleanup
+ }
+}
+
+func (s *FileMediaStore) releaseRefLocked(ref, fallbackPath string) (string, bool) {
+ path := fallbackPath
+ if storedPath, ok := s.refToPath[ref]; ok {
+ path = storedPath
+ delete(s.refToPath, ref)
+ }
+
+ delete(s.refs, ref)
+ delete(s.refToScope, ref)
+
+ if path == "" {
+ return "", false
+ }
+
+ pathState, ok := s.pathStates[path]
+ if !ok {
+ return "", false
+ }
+ if pathState.refCount <= 1 {
+ delete(s.pathStates, path)
+ return path, pathState.deleteEligible
+ }
+
+ pathState.refCount--
+ s.pathStates[path] = pathState
+ return "", false
+}
+
// Start begins the background cleanup goroutine if cleanup is enabled.
// Safe to call multiple times; only the first call starts the goroutine.
func (s *FileMediaStore) Start() {
diff --git a/pkg/media/store_test.go b/pkg/media/store_test.go
index 1dcfdf350..dabcc3142 100644
--- a/pkg/media/store_test.go
+++ b/pkg/media/store_test.go
@@ -77,6 +77,106 @@ func TestReleaseAll(t *testing.T) {
}
}
+func TestReleaseAllForgetOnlyKeepsFile(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ path := createTempFile(t, dir, "workspace.txt")
+ ref, err := store.Store(path, MediaMeta{
+ Source: "test",
+ CleanupPolicy: CleanupPolicyForgetOnly,
+ }, "scope1")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+
+ if err := store.ReleaseAll("scope1"); err != nil {
+ t.Fatalf("ReleaseAll failed: %v", err)
+ }
+
+ if _, err := store.Resolve(ref); err == nil {
+ t.Error("forget-only ref should be unresolvable after release")
+ }
+ if _, err := os.Stat(path); err != nil {
+ t.Errorf("forget-only file should remain on disk: %v", err)
+ }
+}
+
+func TestReleaseAllSharedPathDeletesOnFinalRefOnly(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ path := createTempFile(t, dir, "shared.jpg")
+ refA, err := store.Store(path, MediaMeta{
+ Source: "test",
+ CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+ }, "scopeA")
+ if err != nil {
+ t.Fatalf("Store(scopeA) failed: %v", err)
+ }
+ refB, err := store.Store(path, MediaMeta{
+ Source: "test",
+ CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+ }, "scopeB")
+ if err != nil {
+ t.Fatalf("Store(scopeB) failed: %v", err)
+ }
+
+ if err := store.ReleaseAll("scopeA"); err != nil {
+ t.Fatalf("ReleaseAll(scopeA) failed: %v", err)
+ }
+
+ if _, err := store.Resolve(refA); err == nil {
+ t.Error("refA should be unresolvable after ReleaseAll(scopeA)")
+ }
+ if _, err := store.Resolve(refB); err != nil {
+ t.Fatalf("refB should still resolve: %v", err)
+ }
+ if _, err := os.Stat(path); err != nil {
+ t.Errorf("shared file should remain until final ref is released: %v", err)
+ }
+
+ if err := store.ReleaseAll("scopeB"); err != nil {
+ t.Fatalf("ReleaseAll(scopeB) failed: %v", err)
+ }
+ if _, err := os.Stat(path); !os.IsNotExist(err) {
+ t.Error("shared file should be deleted after final ref is released")
+ }
+}
+
+func TestReleaseAllMixedPoliciesKeepsFile(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ path := createTempFile(t, dir, "shared.txt")
+ if _, err := store.Store(path, MediaMeta{
+ Source: "test",
+ CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+ }, "owned"); err != nil {
+ t.Fatalf("Store(owned) failed: %v", err)
+ }
+ if _, err := store.Store(path, MediaMeta{
+ Source: "test",
+ CleanupPolicy: CleanupPolicyForgetOnly,
+ }, "borrowed"); err != nil {
+ t.Fatalf("Store(borrowed) failed: %v", err)
+ }
+
+ if err := store.ReleaseAll("owned"); err != nil {
+ t.Fatalf("ReleaseAll(owned) failed: %v", err)
+ }
+ if _, err := os.Stat(path); err != nil {
+ t.Fatalf("mixed-policy file should remain after owned ref release: %v", err)
+ }
+
+ if err := store.ReleaseAll("borrowed"); err != nil {
+ t.Fatalf("ReleaseAll(borrowed) failed: %v", err)
+ }
+ if _, err := os.Stat(path); err != nil {
+ t.Errorf("mixed-policy path should not be auto-deleted: %v", err)
+ }
+}
+
func TestMultiScopeIsolation(t *testing.T) {
dir := t.TempDir()
store := NewFileMediaStore()
@@ -293,6 +393,35 @@ func TestCleanExpiredRemovesOldEntries(t *testing.T) {
}
}
+func TestCleanExpiredForgetOnlyKeepsFile(t *testing.T) {
+ dir := t.TempDir()
+ now := time.Now()
+ store := newTestStoreWithCleanup(10 * time.Minute)
+ store.nowFunc = func() time.Time { return now.Add(-20 * time.Minute) }
+
+ path := createTempFile(t, dir, "workspace.txt")
+ ref, err := store.Store(path, MediaMeta{
+ Source: "test",
+ CleanupPolicy: CleanupPolicyForgetOnly,
+ }, "scope1")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+
+ store.nowFunc = func() time.Time { return now }
+ removed := store.CleanExpired()
+
+ if removed != 1 {
+ t.Errorf("expected 1 removed, got %d", removed)
+ }
+ if _, err := store.Resolve(ref); err == nil {
+ t.Error("expired forget-only ref should be unresolvable")
+ }
+ if _, err := os.Stat(path); err != nil {
+ t.Errorf("forget-only file should remain on disk: %v", err)
+ }
+}
+
func TestCleanExpiredKeepsNonExpired(t *testing.T) {
dir := t.TempDir()
now := time.Now()
@@ -346,6 +475,53 @@ func TestCleanExpiredMixedAges(t *testing.T) {
}
}
+func TestCleanExpiredSharedPathDeletesOnFinalRefOnly(t *testing.T) {
+ dir := t.TempDir()
+ now := time.Now()
+ store := newTestStoreWithCleanup(10 * time.Minute)
+
+ path := createTempFile(t, dir, "shared.jpg")
+
+ store.nowFunc = func() time.Time { return now.Add(-20 * time.Minute) }
+ oldRef, err := store.Store(path, MediaMeta{
+ Source: "test",
+ CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+ }, "scope-old")
+ if err != nil {
+ t.Fatalf("Store(old) failed: %v", err)
+ }
+
+ store.nowFunc = func() time.Time { return now }
+ freshRef, err := store.Store(path, MediaMeta{
+ Source: "test",
+ CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+ }, "scope-fresh")
+ if err != nil {
+ t.Fatalf("Store(fresh) failed: %v", err)
+ }
+
+ removed := store.CleanExpired()
+ if removed != 1 {
+ t.Errorf("expected 1 removed, got %d", removed)
+ }
+ if _, err := store.Resolve(oldRef); err == nil {
+ t.Error("old ref should be gone after cleanup")
+ }
+ if _, err := store.Resolve(freshRef); err != nil {
+ t.Fatalf("fresh ref should still resolve: %v", err)
+ }
+ if _, err := os.Stat(path); err != nil {
+ t.Errorf("shared file should remain while fresh ref exists: %v", err)
+ }
+
+ if err := store.ReleaseAll("scope-fresh"); err != nil {
+ t.Fatalf("ReleaseAll(scope-fresh) failed: %v", err)
+ }
+ if _, err := os.Stat(path); !os.IsNotExist(err) {
+ t.Error("shared file should be deleted after final ref is released")
+ }
+}
+
func TestCleanExpiredCleansEmptyScopes(t *testing.T) {
dir := t.TempDir()
now := time.Now()
diff --git a/pkg/migrate/internal/common.go b/pkg/migrate/internal/common.go
index 75aef5dc2..65a87adc4 100644
--- a/pkg/migrate/internal/common.go
+++ b/pkg/migrate/internal/common.go
@@ -6,6 +6,7 @@ import (
"os"
"path/filepath"
+ "github.com/sipeed/picoclaw/pkg"
"github.com/sipeed/picoclaw/pkg/config"
)
@@ -20,7 +21,7 @@ func ResolveTargetHome(override string) (string, error) {
if err != nil {
return "", fmt.Errorf("resolving home directory: %w", err)
}
- return filepath.Join(home, ".picoclaw"), nil
+ return filepath.Join(home, pkg.DefaultPicoClawHome), nil
}
func ExpandHome(path string) string {
diff --git a/pkg/migrate/sources/openclaw/openclaw_config.go b/pkg/migrate/sources/openclaw/openclaw_config.go
index 317bd3e84..b56194b3d 100644
--- a/pkg/migrate/sources/openclaw/openclaw_config.go
+++ b/pkg/migrate/sources/openclaw/openclaw_config.go
@@ -981,13 +981,16 @@ func (c *PicoClawConfig) ToStandardConfig() *config.Config {
cfg.Agents.Defaults.ModelFallbacks = c.Agents.Defaults.ModelFallbacks
for _, m := range c.ModelList {
- cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+ mc := &config.ModelConfig{
ModelName: m.ModelName,
Model: m.Model,
APIBase: m.APIBase,
- APIKey: m.APIKey,
Proxy: m.Proxy,
- })
+ }
+ if m.APIKey != "" {
+ mc.SetAPIKey(m.APIKey)
+ }
+ cfg.ModelList = append(cfg.ModelList, mc)
}
cfg.Channels = c.Channels.ToStandardChannels()
@@ -1020,59 +1023,107 @@ func (c ChannelsConfig) ToStandardChannels() config.ChannelsConfig {
Enabled: c.WhatsApp.Enabled,
BridgeURL: c.WhatsApp.BridgeURL,
},
- Telegram: config.TelegramConfig{
- Enabled: c.Telegram.Enabled,
- Token: c.Telegram.Token,
- Proxy: c.Telegram.Proxy,
- },
- Feishu: config.FeishuConfig{
- Enabled: c.Feishu.Enabled,
- AppID: c.Feishu.AppID,
- AppSecret: c.Feishu.AppSecret,
- EncryptKey: c.Feishu.EncryptKey,
- VerificationToken: c.Feishu.VerificationToken,
- },
- Discord: config.DiscordConfig{
- Enabled: c.Discord.Enabled,
- Token: c.Discord.Token,
- MentionOnly: c.Discord.MentionOnly,
- },
+ Telegram: func() config.TelegramConfig {
+ tc := config.TelegramConfig{
+ Enabled: c.Telegram.Enabled,
+ Proxy: c.Telegram.Proxy,
+ }
+ if c.Telegram.Token != "" {
+ tc.SetToken(c.Telegram.Token)
+ }
+ return tc
+ }(),
+ Feishu: func() config.FeishuConfig {
+ fc := config.FeishuConfig{
+ Enabled: c.Feishu.Enabled,
+ AppID: c.Feishu.AppID,
+ }
+ if c.Feishu.AppSecret != "" {
+ fc.SetAppSecret(c.Feishu.AppSecret)
+ }
+ if c.Feishu.EncryptKey != "" {
+ fc.SetEncryptKey(c.Feishu.EncryptKey)
+ }
+ if c.Feishu.VerificationToken != "" {
+ fc.SetVerificationToken(c.Feishu.VerificationToken)
+ }
+ return fc
+ }(),
+ Discord: func() config.DiscordConfig {
+ dc := config.DiscordConfig{
+ Enabled: c.Discord.Enabled,
+ MentionOnly: c.Discord.MentionOnly,
+ }
+ if c.Discord.Token != "" {
+ dc.SetToken(c.Discord.Token)
+ }
+ return dc
+ }(),
MaixCam: config.MaixCamConfig{
Enabled: c.MaixCam.Enabled,
Host: c.MaixCam.Host,
Port: c.MaixCam.Port,
},
- QQ: config.QQConfig{
- Enabled: c.QQ.Enabled,
- AppID: c.QQ.AppID,
- AppSecret: c.QQ.AppSecret,
- },
- DingTalk: config.DingTalkConfig{
- Enabled: c.DingTalk.Enabled,
- ClientID: c.DingTalk.ClientID,
- ClientSecret: c.DingTalk.ClientSecret,
- },
- Slack: config.SlackConfig{
- Enabled: c.Slack.Enabled,
- BotToken: c.Slack.BotToken,
- AppToken: c.Slack.AppToken,
- },
- Matrix: config.MatrixConfig{
- Enabled: c.Matrix.Enabled,
- Homeserver: c.Matrix.Homeserver,
- UserID: c.Matrix.UserID,
- AccessToken: c.Matrix.AccessToken,
- AllowFrom: c.Matrix.AllowFrom,
- JoinOnInvite: true,
- },
- LINE: config.LINEConfig{
- Enabled: c.LINE.Enabled,
- ChannelSecret: c.LINE.ChannelSecret,
- ChannelAccessToken: c.LINE.ChannelAccessToken,
- WebhookHost: c.LINE.WebhookHost,
- WebhookPort: c.LINE.WebhookPort,
- WebhookPath: c.LINE.WebhookPath,
- },
+ QQ: func() config.QQConfig {
+ qc := config.QQConfig{
+ Enabled: c.QQ.Enabled,
+ AppID: c.QQ.AppID,
+ }
+ if c.QQ.AppSecret != "" {
+ qc.SetAppSecret(c.QQ.AppSecret)
+ }
+ return qc
+ }(),
+ DingTalk: func() config.DingTalkConfig {
+ dt := config.DingTalkConfig{
+ Enabled: c.DingTalk.Enabled,
+ ClientID: c.DingTalk.ClientID,
+ }
+ if c.DingTalk.ClientSecret != "" {
+ dt.SetClientSecret(c.DingTalk.ClientSecret)
+ }
+ return dt
+ }(),
+ Slack: func() config.SlackConfig {
+ sc := config.SlackConfig{
+ Enabled: c.Slack.Enabled,
+ }
+ if c.Slack.BotToken != "" {
+ sc.SetBotToken(c.Slack.BotToken)
+ }
+ if c.Slack.AppToken != "" {
+ sc.SetAppToken(c.Slack.AppToken)
+ }
+ return sc
+ }(),
+ Matrix: func() config.MatrixConfig {
+ mc := config.MatrixConfig{
+ Enabled: c.Matrix.Enabled,
+ Homeserver: c.Matrix.Homeserver,
+ UserID: c.Matrix.UserID,
+ AllowFrom: c.Matrix.AllowFrom,
+ JoinOnInvite: true,
+ }
+ if c.Matrix.AccessToken != "" {
+ mc.SetAccessToken(c.Matrix.AccessToken)
+ }
+ return mc
+ }(),
+ LINE: func() config.LINEConfig {
+ lc := config.LINEConfig{
+ Enabled: c.LINE.Enabled,
+ WebhookHost: c.LINE.WebhookHost,
+ WebhookPort: c.LINE.WebhookPort,
+ WebhookPath: c.LINE.WebhookPath,
+ }
+ if c.LINE.ChannelSecret != "" {
+ lc.SetChannelSecret(c.LINE.ChannelSecret)
+ }
+ if c.LINE.ChannelAccessToken != "" {
+ lc.SetChannelAccessToken(c.LINE.ChannelAccessToken)
+ }
+ return lc
+ }(),
}
}
@@ -1084,30 +1135,44 @@ func (c GatewayConfig) ToStandardGateway() config.GatewayConfig {
}
func (c ToolsConfig) ToStandardTools() config.ToolsConfig {
+ brave := config.BraveConfig{
+ Enabled: c.Web.Brave.Enabled,
+ MaxResults: c.Web.Brave.MaxResults,
+ }
+ if c.Web.Brave.APIKey != "" {
+ brave.SetAPIKey(c.Web.Brave.APIKey)
+ }
+ if len(c.Web.Brave.APIKeys) > 0 {
+ brave.SetAPIKeys(c.Web.Brave.APIKeys)
+ }
+
+ tavily := config.TavilyConfig{
+ Enabled: c.Web.Tavily.Enabled,
+ BaseURL: c.Web.Tavily.BaseURL,
+ MaxResults: c.Web.Tavily.MaxResults,
+ }
+ if c.Web.Tavily.APIKey != "" {
+ tavily.SetAPIKey(c.Web.Tavily.APIKey)
+ }
+
+ perplexity := config.PerplexityConfig{
+ Enabled: c.Web.Perplexity.Enabled,
+ MaxResults: c.Web.Perplexity.MaxResults,
+ }
+ if c.Web.Perplexity.APIKey != "" {
+ perplexity.SetAPIKey(c.Web.Perplexity.APIKey)
+ }
+
return config.ToolsConfig{
Web: config.WebToolsConfig{
- Brave: config.BraveConfig{
- Enabled: c.Web.Brave.Enabled,
- APIKey: c.Web.Brave.APIKey,
- APIKeys: c.Web.Brave.APIKeys,
- MaxResults: c.Web.Brave.MaxResults,
- },
- Tavily: config.TavilyConfig{
- Enabled: c.Web.Tavily.Enabled,
- APIKey: c.Web.Tavily.APIKey,
- BaseURL: c.Web.Tavily.BaseURL,
- MaxResults: c.Web.Tavily.MaxResults,
- },
+ Brave: brave,
+ Tavily: tavily,
DuckDuckGo: config.DuckDuckGoConfig{
Enabled: c.Web.DuckDuckGo.Enabled,
MaxResults: c.Web.DuckDuckGo.MaxResults,
},
- Perplexity: config.PerplexityConfig{
- Enabled: c.Web.Perplexity.Enabled,
- APIKey: c.Web.Perplexity.APIKey,
- MaxResults: c.Web.Perplexity.MaxResults,
- },
- Proxy: c.Web.Proxy,
+ Perplexity: perplexity,
+ Proxy: c.Web.Proxy,
},
Cron: config.CronToolsConfig{
ExecTimeoutMinutes: c.Cron.ExecTimeoutMinutes,
diff --git a/pkg/migrate/sources/openclaw/openclaw_config_test.go b/pkg/migrate/sources/openclaw/openclaw_config_test.go
index 802693825..350b29776 100644
--- a/pkg/migrate/sources/openclaw/openclaw_config_test.go
+++ b/pkg/migrate/sources/openclaw/openclaw_config_test.go
@@ -697,7 +697,7 @@ func TestToStandardConfig(t *testing.T) {
for _, m := range stdCfg.ModelList {
if m.ModelName == "claude-sonnet-4-20250514" {
foundModel = true
- foundAPIKey = m.APIKey
+ foundAPIKey = m.APIKey()
break
}
}
@@ -711,8 +711,8 @@ func TestToStandardConfig(t *testing.T) {
if !stdCfg.Channels.Telegram.Enabled {
t.Error("telegram should be enabled")
}
- if stdCfg.Channels.Telegram.Token != "test-token" {
- t.Errorf("expected token 'test-token', got '%s'", stdCfg.Channels.Telegram.Token)
+ if stdCfg.Channels.Telegram.Token() != "test-token" {
+ t.Errorf("expected token 'test-token', got '%s'", stdCfg.Channels.Telegram.Token())
}
if stdCfg.Gateway.Port != 8080 {
diff --git a/pkg/providers/anthropic_messages/provider.go b/pkg/providers/anthropic_messages/provider.go
index 2b19e941a..6a1c473dd 100644
--- a/pkg/providers/anthropic_messages/provider.go
+++ b/pkg/providers/anthropic_messages/provider.go
@@ -188,17 +188,23 @@ func buildRequestBody(
case "user":
if msg.ToolCallID != "" {
- // Tool result message
- content := []map[string]any{
- {
- "type": "tool_result",
- "tool_use_id": msg.ToolCallID,
- "content": msg.Content,
- },
+ // Tool result message — merge into previous user message if it contains tool_results
+ toolResultBlock := map[string]any{
+ "type": "tool_result",
+ "tool_use_id": msg.ToolCallID,
+ "content": msg.Content,
+ }
+ if len(apiMessages) > 0 {
+ if prev, ok := apiMessages[len(apiMessages)-1].(map[string]any); ok && prev["role"] == "user" {
+ if content, ok := prev["content"].([]map[string]any); ok {
+ prev["content"] = append(content, toolResultBlock)
+ continue
+ }
+ }
}
apiMessages = append(apiMessages, map[string]any{
"role": "user",
- "content": content,
+ "content": []map[string]any{toolResultBlock},
})
} else {
// Regular user message
@@ -246,17 +252,23 @@ func buildRequestBody(
})
case "tool":
- // Tool result (alternative format)
- content := []map[string]any{
- {
- "type": "tool_result",
- "tool_use_id": msg.ToolCallID,
- "content": msg.Content,
- },
+ // Tool result (alternative format) — merge into previous user message if it contains tool_results
+ toolResultBlock := map[string]any{
+ "type": "tool_result",
+ "tool_use_id": msg.ToolCallID,
+ "content": msg.Content,
+ }
+ if len(apiMessages) > 0 {
+ if prev, ok := apiMessages[len(apiMessages)-1].(map[string]any); ok && prev["role"] == "user" {
+ if content, ok := prev["content"].([]map[string]any); ok {
+ prev["content"] = append(content, toolResultBlock)
+ continue
+ }
+ }
}
apiMessages = append(apiMessages, map[string]any{
"role": "user",
- "content": content,
+ "content": []map[string]any{toolResultBlock},
})
}
}
diff --git a/pkg/providers/anthropic_messages/provider_test.go b/pkg/providers/anthropic_messages/provider_test.go
index 8eabc15fa..39bc48117 100644
--- a/pkg/providers/anthropic_messages/provider_test.go
+++ b/pkg/providers/anthropic_messages/provider_test.go
@@ -562,6 +562,96 @@ func TestBuildRequestBodyEdgeCases(t *testing.T) {
}
}
+func TestBuildRequestBody_ConsecutiveToolResultsMerged(t *testing.T) {
+ // Consecutive tool results (role "tool") should be merged into a single "user" message
+ messages := []Message{
+ {Role: "user", Content: "Use tools"},
+ {Role: "assistant", Content: "", ToolCalls: []ToolCall{
+ {ID: "t1", Name: "tool_a", Arguments: map[string]any{"x": 1}},
+ {ID: "t2", Name: "tool_b", Arguments: map[string]any{"y": 2}},
+ }},
+ {Role: "tool", ToolCallID: "t1", Content: "result1"},
+ {Role: "tool", ToolCallID: "t2", Content: "result2"},
+ }
+
+ got, err := buildRequestBody(messages, nil, "test-model", map[string]any{"max_tokens": 8192})
+ if err != nil {
+ t.Fatalf("buildRequestBody() error: %v", err)
+ }
+
+ apiMessages, ok := got["messages"].([]any)
+ if !ok {
+ t.Fatalf("messages is not []any")
+ }
+
+ // Expect: user, assistant, user (merged tool results)
+ if len(apiMessages) != 3 {
+ for i, m := range apiMessages {
+ t.Logf("message[%d]: %+v", i, m)
+ }
+ t.Fatalf("expected 3 API messages, got %d", len(apiMessages))
+ }
+
+ // The third message should be a user message with 2 tool_result blocks
+ toolResultMsg, ok := apiMessages[2].(map[string]any)
+ if !ok {
+ t.Fatalf("tool result message is not map[string]any")
+ }
+ if toolResultMsg["role"] != "user" {
+ t.Errorf("expected role 'user', got %v", toolResultMsg["role"])
+ }
+ content, ok := toolResultMsg["content"].([]map[string]any)
+ if !ok {
+ t.Fatalf("content is not []map[string]any: %T", toolResultMsg["content"])
+ }
+ if len(content) != 2 {
+ t.Fatalf("expected 2 tool_result blocks, got %d", len(content))
+ }
+ if content[0]["tool_use_id"] != "t1" {
+ t.Errorf("first tool_result tool_use_id = %v, want t1", content[0]["tool_use_id"])
+ }
+ if content[1]["tool_use_id"] != "t2" {
+ t.Errorf("second tool_result tool_use_id = %v, want t2", content[1]["tool_use_id"])
+ }
+}
+
+func TestBuildRequestBody_UserToolResultsMerged(t *testing.T) {
+ // Consecutive tool results using role "user" with ToolCallID should also be merged
+ messages := []Message{
+ {Role: "user", Content: "Use tools"},
+ {Role: "assistant", Content: "", ToolCalls: []ToolCall{
+ {ID: "t1", Name: "tool_a", Arguments: map[string]any{"x": 1}},
+ {ID: "t2", Name: "tool_b", Arguments: map[string]any{"y": 2}},
+ }},
+ {Role: "user", ToolCallID: "t1", Content: "result1"},
+ {Role: "user", ToolCallID: "t2", Content: "result2"},
+ }
+
+ got, err := buildRequestBody(messages, nil, "test-model", map[string]any{"max_tokens": 8192})
+ if err != nil {
+ t.Fatalf("buildRequestBody() error: %v", err)
+ }
+
+ apiMessages, ok := got["messages"].([]any)
+ if !ok {
+ t.Fatalf("messages is not []any")
+ }
+
+ // Expect: user, assistant, user (merged tool results)
+ if len(apiMessages) != 3 {
+ t.Fatalf("expected 3 API messages, got %d", len(apiMessages))
+ }
+
+ toolResultMsg := apiMessages[2].(map[string]any)
+ content, ok := toolResultMsg["content"].([]map[string]any)
+ if !ok {
+ t.Fatalf("content is not []map[string]any: %T", toolResultMsg["content"])
+ }
+ if len(content) != 2 {
+ t.Fatalf("expected 2 tool_result blocks, got %d", len(content))
+ }
+}
+
// TestParseResponseBodyEdgeCases tests edge cases for parseResponseBody.
func TestParseResponseBodyEdgeCases(t *testing.T) {
tests := []struct {
diff --git a/pkg/providers/claude_cli_provider_test.go b/pkg/providers/claude_cli_provider_test.go
index d4d648f5a..bc9960f0c 100644
--- a/pkg/providers/claude_cli_provider_test.go
+++ b/pkg/providers/claude_cli_provider_test.go
@@ -413,10 +413,10 @@ func TestChat_EmptyWorkspaceDoesNotSetDir(t *testing.T) {
func TestCreateProvider_ClaudeCli(t *testing.T) {
cfg := config.DefaultConfig()
- cfg.ModelList = []config.ModelConfig{
+ cfg.ModelList = []*config.ModelConfig{
{ModelName: "claude-sonnet-4.6", Model: "claude-cli/claude-sonnet-4.6", Workspace: "/test/ws"},
}
- cfg.Agents.Defaults.Model = "claude-sonnet-4.6"
+ cfg.Agents.Defaults.ModelName = "claude-sonnet-4.6"
provider, _, err := CreateProvider(cfg)
if err != nil {
@@ -434,10 +434,10 @@ func TestCreateProvider_ClaudeCli(t *testing.T) {
func TestCreateProvider_ClaudeCode(t *testing.T) {
cfg := config.DefaultConfig()
- cfg.ModelList = []config.ModelConfig{
+ cfg.ModelList = []*config.ModelConfig{
{ModelName: "claude-code", Model: "claude-cli/claude-code"},
}
- cfg.Agents.Defaults.Model = "claude-code"
+ cfg.Agents.Defaults.ModelName = "claude-code"
provider, _, err := CreateProvider(cfg)
if err != nil {
@@ -450,10 +450,10 @@ func TestCreateProvider_ClaudeCode(t *testing.T) {
func TestCreateProvider_ClaudeCodec(t *testing.T) {
cfg := config.DefaultConfig()
- cfg.ModelList = []config.ModelConfig{
+ cfg.ModelList = []*config.ModelConfig{
{ModelName: "claudecode", Model: "claude-cli/claudecode"},
}
- cfg.Agents.Defaults.Model = "claudecode"
+ cfg.Agents.Defaults.ModelName = "claudecode"
provider, _, err := CreateProvider(cfg)
if err != nil {
@@ -466,10 +466,10 @@ func TestCreateProvider_ClaudeCodec(t *testing.T) {
func TestCreateProvider_ClaudeCliDefaultWorkspace(t *testing.T) {
cfg := config.DefaultConfig()
- cfg.ModelList = []config.ModelConfig{
+ cfg.ModelList = []*config.ModelConfig{
{ModelName: "claude-cli", Model: "claude-cli/claude-sonnet"},
}
- cfg.Agents.Defaults.Model = "claude-cli"
+ cfg.Agents.Defaults.ModelName = "claude-cli"
cfg.Agents.Defaults.Workspace = ""
provider, _, err := CreateProvider(cfg)
diff --git a/pkg/providers/common/common.go b/pkg/providers/common/common.go
index 23680a1bf..90142fb8b 100644
--- a/pkg/providers/common/common.go
+++ b/pkg/providers/common/common.go
@@ -111,6 +111,17 @@ func SerializeMessages(messages []Message) []any {
"url": mediaURL,
},
})
+ continue
+ }
+
+ if format, data, ok := parseDataAudioURL(mediaURL); ok {
+ parts = append(parts, map[string]any{
+ "type": "input_audio",
+ "input_audio": map[string]any{
+ "data": data,
+ "format": format,
+ },
+ })
}
}
@@ -132,6 +143,26 @@ func SerializeMessages(messages []Message) []any {
return out
}
+func parseDataAudioURL(mediaURL string) (format, data string, ok bool) {
+ if !strings.HasPrefix(mediaURL, "data:audio/") {
+ return "", "", false
+ }
+
+ payload := strings.TrimPrefix(mediaURL, "data:audio/")
+ meta, data, found := strings.Cut(payload, ",")
+ if !found {
+ return "", "", false
+ }
+
+ format, _, _ = strings.Cut(meta, ";")
+ format = strings.TrimSpace(format)
+ data = strings.TrimSpace(data)
+ if format == "" || data == "" {
+ return "", "", false
+ }
+ return format, data, true
+}
+
// --- Response parsing ---
// ParseResponse parses a JSON chat completion response body into an LLMResponse.
@@ -214,11 +245,20 @@ func ParseResponse(body io.Reader) (*LLMResponse, error) {
Reasoning: choice.Message.Reasoning,
ReasoningDetails: choice.Message.ReasoningDetails,
ToolCalls: toolCalls,
- FinishReason: choice.FinishReason,
+ FinishReason: normalizeFinishReason(choice.FinishReason),
Usage: apiResponse.Usage,
}, nil
}
+// normalizeFinishReason normalizes finish_reason values across providers.
+// Converts "length" to "truncated" for consistent handling.
+func normalizeFinishReason(reason string) string {
+ if reason == "length" {
+ return "truncated"
+ }
+ return reason
+}
+
// DecodeToolCallArguments decodes a tool call's arguments from raw JSON.
func DecodeToolCallArguments(raw json.RawMessage, name string) map[string]any {
arguments := make(map[string]any)
diff --git a/pkg/providers/common/common_test.go b/pkg/providers/common/common_test.go
index bb7e7434d..79a637d48 100644
--- a/pkg/providers/common/common_test.go
+++ b/pkg/providers/common/common_test.go
@@ -91,6 +91,44 @@ func TestSerializeMessages_WithMedia(t *testing.T) {
}
}
+func TestSerializeMessages_WithAudioMedia(t *testing.T) {
+ messages := []Message{
+ {Role: "user", Content: "transcribe this", Media: []string{"data:audio/ogg;base64,abc123"}},
+ }
+ result := SerializeMessages(messages)
+
+ data, _ := json.Marshal(result)
+ var msgs []map[string]any
+ json.Unmarshal(data, &msgs)
+
+ content, ok := msgs[0]["content"].([]any)
+ if !ok {
+ t.Fatalf("expected array content for media message, got %T", msgs[0]["content"])
+ }
+ if len(content) != 2 {
+ t.Fatalf("expected 2 content parts, got %d", len(content))
+ }
+
+ audioPart, ok := content[1].(map[string]any)
+ if !ok {
+ t.Fatalf("expected audio content part to be an object, got %T", content[1])
+ }
+ if audioPart["type"] != "input_audio" {
+ t.Fatalf("audio part type = %v, want input_audio", audioPart["type"])
+ }
+
+ inputAudio, ok := audioPart["input_audio"].(map[string]any)
+ if !ok {
+ t.Fatalf("expected input_audio object, got %T", audioPart["input_audio"])
+ }
+ if inputAudio["format"] != "ogg" {
+ t.Fatalf("audio format = %v, want ogg", inputAudio["format"])
+ }
+ if inputAudio["data"] != "abc123" {
+ t.Fatalf("audio data = %v, want abc123", inputAudio["data"])
+ }
+}
+
func TestSerializeMessages_MediaWithToolCallID(t *testing.T) {
messages := []Message{
{Role: "tool", Content: "result", Media: []string{"data:image/png;base64,xyz"}, ToolCallID: "call_1"},
diff --git a/pkg/providers/factory.go b/pkg/providers/factory.go
index d2afe2943..354acafcb 100644
--- a/pkg/providers/factory.go
+++ b/pkg/providers/factory.go
@@ -1,400 +1,7 @@
package providers
import (
- "fmt"
- "strings"
-
"github.com/sipeed/picoclaw/pkg/auth"
- "github.com/sipeed/picoclaw/pkg/config"
)
-const defaultAnthropicAPIBase = "https://api.anthropic.com/v1"
-
var getCredential = auth.GetCredential
-
-type providerType int
-
-const (
- providerTypeHTTPCompat providerType = iota
- providerTypeClaudeAuth
- providerTypeCodexAuth
- providerTypeCodexCLIToken
- providerTypeClaudeCLI
- providerTypeCodexCLI
- providerTypeGitHubCopilot
-)
-
-type providerSelection struct {
- providerType providerType
- apiKey string
- apiBase string
- proxy string
- model string
- workspace string
- connectMode string
- enableWebSearch bool
-}
-
-func resolveProviderSelection(cfg *config.Config) (providerSelection, error) {
- model := cfg.Agents.Defaults.GetModelName()
- providerName := strings.ToLower(cfg.Agents.Defaults.Provider)
- lowerModel := strings.ToLower(model)
-
- if providerName == "" && model == "" {
- return providerSelection{}, fmt.Errorf("no model configured: agents.defaults.model is empty")
- }
-
- sel := providerSelection{
- providerType: providerTypeHTTPCompat,
- model: model,
- }
-
- // First, prefer explicit provider configuration.
- if providerName != "" {
- switch providerName {
- case "groq":
- if cfg.Providers.Groq.APIKey != "" {
- sel.apiKey = cfg.Providers.Groq.APIKey
- sel.apiBase = cfg.Providers.Groq.APIBase
- sel.proxy = cfg.Providers.Groq.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.groq.com/openai/v1"
- }
- }
- case "openai", "gpt":
- if cfg.Providers.OpenAI.APIKey != "" || cfg.Providers.OpenAI.AuthMethod != "" {
- sel.enableWebSearch = cfg.Providers.OpenAI.WebSearch
- if cfg.Providers.OpenAI.AuthMethod == "codex-cli" {
- sel.providerType = providerTypeCodexCLIToken
- return sel, nil
- }
- if cfg.Providers.OpenAI.AuthMethod == "oauth" || cfg.Providers.OpenAI.AuthMethod == "token" {
- sel.providerType = providerTypeCodexAuth
- return sel, nil
- }
- sel.apiKey = cfg.Providers.OpenAI.APIKey
- sel.apiBase = cfg.Providers.OpenAI.APIBase
- sel.proxy = cfg.Providers.OpenAI.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.openai.com/v1"
- }
- }
- case "anthropic", "claude":
- if cfg.Providers.Anthropic.APIKey != "" || cfg.Providers.Anthropic.AuthMethod != "" {
- if cfg.Providers.Anthropic.AuthMethod == "oauth" || cfg.Providers.Anthropic.AuthMethod == "token" {
- sel.apiBase = cfg.Providers.Anthropic.APIBase
- if sel.apiBase == "" {
- sel.apiBase = defaultAnthropicAPIBase
- }
- sel.providerType = providerTypeClaudeAuth
- return sel, nil
- }
- sel.apiKey = cfg.Providers.Anthropic.APIKey
- sel.apiBase = cfg.Providers.Anthropic.APIBase
- sel.proxy = cfg.Providers.Anthropic.Proxy
- if sel.apiBase == "" {
- sel.apiBase = defaultAnthropicAPIBase
- }
- }
- case "openrouter":
- if cfg.Providers.OpenRouter.APIKey != "" {
- sel.apiKey = cfg.Providers.OpenRouter.APIKey
- sel.proxy = cfg.Providers.OpenRouter.Proxy
- if cfg.Providers.OpenRouter.APIBase != "" {
- sel.apiBase = cfg.Providers.OpenRouter.APIBase
- } else {
- sel.apiBase = "https://openrouter.ai/api/v1"
- }
- }
- case "litellm":
- if cfg.Providers.LiteLLM.APIKey != "" || cfg.Providers.LiteLLM.APIBase != "" {
- sel.apiKey = cfg.Providers.LiteLLM.APIKey
- sel.apiBase = cfg.Providers.LiteLLM.APIBase
- sel.proxy = cfg.Providers.LiteLLM.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "http://localhost:4000/v1"
- }
- }
- case "zhipu", "glm":
- if cfg.Providers.Zhipu.APIKey != "" {
- sel.apiKey = cfg.Providers.Zhipu.APIKey
- sel.apiBase = cfg.Providers.Zhipu.APIBase
- sel.proxy = cfg.Providers.Zhipu.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://open.bigmodel.cn/api/paas/v4"
- }
- }
- case "gemini", "google":
- if cfg.Providers.Gemini.APIKey != "" {
- sel.apiKey = cfg.Providers.Gemini.APIKey
- sel.apiBase = cfg.Providers.Gemini.APIBase
- sel.proxy = cfg.Providers.Gemini.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://generativelanguage.googleapis.com/v1beta"
- }
- }
- case "vllm":
- if cfg.Providers.VLLM.APIBase != "" {
- sel.apiKey = cfg.Providers.VLLM.APIKey
- sel.apiBase = cfg.Providers.VLLM.APIBase
- sel.proxy = cfg.Providers.VLLM.Proxy
- }
- case "shengsuanyun":
- if cfg.Providers.ShengSuanYun.APIKey != "" {
- sel.apiKey = cfg.Providers.ShengSuanYun.APIKey
- sel.apiBase = cfg.Providers.ShengSuanYun.APIBase
- sel.proxy = cfg.Providers.ShengSuanYun.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://router.shengsuanyun.com/api/v1"
- }
- }
- case "nvidia":
- if cfg.Providers.Nvidia.APIKey != "" {
- sel.apiKey = cfg.Providers.Nvidia.APIKey
- sel.apiBase = cfg.Providers.Nvidia.APIBase
- sel.proxy = cfg.Providers.Nvidia.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://integrate.api.nvidia.com/v1"
- }
- }
- case "vivgrid":
- if cfg.Providers.Vivgrid.APIKey != "" {
- sel.apiKey = cfg.Providers.Vivgrid.APIKey
- sel.apiBase = cfg.Providers.Vivgrid.APIBase
- sel.proxy = cfg.Providers.Vivgrid.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.vivgrid.com/v1"
- }
- }
- case "claude-cli", "claude-code", "claudecode":
- workspace := cfg.WorkspacePath()
- if workspace == "" {
- workspace = "."
- }
- sel.providerType = providerTypeClaudeCLI
- sel.workspace = workspace
- return sel, nil
- case "codex-cli", "codex-code":
- workspace := cfg.WorkspacePath()
- if workspace == "" {
- workspace = "."
- }
- sel.providerType = providerTypeCodexCLI
- sel.workspace = workspace
- return sel, nil
- case "deepseek":
- if cfg.Providers.DeepSeek.APIKey != "" {
- sel.apiKey = cfg.Providers.DeepSeek.APIKey
- sel.apiBase = cfg.Providers.DeepSeek.APIBase
- sel.proxy = cfg.Providers.DeepSeek.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.deepseek.com/v1"
- }
- if model != "deepseek-chat" && model != "deepseek-reasoner" {
- sel.model = "deepseek-chat"
- }
- }
- case "avian":
- if cfg.Providers.Avian.APIKey != "" {
- sel.apiKey = cfg.Providers.Avian.APIKey
- sel.apiBase = cfg.Providers.Avian.APIBase
- sel.proxy = cfg.Providers.Avian.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.avian.io/v1"
- }
- }
- case "mistral":
- if cfg.Providers.Mistral.APIKey != "" {
- sel.apiKey = cfg.Providers.Mistral.APIKey
- sel.apiBase = cfg.Providers.Mistral.APIBase
- sel.proxy = cfg.Providers.Mistral.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.mistral.ai/v1"
- }
- }
- case "minimax":
- if cfg.Providers.Minimax.APIKey != "" {
- sel.apiKey = cfg.Providers.Minimax.APIKey
- sel.apiBase = cfg.Providers.Minimax.APIBase
- sel.proxy = cfg.Providers.Minimax.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.minimaxi.com/v1"
- }
- }
- case "longcat":
- if cfg.Providers.LongCat.APIKey != "" {
- sel.apiKey = cfg.Providers.LongCat.APIKey
- sel.apiBase = cfg.Providers.LongCat.APIBase
- sel.proxy = cfg.Providers.LongCat.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.longcat.chat/openai"
- }
- }
- case "github_copilot", "copilot":
- sel.providerType = providerTypeGitHubCopilot
- if cfg.Providers.GitHubCopilot.APIBase != "" {
- sel.apiBase = cfg.Providers.GitHubCopilot.APIBase
- } else {
- sel.apiBase = "localhost:4321"
- }
- sel.connectMode = cfg.Providers.GitHubCopilot.ConnectMode
- return sel, nil
- }
- }
-
- // Fallback: infer provider from model and configured keys.
- if sel.apiKey == "" && sel.apiBase == "" {
- switch {
- case (strings.Contains(lowerModel, "kimi") || strings.Contains(lowerModel, "moonshot") || strings.HasPrefix(model, "moonshot/")) && cfg.Providers.Moonshot.APIKey != "":
- sel.apiKey = cfg.Providers.Moonshot.APIKey
- sel.apiBase = cfg.Providers.Moonshot.APIBase
- sel.proxy = cfg.Providers.Moonshot.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.moonshot.cn/v1"
- }
- case strings.HasPrefix(model, "openrouter/") ||
- strings.HasPrefix(model, "anthropic/") ||
- strings.HasPrefix(model, "openai/") ||
- strings.HasPrefix(model, "meta-llama/") ||
- strings.HasPrefix(model, "deepseek/") ||
- strings.HasPrefix(model, "google/"):
- sel.apiKey = cfg.Providers.OpenRouter.APIKey
- sel.proxy = cfg.Providers.OpenRouter.Proxy
- if cfg.Providers.OpenRouter.APIBase != "" {
- sel.apiBase = cfg.Providers.OpenRouter.APIBase
- } else {
- sel.apiBase = "https://openrouter.ai/api/v1"
- }
- case (strings.Contains(lowerModel, "claude") || strings.HasPrefix(model, "anthropic/")) &&
- (cfg.Providers.Anthropic.APIKey != "" || cfg.Providers.Anthropic.AuthMethod != ""):
- if cfg.Providers.Anthropic.AuthMethod == "oauth" || cfg.Providers.Anthropic.AuthMethod == "token" {
- sel.apiBase = cfg.Providers.Anthropic.APIBase
- if sel.apiBase == "" {
- sel.apiBase = defaultAnthropicAPIBase
- }
- sel.providerType = providerTypeClaudeAuth
- return sel, nil
- }
- sel.apiKey = cfg.Providers.Anthropic.APIKey
- sel.apiBase = cfg.Providers.Anthropic.APIBase
- sel.proxy = cfg.Providers.Anthropic.Proxy
- if sel.apiBase == "" {
- sel.apiBase = defaultAnthropicAPIBase
- }
- case (strings.Contains(lowerModel, "gpt") || strings.HasPrefix(model, "openai/")) &&
- (cfg.Providers.OpenAI.APIKey != "" || cfg.Providers.OpenAI.AuthMethod != ""):
- sel.enableWebSearch = cfg.Providers.OpenAI.WebSearch
- if cfg.Providers.OpenAI.AuthMethod == "codex-cli" {
- sel.providerType = providerTypeCodexCLIToken
- return sel, nil
- }
- if cfg.Providers.OpenAI.AuthMethod == "oauth" || cfg.Providers.OpenAI.AuthMethod == "token" {
- sel.providerType = providerTypeCodexAuth
- return sel, nil
- }
- sel.apiKey = cfg.Providers.OpenAI.APIKey
- sel.apiBase = cfg.Providers.OpenAI.APIBase
- sel.proxy = cfg.Providers.OpenAI.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.openai.com/v1"
- }
- case (strings.Contains(lowerModel, "gemini") || strings.HasPrefix(model, "google/")) && cfg.Providers.Gemini.APIKey != "":
- sel.apiKey = cfg.Providers.Gemini.APIKey
- sel.apiBase = cfg.Providers.Gemini.APIBase
- sel.proxy = cfg.Providers.Gemini.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://generativelanguage.googleapis.com/v1beta"
- }
- case (strings.Contains(lowerModel, "glm") || strings.Contains(lowerModel, "zhipu") || strings.Contains(lowerModel, "zai")) && cfg.Providers.Zhipu.APIKey != "":
- sel.apiKey = cfg.Providers.Zhipu.APIKey
- sel.apiBase = cfg.Providers.Zhipu.APIBase
- sel.proxy = cfg.Providers.Zhipu.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://open.bigmodel.cn/api/paas/v4"
- }
- case (strings.Contains(lowerModel, "groq") || strings.HasPrefix(model, "groq/")) && cfg.Providers.Groq.APIKey != "":
- sel.apiKey = cfg.Providers.Groq.APIKey
- sel.apiBase = cfg.Providers.Groq.APIBase
- sel.proxy = cfg.Providers.Groq.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.groq.com/openai/v1"
- }
- case (strings.Contains(lowerModel, "nvidia") || strings.HasPrefix(model, "nvidia/")) && cfg.Providers.Nvidia.APIKey != "":
- sel.apiKey = cfg.Providers.Nvidia.APIKey
- sel.apiBase = cfg.Providers.Nvidia.APIBase
- sel.proxy = cfg.Providers.Nvidia.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://integrate.api.nvidia.com/v1"
- }
- case strings.HasPrefix(model, "vivgrid/") && cfg.Providers.Vivgrid.APIKey != "":
- sel.apiKey = cfg.Providers.Vivgrid.APIKey
- sel.apiBase = cfg.Providers.Vivgrid.APIBase
- sel.proxy = cfg.Providers.Vivgrid.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.vivgrid.com/v1"
- }
- case (strings.Contains(lowerModel, "ollama") || strings.HasPrefix(model, "ollama/")) && cfg.Providers.Ollama.APIKey != "":
- sel.apiKey = cfg.Providers.Ollama.APIKey
- sel.apiBase = cfg.Providers.Ollama.APIBase
- sel.proxy = cfg.Providers.Ollama.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "http://localhost:11434/v1"
- }
- case (strings.Contains(lowerModel, "mistral") || strings.HasPrefix(model, "mistral/")) && cfg.Providers.Mistral.APIKey != "":
- sel.apiKey = cfg.Providers.Mistral.APIKey
- sel.apiBase = cfg.Providers.Mistral.APIBase
- sel.proxy = cfg.Providers.Mistral.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.mistral.ai/v1"
- }
- case (strings.Contains(lowerModel, "minimax") || strings.HasPrefix(model, "minimax/")) && cfg.Providers.Minimax.APIKey != "":
- sel.apiKey = cfg.Providers.Minimax.APIKey
- sel.apiBase = cfg.Providers.Minimax.APIBase
- sel.proxy = cfg.Providers.Minimax.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.minimaxi.com/v1"
- }
- case strings.HasPrefix(model, "avian/") && cfg.Providers.Avian.APIKey != "":
- sel.apiKey = cfg.Providers.Avian.APIKey
- sel.apiBase = cfg.Providers.Avian.APIBase
- sel.proxy = cfg.Providers.Avian.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.avian.io/v1"
- }
- case (strings.Contains(lowerModel, "longcat") || strings.HasPrefix(model, "longcat/")) && cfg.Providers.LongCat.APIKey != "":
- sel.apiKey = cfg.Providers.LongCat.APIKey
- sel.apiBase = cfg.Providers.LongCat.APIBase
- sel.proxy = cfg.Providers.LongCat.Proxy
- if sel.apiBase == "" {
- sel.apiBase = "https://api.longcat.chat/openai"
- }
- case cfg.Providers.VLLM.APIBase != "":
- sel.apiKey = cfg.Providers.VLLM.APIKey
- sel.apiBase = cfg.Providers.VLLM.APIBase
- sel.proxy = cfg.Providers.VLLM.Proxy
- default:
- if cfg.Providers.OpenRouter.APIKey != "" {
- sel.apiKey = cfg.Providers.OpenRouter.APIKey
- sel.proxy = cfg.Providers.OpenRouter.Proxy
- if cfg.Providers.OpenRouter.APIBase != "" {
- sel.apiBase = cfg.Providers.OpenRouter.APIBase
- } else {
- sel.apiBase = "https://openrouter.ai/api/v1"
- }
- } else {
- return providerSelection{}, fmt.Errorf("no API key configured for model: %s", model)
- }
- }
- }
-
- if sel.providerType == providerTypeHTTPCompat {
- if sel.apiKey == "" && !strings.HasPrefix(model, "bedrock/") {
- return providerSelection{}, fmt.Errorf("no API key configured for provider (model: %s)", model)
- }
- if sel.apiBase == "" {
- return providerSelection{}, fmt.Errorf("no API base configured for provider (model: %s)", model)
- }
- }
-
- return sel, nil
-}
diff --git a/pkg/providers/factory_provider.go b/pkg/providers/factory_provider.go
index dbb5db5cb..bc7c2ff70 100644
--- a/pkg/providers/factory_provider.go
+++ b/pkg/providers/factory_provider.go
@@ -80,7 +80,7 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
return provider, modelID, nil
}
// OpenAI with API key
- if cfg.APIKey == "" && cfg.APIBase == "" {
+ if cfg.APIKey() == "" && cfg.APIBase == "" {
return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
}
apiBase := cfg.APIBase
@@ -88,17 +88,18 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
apiBase = getDefaultAPIBase(protocol)
}
return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
- cfg.APIKey,
+ cfg.APIKey(),
apiBase,
cfg.Proxy,
cfg.MaxTokensField,
cfg.RequestTimeout,
+ cfg.ExtraBody,
), modelID, nil
case "azure", "azure-openai":
// Azure OpenAI uses deployment-based URLs, api-key header auth,
// and always sends max_completion_tokens.
- if cfg.APIKey == "" {
+ if cfg.APIKey() == "" {
return nil, "", fmt.Errorf("api_key is required for azure protocol")
}
if cfg.APIBase == "" {
@@ -107,7 +108,7 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
)
}
return azure.NewProviderWithTimeout(
- cfg.APIKey,
+ cfg.APIKey(),
cfg.APIBase,
cfg.Proxy,
cfg.RequestTimeout,
@@ -115,10 +116,11 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
case "litellm", "openrouter", "groq", "zhipu", "gemini", "nvidia",
"ollama", "moonshot", "shengsuanyun", "deepseek", "cerebras",
- "vivgrid", "volcengine", "vllm", "qwen", "mistral", "avian",
- "minimax", "longcat", "modelscope", "novita":
+ "vivgrid", "volcengine", "vllm", "qwen", "qwen-intl", "qwen-international", "dashscope-intl",
+ "qwen-us", "dashscope-us", "mistral", "avian", "longcat", "modelscope", "novita",
+ "coding-plan", "alibaba-coding", "qwen-coding":
// All other OpenAI-compatible HTTP providers
- if cfg.APIKey == "" && cfg.APIBase == "" {
+ if cfg.APIKey() == "" && cfg.APIBase == "" {
return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
}
apiBase := cfg.APIBase
@@ -126,11 +128,37 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
apiBase = getDefaultAPIBase(protocol)
}
return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
- cfg.APIKey,
+ cfg.APIKey(),
apiBase,
cfg.Proxy,
cfg.MaxTokensField,
cfg.RequestTimeout,
+ cfg.ExtraBody,
+ ), modelID, nil
+
+ case "minimax":
+ // Minimax requires reasoning_split: true in the request body
+ if cfg.APIKey() == "" && cfg.APIBase == "" {
+ return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
+ }
+ apiBase := cfg.APIBase
+ if apiBase == "" {
+ apiBase = getDefaultAPIBase(protocol)
+ }
+ extraBody := cfg.ExtraBody
+ if extraBody == nil {
+ extraBody = make(map[string]any)
+ }
+ if _, ok := extraBody["reasoning_split"]; !ok {
+ extraBody["reasoning_split"] = true
+ }
+ return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+ cfg.APIKey(),
+ apiBase,
+ cfg.Proxy,
+ cfg.MaxTokensField,
+ cfg.RequestTimeout,
+ extraBody,
), modelID, nil
case "anthropic":
@@ -147,15 +175,16 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
if apiBase == "" {
apiBase = "https://api.anthropic.com/v1"
}
- if cfg.APIKey == "" {
+ if cfg.APIKey() == "" {
return nil, "", fmt.Errorf("api_key is required for anthropic protocol (model: %s)", cfg.Model)
}
return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
- cfg.APIKey,
+ cfg.APIKey(),
apiBase,
cfg.Proxy,
cfg.MaxTokensField,
cfg.RequestTimeout,
+ cfg.ExtraBody,
), modelID, nil
case "anthropic-messages":
@@ -164,11 +193,26 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
if apiBase == "" {
apiBase = "https://api.anthropic.com/v1"
}
- if cfg.APIKey == "" {
+ if cfg.APIKey() == "" {
return nil, "", fmt.Errorf("api_key is required for anthropic-messages protocol (model: %s)", cfg.Model)
}
return anthropicmessages.NewProviderWithTimeout(
- cfg.APIKey,
+ cfg.APIKey(),
+ apiBase,
+ cfg.RequestTimeout,
+ ), modelID, nil
+
+ case "coding-plan-anthropic", "alibaba-coding-anthropic":
+ // Alibaba Coding Plan with Anthropic-compatible API
+ apiBase := cfg.APIBase
+ if apiBase == "" {
+ apiBase = getDefaultAPIBase(protocol)
+ }
+ if cfg.APIKey() == "" {
+ return nil, "", fmt.Errorf("api_key is required for %q protocol (model: %s)", protocol, cfg.Model)
+ }
+ return anthropicmessages.NewProviderWithTimeout(
+ cfg.APIKey(),
apiBase,
cfg.RequestTimeout,
), modelID, nil
@@ -245,6 +289,14 @@ func getDefaultAPIBase(protocol string) string {
return "https://ark.cn-beijing.volces.com/api/v3"
case "qwen":
return "https://dashscope.aliyuncs.com/compatible-mode/v1"
+ case "qwen-intl", "qwen-international", "dashscope-intl":
+ return "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+ case "qwen-us", "dashscope-us":
+ return "https://dashscope-us.aliyuncs.com/compatible-mode/v1"
+ case "coding-plan", "alibaba-coding", "qwen-coding":
+ return "https://coding-intl.dashscope.aliyuncs.com/v1"
+ case "coding-plan-anthropic", "alibaba-coding-anthropic":
+ return "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
case "vllm":
return "http://localhost:8000/v1"
case "mistral":
diff --git a/pkg/providers/factory_provider_test.go b/pkg/providers/factory_provider_test.go
index c7629ad9d..1bff0419d 100644
--- a/pkg/providers/factory_provider_test.go
+++ b/pkg/providers/factory_provider_test.go
@@ -6,6 +6,7 @@
package providers
import (
+ "encoding/json"
"net/http"
"net/http/httptest"
"strings"
@@ -89,9 +90,9 @@ func TestCreateProviderFromConfig_OpenAI(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-openai",
Model: "openai/gpt-4o",
- APIKey: "test-key",
APIBase: "https://api.example.com/v1",
}
+ cfg.SetAPIKey("test-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -129,8 +130,8 @@ func TestCreateProviderFromConfig_DefaultAPIBase(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-" + tt.protocol,
Model: tt.protocol + "/test-model",
- APIKey: "test-key",
}
+ cfg.SetAPIKey("test-key")
provider, _, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -155,9 +156,9 @@ func TestCreateProviderFromConfig_LiteLLM(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-litellm",
Model: "litellm/my-proxy-alias",
- APIKey: "test-key",
APIBase: "http://localhost:4000/v1",
}
+ cfg.SetAPIKey("test-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -175,9 +176,9 @@ func TestCreateProviderFromConfig_LongCat(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-longcat",
Model: "longcat/LongCat-Flash-Thinking",
- APIKey: "test-key",
APIBase: "https://api.longcat.chat/openai",
}
+ cfg.SetAPIKey("test-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -198,9 +199,9 @@ func TestCreateProviderFromConfig_ModelScope(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-modelscope",
Model: "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
- APIKey: "test-key",
APIBase: "https://api-inference.modelscope.cn/v1",
}
+ cfg.SetAPIKey("test-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -227,8 +228,8 @@ func TestCreateProviderFromConfig_Novita(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-novita",
Model: "novita/deepseek/deepseek-v3.2",
- APIKey: "test-key",
}
+ cfg.SetAPIKey("test-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -255,8 +256,8 @@ func TestCreateProviderFromConfig_Anthropic(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-anthropic",
Model: "anthropic/claude-sonnet-4.6",
- APIKey: "test-key",
}
+ cfg.SetAPIKey("test-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -340,8 +341,8 @@ func TestCreateProviderFromConfig_UnknownProtocol(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-unknown",
Model: "unknown-protocol/model",
- APIKey: "test-key",
}
+ cfg.SetAPIKey("test-key")
_, _, err := CreateProviderFromConfig(cfg)
if err == nil {
@@ -382,6 +383,7 @@ func TestCreateProviderFromConfig_RequestTimeoutPropagation(t *testing.T) {
APIBase: server.URL,
RequestTimeout: 1,
}
+ cfg.SetAPIKey("test-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -411,9 +413,9 @@ func TestCreateProviderFromConfig_Azure(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "azure-gpt5",
Model: "azure/my-gpt5-deployment",
- APIKey: "test-azure-key",
APIBase: "https://my-resource.openai.azure.com",
}
+ cfg.SetAPIKey("test-azure-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -431,9 +433,9 @@ func TestCreateProviderFromConfig_AzureOpenAIAlias(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "azure-gpt4",
Model: "azure-openai/my-deployment",
- APIKey: "test-azure-key",
APIBase: "https://my-resource.openai.azure.com",
}
+ cfg.SetAPIKey("test-azure-key")
provider, modelID, err := CreateProviderFromConfig(cfg)
if err != nil {
@@ -464,11 +466,237 @@ func TestCreateProviderFromConfig_AzureMissingAPIBase(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "azure-gpt5",
Model: "azure/my-gpt5-deployment",
- APIKey: "test-azure-key",
}
+ cfg.SetAPIKey("test-azure-key")
_, _, err := CreateProviderFromConfig(cfg)
if err == nil {
t.Fatal("CreateProviderFromConfig() expected error for missing API base")
}
}
+
+func TestCreateProviderFromConfig_QwenInternationalAlias(t *testing.T) {
+ tests := []struct {
+ name string
+ protocol string
+ }{
+ {"qwen-international", "qwen-international"},
+ {"dashscope-intl", "dashscope-intl"},
+ {"qwen-intl", "qwen-intl"},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ cfg := &config.ModelConfig{
+ ModelName: "test-" + tt.protocol,
+ Model: tt.protocol + "/qwen-max",
+ }
+ cfg.SetAPIKey("test-key")
+
+ provider, modelID, err := CreateProviderFromConfig(cfg)
+ if err != nil {
+ t.Fatalf("CreateProviderFromConfig() error = %v", err)
+ }
+ if provider == nil {
+ t.Fatal("CreateProviderFromConfig() returned nil provider")
+ }
+ if modelID != "qwen-max" {
+ t.Errorf("modelID = %q, want %q", modelID, "qwen-max")
+ }
+ if _, ok := provider.(*HTTPProvider); !ok {
+ t.Fatalf("expected *HTTPProvider, got %T", provider)
+ }
+ })
+ }
+}
+
+func TestCreateProviderFromConfig_QwenUSAlias(t *testing.T) {
+ tests := []struct {
+ name string
+ protocol string
+ }{
+ {"qwen-us", "qwen-us"},
+ {"dashscope-us", "dashscope-us"},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ cfg := &config.ModelConfig{
+ ModelName: "test-" + tt.protocol,
+ Model: tt.protocol + "/qwen-max",
+ }
+ cfg.SetAPIKey("test-key")
+
+ provider, modelID, err := CreateProviderFromConfig(cfg)
+ if err != nil {
+ t.Fatalf("CreateProviderFromConfig() error = %v", err)
+ }
+ if provider == nil {
+ t.Fatal("CreateProviderFromConfig() returned nil provider")
+ }
+ if modelID != "qwen-max" {
+ t.Errorf("modelID = %q, want %q", modelID, "qwen-max")
+ }
+ if _, ok := provider.(*HTTPProvider); !ok {
+ t.Fatalf("expected *HTTPProvider, got %T", provider)
+ }
+ })
+ }
+}
+
+func TestCreateProviderFromConfig_CodingPlanAnthropic(t *testing.T) {
+ tests := []struct {
+ name string
+ protocol string
+ }{
+ {"coding-plan-anthropic", "coding-plan-anthropic"},
+ {"alibaba-coding-anthropic", "alibaba-coding-anthropic"},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ cfg := &config.ModelConfig{
+ ModelName: "test-" + tt.protocol,
+ Model: tt.protocol + "/claude-sonnet-4-20250514",
+ }
+ cfg.SetAPIKey("test-key")
+
+ provider, modelID, err := CreateProviderFromConfig(cfg)
+ if err != nil {
+ t.Fatalf("CreateProviderFromConfig() error = %v", err)
+ }
+ if provider == nil {
+ t.Fatal("CreateProviderFromConfig() returned nil provider")
+ }
+ if modelID != "claude-sonnet-4-20250514" {
+ t.Errorf("modelID = %q, want %q", modelID, "claude-sonnet-4-20250514")
+ }
+ // coding-plan-anthropic uses Anthropic Messages provider
+ // Verify it's the anthropic messages provider by checking interface
+ var _ LLMProvider = provider
+ })
+ }
+}
+
+func TestGetDefaultAPIBase_CodingPlanAnthropic(t *testing.T) {
+ expectedURL := "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
+ if got := getDefaultAPIBase("coding-plan-anthropic"); got != expectedURL {
+ t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", "coding-plan-anthropic", got, expectedURL)
+ }
+ if got := getDefaultAPIBase("alibaba-coding-anthropic"); got != expectedURL {
+ t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", "alibaba-coding-anthropic", got, expectedURL)
+ }
+}
+
+func TestGetDefaultAPIBase_QwenIntlAliases(t *testing.T) {
+ expectedURL := "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+ for _, protocol := range []string{"qwen-intl", "qwen-international", "dashscope-intl"} {
+ if got := getDefaultAPIBase(protocol); got != expectedURL {
+ t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", protocol, got, expectedURL)
+ }
+ }
+}
+
+func TestGetDefaultAPIBase_QwenUSAliases(t *testing.T) {
+ expectedURL := "https://dashscope-us.aliyuncs.com/compatible-mode/v1"
+ for _, protocol := range []string{"qwen-us", "dashscope-us"} {
+ if got := getDefaultAPIBase(protocol); got != expectedURL {
+ t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", protocol, got, expectedURL)
+ }
+ }
+}
+
+func TestCreateProviderFromConfig_MinimaxInjectsReasoningSplit(t *testing.T) {
+ var requestBody map[string]any
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"},"finish_reason":"stop"}]}`))
+ }))
+ defer server.Close()
+
+ cfg := &config.ModelConfig{
+ ModelName: "test-minimax",
+ Model: "minimax/MiniMax-M2.5",
+ APIBase: server.URL,
+ }
+ cfg.SetAPIKey("test-key")
+
+ provider, modelID, err := CreateProviderFromConfig(cfg)
+ if err != nil {
+ t.Fatalf("CreateProviderFromConfig() error = %v", err)
+ }
+ if provider == nil {
+ t.Fatal("CreateProviderFromConfig() returned nil provider")
+ }
+ if modelID != "MiniMax-M2.5" {
+ t.Errorf("modelID = %q, want %q", modelID, "MiniMax-M2.5")
+ }
+
+ _, err = provider.Chat(
+ t.Context(),
+ []Message{{Role: "user", Content: "hi"}},
+ nil,
+ modelID,
+ nil,
+ )
+ if err != nil {
+ t.Fatalf("Chat() error = %v", err)
+ }
+
+ // Verify reasoning_split is automatically injected
+ if got, ok := requestBody["reasoning_split"]; !ok || got != true {
+ t.Fatalf("reasoning_split = %v, want true", got)
+ }
+}
+
+func TestCreateProviderFromConfig_MinimaxPreservesUserExtraBody(t *testing.T) {
+ var requestBody map[string]any
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"},"finish_reason":"stop"}]}`))
+ }))
+ defer server.Close()
+
+ cfg := &config.ModelConfig{
+ ModelName: "test-minimax-custom",
+ Model: "minimax/MiniMax-M2.5",
+ APIBase: server.URL,
+ ExtraBody: map[string]any{"custom_field": "test"},
+ }
+ cfg.SetAPIKey("test-key")
+
+ provider, modelID, err := CreateProviderFromConfig(cfg)
+ if err != nil {
+ t.Fatalf("CreateProviderFromConfig() error = %v", err)
+ }
+
+ _, err = provider.Chat(
+ t.Context(),
+ []Message{{Role: "user", Content: "hi"}},
+ nil,
+ modelID,
+ nil,
+ )
+ if err != nil {
+ t.Fatalf("Chat() error = %v", err)
+ }
+
+ // Verify reasoning_split is automatically injected
+ if got, ok := requestBody["reasoning_split"]; !ok || got != true {
+ t.Fatalf("reasoning_split = %v, want true", got)
+ }
+ // Verify user's custom field is preserved
+ if got, ok := requestBody["custom_field"]; !ok || got != "test" {
+ t.Fatalf("custom_field = %v, want test", got)
+ }
+}
diff --git a/pkg/providers/factory_test.go b/pkg/providers/factory_test.go
index 91469f25b..b99f5baf9 100644
--- a/pkg/providers/factory_test.go
+++ b/pkg/providers/factory_test.go
@@ -1,262 +1,22 @@
package providers
import (
- "strings"
"testing"
"github.com/sipeed/picoclaw/pkg/auth"
"github.com/sipeed/picoclaw/pkg/config"
)
-func TestResolveProviderSelection(t *testing.T) {
- tests := []struct {
- name string
- setup func(*config.Config)
- wantType providerType
- wantAPIBase string
- wantProxy string
- wantErrSubstr string
- }{
- {
- name: "explicit litellm provider uses configured base",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "litellm"
- cfg.Providers.LiteLLM.APIKey = "litellm-key"
- cfg.Providers.LiteLLM.APIBase = "http://localhost:4000/v1"
- cfg.Providers.LiteLLM.Proxy = "http://127.0.0.1:7890"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "http://localhost:4000/v1",
- wantProxy: "http://127.0.0.1:7890",
- },
- {
- name: "explicit litellm provider defaults base when only key is configured",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "litellm"
- cfg.Providers.LiteLLM.APIKey = "litellm-key"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "http://localhost:4000/v1",
- },
- {
- name: "explicit claude-cli provider routes to cli provider type",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "claude-cli"
- cfg.Agents.Defaults.Workspace = "/tmp/ws"
- },
- wantType: providerTypeClaudeCLI,
- },
- {
- name: "explicit copilot provider routes to github copilot type",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "copilot"
- },
- wantType: providerTypeGitHubCopilot,
- wantAPIBase: "localhost:4321",
- },
- {
- name: "explicit deepseek provider uses deepseek defaults",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "deepseek"
- cfg.Agents.Defaults.Model = "deepseek/deepseek-chat"
- cfg.Providers.DeepSeek.APIKey = "deepseek-key"
- cfg.Providers.DeepSeek.Proxy = "http://127.0.0.1:7890"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://api.deepseek.com/v1",
- wantProxy: "http://127.0.0.1:7890",
- },
- {
- name: "explicit shengsuanyun provider uses defaults",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "shengsuanyun"
- cfg.Providers.ShengSuanYun.APIKey = "ssy-key"
- cfg.Providers.ShengSuanYun.Proxy = "http://127.0.0.1:7890"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://router.shengsuanyun.com/api/v1",
- wantProxy: "http://127.0.0.1:7890",
- },
- {
- name: "explicit nvidia provider uses defaults",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "nvidia"
- cfg.Providers.Nvidia.APIKey = "nvapi-test"
- cfg.Providers.Nvidia.Proxy = "http://127.0.0.1:7890"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://integrate.api.nvidia.com/v1",
- wantProxy: "http://127.0.0.1:7890",
- },
- {
- name: "explicit vivgrid provider uses defaults",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "vivgrid"
- cfg.Providers.Vivgrid.APIKey = "vivgrid-key"
- cfg.Providers.Vivgrid.Proxy = "http://127.0.0.1:7890"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://api.vivgrid.com/v1",
- wantProxy: "http://127.0.0.1:7890",
- },
- {
- name: "openrouter model uses openrouter defaults",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "openrouter/auto"
- cfg.Providers.OpenRouter.APIKey = "sk-or-test"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://openrouter.ai/api/v1",
- },
- {
- name: "anthropic oauth routes to claude auth provider",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "claude-sonnet-4.6"
- cfg.Providers.Anthropic.AuthMethod = "oauth"
- },
- wantType: providerTypeClaudeAuth,
- },
- {
- name: "openai oauth routes to codex auth provider",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "gpt-4o"
- cfg.Providers.OpenAI.AuthMethod = "oauth"
- },
- wantType: providerTypeCodexAuth,
- },
- {
- name: "openai codex-cli auth routes to codex cli token provider",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "gpt-4o"
- cfg.Providers.OpenAI.AuthMethod = "codex-cli"
- },
- wantType: providerTypeCodexCLIToken,
- },
- {
- name: "explicit codex-code provider routes to codex cli provider type",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "codex-code"
- cfg.Agents.Defaults.Workspace = "/tmp/ws"
- },
- wantType: providerTypeCodexCLI,
- },
- {
- name: "zhipu model uses zhipu base default",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "glm-4.7"
- cfg.Providers.Zhipu.APIKey = "zhipu-key"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://open.bigmodel.cn/api/paas/v4",
- },
- {
- name: "groq model uses groq base default",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "groq/llama-3.3-70b"
- cfg.Providers.Groq.APIKey = "gsk-key"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://api.groq.com/openai/v1",
- },
- {
- name: "ollama model uses ollama base default",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "ollama/qwen2.5:14b"
- cfg.Providers.Ollama.APIKey = "ollama-key"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "http://localhost:11434/v1",
- },
- {
- name: "moonshot model keeps proxy and default base",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "moonshot/kimi-k2.5"
- cfg.Providers.Moonshot.APIKey = "moonshot-key"
- cfg.Providers.Moonshot.Proxy = "http://127.0.0.1:7890"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://api.moonshot.cn/v1",
- wantProxy: "http://127.0.0.1:7890",
- },
- {
- name: "explicit longcat provider uses defaults",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Provider = "longcat"
- cfg.Providers.LongCat.APIKey = "longcat-key"
- cfg.Providers.LongCat.Proxy = "http://127.0.0.1:7890"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://api.longcat.chat/openai",
- wantProxy: "http://127.0.0.1:7890",
- },
- {
- name: "longcat model fallback uses longcat base default",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "longcat/LongCat-Flash-Thinking"
- cfg.Providers.LongCat.APIKey = "longcat-key"
- },
- wantType: providerTypeHTTPCompat,
- wantAPIBase: "https://api.longcat.chat/openai",
- },
- {
- name: "missing keys returns model config error",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "custom-model"
- },
- wantErrSubstr: "no API key configured for model",
- },
- {
- name: "openrouter prefix without key returns provider key error",
- setup: func(cfg *config.Config) {
- cfg.Agents.Defaults.Model = "openrouter/auto"
- },
- wantErrSubstr: "no API key configured for provider",
- },
- }
-
- for _, tt := range tests {
- t.Run(tt.name, func(t *testing.T) {
- cfg := config.DefaultConfig()
- tt.setup(cfg)
-
- got, err := resolveProviderSelection(cfg)
- if tt.wantErrSubstr != "" {
- if err == nil {
- t.Fatalf("expected error containing %q, got nil", tt.wantErrSubstr)
- }
- if !strings.Contains(err.Error(), tt.wantErrSubstr) {
- t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantErrSubstr)
- }
- return
- }
-
- if err != nil {
- t.Fatalf("resolveProviderSelection() error = %v", err)
- }
- if got.providerType != tt.wantType {
- t.Fatalf("providerType = %v, want %v", got.providerType, tt.wantType)
- }
- if tt.wantAPIBase != "" && got.apiBase != tt.wantAPIBase {
- t.Fatalf("apiBase = %q, want %q", got.apiBase, tt.wantAPIBase)
- }
- if tt.wantProxy != "" && got.proxy != tt.wantProxy {
- t.Fatalf("proxy = %q, want %q", got.proxy, tt.wantProxy)
- }
- })
- }
-}
-
func TestCreateProviderReturnsHTTPProviderForOpenRouter(t *testing.T) {
cfg := config.DefaultConfig()
- cfg.Agents.Defaults.Model = "test-openrouter"
- cfg.ModelList = []config.ModelConfig{
- {
- ModelName: "test-openrouter",
- Model: "openrouter/auto",
- APIKey: "sk-or-test",
- APIBase: "https://openrouter.ai/api/v1",
- },
+ cfg.Agents.Defaults.ModelName = "test-openrouter"
+ modelCfg := &config.ModelConfig{
+ ModelName: "test-openrouter",
+ Model: "openrouter/auto",
+ APIBase: "https://openrouter.ai/api/v1",
}
+ modelCfg.SetAPIKey("sk-or-test")
+ cfg.ModelList = []*config.ModelConfig{modelCfg}
provider, _, err := CreateProvider(cfg)
if err != nil {
@@ -270,8 +30,8 @@ func TestCreateProviderReturnsHTTPProviderForOpenRouter(t *testing.T) {
func TestCreateProviderReturnsCodexCliProviderForCodexCode(t *testing.T) {
cfg := config.DefaultConfig()
- cfg.Agents.Defaults.Model = "test-codex"
- cfg.ModelList = []config.ModelConfig{
+ cfg.Agents.Defaults.ModelName = "test-codex"
+ cfg.ModelList = []*config.ModelConfig{
{
ModelName: "test-codex",
Model: "codex-cli/codex-model",
@@ -291,8 +51,8 @@ func TestCreateProviderReturnsCodexCliProviderForCodexCode(t *testing.T) {
func TestCreateProviderReturnsClaudeCliProviderForClaudeCli(t *testing.T) {
cfg := config.DefaultConfig()
- cfg.Agents.Defaults.Model = "test-claude-cli"
- cfg.ModelList = []config.ModelConfig{
+ cfg.Agents.Defaults.ModelName = "test-claude-cli"
+ cfg.ModelList = []*config.ModelConfig{
{
ModelName: "test-claude-cli",
Model: "claude-cli/claude-sonnet",
@@ -324,8 +84,8 @@ func TestCreateProviderReturnsClaudeProviderForAnthropicOAuth(t *testing.T) {
}
cfg := config.DefaultConfig()
- cfg.Agents.Defaults.Model = "test-claude-oauth"
- cfg.ModelList = []config.ModelConfig{
+ cfg.Agents.Defaults.ModelName = "test-claude-oauth"
+ cfg.ModelList = []*config.ModelConfig{
{
ModelName: "test-claude-oauth",
Model: "anthropic/claude-sonnet-4.6",
diff --git a/pkg/providers/http_provider.go b/pkg/providers/http_provider.go
index 4d823630e..f2ff52f1d 100644
--- a/pkg/providers/http_provider.go
+++ b/pkg/providers/http_provider.go
@@ -24,12 +24,13 @@ func NewHTTPProvider(apiKey, apiBase, proxy string) *HTTPProvider {
}
func NewHTTPProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *HTTPProvider {
- return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(apiKey, apiBase, proxy, maxTokensField, 0)
+ return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(apiKey, apiBase, proxy, maxTokensField, 0, nil)
}
func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
apiKey, apiBase, proxy, maxTokensField string,
requestTimeoutSeconds int,
+ extraBody map[string]any,
) *HTTPProvider {
return &HTTPProvider{
delegate: openai_compat.NewProvider(
@@ -38,6 +39,7 @@ func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
proxy,
openai_compat.WithMaxTokensField(maxTokensField),
openai_compat.WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+ openai_compat.WithExtraBody(extraBody),
),
}
}
@@ -52,6 +54,19 @@ func (p *HTTPProvider) Chat(
return p.delegate.Chat(ctx, messages, tools, model, options)
}
+// ChatStream implements providers.StreamingProvider by delegating to the
+// OpenAI-compatible streaming endpoint (SSE with stream: true).
+func (p *HTTPProvider) ChatStream(
+ ctx context.Context,
+ messages []Message,
+ tools []ToolDefinition,
+ model string,
+ options map[string]any,
+ onChunk func(accumulated string),
+) (*LLMResponse, error) {
+ return p.delegate.ChatStream(ctx, messages, tools, model, options, onChunk)
+}
+
func (p *HTTPProvider) GetDefaultModel() string {
return ""
}
diff --git a/pkg/providers/legacy_provider.go b/pkg/providers/legacy_provider.go
index 26905159f..4b0815dd4 100644
--- a/pkg/providers/legacy_provider.go
+++ b/pkg/providers/legacy_provider.go
@@ -18,23 +18,6 @@ import (
func CreateProvider(cfg *config.Config) (LLMProvider, string, error) {
model := cfg.Agents.Defaults.GetModelName()
- // Ensure model_list is populated from providers config if needed
- // This handles two cases:
- // 1. ModelList is empty - convert all providers
- // 2. ModelList has some entries but not all providers - merge missing ones
- if cfg.HasProvidersConfig() {
- providerModels := config.ConvertProvidersToModelList(cfg)
- existingModelNames := make(map[string]bool)
- for _, m := range cfg.ModelList {
- existingModelNames[m.ModelName] = true
- }
- for _, pm := range providerModels {
- if !existingModelNames[pm.ModelName] {
- cfg.ModelList = append(cfg.ModelList, pm)
- }
- }
- }
-
// Must have model_list at this point
if len(cfg.ModelList) == 0 {
return nil, "", fmt.Errorf("no providers configured. Please add entries to model_list in your config")
diff --git a/pkg/providers/model_ref.go b/pkg/providers/model_ref.go
index 0d1b02d16..be9f63bc6 100644
--- a/pkg/providers/model_ref.go
+++ b/pkg/providers/model_ref.go
@@ -53,6 +53,14 @@ func NormalizeProvider(provider string) string {
return "zhipu"
case "google":
return "gemini"
+ case "alibaba-coding", "qwen-coding":
+ return "coding-plan"
+ case "alibaba-coding-anthropic":
+ return "coding-plan-anthropic"
+ case "qwen-international", "dashscope-intl":
+ return "qwen-intl"
+ case "dashscope-us":
+ return "qwen-us"
}
return p
diff --git a/pkg/providers/model_ref_test.go b/pkg/providers/model_ref_test.go
index 6dd25167f..040c511ba 100644
--- a/pkg/providers/model_ref_test.go
+++ b/pkg/providers/model_ref_test.go
@@ -73,6 +73,14 @@ func TestNormalizeProvider(t *testing.T) {
{"glm", "zhipu"},
{"google", "gemini"},
{"groq", "groq"},
+ // Alibaba Coding Plan aliases
+ {"alibaba-coding", "coding-plan"},
+ {"qwen-coding", "coding-plan"},
+ {"alibaba-coding-anthropic", "coding-plan-anthropic"},
+ // Qwen international aliases
+ {"qwen-international", "qwen-intl"},
+ {"dashscope-intl", "qwen-intl"},
+ {"dashscope-us", "qwen-us"},
{"", ""},
}
diff --git a/pkg/providers/openai_compat/provider.go b/pkg/providers/openai_compat/provider.go
index 463db83c9..90bc683b8 100644
--- a/pkg/providers/openai_compat/provider.go
+++ b/pkg/providers/openai_compat/provider.go
@@ -1,10 +1,13 @@
package openai_compat
import (
+ "bufio"
"bytes"
"context"
"encoding/json"
"fmt"
+ "io"
+ "log"
"net/http"
"net/url"
"strings"
@@ -32,6 +35,7 @@ type Provider struct {
apiBase string
maxTokensField string // Field name for max tokens (e.g., "max_completion_tokens" for o1/glm models)
httpClient *http.Client
+ extraBody map[string]any // Additional fields to inject into request body
}
type Option func(*Provider)
@@ -52,6 +56,12 @@ func WithRequestTimeout(timeout time.Duration) Option {
}
}
+func WithExtraBody(extraBody map[string]any) Option {
+ return func(p *Provider) {
+ p.extraBody = extraBody
+ }
+}
+
func NewProvider(apiKey, apiBase, proxy string, opts ...Option) *Provider {
p := &Provider{
apiKey: apiKey,
@@ -85,17 +95,10 @@ func NewProviderWithMaxTokensFieldAndTimeout(
)
}
-func (p *Provider) Chat(
- ctx context.Context,
- messages []Message,
- tools []ToolDefinition,
- model string,
- options map[string]any,
-) (*LLMResponse, error) {
- if p.apiBase == "" {
- return nil, fmt.Errorf("API base not configured")
- }
-
+// buildRequestBody constructs the common request body for Chat and ChatStream.
+func (p *Provider) buildRequestBody(
+ messages []Message, tools []ToolDefinition, model string, options map[string]any,
+) map[string]any {
model = normalizeModel(model, p.apiBase)
requestBody := map[string]any{
@@ -112,10 +115,8 @@ func (p *Provider) Chat(
}
if maxTokens, ok := common.AsInt(options["max_tokens"]); ok {
- // Use configured maxTokensField if specified, otherwise fallback to model-based detection
fieldName := p.maxTokensField
if fieldName == "" {
- // Fallback: detect from model name for backward compatibility
lowerModel := strings.ToLower(model)
if strings.Contains(lowerModel, "glm") || strings.Contains(lowerModel, "o1") ||
strings.Contains(lowerModel, "gpt-5") {
@@ -129,7 +130,6 @@ func (p *Provider) Chat(
if temperature, ok := common.AsFloat(options["temperature"]); ok {
lowerModel := strings.ToLower(model)
- // Kimi k2 models only support temperature=1.
if strings.Contains(lowerModel, "kimi") && strings.Contains(lowerModel, "k2") {
requestBody["temperature"] = 1.0
} else {
@@ -139,17 +139,36 @@ func (p *Provider) Chat(
// Prompt caching: pass a stable cache key so OpenAI can bucket requests
// with the same key and reuse prefix KV cache across calls.
- // The key is typically the agent ID — stable per agent, shared across requests.
- // See: https://platform.openai.com/docs/guides/prompt-caching
// Prompt caching is only supported by OpenAI-native endpoints.
- // Non-OpenAI providers (Mistral, Gemini, DeepSeek, etc.) reject unknown
- // fields with 422 errors, so only include it for OpenAI APIs.
+ // Non-OpenAI providers reject unknown fields with 422 errors.
if cacheKey, ok := options["prompt_cache_key"].(string); ok && cacheKey != "" {
if supportsPromptCacheKey(p.apiBase) {
requestBody["prompt_cache_key"] = cacheKey
}
}
+ // Merge extra body fields configured per-provider/model.
+ // These are injected last so they take precedence over defaults.
+ for k, v := range p.extraBody {
+ requestBody[k] = v
+ }
+
+ return requestBody
+}
+
+func (p *Provider) Chat(
+ ctx context.Context,
+ messages []Message,
+ tools []ToolDefinition,
+ model string,
+ options map[string]any,
+) (*LLMResponse, error) {
+ if p.apiBase == "" {
+ return nil, fmt.Errorf("API base not configured")
+ }
+
+ requestBody := p.buildRequestBody(messages, tools, model, options)
+
jsonData, err := json.Marshal(requestBody)
if err != nil {
return nil, fmt.Errorf("failed to marshal request: %w", err)
@@ -178,6 +197,195 @@ func (p *Provider) Chat(
return common.ReadAndParseResponse(resp, p.apiBase)
}
+// ChatStream implements streaming via OpenAI-compatible SSE (stream: true).
+// onChunk receives the accumulated text so far on each text delta.
+func (p *Provider) ChatStream(
+ ctx context.Context,
+ messages []Message,
+ tools []ToolDefinition,
+ model string,
+ options map[string]any,
+ onChunk func(accumulated string),
+) (*LLMResponse, error) {
+ if p.apiBase == "" {
+ return nil, fmt.Errorf("API base not configured")
+ }
+
+ requestBody := p.buildRequestBody(messages, tools, model, options)
+ requestBody["stream"] = true
+
+ jsonData, err := json.Marshal(requestBody)
+ if err != nil {
+ return nil, fmt.Errorf("failed to marshal request: %w", err)
+ }
+
+ req, err := http.NewRequestWithContext(ctx, "POST", p.apiBase+"/chat/completions", bytes.NewReader(jsonData))
+ if err != nil {
+ return nil, fmt.Errorf("failed to create request: %w", err)
+ }
+
+ req.Header.Set("Content-Type", "application/json")
+ req.Header.Set("Accept", "text/event-stream")
+ if p.apiKey != "" {
+ req.Header.Set("Authorization", "Bearer "+p.apiKey)
+ }
+
+ // Use a client without Timeout for streaming — the http.Client.Timeout covers
+ // the entire request lifecycle including body reads, which would kill long streams.
+ // Context cancellation still provides the safety net.
+ streamClient := &http.Client{Transport: p.httpClient.Transport}
+ resp, err := streamClient.Do(req)
+ if err != nil {
+ return nil, fmt.Errorf("failed to send request: %w", err)
+ }
+ defer resp.Body.Close()
+
+ if resp.StatusCode != http.StatusOK {
+ return nil, common.HandleErrorResponse(resp, p.apiBase)
+ }
+
+ return parseStreamResponse(ctx, resp.Body, onChunk)
+}
+
+// parseStreamResponse parses an OpenAI-compatible SSE stream.
+func parseStreamResponse(
+ ctx context.Context,
+ reader io.Reader,
+ onChunk func(accumulated string),
+) (*LLMResponse, error) {
+ var textContent strings.Builder
+ var finishReason string
+ var usage *UsageInfo
+
+ // Tool call assembly: OpenAI streams tool calls as incremental deltas
+ type toolAccum struct {
+ id string
+ name string
+ argsJSON strings.Builder
+ }
+ activeTools := map[int]*toolAccum{}
+
+ scanner := bufio.NewScanner(reader)
+ scanner.Buffer(make([]byte, 0, 1024*1024), 10*1024*1024) // 1MB initial, 10MB max
+ for scanner.Scan() {
+ // Check for context cancellation between chunks
+ if err := ctx.Err(); err != nil {
+ return nil, err
+ }
+
+ line := scanner.Text()
+
+ if !strings.HasPrefix(line, "data: ") {
+ continue
+ }
+ data := strings.TrimPrefix(line, "data: ")
+ if data == "[DONE]" {
+ break
+ }
+
+ var chunk struct {
+ Choices []struct {
+ Delta struct {
+ Content string `json:"content"`
+ ToolCalls []struct {
+ Index int `json:"index"`
+ ID string `json:"id"`
+ Function *struct {
+ Name string `json:"name"`
+ Arguments string `json:"arguments"`
+ } `json:"function"`
+ } `json:"tool_calls"`
+ } `json:"delta"`
+ FinishReason *string `json:"finish_reason"`
+ } `json:"choices"`
+ Usage *UsageInfo `json:"usage"`
+ }
+
+ if err := json.Unmarshal([]byte(data), &chunk); err != nil {
+ continue // skip malformed chunks
+ }
+
+ if chunk.Usage != nil {
+ usage = chunk.Usage
+ }
+
+ if len(chunk.Choices) == 0 {
+ continue
+ }
+
+ choice := chunk.Choices[0]
+
+ // Accumulate text content
+ if choice.Delta.Content != "" {
+ textContent.WriteString(choice.Delta.Content)
+ if onChunk != nil {
+ onChunk(textContent.String())
+ }
+ }
+
+ // Accumulate tool call deltas
+ for _, tc := range choice.Delta.ToolCalls {
+ acc, ok := activeTools[tc.Index]
+ if !ok {
+ acc = &toolAccum{}
+ activeTools[tc.Index] = acc
+ }
+ if tc.ID != "" {
+ acc.id = tc.ID
+ }
+ if tc.Function != nil {
+ if tc.Function.Name != "" {
+ acc.name = tc.Function.Name
+ }
+ if tc.Function.Arguments != "" {
+ acc.argsJSON.WriteString(tc.Function.Arguments)
+ }
+ }
+ }
+
+ if choice.FinishReason != nil {
+ finishReason = *choice.FinishReason
+ }
+ }
+
+ if err := scanner.Err(); err != nil {
+ return nil, fmt.Errorf("streaming read error: %w", err)
+ }
+
+ // Assemble tool calls from accumulated deltas
+ var toolCalls []ToolCall
+ for i := 0; i < len(activeTools); i++ {
+ acc, ok := activeTools[i]
+ if !ok {
+ continue
+ }
+ args := make(map[string]any)
+ raw := acc.argsJSON.String()
+ if raw != "" {
+ if err := json.Unmarshal([]byte(raw), &args); err != nil {
+ log.Printf("openai_compat stream: failed to decode tool call arguments for %q: %v", acc.name, err)
+ args["raw"] = raw
+ }
+ }
+ toolCalls = append(toolCalls, ToolCall{
+ ID: acc.id,
+ Name: acc.name,
+ Arguments: args,
+ })
+ }
+
+ if finishReason == "" {
+ finishReason = "stop"
+ }
+
+ return &LLMResponse{
+ Content: textContent.String(),
+ ToolCalls: toolCalls,
+ FinishReason: finishReason,
+ Usage: usage,
+ }, nil
+}
+
func normalizeModel(model, apiBase string) string {
before, after, ok := strings.Cut(model, "/")
if !ok {
diff --git a/pkg/providers/openai_compat/provider_test.go b/pkg/providers/openai_compat/provider_test.go
index efb03ccb8..ab632ccf3 100644
--- a/pkg/providers/openai_compat/provider_test.go
+++ b/pkg/providers/openai_compat/provider_test.go
@@ -610,6 +610,90 @@ func TestProvider_RequestTimeoutOverride(t *testing.T) {
}
}
+func TestProviderChat_ExtraBodyInjected(t *testing.T) {
+ var requestBody map[string]any
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+ resp := map[string]any{
+ "choices": []map[string]any{
+ {
+ "message": map[string]any{"content": "ok"},
+ "finish_reason": "stop",
+ },
+ },
+ }
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(resp)
+ }))
+ defer server.Close()
+
+ extraBody := map[string]any{"reasoning_split": true, "custom_field": "test"}
+ p := NewProvider("key", server.URL, "", WithExtraBody(extraBody))
+
+ _, err := p.Chat(
+ t.Context(),
+ []Message{{Role: "user", Content: "hi"}},
+ nil,
+ "minimax/abab7",
+ nil,
+ )
+ if err != nil {
+ t.Fatalf("Chat() error = %v", err)
+ }
+
+ if got, ok := requestBody["reasoning_split"]; !ok || got != true {
+ t.Fatalf("reasoning_split = %v, want true", got)
+ }
+ if got, ok := requestBody["custom_field"]; !ok || got != "test" {
+ t.Fatalf("custom_field = %v, want test", got)
+ }
+}
+
+func TestProviderChat_ExtraBodyOverridesOptions(t *testing.T) {
+ var requestBody map[string]any
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+ http.Error(w, err.Error(), http.StatusBadRequest)
+ return
+ }
+ resp := map[string]any{
+ "choices": []map[string]any{
+ {
+ "message": map[string]any{"content": "ok"},
+ "finish_reason": "stop",
+ },
+ },
+ }
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(resp)
+ }))
+ defer server.Close()
+
+ extraBody := map[string]any{"temperature": 0.9}
+ p := NewProvider("key", server.URL, "", WithExtraBody(extraBody))
+
+ _, err := p.Chat(
+ t.Context(),
+ []Message{{Role: "user", Content: "hi"}},
+ nil,
+ "gpt-4o",
+ map[string]any{"temperature": 0.5},
+ )
+ if err != nil {
+ t.Fatalf("Chat() error = %v", err)
+ }
+
+ // ExtraBody takes precedence over options since it is merged last.
+ if got := requestBody["temperature"]; got != float64(0.9) {
+ t.Fatalf("temperature = %v, want 0.9 (from extraBody, overriding options)", got)
+ }
+}
+
type roundTripperFunc func(*http.Request) (*http.Response, error)
func (f roundTripperFunc) RoundTrip(r *http.Request) (*http.Response, error) {
diff --git a/pkg/providers/types.go b/pkg/providers/types.go
index 1f28bc4ad..9a4d126a7 100644
--- a/pkg/providers/types.go
+++ b/pkg/providers/types.go
@@ -37,6 +37,20 @@ type StatefulProvider interface {
Close()
}
+// StreamingProvider is an optional interface for providers that support token streaming.
+// onChunk receives the accumulated text so far (not individual deltas).
+// The returned LLMResponse is the same complete response for compatibility with tool-call handling.
+type StreamingProvider interface {
+ ChatStream(
+ ctx context.Context,
+ messages []Message,
+ tools []ToolDefinition,
+ model string,
+ options map[string]any,
+ onChunk func(accumulated string),
+ ) (*LLMResponse, error)
+}
+
// ThinkingCapable is an optional interface for providers that support
// extended thinking (e.g. Anthropic). Used by the agent loop to warn
// when thinking_level is configured but the active provider cannot use it.
diff --git a/pkg/routing/route_test.go b/pkg/routing/route_test.go
index 8255db5f9..fdfc899f9 100644
--- a/pkg/routing/route_test.go
+++ b/pkg/routing/route_test.go
@@ -11,7 +11,7 @@ func testConfig(agents []config.AgentConfig, bindings []config.AgentBinding) *co
Agents: config.AgentsConfig{
Defaults: config.AgentDefaults{
Workspace: "/tmp/picoclaw-test",
- Model: "gpt-4",
+ ModelName: "gpt-4",
},
List: agents,
},
diff --git a/pkg/tools/registry.go b/pkg/tools/registry.go
index 0b0f51cc1..ed373a28f 100644
--- a/pkg/tools/registry.go
+++ b/pkg/tools/registry.go
@@ -384,3 +384,22 @@ func (r *ToolRegistry) GetSummaries() []string {
}
return summaries
}
+
+// GetAll returns all registered tools (both core and non-core with TTL > 0).
+// Used by SubTurn to inherit parent's tool set.
+func (r *ToolRegistry) GetAll() []Tool {
+ r.mu.RLock()
+ defer r.mu.RUnlock()
+
+ sorted := r.sortedToolNames()
+ tools := make([]Tool, 0, len(sorted))
+ for _, name := range sorted {
+ entry := r.tools[name]
+
+ // Include core tools and non-core tools with active TTL
+ if entry.IsCore || entry.TTL > 0 {
+ tools = append(tools, entry.Tool)
+ }
+ }
+ return tools
+}
diff --git a/pkg/tools/result.go b/pkg/tools/result.go
index cab833284..bf34b7bc6 100644
--- a/pkg/tools/result.go
+++ b/pkg/tools/result.go
@@ -1,6 +1,10 @@
package tools
-import "encoding/json"
+import (
+ "encoding/json"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
// ToolResult represents the structured return value from tool execution.
// It provides clear semantics for different types of results and supports
@@ -34,6 +38,11 @@ type ToolResult struct {
// Media contains media store refs produced by this tool.
// When non-empty, the agent will publish these as OutboundMediaMessage.
Media []string `json:"media,omitempty"`
+
+ // Messages holds the ephemeral session history after execution.
+ // Only populated by SubTurn executions; used by evaluator_optimizer
+ // to carry stateful worker context across evaluation iterations.
+ Messages []providers.Message `json:"-"`
}
// NewToolResult creates a basic ToolResult with content for the LLM.
diff --git a/pkg/tools/send_file.go b/pkg/tools/send_file.go
index a67bd4210..57b99a845 100644
--- a/pkg/tools/send_file.go
+++ b/pkg/tools/send_file.go
@@ -133,9 +133,10 @@ func (t *SendFileTool) Execute(ctx context.Context, args map[string]any) *ToolRe
scope := fmt.Sprintf("tool:send_file:%s:%s", channel, chatID)
ref, err := t.mediaStore.Store(resolved, media.MediaMeta{
- Filename: filename,
- ContentType: mediaType,
- Source: "tool:send_file",
+ Filename: filename,
+ ContentType: mediaType,
+ Source: "tool:send_file",
+ CleanupPolicy: media.CleanupPolicyForgetOnly,
}, scope)
if err != nil {
return ErrorResult(fmt.Sprintf("failed to register media: %v", err))
diff --git a/pkg/tools/send_file_test.go b/pkg/tools/send_file_test.go
index 6daaab31c..0a99e8028 100644
--- a/pkg/tools/send_file_test.go
+++ b/pkg/tools/send_file_test.go
@@ -104,6 +104,14 @@ func TestSendFileTool_Success(t *testing.T) {
if result.Media[0][:8] != "media://" {
t.Errorf("expected media:// ref, got %q", result.Media[0])
}
+
+ _, meta, err := store.ResolveWithMeta(result.Media[0])
+ if err != nil {
+ t.Fatalf("ResolveWithMeta failed: %v", err)
+ }
+ if meta.CleanupPolicy != media.CleanupPolicyForgetOnly {
+ t.Errorf("CleanupPolicy = %q, want %q", meta.CleanupPolicy, media.CleanupPolicyForgetOnly)
+ }
}
func TestSendFileTool_CustomFilename(t *testing.T) {
diff --git a/pkg/tools/spawn.go b/pkg/tools/spawn.go
index be40ffda2..d019d511a 100644
--- a/pkg/tools/spawn.go
+++ b/pkg/tools/spawn.go
@@ -7,7 +7,10 @@ import (
)
type SpawnTool struct {
- manager *SubagentManager
+ spawner SubTurnSpawner
+ defaultModel string
+ maxTokens int
+ temperature float64
allowlistCheck func(targetAgentID string) bool
}
@@ -15,9 +18,19 @@ type SpawnTool struct {
var _ AsyncExecutor = (*SpawnTool)(nil)
func NewSpawnTool(manager *SubagentManager) *SpawnTool {
- return &SpawnTool{
- manager: manager,
+ if manager == nil {
+ return &SpawnTool{}
}
+ return &SpawnTool{
+ defaultModel: manager.defaultModel,
+ maxTokens: manager.maxTokens,
+ temperature: manager.temperature,
+ }
+}
+
+// SetSpawner sets the SubTurnSpawner for direct sub-turn execution.
+func (t *SpawnTool) SetSpawner(spawner SubTurnSpawner) {
+ t.spawner = spawner
}
func (t *SpawnTool) Name() string {
@@ -59,11 +72,19 @@ func (t *SpawnTool) Execute(ctx context.Context, args map[string]any) *ToolResul
// ExecuteAsync implements AsyncExecutor. The callback is passed through to the
// subagent manager as a call parameter — never stored on the SpawnTool instance.
-func (t *SpawnTool) ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult {
+func (t *SpawnTool) ExecuteAsync(
+ ctx context.Context,
+ args map[string]any,
+ cb AsyncCallback,
+) *ToolResult {
return t.execute(ctx, args, cb)
}
-func (t *SpawnTool) execute(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult {
+func (t *SpawnTool) execute(
+ ctx context.Context,
+ args map[string]any,
+ cb AsyncCallback,
+) *ToolResult {
task, ok := args["task"].(string)
if !ok || strings.TrimSpace(task) == "" {
return ErrorResult("task is required and must be a non-empty string")
@@ -79,28 +100,53 @@ func (t *SpawnTool) execute(ctx context.Context, args map[string]any, cb AsyncCa
}
}
- if t.manager == nil {
- return ErrorResult("Subagent manager not configured")
+ // Build system prompt for spawned subagent
+ systemPrompt := fmt.Sprintf(
+ `You are a spawned subagent running in the background. Complete the given task independently and report back when done.
+
+Task: %s`,
+ task,
+ )
+
+ if label != "" {
+ systemPrompt = fmt.Sprintf(
+ `You are a spawned subagent labeled "%s" running in the background. Complete the given task independently and report back when done.
+
+Task: %s`,
+ label,
+ task,
+ )
}
- // Read channel/chatID from context (injected by registry).
- // Fall back to "cli"/"direct" for non-conversation callers (e.g., CLI, tests)
- // to preserve the same defaults as the original NewSpawnTool constructor.
- channel := ToolChannel(ctx)
- if channel == "" {
- channel = "cli"
- }
- chatID := ToolChatID(ctx)
- if chatID == "" {
- chatID = "direct"
+ // Use spawner if available (direct SpawnSubTurn call)
+ if t.spawner != nil {
+ // Launch async sub-turn in goroutine
+ go func() {
+ result, err := t.spawner.SpawnSubTurn(ctx, SubTurnConfig{
+ Model: t.defaultModel,
+ Tools: nil, // Will inherit from parent via context
+ SystemPrompt: systemPrompt,
+ MaxTokens: t.maxTokens,
+ Temperature: t.temperature,
+ Async: true, // Async execution
+ })
+ if err != nil {
+ result = ErrorResult(fmt.Sprintf("Spawn failed: %v", err)).WithError(err)
+ }
+
+ // Call callback if provided
+ if cb != nil {
+ cb(ctx, result)
+ }
+ }()
+
+ // Return immediate acknowledgment
+ if label != "" {
+ return AsyncResult(fmt.Sprintf("Spawned subagent '%s' for task: %s", label, task))
+ }
+ return AsyncResult(fmt.Sprintf("Spawned subagent for task: %s", task))
}
- // Pass callback to manager for async completion notification
- result, err := t.manager.Spawn(ctx, task, label, agentID, channel, chatID, cb)
- if err != nil {
- return ErrorResult(fmt.Sprintf("failed to spawn subagent: %v", err))
- }
-
- // Return AsyncResult since the task runs in background
- return AsyncResult(result)
+ // Fallback: spawner not configured
+ return ErrorResult("Subagent manager not configured")
}
diff --git a/pkg/tools/spawn_test.go b/pkg/tools/spawn_test.go
index 43223b8db..fda6bbd89 100644
--- a/pkg/tools/spawn_test.go
+++ b/pkg/tools/spawn_test.go
@@ -6,6 +6,24 @@ import (
"testing"
)
+// mockSpawner implements SubTurnSpawner for testing
+type mockSpawner struct{}
+
+func (m *mockSpawner) SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*ToolResult, error) {
+ // Extract task from system prompt for response
+ task := cfg.SystemPrompt
+ if strings.Contains(task, "Task: ") {
+ parts := strings.Split(task, "Task: ")
+ if len(parts) > 1 {
+ task = parts[1]
+ }
+ }
+ return &ToolResult{
+ ForLLM: "Task completed: " + task,
+ ForUser: "Task completed",
+ }, nil
+}
+
func TestSpawnTool_Execute_EmptyTask(t *testing.T) {
provider := &MockLLMProvider{}
manager := NewSubagentManager(provider, "test-model", "/tmp/test")
@@ -44,6 +62,7 @@ func TestSpawnTool_Execute_ValidTask(t *testing.T) {
provider := &MockLLMProvider{}
manager := NewSubagentManager(provider, "test-model", "/tmp/test")
tool := NewSpawnTool(manager)
+ tool.SetSpawner(&mockSpawner{})
ctx := context.Background()
args := map[string]any{
diff --git a/pkg/tools/subagent.go b/pkg/tools/subagent.go
index c37a5ee0f..9a1a8b802 100644
--- a/pkg/tools/subagent.go
+++ b/pkg/tools/subagent.go
@@ -4,11 +4,34 @@ import (
"context"
"fmt"
"sync"
+ "sync/atomic"
"time"
"github.com/sipeed/picoclaw/pkg/providers"
)
+// SubTurnSpawner is an interface for spawning sub-turns.
+// This avoids circular dependency between tools and agent packages.
+type SubTurnSpawner interface {
+ SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*ToolResult, error)
+}
+
+// SubTurnConfig holds configuration for spawning a sub-turn.
+type SubTurnConfig struct {
+ Model string
+ Tools []Tool
+ SystemPrompt string
+ MaxTokens int
+ Temperature float64
+ Async bool // true for async (spawn), false for sync (subagent)
+ Critical bool // continue running after parent finishes gracefully
+ Timeout time.Duration // 0 = use default (5 minutes)
+ MaxContextRunes int // 0 = auto, -1 = no limit, >0 = explicit limit
+ ActualSystemPrompt string
+ InitialMessages []providers.Message
+ InitialTokenBudget *atomic.Int64 // Shared token budget for team members; nil if no budget
+}
+
type SubagentTask struct {
ID string
Task string
@@ -21,6 +44,15 @@ type SubagentTask struct {
Created int64
}
+type SpawnSubTurnFunc func(
+ ctx context.Context,
+ task, label, agentID string,
+ tools *ToolRegistry,
+ maxTokens int,
+ temperature float64,
+ hasMaxTokens, hasTemperature bool,
+) (*ToolResult, error)
+
type SubagentManager struct {
tasks map[string]*SubagentTask
mu sync.RWMutex
@@ -34,6 +66,7 @@ type SubagentManager struct {
hasMaxTokens bool
hasTemperature bool
nextID int
+ spawner SpawnSubTurnFunc
}
func NewSubagentManager(
@@ -51,6 +84,12 @@ func NewSubagentManager(
}
}
+func (sm *SubagentManager) SetSpawner(spawner SpawnSubTurnFunc) {
+ sm.mu.Lock()
+ defer sm.mu.Unlock()
+ sm.spawner = spawner
+}
+
// SetLLMOptions sets max tokens and temperature for subagent LLM calls.
func (sm *SubagentManager) SetLLMOptions(maxTokens int, temperature float64) {
sm.mu.Lock()
@@ -108,22 +147,16 @@ func (sm *SubagentManager) Spawn(
return fmt.Sprintf("Spawned subagent for task: %s", task), nil
}
-func (sm *SubagentManager) runTask(ctx context.Context, task *SubagentTask, callback AsyncCallback) {
- // Build system prompt for subagent
- systemPrompt := `You are a subagent. Complete the given task independently and report the result.
-You have access to tools - use them as needed to complete your task.
-After completing the task, provide a clear summary of what was done.`
-
- messages := []providers.Message{
- {
- Role: "system",
- Content: systemPrompt,
- },
- {
- Role: "user",
- Content: task.Task,
- },
- }
+func (sm *SubagentManager) runTask(
+ ctx context.Context,
+ task *SubagentTask,
+ callback AsyncCallback,
+) {
+ task.Status = "running"
+ task.Created = time.Now().UnixMilli()
+ // TODO(eventbus): once subagents are modeled as child turns inside
+ // pkg/agent, emit SubTurnEnd and SubTurnResultDelivered from the parent
+ // AgentLoop instead of this legacy manager.
// Check if context is already canceled before starting
select {
@@ -136,8 +169,8 @@ After completing the task, provide a clear summary of what was done.`
default:
}
- // Run tool loop with access to tools
sm.mu.RLock()
+ spawner := sm.spawner
tools := sm.tools
maxIter := sm.maxIterations
maxTokens := sm.maxTokens
@@ -146,27 +179,69 @@ After completing the task, provide a clear summary of what was done.`
hasTemperature := sm.hasTemperature
sm.mu.RUnlock()
- var llmOptions map[string]any
- if hasMaxTokens || hasTemperature {
- llmOptions = map[string]any{}
- if hasMaxTokens {
- llmOptions["max_tokens"] = maxTokens
+ var result *ToolResult
+ var err error
+
+ if spawner != nil {
+ result, err = spawner(
+ ctx,
+ task.Task,
+ task.Label,
+ task.AgentID,
+ tools,
+ maxTokens,
+ temperature,
+ hasMaxTokens,
+ hasTemperature,
+ )
+ } else {
+ // Fallback to legacy RunToolLoop
+ systemPrompt := `You are a subagent. Complete the given task independently and report the result.
+You have access to tools - use them as needed to complete your task.
+After completing the task, provide a clear summary of what was done.`
+
+ messages := []providers.Message{
+ {Role: "system", Content: systemPrompt},
+ {Role: "user", Content: task.Task},
}
- if hasTemperature {
- llmOptions["temperature"] = temperature
+
+ var llmOptions map[string]any
+ if hasMaxTokens || hasTemperature {
+ llmOptions = map[string]any{}
+ if hasMaxTokens {
+ llmOptions["max_tokens"] = maxTokens
+ }
+ if hasTemperature {
+ llmOptions["temperature"] = temperature
+ }
+ }
+
+ var loopResult *ToolLoopResult
+ loopResult, err = RunToolLoop(ctx, ToolLoopConfig{
+ Provider: sm.provider,
+ Model: sm.defaultModel,
+ Tools: tools,
+ MaxIterations: maxIter,
+ LLMOptions: llmOptions,
+ }, messages, task.OriginChannel, task.OriginChatID)
+
+ if err == nil {
+ result = &ToolResult{
+ ForLLM: fmt.Sprintf(
+ "Subagent '%s' completed (iterations: %d): %s",
+ task.Label,
+ loopResult.Iterations,
+ loopResult.Content,
+ ),
+ ForUser: loopResult.Content,
+ Silent: false,
+ IsError: false,
+ Async: false,
+ }
}
}
- loopResult, err := RunToolLoop(ctx, ToolLoopConfig{
- Provider: sm.provider,
- Model: sm.defaultModel,
- Tools: tools,
- MaxIterations: maxIter,
- LLMOptions: llmOptions,
- }, messages, task.OriginChannel, task.OriginChatID)
-
sm.mu.Lock()
- var result *ToolResult
defer func() {
sm.mu.Unlock()
// Call callback if provided and result is set
@@ -193,19 +268,7 @@ After completing the task, provide a clear summary of what was done.`
}
} else {
task.Status = "completed"
- task.Result = loopResult.Content
- result = &ToolResult{
- ForLLM: fmt.Sprintf(
- "Subagent '%s' completed (iterations: %d): %s",
- task.Label,
- loopResult.Iterations,
- loopResult.Content,
- ),
- ForUser: loopResult.Content,
- Silent: false,
- IsError: false,
- Async: false,
- }
+ task.Result = result.ForLLM
}
}
@@ -253,16 +316,28 @@ func (sm *SubagentManager) ListTaskCopies() []SubagentTask {
}
// SubagentTool executes a subagent task synchronously and returns the result.
-// Unlike SpawnTool which runs tasks asynchronously, SubagentTool waits for completion
-// and returns the result directly in the ToolResult.
+// It directly calls SubTurnSpawner with Async=false for synchronous execution.
type SubagentTool struct {
- manager *SubagentManager
+ spawner SubTurnSpawner
+ defaultModel string
+ maxTokens int
+ temperature float64
}
func NewSubagentTool(manager *SubagentManager) *SubagentTool {
- return &SubagentTool{
- manager: manager,
+ if manager == nil {
+ return &SubagentTool{}
}
+ return &SubagentTool{
+ defaultModel: manager.defaultModel,
+ maxTokens: manager.maxTokens,
+ temperature: manager.temperature,
+ }
+}
+
+// SetSpawner sets the SubTurnSpawner for direct sub-turn execution.
+func (t *SubagentTool) SetSpawner(spawner SubTurnSpawner) {
+ t.spawner = spawner
}
func (t *SubagentTool) Name() string {
@@ -298,86 +373,64 @@ func (t *SubagentTool) Execute(ctx context.Context, args map[string]any) *ToolRe
label, _ := args["label"].(string)
- if t.manager == nil {
- return ErrorResult("Subagent manager not configured").WithError(fmt.Errorf("manager is nil"))
+ // Build system prompt for subagent
+ systemPrompt := fmt.Sprintf(
+ `You are a subagent. Complete the given task independently and provide a clear, concise result.
+
+Task: %s`,
+ task,
+ )
+
+ if label != "" {
+ systemPrompt = fmt.Sprintf(
+ `You are a subagent labeled "%s". Complete the given task independently and provide a clear, concise result.
+
+Task: %s`,
+ label,
+ task,
+ )
}
- // Build messages for subagent
- messages := []providers.Message{
- {
- Role: "system",
- Content: "You are a subagent. Complete the given task independently and provide a clear, concise result.",
- },
- {
- Role: "user",
- Content: task,
- },
- }
-
- // Use RunToolLoop to execute with tools (same as async SpawnTool)
- sm := t.manager
- sm.mu.RLock()
- tools := sm.tools
- maxIter := sm.maxIterations
- maxTokens := sm.maxTokens
- temperature := sm.temperature
- hasMaxTokens := sm.hasMaxTokens
- hasTemperature := sm.hasTemperature
- sm.mu.RUnlock()
-
- var llmOptions map[string]any
- if hasMaxTokens || hasTemperature {
- llmOptions = map[string]any{}
- if hasMaxTokens {
- llmOptions["max_tokens"] = maxTokens
+ // Use spawner if available (direct SpawnSubTurn call)
+ if t.spawner != nil {
+ result, err := t.spawner.SpawnSubTurn(ctx, SubTurnConfig{
+ Model: t.defaultModel,
+ Tools: nil, // Will inherit from parent via context
+ SystemPrompt: systemPrompt,
+ MaxTokens: t.maxTokens,
+ Temperature: t.temperature,
+ Async: false, // Synchronous execution
+ })
+ if err != nil {
+ return ErrorResult(fmt.Sprintf("Subagent execution failed: %v", err)).WithError(err)
}
- if hasTemperature {
- llmOptions["temperature"] = temperature
+
+ // Format result for display
+ userContent := result.ForLLM
+ if result.ForUser != "" {
+ userContent = result.ForUser
+ }
+ maxUserLen := 500
+ if len(userContent) > maxUserLen {
+ userContent = userContent[:maxUserLen] + "..."
+ }
+
+ labelStr := label
+ if labelStr == "" {
+ labelStr = "(unnamed)"
+ }
+ llmContent := fmt.Sprintf("Subagent task completed:\nLabel: %s\nResult: %s",
+ labelStr, result.ForLLM)
+
+ return &ToolResult{
+ ForLLM: llmContent,
+ ForUser: userContent,
+ Silent: false,
+ IsError: result.IsError,
+ Async: false,
}
}
- // Fall back to "cli"/"direct" for non-conversation callers (e.g., CLI, tests)
- // to preserve the same defaults as the original NewSubagentTool constructor.
- channel := ToolChannel(ctx)
- if channel == "" {
- channel = "cli"
- }
- chatID := ToolChatID(ctx)
- if chatID == "" {
- chatID = "direct"
- }
-
- loopResult, err := RunToolLoop(ctx, ToolLoopConfig{
- Provider: sm.provider,
- Model: sm.defaultModel,
- Tools: tools,
- MaxIterations: maxIter,
- LLMOptions: llmOptions,
- }, messages, channel, chatID)
- if err != nil {
- return ErrorResult(fmt.Sprintf("Subagent execution failed: %v", err)).WithError(err)
- }
-
- // ForUser: Brief summary for user (truncated if too long)
- userContent := loopResult.Content
- maxUserLen := 500
- if len(userContent) > maxUserLen {
- userContent = userContent[:maxUserLen] + "..."
- }
-
- // ForLLM: Full execution details
- labelStr := label
- if labelStr == "" {
- labelStr = "(unnamed)"
- }
- llmContent := fmt.Sprintf("Subagent task completed:\nLabel: %s\nIterations: %d\nResult: %s",
- labelStr, loopResult.Iterations, loopResult.Content)
-
- return &ToolResult{
- ForLLM: llmContent,
- ForUser: userContent,
- Silent: false,
- IsError: false,
- Async: false,
- }
+ // Fallback: spawner not configured
+ return ErrorResult("Subagent manager not configured").WithError(fmt.Errorf("spawner not set"))
}
diff --git a/pkg/tools/subagent_tool_test.go b/pkg/tools/subagent_tool_test.go
index 4b6f130a5..89ac7d4b5 100644
--- a/pkg/tools/subagent_tool_test.go
+++ b/pkg/tools/subagent_tool_test.go
@@ -48,24 +48,19 @@ func TestSubagentManager_SetLLMOptions_AppliesToRunToolLoop(t *testing.T) {
provider := &MockLLMProvider{}
manager := NewSubagentManager(provider, "test-model", "/tmp/test")
manager.SetLLMOptions(2048, 0.6)
- tool := NewSubagentTool(manager)
- ctx := WithToolContext(context.Background(), "cli", "direct")
- args := map[string]any{"task": "Do something"}
- result := tool.Execute(ctx, args)
-
- if result == nil || result.IsError {
- t.Fatalf("Expected successful result, got: %+v", result)
+ // Verify options are set on manager
+ if manager.maxTokens != 2048 {
+ t.Errorf("manager.maxTokens = %d, want 2048", manager.maxTokens)
}
-
- if provider.lastOptions == nil {
- t.Fatal("Expected LLM options to be passed, got nil")
+ if manager.temperature != 0.6 {
+ t.Errorf("manager.temperature = %f, want 0.6", manager.temperature)
}
- if provider.lastOptions["max_tokens"] != 2048 {
- t.Fatalf("max_tokens = %v, want %d", provider.lastOptions["max_tokens"], 2048)
+ if !manager.hasMaxTokens {
+ t.Error("manager.hasMaxTokens should be true")
}
- if provider.lastOptions["temperature"] != 0.6 {
- t.Fatalf("temperature = %v, want %v", provider.lastOptions["temperature"], 0.6)
+ if !manager.hasTemperature {
+ t.Error("manager.hasTemperature should be true")
}
}
@@ -150,6 +145,7 @@ func TestSubagentTool_Execute_Success(t *testing.T) {
provider := &MockLLMProvider{}
manager := NewSubagentManager(provider, "test-model", "/tmp/test")
tool := NewSubagentTool(manager)
+ tool.SetSpawner(&mockSpawner{})
ctx := WithToolContext(context.Background(), "telegram", "chat-123")
args := map[string]any{
@@ -204,6 +200,7 @@ func TestSubagentTool_Execute_NoLabel(t *testing.T) {
provider := &MockLLMProvider{}
manager := NewSubagentManager(provider, "test-model", "/tmp/test")
tool := NewSubagentTool(manager)
+ tool.SetSpawner(&mockSpawner{})
ctx := context.Background()
args := map[string]any{
@@ -277,6 +274,7 @@ func TestSubagentTool_Execute_ContextPassing(t *testing.T) {
provider := &MockLLMProvider{}
manager := NewSubagentManager(provider, "test-model", "/tmp/test")
tool := NewSubagentTool(manager)
+ tool.SetSpawner(&mockSpawner{})
channel := "test-channel"
chatID := "test-chat"
@@ -302,6 +300,7 @@ func TestSubagentTool_ForUserTruncation(t *testing.T) {
provider := &MockLLMProvider{}
manager := NewSubagentManager(provider, "test-model", "/tmp/test")
tool := NewSubagentTool(manager)
+ tool.SetSpawner(&mockSpawner{})
ctx := context.Background()
diff --git a/pkg/tools/web.go b/pkg/tools/web.go
index 42cf79578..7ff724802 100644
--- a/pkg/tools/web.go
+++ b/pkg/tools/web.go
@@ -613,39 +613,124 @@ func (p *GLMSearchProvider) Search(ctx context.Context, query string, count int)
return strings.Join(lines, "\n"), nil
}
+type BaiduSearchProvider struct {
+ apiKey string
+ baseURL string
+ proxy string
+ client *http.Client
+}
+
+func (p *BaiduSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
+ searchURL := p.baseURL
+ if searchURL == "" {
+ searchURL = "https://qianfan.baidubce.com/v2/ai_search/web_search"
+ }
+
+ payload := map[string]any{
+ "messages": []map[string]string{
+ {
+ "role": "user",
+ "content": query,
+ },
+ },
+ "search_source": "baidu_search_v2",
+ "resource_type_filter": []map[string]any{{"type": "web", "top_k": count}},
+ }
+
+ bodyBytes, err := json.Marshal(payload)
+ if err != nil {
+ return "", fmt.Errorf("failed to marshal payload: %w", err)
+ }
+
+ req, err := http.NewRequestWithContext(ctx, "POST", searchURL, bytes.NewReader(bodyBytes))
+ if err != nil {
+ return "", fmt.Errorf("failed to create request: %w", err)
+ }
+
+ req.Header.Set("Content-Type", "application/json")
+ req.Header.Set("Authorization", "Bearer "+p.apiKey)
+
+ resp, err := p.client.Do(req)
+ if err != nil {
+ return "", fmt.Errorf("baidu search request failed: %w", err)
+ }
+ defer resp.Body.Close()
+
+ body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+ if err != nil {
+ return "", fmt.Errorf("failed to read response: %w", err)
+ }
+
+ if resp.StatusCode != http.StatusOK {
+ return "", fmt.Errorf("baidu search API error %d: %s", resp.StatusCode, string(body))
+ }
+
+ var result struct {
+ References []struct {
+ Title string `json:"title"`
+ URL string `json:"url"`
+ Content string `json:"content"`
+ } `json:"references"`
+ }
+ if err := json.Unmarshal(body, &result); err != nil {
+ return "", fmt.Errorf("failed to parse response: %w", err)
+ }
+
+ if len(result.References) == 0 {
+ return fmt.Sprintf("No results for: %s", query), nil
+ }
+
+ lines := []string{fmt.Sprintf("Results for: %s (via Baidu Search)", query)}
+ for i, item := range result.References {
+ if i >= count {
+ break
+ }
+ lines = append(lines, fmt.Sprintf("%d. %s\n %s", i+1, item.Title, item.URL))
+ if item.Content != "" {
+ lines = append(lines, fmt.Sprintf(" %s", item.Content))
+ }
+ }
+
+ return strings.Join(lines, "\n"), nil
+}
+
type WebSearchTool struct {
provider SearchProvider
maxResults int
}
type WebSearchToolOptions struct {
- BraveAPIKeys []string
- BraveMaxResults int
- BraveEnabled bool
- TavilyAPIKeys []string
- TavilyBaseURL string
- TavilyMaxResults int
- TavilyEnabled bool
- DuckDuckGoMaxResults int
- DuckDuckGoEnabled bool
- PerplexityAPIKeys []string
- PerplexityMaxResults int
- PerplexityEnabled bool
- SearXNGBaseURL string
- SearXNGMaxResults int
- SearXNGEnabled bool
- GLMSearchAPIKey string
- GLMSearchBaseURL string
- GLMSearchEngine string
- GLMSearchMaxResults int
- GLMSearchEnabled bool
- Proxy string
+ BraveAPIKeys []string
+ BraveMaxResults int
+ BraveEnabled bool
+ TavilyAPIKeys []string
+ TavilyBaseURL string
+ TavilyMaxResults int
+ TavilyEnabled bool
+ DuckDuckGoMaxResults int
+ DuckDuckGoEnabled bool
+ PerplexityAPIKeys []string
+ PerplexityMaxResults int
+ PerplexityEnabled bool
+ SearXNGBaseURL string
+ SearXNGMaxResults int
+ SearXNGEnabled bool
+ GLMSearchAPIKey string
+ GLMSearchBaseURL string
+ GLMSearchEngine string
+ GLMSearchMaxResults int
+ GLMSearchEnabled bool
+ BaiduSearchAPIKey string
+ BaiduSearchBaseURL string
+ BaiduSearchMaxResults int
+ BaiduSearchEnabled bool
+ Proxy string
}
func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) {
var provider SearchProvider
maxResults := 5
- // Priority: Perplexity > Brave > SearXNG > Tavily > DuckDuckGo > GLM Search
+ // Priority: Perplexity > Brave > SearXNG > Tavily > DuckDuckGo > Baidu Search > GLM Search
if opts.PerplexityEnabled && len(opts.PerplexityAPIKeys) > 0 {
client, err := utils.CreateHTTPClient(opts.Proxy, perplexityTimeout)
if err != nil {
@@ -696,6 +781,20 @@ func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) {
if opts.DuckDuckGoMaxResults > 0 {
maxResults = opts.DuckDuckGoMaxResults
}
+ } else if opts.BaiduSearchEnabled && opts.BaiduSearchAPIKey != "" {
+ client, err := utils.CreateHTTPClient(opts.Proxy, perplexityTimeout)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create HTTP client for Baidu Search: %w", err)
+ }
+ provider = &BaiduSearchProvider{
+ apiKey: opts.BaiduSearchAPIKey,
+ baseURL: opts.BaiduSearchBaseURL,
+ proxy: opts.Proxy,
+ client: client,
+ }
+ if opts.BaiduSearchMaxResults > 0 {
+ maxResults = opts.BaiduSearchMaxResults
+ }
} else if opts.GLMSearchEnabled && opts.GLMSearchAPIKey != "" {
client, err := utils.CreateHTTPClient(opts.Proxy, searchTimeout)
if err != nil {
diff --git a/pkg/utils/context.go b/pkg/utils/context.go
new file mode 100644
index 000000000..2007de9a3
--- /dev/null
+++ b/pkg/utils/context.go
@@ -0,0 +1,173 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package utils
+
+import (
+ "encoding/json"
+ "fmt"
+ "unicode/utf8"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// CalculateDefaultMaxContextRunes computes a default context limit based on the model's context window.
+// Strategy: Use 75% of the context window and convert to rune estimate.
+//
+// Token-to-rune conversion ratios (conservative estimates):
+// - English: ~4 chars per token
+// - Chinese: ~1.5-2 chars per token
+// - Mixed: ~3 chars per token (used here for safety)
+func CalculateDefaultMaxContextRunes(contextWindow int) int {
+ if contextWindow <= 0 {
+ // Conservative fallback when context window is unknown
+ return 8000 // ~2000 tokens
+ }
+
+ // Use 75% of context window to leave headroom
+ targetTokens := int(float64(contextWindow) * 0.75)
+
+ // Convert tokens to runes using conservative ratio
+ const avgCharsPerToken = 3
+ return targetTokens * avgCharsPerToken
+}
+
+// ResolveMaxContextRunes determines the final MaxContextRunes value to use.
+// Priority: explicit config > auto-calculate > conservative default
+func ResolveMaxContextRunes(configValue, contextWindow int) int {
+ switch {
+ case configValue > 0:
+ // Explicitly configured, use as-is
+ return configValue
+ case configValue == -1:
+ // Explicitly disabled
+ return -1
+ default:
+ // 0 or unset: auto-calculate
+ return CalculateDefaultMaxContextRunes(contextWindow)
+ }
+}
+
+// MeasureContextRunes calculates the total rune count of a message list.
+// Includes content, reasoning content, and estimates for tool calls.
+func MeasureContextRunes(messages []providers.Message) int {
+ totalRunes := 0
+ for _, msg := range messages {
+ totalRunes += utf8.RuneCountInString(msg.Content)
+ totalRunes += utf8.RuneCountInString(msg.ReasoningContent)
+
+ // Tool calls: serialize to JSON and count
+ if len(msg.ToolCalls) > 0 {
+ for _, tc := range msg.ToolCalls {
+ totalRunes += utf8.RuneCountInString(tc.Name)
+ // Arguments: serialize and count
+ if argsJSON, err := json.Marshal(tc.Arguments); err == nil {
+ totalRunes += utf8.RuneCount(argsJSON)
+ } else {
+ // Fallback estimate if serialization fails
+ totalRunes += 100
+ }
+ }
+ }
+
+ // ToolCallID
+ totalRunes += utf8.RuneCountInString(msg.ToolCallID)
+ }
+ return totalRunes
+}
+
+// TruncateContextSmart intelligently truncates message history to fit within maxRunes.
+//
+// Strategy:
+// 1. Always preserve system messages (they define the agent's behavior)
+// 2. Keep the most recent messages (they contain current context)
+// 3. Drop older middle messages when necessary
+// 4. Insert a truncation notice to inform the LLM
+//
+// Returns the truncated message list.
+func TruncateContextSmart(messages []providers.Message, maxRunes int) []providers.Message {
+ if len(messages) == 0 {
+ return messages
+ }
+
+ // Separate system messages from others
+ var systemMsgs []providers.Message
+ var otherMsgs []providers.Message
+
+ for _, msg := range messages {
+ if msg.Role == "system" {
+ systemMsgs = append(systemMsgs, msg)
+ } else {
+ otherMsgs = append(otherMsgs, msg)
+ }
+ }
+
+ // Calculate system message size
+ systemRunes := 0
+ for _, msg := range systemMsgs {
+ systemRunes += utf8.RuneCountInString(msg.Content)
+ systemRunes += utf8.RuneCountInString(msg.ReasoningContent)
+ }
+
+ // Reserve space for truncation notice (estimate ~80 runes)
+ const truncationNoticeEstimate = 80
+
+ // Allocate remaining space for other messages
+ remainingRunes := maxRunes - systemRunes - truncationNoticeEstimate
+ if remainingRunes <= 0 {
+ // System messages already exceed limit - return only system messages
+ return systemMsgs
+ }
+
+ // Collect recent messages in reverse order until we hit the limit
+ var keptMsgs []providers.Message
+ currentRunes := 0
+
+ for i := len(otherMsgs) - 1; i >= 0; i-- {
+ msg := otherMsgs[i]
+ msgRunes := utf8.RuneCountInString(msg.Content) +
+ utf8.RuneCountInString(msg.ReasoningContent)
+
+ // Estimate tool call size
+ if len(msg.ToolCalls) > 0 {
+ for _, tc := range msg.ToolCalls {
+ msgRunes += utf8.RuneCountInString(tc.Name)
+ if argsJSON, err := json.Marshal(tc.Arguments); err == nil {
+ msgRunes += utf8.RuneCount(argsJSON)
+ } else {
+ msgRunes += 100
+ }
+ }
+ }
+ msgRunes += utf8.RuneCountInString(msg.ToolCallID)
+
+ if currentRunes+msgRunes > remainingRunes {
+ // Would exceed limit, stop collecting
+ break
+ }
+
+ // Prepend to maintain chronological order
+ keptMsgs = append([]providers.Message{msg}, keptMsgs...)
+ currentRunes += msgRunes
+ }
+
+ // If we dropped messages, add a truncation notice
+ result := systemMsgs
+ if len(keptMsgs) < len(otherMsgs) {
+ droppedCount := len(otherMsgs) - len(keptMsgs)
+ truncationNotice := providers.Message{
+ Role: "system",
+ Content: fmt.Sprintf(
+ "[Context truncated: %d earlier messages omitted to stay within context limits]",
+ droppedCount,
+ ),
+ }
+ result = append(result, truncationNotice)
+ }
+
+ result = append(result, keptMsgs...)
+ return result
+}
diff --git a/pkg/utils/context_test.go b/pkg/utils/context_test.go
new file mode 100644
index 000000000..450a29249
--- /dev/null
+++ b/pkg/utils/context_test.go
@@ -0,0 +1,450 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package utils
+
+import (
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func TestCalculateDefaultMaxContextRunes(t *testing.T) {
+ tests := []struct {
+ name string
+ contextWindow int
+ want int
+ }{
+ {
+ name: "zero context window uses fallback",
+ contextWindow: 0,
+ want: 8000,
+ },
+ {
+ name: "negative context window uses fallback",
+ contextWindow: -1,
+ want: 8000,
+ },
+ {
+ name: "small context window (4k tokens)",
+ contextWindow: 4000,
+ want: 9000, // 4000 * 0.75 * 3 = 9000
+ },
+ {
+ name: "medium context window (128k tokens)",
+ contextWindow: 128000,
+ want: 288000, // 128000 * 0.75 * 3 = 288000
+ },
+ {
+ name: "large context window (1M tokens)",
+ contextWindow: 1000000,
+ want: 2250000, // 1000000 * 0.75 * 3 = 2250000
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := CalculateDefaultMaxContextRunes(tt.contextWindow)
+ if got != tt.want {
+ t.Errorf("CalculateDefaultMaxContextRunes(%d) = %d, want %d",
+ tt.contextWindow, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestResolveMaxContextRunes(t *testing.T) {
+ tests := []struct {
+ name string
+ configValue int
+ contextWindow int
+ want int
+ }{
+ {
+ name: "explicit positive value",
+ configValue: 12000,
+ contextWindow: 4000,
+ want: 12000,
+ },
+ {
+ name: "explicit disable (-1)",
+ configValue: -1,
+ contextWindow: 4000,
+ want: -1,
+ },
+ {
+ name: "zero uses auto-calculate",
+ configValue: 0,
+ contextWindow: 4000,
+ want: 9000, // 4000 * 0.75 * 3
+ },
+ {
+ name: "unset (0) with unknown context window",
+ configValue: 0,
+ contextWindow: 0,
+ want: 8000, // fallback
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := ResolveMaxContextRunes(tt.configValue, tt.contextWindow)
+ if got != tt.want {
+ t.Errorf("ResolveMaxContextRunes(%d, %d) = %d, want %d",
+ tt.configValue, tt.contextWindow, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestMeasureContextRunes(t *testing.T) {
+ tests := []struct {
+ name string
+ messages []providers.Message
+ want int
+ }{
+ {
+ name: "empty messages",
+ messages: []providers.Message{},
+ want: 0,
+ },
+ {
+ name: "single simple message",
+ messages: []providers.Message{
+ {Role: "user", Content: "Hello"},
+ },
+ want: 5, // "Hello" = 5 runes
+ },
+ {
+ name: "message with reasoning",
+ messages: []providers.Message{
+ {
+ Role: "assistant",
+ Content: "Answer",
+ ReasoningContent: "Thinking",
+ },
+ },
+ want: 14, // "Answer" (6) + "Thinking" (8) = 14
+ },
+ {
+ name: "message with tool call",
+ messages: []providers.Message{
+ {
+ Role: "assistant",
+ Content: "Using tool",
+ ToolCalls: []providers.ToolCall{
+ {
+ Name: "test_tool",
+ Arguments: map[string]any{"key": "value"},
+ },
+ },
+ },
+ },
+ want: 10 + 9 + 15, // "Using tool" + "test_tool" + {"key":"value"}
+ },
+ {
+ name: "multiple messages",
+ messages: []providers.Message{
+ {Role: "system", Content: "You are helpful"},
+ {Role: "user", Content: "Hi"},
+ {Role: "assistant", Content: "Hello!"},
+ },
+ want: 15 + 2 + 6, // 15 + 2 + 6 = 23
+ },
+ {
+ name: "unicode characters",
+ messages: []providers.Message{
+ {Role: "user", Content: "\u4f60\u597d\u4e16\u754c"}, // 4 Chinese characters
+ },
+ want: 4,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := MeasureContextRunes(tt.messages)
+ if got != tt.want {
+ t.Errorf("MeasureContextRunes() = %d, want %d", got, tt.want)
+ }
+ })
+ }
+}
+
+func TestTruncateContextSmart(t *testing.T) {
+ tests := []struct {
+ name string
+ messages []providers.Message
+ maxRunes int
+ wantLen int
+ wantHas []string // Content strings that should be present
+ wantNot []string // Content strings that should be absent
+ }{
+ {
+ name: "empty messages",
+ messages: []providers.Message{},
+ maxRunes: 100,
+ wantLen: 0,
+ },
+ {
+ name: "no truncation needed",
+ messages: []providers.Message{
+ {Role: "system", Content: "System"},
+ {Role: "user", Content: "Hello"},
+ },
+ maxRunes: 100,
+ wantLen: 2,
+ wantHas: []string{"System", "Hello"},
+ },
+ {
+ name: "truncate when limit is tight",
+ messages: []providers.Message{
+ {Role: "system", Content: "System"},
+ {Role: "user", Content: "Message 1 with some content here"},
+ {Role: "assistant", Content: "Response 1 with some content here"},
+ {Role: "user", Content: "Message 2 with some content here"},
+ {Role: "assistant", Content: "Response 2 with some content here"},
+ {Role: "user", Content: "Latest"},
+ },
+ maxRunes: 120, // Tight limit to force truncation
+ wantLen: -1, // Don't check exact length, just verify truncation occurred
+ wantHas: []string{"System", "Latest"},
+ wantNot: []string{"Message 1", "Response 1"},
+ },
+ {
+ name: "system messages exceed limit",
+ messages: []providers.Message{
+ {Role: "system", Content: "Very long system message"},
+ {Role: "user", Content: "User message"},
+ },
+ maxRunes: 10, // Less than system message
+ wantLen: 1, // Only system message
+ wantHas: []string{"Very long system message"},
+ wantNot: []string{"User message"},
+ },
+ {
+ name: "preserve multiple system messages",
+ messages: []providers.Message{
+ {Role: "system", Content: "Sys1"},
+ {Role: "system", Content: "Sys2"},
+ {Role: "user", Content: "Old"},
+ {Role: "user", Content: "New"},
+ },
+ maxRunes: 200, // Generous limit
+ wantLen: 4, // Both system + truncation notice + new
+ wantHas: []string{"Sys1", "Sys2", "New"},
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := TruncateContextSmart(tt.messages, tt.maxRunes)
+
+ if tt.wantLen >= 0 && len(got) != tt.wantLen {
+ t.Errorf("TruncateContextSmart() returned %d messages, want %d",
+ len(got), tt.wantLen)
+ }
+
+ // Check for expected content
+ allContent := ""
+ for _, msg := range got {
+ allContent += msg.Content + " "
+ }
+
+ for _, want := range tt.wantHas {
+ found := false
+ for _, msg := range got {
+ if msg.Content == want || containsSubstring(msg.Content, want) {
+ found = true
+ break
+ }
+ }
+ if !found {
+ t.Errorf("Expected content %q not found in truncated messages", want)
+ }
+ }
+
+ for _, notWant := range tt.wantNot {
+ for _, msg := range got {
+ if containsSubstring(msg.Content, notWant) {
+ t.Errorf("Unexpected content %q found in truncated messages", notWant)
+ }
+ }
+ }
+ })
+ }
+}
+
+func containsSubstring(s, substr string) bool {
+ return len(s) >= len(substr) && findSubstring(s, substr)
+}
+
+func findSubstring(s, substr string) bool {
+ for i := 0; i <= len(s)-len(substr); i++ {
+ if s[i:i+len(substr)] == substr {
+ return true
+ }
+ }
+ return false
+}
+
+// TestSubTurnConfigMaxContextRunes verifies that MaxContextRunes configuration
+// is properly integrated into the SubTurn execution flow.
+func TestSubTurnConfigMaxContextRunes(t *testing.T) {
+ tests := []struct {
+ name string
+ maxContextRunes int
+ contextWindow int
+ wantResolved int
+ }{
+ {
+ name: "default (0) auto-calculates from context window",
+ maxContextRunes: 0,
+ contextWindow: 4000,
+ wantResolved: 9000, // 4000 * 0.75 * 3
+ },
+ {
+ name: "explicit value is used",
+ maxContextRunes: 12000,
+ contextWindow: 4000,
+ wantResolved: 12000,
+ },
+ {
+ name: "disabled (-1) returns -1",
+ maxContextRunes: -1,
+ contextWindow: 4000,
+ wantResolved: -1,
+ },
+ {
+ name: "fallback when context window unknown",
+ maxContextRunes: 0,
+ contextWindow: 0,
+ wantResolved: 8000, // conservative fallback
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := ResolveMaxContextRunes(tt.maxContextRunes, tt.contextWindow)
+ if got != tt.wantResolved {
+ t.Errorf("utils.ResolveMaxContextRunes(%d, %d) = %d, want %d",
+ tt.maxContextRunes, tt.contextWindow, got, tt.wantResolved)
+ }
+ })
+ }
+}
+
+// TestContextTruncationFlow verifies the complete context truncation flow:
+// 1. Messages accumulate beyond soft limit
+// 2. Truncation is triggered
+// 3. System messages are preserved
+// 4. Recent messages are kept
+func TestContextTruncationFlow(t *testing.T) {
+ // Build a message history that exceeds the limit
+ messages := []providers.Message{
+ {Role: "system", Content: "You are a helpful assistant"}, // ~27 runes
+ {Role: "user", Content: "First question"}, // ~14 runes
+ {Role: "assistant", Content: "First answer"}, // ~12 runes
+ {Role: "user", Content: "Second question"}, // ~15 runes
+ {Role: "assistant", Content: "Second answer"}, // ~13 runes
+ {Role: "user", Content: "Third question"}, // ~14 runes
+ {Role: "assistant", Content: "Third answer"}, // ~12 runes
+ {Role: "user", Content: "Latest question"}, // ~15 runes
+ }
+
+ // Total: ~122 runes
+ totalRunes := MeasureContextRunes(messages)
+ if totalRunes < 100 {
+ t.Errorf("Expected total runes > 100, got %d", totalRunes)
+ }
+
+ // Set limit to 150 runes - should force truncation of old messages
+ // but preserve system + truncation notice + recent messages
+ maxRunes := 150
+ truncated := TruncateContextSmart(messages, maxRunes)
+
+ // Verify truncation occurred
+ if len(truncated) >= len(messages) {
+ t.Errorf("Expected truncation, but got %d messages (original: %d)",
+ len(truncated), len(messages))
+ }
+
+ // Verify system message is preserved
+ foundSystem := false
+ for _, msg := range truncated {
+ if msg.Role == "system" && msg.Content == "You are a helpful assistant" {
+ foundSystem = true
+ break
+ }
+ }
+ if !foundSystem {
+ t.Error("System message was not preserved after truncation")
+ }
+
+ // Verify latest message is preserved
+ foundLatest := false
+ for _, msg := range truncated {
+ if msg.Content == "Latest question" {
+ foundLatest = true
+ break
+ }
+ }
+ if !foundLatest {
+ t.Error("Latest message was not preserved after truncation")
+ }
+
+ // Verify truncation notice is present
+ foundNotice := false
+ for _, msg := range truncated {
+ if msg.Role == "system" && containsSubstring(msg.Content, "truncated") {
+ foundNotice = true
+ break
+ }
+ }
+ if !foundNotice {
+ t.Error("Truncation notice was not added")
+ }
+
+ // Verify result is within limit (with some tolerance for estimation)
+ resultRunes := MeasureContextRunes(truncated)
+ if resultRunes > maxRunes+20 { // Allow 20 rune tolerance
+ t.Errorf("Truncated context (%d runes) significantly exceeds limit (%d runes)",
+ resultRunes, maxRunes)
+ }
+}
+
+// TestContextTruncationPreservesToolCalls verifies that tool calls are
+// properly handled during context truncation.
+func TestContextTruncationPreservesToolCalls(t *testing.T) {
+ messages := []providers.Message{
+ {Role: "system", Content: "System"},
+ {Role: "user", Content: "Old message that should be dropped"},
+ {
+ Role: "assistant",
+ Content: "Recent tool use",
+ ToolCalls: []providers.ToolCall{
+ {
+ Name: "important_tool",
+ Arguments: map[string]any{"key": "value"},
+ },
+ },
+ },
+ }
+
+ // Set a generous limit that should keep the tool call message
+ maxRunes := 200
+ truncated := TruncateContextSmart(messages, maxRunes)
+
+ // Verify tool call message is preserved
+ foundToolCall := false
+ for _, msg := range truncated {
+ if len(msg.ToolCalls) > 0 && msg.ToolCalls[0].Name == "important_tool" {
+ foundToolCall = true
+ break
+ }
+ }
+ if !foundToolCall {
+ t.Error("Tool call message was not preserved during truncation")
+ }
+}
diff --git a/pkg/utils/media.go b/pkg/utils/media.go
index 82e9f5f45..823ca155e 100644
--- a/pkg/utils/media.go
+++ b/pkg/utils/media.go
@@ -1,6 +1,7 @@
package utils
import (
+ "fmt"
"io"
"net/http"
"net/url"
@@ -15,9 +16,21 @@ import (
"github.com/sipeed/picoclaw/pkg/media"
)
+var audioExtensions = []string{".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma"}
+
+func AudioFormat(path string) (string, error) {
+ ext := strings.ToLower(filepath.Ext(path))
+ for _, supportedExt := range audioExtensions {
+ if ext == supportedExt {
+ return strings.TrimPrefix(ext, "."), nil
+ }
+ }
+
+ return "", fmt.Errorf("unsupported audio format for %q", path)
+}
+
// IsAudioFile checks if a file is an audio file based on its filename extension and content type.
func IsAudioFile(filename, contentType string) bool {
- audioExtensions := []string{".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma"}
audioTypes := []string{"audio/", "application/ogg", "application/x-ogg"}
for _, ext := range audioExtensions {
diff --git a/pkg/voice/audio_model_transcriber.go b/pkg/voice/audio_model_transcriber.go
new file mode 100644
index 000000000..f3ca81961
--- /dev/null
+++ b/pkg/voice/audio_model_transcriber.go
@@ -0,0 +1,95 @@
+package voice
+
+import (
+ "context"
+ "encoding/base64"
+ "fmt"
+ "os"
+ "strings"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/logger"
+ "github.com/sipeed/picoclaw/pkg/providers"
+ "github.com/sipeed/picoclaw/pkg/utils"
+)
+
+type AudioModelTranscriber struct {
+ provider providers.LLMProvider
+ modelID string
+ prompt string
+}
+
+const (
+ defaultTranscriptionPrompt = "Transcribe this audio."
+)
+
+func NewAudioModelTranscriber(modelCfg *config.ModelConfig) *AudioModelTranscriber {
+ if modelCfg == nil {
+ return nil
+ }
+
+ logger.DebugCF("voice", "Creating audio model transcriber", map[string]any{
+ "has_api_key": modelCfg.APIKey() != "",
+ "api_base": modelCfg.APIBase,
+ "model": modelCfg.Model,
+ })
+
+ provider, modelID, err := providers.CreateProviderFromConfig(modelCfg)
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to create audio model provider", map[string]any{"error": err})
+ return nil
+ }
+
+ return &AudioModelTranscriber{
+ provider: provider,
+ modelID: modelID,
+ prompt: defaultTranscriptionPrompt,
+ }
+}
+
+func (t *AudioModelTranscriber) Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error) {
+ logger.InfoCF("voice", "Starting audio model transcription", map[string]any{
+ "audio_file": audioFilePath,
+ "model": t.modelID,
+ })
+
+ audioBytes, err := os.ReadFile(audioFilePath)
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to read audio file", map[string]any{"path": audioFilePath, "error": err})
+ return nil, fmt.Errorf("failed to read audio file: %w", err)
+ }
+
+ format, err := utils.AudioFormat(audioFilePath)
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to detect audio format", map[string]any{"path": audioFilePath, "error": err})
+ return nil, err
+ }
+
+ resp, err := t.provider.Chat(ctx, []providers.Message{
+ {
+ Role: "user",
+ Content: t.prompt,
+ Media: []string{
+ fmt.Sprintf("data:audio/%s;base64,%s", format, base64.StdEncoding.EncodeToString(audioBytes)),
+ },
+ },
+ }, nil, t.modelID, map[string]any{
+ "temperature": 0,
+ })
+ if err != nil {
+ logger.ErrorCF("voice", "Audio model transcription request failed", map[string]any{"error": err})
+ return nil, fmt.Errorf("transcription request failed: %w", err)
+ }
+
+ text := strings.TrimSpace(resp.Content)
+ logger.InfoCF("voice", "Audio model transcription completed successfully", map[string]any{
+ "text_length": len(text),
+ "transcription_preview": utils.Truncate(text, 50),
+ })
+
+ return &TranscriptionResponse{Text: text}, nil
+}
+
+func (t *AudioModelTranscriber) Name() string {
+ return "audio-model"
+}
diff --git a/pkg/voice/audio_model_transcriber_test.go b/pkg/voice/audio_model_transcriber_test.go
new file mode 100644
index 000000000..c33e3bf97
--- /dev/null
+++ b/pkg/voice/audio_model_transcriber_test.go
@@ -0,0 +1,203 @@
+package voice
+
+import (
+ "context"
+ "encoding/base64"
+ "errors"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+var _ Transcriber = (*AudioModelTranscriber)(nil)
+
+type fakeLLMProvider struct {
+ chatFunc func(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ options map[string]any,
+ ) (*providers.LLMResponse, error)
+}
+
+func (p *fakeLLMProvider) Chat(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ options map[string]any,
+) (*providers.LLMResponse, error) {
+ if p.chatFunc == nil {
+ return nil, nil
+ }
+ return p.chatFunc(ctx, messages, tools, model, options)
+}
+
+func (p *fakeLLMProvider) GetDefaultModel() string {
+ return ""
+}
+
+func TestAudioModelTranscriberName(t *testing.T) {
+ tr := &AudioModelTranscriber{}
+ if got := tr.Name(); got != "audio-model" {
+ t.Errorf("Name() = %q, want %q", got, "audio-model")
+ }
+}
+
+func TestNewAudioModelTranscriberInvalidConfig(t *testing.T) {
+ tests := []struct {
+ name string
+ cfg *config.ModelConfig
+ }{
+ {
+ name: "nil config",
+ cfg: nil,
+ },
+ {
+ name: "missing api key",
+ cfg: &config.ModelConfig{
+ Model: "gemini/gemini-2.5-flash",
+ },
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ if tr := NewAudioModelTranscriber(tt.cfg); tr != nil {
+ t.Fatalf("NewAudioModelTranscriber() = %#v, want nil", tr)
+ }
+ })
+ }
+}
+
+func TestAudioModelTranscriberTranscribe(t *testing.T) {
+ tmpDir := t.TempDir()
+ audioPath := filepath.Join(tmpDir, "clip.ogg")
+ audioData := []byte("fake-audio-data")
+ if err := os.WriteFile(audioPath, audioData, 0o644); err != nil {
+ t.Fatalf("failed to write fake audio file: %v", err)
+ }
+
+ t.Run("success", func(t *testing.T) {
+ tr := &AudioModelTranscriber{
+ provider: &fakeLLMProvider{
+ chatFunc: func(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ options map[string]any,
+ ) (*providers.LLMResponse, error) {
+ if ctx == nil {
+ t.Fatal("context should not be nil")
+ }
+ if tools != nil {
+ t.Fatalf("tools = %#v, want nil", tools)
+ }
+ if model != "gemini-2.5-flash" {
+ t.Fatalf("model = %q, want %q", model, "gemini-2.5-flash")
+ }
+ if len(messages) != 1 {
+ t.Fatalf("len(messages) = %d, want 1", len(messages))
+ }
+ msg := messages[0]
+ if msg.Role != "user" {
+ t.Fatalf("role = %q, want %q", msg.Role, "user")
+ }
+ if msg.Content != defaultTranscriptionPrompt {
+ t.Fatalf("prompt = %q, want %q", msg.Content, defaultTranscriptionPrompt)
+ }
+ if len(msg.Media) != 1 {
+ t.Fatalf("len(media) = %d, want 1", len(msg.Media))
+ }
+ wantMedia := "data:audio/ogg;base64," + base64.StdEncoding.EncodeToString(audioData)
+ if msg.Media[0] != wantMedia {
+ t.Fatalf("media = %q, want %q", msg.Media[0], wantMedia)
+ }
+ if len(options) != 1 {
+ t.Fatalf("options = %#v, want only temperature", options)
+ }
+ if got := options["temperature"]; got != 0 {
+ t.Fatalf("temperature = %#v, want 0", got)
+ }
+
+ return &providers.LLMResponse{Content: " hello from gemini \n"}, nil
+ },
+ },
+ modelID: "gemini-2.5-flash",
+ prompt: defaultTranscriptionPrompt,
+ }
+
+ resp, err := tr.Transcribe(context.Background(), audioPath)
+ if err != nil {
+ t.Fatalf("Transcribe() error: %v", err)
+ }
+ if resp.Text != "hello from gemini" {
+ t.Fatalf("Text = %q, want %q", resp.Text, "hello from gemini")
+ }
+ })
+
+ t.Run("provider error", func(t *testing.T) {
+ tr := &AudioModelTranscriber{
+ provider: &fakeLLMProvider{
+ chatFunc: func(
+ ctx context.Context,
+ messages []providers.Message,
+ tools []providers.ToolDefinition,
+ model string,
+ options map[string]any,
+ ) (*providers.LLMResponse, error) {
+ return nil, errors.New("upstream failure")
+ },
+ },
+ modelID: "gemini-2.5-flash",
+ prompt: defaultTranscriptionPrompt,
+ }
+
+ _, err := tr.Transcribe(context.Background(), audioPath)
+ if err == nil {
+ t.Fatal("expected error for provider failure, got nil")
+ }
+ if got := err.Error(); got != "transcription request failed: upstream failure" {
+ t.Fatalf("error = %q, want %q", got, "transcription request failed: upstream failure")
+ }
+ })
+
+ t.Run("missing file", func(t *testing.T) {
+ tr := &AudioModelTranscriber{
+ provider: &fakeLLMProvider{},
+ modelID: "gemini-2.5-flash",
+ prompt: defaultTranscriptionPrompt,
+ }
+
+ _, err := tr.Transcribe(context.Background(), filepath.Join(tmpDir, "nonexistent.ogg"))
+ if err == nil {
+ t.Fatal("expected error for missing file, got nil")
+ }
+ })
+
+ t.Run("unsupported audio format", func(t *testing.T) {
+ badPath := filepath.Join(tmpDir, "clip.txt")
+ if err := os.WriteFile(badPath, []byte("not-audio"), 0o644); err != nil {
+ t.Fatalf("failed to write fake file: %v", err)
+ }
+
+ tr := &AudioModelTranscriber{
+ provider: &fakeLLMProvider{},
+ modelID: "gemini-2.5-flash",
+ prompt: defaultTranscriptionPrompt,
+ }
+
+ _, err := tr.Transcribe(context.Background(), badPath)
+ if err == nil {
+ t.Fatal("expected error for unsupported audio format, got nil")
+ }
+ if got := err.Error(); got != `unsupported audio format for "`+badPath+`"` {
+ t.Fatalf("error = %q, want unsupported format error", got)
+ }
+ })
+}
diff --git a/pkg/voice/groq_transcriber.go b/pkg/voice/groq_transcriber.go
new file mode 100644
index 000000000..b42e598f7
--- /dev/null
+++ b/pkg/voice/groq_transcriber.go
@@ -0,0 +1,151 @@
+package voice
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "mime/multipart"
+ "net/http"
+ "os"
+ "path/filepath"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
+ "github.com/sipeed/picoclaw/pkg/utils"
+)
+
+type GroqTranscriber struct {
+ apiKey string
+ apiBase string
+ httpClient *http.Client
+}
+
+func NewGroqTranscriber(apiKey string) *GroqTranscriber {
+ logger.DebugCF("voice", "Creating Groq transcriber", map[string]any{"has_api_key": apiKey != ""})
+
+ apiBase := "https://api.groq.com/openai/v1"
+ return &GroqTranscriber{
+ apiKey: apiKey,
+ apiBase: apiBase,
+ httpClient: &http.Client{
+ Timeout: 60 * time.Second,
+ },
+ }
+}
+
+func (t *GroqTranscriber) Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error) {
+ logger.InfoCF("voice", "Starting transcription", map[string]any{"audio_file": audioFilePath})
+
+ audioFile, err := os.Open(audioFilePath)
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to open audio file", map[string]any{"path": audioFilePath, "error": err})
+ return nil, fmt.Errorf("failed to open audio file: %w", err)
+ }
+ defer audioFile.Close()
+
+ fileInfo, err := audioFile.Stat()
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to get file info", map[string]any{"path": audioFilePath, "error": err})
+ return nil, fmt.Errorf("failed to get file info: %w", err)
+ }
+
+ logger.DebugCF("voice", "Audio file details", map[string]any{
+ "size_bytes": fileInfo.Size(),
+ "file_name": filepath.Base(audioFilePath),
+ })
+
+ var requestBody bytes.Buffer
+ writer := multipart.NewWriter(&requestBody)
+
+ part, err := writer.CreateFormFile("file", filepath.Base(audioFilePath))
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to create form file", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to create form file: %w", err)
+ }
+
+ copied, err := io.Copy(part, audioFile)
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to copy file content", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to copy file content: %w", err)
+ }
+
+ logger.DebugCF("voice", "File copied to request", map[string]any{"bytes_copied": copied})
+
+ if err = writer.WriteField("model", "whisper-large-v3"); err != nil {
+ logger.ErrorCF("voice", "Failed to write model field", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to write model field: %w", err)
+ }
+
+ if err = writer.WriteField("response_format", "json"); err != nil {
+ logger.ErrorCF("voice", "Failed to write response_format field", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to write response_format field: %w", err)
+ }
+
+ if err = writer.Close(); err != nil {
+ logger.ErrorCF("voice", "Failed to close multipart writer", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to close multipart writer: %w", err)
+ }
+
+ url := t.apiBase + "/audio/transcriptions"
+ req, err := http.NewRequestWithContext(ctx, "POST", url, &requestBody)
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to create request", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to create request: %w", err)
+ }
+
+ req.Header.Set("Content-Type", writer.FormDataContentType())
+ req.Header.Set("Authorization", "Bearer "+t.apiKey)
+
+ logger.DebugCF("voice", "Sending transcription request to Groq API", map[string]any{
+ "url": url,
+ "request_size_bytes": requestBody.Len(),
+ "file_size_bytes": fileInfo.Size(),
+ })
+
+ resp, err := t.httpClient.Do(req)
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to send request", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to send request: %w", err)
+ }
+ defer resp.Body.Close()
+
+ body, err := io.ReadAll(resp.Body)
+ if err != nil {
+ logger.ErrorCF("voice", "Failed to read response", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to read response: %w", err)
+ }
+
+ if resp.StatusCode != http.StatusOK {
+ logger.ErrorCF("voice", "API error", map[string]any{
+ "status_code": resp.StatusCode,
+ "response": string(body),
+ })
+ return nil, fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(body))
+ }
+
+ logger.DebugCF("voice", "Received response from Groq API", map[string]any{
+ "status_code": resp.StatusCode,
+ "response_size_bytes": len(body),
+ })
+
+ var result TranscriptionResponse
+ if err := json.Unmarshal(body, &result); err != nil {
+ logger.ErrorCF("voice", "Failed to unmarshal response", map[string]any{"error": err})
+ return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+ }
+
+ logger.InfoCF("voice", "Transcription completed successfully", map[string]any{
+ "text_length": len(result.Text),
+ "language": result.Language,
+ "duration_seconds": result.Duration,
+ "transcription_preview": utils.Truncate(result.Text, 50),
+ })
+
+ return &result, nil
+}
+
+func (t *GroqTranscriber) Name() string {
+ return "groq"
+}
diff --git a/pkg/voice/groq_transcriber_test.go b/pkg/voice/groq_transcriber_test.go
new file mode 100644
index 000000000..fdcaa7580
--- /dev/null
+++ b/pkg/voice/groq_transcriber_test.go
@@ -0,0 +1,84 @@
+package voice
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+var _ Transcriber = (*GroqTranscriber)(nil)
+
+func TestGroqTranscriberName(t *testing.T) {
+ tr := NewGroqTranscriber("sk-test")
+ if got := tr.Name(); got != "groq" {
+ t.Errorf("Name() = %q, want %q", got, "groq")
+ }
+}
+
+func TestGroqTranscribe(t *testing.T) {
+ // Write a minimal fake audio file so the transcriber can open and send it.
+ tmpDir := t.TempDir()
+ audioPath := filepath.Join(tmpDir, "clip.ogg")
+ if err := os.WriteFile(audioPath, []byte("fake-audio-data"), 0o644); err != nil {
+ t.Fatalf("failed to write fake audio file: %v", err)
+ }
+
+ t.Run("success", func(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/audio/transcriptions" {
+ t.Errorf("unexpected path: %s", r.URL.Path)
+ }
+ if r.Header.Get("Authorization") != "Bearer sk-test" {
+ t.Errorf("unexpected Authorization header: %s", r.Header.Get("Authorization"))
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _ = json.NewEncoder(w).Encode(TranscriptionResponse{
+ Text: "hello world",
+ Language: "en",
+ Duration: 1.5,
+ })
+ }))
+ defer srv.Close()
+
+ tr := NewGroqTranscriber("sk-test")
+ tr.apiBase = srv.URL
+
+ resp, err := tr.Transcribe(context.Background(), audioPath)
+ if err != nil {
+ t.Fatalf("Transcribe() error: %v", err)
+ }
+ if resp.Text != "hello world" {
+ t.Errorf("Text = %q, want %q", resp.Text, "hello world")
+ }
+ if resp.Language != "en" {
+ t.Errorf("Language = %q, want %q", resp.Language, "en")
+ }
+ })
+
+ t.Run("api error", func(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ http.Error(w, `{"error":"invalid_api_key"}`, http.StatusUnauthorized)
+ }))
+ defer srv.Close()
+
+ tr := NewGroqTranscriber("sk-bad")
+ tr.apiBase = srv.URL
+
+ _, err := tr.Transcribe(context.Background(), audioPath)
+ if err == nil {
+ t.Fatal("expected error for non-200 response, got nil")
+ }
+ })
+
+ t.Run("missing file", func(t *testing.T) {
+ tr := NewGroqTranscriber("sk-test")
+ _, err := tr.Transcribe(context.Background(), filepath.Join(tmpDir, "nonexistent.ogg"))
+ if err == nil {
+ t.Fatal("expected error for missing file, got nil")
+ }
+ })
+}
diff --git a/pkg/voice/transcriber.go b/pkg/voice/transcriber.go
index e949d7a22..a50fba8f8 100644
--- a/pkg/voice/transcriber.go
+++ b/pkg/voice/transcriber.go
@@ -1,21 +1,11 @@
package voice
import (
- "bytes"
"context"
- "encoding/json"
- "fmt"
- "io"
- "mime/multipart"
- "net/http"
- "os"
- "path/filepath"
"strings"
- "time"
"github.com/sipeed/picoclaw/pkg/config"
- "github.com/sipeed/picoclaw/pkg/logger"
- "github.com/sipeed/picoclaw/pkg/utils"
+ "github.com/sipeed/picoclaw/pkg/providers"
)
type Transcriber interface {
@@ -23,157 +13,51 @@ type Transcriber interface {
Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error)
}
-type GroqTranscriber struct {
- apiKey string
- apiBase string
- httpClient *http.Client
-}
-
type TranscriptionResponse struct {
Text string `json:"text"`
Language string `json:"language,omitempty"`
Duration float64 `json:"duration,omitempty"`
}
-func NewGroqTranscriber(apiKey string) *GroqTranscriber {
- logger.DebugCF("voice", "Creating Groq transcriber", map[string]any{"has_api_key": apiKey != ""})
+func supportsAudioTranscription(model string) bool {
+ protocol, _ := providers.ExtractProtocol(model)
- apiBase := "https://api.groq.com/openai/v1"
- return &GroqTranscriber{
- apiKey: apiKey,
- apiBase: apiBase,
- httpClient: &http.Client{
- Timeout: 60 * time.Second,
- },
+ switch protocol {
+ case "openai", "azure", "azure-openai",
+ "litellm", "openrouter", "groq", "zhipu", "gemini", "nvidia",
+ "ollama", "moonshot", "shengsuanyun", "deepseek", "cerebras",
+ "vivgrid", "volcengine", "vllm", "qwen", "qwen-intl", "qwen-international", "dashscope-intl",
+ "qwen-us", "dashscope-us", "mistral", "avian", "minimax", "longcat", "modelscope", "novita",
+ "coding-plan", "alibaba-coding", "qwen-coding":
+ // These protocols all go through the OpenAI-compatible or Azure provider path in
+ // providers.CreateProviderFromConfig, so they are the only ones that can supply
+ // the audio media payload shape expected by NewAudioModelTranscriber.
+
+ // TODO: Further restrict this by modelID, since not every model under these
+ // protocols supports audio transcription.
+ return true
+ default:
+ return false
}
}
-func (t *GroqTranscriber) Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error) {
- logger.InfoCF("voice", "Starting transcription", map[string]any{"audio_file": audioFilePath})
-
- audioFile, err := os.Open(audioFilePath)
- if err != nil {
- logger.ErrorCF("voice", "Failed to open audio file", map[string]any{"path": audioFilePath, "error": err})
- return nil, fmt.Errorf("failed to open audio file: %w", err)
- }
- defer audioFile.Close()
-
- fileInfo, err := audioFile.Stat()
- if err != nil {
- logger.ErrorCF("voice", "Failed to get file info", map[string]any{"path": audioFilePath, "error": err})
- return nil, fmt.Errorf("failed to get file info: %w", err)
- }
-
- logger.DebugCF("voice", "Audio file details", map[string]any{
- "size_bytes": fileInfo.Size(),
- "file_name": filepath.Base(audioFilePath),
- })
-
- var requestBody bytes.Buffer
- writer := multipart.NewWriter(&requestBody)
-
- part, err := writer.CreateFormFile("file", filepath.Base(audioFilePath))
- if err != nil {
- logger.ErrorCF("voice", "Failed to create form file", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to create form file: %w", err)
- }
-
- copied, err := io.Copy(part, audioFile)
- if err != nil {
- logger.ErrorCF("voice", "Failed to copy file content", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to copy file content: %w", err)
- }
-
- logger.DebugCF("voice", "File copied to request", map[string]any{"bytes_copied": copied})
-
- if err = writer.WriteField("model", "whisper-large-v3"); err != nil {
- logger.ErrorCF("voice", "Failed to write model field", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to write model field: %w", err)
- }
-
- if err = writer.WriteField("response_format", "json"); err != nil {
- logger.ErrorCF("voice", "Failed to write response_format field", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to write response_format field: %w", err)
- }
-
- if err = writer.Close(); err != nil {
- logger.ErrorCF("voice", "Failed to close multipart writer", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to close multipart writer: %w", err)
- }
-
- url := t.apiBase + "/audio/transcriptions"
- req, err := http.NewRequestWithContext(ctx, "POST", url, &requestBody)
- if err != nil {
- logger.ErrorCF("voice", "Failed to create request", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to create request: %w", err)
- }
-
- req.Header.Set("Content-Type", writer.FormDataContentType())
- req.Header.Set("Authorization", "Bearer "+t.apiKey)
-
- logger.DebugCF("voice", "Sending transcription request to Groq API", map[string]any{
- "url": url,
- "request_size_bytes": requestBody.Len(),
- "file_size_bytes": fileInfo.Size(),
- })
-
- resp, err := t.httpClient.Do(req)
- if err != nil {
- logger.ErrorCF("voice", "Failed to send request", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to send request: %w", err)
- }
- defer resp.Body.Close()
-
- body, err := io.ReadAll(resp.Body)
- if err != nil {
- logger.ErrorCF("voice", "Failed to read response", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to read response: %w", err)
- }
-
- if resp.StatusCode != http.StatusOK {
- logger.ErrorCF("voice", "API error", map[string]any{
- "status_code": resp.StatusCode,
- "response": string(body),
- })
- return nil, fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(body))
- }
-
- logger.DebugCF("voice", "Received response from Groq API", map[string]any{
- "status_code": resp.StatusCode,
- "response_size_bytes": len(body),
- })
-
- var result TranscriptionResponse
- if err := json.Unmarshal(body, &result); err != nil {
- logger.ErrorCF("voice", "Failed to unmarshal response", map[string]any{"error": err})
- return nil, fmt.Errorf("failed to unmarshal response: %w", err)
- }
-
- logger.InfoCF("voice", "Transcription completed successfully", map[string]any{
- "text_length": len(result.Text),
- "language": result.Language,
- "duration_seconds": result.Duration,
- "transcription_preview": utils.Truncate(result.Text, 50),
- })
-
- return &result, nil
-}
-
-func (t *GroqTranscriber) Name() string {
- return "groq"
-}
-
// DetectTranscriber inspects cfg and returns the appropriate Transcriber, or
// nil if no supported transcription provider is configured.
func DetectTranscriber(cfg *config.Config) Transcriber {
- // Direct Groq provider config takes priority.
- if key := cfg.Providers.Groq.APIKey; key != "" {
- return NewGroqTranscriber(key)
+ if modelName := strings.TrimSpace(cfg.Voice.ModelName); modelName != "" {
+ modelCfg, err := cfg.GetModelConfig(modelName)
+ if err != nil {
+ return nil
+ }
+ if supportsAudioTranscription(modelCfg.Model) {
+ return NewAudioModelTranscriber(modelCfg)
+ }
}
+
// Fall back to any model-list entry that uses the groq/ protocol.
for _, mc := range cfg.ModelList {
- if strings.HasPrefix(mc.Model, "groq/") && mc.APIKey != "" {
- return NewGroqTranscriber(mc.APIKey)
+ if strings.HasPrefix(mc.Model, "groq/") && mc.APIKey() != "" {
+ return NewGroqTranscriber(mc.APIKey())
}
}
return nil
diff --git a/pkg/voice/transcriber_test.go b/pkg/voice/transcriber_test.go
index 9b6add333..20ba5388b 100644
--- a/pkg/voice/transcriber_test.go
+++ b/pkg/voice/transcriber_test.go
@@ -1,27 +1,11 @@
package voice
import (
- "context"
- "encoding/json"
- "net/http"
- "net/http/httptest"
- "os"
- "path/filepath"
"testing"
"github.com/sipeed/picoclaw/pkg/config"
)
-// Ensure GroqTranscriber satisfies the Transcriber interface at compile time.
-var _ Transcriber = (*GroqTranscriber)(nil)
-
-func TestGroqTranscriberName(t *testing.T) {
- tr := NewGroqTranscriber("sk-test")
- if got := tr.Name(); got != "groq" {
- t.Errorf("Name() = %q, want %q", got, "groq")
- }
-}
-
func TestDetectTranscriber(t *testing.T) {
tests := []struct {
name string
@@ -35,45 +19,132 @@ func TestDetectTranscriber(t *testing.T) {
wantNil: true,
},
{
- name: "groq provider key",
- cfg: &config.Config{
- Providers: config.ProvidersConfig{
- Groq: config.ProviderConfig{APIKey: "sk-groq-direct"},
+ name: "voice model name selects audio model transcriber",
+ cfg: (&config.Config{
+ Voice: config.VoiceConfig{ModelName: "voice-gemini"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "voice-gemini", Model: "gemini/gemini-2.5-flash"},
},
- },
- wantName: "groq",
+ }).WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "voice-gemini": {
+ APIKeys: []string{"sk-gemini-model"},
+ },
+ },
+ }),
+ wantName: "audio-model",
},
{
name: "groq via model list",
- cfg: &config.Config{
- ModelList: []config.ModelConfig{
- {Model: "openai/gpt-4o", APIKey: "sk-openai"},
- {Model: "groq/llama-3.3-70b", APIKey: "sk-groq-model"},
+ cfg: (&config.Config{
+ ModelList: []*config.ModelConfig{
+ {ModelName: "openai", Model: "openai/gpt-4o"},
+ {ModelName: "groq", Model: "groq/llama-3.3-70b"},
},
- },
+ }).WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "openai": {
+ APIKeys: []string{"sk-openai"},
+ },
+ "groq": {
+ APIKeys: []string{"sk-groq-model"},
+ },
+ },
+ }),
wantName: "groq",
},
+ {
+ name: "voice model name selects non-gemini audio model transcriber",
+ cfg: (&config.Config{
+ Voice: config.VoiceConfig{ModelName: "voice-openai-audio"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "voice-openai-audio", Model: "openai/gpt-4o-audio-preview"},
+ },
+ }).WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "voice-openai-audio": {
+ APIKeys: []string{"sk-openai"},
+ },
+ },
+ }),
+ wantName: "audio-model",
+ },
+ {
+ name: "voice model name selects azure audio model transcriber",
+ cfg: (&config.Config{
+ Voice: config.VoiceConfig{ModelName: "voice-azure-audio"},
+ ModelList: []*config.ModelConfig{
+ {
+ ModelName: "voice-azure-audio",
+ Model: "azure/my-audio-deployment",
+ APIBase: "https://example.openai.azure.com",
+ },
+ },
+ }).WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "voice-azure-audio": {
+ APIKeys: []string{"sk-azure"},
+ },
+ },
+ }),
+ wantName: "audio-model",
+ },
+ {
+ name: "voice model name with non openai compatible protocol does not select audio model transcriber",
+ cfg: (&config.Config{
+ Voice: config.VoiceConfig{ModelName: "voice-anthropic"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "voice-anthropic", Model: "anthropic/claude-sonnet-4.6"},
+ },
+ }).WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "voice-anthropic": {
+ APIKeys: []string{"sk-anthropic"},
+ },
+ },
+ }),
+ wantNil: true,
+ },
{
name: "groq model list entry without key is skipped",
cfg: &config.Config{
- ModelList: []config.ModelConfig{
- {Model: "groq/llama-3.3-70b", APIKey: ""},
+ ModelList: []*config.ModelConfig{
+ {Model: "groq/llama-3.3-70b"},
},
},
wantNil: true,
},
{
name: "provider key takes priority over model list",
- cfg: &config.Config{
- Providers: config.ProvidersConfig{
- Groq: config.ProviderConfig{APIKey: "sk-groq-direct"},
+ cfg: (&config.Config{
+ ModelList: []*config.ModelConfig{
+ {ModelName: "groq", Model: "groq/llama-3.3-70b"},
},
- ModelList: []config.ModelConfig{
- {Model: "groq/llama-3.3-70b", APIKey: "sk-groq-model"},
+ }).WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "groq": {
+ APIKeys: []string{"sk-groq-model"},
+ },
},
- },
+ }),
wantName: "groq",
},
+ {
+ name: "missing voice model name config returns nil",
+ cfg: (&config.Config{
+ Voice: config.VoiceConfig{ModelName: "missing"},
+ ModelList: []*config.ModelConfig{
+ {ModelName: "other", Model: "gemini/gemini-2.5-flash"},
+ },
+ }).WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "other": {
+ APIKeys: []string{"sk-other-model"},
+ },
+ },
+ }),
+ wantNil: true,
+ },
}
for _, tc := range tests {
@@ -94,67 +165,3 @@ func TestDetectTranscriber(t *testing.T) {
})
}
}
-
-func TestTranscribe(t *testing.T) {
- // Write a minimal fake audio file so the transcriber can open and send it.
- tmpDir := t.TempDir()
- audioPath := filepath.Join(tmpDir, "clip.ogg")
- if err := os.WriteFile(audioPath, []byte("fake-audio-data"), 0o644); err != nil {
- t.Fatalf("failed to write fake audio file: %v", err)
- }
-
- t.Run("success", func(t *testing.T) {
- srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- if r.URL.Path != "/audio/transcriptions" {
- t.Errorf("unexpected path: %s", r.URL.Path)
- }
- if r.Header.Get("Authorization") != "Bearer sk-test" {
- t.Errorf("unexpected Authorization header: %s", r.Header.Get("Authorization"))
- }
- w.Header().Set("Content-Type", "application/json")
- _ = json.NewEncoder(w).Encode(TranscriptionResponse{
- Text: "hello world",
- Language: "en",
- Duration: 1.5,
- })
- }))
- defer srv.Close()
-
- tr := NewGroqTranscriber("sk-test")
- tr.apiBase = srv.URL
-
- resp, err := tr.Transcribe(context.Background(), audioPath)
- if err != nil {
- t.Fatalf("Transcribe() error: %v", err)
- }
- if resp.Text != "hello world" {
- t.Errorf("Text = %q, want %q", resp.Text, "hello world")
- }
- if resp.Language != "en" {
- t.Errorf("Language = %q, want %q", resp.Language, "en")
- }
- })
-
- t.Run("api error", func(t *testing.T) {
- srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- http.Error(w, `{"error":"invalid_api_key"}`, http.StatusUnauthorized)
- }))
- defer srv.Close()
-
- tr := NewGroqTranscriber("sk-bad")
- tr.apiBase = srv.URL
-
- _, err := tr.Transcribe(context.Background(), audioPath)
- if err == nil {
- t.Fatal("expected error for non-200 response, got nil")
- }
- })
-
- t.Run("missing file", func(t *testing.T) {
- tr := NewGroqTranscriber("sk-test")
- _, err := tr.Transcribe(context.Background(), filepath.Join(tmpDir, "nonexistent.ogg"))
- if err == nil {
- t.Fatal("expected error for missing file, got nil")
- }
- })
-}
diff --git a/web/backend/api/config.go b/web/backend/api/config.go
index a7d5b3c5d..7cdfde174 100644
--- a/web/backend/api/config.go
+++ b/web/backend/api/config.go
@@ -8,6 +8,7 @@ import (
"regexp"
"github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/logger"
)
// registerConfigRoutes binds configuration management endpoints to the ServeMux.
@@ -45,7 +46,7 @@ func (h *Handler) handleUpdateConfig(w http.ResponseWriter, r *http.Request) {
defer r.Body.Close()
var cfg config.Config
- if err := json.Unmarshal(body, &cfg); err != nil {
+ if err = json.Unmarshal(body, &cfg); err != nil {
http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
return
}
@@ -63,6 +64,14 @@ func (h *Handler) handleUpdateConfig(w http.ResponseWriter, r *http.Request) {
return
}
+ logger.Infof("new config: %+v", cfg)
+ oldCfg, err := config.LoadConfig(h.configPath)
+ if err != nil {
+ http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+ return
+ }
+ cfg.SecurityCopyFrom(oldCfg)
+
if err := config.SaveConfig(h.configPath, &cfg); err != nil {
http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
return
@@ -150,6 +159,8 @@ func (h *Handler) handlePatchConfig(w http.ResponseWriter, r *http.Request) {
return
}
+ newCfg.SecurityCopyFrom(cfg)
+
if err := config.SaveConfig(h.configPath, &newCfg); err != nil {
http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
return
@@ -175,17 +186,17 @@ func validateConfig(cfg *config.Config) []string {
}
// Pico channel: token required when enabled
- if cfg.Channels.Pico.Enabled && cfg.Channels.Pico.Token == "" {
+ if cfg.Channels.Pico.Enabled && cfg.Channels.Pico.Token() == "" {
errs = append(errs, "channels.pico.token is required when pico channel is enabled")
}
// Telegram: token required when enabled
- if cfg.Channels.Telegram.Enabled && cfg.Channels.Telegram.Token == "" {
+ if cfg.Channels.Telegram.Enabled && cfg.Channels.Telegram.Token() == "" {
errs = append(errs, "channels.telegram.token is required when telegram channel is enabled")
}
// Discord: token required when enabled
- if cfg.Channels.Discord.Enabled && cfg.Channels.Discord.Token == "" {
+ if cfg.Channels.Discord.Enabled && cfg.Channels.Discord.Token() == "" {
errs = append(errs, "channels.discord.token is required when discord channel is enabled")
}
diff --git a/web/backend/api/config_test.go b/web/backend/api/config_test.go
index 54ec8e857..bbf285e14 100644
--- a/web/backend/api/config_test.go
+++ b/web/backend/api/config_test.go
@@ -18,6 +18,7 @@ func TestHandleUpdateConfig_PreservesExecAllowRemoteDefaultWhenOmitted(t *testin
h.RegisterRoutes(mux)
req := httptest.NewRequest(http.MethodPut, "/api/config", bytes.NewBufferString(`{
+"version": 1,
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace"
@@ -27,7 +28,7 @@ func TestHandleUpdateConfig_PreservesExecAllowRemoteDefaultWhenOmitted(t *testin
{
"model_name": "custom-default",
"model": "openai/gpt-4o",
- "api_key": "sk-default"
+ "api_keys": ["sk-default"]
}
]
}`))
diff --git a/web/backend/api/gateway.go b/web/backend/api/gateway.go
index d5ccd6e29..7f72f12b8 100644
--- a/web/backend/api/gateway.go
+++ b/web/backend/api/gateway.go
@@ -159,10 +159,10 @@ func (h *Handler) gatewayStartReady() (bool, string, error) {
return false, fmt.Sprintf("default model %q is invalid", modelName), nil
}
- if !hasModelConfiguration(*modelCfg) {
+ if !hasModelConfiguration(modelCfg) {
return false, fmt.Sprintf("default model %q has no credentials configured", modelName), nil
}
- if requiresRuntimeProbe(*modelCfg) && !probeLocalModelAvailability(*modelCfg) {
+ if requiresRuntimeProbe(modelCfg) && !probeLocalModelAvailability(modelCfg) {
return false, fmt.Sprintf("default model %q is not reachable", modelName), nil
}
diff --git a/web/backend/api/gateway_test.go b/web/backend/api/gateway_test.go
index 5c94f0b89..a5ba2bad2 100644
--- a/web/backend/api/gateway_test.go
+++ b/web/backend/api/gateway_test.go
@@ -101,7 +101,7 @@ func TestGatewayStartReady_NoDefaultModel(t *testing.T) {
func TestGatewayStartReady_InvalidDefaultModel(t *testing.T) {
configPath := filepath.Join(t.TempDir(), "config.json")
cfg := config.DefaultConfig()
- cfg.Agents.Defaults.Model = "missing-model"
+ cfg.Agents.Defaults.ModelName = "missing-model"
err := config.SaveConfig(configPath, cfg)
if err != nil {
t.Fatalf("SaveConfig() error = %v", err)
@@ -124,7 +124,7 @@ func TestGatewayStartReady_ValidDefaultModel(t *testing.T) {
configPath := filepath.Join(t.TempDir(), "config.json")
cfg := config.DefaultConfig()
cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
- cfg.ModelList[0].APIKey = "test-key"
+ cfg.ModelList[0].SetAPIKey("test-key")
err := config.SaveConfig(configPath, cfg)
if err != nil {
t.Fatalf("SaveConfig() error = %v", err)
@@ -144,7 +144,7 @@ func TestGatewayStartReady_DefaultModelWithoutCredential(t *testing.T) {
configPath := filepath.Join(t.TempDir(), "config.json")
cfg := config.DefaultConfig()
cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
- cfg.ModelList[0].APIKey = ""
+ cfg.ModelList[0].SetAPIKey("")
cfg.ModelList[0].AuthMethod = ""
err := config.SaveConfig(configPath, cfg)
if err != nil {
@@ -169,7 +169,7 @@ func TestGatewayStartReady_LocalModelWithoutAPIKey(t *testing.T) {
defer cleanup()
resetModelProbeHooks(t)
- probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+ probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
return false
}
@@ -177,7 +177,7 @@ func TestGatewayStartReady_LocalModelWithoutAPIKey(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{{
+ cfg.ModelList = []*config.ModelConfig{{
ModelName: "local-vllm",
Model: "vllm/custom-model",
APIBase: "http://localhost:8000/v1",
@@ -206,15 +206,15 @@ func TestGatewayStartReady_LocalModelWithRunningService(t *testing.T) {
defer cleanup()
resetModelProbeHooks(t)
- probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
- return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model"
+ probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
+ return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model" && apiKey == ""
}
cfg, err := config.LoadConfig(configPath)
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{{
+ cfg.ModelList = []*config.ModelConfig{{
ModelName: "local-vllm",
Model: "vllm/custom-model",
APIBase: "http://127.0.0.1:8000/v1",
@@ -240,7 +240,7 @@ func TestGatewayStartReady_RemoteVLLMWithAPIKeyDoesNotProbe(t *testing.T) {
defer cleanup()
resetModelProbeHooks(t)
- probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+ probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
t.Fatalf("unexpected OpenAI-compatible probe for %q (%q)", apiBase, modelID)
return false
}
@@ -249,12 +249,12 @@ func TestGatewayStartReady_RemoteVLLMWithAPIKeyDoesNotProbe(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{{
+ cfg.ModelList = []*config.ModelConfig{{
ModelName: "remote-vllm",
Model: "vllm/custom-model",
APIBase: "https://models.example.com/v1",
- APIKey: "remote-key",
}}
+ cfg.ModelList[0o0].SetAPIKey("remote-key")
cfg.Agents.Defaults.ModelName = "remote-vllm"
err = config.SaveConfig(configPath, cfg)
if err != nil {
@@ -284,7 +284,7 @@ func TestGatewayStartReady_LocalOllamaUsesDefaultProbeBase(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{{
+ cfg.ModelList = []*config.ModelConfig{{
ModelName: "local-ollama",
Model: "ollama/llama3",
}}
@@ -312,7 +312,7 @@ func TestGatewayStartReady_OAuthModelRequiresStoredCredential(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{{
+ cfg.ModelList = []*config.ModelConfig{{
ModelName: "openai-oauth",
Model: "openai/gpt-5.4",
AuthMethod: "oauth",
@@ -483,12 +483,12 @@ func TestGatewayStatusRequiresRestartAfterDefaultModelChange(t *testing.T) {
configPath := filepath.Join(t.TempDir(), "config.json")
cfg := config.DefaultConfig()
cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
- cfg.ModelList[0].APIKey = "test-key"
- cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+ cfg.ModelList[0].SetAPIKey("test-key")
+ cfg.ModelList = append(cfg.ModelList, &config.ModelConfig{
ModelName: "second-model",
Model: "openai/gpt-4.1",
- APIKey: "second-key",
})
+ cfg.ModelList[len(cfg.ModelList)-1].SetAPIKey("second-key")
if err := config.SaveConfig(configPath, cfg); err != nil {
t.Fatalf("SaveConfig() error = %v", err)
}
@@ -596,6 +596,11 @@ func TestGatewayStatusReturnsErrorAfterStartupWindowExpires(t *testing.T) {
func TestGatewayStatusReturnsRestartingDuringRestartGap(t *testing.T) {
resetGatewayTestState(t)
+ // Mock health check to return error, so it won't override our "restarting" status
+ gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) {
+ return nil, errors.New("mock health check error")
+ }
+
configPath := filepath.Join(t.TempDir(), "config.json")
h := NewHandler(configPath)
mux := http.NewServeMux()
@@ -627,7 +632,7 @@ func TestGatewayRestartKeepsRunningProcessWhenPreconditionsFail(t *testing.T) {
configPath := filepath.Join(t.TempDir(), "config.json")
cfg := config.DefaultConfig()
cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
- cfg.ModelList[0].APIKey = ""
+ cfg.ModelList[0].SetAPIKey("")
cfg.ModelList[0].AuthMethod = ""
if err := config.SaveConfig(configPath, cfg); err != nil {
t.Fatalf("SaveConfig() error = %v", err)
@@ -680,7 +685,7 @@ func TestGatewayRestartKeepsOldProcessWhenItDoesNotExitInTime(t *testing.T) {
configPath := filepath.Join(t.TempDir(), "config.json")
cfg := config.DefaultConfig()
cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
- cfg.ModelList[0].APIKey = "test-key"
+ cfg.ModelList[0].SetAPIKey("test-key")
if err := config.SaveConfig(configPath, cfg); err != nil {
t.Fatalf("SaveConfig() error = %v", err)
}
@@ -738,10 +743,15 @@ func TestGatewayRestartKeepsOldProcessWhenItDoesNotExitInTime(t *testing.T) {
func TestGatewayRestartReturnsErrorStatusWhenReplacementFailsToStart(t *testing.T) {
resetGatewayTestState(t)
+ // Mock health check to return error, so it won't override our "error" status
+ gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) {
+ return nil, errors.New("mock health check error")
+ }
+
configPath := filepath.Join(t.TempDir(), "config.json")
cfg := config.DefaultConfig()
cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
- cfg.ModelList[0].APIKey = "test-key"
+ cfg.ModelList[0].SetAPIKey("test-key")
if err := config.SaveConfig(configPath, cfg); err != nil {
t.Fatalf("SaveConfig() error = %v", err)
}
diff --git a/web/backend/api/model_status.go b/web/backend/api/model_status.go
index 22bf5c15b..aeef85119 100644
--- a/web/backend/api/model_status.go
+++ b/web/backend/api/model_status.go
@@ -20,9 +20,9 @@ var (
probeOpenAICompatibleModelFunc = probeOpenAICompatibleModel
)
-func hasModelConfiguration(m config.ModelConfig) bool {
+func hasModelConfiguration(m *config.ModelConfig) bool {
authMethod := strings.ToLower(strings.TrimSpace(m.AuthMethod))
- apiKey := strings.TrimSpace(m.APIKey)
+ apiKey := strings.TrimSpace(m.APIKey())
if authMethod == "oauth" || authMethod == "token" {
if provider, ok := oauthProviderForModel(m.Model); ok {
@@ -44,7 +44,7 @@ func hasModelConfiguration(m config.ModelConfig) bool {
// isModelConfigured reports whether a model is currently available to use.
// Local models must be reachable; remote/API-key models only need saved config.
-func isModelConfigured(m config.ModelConfig) bool {
+func isModelConfigured(m *config.ModelConfig) bool {
if !hasModelConfiguration(m) {
return false
}
@@ -54,7 +54,7 @@ func isModelConfigured(m config.ModelConfig) bool {
return true
}
-func requiresRuntimeProbe(m config.ModelConfig) bool {
+func requiresRuntimeProbe(m *config.ModelConfig) bool {
authMethod := strings.ToLower(strings.TrimSpace(m.AuthMethod))
if authMethod == "local" {
return true
@@ -75,27 +75,27 @@ func requiresRuntimeProbe(m config.ModelConfig) bool {
return false
}
-func probeLocalModelAvailability(m config.ModelConfig) bool {
+func probeLocalModelAvailability(m *config.ModelConfig) bool {
apiBase := modelProbeAPIBase(m)
protocol, modelID := splitModel(m.Model)
switch protocol {
case "ollama":
return probeOllamaModelFunc(apiBase, modelID)
case "vllm":
- return probeOpenAICompatibleModelFunc(apiBase, modelID)
+ return probeOpenAICompatibleModelFunc(apiBase, modelID, m.APIKey())
case "github-copilot", "copilot":
return probeTCPServiceFunc(apiBase)
case "claude-cli", "claudecli", "codex-cli", "codexcli":
return true
default:
if hasLocalAPIBase(apiBase) {
- return probeOpenAICompatibleModelFunc(apiBase, modelID)
+ return probeOpenAICompatibleModelFunc(apiBase, modelID, m.APIKey())
}
return false
}
}
-func modelProbeAPIBase(m config.ModelConfig) string {
+func modelProbeAPIBase(m *config.ModelConfig) string {
if apiBase := strings.TrimSpace(m.APIBase); apiBase != "" {
return normalizeModelProbeAPIBase(apiBase)
}
@@ -209,7 +209,7 @@ func probeOllamaModel(apiBase, modelID string) bool {
Model string `json:"model"`
} `json:"models"`
}
- if err := getJSON(root+"/api/tags", &resp); err != nil {
+ if err := getJSON(root+"/api/tags", &resp, ""); err != nil {
return false
}
@@ -221,7 +221,7 @@ func probeOllamaModel(apiBase, modelID string) bool {
return false
}
-func probeOpenAICompatibleModel(apiBase, modelID string) bool {
+func probeOpenAICompatibleModel(apiBase, modelID, apiKey string) bool {
if strings.TrimSpace(apiBase) == "" {
return false
}
@@ -231,7 +231,7 @@ func probeOpenAICompatibleModel(apiBase, modelID string) bool {
ID string `json:"id"`
} `json:"data"`
}
- if err := getJSON(strings.TrimRight(strings.TrimSpace(apiBase), "/")+"/models", &resp); err != nil {
+ if err := getJSON(strings.TrimRight(strings.TrimSpace(apiBase), "/")+"/models", &resp, apiKey); err != nil {
return false
}
@@ -243,11 +243,14 @@ func probeOpenAICompatibleModel(apiBase, modelID string) bool {
return false
}
-func getJSON(rawURL string, out any) error {
+func getJSON(rawURL string, out any, apiKey string) error {
req, err := http.NewRequest(http.MethodGet, rawURL, nil)
if err != nil {
return err
}
+ if apiKey = strings.TrimSpace(apiKey); apiKey != "" {
+ req.Header.Set("Authorization", "Bearer "+apiKey)
+ }
client := &http.Client{Timeout: modelProbeTimeout}
resp, err := client.Do(req)
diff --git a/web/backend/api/model_status_test.go b/web/backend/api/model_status_test.go
new file mode 100644
index 000000000..df942a9e9
--- /dev/null
+++ b/web/backend/api/model_status_test.go
@@ -0,0 +1,37 @@
+package api
+
+import (
+ "net/http"
+ "net/http/httptest"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestProbeLocalModelAvailability_OpenAICompatibleIncludesAPIKey(t *testing.T) {
+ const apiKey = "test-api-key"
+
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/v1/models" {
+ t.Fatalf("path = %q, want %q", r.URL.Path, "/v1/models")
+ }
+ if got := r.Header.Get("Authorization"); got != "Bearer "+apiKey {
+ http.Error(w, "missing auth", http.StatusUnauthorized)
+ return
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"data":[{"id":"custom-model"}]}`))
+ }))
+ defer srv.Close()
+
+ model := &config.ModelConfig{
+ Model: "openai/custom-model",
+ APIBase: srv.URL + "/v1",
+ }
+ model.SetAPIKey(apiKey)
+
+ if !probeLocalModelAvailability(model) {
+ t.Fatal("probeLocalModelAvailability() = false, want true when api_key is configured")
+ }
+}
diff --git a/web/backend/api/models.go b/web/backend/api/models.go
index 7f3d29c77..802b28526 100644
--- a/web/backend/api/models.go
+++ b/web/backend/api/models.go
@@ -31,12 +31,13 @@ type modelResponse struct {
Proxy string `json:"proxy,omitempty"`
AuthMethod string `json:"auth_method,omitempty"`
// Advanced fields
- ConnectMode string `json:"connect_mode,omitempty"`
- Workspace string `json:"workspace,omitempty"`
- RPM int `json:"rpm,omitempty"`
- MaxTokensField string `json:"max_tokens_field,omitempty"`
- RequestTimeout int `json:"request_timeout,omitempty"`
- ThinkingLevel string `json:"thinking_level,omitempty"`
+ ConnectMode string `json:"connect_mode,omitempty"`
+ Workspace string `json:"workspace,omitempty"`
+ RPM int `json:"rpm,omitempty"`
+ MaxTokensField string `json:"max_tokens_field,omitempty"`
+ RequestTimeout int `json:"request_timeout,omitempty"`
+ ThinkingLevel string `json:"thinking_level,omitempty"`
+ ExtraBody map[string]any `json:"extra_body,omitempty"`
// Meta
Configured bool `json:"configured"`
IsDefault bool `json:"is_default"`
@@ -58,7 +59,7 @@ func (h *Handler) handleListModels(w http.ResponseWriter, r *http.Request) {
var wg sync.WaitGroup
wg.Add(len(cfg.ModelList))
for i, m := range cfg.ModelList {
- go func(i int, m config.ModelConfig) {
+ go func(i int, m *config.ModelConfig) {
defer wg.Done()
configured[i] = isModelConfigured(m)
}(i, m)
@@ -72,7 +73,7 @@ func (h *Handler) handleListModels(w http.ResponseWriter, r *http.Request) {
ModelName: m.ModelName,
Model: m.Model,
APIBase: m.APIBase,
- APIKey: maskAPIKey(m.APIKey),
+ APIKey: maskAPIKey(m.APIKey()),
Proxy: m.Proxy,
AuthMethod: m.AuthMethod,
ConnectMode: m.ConnectMode,
@@ -81,6 +82,7 @@ func (h *Handler) handleListModels(w http.ResponseWriter, r *http.Request) {
MaxTokensField: m.MaxTokensField,
RequestTimeout: m.RequestTimeout,
ThinkingLevel: m.ThinkingLevel,
+ ExtraBody: m.ExtraBody,
Configured: configured[i],
IsDefault: m.ModelName == defaultModel,
})
@@ -122,7 +124,7 @@ func (h *Handler) handleAddModel(w http.ResponseWriter, r *http.Request) {
return
}
- cfg.ModelList = append(cfg.ModelList, mc)
+ cfg.ModelList = append(cfg.ModelList, &mc)
if err := config.SaveConfig(h.configPath, cfg); err != nil {
http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
@@ -180,11 +182,14 @@ func (h *Handler) handleUpdateModel(w http.ResponseWriter, r *http.Request) {
// Preserve the existing API key when the caller omits it (empty string).
// This lets the UI update api_base / proxy without clearing the stored secret.
- if mc.APIKey == "" {
- mc.APIKey = cfg.ModelList[idx].APIKey
+ if mc.APIKey() == "" {
+ mc.SetAPIKey(cfg.ModelList[idx].APIKey())
+ }
+ if mc.ExtraBody == nil {
+ mc.ExtraBody = cfg.ModelList[idx].ExtraBody
}
- cfg.ModelList[idx] = mc
+ cfg.ModelList[idx] = &mc
if err := config.SaveConfig(h.configPath, cfg); err != nil {
http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
@@ -224,9 +229,6 @@ func (h *Handler) handleDeleteModel(w http.ResponseWriter, r *http.Request) {
if cfg.Agents.Defaults.ModelName == deletedModelName {
cfg.Agents.Defaults.ModelName = ""
}
- if cfg.Agents.Defaults.Model == deletedModelName {
- cfg.Agents.Defaults.Model = ""
- }
if err := config.SaveConfig(h.configPath, cfg); err != nil {
http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
diff --git a/web/backend/api/models_test.go b/web/backend/api/models_test.go
index 2377b5b66..44d10154e 100644
--- a/web/backend/api/models_test.go
+++ b/web/backend/api/models_test.go
@@ -36,11 +36,11 @@ func TestHandleListModels_ConfiguredStatusUsesRuntimeProbesForLocalModels(t *tes
var ollamaProbes []string
var tcpProbes []string
- probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+ probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
mu.Lock()
- openAIProbes = append(openAIProbes, apiBase+"|"+modelID)
+ openAIProbes = append(openAIProbes, apiBase+"|"+modelID+"|"+apiKey)
mu.Unlock()
- return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model"
+ return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model" && apiKey == ""
}
probeOllamaModelFunc = func(apiBase, modelID string) bool {
mu.Lock()
@@ -59,7 +59,7 @@ func TestHandleListModels_ConfiguredStatusUsesRuntimeProbesForLocalModels(t *tes
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{
+ cfg.ModelList = []*config.ModelConfig{
{
ModelName: "openai-oauth",
Model: "openai/gpt-5.4",
@@ -78,7 +78,6 @@ func TestHandleListModels_ConfiguredStatusUsesRuntimeProbesForLocalModels(t *tes
ModelName: "vllm-remote",
Model: "vllm/custom-model",
APIBase: "https://models.example.com/v1",
- APIKey: "remote-key",
},
{
ModelName: "copilot-gpt-5.4",
@@ -87,6 +86,11 @@ func TestHandleListModels_ConfiguredStatusUsesRuntimeProbesForLocalModels(t *tes
AuthMethod: "oauth",
},
}
+ cfg.WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+ "vllm-remote": {
+ APIKeys: []string{"remote-key"},
+ },
+ }})
cfg.Agents.Defaults.ModelName = "openai-oauth"
if err := config.SaveConfig(configPath, cfg); err != nil {
t.Fatalf("SaveConfig() error = %v", err)
@@ -131,7 +135,7 @@ func TestHandleListModels_ConfiguredStatusUsesRuntimeProbesForLocalModels(t *tes
if !got["copilot-gpt-5.4"] {
t.Fatalf("copilot model configured = false, want true when local bridge probe succeeds")
}
- if len(openAIProbes) != 1 || openAIProbes[0] != "http://127.0.0.1:8000/v1|custom-model" {
+ if len(openAIProbes) != 1 || openAIProbes[0] != "http://127.0.0.1:8000/v1|custom-model|" {
t.Fatalf("openAI probes = %#v, want only local vllm probe", openAIProbes)
}
if len(ollamaProbes) != 1 || ollamaProbes[0] != "http://localhost:11434/v1|llama3" {
@@ -152,7 +156,7 @@ func TestHandleListModels_ConfiguredStatusForOAuthModelWithCredential(t *testing
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{{
+ cfg.ModelList = []*config.ModelConfig{{
ModelName: "claude-oauth",
Model: "anthropic/claude-sonnet-4.6",
AuthMethod: "oauth",
@@ -205,7 +209,7 @@ func TestHandleListModels_ProbesLocalModelsConcurrently(t *testing.T) {
started := make(chan string, 2)
release := make(chan struct{})
- probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
+ probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
started <- apiBase + "|" + modelID
<-release
return true
@@ -215,7 +219,7 @@ func TestHandleListModels_ProbesLocalModelsConcurrently(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{
+ cfg.ModelList = []*config.ModelConfig{
{
ModelName: "local-vllm-a",
Model: "vllm/custom-a",
@@ -265,16 +269,16 @@ func TestHandleListModels_NormalizesWildcardLocalAPIBaseForProbe(t *testing.T) {
resetModelProbeHooks(t)
var gotProbe string
- probeOpenAICompatibleModelFunc = func(apiBase, modelID string) bool {
- gotProbe = apiBase + "|" + modelID
- return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model"
+ probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
+ gotProbe = apiBase + "|" + modelID + "|" + apiKey
+ return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model" && apiKey == ""
}
cfg, err := config.LoadConfig(configPath)
if err != nil {
t.Fatalf("LoadConfig() error = %v", err)
}
- cfg.ModelList = []config.ModelConfig{{
+ cfg.ModelList = []*config.ModelConfig{{
ModelName: "vllm-local",
Model: "vllm/custom-model",
APIBase: "http://0.0.0.0:8000/v1",
@@ -307,7 +311,7 @@ func TestHandleListModels_NormalizesWildcardLocalAPIBaseForProbe(t *testing.T) {
if !resp.Models[0].Configured {
t.Fatal("wildcard-bound local model configured = false, want true after probe host normalization")
}
- if gotProbe != "http://127.0.0.1:8000/v1|custom-model" {
- t.Fatalf("probe api base = %q, want %q", gotProbe, "http://127.0.0.1:8000/v1|custom-model")
+ if gotProbe != "http://127.0.0.1:8000/v1|custom-model|" {
+ t.Fatalf("probe api base = %q, want %q", gotProbe, "http://127.0.0.1:8000/v1|custom-model|")
}
}
diff --git a/web/backend/api/oauth.go b/web/backend/api/oauth.go
index 4edabb9ab..213b53836 100644
--- a/web/backend/api/oauth.go
+++ b/web/backend/api/oauth.go
@@ -744,17 +744,6 @@ func (h *Handler) syncProviderAuthMethod(provider, authMethod string) error {
return err
}
- switch provider {
- case oauthProviderOpenAI:
- cfg.Providers.OpenAI.AuthMethod = authMethod
- case oauthProviderAnthropic:
- cfg.Providers.Anthropic.AuthMethod = authMethod
- case oauthProviderGoogleAntigravity:
- cfg.Providers.Antigravity.AuthMethod = authMethod
- default:
- return fmt.Errorf("unsupported provider %q", provider)
- }
-
found := false
for i := range cfg.ModelList {
if modelBelongsToProvider(provider, cfg.ModelList[i].Model) {
@@ -787,28 +776,28 @@ func modelBelongsToProvider(provider, model string) bool {
}
}
-func defaultModelConfigForProvider(provider, authMethod string) config.ModelConfig {
+func defaultModelConfigForProvider(provider, authMethod string) *config.ModelConfig {
switch provider {
case oauthProviderOpenAI:
- return config.ModelConfig{
+ return &config.ModelConfig{
ModelName: "gpt-5.4",
Model: "openai/gpt-5.4",
AuthMethod: authMethod,
}
case oauthProviderAnthropic:
- return config.ModelConfig{
+ return &config.ModelConfig{
ModelName: "claude-sonnet-4.6",
Model: "anthropic/claude-sonnet-4.6",
AuthMethod: authMethod,
}
case oauthProviderGoogleAntigravity:
- return config.ModelConfig{
+ return &config.ModelConfig{
ModelName: "gemini-flash",
Model: "antigravity/gemini-3-flash",
AuthMethod: authMethod,
}
default:
- return config.ModelConfig{}
+ return &config.ModelConfig{}
}
}
diff --git a/web/backend/api/oauth_test.go b/web/backend/api/oauth_test.go
index 7d63abbd4..7cab79b52 100644
--- a/web/backend/api/oauth_test.go
+++ b/web/backend/api/oauth_test.go
@@ -166,8 +166,7 @@ func TestOAuthLogoutClearsCredentialAndConfig(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig error: %v", err)
}
- cfg.Providers.OpenAI.AuthMethod = "oauth"
- cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+ cfg.ModelList = append(cfg.ModelList, &config.ModelConfig{
ModelName: "gpt-5.4",
Model: "openai/gpt-5.4",
AuthMethod: "oauth",
@@ -208,9 +207,6 @@ func TestOAuthLogoutClearsCredentialAndConfig(t *testing.T) {
if err != nil {
t.Fatalf("LoadConfig error: %v", err)
}
- if updated.Providers.OpenAI.AuthMethod != "" {
- t.Fatalf("providers.openai.auth_method = %q, want empty", updated.Providers.OpenAI.AuthMethod)
- }
for _, m := range updated.ModelList {
if strings.HasPrefix(m.Model, "openai/") && m.AuthMethod != "" {
t.Fatalf("openai model auth_method = %q, want empty", m.AuthMethod)
@@ -233,12 +229,18 @@ func setupOAuthTestEnv(t *testing.T) (string, func()) {
}
cfg := config.DefaultConfig()
- cfg.ModelList = []config.ModelConfig{{
+ cfg.ModelList = []*config.ModelConfig{{
ModelName: "custom-default",
Model: "openai/gpt-4o",
- APIKey: "sk-default",
}}
cfg.Agents.Defaults.ModelName = "custom-default"
+ cfg.WithSecurity(&config.SecurityConfig{
+ ModelList: map[string]config.ModelSecurityEntry{
+ "custom-default": {
+ APIKeys: []string{"sk-default"},
+ },
+ },
+ })
configPath := filepath.Join(tmp, "config.json")
if err := config.SaveConfig(configPath, cfg); err != nil {
diff --git a/web/backend/api/pico.go b/web/backend/api/pico.go
index a880f2f0c..8fbb8737f 100644
--- a/web/backend/api/pico.go
+++ b/web/backend/api/pico.go
@@ -57,7 +57,7 @@ func (h *Handler) handleGetPicoToken(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]any{
- "token": cfg.Channels.Pico.Token,
+ "token": cfg.Channels.Pico.Token(),
"ws_url": wsURL,
"enabled": cfg.Channels.Pico.Enabled,
})
@@ -74,7 +74,7 @@ func (h *Handler) handleRegenPicoToken(w http.ResponseWriter, r *http.Request) {
}
token := generateSecureToken()
- cfg.Channels.Pico.Token = token
+ cfg.Channels.Pico.SetToken(token)
if err := config.SaveConfig(h.configPath, cfg); err != nil {
http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
@@ -110,8 +110,8 @@ func (h *Handler) ensurePicoChannel(callerOrigin string) (bool, error) {
changed = true
}
- if cfg.Channels.Pico.Token == "" {
- cfg.Channels.Pico.Token = generateSecureToken()
+ if cfg.Channels.Pico.Token() == "" {
+ cfg.Channels.Pico.SetToken(generateSecureToken())
changed = true
}
@@ -150,7 +150,7 @@ func (h *Handler) handlePicoSetup(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]any{
- "token": cfg.Channels.Pico.Token,
+ "token": cfg.Channels.Pico.Token(),
"ws_url": wsURL,
"enabled": true,
"changed": changed,
diff --git a/web/backend/api/pico_test.go b/web/backend/api/pico_test.go
index 075da4ddc..263253cb2 100644
--- a/web/backend/api/pico_test.go
+++ b/web/backend/api/pico_test.go
@@ -33,7 +33,7 @@ func TestEnsurePicoChannel_FreshConfig(t *testing.T) {
if !cfg.Channels.Pico.Enabled {
t.Error("expected Pico to be enabled after setup")
}
- if cfg.Channels.Pico.Token == "" {
+ if cfg.Channels.Pico.Token() == "" {
t.Error("expected a non-empty token after setup")
}
}
@@ -121,7 +121,7 @@ func TestEnsurePicoChannel_PreservesUserSettings(t *testing.T) {
// Pre-configure with custom user settings
cfg := config.DefaultConfig()
cfg.Channels.Pico.Enabled = true
- cfg.Channels.Pico.Token = "user-custom-token"
+ cfg.Channels.Pico.SetToken("user-custom-token")
cfg.Channels.Pico.AllowTokenQuery = true
cfg.Channels.Pico.AllowOrigins = []string{"https://myapp.example.com"}
if err := config.SaveConfig(configPath, cfg); err != nil {
@@ -143,8 +143,8 @@ func TestEnsurePicoChannel_PreservesUserSettings(t *testing.T) {
t.Fatalf("LoadConfig() error = %v", err)
}
- if cfg.Channels.Pico.Token != "user-custom-token" {
- t.Errorf("token = %q, want %q", cfg.Channels.Pico.Token, "user-custom-token")
+ if cfg.Channels.Pico.Token() != "user-custom-token" {
+ t.Errorf("token = %q, want %q", cfg.Channels.Pico.Token(), "user-custom-token")
}
if !cfg.Channels.Pico.AllowTokenQuery {
t.Error("user's allow_token_query=true must be preserved")
@@ -166,7 +166,7 @@ func TestEnsurePicoChannel_Idempotent(t *testing.T) {
}
cfg1, _ := config.LoadConfig(configPath)
- token1 := cfg1.Channels.Pico.Token
+ token1 := cfg1.Channels.Pico.Token()
// Second call should be a no-op
changed, err := h.ensurePicoChannel(origin)
@@ -178,7 +178,7 @@ func TestEnsurePicoChannel_Idempotent(t *testing.T) {
}
cfg2, _ := config.LoadConfig(configPath)
- if cfg2.Channels.Pico.Token != token1 {
+ if cfg2.Channels.Pico.Token() != token1 {
t.Error("token should not change on subsequent calls")
}
}
diff --git a/web/backend/main.go b/web/backend/main.go
index b1db3c57a..8183731fe 100644
--- a/web/backend/main.go
+++ b/web/backend/main.go
@@ -33,6 +33,10 @@ import (
const (
appName = "PicoClaw"
+
+ logPath = "logs"
+ panicFile = "launcher_panic.log"
+ logFile = "launcher.log"
)
var (
@@ -72,6 +76,14 @@ func main() {
// Initialize logger
picoHome := utils.GetPicoclawHome()
+
+ f := filepath.Join(picoHome, logPath, panicFile)
+ panicFunc, err := logger.InitPanic(f)
+ if err != nil {
+ panic(fmt.Sprintf("error initializing panic log: %v", err))
+ }
+ defer panicFunc()
+
// By default, detect terminal to decide console log behavior
// If -console-logs flag is explicitly set, it overrides the detection
enableConsole := *console
@@ -79,11 +91,9 @@ func main() {
// Disable console logging by setting level to Fatal (no output)
logger.SetConsoleLevel(logger.FATAL)
- logPath := filepath.Join(picoHome, "logs", "web.log")
- if err := logger.EnableFileLogging(logPath); err != nil {
- // FIXME: https://github.com/sipeed/picoclaw/issues/1734
- fmt.Fprintf(os.Stderr, "Failed to initialize logger: %v\n", err)
- os.Exit(1)
+ f := filepath.Join(picoHome, logPath, logFile)
+ if err = logger.EnableFileLogging(f); err != nil {
+ panic(fmt.Sprintf("error enabling file logging: %v", err))
}
defer logger.DisableFileLogging()
}
diff --git a/web/frontend/package.json b/web/frontend/package.json
index 2e0e37117..8053d1f2a 100644
--- a/web/frontend/package.json
+++ b/web/frontend/package.json
@@ -14,8 +14,8 @@
},
"dependencies": {
"@fontsource-variable/inter": "^5.2.8",
- "@tabler/icons-react": "^3.38.0",
- "@tailwindcss/vite": "^4.2.1",
+ "@tabler/icons-react": "^3.40.0",
+ "@tailwindcss/vite": "^4.2.2",
"@tanstack/react-query": "^5.90.21",
"@tanstack/react-router": "^1.167.0",
"@tanstack/react-router-devtools": "^1.163.3",
@@ -31,33 +31,35 @@
"react-i18next": "^16.5.8",
"react-markdown": "^10.1.0",
"react-textarea-autosize": "^8.5.9",
+ "rehype-raw": "^7.0.0",
+ "rehype-sanitize": "^6.0.0",
"remark-gfm": "^4.0.1",
- "shadcn": "^4.0.5",
+ "shadcn": "^4.1.0",
"sonner": "^2.0.7",
"tailwind-merge": "^3.5.0",
- "tailwindcss": "^4.2.1",
+ "tailwindcss": "^4.2.2",
"tw-animate-css": "^1.4.0",
"wrap-ansi": "^10.0.0"
},
"devDependencies": {
- "@eslint/js": "^9.39.3",
+ "@eslint/js": "^9.39.4",
"@tailwindcss/typography": "^0.5.19",
"@tanstack/router-plugin": "^1.164.0",
"@trivago/prettier-plugin-sort-imports": "^6.0.2",
- "@types/node": "^24.10.1",
+ "@types/node": "^25.5.0",
"@types/react": "^19.2.7",
"@types/react-dom": "^19.2.3",
- "@typescript-eslint/eslint-plugin": "^8.56.1",
+ "@typescript-eslint/eslint-plugin": "^8.57.1",
"@vitejs/plugin-react": "^5.2.0",
- "eslint": "^9.39.3",
+ "eslint": "^9.39.4",
"eslint-config-prettier": "^10.1.8",
"eslint-plugin-react-hooks": "^7.0.1",
- "eslint-plugin-react-refresh": "^0.4.24",
+ "eslint-plugin-react-refresh": "^0.4.26",
"globals": "^16.5.0",
"prettier": "^3.8.1",
"prettier-plugin-tailwindcss": "^0.7.2",
"typescript": "~5.9.3",
- "typescript-eslint": "^8.48.0",
+ "typescript-eslint": "^8.57.1",
"vite": "^7.3.1"
}
}
diff --git a/web/frontend/pnpm-lock.yaml b/web/frontend/pnpm-lock.yaml
index 20f0a7342..edaf49ccc 100644
--- a/web/frontend/pnpm-lock.yaml
+++ b/web/frontend/pnpm-lock.yaml
@@ -12,20 +12,20 @@ importers:
specifier: ^5.2.8
version: 5.2.8
'@tabler/icons-react':
- specifier: ^3.38.0
- version: 3.38.0(react@19.2.4)
+ specifier: ^3.40.0
+ version: 3.40.0(react@19.2.4)
'@tailwindcss/vite':
- specifier: ^4.2.1
- version: 4.2.1(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))
+ specifier: ^4.2.2
+ version: 4.2.2(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))
'@tanstack/react-query':
specifier: ^5.90.21
- version: 5.90.21(react@19.2.4)
+ version: 5.91.2(react@19.2.4)
'@tanstack/react-router':
specifier: ^1.167.0
- version: 1.167.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+ version: 1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
'@tanstack/react-router-devtools':
specifier: ^1.163.3
- version: 1.163.3(@tanstack/react-router@1.167.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@tanstack/router-core@1.167.0)(csstype@3.2.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+ version: 1.166.9(@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@tanstack/router-core@1.167.5)(csstype@3.2.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
class-variance-authority:
specifier: ^0.7.1
version: 0.7.1
@@ -37,7 +37,7 @@ importers:
version: 1.11.20
i18next:
specifier: ^25.8.14
- version: 25.8.14(typescript@5.9.3)
+ version: 25.8.20(typescript@5.9.3)
i18next-browser-languagedetector:
specifier: ^8.2.1
version: 8.2.1
@@ -55,19 +55,25 @@ importers:
version: 19.2.4(react@19.2.4)
react-i18next:
specifier: ^16.5.8
- version: 16.5.8(i18next@25.8.14(typescript@5.9.3))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)
+ version: 16.5.8(i18next@25.8.20(typescript@5.9.3))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)
react-markdown:
specifier: ^10.1.0
version: 10.1.0(@types/react@19.2.14)(react@19.2.4)
react-textarea-autosize:
specifier: ^8.5.9
version: 8.5.9(@types/react@19.2.14)(react@19.2.4)
+ rehype-raw:
+ specifier: ^7.0.0
+ version: 7.0.0
+ rehype-sanitize:
+ specifier: ^6.0.0
+ version: 6.0.0
remark-gfm:
specifier: ^4.0.1
version: 4.0.1
shadcn:
- specifier: ^4.0.5
- version: 4.0.5(@types/node@24.11.0)(typescript@5.9.3)
+ specifier: ^4.1.0
+ version: 4.1.0(@types/node@25.5.0)(typescript@5.9.3)
sonner:
specifier: ^2.0.7
version: 2.0.7(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -75,8 +81,8 @@ importers:
specifier: ^3.5.0
version: 3.5.0
tailwindcss:
- specifier: ^4.2.1
- version: 4.2.1
+ specifier: ^4.2.2
+ version: 4.2.2
tw-animate-css:
specifier: ^1.4.0
version: 1.4.0
@@ -85,20 +91,20 @@ importers:
version: 10.0.0
devDependencies:
'@eslint/js':
- specifier: ^9.39.3
- version: 9.39.3
+ specifier: ^9.39.4
+ version: 9.39.4
'@tailwindcss/typography':
specifier: ^0.5.19
- version: 0.5.19(tailwindcss@4.2.1)
+ version: 0.5.19(tailwindcss@4.2.2)
'@tanstack/router-plugin':
specifier: ^1.164.0
- version: 1.164.0(@tanstack/react-router@1.167.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))
+ version: 1.166.14(@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))
'@trivago/prettier-plugin-sort-imports':
specifier: ^6.0.2
version: 6.0.2(prettier@3.8.1)
'@types/node':
- specifier: ^24.10.1
- version: 24.11.0
+ specifier: ^25.5.0
+ version: 25.5.0
'@types/react':
specifier: ^19.2.7
version: 19.2.14
@@ -106,23 +112,23 @@ importers:
specifier: ^19.2.3
version: 19.2.3(@types/react@19.2.14)
'@typescript-eslint/eslint-plugin':
- specifier: ^8.56.1
- version: 8.56.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+ specifier: ^8.57.1
+ version: 8.57.1(@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
'@vitejs/plugin-react':
specifier: ^5.2.0
- version: 5.2.0(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))
+ version: 5.2.0(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))
eslint:
- specifier: ^9.39.3
- version: 9.39.3(jiti@2.6.1)
+ specifier: ^9.39.4
+ version: 9.39.4(jiti@2.6.1)
eslint-config-prettier:
specifier: ^10.1.8
- version: 10.1.8(eslint@9.39.3(jiti@2.6.1))
+ version: 10.1.8(eslint@9.39.4(jiti@2.6.1))
eslint-plugin-react-hooks:
specifier: ^7.0.1
- version: 7.0.1(eslint@9.39.3(jiti@2.6.1))
+ version: 7.0.1(eslint@9.39.4(jiti@2.6.1))
eslint-plugin-react-refresh:
- specifier: ^0.4.24
- version: 0.4.26(eslint@9.39.3(jiti@2.6.1))
+ specifier: ^0.4.26
+ version: 0.4.26(eslint@9.39.4(jiti@2.6.1))
globals:
specifier: ^16.5.0
version: 16.5.0
@@ -136,18 +142,14 @@ importers:
specifier: ~5.9.3
version: 5.9.3
typescript-eslint:
- specifier: ^8.48.0
- version: 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+ specifier: ^8.57.1
+ version: 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
vite:
specifier: ^7.3.1
- version: 7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0)
+ version: 7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
packages:
- '@antfu/ni@25.0.0':
- resolution: {integrity: sha512-9q/yCljni37pkMr4sPrI3G4jqdIk074+iukc5aFJl7kmDCCsiJrbZ6zKxnES1Gwg+i9RcDZwvktl23puGslmvA==}
- hasBin: true
-
'@babel/code-frame@7.29.0':
resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
engines: {node: '>=6.9.0'}
@@ -226,12 +228,12 @@ packages:
resolution: {integrity: sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==}
engines: {node: '>=6.9.0'}
- '@babel/helpers@7.28.6':
- resolution: {integrity: sha512-xOBvwq86HHdB7WUDTfKfT/Vuxh7gElQ+Sfti2Cy6yIWNW05P8iUslOVcZ4/sKbE+/jQaukQAdz/gf3724kYdqw==}
+ '@babel/helpers@7.29.2':
+ resolution: {integrity: sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==}
engines: {node: '>=6.9.0'}
- '@babel/parser@7.29.0':
- resolution: {integrity: sha512-IyDgFV5GeDUVX4YdF/3CPULtVGSXXMLh1xVIgdCgxApktqnQV0r7/8Nqthg+8YLGaAtdyIlo2qIdZrbCv4+7ww==}
+ '@babel/parser@7.29.2':
+ resolution: {integrity: sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==}
engines: {node: '>=6.0.0'}
hasBin: true
@@ -277,8 +279,8 @@ packages:
peerDependencies:
'@babel/core': ^7.0.0-0
- '@babel/runtime@7.28.6':
- resolution: {integrity: sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==}
+ '@babel/runtime@7.29.2':
+ resolution: {integrity: sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==}
engines: {node: '>=6.9.0'}
'@babel/template@7.28.6':
@@ -293,8 +295,8 @@ packages:
resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
engines: {node: '>=6.9.0'}
- '@dotenvx/dotenvx@1.52.0':
- resolution: {integrity: sha512-CaQcc8JvtzQhUSm9877b6V4Tb7HCotkcyud9X2YwdqtQKwgljkMRwU96fVYKnzN3V0Hj74oP7Es+vZ0mS+Aa1w==}
+ '@dotenvx/dotenvx@1.57.0':
+ resolution: {integrity: sha512-WsTEcqfHzKmLFZh3jLGd7o4iCkrIupp+qFH2FJUJtQXUh2GcOnLXD00DcrhlO4H8QSmaKnW9lugOEbrdpu25kA==}
hasBin: true
'@ecies/ciphers@0.2.5':
@@ -303,158 +305,158 @@ packages:
peerDependencies:
'@noble/ciphers': ^1.0.0
- '@esbuild/aix-ppc64@0.27.3':
- resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
+ '@esbuild/aix-ppc64@0.27.4':
+ resolution: {integrity: sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==}
engines: {node: '>=18'}
cpu: [ppc64]
os: [aix]
- '@esbuild/android-arm64@0.27.3':
- resolution: {integrity: sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==}
+ '@esbuild/android-arm64@0.27.4':
+ resolution: {integrity: sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==}
engines: {node: '>=18'}
cpu: [arm64]
os: [android]
- '@esbuild/android-arm@0.27.3':
- resolution: {integrity: sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==}
+ '@esbuild/android-arm@0.27.4':
+ resolution: {integrity: sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==}
engines: {node: '>=18'}
cpu: [arm]
os: [android]
- '@esbuild/android-x64@0.27.3':
- resolution: {integrity: sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==}
+ '@esbuild/android-x64@0.27.4':
+ resolution: {integrity: sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==}
engines: {node: '>=18'}
cpu: [x64]
os: [android]
- '@esbuild/darwin-arm64@0.27.3':
- resolution: {integrity: sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==}
+ '@esbuild/darwin-arm64@0.27.4':
+ resolution: {integrity: sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==}
engines: {node: '>=18'}
cpu: [arm64]
os: [darwin]
- '@esbuild/darwin-x64@0.27.3':
- resolution: {integrity: sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==}
+ '@esbuild/darwin-x64@0.27.4':
+ resolution: {integrity: sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==}
engines: {node: '>=18'}
cpu: [x64]
os: [darwin]
- '@esbuild/freebsd-arm64@0.27.3':
- resolution: {integrity: sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==}
+ '@esbuild/freebsd-arm64@0.27.4':
+ resolution: {integrity: sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==}
engines: {node: '>=18'}
cpu: [arm64]
os: [freebsd]
- '@esbuild/freebsd-x64@0.27.3':
- resolution: {integrity: sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==}
+ '@esbuild/freebsd-x64@0.27.4':
+ resolution: {integrity: sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==}
engines: {node: '>=18'}
cpu: [x64]
os: [freebsd]
- '@esbuild/linux-arm64@0.27.3':
- resolution: {integrity: sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==}
+ '@esbuild/linux-arm64@0.27.4':
+ resolution: {integrity: sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==}
engines: {node: '>=18'}
cpu: [arm64]
os: [linux]
- '@esbuild/linux-arm@0.27.3':
- resolution: {integrity: sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==}
+ '@esbuild/linux-arm@0.27.4':
+ resolution: {integrity: sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==}
engines: {node: '>=18'}
cpu: [arm]
os: [linux]
- '@esbuild/linux-ia32@0.27.3':
- resolution: {integrity: sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==}
+ '@esbuild/linux-ia32@0.27.4':
+ resolution: {integrity: sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==}
engines: {node: '>=18'}
cpu: [ia32]
os: [linux]
- '@esbuild/linux-loong64@0.27.3':
- resolution: {integrity: sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==}
+ '@esbuild/linux-loong64@0.27.4':
+ resolution: {integrity: sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==}
engines: {node: '>=18'}
cpu: [loong64]
os: [linux]
- '@esbuild/linux-mips64el@0.27.3':
- resolution: {integrity: sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==}
+ '@esbuild/linux-mips64el@0.27.4':
+ resolution: {integrity: sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==}
engines: {node: '>=18'}
cpu: [mips64el]
os: [linux]
- '@esbuild/linux-ppc64@0.27.3':
- resolution: {integrity: sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==}
+ '@esbuild/linux-ppc64@0.27.4':
+ resolution: {integrity: sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==}
engines: {node: '>=18'}
cpu: [ppc64]
os: [linux]
- '@esbuild/linux-riscv64@0.27.3':
- resolution: {integrity: sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==}
+ '@esbuild/linux-riscv64@0.27.4':
+ resolution: {integrity: sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==}
engines: {node: '>=18'}
cpu: [riscv64]
os: [linux]
- '@esbuild/linux-s390x@0.27.3':
- resolution: {integrity: sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==}
+ '@esbuild/linux-s390x@0.27.4':
+ resolution: {integrity: sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==}
engines: {node: '>=18'}
cpu: [s390x]
os: [linux]
- '@esbuild/linux-x64@0.27.3':
- resolution: {integrity: sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==}
+ '@esbuild/linux-x64@0.27.4':
+ resolution: {integrity: sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==}
engines: {node: '>=18'}
cpu: [x64]
os: [linux]
- '@esbuild/netbsd-arm64@0.27.3':
- resolution: {integrity: sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==}
+ '@esbuild/netbsd-arm64@0.27.4':
+ resolution: {integrity: sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==}
engines: {node: '>=18'}
cpu: [arm64]
os: [netbsd]
- '@esbuild/netbsd-x64@0.27.3':
- resolution: {integrity: sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==}
+ '@esbuild/netbsd-x64@0.27.4':
+ resolution: {integrity: sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==}
engines: {node: '>=18'}
cpu: [x64]
os: [netbsd]
- '@esbuild/openbsd-arm64@0.27.3':
- resolution: {integrity: sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==}
+ '@esbuild/openbsd-arm64@0.27.4':
+ resolution: {integrity: sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==}
engines: {node: '>=18'}
cpu: [arm64]
os: [openbsd]
- '@esbuild/openbsd-x64@0.27.3':
- resolution: {integrity: sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==}
+ '@esbuild/openbsd-x64@0.27.4':
+ resolution: {integrity: sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==}
engines: {node: '>=18'}
cpu: [x64]
os: [openbsd]
- '@esbuild/openharmony-arm64@0.27.3':
- resolution: {integrity: sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==}
+ '@esbuild/openharmony-arm64@0.27.4':
+ resolution: {integrity: sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==}
engines: {node: '>=18'}
cpu: [arm64]
os: [openharmony]
- '@esbuild/sunos-x64@0.27.3':
- resolution: {integrity: sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==}
+ '@esbuild/sunos-x64@0.27.4':
+ resolution: {integrity: sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==}
engines: {node: '>=18'}
cpu: [x64]
os: [sunos]
- '@esbuild/win32-arm64@0.27.3':
- resolution: {integrity: sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==}
+ '@esbuild/win32-arm64@0.27.4':
+ resolution: {integrity: sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==}
engines: {node: '>=18'}
cpu: [arm64]
os: [win32]
- '@esbuild/win32-ia32@0.27.3':
- resolution: {integrity: sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==}
+ '@esbuild/win32-ia32@0.27.4':
+ resolution: {integrity: sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==}
engines: {node: '>=18'}
cpu: [ia32]
os: [win32]
- '@esbuild/win32-x64@0.27.3':
- resolution: {integrity: sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==}
+ '@esbuild/win32-x64@0.27.4':
+ resolution: {integrity: sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==}
engines: {node: '>=18'}
cpu: [x64]
os: [win32]
@@ -485,8 +487,8 @@ packages:
resolution: {integrity: sha512-4IlJx0X0qftVsN5E+/vGujTRIFtwuLbNsVUe7TO6zYPDR1O6nFwvwhIKEKSrl6dZchmYBITazxKoUYOjdtjlRg==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
- '@eslint/js@9.39.3':
- resolution: {integrity: sha512-1B1VkCq6FuUNlQvlBYb+1jDu/gV297TIs/OeiaSR9l1H27SVW55ONE1e1Vp16NqP683+xEGzxYtv4XCiDPaQiw==}
+ '@eslint/js@9.39.4':
+ resolution: {integrity: sha512-nE7DEIchvtiFTwBw4Lfbu59PG+kCofhjsKaCWzxTpt4lfRjRMqG6uMBzKXuEcyXhOHoUp9riAm7/aWYGhXZ9cw==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
'@eslint/object-schema@2.1.7':
@@ -497,20 +499,20 @@ packages:
resolution: {integrity: sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
- '@floating-ui/core@1.7.4':
- resolution: {integrity: sha512-C3HlIdsBxszvm5McXlB8PeOEWfBhcGBTZGkGlWc2U0KFY5IwG5OQEuQ8rq52DZmcHDlPLd+YFBK+cZcytwIFWg==}
+ '@floating-ui/core@1.7.5':
+ resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==}
- '@floating-ui/dom@1.7.5':
- resolution: {integrity: sha512-N0bD2kIPInNHUHehXhMke1rBGs1dwqvC9O9KYMyyjK7iXt7GAhnro7UlcuYcGdS/yYOlq0MAVgrow8IbWJwyqg==}
+ '@floating-ui/dom@1.7.6':
+ resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==}
- '@floating-ui/react-dom@2.1.7':
- resolution: {integrity: sha512-0tLRojf/1Go2JgEVm+3Frg9A3IW8bJgKgdO0BN5RkF//ufuz2joZM63Npau2ff3J6lUVYgDSNzNkR+aH3IVfjg==}
+ '@floating-ui/react-dom@2.1.8':
+ resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==}
peerDependencies:
react: '>=16.8.0'
react-dom: '>=16.8.0'
- '@floating-ui/utils@0.2.10':
- resolution: {integrity: sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ==}
+ '@floating-ui/utils@0.2.11':
+ resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
'@fontsource-variable/inter@5.2.8':
resolution: {integrity: sha512-kOfP2D+ykbcX/P3IFnokOhVRNoTozo5/JxhAIVYLpea/UBmCQ/YWPBfWIDuBImXX/15KH+eKh4xpEUyS2sQQGQ==}
@@ -1460,73 +1462,73 @@ packages:
resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
engines: {node: '>=18'}
- '@tabler/icons-react@3.38.0':
- resolution: {integrity: sha512-kR5wv+m4+GgmnSszg3rQd6SrTFAQ/XnQC/yTwIfuRJSfqB12KoIC7fPbIijFgOHTFlBN5DARnN0IVrR7KYG6/A==}
+ '@tabler/icons-react@3.40.0':
+ resolution: {integrity: sha512-oO5+6QCnna4a//mYubx4euZfECtzQZFDGsDMIdzZUhbdyBCT+3bRVFBPueGIcemWld4Vb/0UQ39C/cmGfGylAg==}
peerDependencies:
react: '>= 16'
- '@tabler/icons@3.38.0':
- resolution: {integrity: sha512-FdETQSpQ3lN7BEjEUzjKhsfTDCamrvMDops4HEMphTm3DmkIFpThoODn8XXZ8Q9MhjshIvphIYVHHB7zpq167w==}
+ '@tabler/icons@3.40.0':
+ resolution: {integrity: sha512-V/Q4VgNPKubRTiLdmWjV/zscYcj5IIk+euicUtaVVqF6luSC9rDngYWgST5/yh3Mrg/mYUwRv1YVTk71Jp0twQ==}
- '@tailwindcss/node@4.2.1':
- resolution: {integrity: sha512-jlx6sLk4EOwO6hHe1oCGm1Q4AN/s0rSrTTPBGPM0/RQ6Uylwq17FuU8IeJJKEjtc6K6O07zsvP+gDO6MMWo7pg==}
+ '@tailwindcss/node@4.2.2':
+ resolution: {integrity: sha512-pXS+wJ2gZpVXqFaUEjojq7jzMpTGf8rU6ipJz5ovJV6PUGmlJ+jvIwGrzdHdQ80Sg+wmQxUFuoW1UAAwHNEdFA==}
- '@tailwindcss/oxide-android-arm64@4.2.1':
- resolution: {integrity: sha512-eZ7G1Zm5EC8OOKaesIKuw77jw++QJ2lL9N+dDpdQiAB/c/B2wDh0QPFHbkBVrXnwNugvrbJFk1gK2SsVjwWReg==}
+ '@tailwindcss/oxide-android-arm64@4.2.2':
+ resolution: {integrity: sha512-dXGR1n+P3B6748jZO/SvHZq7qBOqqzQ+yFrXpoOWWALWndF9MoSKAT3Q0fYgAzYzGhxNYOoysRvYlpixRBBoDg==}
engines: {node: '>= 20'}
cpu: [arm64]
os: [android]
- '@tailwindcss/oxide-darwin-arm64@4.2.1':
- resolution: {integrity: sha512-q/LHkOstoJ7pI1J0q6djesLzRvQSIfEto148ppAd+BVQK0JYjQIFSK3JgYZJa+Yzi0DDa52ZsQx2rqytBnf8Hw==}
+ '@tailwindcss/oxide-darwin-arm64@4.2.2':
+ resolution: {integrity: sha512-iq9Qjr6knfMpZHj55/37ouZeykwbDqF21gPFtfnhCCKGDcPI/21FKC9XdMO/XyBM7qKORx6UIhGgg6jLl7BZlg==}
engines: {node: '>= 20'}
cpu: [arm64]
os: [darwin]
- '@tailwindcss/oxide-darwin-x64@4.2.1':
- resolution: {integrity: sha512-/f/ozlaXGY6QLbpvd/kFTro2l18f7dHKpB+ieXz+Cijl4Mt9AI2rTrpq7V+t04nK+j9XBQHnSMdeQRhbGyt6fw==}
+ '@tailwindcss/oxide-darwin-x64@4.2.2':
+ resolution: {integrity: sha512-BlR+2c3nzc8f2G639LpL89YY4bdcIdUmiOOkv2GQv4/4M0vJlpXEa0JXNHhCHU7VWOKWT/CjqHdTP8aUuDJkuw==}
engines: {node: '>= 20'}
cpu: [x64]
os: [darwin]
- '@tailwindcss/oxide-freebsd-x64@4.2.1':
- resolution: {integrity: sha512-5e/AkgYJT/cpbkys/OU2Ei2jdETCLlifwm7ogMC7/hksI2fC3iiq6OcXwjibcIjPung0kRtR3TxEITkqgn0TcA==}
+ '@tailwindcss/oxide-freebsd-x64@4.2.2':
+ resolution: {integrity: sha512-YUqUgrGMSu2CDO82hzlQ5qSb5xmx3RUrke/QgnoEx7KvmRJHQuZHZmZTLSuuHwFf0DJPybFMXMYf+WJdxHy/nQ==}
engines: {node: '>= 20'}
cpu: [x64]
os: [freebsd]
- '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.1':
- resolution: {integrity: sha512-Uny1EcVTTmerCKt/1ZuKTkb0x8ZaiuYucg2/kImO5A5Y/kBz41/+j0gxUZl+hTF3xkWpDmHX+TaWhOtba2Fyuw==}
+ '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.2':
+ resolution: {integrity: sha512-FPdhvsW6g06T9BWT0qTwiVZYE2WIFo2dY5aCSpjG/S/u1tby+wXoslXS0kl3/KXnULlLr1E3NPRRw0g7t2kgaQ==}
engines: {node: '>= 20'}
cpu: [arm]
os: [linux]
- '@tailwindcss/oxide-linux-arm64-gnu@4.2.1':
- resolution: {integrity: sha512-CTrwomI+c7n6aSSQlsPL0roRiNMDQ/YzMD9EjcR+H4f0I1SQ8QqIuPnsVp7QgMkC1Qi8rtkekLkOFjo7OlEFRQ==}
+ '@tailwindcss/oxide-linux-arm64-gnu@4.2.2':
+ resolution: {integrity: sha512-4og1V+ftEPXGttOO7eCmW7VICmzzJWgMx+QXAJRAhjrSjumCwWqMfkDrNu1LXEQzNAwz28NCUpucgQPrR4S2yw==}
engines: {node: '>= 20'}
cpu: [arm64]
os: [linux]
- '@tailwindcss/oxide-linux-arm64-musl@4.2.1':
- resolution: {integrity: sha512-WZA0CHRL/SP1TRbA5mp9htsppSEkWuQ4KsSUumYQnyl8ZdT39ntwqmz4IUHGN6p4XdSlYfJwM4rRzZLShHsGAQ==}
+ '@tailwindcss/oxide-linux-arm64-musl@4.2.2':
+ resolution: {integrity: sha512-oCfG/mS+/+XRlwNjnsNLVwnMWYH7tn/kYPsNPh+JSOMlnt93mYNCKHYzylRhI51X+TbR+ufNhhKKzm6QkqX8ag==}
engines: {node: '>= 20'}
cpu: [arm64]
os: [linux]
- '@tailwindcss/oxide-linux-x64-gnu@4.2.1':
- resolution: {integrity: sha512-qMFzxI2YlBOLW5PhblzuSWlWfwLHaneBE0xHzLrBgNtqN6mWfs+qYbhryGSXQjFYB1Dzf5w+LN5qbUTPhW7Y5g==}
+ '@tailwindcss/oxide-linux-x64-gnu@4.2.2':
+ resolution: {integrity: sha512-rTAGAkDgqbXHNp/xW0iugLVmX62wOp2PoE39BTCGKjv3Iocf6AFbRP/wZT/kuCxC9QBh9Pu8XPkv/zCZB2mcMg==}
engines: {node: '>= 20'}
cpu: [x64]
os: [linux]
- '@tailwindcss/oxide-linux-x64-musl@4.2.1':
- resolution: {integrity: sha512-5r1X2FKnCMUPlXTWRYpHdPYUY6a1Ar/t7P24OuiEdEOmms5lyqjDRvVY1yy9Rmioh+AunQ0rWiOTPE8F9A3v5g==}
+ '@tailwindcss/oxide-linux-x64-musl@4.2.2':
+ resolution: {integrity: sha512-XW3t3qwbIwiSyRCggeO2zxe3KWaEbM0/kW9e8+0XpBgyKU4ATYzcVSMKteZJ1iukJ3HgHBjbg9P5YPRCVUxlnQ==}
engines: {node: '>= 20'}
cpu: [x64]
os: [linux]
- '@tailwindcss/oxide-wasm32-wasi@4.2.1':
- resolution: {integrity: sha512-MGFB5cVPvshR85MTJkEvqDUnuNoysrsRxd6vnk1Lf2tbiqNlXpHYZqkqOQalydienEWOHHFyyuTSYRsLfxFJ2Q==}
+ '@tailwindcss/oxide-wasm32-wasi@4.2.2':
+ resolution: {integrity: sha512-eKSztKsmEsn1O5lJ4ZAfyn41NfG7vzCg496YiGtMDV86jz1q/irhms5O0VrY6ZwTUkFy/EKG3RfWgxSI3VbZ8Q==}
engines: {node: '>=14.0.0'}
cpu: [wasm32]
bundledDependencies:
@@ -1537,20 +1539,20 @@ packages:
- '@emnapi/wasi-threads'
- tslib
- '@tailwindcss/oxide-win32-arm64-msvc@4.2.1':
- resolution: {integrity: sha512-YlUEHRHBGnCMh4Nj4GnqQyBtsshUPdiNroZj8VPkvTZSoHsilRCwXcVKnG9kyi0ZFAS/3u+qKHBdDc81SADTRA==}
+ '@tailwindcss/oxide-win32-arm64-msvc@4.2.2':
+ resolution: {integrity: sha512-qPmaQM4iKu5mxpsrWZMOZRgZv1tOZpUm+zdhhQP0VhJfyGGO3aUKdbh3gDZc/dPLQwW4eSqWGrrcWNBZWUWaXQ==}
engines: {node: '>= 20'}
cpu: [arm64]
os: [win32]
- '@tailwindcss/oxide-win32-x64-msvc@4.2.1':
- resolution: {integrity: sha512-rbO34G5sMWWyrN/idLeVxAZgAKWrn5LiR3/I90Q9MkA67s6T1oB0xtTe+0heoBvHSpbU9Mk7i6uwJnpo4u21XQ==}
+ '@tailwindcss/oxide-win32-x64-msvc@4.2.2':
+ resolution: {integrity: sha512-1T/37VvI7WyH66b+vqHj/cLwnCxt7Qt3WFu5Q8hk65aOvlwAhs7rAp1VkulBJw/N4tMirXjVnylTR72uI0HGcA==}
engines: {node: '>= 20'}
cpu: [x64]
os: [win32]
- '@tailwindcss/oxide@4.2.1':
- resolution: {integrity: sha512-yv9jeEFWnjKCI6/T3Oq50yQEOqmpmpfzG1hcZsAOaXFQPfzWprWrlHSdGPEF3WQTi8zu8ohC9Mh9J470nT5pUw==}
+ '@tailwindcss/oxide@4.2.2':
+ resolution: {integrity: sha512-qEUA07+E5kehxYp9BVMpq9E8vnJuBHfJEC0vPC5e7iL/hw7HR61aDKoVoKzrG+QKp56vhNZe4qwkRmMC0zDLvg==}
engines: {node: '>= 20'}
'@tailwindcss/typography@0.5.19':
@@ -1558,37 +1560,37 @@ packages:
peerDependencies:
tailwindcss: '>=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1'
- '@tailwindcss/vite@4.2.1':
- resolution: {integrity: sha512-TBf2sJjYeb28jD2U/OhwdW0bbOsxkWPwQ7SrqGf9sVcoYwZj7rkXljroBO9wKBut9XnmQLXanuDUeqQK0lGg/w==}
+ '@tailwindcss/vite@4.2.2':
+ resolution: {integrity: sha512-mEiF5HO1QqCLXoNEfXVA1Tzo+cYsrqV7w9Juj2wdUFyW07JRenqMG225MvPwr3ZD9N1bFQj46X7r33iHxLUW0w==}
peerDependencies:
- vite: ^5.2.0 || ^6 || ^7
+ vite: ^5.2.0 || ^6 || ^7 || ^8
- '@tanstack/history@1.161.4':
- resolution: {integrity: sha512-Kp/WSt411ZWYvgXy6uiv5RmhHrz9cAml05AQPrtdAp7eUqvIDbMGPnML25OKbzR3RJ1q4wgENxDTvlGPa9+Mww==}
+ '@tanstack/history@1.161.6':
+ resolution: {integrity: sha512-NaOGLRrddszbQj9upGat6HG/4TKvXLvu+osAIgfxPYA+eIvYKv8GKDJOrY2D3/U9MRnKfMWD7bU4jeD4xmqyIg==}
engines: {node: '>=20.19'}
- '@tanstack/query-core@5.90.20':
- resolution: {integrity: sha512-OMD2HLpNouXEfZJWcKeVKUgQ5n+n3A2JFmBaScpNDUqSrQSjiveC7dKMe53uJUg1nDG16ttFPz2xfilz6i2uVg==}
+ '@tanstack/query-core@5.91.2':
+ resolution: {integrity: sha512-Uz2pTgPC1mhqrrSGg18RKCWT/pkduAYtxbcyIyKBhw7dTWjXZIzqmpzO2lBkyWr4hlImQgpu1m1pei3UnkFRWw==}
- '@tanstack/react-query@5.90.21':
- resolution: {integrity: sha512-0Lu6y5t+tvlTJMTO7oh5NSpJfpg/5D41LlThfepTixPYkJ0sE2Jj0m0f6yYqujBwIXlId87e234+MxG3D3g7kg==}
+ '@tanstack/react-query@5.91.2':
+ resolution: {integrity: sha512-GClLPzbM57iFXv+FlvOUL56XVe00PxuTaVEyj1zAObhRiKF008J5vedmaq7O6ehs+VmPHe8+PUQhMuEyv8d9wQ==}
peerDependencies:
react: ^18 || ^19
- '@tanstack/react-router-devtools@1.163.3':
- resolution: {integrity: sha512-42VMkV/2Z8ro7xzblPBRNZIEmCNXMzm2jD68G52p2qhjXm38wGpg46qneAESN9FtTQeVWk5aSXs47/jt7lkzmw==}
+ '@tanstack/react-router-devtools@1.166.9':
+ resolution: {integrity: sha512-O49eZmaeEKB5YnKH/qd61AbxV/lW8ICm4stfZ4GNQNpzQQ6rhPIB0p3PMZDIgX+6DoMivdNvLRmXAOOpzpIpDg==}
engines: {node: '>=20.19'}
peerDependencies:
- '@tanstack/react-router': ^1.163.3
- '@tanstack/router-core': ^1.163.3
+ '@tanstack/react-router': ^1.167.2
+ '@tanstack/router-core': ^1.167.2
react: '>=18.0.0 || >=19.0.0'
react-dom: '>=18.0.0 || >=19.0.0'
peerDependenciesMeta:
'@tanstack/router-core':
optional: true
- '@tanstack/react-router@1.167.0':
- resolution: {integrity: sha512-U7CamtXjuC8ixg1c32Rj/4A2OFBnjtMLdbgbyOGHrFHE7ULWS/yhnZLVXff0QSyn6qF92Oecek9mDMHCaTnB2Q==}
+ '@tanstack/react-router@1.167.5':
+ resolution: {integrity: sha512-s1nP6l/7BYZfSwhoNbB7/rUmZ07q/AvkmhBoiDQl3tgy5dpb9Q1qjtIapYdvCOrao1aA/QCaWqxcbGc2Ct1bvQ==}
engines: {node: '>=20.19'}
peerDependencies:
react: '>=18.0.0 || >=19.0.0'
@@ -1600,34 +1602,32 @@ packages:
react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
- '@tanstack/router-core@1.163.3':
- resolution: {integrity: sha512-jPptiGq/w3nuPzcMC7RNa79aU+b6OjaDzWJnBcV2UAwL4ThJamRS4h42TdhJE+oF5yH9IEnCOGQdfnbw45LbfA==}
+ '@tanstack/router-core@1.167.5':
+ resolution: {integrity: sha512-8fRgJ0zNJf77R4grCaJQ5Imatjyc4YT5v8rlsPkYYYeUlcFNLbuFRhLlAMdND9gRUMznpnbRDXngpTPgx2K7HQ==}
engines: {node: '>=20.19'}
+ hasBin: true
- '@tanstack/router-core@1.167.0':
- resolution: {integrity: sha512-pnaaUP+vMQEyL2XjZGe2PXmtzulxvXfGyvEMUs+AEBaNEk77xWA88bl3ujiBRbUxzpK0rxfJf+eSKPdZmBMFdQ==}
- engines: {node: '>=20.19'}
-
- '@tanstack/router-devtools-core@1.163.3':
- resolution: {integrity: sha512-FPi64IP0PT1IkoeyGmsD6JoOVOYAb85VCH0mUbSdD90yV0+1UB6oT+D7K27GXkp7SXMJN3mBEjU5rKnNnmSCIw==}
+ '@tanstack/router-devtools-core@1.166.9':
+ resolution: {integrity: sha512-PNlA7GmOUX9wY7LUG709Pk3Lg33dfHBztQwzjzrOiOsuf4ggp2R6bwarF8nYGNjG79z/MaB5PN+5yvkCVk8jGw==}
engines: {node: '>=20.19'}
peerDependencies:
- '@tanstack/router-core': ^1.163.3
+ '@tanstack/router-core': ^1.167.2
csstype: ^3.0.10
peerDependenciesMeta:
csstype:
optional: true
- '@tanstack/router-generator@1.164.0':
- resolution: {integrity: sha512-Uiyj+RtW0kdeqEd8NEd3Np1Z2nhJ2xgLS8U+5mTvFrm/s3xkM2LYjJHoLzc6am7sKPDsmeF9a4/NYq3R7ZJP0Q==}
+ '@tanstack/router-generator@1.166.13':
+ resolution: {integrity: sha512-ALxSs6OzimiSgpOuIm+AXmc7eUx/oGPwSPpdQbpZ/kX7WHRh6qM7lv8DAN0K3jWcBpzF8eeOIdryWryX8gH+Yg==}
engines: {node: '>=20.19'}
- '@tanstack/router-plugin@1.164.0':
- resolution: {integrity: sha512-cZPsEMhqzyzmuPuDbsTAzBZaT+cj0pGjwdhjxJfPCM06Ax8v4tFR7n/Ug0UCwnNAUEmKZWN3lA9uT+TxXnk9PQ==}
+ '@tanstack/router-plugin@1.166.14':
+ resolution: {integrity: sha512-hypyj0qlsAbJf60/glmVYqSVwnRB4hKRrMCUsSXjrPdO2g6gs3z6xHmcWsHQ831C4G9+bSFEK9Uy5EjO3A4THQ==}
engines: {node: '>=20.19'}
+ hasBin: true
peerDependencies:
'@rsbuild/core': '>=1.0.2'
- '@tanstack/react-router': ^1.163.3
+ '@tanstack/react-router': ^1.167.5
vite: '>=5.0.0 || >=6.0.0 || >=7.0.0'
vite-plugin-solid: ^2.11.10
webpack: '>=5.92.0'
@@ -1643,19 +1643,17 @@ packages:
webpack:
optional: true
- '@tanstack/router-utils@1.161.4':
- resolution: {integrity: sha512-r8TpjyIZoqrXXaf2DDyjd44gjGBoyE+/oEaaH68yLI9ySPO1gUWmQENZ1MZnmBnpUGN24NOZxdjDLc8npK0SAw==}
+ '@tanstack/router-utils@1.161.6':
+ resolution: {integrity: sha512-nRcYw+w2OEgK6VfjirYvGyPLOK+tZQz1jkYcmH5AjMamQ9PycnlxZF2aEZtPpNoUsaceX2bHptn6Ub5hGXqNvw==}
engines: {node: '>=20.19'}
- '@tanstack/store@0.9.1':
- resolution: {integrity: sha512-+qcNkOy0N1qSGsP7omVCW0SDrXtaDcycPqBDE726yryiA5eTDFpjBReaYjghVJwNf1pcPMyzIwTGlYjCSQR0Fg==}
-
'@tanstack/store@0.9.2':
resolution: {integrity: sha512-K013lUJEFJK2ofFQ/hZKJUmCnpcV00ebLyOyFOWQvyQHUOZp/iYO84BM6aOGiV81JzwbX0APTVmW8YI7yiG5oA==}
- '@tanstack/virtual-file-routes@1.161.4':
- resolution: {integrity: sha512-42WoRePf8v690qG8yGRe/YOh+oHni9vUaUUfoqlS91U2scd3a5rkLtVsc6b7z60w3RogH0I00vdrC5AaeiZ18w==}
+ '@tanstack/virtual-file-routes@1.161.7':
+ resolution: {integrity: sha512-olW33+Cn+bsCsZKPwEGhlkqS6w3M2slFv11JIobdnCFKMLG97oAI2kWKdx5/zsywTL8flpnoIgaZZPlQTFYhdQ==}
engines: {node: '>=20.19'}
+ hasBin: true
'@trivago/prettier-plugin-sort-imports@6.0.2':
resolution: {integrity: sha512-3DgfkukFyC/sE/VuYjaUUWoFfuVjPK55vOFDsxD56XXynFMCZDYFogH2l/hDfOsQAm1myoU/1xByJ3tWqtulXA==}
@@ -1691,8 +1689,8 @@ packages:
'@types/babel__traverse@7.28.0':
resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==}
- '@types/debug@4.1.12':
- resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==}
+ '@types/debug@4.1.13':
+ resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
'@types/estree-jsx@1.0.5':
resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
@@ -1712,8 +1710,8 @@ packages:
'@types/ms@2.1.0':
resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
- '@types/node@24.11.0':
- resolution: {integrity: sha512-fPxQqz4VTgPI/IQ+lj9r0h+fDR66bzoeMGHp8ASee+32OSGIkeASsoZuJixsQoVef1QJbeubcPBxKk22QVoWdw==}
+ '@types/node@25.5.0':
+ resolution: {integrity: sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw==}
'@types/react-dom@19.2.3':
resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
@@ -1735,63 +1733,63 @@ packages:
'@types/validate-npm-package-name@4.0.2':
resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
- '@typescript-eslint/eslint-plugin@8.56.1':
- resolution: {integrity: sha512-Jz9ZztpB37dNC+HU2HI28Bs9QXpzCz+y/twHOwhyrIRdbuVDxSytJNDl6z/aAKlaRIwC7y8wJdkBv7FxYGgi0A==}
+ '@typescript-eslint/eslint-plugin@8.57.1':
+ resolution: {integrity: sha512-Gn3aqnvNl4NGc6x3/Bqk1AOn0thyTU9bqDRhiRnUWezgvr2OnhYCWCgC8zXXRVqBsIL1pSDt7T9nJUe0oM0kDQ==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
peerDependencies:
- '@typescript-eslint/parser': ^8.56.1
+ '@typescript-eslint/parser': ^8.57.1
eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
typescript: '>=4.8.4 <6.0.0'
- '@typescript-eslint/parser@8.56.1':
- resolution: {integrity: sha512-klQbnPAAiGYFyI02+znpBRLyjL4/BrBd0nyWkdC0s/6xFLkXYQ8OoRrSkqacS1ddVxf/LDyODIKbQ5TgKAf/Fg==}
+ '@typescript-eslint/parser@8.57.1':
+ resolution: {integrity: sha512-k4eNDan0EIMTT/dUKc/g+rsJ6wcHYhNPdY19VoX/EOtaAG8DLtKCykhrUnuHPYvinn5jhAPgD2Qw9hXBwrahsw==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
peerDependencies:
eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
typescript: '>=4.8.4 <6.0.0'
- '@typescript-eslint/project-service@8.56.1':
- resolution: {integrity: sha512-TAdqQTzHNNvlVFfR+hu2PDJrURiwKsUvxFn1M0h95BB8ah5jejas08jUWG4dBA68jDMI988IvtfdAI53JzEHOQ==}
+ '@typescript-eslint/project-service@8.57.1':
+ resolution: {integrity: sha512-vx1F37BRO1OftsYlmG9xay1TqnjNVlqALymwWVuYTdo18XuKxtBpCj1QlzNIEHlvlB27osvXFWptYiEWsVdYsg==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
peerDependencies:
typescript: '>=4.8.4 <6.0.0'
- '@typescript-eslint/scope-manager@8.56.1':
- resolution: {integrity: sha512-YAi4VDKcIZp0O4tz/haYKhmIDZFEUPOreKbfdAN3SzUDMcPhJ8QI99xQXqX+HoUVq8cs85eRKnD+rne2UAnj2w==}
+ '@typescript-eslint/scope-manager@8.57.1':
+ resolution: {integrity: sha512-hs/QcpCwlwT2L5S+3fT6gp0PabyGk4Q0Rv2doJXA0435/OpnSR3VRgvrp8Xdoc3UAYSg9cyUjTeFXZEPg/3OKg==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
- '@typescript-eslint/tsconfig-utils@8.56.1':
- resolution: {integrity: sha512-qOtCYzKEeyr3aR9f28mPJqBty7+DBqsdd63eO0yyDwc6vgThj2UjWfJIcsFeSucYydqcuudMOprZ+x1SpF3ZuQ==}
+ '@typescript-eslint/tsconfig-utils@8.57.1':
+ resolution: {integrity: sha512-0lgOZB8cl19fHO4eI46YUx2EceQqhgkPSuCGLlGi79L2jwYY1cxeYc1Nae8Aw1xjgW3PKVDLlr3YJ6Bxx8HkWg==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
peerDependencies:
typescript: '>=4.8.4 <6.0.0'
- '@typescript-eslint/type-utils@8.56.1':
- resolution: {integrity: sha512-yB/7dxi7MgTtGhZdaHCemf7PuwrHMenHjmzgUW1aJpO+bBU43OycnM3Wn+DdvDO/8zzA9HlhaJ0AUGuvri4oGg==}
+ '@typescript-eslint/type-utils@8.57.1':
+ resolution: {integrity: sha512-+Bwwm0ScukFdyoJsh2u6pp4S9ktegF98pYUU0hkphOOqdMB+1sNQhIz8y5E9+4pOioZijrkfNO/HUJVAFFfPKA==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
peerDependencies:
eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
typescript: '>=4.8.4 <6.0.0'
- '@typescript-eslint/types@8.56.1':
- resolution: {integrity: sha512-dbMkdIUkIkchgGDIv7KLUpa0Mda4IYjo4IAMJUZ+3xNoUXxMsk9YtKpTHSChRS85o+H9ftm51gsK1dZReY9CVw==}
+ '@typescript-eslint/types@8.57.1':
+ resolution: {integrity: sha512-S29BOBPJSFUiblEl6RzPPjJt6w25A6XsBqRVDt53tA/tlL8q7ceQNZHTjPeONt/3S7KRI4quk+yP9jK2WjBiPQ==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
- '@typescript-eslint/typescript-estree@8.56.1':
- resolution: {integrity: sha512-qzUL1qgalIvKWAf9C1HpvBjif+Vm6rcT5wZd4VoMb9+Km3iS3Cv9DY6dMRMDtPnwRAFyAi7YXJpTIEXLvdfPxg==}
+ '@typescript-eslint/typescript-estree@8.57.1':
+ resolution: {integrity: sha512-ybe2hS9G6pXpqGtPli9Gx9quNV0TWLOmh58ADlmZe9DguLq0tiAKVjirSbtM1szG6+QH6rVXyU6GTLQbWnMY+g==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
peerDependencies:
typescript: '>=4.8.4 <6.0.0'
- '@typescript-eslint/utils@8.56.1':
- resolution: {integrity: sha512-HPAVNIME3tABJ61siYlHzSWCGtOoeP2RTIaHXFMPqjrQKCGB9OgUVdiNgH7TJS2JNIQ5qQ4RsAUDuGaGme/KOA==}
+ '@typescript-eslint/utils@8.57.1':
+ resolution: {integrity: sha512-XUNSJ/lEVFttPMMoDVA2r2bwrl8/oPx8cURtczkSEswY5T3AeLmCy+EKWQNdL4u0MmAHOjcWrqJp2cdvgjn8dQ==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
peerDependencies:
eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
typescript: '>=4.8.4 <6.0.0'
- '@typescript-eslint/visitor-keys@8.56.1':
- resolution: {integrity: sha512-KiROIzYdEV85YygXw6BI/Dx4fnBlFQu6Mq4QE4MOH9fFnhohw6wX/OAvDY2/C+ut0I3RSPKenvZJIVYqJNkhEw==}
+ '@typescript-eslint/visitor-keys@8.57.1':
+ resolution: {integrity: sha512-YWnmJkXbofiz9KbnbbwuA2rpGkFPLbAIetcCNO6mJ8gdhdZ/v7WDXsoGFAJuM6ikUFKTlSQnjWnVO4ux+UzS6A==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
'@ungap/structured-clone@1.3.0':
@@ -1883,8 +1881,8 @@ packages:
resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
engines: {node: 18 || 20 || >=22}
- baseline-browser-mapping@2.10.0:
- resolution: {integrity: sha512-lIyg0szRfYbiy67j9KN8IyeD7q7hcmqnJ1ddWmNt19ItGpNN64mnllmxUNFIOdOm6by97jlL6wfpTTJrmnjWAA==}
+ baseline-browser-mapping@2.10.9:
+ resolution: {integrity: sha512-OZd0e2mU11ClX8+IdXe3r0dbqMEznRiT4TfbhYIbcRPZkqJ7Qwer8ij3GZAmLsRKa+II9V1v5czCkvmHH3XZBg==}
engines: {node: '>=6.0.0'}
hasBin: true
@@ -1935,8 +1933,8 @@ packages:
resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
engines: {node: '>=6'}
- caniuse-lite@1.0.30001775:
- resolution: {integrity: sha512-s3Qv7Lht9zbVKE9XoTyRG6wVDCKdtOFIjBGg3+Yhn6JaytuNKPIjBMTMIY1AnOH3seL5mvF+x33oGAyK3hVt3A==}
+ caniuse-lite@1.0.30001780:
+ resolution: {integrity: sha512-llngX0E7nQci5BPJDqoZSbuZ5Bcs9F5db7EtgfwBerX9XGtkkiO4NwfDDIRzHTTwcYC8vC7bmeUEPGrKlR/TkQ==}
ccount@2.0.1:
resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
@@ -2042,8 +2040,8 @@ packages:
resolution: {integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==}
engines: {node: '>= 0.10'}
- cosmiconfig@9.0.0:
- resolution: {integrity: sha512-itvL5h8RETACmOTFc4UfIyB2RfEHi71Ax6E/PivVxq9NseKbOWpeyHEOIbmAw1rs8Ak0VursQNww7lf7YtUwzg==}
+ cosmiconfig@9.0.1:
+ resolution: {integrity: sha512-hr4ihw+DBqcvrsEDioRO31Z17x71pUYoNe/4h6Z0wB72p7MU7/9gH8Q3s12NFhHPfYBBOV3qyfUxmr/Yn3shnQ==}
engines: {node: '>=14'}
peerDependencies:
typescript: '>=4.9.5'
@@ -2139,15 +2137,15 @@ packages:
resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
engines: {node: '>= 0.4'}
- eciesjs@0.4.17:
- resolution: {integrity: sha512-TOOURki4G7sD1wDCjj7NfLaXZZ49dFOeEb5y39IXpb8p0hRzVvfvzZHOi5JcT+PpyAbi/Y+lxPb8eTag2WYH8w==}
+ eciesjs@0.4.18:
+ resolution: {integrity: sha512-wG99Zcfcys9fZux7Cft8BAX/YrOJLJSZ3jyYPfhZHqN2E+Ffx+QXBDsv3gubEgPtV6dTzJMSQUwk1H98/t/0wQ==}
engines: {bun: '>=1', deno: '>=2', node: '>=16'}
ee-first@1.1.1:
resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
- electron-to-chromium@1.5.302:
- resolution: {integrity: sha512-sM6HAN2LyK82IyPBpznDRqlTQAtuSaO+ShzFiWTvoMJLHyZ+Y39r8VMfHzwbU8MVBzQ4Wdn85+wlZl2TLGIlwg==}
+ electron-to-chromium@1.5.321:
+ resolution: {integrity: sha512-L2C7Q279W2D/J4PLZLk7sebOILDSWos7bMsMNN06rK482umHUrh/3lM8G7IlHFOYip2oAg5nha1rCMxr/rs6ZQ==}
emoji-regex@10.6.0:
resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
@@ -2159,10 +2157,14 @@ packages:
resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
engines: {node: '>= 0.8'}
- enhanced-resolve@5.20.0:
- resolution: {integrity: sha512-/ce7+jQ1PQ6rVXwe+jKEg5hW5ciicHwIQUagZkp6IufBoY3YDgdTTY1azVs0qoRgVmvsNB+rbjLJxDAeHHtwsQ==}
+ enhanced-resolve@5.20.1:
+ resolution: {integrity: sha512-Qohcme7V1inbAfvjItgw0EaxVX5q2rdVEZHRBrEQdRZTssLDGsL8Lwrznl8oQ/6kuTJONLaDcGjkNP247XEhcA==}
engines: {node: '>=10.13.0'}
+ entities@6.0.1:
+ resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
+ engines: {node: '>=0.12'}
+
env-paths@2.2.1:
resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
engines: {node: '>=6'}
@@ -2182,8 +2184,8 @@ packages:
resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==}
engines: {node: '>= 0.4'}
- esbuild@0.27.3:
- resolution: {integrity: sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==}
+ esbuild@0.27.4:
+ resolution: {integrity: sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==}
engines: {node: '>=18'}
hasBin: true
@@ -2235,8 +2237,8 @@ packages:
resolution: {integrity: sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
- eslint@9.39.3:
- resolution: {integrity: sha512-VmQ+sifHUbI/IcSopBCF/HO3YiHQx/AVd3UVyYL6weuwW+HvON9VYn5l6Zl1WZzPWXPNZrSQpxwkkZ/VuvJZzg==}
+ eslint@9.39.4:
+ resolution: {integrity: sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
hasBin: true
peerDependencies:
@@ -2362,8 +2364,8 @@ packages:
resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==}
engines: {node: '>=16'}
- flatted@3.4.1:
- resolution: {integrity: sha512-IxfVbRFVlV8V/yRaGzk0UVIcsKKHMSfYw66T/u4nTwlWteQePsxe//LjudR1AMX4tZW3WFCh3Zqa/sjlqpbURQ==}
+ flatted@3.4.2:
+ resolution: {integrity: sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==}
formdata-polyfill@4.0.10:
resolution: {integrity: sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==}
@@ -2377,8 +2379,8 @@ packages:
resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
engines: {node: '>= 0.8'}
- fs-extra@11.3.3:
- resolution: {integrity: sha512-VWSRii4t0AFm6ixFFmLLx1t7wS1gh+ckoa84aOeapGum0h+EZd1EhEumSB+ZdDLnEPuucsVB9oB7cxJHap6Afg==}
+ fs-extra@11.3.4:
+ resolution: {integrity: sha512-CTXd6rk/M3/ULNQj8FBqBWHYBVYybQ3VPBw0xGKFe3tuH7ytT6ACnvzpIQ3UZtB8yvUKC2cXn1a+x+5EVQLovA==}
engines: {node: '>=14.14'}
fsevents@2.3.3:
@@ -2392,9 +2394,6 @@ packages:
fuzzysort@3.1.0:
resolution: {integrity: sha512-sR9BNCjBg6LNgwvxlBd0sBABvQitkLzoVY9MYYROQVX/FvfJ4Mai9LsGhDgd8qYdds0bY77VzYd5iuB+v5rwQQ==}
- fzf@0.5.2:
- resolution: {integrity: sha512-Tt4kuxLXFKHy8KT40zwsUPUkg1CrsgY25FxA2U/j/0WgEDCk3ddc/zLTCCcbSHX9FcKtLuVaDGtGE/STWC+j3Q==}
-
gensync@1.0.0-beta.2:
resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
engines: {node: '>=6.9.0'}
@@ -2462,8 +2461,8 @@ packages:
graceful-fs@4.2.11:
resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
- graphql@16.13.0:
- resolution: {integrity: sha512-uSisMYERbaB9bkA9M4/4dnqyktaEkf1kMHNKq/7DHyxVeWqHQ2mBmVqm5u6/FVHwF3iCNalKcg82Zfl+tffWoA==}
+ graphql@16.13.1:
+ resolution: {integrity: sha512-gGgrVCoDKlIZ8fIqXBBb0pPKqDgki0Z/FSKNiQzSGj2uEYHr1tq5wmBegGwJx6QB5S5cM0khSBpi/JFHMCvsmQ==}
engines: {node: ^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0}
has-flag@4.0.0:
@@ -2478,12 +2477,30 @@ packages:
resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
engines: {node: '>= 0.4'}
+ hast-util-from-parse5@8.0.3:
+ resolution: {integrity: sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==}
+
+ hast-util-parse-selector@4.0.0:
+ resolution: {integrity: sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==}
+
+ hast-util-raw@9.1.0:
+ resolution: {integrity: sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw==}
+
+ hast-util-sanitize@5.0.2:
+ resolution: {integrity: sha512-3yTWghByc50aGS7JlGhk61SPenfE/p1oaFeNwkOOyrscaOkMGrcW9+Cy/QAIOBpZxP1yqDIzFMR0+Np0i0+usg==}
+
hast-util-to-jsx-runtime@2.3.6:
resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+ hast-util-to-parse5@8.0.1:
+ resolution: {integrity: sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==}
+
hast-util-whitespace@3.0.0:
resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+ hastscript@9.0.1:
+ resolution: {integrity: sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==}
+
headers-polyfill@4.0.3:
resolution: {integrity: sha512-IScLbePpkvO846sIwOtOTDjutRMWdXdJmXdMvk6gCBHxFO8d+QKOQedyZSxFTTFYRSmlgSTDtXqqq4pcenBXLQ==}
@@ -2493,8 +2510,8 @@ packages:
hermes-parser@0.25.1:
resolution: {integrity: sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==}
- hono@4.12.7:
- resolution: {integrity: sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw==}
+ hono@4.12.8:
+ resolution: {integrity: sha512-VJCEvtrezO1IAR+kqEYnxUOoStaQPGrCmX3j4wDTNOcD1uRPFpGlwQUIW8niPuvHXaTUxeOUl5MMDGrl+tmO9A==}
engines: {node: '>=16.9.0'}
html-parse-stringify@3.0.1:
@@ -2503,6 +2520,9 @@ packages:
html-url-attributes@3.0.1:
resolution: {integrity: sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==}
+ html-void-elements@3.0.0:
+ resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==}
+
http-errors@2.0.1:
resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
engines: {node: '>= 0.8'}
@@ -2522,8 +2542,8 @@ packages:
i18next-browser-languagedetector@8.2.1:
resolution: {integrity: sha512-bZg8+4bdmaOiApD7N7BPT9W8MLZG+nPTOFlLiJiT8uzKXFjhxw4v2ierCXOwB5sFDMtuA5G4kgYZ0AznZxQ/cw==}
- i18next@25.8.14:
- resolution: {integrity: sha512-paMUYkfWJMsWPeE/Hejcw+XLhHrQPehem+4wMo+uELnvIwvCG019L9sAIljwjCmEMtFQQO3YeitJY8Kctei3iA==}
+ i18next@25.8.20:
+ resolution: {integrity: sha512-xjo9+lbX/P1tQt3xpO2rfJiBppNfUnNIPKgCvNsTKsvTOCro1Qr/geXVg1N47j5ScOSaXAPq8ET93raK3Rr06A==}
peerDependencies:
typescript: ^5
peerDependenciesMeta:
@@ -2673,8 +2693,8 @@ packages:
resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
hasBin: true
- jose@6.1.3:
- resolution: {integrity: sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ==}
+ jose@6.2.2:
+ resolution: {integrity: sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ==}
jotai@2.18.1:
resolution: {integrity: sha512-e0NOzK+yRFwHo7DOp0DS0Ycq74KMEAObDWFGmfEL28PD9nLqBTt3/Ug7jf9ca72x0gC9LQZG9zH+0ISICmy3iA==}
@@ -2747,74 +2767,74 @@ packages:
resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
engines: {node: '>= 0.8.0'}
- lightningcss-android-arm64@1.31.1:
- resolution: {integrity: sha512-HXJF3x8w9nQ4jbXRiNppBCqeZPIAfUo8zE/kOEGbW5NZvGc/K7nMxbhIr+YlFlHW5mpbg/YFPdbnCh1wAXCKFg==}
+ lightningcss-android-arm64@1.32.0:
+ resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
engines: {node: '>= 12.0.0'}
cpu: [arm64]
os: [android]
- lightningcss-darwin-arm64@1.31.1:
- resolution: {integrity: sha512-02uTEqf3vIfNMq3h/z2cJfcOXnQ0GRwQrkmPafhueLb2h7mqEidiCzkE4gBMEH65abHRiQvhdcQ+aP0D0g67sg==}
+ lightningcss-darwin-arm64@1.32.0:
+ resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
engines: {node: '>= 12.0.0'}
cpu: [arm64]
os: [darwin]
- lightningcss-darwin-x64@1.31.1:
- resolution: {integrity: sha512-1ObhyoCY+tGxtsz1lSx5NXCj3nirk0Y0kB/g8B8DT+sSx4G9djitg9ejFnjb3gJNWo7qXH4DIy2SUHvpoFwfTA==}
+ lightningcss-darwin-x64@1.32.0:
+ resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
engines: {node: '>= 12.0.0'}
cpu: [x64]
os: [darwin]
- lightningcss-freebsd-x64@1.31.1:
- resolution: {integrity: sha512-1RINmQKAItO6ISxYgPwszQE1BrsVU5aB45ho6O42mu96UiZBxEXsuQ7cJW4zs4CEodPUioj/QrXW1r9pLUM74A==}
+ lightningcss-freebsd-x64@1.32.0:
+ resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
engines: {node: '>= 12.0.0'}
cpu: [x64]
os: [freebsd]
- lightningcss-linux-arm-gnueabihf@1.31.1:
- resolution: {integrity: sha512-OOCm2//MZJ87CdDK62rZIu+aw9gBv4azMJuA8/KB74wmfS3lnC4yoPHm0uXZ/dvNNHmnZnB8XLAZzObeG0nS1g==}
+ lightningcss-linux-arm-gnueabihf@1.32.0:
+ resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
engines: {node: '>= 12.0.0'}
cpu: [arm]
os: [linux]
- lightningcss-linux-arm64-gnu@1.31.1:
- resolution: {integrity: sha512-WKyLWztD71rTnou4xAD5kQT+982wvca7E6QoLpoawZ1gP9JM0GJj4Tp5jMUh9B3AitHbRZ2/H3W5xQmdEOUlLg==}
+ lightningcss-linux-arm64-gnu@1.32.0:
+ resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
engines: {node: '>= 12.0.0'}
cpu: [arm64]
os: [linux]
- lightningcss-linux-arm64-musl@1.31.1:
- resolution: {integrity: sha512-mVZ7Pg2zIbe3XlNbZJdjs86YViQFoJSpc41CbVmKBPiGmC4YrfeOyz65ms2qpAobVd7WQsbW4PdsSJEMymyIMg==}
+ lightningcss-linux-arm64-musl@1.32.0:
+ resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
engines: {node: '>= 12.0.0'}
cpu: [arm64]
os: [linux]
- lightningcss-linux-x64-gnu@1.31.1:
- resolution: {integrity: sha512-xGlFWRMl+0KvUhgySdIaReQdB4FNudfUTARn7q0hh/V67PVGCs3ADFjw+6++kG1RNd0zdGRlEKa+T13/tQjPMA==}
+ lightningcss-linux-x64-gnu@1.32.0:
+ resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
engines: {node: '>= 12.0.0'}
cpu: [x64]
os: [linux]
- lightningcss-linux-x64-musl@1.31.1:
- resolution: {integrity: sha512-eowF8PrKHw9LpoZii5tdZwnBcYDxRw2rRCyvAXLi34iyeYfqCQNA9rmUM0ce62NlPhCvof1+9ivRaTY6pSKDaA==}
+ lightningcss-linux-x64-musl@1.32.0:
+ resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
engines: {node: '>= 12.0.0'}
cpu: [x64]
os: [linux]
- lightningcss-win32-arm64-msvc@1.31.1:
- resolution: {integrity: sha512-aJReEbSEQzx1uBlQizAOBSjcmr9dCdL3XuC/6HLXAxmtErsj2ICo5yYggg1qOODQMtnjNQv2UHb9NpOuFtYe4w==}
+ lightningcss-win32-arm64-msvc@1.32.0:
+ resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
engines: {node: '>= 12.0.0'}
cpu: [arm64]
os: [win32]
- lightningcss-win32-x64-msvc@1.31.1:
- resolution: {integrity: sha512-I9aiFrbd7oYHwlnQDqr1Roz+fTz61oDDJX7n9tYF9FJymH1cIN1DtKw3iYt6b8WZgEjoNwVSncwF4wx/ZedMhw==}
+ lightningcss-win32-x64-msvc@1.32.0:
+ resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
engines: {node: '>= 12.0.0'}
cpu: [x64]
os: [win32]
- lightningcss@1.31.1:
- resolution: {integrity: sha512-l51N2r93WmGUye3WuFoN5k10zyvrVs0qfKBhyC5ogUQ6Ew6JUSswh78mbSO+IU3nTWsyOArqPCcShdQSadghBQ==}
+ lightningcss@1.32.0:
+ resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
engines: {node: '>= 12.0.0'}
lines-and-columns@1.2.4:
@@ -3031,8 +3051,8 @@ packages:
ms@2.1.3:
resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
- msw@2.12.10:
- resolution: {integrity: sha512-G3VUymSE0/iegFnuipujpwyTM2GuZAKXNeerUSrG2+Eg391wW63xFs5ixWsK9MWzr1AGoSkYGmyAzNgbR3+urw==}
+ msw@2.12.13:
+ resolution: {integrity: sha512-9CV2mXT9+z0J26MQDfEZZkj/psJ5Er/w0w+t95FWdaGH/DTlhNZBx8vBO5jSYv8AZEnl3ouX+AaTT68KXdAIag==}
engines: {node: '>=18'}
hasBin: true
peerDependencies:
@@ -3066,8 +3086,8 @@ packages:
resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
- node-releases@2.0.27:
- resolution: {integrity: sha512-nmh3lCkYZ3grZvqcCH+fjmQ7X+H0OeZgP40OierEaAptX4XofMh5kwNbWh7lBduUzCcV/8kZ+NDLCwm2iorIlA==}
+ node-releases@2.0.36:
+ resolution: {integrity: sha512-TdC8FSgHz8Mwtw9g5L4gR/Sh9XhSP/0DEkQxfEFXOpiul5IiHgHan2VhYYb6agDSfp4KuvltmGApc8HMgUrIkA==}
normalize-path@3.0.0:
resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==}
@@ -3131,9 +3151,6 @@ packages:
resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
engines: {node: '>=10'}
- package-manager-detector@1.6.0:
- resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
-
parent-module@1.0.1:
resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
engines: {node: '>=6'}
@@ -3155,6 +3172,9 @@ packages:
parse-statements@1.0.11:
resolution: {integrity: sha512-HlsyYdMBnbPQ9Jr/VgJ1YF4scnldvJpJxCVx6KgqPL4dxppsWrJHCIIxQXMJrqGnsRkNPATbeMJ8Yxu7JMsYcA==}
+ parse5@7.3.0:
+ resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
+
parseurl@1.3.3:
resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
engines: {node: '>= 0.8'}
@@ -3206,8 +3226,8 @@ packages:
resolution: {integrity: sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==}
engines: {node: '>=4'}
- postcss@8.5.6:
- resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
+ postcss@8.5.8:
+ resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==}
engines: {node: ^10 || ^12 || >=14}
powershell-utils@0.1.0:
@@ -3404,6 +3424,12 @@ packages:
resolution: {integrity: sha512-YTUo+Flmw4ZXiWfQKGcwwc11KnoRAYgzAE2E7mXKCjSviTKShtxBsN6YUUBB2gtaBzKzeKunxhUwNHQuRryhWA==}
engines: {node: '>= 4'}
+ rehype-raw@7.0.0:
+ resolution: {integrity: sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==}
+
+ rehype-sanitize@6.0.0:
+ resolution: {integrity: sha512-CsnhKNsyI8Tub6L4sm5ZFsme4puGfc6pYylvXo1AeqaGbjOYyzNv3qZPwvs0oMJ39eryyeOdmxwUIo94IpEhqg==}
+
remark-gfm@4.0.1:
resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
@@ -3477,22 +3503,12 @@ packages:
resolution: {integrity: sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==}
engines: {node: '>= 18'}
- seroval-plugins@1.5.0:
- resolution: {integrity: sha512-EAHqADIQondwRZIdeW2I636zgsODzoBDwb3PT/+7TLDWyw1Dy/Xv7iGUIEXXav7usHDE9HVhOU61irI3EnyyHA==}
- engines: {node: '>=10'}
- peerDependencies:
- seroval: ^1.0
-
seroval-plugins@1.5.1:
resolution: {integrity: sha512-4FbuZ/TMl02sqv0RTFexu0SP6V+ywaIe5bAWCCEik0fk17BhALgwvUDVF7e3Uvf9pxmwCEJsRPmlkUE6HdzLAw==}
engines: {node: '>=10'}
peerDependencies:
seroval: ^1.0
- seroval@1.5.0:
- resolution: {integrity: sha512-OE4cvmJ1uSPrKorFIH9/w/Qwuvi/IMcGbv5RKgcJ/zjA/IohDLU6SVaxFN9FwajbP7nsX0dQqMDes1whk3y+yw==}
- engines: {node: '>=10'}
-
seroval@1.5.1:
resolution: {integrity: sha512-OwrZRZAfhHww0WEnKHDY8OM0U/Qs8OTfIDWhUD4BLpNJUfXK4cGmjiagGze086m+mhI+V2nD0gfbHEnJjb9STA==}
engines: {node: '>=10'}
@@ -3504,8 +3520,8 @@ packages:
setprototypeof@1.2.0:
resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
- shadcn@4.0.5:
- resolution: {integrity: sha512-z0SOHEU1+ADam1UJHrgxJhUsOb0/jBoYc+u9mhWs071KrnORq48X7uCwG3mD2ysQEBtOfeK/MxMGsmzL5Jt+Jg==}
+ shadcn@4.1.0:
+ resolution: {integrity: sha512-3zETJ+0Ezj69FS6RL0HOkLKKAR5yXisXx1iISJdfLQfrUqj/VIQlanQi1Ukk+9OE+XHZVj4FQNTBSfbr2CyCYg==}
hasBin: true
shebang-command@2.0.0:
@@ -3634,8 +3650,8 @@ packages:
tailwind-merge@3.5.0:
resolution: {integrity: sha512-I8K9wewnVDkL1NTGoqWmVEIlUcB9gFriAEkXkfCjX5ib8ezGxtR3xD7iZIxrfArjEsH7F1CHD4RFUtxefdqV/A==}
- tailwindcss@4.2.1:
- resolution: {integrity: sha512-/tBrSQ36vCleJkAOsy9kbNTgaxvGbyOamC30PRePTQe/o1MFwEKHQk4Cn7BNGaPtjp+PuUrByJehM1hgxfq4sw==}
+ tailwindcss@4.2.2:
+ resolution: {integrity: sha512-KWBIxs1Xb6NoLdMVqhbhgwZf2PGBpPEiwOqgI4pFIYbNTfBXiKYyWoTsXgBQ9WFg/OlhnvHaY+AEpW7wSmFo2Q==}
tapable@2.3.0:
resolution: {integrity: sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==}
@@ -3647,19 +3663,15 @@ packages:
tiny-warning@1.0.3:
resolution: {integrity: sha512-lBN9zLN/oAf68o3zNXYrdCt1kP8WsiGW8Oo2ka41b2IM5JL/S1CTyX1rW0mb/zSuJun0ZUrDxx4sqvYS2FWzPA==}
- tinyexec@1.0.2:
- resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==}
- engines: {node: '>=18'}
-
tinyglobby@0.2.15:
resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
engines: {node: '>=12.0.0'}
- tldts-core@7.0.23:
- resolution: {integrity: sha512-0g9vrtDQLrNIiCj22HSe9d4mLVG3g5ph5DZ8zCKBr4OtrspmNB6ss7hVyzArAeE88ceZocIEGkyW1Ime7fxPtQ==}
+ tldts-core@7.0.26:
+ resolution: {integrity: sha512-5WJ2SqFsv4G2Dwi7ZFVRnz6b2H1od39QME1lc2y5Ew3eWiZMAeqOAfWpRP9jHvhUl881406QtZTODvjttJs+ew==}
- tldts@7.0.23:
- resolution: {integrity: sha512-ASdhgQIBSay0R/eXggAkQ53G4nTJqTXqC2kbaBbdDwM7SkjyZyO0OaaN1/FH7U/yCeqOHDwFO5j8+Os/IS1dXw==}
+ tldts@7.0.26:
+ resolution: {integrity: sha512-WiGwQjr0qYdNNG8KpMKlSvpxz652lqa3Rd+/hSaDcY4Uo6SKWZq2LAF+hsAhUewTtYhXlorBKgNF3Kk8hnjGoQ==}
hasBin: true
to-regex-range@5.0.1:
@@ -3670,8 +3682,8 @@ packages:
resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
engines: {node: '>=0.6'}
- tough-cookie@6.0.0:
- resolution: {integrity: sha512-kXuRi1mtaKMrsLUxz3sQYvVl37B0Ns6MzfrtV5DvJceE9bPyspOqk9xxv7XbZWcfLWbFmm997vl83qUWVJA64w==}
+ tough-cookie@6.0.1:
+ resolution: {integrity: sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==}
engines: {node: '>=16'}
trim-lines@3.0.1:
@@ -3680,8 +3692,8 @@ packages:
trough@2.2.0:
resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
- ts-api-utils@2.4.0:
- resolution: {integrity: sha512-3TaVTaAv2gTiMB35i3FiGJaRfwb3Pyn/j3m/bfAvGe8FB7CF6u+LMYqYlDh7reQf7UNvoTvdfAqHGmPGOSsPmA==}
+ ts-api-utils@2.5.0:
+ resolution: {integrity: sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==}
engines: {node: '>=18.12'}
peerDependencies:
typescript: '>=4.8.4'
@@ -3708,16 +3720,16 @@ packages:
resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
engines: {node: '>= 0.8.0'}
- type-fest@5.4.4:
- resolution: {integrity: sha512-JnTrzGu+zPV3aXIUhnyWJj4z/wigMsdYajGLIYakqyOW1nPllzXEJee0QQbHj+CTIQtXGlAjuK0UY+2xTyjVAw==}
+ type-fest@5.5.0:
+ resolution: {integrity: sha512-PlBfpQwiUvGViBNX84Yxwjsdhd1TUlXr6zjX7eoirtCPIr08NAmxwa+fcYBTeRQxHo9YC9wwF3m9i700sHma8g==}
engines: {node: '>=20'}
type-is@2.0.1:
resolution: {integrity: sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==}
engines: {node: '>= 0.6'}
- typescript-eslint@8.56.1:
- resolution: {integrity: sha512-U4lM6pjmBX7J5wk4szltF7I1cGBHXZopnAXCMXb3+fZ3B/0Z3hq3wS/CCUB2NZBNAExK92mCU2tEohWuwVMsDQ==}
+ typescript-eslint@8.57.1:
+ resolution: {integrity: sha512-fLvZWf+cAGw3tqMCYzGIU6yR8K+Y9NT2z23RwOjlNFF2HwSB3KhdEFI5lSBv8tNmFkkBShSjsCjzx1vahZfISA==}
engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
peerDependencies:
eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
@@ -3728,8 +3740,8 @@ packages:
engines: {node: '>=14.17'}
hasBin: true
- undici-types@7.16.0:
- resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
+ undici-types@7.18.2:
+ resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
unicorn-magic@0.3.0:
resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
@@ -3840,6 +3852,9 @@ packages:
resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
engines: {node: '>= 0.8'}
+ vfile-location@5.0.3:
+ resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
+
vfile-message@4.0.3:
resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
@@ -3890,6 +3905,9 @@ packages:
resolution: {integrity: sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==}
engines: {node: '>=0.10.0'}
+ web-namespaces@2.0.1:
+ resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
+
web-streams-polyfill@3.3.3:
resolution: {integrity: sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==}
engines: {node: '>= 8'}
@@ -3979,13 +3997,6 @@ packages:
snapshots:
- '@antfu/ni@25.0.0':
- dependencies:
- ansis: 4.2.0
- fzf: 0.5.2
- package-manager-detector: 1.6.0
- tinyexec: 1.0.2
-
'@babel/code-frame@7.29.0':
dependencies:
'@babel/helper-validator-identifier': 7.28.5
@@ -4000,8 +4011,8 @@ snapshots:
'@babel/generator': 7.29.1
'@babel/helper-compilation-targets': 7.28.6
'@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
- '@babel/helpers': 7.28.6
- '@babel/parser': 7.29.0
+ '@babel/helpers': 7.29.2
+ '@babel/parser': 7.29.2
'@babel/template': 7.28.6
'@babel/traverse': 7.29.0
'@babel/types': 7.29.0
@@ -4016,7 +4027,7 @@ snapshots:
'@babel/generator@7.29.1':
dependencies:
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/types': 7.29.0
'@jridgewell/gen-mapping': 0.3.13
'@jridgewell/trace-mapping': 0.3.31
@@ -4100,12 +4111,12 @@ snapshots:
'@babel/helper-validator-option@7.27.1': {}
- '@babel/helpers@7.28.6':
+ '@babel/helpers@7.29.2':
dependencies:
'@babel/template': 7.28.6
'@babel/types': 7.29.0
- '@babel/parser@7.29.0':
+ '@babel/parser@7.29.2':
dependencies:
'@babel/types': 7.29.0
@@ -4159,12 +4170,12 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@babel/runtime@7.28.6': {}
+ '@babel/runtime@7.29.2': {}
'@babel/template@7.28.6':
dependencies:
'@babel/code-frame': 7.29.0
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/types': 7.29.0
'@babel/traverse@7.29.0':
@@ -4172,7 +4183,7 @@ snapshots:
'@babel/code-frame': 7.29.0
'@babel/generator': 7.29.1
'@babel/helper-globals': 7.28.0
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/template': 7.28.6
'@babel/types': 7.29.0
debug: 4.4.3
@@ -4184,11 +4195,11 @@ snapshots:
'@babel/helper-string-parser': 7.27.1
'@babel/helper-validator-identifier': 7.28.5
- '@dotenvx/dotenvx@1.52.0':
+ '@dotenvx/dotenvx@1.57.0':
dependencies:
commander: 11.1.0
dotenv: 17.3.1
- eciesjs: 0.4.17
+ eciesjs: 0.4.18
execa: 5.1.1
fdir: 6.5.0(picomatch@4.0.3)
ignore: 5.3.2
@@ -4200,87 +4211,87 @@ snapshots:
dependencies:
'@noble/ciphers': 1.3.0
- '@esbuild/aix-ppc64@0.27.3':
+ '@esbuild/aix-ppc64@0.27.4':
optional: true
- '@esbuild/android-arm64@0.27.3':
+ '@esbuild/android-arm64@0.27.4':
optional: true
- '@esbuild/android-arm@0.27.3':
+ '@esbuild/android-arm@0.27.4':
optional: true
- '@esbuild/android-x64@0.27.3':
+ '@esbuild/android-x64@0.27.4':
optional: true
- '@esbuild/darwin-arm64@0.27.3':
+ '@esbuild/darwin-arm64@0.27.4':
optional: true
- '@esbuild/darwin-x64@0.27.3':
+ '@esbuild/darwin-x64@0.27.4':
optional: true
- '@esbuild/freebsd-arm64@0.27.3':
+ '@esbuild/freebsd-arm64@0.27.4':
optional: true
- '@esbuild/freebsd-x64@0.27.3':
+ '@esbuild/freebsd-x64@0.27.4':
optional: true
- '@esbuild/linux-arm64@0.27.3':
+ '@esbuild/linux-arm64@0.27.4':
optional: true
- '@esbuild/linux-arm@0.27.3':
+ '@esbuild/linux-arm@0.27.4':
optional: true
- '@esbuild/linux-ia32@0.27.3':
+ '@esbuild/linux-ia32@0.27.4':
optional: true
- '@esbuild/linux-loong64@0.27.3':
+ '@esbuild/linux-loong64@0.27.4':
optional: true
- '@esbuild/linux-mips64el@0.27.3':
+ '@esbuild/linux-mips64el@0.27.4':
optional: true
- '@esbuild/linux-ppc64@0.27.3':
+ '@esbuild/linux-ppc64@0.27.4':
optional: true
- '@esbuild/linux-riscv64@0.27.3':
+ '@esbuild/linux-riscv64@0.27.4':
optional: true
- '@esbuild/linux-s390x@0.27.3':
+ '@esbuild/linux-s390x@0.27.4':
optional: true
- '@esbuild/linux-x64@0.27.3':
+ '@esbuild/linux-x64@0.27.4':
optional: true
- '@esbuild/netbsd-arm64@0.27.3':
+ '@esbuild/netbsd-arm64@0.27.4':
optional: true
- '@esbuild/netbsd-x64@0.27.3':
+ '@esbuild/netbsd-x64@0.27.4':
optional: true
- '@esbuild/openbsd-arm64@0.27.3':
+ '@esbuild/openbsd-arm64@0.27.4':
optional: true
- '@esbuild/openbsd-x64@0.27.3':
+ '@esbuild/openbsd-x64@0.27.4':
optional: true
- '@esbuild/openharmony-arm64@0.27.3':
+ '@esbuild/openharmony-arm64@0.27.4':
optional: true
- '@esbuild/sunos-x64@0.27.3':
+ '@esbuild/sunos-x64@0.27.4':
optional: true
- '@esbuild/win32-arm64@0.27.3':
+ '@esbuild/win32-arm64@0.27.4':
optional: true
- '@esbuild/win32-ia32@0.27.3':
+ '@esbuild/win32-ia32@0.27.4':
optional: true
- '@esbuild/win32-x64@0.27.3':
+ '@esbuild/win32-x64@0.27.4':
optional: true
- '@eslint-community/eslint-utils@4.9.1(eslint@9.39.3(jiti@2.6.1))':
+ '@eslint-community/eslint-utils@4.9.1(eslint@9.39.4(jiti@2.6.1))':
dependencies:
- eslint: 9.39.3(jiti@2.6.1)
+ eslint: 9.39.4(jiti@2.6.1)
eslint-visitor-keys: 3.4.3
'@eslint-community/regexpp@4.12.2': {}
@@ -4315,7 +4326,7 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@eslint/js@9.39.3': {}
+ '@eslint/js@9.39.4': {}
'@eslint/object-schema@2.1.7': {}
@@ -4324,28 +4335,28 @@ snapshots:
'@eslint/core': 0.17.0
levn: 0.4.1
- '@floating-ui/core@1.7.4':
+ '@floating-ui/core@1.7.5':
dependencies:
- '@floating-ui/utils': 0.2.10
+ '@floating-ui/utils': 0.2.11
- '@floating-ui/dom@1.7.5':
+ '@floating-ui/dom@1.7.6':
dependencies:
- '@floating-ui/core': 1.7.4
- '@floating-ui/utils': 0.2.10
+ '@floating-ui/core': 1.7.5
+ '@floating-ui/utils': 0.2.11
- '@floating-ui/react-dom@2.1.7(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+ '@floating-ui/react-dom@2.1.8(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
dependencies:
- '@floating-ui/dom': 1.7.5
+ '@floating-ui/dom': 1.7.6
react: 19.2.4
react-dom: 19.2.4(react@19.2.4)
- '@floating-ui/utils@0.2.10': {}
+ '@floating-ui/utils@0.2.11': {}
'@fontsource-variable/inter@5.2.8': {}
- '@hono/node-server@1.19.11(hono@4.12.7)':
+ '@hono/node-server@1.19.11(hono@4.12.8)':
dependencies:
- hono: 4.12.7
+ hono: 4.12.8
'@humanfs/core@0.19.1': {}
@@ -4360,31 +4371,31 @@ snapshots:
'@inquirer/ansi@1.0.2': {}
- '@inquirer/confirm@5.1.21(@types/node@24.11.0)':
+ '@inquirer/confirm@5.1.21(@types/node@25.5.0)':
dependencies:
- '@inquirer/core': 10.3.2(@types/node@24.11.0)
- '@inquirer/type': 3.0.10(@types/node@24.11.0)
+ '@inquirer/core': 10.3.2(@types/node@25.5.0)
+ '@inquirer/type': 3.0.10(@types/node@25.5.0)
optionalDependencies:
- '@types/node': 24.11.0
+ '@types/node': 25.5.0
- '@inquirer/core@10.3.2(@types/node@24.11.0)':
+ '@inquirer/core@10.3.2(@types/node@25.5.0)':
dependencies:
'@inquirer/ansi': 1.0.2
'@inquirer/figures': 1.0.15
- '@inquirer/type': 3.0.10(@types/node@24.11.0)
+ '@inquirer/type': 3.0.10(@types/node@25.5.0)
cli-width: 4.1.0
mute-stream: 2.0.0
signal-exit: 4.1.0
wrap-ansi: 6.2.0
yoctocolors-cjs: 2.1.3
optionalDependencies:
- '@types/node': 24.11.0
+ '@types/node': 25.5.0
'@inquirer/figures@1.0.15': {}
- '@inquirer/type@3.0.10(@types/node@24.11.0)':
+ '@inquirer/type@3.0.10(@types/node@25.5.0)':
optionalDependencies:
- '@types/node': 24.11.0
+ '@types/node': 25.5.0
'@jridgewell/gen-mapping@0.3.13':
dependencies:
@@ -4407,7 +4418,7 @@ snapshots:
'@modelcontextprotocol/sdk@1.27.1(zod@3.25.76)':
dependencies:
- '@hono/node-server': 1.19.11(hono@4.12.7)
+ '@hono/node-server': 1.19.11(hono@4.12.8)
ajv: 8.18.0
ajv-formats: 3.0.1(ajv@8.18.0)
content-type: 1.0.5
@@ -4417,8 +4428,8 @@ snapshots:
eventsource-parser: 3.0.6
express: 5.2.1
express-rate-limit: 8.3.1(express@5.2.1)
- hono: 4.12.7
- jose: 6.1.3
+ hono: 4.12.8
+ jose: 6.2.2
json-schema-typed: 8.0.2
pkce-challenge: 5.0.1
raw-body: 3.0.2
@@ -4857,7 +4868,7 @@ snapshots:
'@radix-ui/react-popper@1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
dependencies:
- '@floating-ui/react-dom': 2.1.7(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+ '@floating-ui/react-dom': 2.1.8(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
'@radix-ui/react-arrow': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
'@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
'@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
@@ -5293,111 +5304,111 @@ snapshots:
'@sindresorhus/merge-streams@4.0.0': {}
- '@tabler/icons-react@3.38.0(react@19.2.4)':
+ '@tabler/icons-react@3.40.0(react@19.2.4)':
dependencies:
- '@tabler/icons': 3.38.0
+ '@tabler/icons': 3.40.0
react: 19.2.4
- '@tabler/icons@3.38.0': {}
+ '@tabler/icons@3.40.0': {}
- '@tailwindcss/node@4.2.1':
+ '@tailwindcss/node@4.2.2':
dependencies:
'@jridgewell/remapping': 2.3.5
- enhanced-resolve: 5.20.0
+ enhanced-resolve: 5.20.1
jiti: 2.6.1
- lightningcss: 1.31.1
+ lightningcss: 1.32.0
magic-string: 0.30.21
source-map-js: 1.2.1
- tailwindcss: 4.2.1
+ tailwindcss: 4.2.2
- '@tailwindcss/oxide-android-arm64@4.2.1':
+ '@tailwindcss/oxide-android-arm64@4.2.2':
optional: true
- '@tailwindcss/oxide-darwin-arm64@4.2.1':
+ '@tailwindcss/oxide-darwin-arm64@4.2.2':
optional: true
- '@tailwindcss/oxide-darwin-x64@4.2.1':
+ '@tailwindcss/oxide-darwin-x64@4.2.2':
optional: true
- '@tailwindcss/oxide-freebsd-x64@4.2.1':
+ '@tailwindcss/oxide-freebsd-x64@4.2.2':
optional: true
- '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.1':
+ '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.2':
optional: true
- '@tailwindcss/oxide-linux-arm64-gnu@4.2.1':
+ '@tailwindcss/oxide-linux-arm64-gnu@4.2.2':
optional: true
- '@tailwindcss/oxide-linux-arm64-musl@4.2.1':
+ '@tailwindcss/oxide-linux-arm64-musl@4.2.2':
optional: true
- '@tailwindcss/oxide-linux-x64-gnu@4.2.1':
+ '@tailwindcss/oxide-linux-x64-gnu@4.2.2':
optional: true
- '@tailwindcss/oxide-linux-x64-musl@4.2.1':
+ '@tailwindcss/oxide-linux-x64-musl@4.2.2':
optional: true
- '@tailwindcss/oxide-wasm32-wasi@4.2.1':
+ '@tailwindcss/oxide-wasm32-wasi@4.2.2':
optional: true
- '@tailwindcss/oxide-win32-arm64-msvc@4.2.1':
+ '@tailwindcss/oxide-win32-arm64-msvc@4.2.2':
optional: true
- '@tailwindcss/oxide-win32-x64-msvc@4.2.1':
+ '@tailwindcss/oxide-win32-x64-msvc@4.2.2':
optional: true
- '@tailwindcss/oxide@4.2.1':
+ '@tailwindcss/oxide@4.2.2':
optionalDependencies:
- '@tailwindcss/oxide-android-arm64': 4.2.1
- '@tailwindcss/oxide-darwin-arm64': 4.2.1
- '@tailwindcss/oxide-darwin-x64': 4.2.1
- '@tailwindcss/oxide-freebsd-x64': 4.2.1
- '@tailwindcss/oxide-linux-arm-gnueabihf': 4.2.1
- '@tailwindcss/oxide-linux-arm64-gnu': 4.2.1
- '@tailwindcss/oxide-linux-arm64-musl': 4.2.1
- '@tailwindcss/oxide-linux-x64-gnu': 4.2.1
- '@tailwindcss/oxide-linux-x64-musl': 4.2.1
- '@tailwindcss/oxide-wasm32-wasi': 4.2.1
- '@tailwindcss/oxide-win32-arm64-msvc': 4.2.1
- '@tailwindcss/oxide-win32-x64-msvc': 4.2.1
+ '@tailwindcss/oxide-android-arm64': 4.2.2
+ '@tailwindcss/oxide-darwin-arm64': 4.2.2
+ '@tailwindcss/oxide-darwin-x64': 4.2.2
+ '@tailwindcss/oxide-freebsd-x64': 4.2.2
+ '@tailwindcss/oxide-linux-arm-gnueabihf': 4.2.2
+ '@tailwindcss/oxide-linux-arm64-gnu': 4.2.2
+ '@tailwindcss/oxide-linux-arm64-musl': 4.2.2
+ '@tailwindcss/oxide-linux-x64-gnu': 4.2.2
+ '@tailwindcss/oxide-linux-x64-musl': 4.2.2
+ '@tailwindcss/oxide-wasm32-wasi': 4.2.2
+ '@tailwindcss/oxide-win32-arm64-msvc': 4.2.2
+ '@tailwindcss/oxide-win32-x64-msvc': 4.2.2
- '@tailwindcss/typography@0.5.19(tailwindcss@4.2.1)':
+ '@tailwindcss/typography@0.5.19(tailwindcss@4.2.2)':
dependencies:
postcss-selector-parser: 6.0.10
- tailwindcss: 4.2.1
+ tailwindcss: 4.2.2
- '@tailwindcss/vite@4.2.1(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))':
+ '@tailwindcss/vite@4.2.2(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))':
dependencies:
- '@tailwindcss/node': 4.2.1
- '@tailwindcss/oxide': 4.2.1
- tailwindcss: 4.2.1
- vite: 7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0)
+ '@tailwindcss/node': 4.2.2
+ '@tailwindcss/oxide': 4.2.2
+ tailwindcss: 4.2.2
+ vite: 7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
- '@tanstack/history@1.161.4': {}
+ '@tanstack/history@1.161.6': {}
- '@tanstack/query-core@5.90.20': {}
+ '@tanstack/query-core@5.91.2': {}
- '@tanstack/react-query@5.90.21(react@19.2.4)':
+ '@tanstack/react-query@5.91.2(react@19.2.4)':
dependencies:
- '@tanstack/query-core': 5.90.20
+ '@tanstack/query-core': 5.91.2
react: 19.2.4
- '@tanstack/react-router-devtools@1.163.3(@tanstack/react-router@1.167.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@tanstack/router-core@1.167.0)(csstype@3.2.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+ '@tanstack/react-router-devtools@1.166.9(@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@tanstack/router-core@1.167.5)(csstype@3.2.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
dependencies:
- '@tanstack/react-router': 1.167.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
- '@tanstack/router-devtools-core': 1.163.3(@tanstack/router-core@1.167.0)(csstype@3.2.3)
+ '@tanstack/react-router': 1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+ '@tanstack/router-devtools-core': 1.166.9(@tanstack/router-core@1.167.5)(csstype@3.2.3)
react: 19.2.4
react-dom: 19.2.4(react@19.2.4)
optionalDependencies:
- '@tanstack/router-core': 1.167.0
+ '@tanstack/router-core': 1.167.5
transitivePeerDependencies:
- csstype
- '@tanstack/react-router@1.167.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+ '@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
dependencies:
- '@tanstack/history': 1.161.4
+ '@tanstack/history': 1.161.6
'@tanstack/react-store': 0.9.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
- '@tanstack/router-core': 1.167.0
+ '@tanstack/router-core': 1.167.5
isbot: 5.1.36
react: 19.2.4
react-dom: 19.2.4(react@19.2.4)
@@ -5411,19 +5422,9 @@ snapshots:
react-dom: 19.2.4(react@19.2.4)
use-sync-external-store: 1.6.0(react@19.2.4)
- '@tanstack/router-core@1.163.3':
+ '@tanstack/router-core@1.167.5':
dependencies:
- '@tanstack/history': 1.161.4
- '@tanstack/store': 0.9.1
- cookie-es: 2.0.0
- seroval: 1.5.0
- seroval-plugins: 1.5.0(seroval@1.5.0)
- tiny-invariant: 1.3.3
- tiny-warning: 1.0.3
-
- '@tanstack/router-core@1.167.0':
- dependencies:
- '@tanstack/history': 1.161.4
+ '@tanstack/history': 1.161.6
'@tanstack/store': 0.9.2
cookie-es: 2.0.0
seroval: 1.5.1
@@ -5431,20 +5432,20 @@ snapshots:
tiny-invariant: 1.3.3
tiny-warning: 1.0.3
- '@tanstack/router-devtools-core@1.163.3(@tanstack/router-core@1.167.0)(csstype@3.2.3)':
+ '@tanstack/router-devtools-core@1.166.9(@tanstack/router-core@1.167.5)(csstype@3.2.3)':
dependencies:
- '@tanstack/router-core': 1.167.0
+ '@tanstack/router-core': 1.167.5
clsx: 2.1.1
goober: 2.1.18(csstype@3.2.3)
tiny-invariant: 1.3.3
optionalDependencies:
csstype: 3.2.3
- '@tanstack/router-generator@1.164.0':
+ '@tanstack/router-generator@1.166.13':
dependencies:
- '@tanstack/router-core': 1.163.3
- '@tanstack/router-utils': 1.161.4
- '@tanstack/virtual-file-routes': 1.161.4
+ '@tanstack/router-core': 1.167.5
+ '@tanstack/router-utils': 1.161.6
+ '@tanstack/virtual-file-routes': 1.161.7
prettier: 3.8.1
recast: 0.23.11
source-map: 0.7.6
@@ -5453,7 +5454,7 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@tanstack/router-plugin@1.164.0(@tanstack/react-router@1.167.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))':
+ '@tanstack/router-plugin@1.166.14(@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))':
dependencies:
'@babel/core': 7.29.0
'@babel/plugin-syntax-jsx': 7.28.6(@babel/core@7.29.0)
@@ -5461,24 +5462,24 @@ snapshots:
'@babel/template': 7.28.6
'@babel/traverse': 7.29.0
'@babel/types': 7.29.0
- '@tanstack/router-core': 1.163.3
- '@tanstack/router-generator': 1.164.0
- '@tanstack/router-utils': 1.161.4
- '@tanstack/virtual-file-routes': 1.161.4
+ '@tanstack/router-core': 1.167.5
+ '@tanstack/router-generator': 1.166.13
+ '@tanstack/router-utils': 1.161.6
+ '@tanstack/virtual-file-routes': 1.161.7
chokidar: 3.6.0
unplugin: 2.3.11
zod: 3.25.76
optionalDependencies:
- '@tanstack/react-router': 1.167.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
- vite: 7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0)
+ '@tanstack/react-router': 1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+ vite: 7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
transitivePeerDependencies:
- supports-color
- '@tanstack/router-utils@1.161.4':
+ '@tanstack/router-utils@1.161.6':
dependencies:
'@babel/core': 7.29.0
'@babel/generator': 7.29.1
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/types': 7.29.0
ansis: 4.2.0
babel-dead-code-elimination: 1.0.12
@@ -5488,16 +5489,14 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@tanstack/store@0.9.1': {}
-
'@tanstack/store@0.9.2': {}
- '@tanstack/virtual-file-routes@1.161.4': {}
+ '@tanstack/virtual-file-routes@1.161.7': {}
'@trivago/prettier-plugin-sort-imports@6.0.2(prettier@3.8.1)':
dependencies:
'@babel/generator': 7.29.1
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/traverse': 7.29.0
'@babel/types': 7.29.0
javascript-natural-sort: 0.7.1
@@ -5516,7 +5515,7 @@ snapshots:
'@types/babel__core@7.20.5':
dependencies:
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/types': 7.29.0
'@types/babel__generator': 7.27.0
'@types/babel__template': 7.4.4
@@ -5528,14 +5527,14 @@ snapshots:
'@types/babel__template@7.4.4':
dependencies:
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/types': 7.29.0
'@types/babel__traverse@7.28.0':
dependencies:
'@babel/types': 7.29.0
- '@types/debug@4.1.12':
+ '@types/debug@4.1.13':
dependencies:
'@types/ms': 2.1.0
@@ -5557,9 +5556,9 @@ snapshots:
'@types/ms@2.1.0': {}
- '@types/node@24.11.0':
+ '@types/node@25.5.0':
dependencies:
- undici-types: 7.16.0
+ undici-types: 7.18.2
'@types/react-dom@19.2.3(@types/react@19.2.14)':
dependencies:
@@ -5577,100 +5576,100 @@ snapshots:
'@types/validate-npm-package-name@4.0.2': {}
- '@typescript-eslint/eslint-plugin@8.56.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)':
+ '@typescript-eslint/eslint-plugin@8.57.1(@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
dependencies:
'@eslint-community/regexpp': 4.12.2
- '@typescript-eslint/parser': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
- '@typescript-eslint/scope-manager': 8.56.1
- '@typescript-eslint/type-utils': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
- '@typescript-eslint/utils': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
- '@typescript-eslint/visitor-keys': 8.56.1
- eslint: 9.39.3(jiti@2.6.1)
+ '@typescript-eslint/parser': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+ '@typescript-eslint/scope-manager': 8.57.1
+ '@typescript-eslint/type-utils': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+ '@typescript-eslint/utils': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+ '@typescript-eslint/visitor-keys': 8.57.1
+ eslint: 9.39.4(jiti@2.6.1)
ignore: 7.0.5
natural-compare: 1.4.0
- ts-api-utils: 2.4.0(typescript@5.9.3)
+ ts-api-utils: 2.5.0(typescript@5.9.3)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
- '@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)':
+ '@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
dependencies:
- '@typescript-eslint/scope-manager': 8.56.1
- '@typescript-eslint/types': 8.56.1
- '@typescript-eslint/typescript-estree': 8.56.1(typescript@5.9.3)
- '@typescript-eslint/visitor-keys': 8.56.1
+ '@typescript-eslint/scope-manager': 8.57.1
+ '@typescript-eslint/types': 8.57.1
+ '@typescript-eslint/typescript-estree': 8.57.1(typescript@5.9.3)
+ '@typescript-eslint/visitor-keys': 8.57.1
debug: 4.4.3
- eslint: 9.39.3(jiti@2.6.1)
+ eslint: 9.39.4(jiti@2.6.1)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
- '@typescript-eslint/project-service@8.56.1(typescript@5.9.3)':
+ '@typescript-eslint/project-service@8.57.1(typescript@5.9.3)':
dependencies:
- '@typescript-eslint/tsconfig-utils': 8.56.1(typescript@5.9.3)
- '@typescript-eslint/types': 8.56.1
+ '@typescript-eslint/tsconfig-utils': 8.57.1(typescript@5.9.3)
+ '@typescript-eslint/types': 8.57.1
debug: 4.4.3
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
- '@typescript-eslint/scope-manager@8.56.1':
+ '@typescript-eslint/scope-manager@8.57.1':
dependencies:
- '@typescript-eslint/types': 8.56.1
- '@typescript-eslint/visitor-keys': 8.56.1
+ '@typescript-eslint/types': 8.57.1
+ '@typescript-eslint/visitor-keys': 8.57.1
- '@typescript-eslint/tsconfig-utils@8.56.1(typescript@5.9.3)':
+ '@typescript-eslint/tsconfig-utils@8.57.1(typescript@5.9.3)':
dependencies:
typescript: 5.9.3
- '@typescript-eslint/type-utils@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)':
+ '@typescript-eslint/type-utils@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
dependencies:
- '@typescript-eslint/types': 8.56.1
- '@typescript-eslint/typescript-estree': 8.56.1(typescript@5.9.3)
- '@typescript-eslint/utils': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
+ '@typescript-eslint/types': 8.57.1
+ '@typescript-eslint/typescript-estree': 8.57.1(typescript@5.9.3)
+ '@typescript-eslint/utils': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
debug: 4.4.3
- eslint: 9.39.3(jiti@2.6.1)
- ts-api-utils: 2.4.0(typescript@5.9.3)
+ eslint: 9.39.4(jiti@2.6.1)
+ ts-api-utils: 2.5.0(typescript@5.9.3)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
- '@typescript-eslint/types@8.56.1': {}
+ '@typescript-eslint/types@8.57.1': {}
- '@typescript-eslint/typescript-estree@8.56.1(typescript@5.9.3)':
+ '@typescript-eslint/typescript-estree@8.57.1(typescript@5.9.3)':
dependencies:
- '@typescript-eslint/project-service': 8.56.1(typescript@5.9.3)
- '@typescript-eslint/tsconfig-utils': 8.56.1(typescript@5.9.3)
- '@typescript-eslint/types': 8.56.1
- '@typescript-eslint/visitor-keys': 8.56.1
+ '@typescript-eslint/project-service': 8.57.1(typescript@5.9.3)
+ '@typescript-eslint/tsconfig-utils': 8.57.1(typescript@5.9.3)
+ '@typescript-eslint/types': 8.57.1
+ '@typescript-eslint/visitor-keys': 8.57.1
debug: 4.4.3
minimatch: 10.2.4
semver: 7.7.4
tinyglobby: 0.2.15
- ts-api-utils: 2.4.0(typescript@5.9.3)
+ ts-api-utils: 2.5.0(typescript@5.9.3)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
- '@typescript-eslint/utils@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)':
+ '@typescript-eslint/utils@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
dependencies:
- '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.3(jiti@2.6.1))
- '@typescript-eslint/scope-manager': 8.56.1
- '@typescript-eslint/types': 8.56.1
- '@typescript-eslint/typescript-estree': 8.56.1(typescript@5.9.3)
- eslint: 9.39.3(jiti@2.6.1)
+ '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.4(jiti@2.6.1))
+ '@typescript-eslint/scope-manager': 8.57.1
+ '@typescript-eslint/types': 8.57.1
+ '@typescript-eslint/typescript-estree': 8.57.1(typescript@5.9.3)
+ eslint: 9.39.4(jiti@2.6.1)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
- '@typescript-eslint/visitor-keys@8.56.1':
+ '@typescript-eslint/visitor-keys@8.57.1':
dependencies:
- '@typescript-eslint/types': 8.56.1
+ '@typescript-eslint/types': 8.57.1
eslint-visitor-keys: 5.0.1
'@ungap/structured-clone@1.3.0': {}
- '@vitejs/plugin-react@5.2.0(vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0))':
+ '@vitejs/plugin-react@5.2.0(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))':
dependencies:
'@babel/core': 7.29.0
'@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
@@ -5678,7 +5677,7 @@ snapshots:
'@rolldown/pluginutils': 1.0.0-rc.3
'@types/babel__core': 7.20.5
react-refresh: 0.18.0
- vite: 7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0)
+ vite: 7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
transitivePeerDependencies:
- supports-color
@@ -5743,7 +5742,7 @@ snapshots:
babel-dead-code-elimination@1.0.12:
dependencies:
'@babel/core': 7.29.0
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/traverse': 7.29.0
'@babel/types': 7.29.0
transitivePeerDependencies:
@@ -5755,7 +5754,7 @@ snapshots:
balanced-match@4.0.4: {}
- baseline-browser-mapping@2.10.0: {}
+ baseline-browser-mapping@2.10.9: {}
binary-extensions@2.3.0: {}
@@ -5792,10 +5791,10 @@ snapshots:
browserslist@4.28.1:
dependencies:
- baseline-browser-mapping: 2.10.0
- caniuse-lite: 1.0.30001775
- electron-to-chromium: 1.5.302
- node-releases: 2.0.27
+ baseline-browser-mapping: 2.10.9
+ caniuse-lite: 1.0.30001780
+ electron-to-chromium: 1.5.321
+ node-releases: 2.0.36
update-browserslist-db: 1.2.3(browserslist@4.28.1)
bundle-name@4.1.0:
@@ -5816,7 +5815,7 @@ snapshots:
callsites@3.1.0: {}
- caniuse-lite@1.0.30001775: {}
+ caniuse-lite@1.0.30001780: {}
ccount@2.0.1: {}
@@ -5902,7 +5901,7 @@ snapshots:
object-assign: 4.1.1
vary: 1.1.2
- cosmiconfig@9.0.0(typescript@5.9.3):
+ cosmiconfig@9.0.1(typescript@5.9.3):
dependencies:
env-paths: 2.2.1
import-fresh: 3.3.1
@@ -5970,7 +5969,7 @@ snapshots:
es-errors: 1.3.0
gopd: 1.2.0
- eciesjs@0.4.17:
+ eciesjs@0.4.18:
dependencies:
'@ecies/ciphers': 0.2.5(@noble/ciphers@1.3.0)
'@noble/ciphers': 1.3.0
@@ -5979,7 +5978,7 @@ snapshots:
ee-first@1.1.1: {}
- electron-to-chromium@1.5.302: {}
+ electron-to-chromium@1.5.321: {}
emoji-regex@10.6.0: {}
@@ -5987,11 +5986,13 @@ snapshots:
encodeurl@2.0.0: {}
- enhanced-resolve@5.20.0:
+ enhanced-resolve@5.20.1:
dependencies:
graceful-fs: 4.2.11
tapable: 2.3.0
+ entities@6.0.1: {}
+
env-paths@2.2.1: {}
error-ex@1.3.4:
@@ -6006,34 +6007,34 @@ snapshots:
dependencies:
es-errors: 1.3.0
- esbuild@0.27.3:
+ esbuild@0.27.4:
optionalDependencies:
- '@esbuild/aix-ppc64': 0.27.3
- '@esbuild/android-arm': 0.27.3
- '@esbuild/android-arm64': 0.27.3
- '@esbuild/android-x64': 0.27.3
- '@esbuild/darwin-arm64': 0.27.3
- '@esbuild/darwin-x64': 0.27.3
- '@esbuild/freebsd-arm64': 0.27.3
- '@esbuild/freebsd-x64': 0.27.3
- '@esbuild/linux-arm': 0.27.3
- '@esbuild/linux-arm64': 0.27.3
- '@esbuild/linux-ia32': 0.27.3
- '@esbuild/linux-loong64': 0.27.3
- '@esbuild/linux-mips64el': 0.27.3
- '@esbuild/linux-ppc64': 0.27.3
- '@esbuild/linux-riscv64': 0.27.3
- '@esbuild/linux-s390x': 0.27.3
- '@esbuild/linux-x64': 0.27.3
- '@esbuild/netbsd-arm64': 0.27.3
- '@esbuild/netbsd-x64': 0.27.3
- '@esbuild/openbsd-arm64': 0.27.3
- '@esbuild/openbsd-x64': 0.27.3
- '@esbuild/openharmony-arm64': 0.27.3
- '@esbuild/sunos-x64': 0.27.3
- '@esbuild/win32-arm64': 0.27.3
- '@esbuild/win32-ia32': 0.27.3
- '@esbuild/win32-x64': 0.27.3
+ '@esbuild/aix-ppc64': 0.27.4
+ '@esbuild/android-arm': 0.27.4
+ '@esbuild/android-arm64': 0.27.4
+ '@esbuild/android-x64': 0.27.4
+ '@esbuild/darwin-arm64': 0.27.4
+ '@esbuild/darwin-x64': 0.27.4
+ '@esbuild/freebsd-arm64': 0.27.4
+ '@esbuild/freebsd-x64': 0.27.4
+ '@esbuild/linux-arm': 0.27.4
+ '@esbuild/linux-arm64': 0.27.4
+ '@esbuild/linux-ia32': 0.27.4
+ '@esbuild/linux-loong64': 0.27.4
+ '@esbuild/linux-mips64el': 0.27.4
+ '@esbuild/linux-ppc64': 0.27.4
+ '@esbuild/linux-riscv64': 0.27.4
+ '@esbuild/linux-s390x': 0.27.4
+ '@esbuild/linux-x64': 0.27.4
+ '@esbuild/netbsd-arm64': 0.27.4
+ '@esbuild/netbsd-x64': 0.27.4
+ '@esbuild/openbsd-arm64': 0.27.4
+ '@esbuild/openbsd-x64': 0.27.4
+ '@esbuild/openharmony-arm64': 0.27.4
+ '@esbuild/sunos-x64': 0.27.4
+ '@esbuild/win32-arm64': 0.27.4
+ '@esbuild/win32-ia32': 0.27.4
+ '@esbuild/win32-x64': 0.27.4
escalade@3.2.0: {}
@@ -6043,24 +6044,24 @@ snapshots:
escape-string-regexp@5.0.0: {}
- eslint-config-prettier@10.1.8(eslint@9.39.3(jiti@2.6.1)):
+ eslint-config-prettier@10.1.8(eslint@9.39.4(jiti@2.6.1)):
dependencies:
- eslint: 9.39.3(jiti@2.6.1)
+ eslint: 9.39.4(jiti@2.6.1)
- eslint-plugin-react-hooks@7.0.1(eslint@9.39.3(jiti@2.6.1)):
+ eslint-plugin-react-hooks@7.0.1(eslint@9.39.4(jiti@2.6.1)):
dependencies:
'@babel/core': 7.29.0
- '@babel/parser': 7.29.0
- eslint: 9.39.3(jiti@2.6.1)
+ '@babel/parser': 7.29.2
+ eslint: 9.39.4(jiti@2.6.1)
hermes-parser: 0.25.1
zod: 4.3.6
zod-validation-error: 4.0.2(zod@4.3.6)
transitivePeerDependencies:
- supports-color
- eslint-plugin-react-refresh@0.4.26(eslint@9.39.3(jiti@2.6.1)):
+ eslint-plugin-react-refresh@0.4.26(eslint@9.39.4(jiti@2.6.1)):
dependencies:
- eslint: 9.39.3(jiti@2.6.1)
+ eslint: 9.39.4(jiti@2.6.1)
eslint-scope@8.4.0:
dependencies:
@@ -6073,15 +6074,15 @@ snapshots:
eslint-visitor-keys@5.0.1: {}
- eslint@9.39.3(jiti@2.6.1):
+ eslint@9.39.4(jiti@2.6.1):
dependencies:
- '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.3(jiti@2.6.1))
+ '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.4(jiti@2.6.1))
'@eslint-community/regexpp': 4.12.2
'@eslint/config-array': 0.21.2
'@eslint/config-helpers': 0.4.2
'@eslint/core': 0.17.0
'@eslint/eslintrc': 3.3.5
- '@eslint/js': 9.39.3
+ '@eslint/js': 9.39.4
'@eslint/plugin-kit': 0.4.1
'@humanfs/node': 0.16.7
'@humanwhocodes/module-importer': 1.0.1
@@ -6270,10 +6271,10 @@ snapshots:
flat-cache@4.0.1:
dependencies:
- flatted: 3.4.1
+ flatted: 3.4.2
keyv: 4.5.4
- flatted@3.4.1: {}
+ flatted@3.4.2: {}
formdata-polyfill@4.0.10:
dependencies:
@@ -6283,7 +6284,7 @@ snapshots:
fresh@2.0.0: {}
- fs-extra@11.3.3:
+ fs-extra@11.3.4:
dependencies:
graceful-fs: 4.2.11
jsonfile: 6.2.0
@@ -6296,8 +6297,6 @@ snapshots:
fuzzysort@3.1.0: {}
- fzf@0.5.2: {}
-
gensync@1.0.0-beta.2: {}
get-caller-file@2.0.5: {}
@@ -6357,7 +6356,7 @@ snapshots:
graceful-fs@4.2.11: {}
- graphql@16.13.0: {}
+ graphql@16.13.1: {}
has-flag@4.0.0: {}
@@ -6367,6 +6366,43 @@ snapshots:
dependencies:
function-bind: 1.1.2
+ hast-util-from-parse5@8.0.3:
+ dependencies:
+ '@types/hast': 3.0.4
+ '@types/unist': 3.0.3
+ devlop: 1.1.0
+ hastscript: 9.0.1
+ property-information: 7.1.0
+ vfile: 6.0.3
+ vfile-location: 5.0.3
+ web-namespaces: 2.0.1
+
+ hast-util-parse-selector@4.0.0:
+ dependencies:
+ '@types/hast': 3.0.4
+
+ hast-util-raw@9.1.0:
+ dependencies:
+ '@types/hast': 3.0.4
+ '@types/unist': 3.0.3
+ '@ungap/structured-clone': 1.3.0
+ hast-util-from-parse5: 8.0.3
+ hast-util-to-parse5: 8.0.1
+ html-void-elements: 3.0.0
+ mdast-util-to-hast: 13.2.1
+ parse5: 7.3.0
+ unist-util-position: 5.0.0
+ unist-util-visit: 5.1.0
+ vfile: 6.0.3
+ web-namespaces: 2.0.1
+ zwitch: 2.0.4
+
+ hast-util-sanitize@5.0.2:
+ dependencies:
+ '@types/hast': 3.0.4
+ '@ungap/structured-clone': 1.3.0
+ unist-util-position: 5.0.0
+
hast-util-to-jsx-runtime@2.3.6:
dependencies:
'@types/estree': 1.0.8
@@ -6387,10 +6423,28 @@ snapshots:
transitivePeerDependencies:
- supports-color
+ hast-util-to-parse5@8.0.1:
+ dependencies:
+ '@types/hast': 3.0.4
+ comma-separated-tokens: 2.0.3
+ devlop: 1.1.0
+ property-information: 7.1.0
+ space-separated-tokens: 2.0.2
+ web-namespaces: 2.0.1
+ zwitch: 2.0.4
+
hast-util-whitespace@3.0.0:
dependencies:
'@types/hast': 3.0.4
+ hastscript@9.0.1:
+ dependencies:
+ '@types/hast': 3.0.4
+ comma-separated-tokens: 2.0.3
+ hast-util-parse-selector: 4.0.0
+ property-information: 7.1.0
+ space-separated-tokens: 2.0.2
+
headers-polyfill@4.0.3: {}
hermes-estree@0.25.1: {}
@@ -6399,7 +6453,7 @@ snapshots:
dependencies:
hermes-estree: 0.25.1
- hono@4.12.7: {}
+ hono@4.12.8: {}
html-parse-stringify@3.0.1:
dependencies:
@@ -6407,6 +6461,8 @@ snapshots:
html-url-attributes@3.0.1: {}
+ html-void-elements@3.0.0: {}
+
http-errors@2.0.1:
dependencies:
depd: 2.0.0
@@ -6428,11 +6484,11 @@ snapshots:
i18next-browser-languagedetector@8.2.1:
dependencies:
- '@babel/runtime': 7.28.6
+ '@babel/runtime': 7.29.2
- i18next@25.8.14(typescript@5.9.3):
+ i18next@25.8.20(typescript@5.9.3):
dependencies:
- '@babel/runtime': 7.28.6
+ '@babel/runtime': 7.29.2
optionalDependencies:
typescript: 5.9.3
@@ -6528,7 +6584,7 @@ snapshots:
jiti@2.6.1: {}
- jose@6.1.3: {}
+ jose@6.2.2: {}
jotai@2.18.1(@babel/core@7.29.0)(@babel/template@7.28.6)(@types/react@19.2.14)(react@19.2.4):
optionalDependencies:
@@ -6578,54 +6634,54 @@ snapshots:
prelude-ls: 1.2.1
type-check: 0.4.0
- lightningcss-android-arm64@1.31.1:
+ lightningcss-android-arm64@1.32.0:
optional: true
- lightningcss-darwin-arm64@1.31.1:
+ lightningcss-darwin-arm64@1.32.0:
optional: true
- lightningcss-darwin-x64@1.31.1:
+ lightningcss-darwin-x64@1.32.0:
optional: true
- lightningcss-freebsd-x64@1.31.1:
+ lightningcss-freebsd-x64@1.32.0:
optional: true
- lightningcss-linux-arm-gnueabihf@1.31.1:
+ lightningcss-linux-arm-gnueabihf@1.32.0:
optional: true
- lightningcss-linux-arm64-gnu@1.31.1:
+ lightningcss-linux-arm64-gnu@1.32.0:
optional: true
- lightningcss-linux-arm64-musl@1.31.1:
+ lightningcss-linux-arm64-musl@1.32.0:
optional: true
- lightningcss-linux-x64-gnu@1.31.1:
+ lightningcss-linux-x64-gnu@1.32.0:
optional: true
- lightningcss-linux-x64-musl@1.31.1:
+ lightningcss-linux-x64-musl@1.32.0:
optional: true
- lightningcss-win32-arm64-msvc@1.31.1:
+ lightningcss-win32-arm64-msvc@1.32.0:
optional: true
- lightningcss-win32-x64-msvc@1.31.1:
+ lightningcss-win32-x64-msvc@1.32.0:
optional: true
- lightningcss@1.31.1:
+ lightningcss@1.32.0:
dependencies:
detect-libc: 2.1.2
optionalDependencies:
- lightningcss-android-arm64: 1.31.1
- lightningcss-darwin-arm64: 1.31.1
- lightningcss-darwin-x64: 1.31.1
- lightningcss-freebsd-x64: 1.31.1
- lightningcss-linux-arm-gnueabihf: 1.31.1
- lightningcss-linux-arm64-gnu: 1.31.1
- lightningcss-linux-arm64-musl: 1.31.1
- lightningcss-linux-x64-gnu: 1.31.1
- lightningcss-linux-x64-musl: 1.31.1
- lightningcss-win32-arm64-msvc: 1.31.1
- lightningcss-win32-x64-msvc: 1.31.1
+ lightningcss-android-arm64: 1.32.0
+ lightningcss-darwin-arm64: 1.32.0
+ lightningcss-darwin-x64: 1.32.0
+ lightningcss-freebsd-x64: 1.32.0
+ lightningcss-linux-arm-gnueabihf: 1.32.0
+ lightningcss-linux-arm64-gnu: 1.32.0
+ lightningcss-linux-arm64-musl: 1.32.0
+ lightningcss-linux-x64-gnu: 1.32.0
+ lightningcss-linux-x64-musl: 1.32.0
+ lightningcss-win32-arm64-msvc: 1.32.0
+ lightningcss-win32-x64-msvc: 1.32.0
lines-and-columns@1.2.4: {}
@@ -6988,7 +7044,7 @@ snapshots:
micromark@4.0.2:
dependencies:
- '@types/debug': 4.1.12
+ '@types/debug': 4.1.13
debug: 4.4.3
decode-named-character-reference: 1.3.0
devlop: 1.1.0
@@ -7039,14 +7095,14 @@ snapshots:
ms@2.1.3: {}
- msw@2.12.10(@types/node@24.11.0)(typescript@5.9.3):
+ msw@2.12.13(@types/node@25.5.0)(typescript@5.9.3):
dependencies:
- '@inquirer/confirm': 5.1.21(@types/node@24.11.0)
+ '@inquirer/confirm': 5.1.21(@types/node@25.5.0)
'@mswjs/interceptors': 0.41.3
'@open-draft/deferred-promise': 2.2.0
'@types/statuses': 2.0.6
cookie: 1.1.1
- graphql: 16.13.0
+ graphql: 16.13.1
headers-polyfill: 4.0.3
is-node-process: 1.2.0
outvariant: 1.4.3
@@ -7055,8 +7111,8 @@ snapshots:
rettime: 0.10.1
statuses: 2.0.2
strict-event-emitter: 0.5.1
- tough-cookie: 6.0.0
- type-fest: 5.4.4
+ tough-cookie: 6.0.1
+ type-fest: 5.5.0
until-async: 3.0.2
yargs: 17.7.2
optionalDependencies:
@@ -7080,7 +7136,7 @@ snapshots:
fetch-blob: 3.2.0
formdata-polyfill: 4.0.10
- node-releases@2.0.27: {}
+ node-releases@2.0.36: {}
normalize-path@3.0.0: {}
@@ -7155,8 +7211,6 @@ snapshots:
dependencies:
p-limit: 3.1.0
- package-manager-detector@1.6.0: {}
-
parent-module@1.0.1:
dependencies:
callsites: 3.1.0
@@ -7186,6 +7240,10 @@ snapshots:
parse-statements@1.0.11: {}
+ parse5@7.3.0:
+ dependencies:
+ entities: 6.0.1
+
parseurl@1.3.3: {}
path-browserify@1.0.1: {}
@@ -7220,7 +7278,7 @@ snapshots:
cssesc: 3.0.0
util-deprecate: 1.0.2
- postcss@8.5.6:
+ postcss@8.5.8:
dependencies:
nanoid: 3.3.11
picocolors: 1.1.1
@@ -7339,11 +7397,11 @@ snapshots:
react: 19.2.4
scheduler: 0.27.0
- react-i18next@16.5.8(i18next@25.8.14(typescript@5.9.3))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3):
+ react-i18next@16.5.8(i18next@25.8.20(typescript@5.9.3))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3):
dependencies:
- '@babel/runtime': 7.28.6
+ '@babel/runtime': 7.29.2
html-parse-stringify: 3.0.1
- i18next: 25.8.14(typescript@5.9.3)
+ i18next: 25.8.20(typescript@5.9.3)
react: 19.2.4
use-sync-external-store: 1.6.0(react@19.2.4)
optionalDependencies:
@@ -7399,7 +7457,7 @@ snapshots:
react-textarea-autosize@8.5.9(@types/react@19.2.14)(react@19.2.4):
dependencies:
- '@babel/runtime': 7.28.6
+ '@babel/runtime': 7.29.2
react: 19.2.4
use-composed-ref: 1.4.0(@types/react@19.2.14)(react@19.2.4)
use-latest: 1.3.0(@types/react@19.2.14)(react@19.2.4)
@@ -7420,6 +7478,17 @@ snapshots:
tiny-invariant: 1.3.3
tslib: 2.8.1
+ rehype-raw@7.0.0:
+ dependencies:
+ '@types/hast': 3.0.4
+ hast-util-raw: 9.1.0
+ vfile: 6.0.3
+
+ rehype-sanitize@6.0.0:
+ dependencies:
+ '@types/hast': 3.0.4
+ hast-util-sanitize: 5.0.2
+
remark-gfm@4.0.1:
dependencies:
'@types/mdast': 4.0.4
@@ -7542,16 +7611,10 @@ snapshots:
transitivePeerDependencies:
- supports-color
- seroval-plugins@1.5.0(seroval@1.5.0):
- dependencies:
- seroval: 1.5.0
-
seroval-plugins@1.5.1(seroval@1.5.1):
dependencies:
seroval: 1.5.1
- seroval@1.5.0: {}
-
seroval@1.5.1: {}
serve-static@2.2.1:
@@ -7565,33 +7628,32 @@ snapshots:
setprototypeof@1.2.0: {}
- shadcn@4.0.5(@types/node@24.11.0)(typescript@5.9.3):
+ shadcn@4.1.0(@types/node@25.5.0)(typescript@5.9.3):
dependencies:
- '@antfu/ni': 25.0.0
'@babel/core': 7.29.0
- '@babel/parser': 7.29.0
+ '@babel/parser': 7.29.2
'@babel/plugin-transform-typescript': 7.28.6(@babel/core@7.29.0)
'@babel/preset-typescript': 7.28.5(@babel/core@7.29.0)
- '@dotenvx/dotenvx': 1.52.0
+ '@dotenvx/dotenvx': 1.57.0
'@modelcontextprotocol/sdk': 1.27.1(zod@3.25.76)
'@types/validate-npm-package-name': 4.0.2
browserslist: 4.28.1
commander: 14.0.3
- cosmiconfig: 9.0.0(typescript@5.9.3)
+ cosmiconfig: 9.0.1(typescript@5.9.3)
dedent: 1.7.2
deepmerge: 4.3.1
diff: 8.0.3
execa: 9.6.1
fast-glob: 3.3.3
- fs-extra: 11.3.3
+ fs-extra: 11.3.4
fuzzysort: 3.1.0
https-proxy-agent: 7.0.6
kleur: 4.1.5
- msw: 2.12.10(@types/node@24.11.0)(typescript@5.9.3)
+ msw: 2.12.13(@types/node@25.5.0)(typescript@5.9.3)
node-fetch: 3.3.2
open: 11.0.0
ora: 8.2.0
- postcss: 8.5.6
+ postcss: 8.5.8
postcss-selector-parser: 7.1.1
prompts: 2.4.2
recast: 0.23.11
@@ -7728,7 +7790,7 @@ snapshots:
tailwind-merge@3.5.0: {}
- tailwindcss@4.2.1: {}
+ tailwindcss@4.2.2: {}
tapable@2.3.0: {}
@@ -7736,18 +7798,16 @@ snapshots:
tiny-warning@1.0.3: {}
- tinyexec@1.0.2: {}
-
tinyglobby@0.2.15:
dependencies:
fdir: 6.5.0(picomatch@4.0.3)
picomatch: 4.0.3
- tldts-core@7.0.23: {}
+ tldts-core@7.0.26: {}
- tldts@7.0.23:
+ tldts@7.0.26:
dependencies:
- tldts-core: 7.0.23
+ tldts-core: 7.0.26
to-regex-range@5.0.1:
dependencies:
@@ -7755,15 +7815,15 @@ snapshots:
toidentifier@1.0.1: {}
- tough-cookie@6.0.0:
+ tough-cookie@6.0.1:
dependencies:
- tldts: 7.0.23
+ tldts: 7.0.26
trim-lines@3.0.1: {}
trough@2.2.0: {}
- ts-api-utils@2.4.0(typescript@5.9.3):
+ ts-api-utils@2.5.0(typescript@5.9.3):
dependencies:
typescript: 5.9.3
@@ -7782,7 +7842,7 @@ snapshots:
tsx@4.21.0:
dependencies:
- esbuild: 0.27.3
+ esbuild: 0.27.4
get-tsconfig: 4.13.6
optionalDependencies:
fsevents: 2.3.3
@@ -7793,7 +7853,7 @@ snapshots:
dependencies:
prelude-ls: 1.2.1
- type-fest@5.4.4:
+ type-fest@5.5.0:
dependencies:
tagged-tag: 1.0.0
@@ -7803,20 +7863,20 @@ snapshots:
media-typer: 1.1.0
mime-types: 3.0.2
- typescript-eslint@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3):
+ typescript-eslint@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3):
dependencies:
- '@typescript-eslint/eslint-plugin': 8.56.1(@typescript-eslint/parser@8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
- '@typescript-eslint/parser': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
- '@typescript-eslint/typescript-estree': 8.56.1(typescript@5.9.3)
- '@typescript-eslint/utils': 8.56.1(eslint@9.39.3(jiti@2.6.1))(typescript@5.9.3)
- eslint: 9.39.3(jiti@2.6.1)
+ '@typescript-eslint/eslint-plugin': 8.57.1(@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+ '@typescript-eslint/parser': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+ '@typescript-eslint/typescript-estree': 8.57.1(typescript@5.9.3)
+ '@typescript-eslint/utils': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+ eslint: 9.39.4(jiti@2.6.1)
typescript: 5.9.3
transitivePeerDependencies:
- supports-color
typescript@5.9.3: {}
- undici-types@7.16.0: {}
+ undici-types@7.18.2: {}
unicorn-magic@0.3.0: {}
@@ -7920,6 +7980,11 @@ snapshots:
vary@1.1.2: {}
+ vfile-location@5.0.3:
+ dependencies:
+ '@types/unist': 3.0.3
+ vfile: 6.0.3
+
vfile-message@4.0.3:
dependencies:
'@types/unist': 3.0.3
@@ -7930,23 +7995,25 @@ snapshots:
'@types/unist': 3.0.3
vfile-message: 4.0.3
- vite@7.3.1(@types/node@24.11.0)(jiti@2.6.1)(lightningcss@1.31.1)(tsx@4.21.0):
+ vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0):
dependencies:
- esbuild: 0.27.3
+ esbuild: 0.27.4
fdir: 6.5.0(picomatch@4.0.3)
picomatch: 4.0.3
- postcss: 8.5.6
+ postcss: 8.5.8
rollup: 4.59.0
tinyglobby: 0.2.15
optionalDependencies:
- '@types/node': 24.11.0
+ '@types/node': 25.5.0
fsevents: 2.3.3
jiti: 2.6.1
- lightningcss: 1.31.1
+ lightningcss: 1.32.0
tsx: 4.21.0
void-elements@3.1.0: {}
+ web-namespaces@2.0.1: {}
+
web-streams-polyfill@3.3.3: {}
webpack-virtual-modules@0.6.2: {}
diff --git a/web/frontend/src/api/models.ts b/web/frontend/src/api/models.ts
index 8e49b48b4..2fd042593 100644
--- a/web/frontend/src/api/models.ts
+++ b/web/frontend/src/api/models.ts
@@ -17,6 +17,7 @@ export interface ModelInfo {
max_tokens_field?: string
request_timeout?: number
thinking_level?: string
+ extra_body?: Record
// Meta
configured: boolean
is_default: boolean
diff --git a/web/frontend/src/components/chat/assistant-message.tsx b/web/frontend/src/components/chat/assistant-message.tsx
index 150f2f87d..05da3ceb1 100644
--- a/web/frontend/src/components/chat/assistant-message.tsx
+++ b/web/frontend/src/components/chat/assistant-message.tsx
@@ -1,6 +1,8 @@
import { IconCheck, IconCopy } from "@tabler/icons-react"
import { useState } from "react"
import ReactMarkdown from "react-markdown"
+import rehypeRaw from "rehype-raw"
+import rehypeSanitize from "rehype-sanitize"
import remarkGfm from "remark-gfm"
import { Button } from "@/components/ui/button"
@@ -42,7 +44,12 @@ export function AssistantMessage({
- {content}
+
+ {content}
+
-
diff --git a/web/frontend/src/components/config/config-page.tsx b/web/frontend/src/components/config/config-page.tsx
index e533b956f..ee24aafaa 100644
--- a/web/frontend/src/components/config/config-page.tsx
+++ b/web/frontend/src/components/config/config-page.tsx
@@ -147,6 +147,9 @@ export function ConfigPage() {
const maxTokens = parseIntField(form.maxTokens, "Max tokens", {
min: 1,
})
+ const contextWindow = form.contextWindow.trim()
+ ? parseIntField(form.contextWindow, "Context window", { min: 1 })
+ : undefined
const maxToolIterations = parseIntField(
form.maxToolIterations,
"Max tool iterations",
@@ -201,6 +204,7 @@ export function ConfigPage() {
workspace,
restrict_to_workspace: form.restrictToWorkspace,
max_tokens: maxTokens,
+ context_window: contextWindow,
max_tool_iterations: maxToolIterations,
summarize_message_threshold: summarizeMessageThreshold,
summarize_token_percent: summarizeTokenPercent,
diff --git a/web/frontend/src/components/config/config-sections.tsx b/web/frontend/src/components/config/config-sections.tsx
index 517185eda..d938a93d4 100644
--- a/web/frontend/src/components/config/config-sections.tsx
+++ b/web/frontend/src/components/config/config-sections.tsx
@@ -106,6 +106,20 @@ export function AgentDefaultsSection({
/>
+
+
+
-
+
{selectedSkillDetail.content}
diff --git a/web/frontend/src/i18n/locales/en.json b/web/frontend/src/i18n/locales/en.json
index 7b3ad0911..0ff2beb25 100644
--- a/web/frontend/src/i18n/locales/en.json
+++ b/web/frontend/src/i18n/locales/en.json
@@ -17,7 +17,7 @@
"chat": {
"welcome": "How can I help you today?",
"welcomeDesc": "Ask me about weather, settings, or any other tasks. I'm here to assist you.",
- "placeholder": "Start a new message...",
+ "placeholder": "Start a new message...\nPress Enter to send, Shift + Enter for a new line",
"newChat": "New Chat",
"notConnected": "Gateway is not running. Start it to chat.",
"thinking": {
@@ -415,6 +415,8 @@
"cron_exec_timeout_hint": "Maximum runtime for scheduled commands. Set to 0 to disable the timeout.",
"max_tokens": "Max Tokens",
"max_tokens_hint": "Upper token limit per model response.",
+ "context_window": "Context Window",
+ "context_window_hint": "Model input context capacity in tokens. Leave empty to use the default (4x max tokens).",
"max_tool_iterations": "Max Tool Iterations",
"max_tool_iterations_hint": "Maximum tool-call loops in a single task.",
"summarize_threshold": "Summarize Message Threshold",
diff --git a/web/frontend/src/i18n/locales/zh.json b/web/frontend/src/i18n/locales/zh.json
index d1ffa1ac9..fc1f007ae 100644
--- a/web/frontend/src/i18n/locales/zh.json
+++ b/web/frontend/src/i18n/locales/zh.json
@@ -17,7 +17,7 @@
"chat": {
"welcome": "今天我能为您做些什么？",
"welcomeDesc": "您可以询问我天气、设置或其他任何任务，我随时为您效劳。",
- "placeholder": "输入新消息...",
+ "placeholder": "输入新消息...\n按 Enter 发送，Shift + Enter 换行",
"newChat": "新建对话",
"notConnected": "服务未运行，请先启动以进行对话。",
"thinking": {
@@ -415,6 +415,8 @@
"cron_exec_timeout_hint": "定时任务中命令的最长运行时间。设置为 0 表示不限制超时。",
"max_tokens": "最大 Token 数",
"max_tokens_hint": "单次模型响应允许的最大 Token 数。",
+ "context_window": "上下文窗口",
+ "context_window_hint": "模型输入上下文容量（Token 数）。留空使用默认值（最大 Token 数的 4 倍）。",
"max_tool_iterations": "最大工具迭代次数",
"max_tool_iterations_hint": "单个任务中允许的工具调用循环上限。",
"summarize_threshold": "触发摘要的消息阈值",
diff --git a/workspace/AGENT.md b/workspace/AGENT.md
new file mode 100644
index 000000000..08f55a1b7
--- /dev/null
+++ b/workspace/AGENT.md
@@ -0,0 +1,45 @@
+---
+name: pico
+description: >
+ The default general-purpose assistant for everyday conversation, problem
+ solving, and workspace help.
+---
+
+You are Pico, the default assistant for this workspace.
+Your name is PicoClaw 🦞.
+## Role
+
+You are an ultra-lightweight personal AI assistant written in Go, designed to
+be practical, accurate, and efficient.
+
+## Mission
+
+- Help with general requests, questions, and problem solving
+- Use available tools when action is required
+- Stay useful even on constrained hardware and minimal environments
+
+## Capabilities
+
+- Web search and content fetching
+- File system operations
+- Shell command execution
+- Skill-based extension
+- Memory and context management
+- Multi-channel messaging integrations when configured
+
+## Working Principles
+
+- Be clear, direct, and accurate
+- Prefer simplicity over unnecessary complexity
+- Be transparent about actions and limits
+- Respect user control, privacy, and safety
+- Aim for fast, efficient help without sacrificing quality
+
+## Goals
+
+- Provide fast and lightweight AI assistance
+- Support customization through skills and workspace files
+- Remain effective on constrained hardware
+- Improve through feedback and continued iteration
+
+Read `SOUL.md` as part of your identity and communication style.
diff --git a/workspace/AGENTS.md b/workspace/AGENTS.md
deleted file mode 100644
index 5f5fa6480..000000000
--- a/workspace/AGENTS.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Agent Instructions
-
-You are a helpful AI assistant. Be concise, accurate, and friendly.
-
-## Guidelines
-
-- Always explain what you're doing before taking actions
-- Ask for clarification when request is ambiguous
-- Use tools to help accomplish tasks
-- Remember important information in your memory files
-- Be proactive and helpful
-- Learn from user feedback
\ No newline at end of file
diff --git a/workspace/IDENTITY.md b/workspace/IDENTITY.md
deleted file mode 100644
index 20e3e49fa..000000000
--- a/workspace/IDENTITY.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Identity
-
-## Name
-PicoClaw 🦞
-
-## Description
-Ultra-lightweight personal AI assistant written in Go, inspired by nanobot.
-
-## Purpose
-- Provide intelligent AI assistance with minimal resource usage
-- Support multiple LLM providers (OpenAI, Anthropic, Zhipu, etc.)
-- Enable easy customization through skills system
-- Run on minimal hardware ($10 boards, <10MB RAM)
-
-## Capabilities
-
-- Web search and content fetching
-- File system operations (read, write, edit)
-- Shell command execution
-- Multi-channel messaging (Telegram, WhatsApp, Feishu)
-- Skill-based extensibility
-- Memory and context management
-
-## Philosophy
-
-- Simplicity over complexity
-- Performance over features
-- User control and privacy
-- Transparent operation
-- Community-driven development
-
-## Goals
-
-- Provide a fast, lightweight AI assistant
-- Support offline-first operation where possible
-- Enable easy customization and extension
-- Maintain high quality responses
-- Run efficiently on constrained hardware
-
-## License
-MIT License - Free and open source
-
-## Repository
-https://github.com/sipeed/picoclaw
-
-## Contact
-Issues: https://github.com/sipeed/picoclaw/issues
-Discussions: https://github.com/sipeed/picoclaw/discussions
-
----
-
-"Every bit helps, every bit matters."
-- Picoclaw
\ No newline at end of file
diff --git a/workspace/SOUL.md b/workspace/SOUL.md
index 0be8834f5..8a6371ff9 100644
--- a/workspace/SOUL.md
+++ b/workspace/SOUL.md
@@ -1,6 +1,6 @@
# Soul
-I am picoclaw, a lightweight AI assistant powered by AI.
+I am PicoClaw: calm, helpful, and practical.
## Personality
@@ -8,10 +8,12 @@ I am picoclaw, a lightweight AI assistant powered by AI.
- Concise and to the point
- Curious and eager to learn
- Honest and transparent
+- Calm under uncertainty
## Values
- Accuracy over speed
- User privacy and safety
- Transparency in actions
-- Continuous improvement
\ No newline at end of file
+- Continuous improvement
+- Simplicity over unnecessary complexity
diff --git a/workspace/USER.md b/workspace/USER.md
index 91398a019..9a3419d87 100644
--- a/workspace/USER.md
+++ b/workspace/USER.md
@@ -1,6 +1,6 @@
# User
-Information about user goes here.
+Information about the user goes here.
## Preferences
@@ -18,4 +18,4 @@ Information about user goes here.
- What the user wants to learn from AI
- Preferred interaction style
-- Areas of interest
\ No newline at end of file
+- Areas of interest
diff --git a/workspace/skills/agent-browser/SKILL.md b/workspace/skills/agent-browser/SKILL.md
new file mode 100644
index 000000000..43505996d
--- /dev/null
+++ b/workspace/skills/agent-browser/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: agent-browser
+description: "Browser automation via agent-browser CLI. Use when the user needs to navigate websites, fill forms, click buttons, take screenshots, extract data, or test web apps."
+metadata: {"nanobot":{"emoji":"🌐","requires":{"bins":["agent-browser"]},"install":[{"id":"npm","kind":"npm","package":"agent-browser","global":true,"bins":["agent-browser"],"label":"Install agent-browser (npm)"}]}}
+---
+
+# Agent Browser
+
+CLI browser automation via Chrome/Chromium CDP. Install: `npm i -g agent-browser && agent-browser install`.
+
+**Before using this skill**, verify the tool is available by running `which agent-browser`. If the command is not found, tell the user that browser automation requires the `agent-browser` CLI and Chromium, which are only available in the heavy container image. Do not attempt to install it at runtime.
+
+## Core Workflow
+
+1. `agent-browser open ` — navigate
+2. `agent-browser snapshot -i` — get interactive elements with refs (`@e1`, `@e2`, ...)
+3. Interact using refs — `click @e1`, `fill @e2 "text"`
+4. Re-snapshot after any navigation or DOM change — refs are invalidated
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# @e1 [input] "Email", @e2 [input] "Password", @e3 [button] "Submit"
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "secret"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i
+```
+
+Chain commands with `&&` when you don't need intermediate output:
+```bash
+agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+```
+
+## Commands
+
+```bash
+# Navigation
+agent-browser open
+agent-browser close
+
+# Snapshot
+agent-browser snapshot -i # Interactive elements with refs
+agent-browser snapshot -s "#selector" # Scope to CSS selector
+
+# Interaction (use @refs from snapshot)
+agent-browser click @e1
+agent-browser fill @e2 "text" # Clear + type
+agent-browser type @e2 "text" # Type without clearing
+agent-browser select @e1 "option"
+agent-browser check @e1
+agent-browser press Enter
+agent-browser scroll down 500
+
+# Get info
+agent-browser get text @e1
+agent-browser get url
+agent-browser get title
+
+# Wait
+agent-browser wait @e1 # Wait for element
+agent-browser wait --load networkidle # Wait for network idle
+agent-browser wait --url "**/dashboard" # Wait for URL pattern
+agent-browser wait --text "Welcome" # Wait for text
+agent-browser wait 2000 # Wait ms
+
+# Capture
+agent-browser screenshot # Screenshot to temp dir
+agent-browser screenshot --full # Full page
+agent-browser screenshot --annotate # With numbered element labels ([N] -> @eN)
+agent-browser pdf output.pdf
+
+# Semantic locators (when refs unavailable)
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find role button click --name "Submit"
+```
+
+## Authentication
+
+```bash
+# Option 1: Import from user's running Chrome
+agent-browser --auto-connect state save ./auth.json
+agent-browser --state ./auth.json open https://app.example.com
+
+# Option 2: Persistent profile
+agent-browser --profile ~/.myapp open https://app.example.com/login
+# ... login once, all future runs are authenticated
+
+# Option 3: Session name (auto-save/restore)
+agent-browser --session-name myapp open https://app.example.com/login
+# ... login, close, next run state is restored
+
+# Option 4: State file
+agent-browser state save auth.json
+agent-browser state load auth.json
+```
+
+## Iframes
+
+Iframe content is inlined in snapshots. Interact with iframe refs directly — no frame switch needed.
+
+## Parallel Sessions
+
+```bash
+agent-browser --session s1 open https://site-a.com
+agent-browser --session s2 open https://site-b.com
+agent-browser session list
+```
+
+## JavaScript Eval
+
+```bash
+agent-browser eval 'document.title'
+
+# Complex JS — use --stdin to avoid shell quoting issues
+agent-browser eval --stdin <<'EVALEOF'
+JSON.stringify(Array.from(document.querySelectorAll("a")).map(a => a.href))
+EVALEOF
+```
+
+## Cleanup
+
+Always close sessions when done:
+```bash
+agent-browser close
+agent-browser --session s1 close
+```
@@ -24,147 +24,144 @@
---
-> **PicoClaw** est un projet open-source indépendant initié par [Sipeed](https://sipeed.com). Il est entièrement écrit en **Go** — ce n'est pas un fork d'OpenClaw, de NanoBot ou de tout autre projet.
+> **PicoClaw** est un projet open-source indépendant initié par [Sipeed](https://sipeed.com), entièrement écrit en **Go** à partir de zéro — ce n'est pas un fork d'OpenClaw, de NanoBot ou de tout autre projet.
-🦐 **PicoClaw** est un assistant personnel IA ultra-léger inspiré de [NanoBot](https://github.com/HKUDS/nanobot), entièrement réécrit en **Go** via un processus d'auto-amorçage (self-bootstrapping) — où l'agent IA lui-même a piloté l'intégralité de la migration architecturale et de l'optimisation du code.
+**PicoClaw** est un assistant personnel IA ultra-léger inspiré de [NanoBot](https://github.com/HKUDS/nanobot). Il a été entièrement reconstruit en **Go** via un processus d'auto-amorçage (self-bootstrapping) — l'Agent IA lui-même a piloté la migration architecturale et l'optimisation du code.
+
+**Fonctionne sur du matériel à $10 avec <10 Mo de RAM** — c'est 99% de mémoire en moins qu'OpenClaw et 98% moins cher qu'un Mac mini !
-⚡️ **Extrêmement léger :** Fonctionne sur du matériel à seulement **$10** avec **<10 Mo** de RAM. C'est 99% de mémoire en moins qu'OpenClaw et 98% moins cher qu'un Mac mini !
- 
- 
+
+
-
-### 🐜 Déploiement Innovant à Faible Empreinte
+### 🐜 Déploiement innovant à faible empreinte
PicoClaw peut être déployé sur pratiquement n'importe quel appareil Linux !
-- 9,9$ [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) version E (Ethernet) ou W (WiFi6), pour un Assistant Domotique Minimaliste
-- 30~$50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou 100$ [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) pour la Maintenance Automatisée de Serveurs
-- 50$ [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou 100$ [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) pour la Surveillance Intelligente
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) édition E(Ethernet) ou W(WiFi6), pour un assistant domestique minimal
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), pour des opérations serveur automatisées
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), pour la surveillance intelligente
Rejoignez le Réseau Social d'Agents
+**Option 1 : Double-clic (Bureau)**
-Connectez PicoClaw au Réseau Social d'Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée.
+Après téléchargement depuis [picoclaw.io](https://picoclaw.io), double-cliquez sur `picoclaw-launcher` (ou `picoclaw-launcher.exe` sous Windows). Votre navigateur s'ouvrira automatiquement sur `http://localhost:18800`.
+
+**Option 2 : Ligne de commande**
+
+```bash
+picoclaw-launcher
+# Ouvrez http://localhost:18800 dans votre navigateur
+```
+
+> [!TIP]
+> **Accès distant / Docker / VM :** Ajoutez le flag `-public` pour écouter sur toutes les interfaces :
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+
+
+
+
+
+
-
+