/skills` (builtin)
+
+For advanced/test setups, you can override the builtin skills root with:
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
### 🔒 Security Sandbox
PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.
@@ -794,7 +926,7 @@ The subagent has access to tools (message, web_search, etc.) and can communicate
### Providers
> [!NOTE]
-> Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed.
+> 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 |
| -------------------------- | --------------------------------------- | -------------------------------------------------------------------- |
@@ -822,7 +954,7 @@ This design also enables **multi-agent support** with flexible provider selectio
#### 📋 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) |
@@ -834,6 +966,7 @@ This design also enables **multi-agent support** with flexible provider selectio
| **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/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://console.volcengine.com) |
@@ -930,10 +1063,24 @@ This design also enables **multi-agent support** with flexible provider selectio
"model_name": "my-custom-model",
"model": "openai/custom-model",
"api_base": "https://my-proxy.com/v1",
+ "api_key": "sk-...",
+ "request_timeout": 300
+}
+```
+
+**LiteLLM Proxy**
+
+```json
+{
+ "model_name": "lite-gpt4",
+ "model": "litellm/lite-gpt4",
+ "api_base": "http://localhost:4000/v1",
"api_key": "sk-..."
}
```
+PicoClaw strips only the outer `litellm/` prefix before sending the request, so proxy aliases like `litellm/lite-gpt4` send `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`.
+
#### Load Balancing
Configure multiple endpoints for the same model name—PicoClaw will automatically round-robin between them:
@@ -1078,7 +1225,11 @@ picoclaw agent -m "Hello"
"allow_from": [""]
},
"whatsapp": {
- "enabled": false
+ "enabled": false,
+ "bridge_url": "ws://localhost:3001",
+ "use_native": false,
+ "session_store_path": "",
+ "allow_from": []
},
"feishu": {
"enabled": false,
diff --git a/README.pt-br.md b/README.pt-br.md
index 0115b7f89..67ce9e0d3 100644
--- a/README.pt-br.md
+++ b/README.pt-br.md
@@ -165,39 +165,43 @@ Você tambêm pode rodar o PicoClaw usando Docker Compose sem instalar nada loca
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
-# 2. Configure suas API keys
-cp config/config.example.json config/config.json
-vim config/config.json # Configure DISCORD_BOT_TOKEN, API keys, etc.
+# 2. Primeiro uso — gera docker/data/config.json automaticamente e para
+docker compose -f docker/docker-compose.yml --profile gateway up
+# O contêiner exibe "First-run setup complete." e para.
-# 3. Build & Iniciar
-docker compose --profile gateway up -d
+# 3. Configure suas API keys
+vim docker/data/config.json # Chaves de API do provedor, tokens de bot, etc.
+
+# 4. Iniciar
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
> [!TIP]
> **Usuários Docker**: Por padrão, o Gateway ouve em `127.0.0.1`, o que não é acessível a partir do host. Se você precisar acessar os endpoints de integridade ou expor portas, defina `PICOCLAW_GATEWAY_HOST=0.0.0.0` em seu ambiente ou atualize o `config.json`.
+```bash
+# 5. Ver logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
-# 4. Ver logs
-docker compose logs -f picoclaw-gateway
-
-# 5. Parar
-docker compose --profile gateway down
+# 6. Parar
+docker compose -f docker/docker-compose.yml --profile gateway down
```
### Modo Agente (Execução única)
```bash
# Fazer uma pergunta
-docker compose run --rm picoclaw-agent -m "Quanto e 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Quanto e 2+2?"
# Modo interativo
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
```
-### Rebuild
+### Atualizar
```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
```
### 🚀 Início Rápido
@@ -222,6 +226,7 @@ picoclaw onboard
"model_name": "gpt4",
"model": "openai/gpt-5.2",
"api_key": "sk-your-openai-key",
+ "request_timeout": 300,
"api_base": "https://api.openai.com/v1"
}
],
@@ -246,6 +251,9 @@ picoclaw onboard
}
```
+> **Novo**: O formato de configuração `model_list` permite adicionar provedores sem alterar código. Veja [Configuração de Modelo](#configuração-de-modelo-model_list) para detalhes.
+> `request_timeout` é opcional e usa segundos. Se omitido ou definido como `<= 0`, o PicoClaw usa o timeout padrão (120s).
+
**3. Obter API Keys**
* **Provedor de LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
@@ -274,7 +282,7 @@ Converse com seu PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom.
| **QQ** | Fácil (AppID + AppSecret) |
| **DingTalk** | Médio (credenciais do app) |
| **LINE** | Médio (credenciais + webhook URL) |
-| **WeCom** | Médio (CorpID + configuração webhook) |
+| **WeCom AI Bot** | Médio (Token + chave AES) |
Telegram (Recomendado)
@@ -442,8 +450,6 @@ picoclaw gateway
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
- "webhook_host": "0.0.0.0",
- "webhook_port": 18791,
"webhook_path": "/webhook/line",
"allow_from": []
}
@@ -457,11 +463,13 @@ O LINE requer HTTPS para webhooks. Use um reverse proxy ou tunnel:
```bash
# Exemplo com ngrok
-ngrok http 18791
+ngrok http 18790
```
Em seguida, configure a Webhook URL no LINE Developers Console para `https://seu-dominio/webhook/line` e habilite **Use webhook**.
+> **Nota**: O webhook do LINE é servido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Use um proxy reverso/HTTPS ou túnel (como ngrok) para expor o Gateway de forma segura quando necessário.
+
**4. Executar**
```bash
@@ -470,19 +478,20 @@ picoclaw gateway
> Em chats de grupo, o bot responde apenas quando mencionado com @. As respostas citam a mensagem original.
-> **Docker Compose**: Adicione `ports: ["18791:18791"]` ao serviço `picoclaw-gateway` para expor a porta do webhook.
+> **Docker Compose**: Se você usa Docker Compose, exponha o Gateway (padrão 127.0.0.1:18790) se precisar acessar o webhook LINE externamente, por exemplo `ports: ["18790:18790"]`.
WeCom (WeChat Work)
-O PicoClaw suporta dois tipos de integração WeCom:
+O PicoClaw suporta três tipos de integração WeCom:
-**Opção 1: WeCom Bot (Robô Inteligente)** - Configuração mais fácil, suporta chats em grupo
-**Opção 2: WeCom App (Aplicativo Personalizado)** - Mais recursos, mensagens proativas
+**Opção 1: WeCom Bot (Robô)** - Configuração mais fácil, suporta chats em grupo
+**Opção 2: WeCom App (Aplicativo Personalizado)** - Mais recursos, mensagens proativas, somente chat privado
+**Opção 3: WeCom AI Bot (Robô Inteligente)** - Bot IA oficial, respostas em streaming, suporta grupo e privado
-Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para instruções detalhadas.
+Veja o [Guia de Configuração WeCom AI Bot](docs/channels/wecom/wecom_aibot/README.zh.md) para instruções detalhadas.
**Configuração Rápida - WeCom Bot:**
@@ -501,8 +510,6 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
"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_host": "0.0.0.0",
- "webhook_port": 18793,
"webhook_path": "/webhook/wecom",
"allow_from": []
}
@@ -510,6 +517,8 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
}
```
+> **Nota**: O webhook do WeCom Bot é atendido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Use um proxy reverso/HTTPS ou túnel para expor o Gateway em produção.
+
**Configuração Rápida - WeCom App:**
**1. Criar um aplicativo**
@@ -521,7 +530,7 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
**2. Configurar recebimento de mensagens**
* Nos detalhes do aplicativo, clique em "Receber Mensagens" → "Configurar API"
-* Defina a URL como `http://your-server:18792/webhook/wecom-app`
+* Defina a URL como `http://your-server:18790/webhook/wecom-app`
* Gere o **Token** e o **EncodingAESKey**
**3. Configurar**
@@ -536,8 +545,6 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
"agent_id": 1000002,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
- "webhook_host": "0.0.0.0",
- "webhook_port": 18792,
"webhook_path": "/webhook/wecom-app",
"allow_from": []
}
@@ -551,7 +558,40 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
picoclaw gateway
```
-> **Nota**: O WeCom App requer a abertura da porta 18792 para callbacks de webhook. Use um proxy reverso para HTTPS em produção.
+> **Nota**: O WeCom App (callbacks de webhook) é servido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Em produção use um proxy reverso HTTPS para expor a porta do Gateway, ou atualize `PICOCLAW_GATEWAY_HOST` para `0.0.0.0` se necessário.
+
+**Configuração Rápida - WeCom AI Bot:**
+
+**1. Criar um AI Bot**
+
+* Acesse o Console de Administração WeCom → Gerenciamento de Aplicativos → AI Bot
+* Configure a URL de callback: `http://your-server:18791/webhook/wecom-aibot`
+* Copie o **Token** e gere o **EncodingAESKey**
+
+**2. Configurar**
+
+```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": "Olá! Como posso ajudá-lo?"
+ }
+ }
+}
+```
+
+**3. Executar**
+
+```bash
+picoclaw gateway
+```
+
+> **Nota**: O WeCom AI Bot usa protocolo de pull em streaming — sem preocupações com timeout de resposta. Tarefas longas (>5,5 min) alternam automaticamente para entrega via `response_url`.
@@ -565,6 +605,31 @@ Conecte o PicoClaw a Rede Social de Agentes simplesmente enviando uma única men
Arquivo de configuração: `~/.picoclaw/config.json`
+### Variáveis de Ambiente
+
+Você pode substituir os caminhos padrão usando variáveis de ambiente. Isso é útil para instalações portáteis, implantações em contêineres ou para executar o picoclaw como um serviço do sistema. Essas variáveis são independentes e controlam caminhos diferentes.
+
+| Variável | Descrição | Caminho Padrão |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Substitui o caminho para o arquivo de configuração. Isso informa diretamente ao picoclaw qual `config.json` carregar, ignorando todos os outros locais. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME` | Substitui o diretório raiz dos dados do picoclaw. Isso altera o local padrão do `workspace` e de outros diretórios de dados. | `~/.picoclaw` |
+
+**Exemplos:**
+
+```bash
+# Executar o picoclaw usando um arquivo de configuração específico
+# O caminho do workspace será lido de dentro desse arquivo de configuração
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Executar o picoclaw com todos os seus dados armazenados em /opt/picoclaw
+# A configuração será carregada do ~/.picoclaw/config.json padrão
+# O workspace será criado em /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Use ambos para uma configuração totalmente personalizada
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
### Estrutura do Workspace
O PicoClaw armazena dados no workspace configurado (padrão: `~/.picoclaw/workspace`):
@@ -758,7 +823,7 @@ O subagente tem acesso às ferramentas (message, web_search, etc.) e pode se com
### Provedores
> [!NOTE]
-> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de voz do Telegram serão automaticamente transcritas.
+> 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.
| Provedor | Finalidade | Obter API Key |
| --- | --- | --- |
@@ -973,6 +1038,17 @@ Este design também possibilita o **suporte multi-agent** com seleção flexíve
```
> Execute `picoclaw auth login --provider anthropic` para configurar credenciais OAuth.
+**Proxy/API personalizada**
+```json
+{
+ "model_name": "my-custom-model",
+ "model": "openai/custom-model",
+ "api_base": "https://my-proxy.com/v1",
+ "api_key": "sk-...",
+ "request_timeout": 300
+}
+```
+
#### Balanceamento de Carga
Configure vários endpoints para o mesmo nome de modelo—PicoClaw fará round-robin automaticamente entre eles:
diff --git a/README.vi.md b/README.vi.md
index 015bc264e..5755896ed 100644
--- a/README.vi.md
+++ b/README.vi.md
@@ -3,7 +3,7 @@
PicoClaw: Trợ lý AI Siêu Nhẹ viết bằng Go
-Phần cứng $10 · RAM 10MB · Khởi động 1 giây · 皮皮虾，我们走！
+Phần cứng $10 · RAM 10MB · Khởi động 1 giây · Nào, xuất phát!
@@ -145,39 +145,43 @@ Bạn cũng có thể chạy PicoClaw bằng Docker Compose mà không cần cà
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
-# 2. Thiết lập API Key
-cp config/config.example.json config/config.json
-vim config/config.json # Thiết lập DISCORD_BOT_TOKEN, API keys, v.v.
+# 2. Lần chạy đầu tiên — tự tạo docker/data/config.json rồi dừng lại
+docker compose -f docker/docker-compose.yml --profile gateway up
+# Container hiển thị "First-run setup complete." rồi tự dừng.
-# 3. Build & Khởi động
-docker compose --profile gateway up -d
+# 3. Thiết lập API Key
+vim docker/data/config.json # API key của provider, bot token, v.v.
+
+# 4. Khởi động
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
> [!TIP]
> **Người dùng Docker**: Theo mặc định, Gateway lắng nghe trên `127.0.0.1`, không thể truy cập từ máy chủ. Nếu bạn cần truy cập các endpoint kiểm tra sức khỏe hoặc mở cổng, hãy đặt `PICOCLAW_GATEWAY_HOST=0.0.0.0` trong môi trường của bạn hoặc cập nhật `config.json`.
+```bash
+# 5. Xem logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
-# 4. Xem logs
-docker compose logs -f picoclaw-gateway
-
-# 5. Dừng
-docker compose --profile gateway down
+# 6. Dừng
+docker compose -f docker/docker-compose.yml --profile gateway down
```
### Chế độ Agent (chạy một lần)
```bash
# Đặt câu hỏi
-docker compose run --rm picoclaw-agent -m "2+2 bằng mấy?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 bằng mấy?"
# Chế độ tương tác
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
```
-### Build lại
+### Cập nhật
```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
```
### 🚀 Bắt đầu nhanh
@@ -202,6 +206,7 @@ picoclaw onboard
"model_name": "gpt4",
"model": "openai/gpt-5.2",
"api_key": "sk-your-openai-key",
+ "request_timeout": 300,
"api_base": "https://api.openai.com/v1"
}
],
@@ -220,6 +225,9 @@ picoclaw onboard
}
```
+> **Mới**: Định dạng cấu hình `model_list` cho phép thêm nhà cung cấp mà không cần thay đổi mã nguồn. Xem [Cấu hình Mô hình](#cấu-hình-mô-hình-model_list) để biết chi tiết.
+> `request_timeout` là tùy chọn và dùng đơn vị giây. Nếu bỏ qua hoặc đặt `<= 0`, PicoClaw sẽ dùng timeout mặc định (120s).
+
**3. Lấy API Key**
* **Nhà cung cấp LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
@@ -248,7 +256,7 @@ Trò chuyện với PicoClaw qua Telegram, Discord, DingTalk, LINE hoặc WeCom.
| **QQ** | Dễ (AppID + AppSecret) |
| **DingTalk** | Trung bình (app credentials) |
| **LINE** | Trung bình (credentials + webhook URL) |
-| **WeCom** | Trung bình (CorpID + cấu hình webhook) |
+| **WeCom AI Bot** | Trung bình (Token + khóa AES) |
Telegram (Khuyên dùng)
@@ -416,8 +424,6 @@ picoclaw gateway
"enabled": true,
"channel_secret": "YOUR_CHANNEL_SECRET",
"channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
- "webhook_host": "0.0.0.0",
- "webhook_port": 18791,
"webhook_path": "/webhook/line",
"allow_from": []
}
@@ -431,7 +437,7 @@ LINE yêu cầu HTTPS cho webhook. Sử dụng reverse proxy hoặc tunnel:
```bash
# Ví dụ với ngrok
-ngrok http 18791
+ngrok http 18790
```
Sau đó cài đặt Webhook URL trong LINE Developers Console thành `https://your-domain/webhook/line` và bật **Use webhook**.
@@ -444,19 +450,20 @@ picoclaw gateway
> Trong nhóm chat, bot chỉ phản hồi khi được @mention. Các câu trả lời sẽ trích dẫn tin nhắn gốc.
-> **Docker Compose**: Thêm `ports: ["18791:18791"]` vào service `picoclaw-gateway` để mở port webhook.
+> **Docker Compose**: Nếu bạn cần mở port webhook cục bộ, hãy thêm một rule chuyển tiếp từ port Gateway (mặc định 18790) tới host. Lưu ý: LINE webhook được phục vụ bởi Gateway HTTP chung (mặc định 127.0.0.1:18790).
WeCom (WeChat Work)
-PicoClaw hỗ trợ hai loại tích hợp WeCom:
+PicoClaw hỗ trợ ba loại tích hợp WeCom:
-**Tùy chọn 1: WeCom Bot (Robot Thông minh)** - Thiết lập dễ dàng hơn, hỗ trợ chat nhóm
-**Tùy chọn 2: WeCom App (Ứng dụng Tự xây dựng)** - Nhiều tính năng hơn, nhắn tin chủ động
+**Tùy chọn 1: WeCom Bot (Robot)** - Thiết lập dễ dàng hơn, hỗ trợ chat nhóm
+**Tùy chọn 2: WeCom App (Ứng dụng Tùy chỉnh)** - Nhiều tính năng hơn, nhắn tin chủ động, chỉ chat riêng tư
+**Tùy chọn 3: WeCom AI Bot (Bot Thông Minh)** - Bot AI chính thức, phản hồi streaming, hỗ trợ nhóm và riêng tư
-Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) để biết hướng dẫn chi tiết.
+Xem [Hướng dẫn Cấu hình WeCom AI Bot](docs/channels/wecom/wecom_aibot/README.zh.md) để biết hướng dẫn chi tiết.
**Thiết lập Nhanh - WeCom Bot:**
@@ -475,8 +482,6 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
"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_host": "0.0.0.0",
- "webhook_port": 18793,
"webhook_path": "/webhook/wecom",
"allow_from": []
}
@@ -484,6 +489,8 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
}
```
+> **Lưu ý:** Các endpoint webhook của WeCom Bot được phục vụ bởi máy chủ Gateway HTTP dùng chung (mặc định 127.0.0.1:18790). Nếu bạn cần truy cập từ bên ngoài, hãy cấu hình reverse proxy hoặc mở cổng Gateway tương ứng.
+
**Thiết lập Nhanh - WeCom App:**
**1. Tạo ứng dụng**
@@ -495,7 +502,7 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
**2. Cấu hình nhận tin nhắn**
* Trong chi tiết ứng dụng, nhấp vào "Nhận Tin nhắn" → "Thiết lập API"
-* Đặt URL thành `http://your-server:18792/webhook/wecom-app`
+* Đặt URL thành `http://your-server:18790/webhook/wecom-app`
* Tạo **Token** và **EncodingAESKey**
**3. Cấu hình**
@@ -510,8 +517,6 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
"agent_id": 1000002,
"token": "YOUR_TOKEN",
"encoding_aes_key": "YOUR_ENCODING_AES_KEY",
- "webhook_host": "0.0.0.0",
- "webhook_port": 18792,
"webhook_path": "/webhook/wecom-app",
"allow_from": []
}
@@ -525,7 +530,40 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
picoclaw gateway
```
-> **Lưu ý**: WeCom App yêu cầu mở cổng 18792 cho callback webhook. Sử dụng proxy ngược cho HTTPS trong môi trường sản xuất.
+> **Lưu ý**: WeCom App callback webhook được phục vụ bởi Gateway HTTP chung (mặc định 127.0.0.1:18790). Sử dụng proxy ngược để cung cấp HTTPS trong môi trường production nếu cần.
+
+**Thiết lập Nhanh - WeCom AI Bot:**
+
+**1. Tạo AI Bot**
+
+* Truy cập Bảng điều khiển Quản trị WeCom → Quản lý Ứng dụng → AI Bot
+* Cấu hình URL callback: `http://your-server:18791/webhook/wecom-aibot`
+* Sao chép **Token** và tạo **EncodingAESKey**
+
+**2. 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": "Xin chào! Tôi có thể giúp gì cho bạn?"
+ }
+ }
+}
+```
+
+**3. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+> **Lưu ý**: WeCom AI Bot sử dụng giao thức pull streaming — không lo timeout phản hồi. Tác vụ dài (>5,5 phút) tự động chuyển sang gửi qua `response_url`.
@@ -539,6 +577,31 @@ Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một
File cấu hình: `~/.picoclaw/config.json`
+### Biến môi trường
+
+Bạn có thể ghi đè các đường dẫn mặc định bằng cách sử dụng các biến môi trường. Điều này hữu ích cho việc cài đặt di động, triển khai container hóa hoặc chạy picoclaw như một dịch vụ hệ thống. Các biến này độc lập và kiểm soát các đường dẫn khác nhau.
+
+| Biến | Mô tả | Đường dẫn mặc định |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Ghi đè đường dẫn đến file cấu hình. Điều này trực tiếp yêu cầu picoclaw tải file `config.json` nào, bỏ qua tất cả các vị trí khác. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME` | Ghi đè thư mục gốc cho dữ liệu picoclaw. Điều này thay đổi vị trí mặc định của `workspace` và các thư mục dữ liệu khác. | `~/.picoclaw` |
+
+**Ví dụ:**
+
+```bash
+# Chạy picoclaw bằng một file cấu hình cụ thể
+# Đường dẫn workspace sẽ được đọc từ trong file cấu hình đó
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Chạy picoclaw với tất cả dữ liệu được lưu trữ trong /opt/picoclaw
+# Cấu hình sẽ được tải từ ~/.picoclaw/config.json mặc định
+# Workspace sẽ được tạo tại /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Sử dụng cả hai để có thiết lập tùy chỉnh hoàn toàn
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
### Cấu trúc Workspace
PicoClaw lưu trữ dữ liệu trong workspace đã cấu hình (mặc định: `~/.picoclaw/workspace`):
@@ -732,7 +795,7 @@ Subagent có quyền truy cập các công cụ (message, web_search, v.v.) và
### Nhà cung cấp (Providers)
> [!NOTE]
-> Groq cung cấp dịch vụ chuyển giọng nói thành văn bản miễn phí qua Whisper. Nếu đã cấu hình Groq, tin nhắn thoại trên Telegram sẽ được tự động chuyển thành văn bản.
+> Groq cung cấp dịch vụ chuyển giọng nói thành văn bản miễn phí qua Whisper. Nếu đã cấu hình Groq, tin nhắn âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển thành văn bản ở cấp độ agent.
| Nhà cung cấp | Mục đích | Lấy API Key |
| --- | --- | --- |
@@ -944,6 +1007,17 @@ Thiết kế này cũng cho phép **hỗ trợ đa tác nhân** với lựa ch
```
> Chạy `picoclaw auth login --provider anthropic` để thiết lập thông tin xác thực OAuth.
+**Proxy/API tùy chỉnh**
+```json
+{
+ "model_name": "my-custom-model",
+ "model": "openai/custom-model",
+ "api_base": "https://my-proxy.com/v1",
+ "api_key": "sk-...",
+ "request_timeout": 300
+}
+```
+
#### Cân bằng Tải tải
Định cấu hình nhiều endpoint cho cùng một tên mô hình—PicoClaw sẽ tự động phân phối round-robin giữa chúng:
diff --git a/README.zh.md b/README.zh.md
index 4f4bde46a..bd90173f9 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -166,41 +166,43 @@ make install
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
-# 2. 设置 API Key
-cp config/config.example.json config/config.json
-vim config/config.json # 设置 DISCORD_BOT_TOKEN, API keys 等
+# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
+docker compose -f docker/docker-compose.yml --profile gateway up
+# 容器打印 "First-run setup complete." 后自动停止
-# 3. 构建并启动
-docker compose --profile gateway up -d
+# 3. 填写 API Key 等配置
+vim docker/data/config.json # 设置 provider API key、Bot Token 等
+
+# 4. 正式启动
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
> [!TIP]
-**Docker 用户**: 默认情况下, Gateway监听 `127.0.0.1`，这使得这个端口未暴露到容器外。如果你需要通过端口映射访问健康检查接口, 请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
+> **Docker 用户**: 默认情况下, Gateway 监听 `127.0.0.1`，该端口不会暴露到容器外。如果需要通过端口映射访问健康检查接口，请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
-# 4. 查看日志
-docker compose logs -f picoclaw-gateway
-
-# 5. 停止
-docker compose --profile gateway down
+```bash
+# 5. 查看日志
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+# 6. 停止
+docker compose -f docker/docker-compose.yml --profile gateway down
```
### Agent 模式 (一次性运行)
```bash
# 提问
-docker compose run --rm picoclaw-agent -m "2+2 等于几？"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
# 交互模式
-docker compose run --rm picoclaw-agent
-
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
```
-### 重新构建
+### 更新镜像
```bash
-docker compose --profile gateway build --no-cache
-docker compose --profile gateway up -d
-
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
```
### 🚀 快速开始
@@ -234,7 +236,8 @@ picoclaw onboard
{
"model_name": "gpt4",
"model": "openai/gpt-5.2",
- "api_key": "your-api-key"
+ "api_key": "your-api-key",
+ "request_timeout": 300
},
{
"model_name": "claude-sonnet-4.6",
@@ -263,6 +266,7 @@ picoclaw onboard
```
> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](#模型配置-model_list)章节。
+> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。
**3. 获取 API Key**
@@ -286,6 +290,8 @@ picoclaw agent -m "2+2 等于几？"
PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。
+> **注意**: 所有 Webhook 类渠道（LINE、WeCom 等）均挂载在同一个 Gateway HTTP 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。注意：飞书（Feishu）使用 WebSocket/SDK 模式，不通过该共享 HTTP webhook 服务器接收消息。
+
### 核心渠道
| 渠道 | 设置难度 | 特性说明 | 文档链接 |
@@ -295,7 +301,7 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
| **Slack** | ⭐ 简单 | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](docs/channels/slack/README.zh.md) |
| **QQ** | ⭐⭐ 中等 | 官方机器人 API，适合国内社群 | [查看文档](docs/channels/qq/README.zh.md) |
| **钉钉 (DingTalk)** | ⭐⭐ 中等 | Stream 模式无需公网，企业办公首选 | [查看文档](docs/channels/dingtalk/README.zh.md) |
-| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)和自建应用(API) | [Bot 文档](docs/channels/wecom/wecom_bot/README.zh.md) / [App 文档](docs/channels/wecom/wecom_app/README.zh.md) |
+| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)、自建应用(API)和智能机器人(AI Bot) | [Bot 文档](docs/channels/wecom/wecom_bot/README.zh.md) / [App 文档](docs/channels/wecom/wecom_app/README.zh.md) / [AI Bot 文档](docs/channels/wecom/wecom_aibot/README.zh.md) |
| **飞书 (Feishu)** | ⭐⭐⭐ 较难 | 企业级协作，功能丰富 | [查看文档](docs/channels/feishu/README.zh.md) |
| **Line** | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook | [查看文档](docs/channels/line/README.zh.md) |
| **OneBot** | ⭐⭐ 中等 | 兼容 NapCat/Go-CQHTTP，社区生态丰富 | [查看文档](docs/channels/onebot/README.zh.md) |
@@ -311,6 +317,31 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
配置文件路径: `~/.picoclaw/config.json`
+### 环境变量
+
+你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。
+
+| 变量 | 描述 | 默认路径 |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | 覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 `config.json`，忽略所有其他位置。 | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME` | 覆盖 picoclaw 数据根目录。这会更改 `workspace` 和其他数据目录的默认位置。 | `~/.picoclaw` |
+
+**示例：**
+
+```bash
+# 使用特定的配置文件运行 picoclaw
+# 工作区路径将从该配置文件中读取
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# 在 /opt/picoclaw 中存储所有数据运行 picoclaw
+# 配置将从默认的 ~/.picoclaw/config.json 加载
+# 工作区将在 /opt/picoclaw/workspace 创建
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# 同时使用两者进行完全自定义设置
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
### 工作区布局 (Workspace Layout)
PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：
@@ -331,6 +362,20 @@ PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/work
```
+### 技能来源 (Skill Sources)
+
+默认情况下，技能会按以下顺序加载：
+
+1. `~/.picoclaw/workspace/skills`（工作区）
+2. `~/.picoclaw/skills`（全局）
+3. `/skills`（内置）
+
+在高级/测试场景下，可通过以下环境变量覆盖内置技能目录：
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
### 心跳 / 周期性任务 (Heartbeat)
PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件：
@@ -414,7 +459,7 @@ Agent 读取 HEARTBEAT.md
### 提供商 (Providers)
> [!NOTE]
-> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，Telegram 语音消息将被自动转录为文字。
+> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，任意渠道的音频消息都将在 Agent 层面自动转录为文字。
| 提供商 | 用途 | 获取 API Key |
| -------------------- | ---------------------------- | -------------------------------------------------------------------- |
@@ -550,7 +595,8 @@ Agent 读取 HEARTBEAT.md
"model_name": "my-custom-model",
"model": "openai/custom-model",
"api_base": "https://my-proxy.com/v1",
- "api_key": "sk-..."
+ "api_key": "sk-...",
+ "request_timeout": 300
}
```
diff --git a/assets/picoclaw_detect_person.mp4 b/assets/picoclaw_detect_person.mp4
deleted file mode 100644
index b56999689..000000000
Binary files a/assets/picoclaw_detect_person.mp4 and /dev/null differ
diff --git a/assets/wechat.png b/assets/wechat.png
index 776c07885..32998c122 100644
Binary files a/assets/wechat.png and b/assets/wechat.png differ
diff --git a/cmd/picoclaw-launcher-tui/internal/config/store.go b/cmd/picoclaw-launcher-tui/internal/config/store.go
new file mode 100644
index 000000000..0236de19f
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/config/store.go
@@ -0,0 +1,49 @@
+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
new file mode 100644
index 000000000..4947d6aea
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/app.go
@@ -0,0 +1,506 @@
+package ui
+
+import (
+ "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)
+
+ 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("Config Menu", nil)
+ refreshMainMenu(menu, s)
+ menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ switch event.Key() {
+ case tcell.KeyEsc:
+ s.requestExit()
+ return nil
+ }
+ if event.Rune() == 'q' {
+ 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 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()
+ 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(selectedModel),
+ Action: func() {
+ s.push("model", s.modelMenu())
+ },
+ MainColor: func() *tcell.Color {
+ if modelReady {
+ return nil
+ }
+ color := tcell.ColorGray
+ return &color
+ }(),
+ },
+ {
+ Label: rootChannelLabel(channelReady),
+ Description: rootChannelDescription(channelReady),
+ 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 (no model selected)"
+ }
+ return "Model (" + selected + ")"
+}
+
+func rootModelDescription(selected string) string {
+ if selected == "" {
+ return "no model selected"
+ }
+ return "selected"
+}
+
+func rootChannelLabel(valid bool) string {
+ if !valid {
+ return "Channel (no channel enabled)"
+ }
+ return "Channel"
+}
+
+func rootChannelDescription(valid bool) string {
+ if !valid {
+ return "no channel enabled"
+ }
+ return "enabled"
+}
+
+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.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
new file mode 100644
index 000000000..49a6ccc5d
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/channel.go
@@ -0,0 +1,410 @@
+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{
+ {Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
+ 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(
+ "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
+ }
+ if event.Rune() == 'q' {
+ 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) 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
new file mode 100644
index 000000000..bc874f7f2
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/gateway_posix.go
@@ -0,0 +1,16 @@
+//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
new file mode 100644
index 000000000..7067a5c13
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/gateway_windows.go
@@ -0,0 +1,16 @@
+//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
new file mode 100644
index 000000000..9f2132c5a
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/menu.go
@@ -0,0 +1,72 @@
+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
new file mode 100644
index 000000000..ba91f5b09
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/model.go
@@ -0,0 +1,343 @@
+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, 2+len(s.config.ModelList))
+ items = append(items,
+ MenuItem{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
+ MenuItem{
+ Label: "Add model",
+ Description: "Append a new model entry",
+ Action: func() {
+ s.addModel(
+ picoclawconfig.ModelConfig{ModelName: "new-model", Model: "openai/gpt-5.2"},
+ )
+ s.push(
+ fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
+ s.modelForm(len(s.config.ModelList)-1),
+ )
+ },
+ },
+ )
+ 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))
+ },
+ })
+ }
+
+ menu := NewMenu("Models", items)
+ menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+ if event.Key() == tcell.KeyEsc {
+ s.pop()
+ return nil
+ }
+ if event.Rune() == 'q' {
+ s.pop()
+ return nil
+ }
+ if event.Rune() == ' ' {
+ row, _ := menu.GetSelection()
+ if row > 0 && row <= len(s.config.ModelList) {
+ model := s.config.ModelList[row-1]
+ 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))
+ form.SetButtonBackgroundColor(tcell.NewRGBColor(80, 250, 123))
+ form.SetButtonTextColor(tcell.NewRGBColor(12, 13, 22))
+
+ addInput(form, "Model Name", model.ModelName, func(value string) {
+ model.ModelName = value
+ s.dirty = true
+ 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() {
+ s.deleteModel(index)
+ })
+ 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 + 1
+ 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, 2+len(s.config.ModelList))
+ items = append(items,
+ MenuItem{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
+ MenuItem{
+ Label: "Add model",
+ Description: "Append a new model entry",
+ Action: func() {
+ s.addModel(
+ picoclawconfig.ModelConfig{ModelName: "new-model", Model: "openai/gpt-5.2"},
+ )
+ s.push(
+ fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
+ s.modelForm(len(s.config.ModelList)-1),
+ )
+ },
+ },
+ )
+ 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))
+ },
+ })
+ }
+ 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) 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, _ := io.ReadAll(io.LimitReader(resp.Body, 2048))
+ 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
new file mode 100644
index 000000000..68cdd60b9
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/internal/ui/style.go
@@ -0,0 +1,43 @@
+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
+}
diff --git a/cmd/picoclaw-launcher-tui/main.go b/cmd/picoclaw-launcher-tui/main.go
new file mode 100644
index 000000000..0e8cce415
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/main.go
@@ -0,0 +1,15 @@
+package main
+
+import (
+ "fmt"
+ "os"
+
+ "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/internal/ui"
+)
+
+func main() {
+ if err := ui.Run(); err != nil {
+ fmt.Fprintln(os.Stderr, err)
+ os.Exit(1)
+ }
+}
diff --git a/cmd/picoclaw-launcher/README.md b/cmd/picoclaw-launcher/README.md
new file mode 100644
index 000000000..641279bb1
--- /dev/null
+++ b/cmd/picoclaw-launcher/README.md
@@ -0,0 +1,290 @@
+# PicoClaw Launcher
+
+> [!WARNING]
+> This project is a temporary solution and will be refactored in the future to provide a complete web service. Therefore, the APIs in this directory are not stable.
+
+A standalone launcher for PicoClaw, providing visual JSON editing and OAuth provider authentication management.
+
+## Features
+
+- 📝 **Config Editor** — Sidebar-based settings UI with model management, channel configuration forms, and a raw JSON editor
+- 🤖 **Model Management** — Model card grid with availability status (grayed out without API key), primary model selection, add/edit/delete with required/optional field separation
+- 📡 **Channel Configuration** — Form-based settings for 12 channel types (Telegram, Discord, Slack, WeCom, DingTalk, Feishu, LINE, WhatsApp, QQ, OneBot, MaixCAM, etc.) with documentation links
+- 🔐 **Provider Auth** — Login to OpenAI (Device Code), Anthropic (API Token), Google Antigravity (Browser OAuth)
+- 🌐 **Embedded Frontend** — Compiles to a single binary with no external dependencies
+- 🌍 **i18n** — Chinese/English language switching with browser auto-detection
+- 🎨 **Theme** — Light / Dark / System theme toggle with localStorage persistence
+
+## Quick Start
+
+```bash
+# Build
+go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
+
+# Run with default config path (~/.picoclaw/config.json)
+./picoclaw-launcher
+
+# Specify a config file
+./picoclaw-launcher ./config.json
+
+# Allow LAN access
+./picoclaw-launcher -public
+```
+
+Open `http://localhost:18800` in your browser.
+
+## CLI Options
+
+```
+Usage: picoclaw-config [options] [config.json]
+
+Arguments:
+ config.json Path to the configuration file (default: ~/.picoclaw/config.json)
+
+Options:
+ -public Listen on all interfaces (0.0.0.0), allowing access from other devices
+```
+
+## API Reference
+
+Base URL: `http://localhost:18800`
+
+---
+
+### Static Files
+
+#### GET /
+
+Serves the embedded frontend (`index.html`).
+
+---
+
+### Config API
+
+#### GET /api/config
+
+Reads the current configuration file.
+
+**Response** `200 OK`
+
+```json
+{
+ "config": { ... },
+ "path": "/Users/xiao/.picoclaw/config.json"
+}
+```
+
+---
+
+#### PUT /api/config
+
+Saves the configuration. The request body must be a complete Config JSON object.
+
+**Request Body** — `application/json`
+
+```json
+{
+ "agents": { "defaults": { "model_name": "gpt-5.2" } },
+ "model_list": [
+ {
+ "model_name": "gpt-5.2",
+ "model": "openai/gpt-5.2",
+ "auth_method": "oauth"
+ }
+ ]
+}
+```
+
+**Response** `200 OK`
+
+```json
+{ "status": "ok" }
+```
+
+**Error** `400 Bad Request` — Invalid JSON
+
+---
+
+### Auth API
+
+#### GET /api/auth/status
+
+Returns the authentication status of all providers and any in-progress device code login.
+
+**Response** `200 OK`
+
+```json
+{
+ "providers": [
+ {
+ "provider": "openai",
+ "auth_method": "oauth",
+ "status": "active",
+ "account_id": "user-xxx",
+ "expires_at": "2026-03-01T00:00:00Z"
+ }
+ ],
+ "pending_device": {
+ "provider": "openai",
+ "status": "pending",
+ "device_url": "https://auth.openai.com/activate",
+ "user_code": "ABCD-1234"
+ }
+}
+```
+
+`status` values: `active` | `expired` | `needs_refresh`
+
+`pending_device` is only present when a device code login is in progress.
+
+---
+
+#### POST /api/auth/login
+
+Initiates a provider login.
+
+**Request Body** — `application/json`
+
+```json
+{ "provider": "openai" }
+```
+
+Supported `provider` values: `openai` | `anthropic` | `google-antigravity`
+
+##### OpenAI (Device Code Flow)
+
+Returns device code info. The server polls for completion in the background.
+
+```json
+{
+ "status": "pending",
+ "device_url": "https://auth.openai.com/activate",
+ "user_code": "ABCD-1234",
+ "message": "Open the URL and enter the code to authenticate."
+}
+```
+
+The user opens `device_url` in a browser and enters `user_code`. Once authenticated, `GET /api/auth/status` will show `pending_device.status` as `success`.
+
+##### Anthropic (API Token)
+
+Requires a `token` field in the request:
+
+```json
+{ "provider": "anthropic", "token": "sk-ant-xxx" }
+```
+
+**Response:**
+
+```json
+{ "status": "success", "message": "Anthropic token saved" }
+```
+
+##### Google Antigravity (Browser OAuth)
+
+Returns an authorization URL for the frontend to open in a new tab:
+
+```json
+{
+ "status": "redirect",
+ "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
+ "message": "Open the URL to authenticate with Google."
+}
+```
+
+After authentication, Google redirects to `GET /auth/callback`, which saves the credentials and redirects back to the picoclaw-config UI.
+
+---
+
+#### POST /api/auth/logout
+
+Logs out from a provider.
+
+**Request Body** — `application/json`
+
+```json
+{ "provider": "openai" }
+```
+
+Omit or leave `provider` empty to log out from all providers.
+
+**Response** `200 OK`
+
+```json
+{ "status": "ok" }
+```
+
+---
+
+#### GET /auth/callback
+
+OAuth browser callback endpoint (used by Google Antigravity). Called by the OAuth provider's redirect — **not invoked directly by the frontend**.
+
+**Query Parameters:**
+- `state` — OAuth state for CSRF validation
+- `code` — Authorization code
+
+On success, redirects to `/#auth`.
+
+
+### Process API
+
+#### GET /api/process/status
+
+Gets the running status of the `picoclaw gateway` process.
+
+**Response** `200 OK` (Running)
+
+```json
+{
+ "process_status": "running",
+ "status": "ok",
+ "uptime": "1.010814s"
+}
+```
+
+**Response** `200 OK` (Stopped)
+
+```json
+{
+ "process_status": "stopped",
+ "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
+}
+```
+
+---
+
+#### POST /api/process/start
+
+Starts the `picoclaw gateway` process in the background.
+
+**Response** `200 OK`
+
+```json
+{
+ "status": "ok",
+ "pid": 12345
+}
+```
+
+---
+
+#### POST /api/process/stop
+
+Stops the running `picoclaw gateway` process.
+
+**Response** `200 OK`
+
+```json
+{
+ "status": "ok"
+}
+```
+
+---
+
+## Testing
+
+```bash
+go test -v ./cmd/picoclaw-launcher/
+```
diff --git a/cmd/picoclaw-launcher/README.zh.md b/cmd/picoclaw-launcher/README.zh.md
new file mode 100644
index 000000000..320de75a5
--- /dev/null
+++ b/cmd/picoclaw-launcher/README.zh.md
@@ -0,0 +1,287 @@
+# PicoClaw Launcher
+
+> [!WARNING]
+> 该项目属于临时解决方案，后续会重构并提供完整的 Web 服务，因此该目录下的接口并不稳定。
+
+PicoClaw 的独立启动器，提供可视化 JSON 配置编辑和 OAuth Provider 认证管理。
+
+## 功能
+
+- 📝 **配置编辑** — 侧边栏式设置 UI，支持模型管理、通道配置表单和原始 JSON 编辑器
+- 🤖 **模型管理** — 模型卡片网格，可用性状态显示（无 API Key 时灰色），主模型选择，增删改查，必填/选填字段分离
+- 📡 **通道配置** — 12 种通道类型（Telegram、Discord、Slack、企业微信、钉钉、飞书、LINE、WhatsApp、QQ、OneBot、MaixCAM 等）的表单化配置，附带文档链接
+- 🔐 **Provider 认证** — 支持 OpenAI (Device Code)、Anthropic (API Token)、Google Antigravity (Browser OAuth) 登录
+- 🌐 **嵌入式前端** — 编译为单一二进制文件，无需额外依赖
+- 🌍 **国际化** — 中英文切换，首次访问自动检测浏览器语言
+- 🎨 **主题** — 亮色 / 暗色 / 跟随系统，偏好保存在 localStorage
+
+## 快速开始
+
+```bash
+# 编译
+go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
+
+# 运行（使用默认配置路径 ~/.picoclaw/config.json）
+./picoclaw-launcher
+
+# 指定配置文件
+./picoclaw-launcher ./config.json
+
+# 允许局域网访问
+./picoclaw-launcher -public
+```
+
+启动后在浏览器中打开 `http://localhost:18800`。
+
+## 命令行参数
+
+```
+Usage: picoclaw-launcher [options] [config.json]
+
+Arguments:
+ config.json 配置文件路径（默认: ~/.picoclaw/config.json）
+
+Options:
+ -public 监听所有网络接口（0.0.0.0），允许局域网设备访问
+```
+
+## API 文档
+
+Base URL: `http://localhost:18800`
+
+### 静态文件
+
+#### GET /
+
+提供嵌入式前端页面（`index.html`）。
+
+---
+
+### Config API
+
+#### GET /api/config
+
+读取当前配置文件内容。
+
+**Response** `200 OK`
+
+```json
+{
+ "config": { ... },
+ "path": "/Users/xiao/.picoclaw/config.json"
+}
+```
+
+---
+
+#### PUT /api/config
+
+保存配置。请求体为完整的 Config JSON。
+
+**Request Body** — `application/json`
+
+```json
+{
+ "agents": { "defaults": { "model_name": "gpt-5.2" } },
+ "model_list": [
+ {
+ "model_name": "gpt-5.2",
+ "model": "openai/gpt-5.2",
+ "auth_method": "oauth"
+ }
+ ]
+}
+```
+
+**Response** `200 OK`
+
+```json
+{ "status": "ok" }
+```
+
+**Error** `400 Bad Request` — 无效 JSON
+
+---
+
+### Auth API
+
+#### GET /api/auth/status
+
+获取所有 Provider 的认证状态和进行中的 Device Code 登录信息。
+
+**Response** `200 OK`
+
+```json
+{
+ "providers": [
+ {
+ "provider": "openai",
+ "auth_method": "oauth",
+ "status": "active",
+ "account_id": "user-xxx",
+ "expires_at": "2026-03-01T00:00:00Z"
+ }
+ ],
+ "pending_device": {
+ "provider": "openai",
+ "status": "pending",
+ "device_url": "https://auth.openai.com/activate",
+ "user_code": "ABCD-1234"
+ }
+}
+```
+
+`status` 可选值: `active` | `expired` | `needs_refresh`
+
+`pending_device` 仅在有进行中的 Device Code 登录时返回。
+
+---
+
+#### POST /api/auth/login
+
+发起 Provider 登录。
+
+**Request Body** — `application/json`
+
+```json
+{ "provider": "openai" }
+```
+
+支持的 `provider` 值: `openai` | `anthropic` | `google-antigravity`
+
+##### OpenAI (Device Code Flow)
+
+返回 Device Code 信息，后台自动轮询认证结果：
+
+```json
+{
+ "status": "pending",
+ "device_url": "https://auth.openai.com/activate",
+ "user_code": "ABCD-1234",
+ "message": "Open the URL and enter the code to authenticate."
+}
+```
+
+用户在浏览器中打开 `device_url` 并输入 `user_code`。认证完成后通过 `GET /api/auth/status` 的 `pending_device.status` 变为 `success` 通知前端。
+
+##### Anthropic (API Token)
+
+需在请求中附带 token：
+
+```json
+{ "provider": "anthropic", "token": "sk-ant-xxx" }
+```
+
+**Response:**
+
+```json
+{ "status": "success", "message": "Anthropic token saved" }
+```
+
+##### Google Antigravity (Browser OAuth)
+
+返回授权 URL，前端打开新标签页：
+
+```json
+{
+ "status": "redirect",
+ "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
+ "message": "Open the URL to authenticate with Google."
+}
+```
+
+认证完成后 Google 回调至 `GET /auth/callback`，自动保存凭据并重定向回 picoclaw-config 页面。
+
+---
+
+#### POST /api/auth/logout
+
+登出 Provider。
+
+**Request Body** — `application/json`
+
+```json
+{ "provider": "openai" }
+```
+
+传空字符串或省略 `provider` 则登出所有 Provider。
+
+**Response** `200 OK`
+
+```json
+{ "status": "ok" }
+```
+
+---
+
+#### GET /auth/callback
+
+OAuth Browser 回调端点（Google Antigravity 专用），由 OAuth Provider 重定向调用，**非前端直接使用**。
+
+**Query Parameters:**
+- `state` — OAuth state 校验
+- `code` — 授权码
+
+认证成功后重定向到 `/#auth`。
+
+### Process API
+
+#### GET /api/process/status
+
+获取 `picoclaw gateway` 进程的运行状态。
+
+**Response** `200 OK` (运行中)
+
+```json
+{
+ "process_status": "running",
+ "status": "ok",
+ "uptime": "1.010814s"
+}
+```
+
+**Response** `200 OK` (未运行)
+
+```json
+{
+ "process_status": "stopped",
+ "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
+}
+```
+
+---
+
+#### POST /api/process/start
+
+在后台启动 `picoclaw gateway` 进程。
+
+**Response** `200 OK`
+
+```json
+{
+ "status": "ok",
+ "pid": 12345
+}
+```
+
+---
+
+#### POST /api/process/stop
+
+停止正在运行的 `picoclaw gateway` 进程。
+
+**Response** `200 OK`
+
+```json
+{
+ "status": "ok"
+}
+```
+
+---
+
+## 测试
+
+```bash
+go test -v ./cmd/picoclaw-launcher/
+```
diff --git a/cmd/picoclaw-launcher/icon.ico b/cmd/picoclaw-launcher/icon.ico
new file mode 100644
index 000000000..4f6539414
Binary files /dev/null and b/cmd/picoclaw-launcher/icon.ico differ
diff --git a/cmd/picoclaw-launcher/internal/server/auth_config.go b/cmd/picoclaw-launcher/internal/server/auth_config.go
new file mode 100644
index 000000000..f75e8fff0
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/auth_config.go
@@ -0,0 +1,147 @@
+package server
+
+import (
+ "log"
+ "strings"
+
+ "github.com/sipeed/picoclaw/pkg/auth"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+// updateConfigAfterLogin updates config.json after a successful provider login.
+func updateConfigAfterLogin(configPath, provider string, cred *auth.AuthCredential) {
+ cfg, err := config.LoadConfig(configPath)
+ if err != nil {
+ log.Printf("Warning: could not load config to update auth_method: %v", err)
+ return
+ }
+
+ switch provider {
+ case "openai":
+ cfg.Providers.OpenAI.AuthMethod = "oauth"
+ found := false
+ for i := range cfg.ModelList {
+ if isOpenAIModel(cfg.ModelList[i].Model) {
+ cfg.ModelList[i].AuthMethod = "oauth"
+ found = true
+ break
+ }
+ }
+ if !found {
+ cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+ ModelName: "gpt-5.2",
+ Model: "openai/gpt-5.2",
+ AuthMethod: "oauth",
+ })
+ }
+ cfg.Agents.Defaults.ModelName = "gpt-5.2"
+
+ case "anthropic":
+ cfg.Providers.Anthropic.AuthMethod = "token"
+ found := false
+ for i := range cfg.ModelList {
+ if isAnthropicModel(cfg.ModelList[i].Model) {
+ cfg.ModelList[i].AuthMethod = "token"
+ found = true
+ break
+ }
+ }
+ if !found {
+ cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+ ModelName: "claude-sonnet-4.6",
+ Model: "anthropic/claude-sonnet-4.6",
+ AuthMethod: "token",
+ })
+ }
+ cfg.Agents.Defaults.ModelName = "claude-sonnet-4.6"
+
+ case "google-antigravity":
+ cfg.Providers.Antigravity.AuthMethod = "oauth"
+ found := false
+ for i := range cfg.ModelList {
+ if isAntigravityModel(cfg.ModelList[i].Model) {
+ cfg.ModelList[i].AuthMethod = "oauth"
+ found = true
+ break
+ }
+ }
+ if !found {
+ cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+ ModelName: "gemini-flash",
+ Model: "antigravity/gemini-3-flash",
+ AuthMethod: "oauth",
+ })
+ }
+ cfg.Agents.Defaults.ModelName = "gemini-flash"
+ }
+
+ if err := config.SaveConfig(configPath, cfg); err != nil {
+ log.Printf("Warning: could not update config: %v", err)
+ }
+}
+
+// clearAuthMethodInConfig clears auth_method for a specific provider in config.json.
+func clearAuthMethodInConfig(configPath, provider string) {
+ cfg, err := config.LoadConfig(configPath)
+ if err != nil {
+ return
+ }
+
+ for i := range cfg.ModelList {
+ switch provider {
+ case "openai":
+ if isOpenAIModel(cfg.ModelList[i].Model) {
+ cfg.ModelList[i].AuthMethod = ""
+ }
+ case "anthropic":
+ if isAnthropicModel(cfg.ModelList[i].Model) {
+ cfg.ModelList[i].AuthMethod = ""
+ }
+ case "google-antigravity", "antigravity":
+ if isAntigravityModel(cfg.ModelList[i].Model) {
+ cfg.ModelList[i].AuthMethod = ""
+ }
+ }
+ }
+
+ switch provider {
+ case "openai":
+ cfg.Providers.OpenAI.AuthMethod = ""
+ case "anthropic":
+ cfg.Providers.Anthropic.AuthMethod = ""
+ case "google-antigravity", "antigravity":
+ cfg.Providers.Antigravity.AuthMethod = ""
+ }
+
+ config.SaveConfig(configPath, cfg)
+}
+
+// clearAllAuthMethodsInConfig clears auth_method for all providers in config.json.
+func clearAllAuthMethodsInConfig(configPath string) {
+ cfg, err := config.LoadConfig(configPath)
+ if err != nil {
+ return
+ }
+ for i := range cfg.ModelList {
+ cfg.ModelList[i].AuthMethod = ""
+ }
+ cfg.Providers.OpenAI.AuthMethod = ""
+ cfg.Providers.Anthropic.AuthMethod = ""
+ cfg.Providers.Antigravity.AuthMethod = ""
+ config.SaveConfig(configPath, cfg)
+}
+
+// ── Model identification helpers ─────────────────────────────────
+
+func isOpenAIModel(model string) bool {
+ return model == "openai" || strings.HasPrefix(model, "openai/")
+}
+
+func isAnthropicModel(model string) bool {
+ return model == "anthropic" || strings.HasPrefix(model, "anthropic/")
+}
+
+func isAntigravityModel(model string) bool {
+ return model == "antigravity" || model == "google-antigravity" ||
+ strings.HasPrefix(model, "antigravity/") || strings.HasPrefix(model, "google-antigravity/")
+}
diff --git a/cmd/picoclaw-launcher/internal/server/auth_config_test.go b/cmd/picoclaw-launcher/internal/server/auth_config_test.go
new file mode 100644
index 000000000..92158d011
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/auth_config_test.go
@@ -0,0 +1,222 @@
+package server
+
+import (
+ "path/filepath"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/auth"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+// ── Model identification helpers ─────────────────────────────────
+
+func TestIsOpenAIModel(t *testing.T) {
+ tests := []struct {
+ model string
+ want bool
+ }{
+ {"openai", true},
+ {"openai/gpt-4o", true},
+ {"openai/gpt-5.2", true},
+ {"anthropic", false},
+ {"anthropic/claude-sonnet-4.6", false},
+ {"openai-compatible", false},
+ {"", false},
+ }
+ for _, tt := range tests {
+ if got := isOpenAIModel(tt.model); got != tt.want {
+ t.Errorf("isOpenAIModel(%q) = %v, want %v", tt.model, got, tt.want)
+ }
+ }
+}
+
+func TestIsAnthropicModel(t *testing.T) {
+ tests := []struct {
+ model string
+ want bool
+ }{
+ {"anthropic", true},
+ {"anthropic/claude-sonnet-4.6", true},
+ {"openai", false},
+ {"openai/gpt-4o", false},
+ {"", false},
+ }
+ for _, tt := range tests {
+ if got := isAnthropicModel(tt.model); got != tt.want {
+ t.Errorf("isAnthropicModel(%q) = %v, want %v", tt.model, got, tt.want)
+ }
+ }
+}
+
+func TestIsAntigravityModel(t *testing.T) {
+ tests := []struct {
+ model string
+ want bool
+ }{
+ {"antigravity", true},
+ {"google-antigravity", true},
+ {"antigravity/gemini-3-flash", true},
+ {"google-antigravity/gemini-3-flash", true},
+ {"openai", false},
+ {"antigravity-custom", false},
+ {"", false},
+ }
+ for _, tt := range tests {
+ if got := isAntigravityModel(tt.model); got != tt.want {
+ t.Errorf("isAntigravityModel(%q) = %v, want %v", tt.model, got, tt.want)
+ }
+ }
+}
+
+// ── Config update helpers ────────────────────────────────────────
+
+func writeTempConfigViaSave(t *testing.T, cfg *config.Config) string {
+ t.Helper()
+ dir := t.TempDir()
+ path := filepath.Join(dir, "config.json")
+ if err := config.SaveConfig(path, cfg); err != nil {
+ t.Fatalf("save config: %v", err)
+ }
+ return path
+}
+
+func loadTempConfig(t *testing.T, path string) *config.Config {
+ t.Helper()
+ cfg, err := config.LoadConfig(path)
+ if err != nil {
+ t.Fatalf("load config: %v", err)
+ }
+ return cfg
+}
+
+func TestUpdateConfigAfterLogin_OpenAI_ExistingModel(t *testing.T) {
+ cfg := &config.Config{
+ ModelList: []config.ModelConfig{
+ {ModelName: "gpt-4o", Model: "openai/gpt-4o"},
+ },
+ }
+ path := writeTempConfigViaSave(t, cfg)
+
+ cred := &auth.AuthCredential{AuthMethod: "oauth"}
+ updateConfigAfterLogin(path, "openai", cred)
+
+ result := loadTempConfig(t, path)
+
+ // Model-level auth_method persists through serialization
+ if len(result.ModelList) != 1 {
+ t.Fatalf("expected 1 model, got %d", len(result.ModelList))
+ }
+ if result.ModelList[0].AuthMethod != "oauth" {
+ t.Errorf("expected model auth_method=oauth, got %q", result.ModelList[0].AuthMethod)
+ }
+}
+
+func TestUpdateConfigAfterLogin_OpenAI_NoExistingModel(t *testing.T) {
+ cfg := &config.Config{
+ ModelList: []config.ModelConfig{
+ {ModelName: "claude", Model: "anthropic/claude-sonnet-4.6"},
+ },
+ }
+ path := writeTempConfigViaSave(t, cfg)
+
+ cred := &auth.AuthCredential{AuthMethod: "oauth"}
+ updateConfigAfterLogin(path, "openai", cred)
+
+ result := loadTempConfig(t, path)
+
+ if len(result.ModelList) != 2 {
+ t.Fatalf("expected 2 models (original + added), got %d", len(result.ModelList))
+ }
+ if result.ModelList[1].Model != "openai/gpt-5.2" {
+ t.Errorf("expected added model openai/gpt-5.2, got %q", result.ModelList[1].Model)
+ }
+ if result.Agents.Defaults.ModelName != "gpt-5.2" {
+ t.Errorf("expected default model_name=gpt-5.2, got %q", result.Agents.Defaults.ModelName)
+ }
+}
+
+func TestUpdateConfigAfterLogin_Anthropic(t *testing.T) {
+ cfg := &config.Config{}
+ path := writeTempConfigViaSave(t, cfg)
+
+ cred := &auth.AuthCredential{AuthMethod: "token"}
+ updateConfigAfterLogin(path, "anthropic", cred)
+
+ result := loadTempConfig(t, path)
+
+ // Model should be added with correct auth_method
+ if len(result.ModelList) != 1 {
+ t.Fatalf("expected 1 model added, got %d", len(result.ModelList))
+ }
+ if result.ModelList[0].Model != "anthropic/claude-sonnet-4.6" {
+ t.Errorf("expected model anthropic/claude-sonnet-4.6, got %q", result.ModelList[0].Model)
+ }
+ if result.ModelList[0].AuthMethod != "token" {
+ t.Errorf("expected model auth_method=token, got %q", result.ModelList[0].AuthMethod)
+ }
+}
+
+func TestUpdateConfigAfterLogin_GoogleAntigravity(t *testing.T) {
+ cfg := &config.Config{}
+ path := writeTempConfigViaSave(t, cfg)
+
+ cred := &auth.AuthCredential{AuthMethod: "oauth"}
+ updateConfigAfterLogin(path, "google-antigravity", cred)
+
+ result := loadTempConfig(t, path)
+
+ // Model should be added with correct auth_method
+ if len(result.ModelList) != 1 {
+ t.Fatalf("expected 1 model added, got %d", len(result.ModelList))
+ }
+ if result.ModelList[0].Model != "antigravity/gemini-3-flash" {
+ t.Errorf("expected model antigravity/gemini-3-flash, got %q", result.ModelList[0].Model)
+ }
+ if result.ModelList[0].AuthMethod != "oauth" {
+ t.Errorf("expected model auth_method=oauth, got %q", result.ModelList[0].AuthMethod)
+ }
+}
+
+func TestClearAuthMethodInConfig(t *testing.T) {
+ cfg := &config.Config{
+ ModelList: []config.ModelConfig{
+ {ModelName: "gpt-4o", Model: "openai/gpt-4o", AuthMethod: "oauth"},
+ {ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
+ },
+ }
+ path := writeTempConfigViaSave(t, cfg)
+
+ clearAuthMethodInConfig(path, "openai")
+
+ result := loadTempConfig(t, path)
+
+ // Openai model auth_method should be cleared
+ if result.ModelList[0].AuthMethod != "" {
+ t.Errorf("expected openai model auth_method cleared, got %q", result.ModelList[0].AuthMethod)
+ }
+ // Anthropic model should be unchanged
+ if result.ModelList[1].AuthMethod != "token" {
+ t.Errorf("expected anthropic model auth_method unchanged, got %q", result.ModelList[1].AuthMethod)
+ }
+}
+
+func TestClearAllAuthMethodsInConfig(t *testing.T) {
+ cfg := &config.Config{
+ ModelList: []config.ModelConfig{
+ {ModelName: "gpt-4o", Model: "openai/gpt-4o", AuthMethod: "oauth"},
+ {ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
+ {ModelName: "gemini", Model: "antigravity/gemini-3-flash", AuthMethod: "oauth"},
+ },
+ }
+ path := writeTempConfigViaSave(t, cfg)
+
+ clearAllAuthMethodsInConfig(path)
+
+ result := loadTempConfig(t, path)
+
+ for i, m := range result.ModelList {
+ if m.AuthMethod != "" {
+ t.Errorf("model[%d] auth_method not cleared, got %q", i, m.AuthMethod)
+ }
+ }
+}
diff --git a/cmd/picoclaw-launcher/internal/server/auth_handlers.go b/cmd/picoclaw-launcher/internal/server/auth_handlers.go
new file mode 100644
index 000000000..1e9b8be0a
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/auth_handlers.go
@@ -0,0 +1,312 @@
+package server
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+ "log"
+ "net/http"
+ "sync"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/auth"
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// oauthSession stores in-flight OAuth state for browser-based flows.
+type oauthSession struct {
+ Provider string
+ PKCE auth.PKCECodes
+ State string
+ RedirectURI string
+ OAuthCfg auth.OAuthProviderConfig
+ ConfigPath string
+}
+
+// deviceCodeSession stores in-flight device code flow state.
+type deviceCodeSession struct {
+ mu sync.Mutex
+ Provider string
+ Info *auth.DeviceCodeInfo
+ OAuthCfg auth.OAuthProviderConfig
+ ConfigPath string
+ Status string // "pending", "success", "error"
+ Error string
+ Done bool
+}
+
+var (
+ oauthSessions = map[string]*oauthSession{} // keyed by state
+ oauthSessionsMu sync.Mutex
+
+ activeDeviceSession *deviceCodeSession
+ activeDeviceSessionMu sync.Mutex
+)
+
+// handleOpenAILogin starts the OpenAI device code flow and returns device code info to the frontend.
+func handleOpenAILogin(w http.ResponseWriter, configPath string) {
+ // Check if there's already a pending device code session
+ activeDeviceSessionMu.Lock()
+ if activeDeviceSession != nil {
+ activeDeviceSession.mu.Lock()
+ if !activeDeviceSession.Done {
+ resp := map[string]any{
+ "status": "pending",
+ "device_url": activeDeviceSession.Info.VerifyURL,
+ "user_code": activeDeviceSession.Info.UserCode,
+ "message": "Device code flow already in progress. Enter the code in your browser.",
+ }
+ activeDeviceSession.mu.Unlock()
+ activeDeviceSessionMu.Unlock()
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(resp)
+ return
+ }
+ activeDeviceSession.mu.Unlock()
+ }
+ activeDeviceSessionMu.Unlock()
+
+ // Request a device code
+ oauthCfg := auth.OpenAIOAuthConfig()
+ info, err := auth.RequestDeviceCode(oauthCfg)
+ if err != nil {
+ http.Error(w, fmt.Sprintf("Failed to request device code: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ session := &deviceCodeSession{
+ Provider: "openai",
+ Info: info,
+ OAuthCfg: oauthCfg,
+ ConfigPath: configPath,
+ Status: "pending",
+ }
+
+ activeDeviceSessionMu.Lock()
+ activeDeviceSession = session
+ activeDeviceSessionMu.Unlock()
+
+ // Start background polling
+ go func() {
+ deadline := time.After(15 * time.Minute)
+ ticker := time.NewTicker(time.Duration(info.Interval) * time.Second)
+ defer ticker.Stop()
+
+ for {
+ select {
+ case <-deadline:
+ session.mu.Lock()
+ session.Status = "error"
+ session.Error = "Authentication timed out after 15 minutes"
+ session.Done = true
+ session.mu.Unlock()
+ return
+ case <-ticker.C:
+ cred, err := auth.PollDeviceCodeOnce(oauthCfg, info.DeviceAuthID, info.UserCode)
+ if err != nil {
+ continue // Still pending
+ }
+ if cred != nil {
+ if saveErr := auth.SetCredential("openai", cred); saveErr != nil {
+ session.mu.Lock()
+ session.Status = "error"
+ session.Error = saveErr.Error()
+ session.Done = true
+ session.mu.Unlock()
+ return
+ }
+ updateConfigAfterLogin(configPath, "openai", cred)
+ session.mu.Lock()
+ session.Status = "success"
+ session.Done = true
+ session.mu.Unlock()
+ log.Printf("OpenAI device code login successful (account: %s)", cred.AccountID)
+ return
+ }
+ }
+ }
+ }()
+
+ // Return device code info to frontend
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]any{
+ "status": "pending",
+ "device_url": info.VerifyURL,
+ "user_code": info.UserCode,
+ "message": "Open the URL and enter the code to authenticate.",
+ })
+}
+
+// handleAnthropicLogin saves a pasted API token for Anthropic.
+func handleAnthropicLogin(w http.ResponseWriter, token, configPath string) {
+ if token == "" {
+ http.Error(w, "Token is required for Anthropic login", http.StatusBadRequest)
+ return
+ }
+
+ cred := &auth.AuthCredential{
+ AccessToken: token,
+ Provider: "anthropic",
+ AuthMethod: "token",
+ }
+
+ if err := auth.SetCredential("anthropic", cred); err != nil {
+ http.Error(w, fmt.Sprintf("Failed to save credentials: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ updateConfigAfterLogin(configPath, "anthropic", cred)
+
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]string{
+ "status": "success",
+ "message": "Anthropic token saved",
+ })
+}
+
+// handleGoogleAntigravityLogin generates a PKCE + auth URL and returns it to the frontend.
+func handleGoogleAntigravityLogin(w http.ResponseWriter, r *http.Request, configPath string) {
+ oauthCfg := auth.GoogleAntigravityOAuthConfig()
+
+ pkce, err := auth.GeneratePKCE()
+ if err != nil {
+ http.Error(w, fmt.Sprintf("Failed to generate PKCE: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ state, err := auth.GenerateState()
+ if err != nil {
+ http.Error(w, fmt.Sprintf("Failed to generate state: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ // Build redirect URI pointing to picoclaw-launcher's own callback
+ scheme := "http"
+ redirectURI := fmt.Sprintf("%s://%s/auth/callback", scheme, r.Host)
+
+ authURL := auth.BuildAuthorizeURL(oauthCfg, pkce, state, redirectURI)
+
+ // Store session for callback
+ oauthSessionsMu.Lock()
+ oauthSessions[state] = &oauthSession{
+ Provider: "google-antigravity",
+ PKCE: pkce,
+ State: state,
+ RedirectURI: redirectURI,
+ OAuthCfg: oauthCfg,
+ ConfigPath: configPath,
+ }
+ oauthSessionsMu.Unlock()
+
+ // Clean up stale sessions after 10 minutes
+ go func() {
+ time.Sleep(10 * time.Minute)
+ oauthSessionsMu.Lock()
+ delete(oauthSessions, state)
+ oauthSessionsMu.Unlock()
+ }()
+
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]string{
+ "status": "redirect",
+ "auth_url": authURL,
+ "message": "Open the URL to authenticate with Google.",
+ })
+}
+
+// handleOAuthCallback processes the OAuth callback from Google Antigravity.
+func handleOAuthCallback(w http.ResponseWriter, r *http.Request) {
+ state := r.URL.Query().Get("state")
+ code := r.URL.Query().Get("code")
+
+ oauthSessionsMu.Lock()
+ session, ok := oauthSessions[state]
+ if ok {
+ delete(oauthSessions, state)
+ }
+ oauthSessionsMu.Unlock()
+
+ if !ok {
+ http.Error(w, "Invalid or expired OAuth state", http.StatusBadRequest)
+ return
+ }
+
+ if code == "" {
+ errMsg := r.URL.Query().Get("error")
+ w.Header().Set("Content-Type", "text/html")
+ fmt.Fprintf(
+ w,
+ `Authentication failed
%s
You can close this window.
`,
+ errMsg,
+ )
+ return
+ }
+
+ cred, err := auth.ExchangeCodeForTokens(session.OAuthCfg, code, session.PKCE.CodeVerifier, session.RedirectURI)
+ if err != nil {
+ w.Header().Set("Content-Type", "text/html")
+ fmt.Fprintf(
+ w,
+ `Authentication failed
%s
You can close this window.
`,
+ err.Error(),
+ )
+ return
+ }
+
+ cred.Provider = session.Provider
+
+ // Fetch user info for Google Antigravity
+ if session.Provider == "google-antigravity" {
+ if email, err := fetchGoogleUserEmail(cred.AccessToken); err == nil {
+ cred.Email = email
+ }
+ if projectID, err := providers.FetchAntigravityProjectID(cred.AccessToken); err == nil {
+ cred.ProjectID = projectID
+ }
+ }
+
+ if err := auth.SetCredential(session.Provider, cred); err != nil {
+ w.Header().Set("Content-Type", "text/html")
+ fmt.Fprintf(w, `Failed to save credentials
%s
`, err.Error())
+ return
+ }
+
+ updateConfigAfterLogin(session.ConfigPath, session.Provider, cred)
+
+ // Redirect back to picoclaw-launcher UI
+ w.Header().Set("Content-Type", "text/html")
+ fmt.Fprintf(w, `
+ Authentication successful!
+ Redirecting back to Config Editor...
+
+ `)
+}
+
+// fetchGoogleUserEmail retrieves the user's email from Google's userinfo endpoint.
+func fetchGoogleUserEmail(accessToken string) (string, error) {
+ req, err := http.NewRequest("GET", "https://www.googleapis.com/oauth2/v2/userinfo", nil)
+ if err != nil {
+ return "", err
+ }
+ req.Header.Set("Authorization", "Bearer "+accessToken)
+
+ client := &http.Client{Timeout: 10 * time.Second}
+ resp, err := client.Do(req)
+ if err != nil {
+ return "", err
+ }
+ defer resp.Body.Close()
+
+ body, _ := io.ReadAll(resp.Body)
+ if resp.StatusCode != http.StatusOK {
+ return "", fmt.Errorf("userinfo request failed: %s", string(body))
+ }
+
+ var userInfo struct {
+ Email string `json:"email"`
+ }
+ if err := json.Unmarshal(body, &userInfo); err != nil {
+ return "", err
+ }
+ return userInfo.Email, nil
+}
diff --git a/cmd/picoclaw-launcher/internal/server/logbuffer.go b/cmd/picoclaw-launcher/internal/server/logbuffer.go
new file mode 100644
index 000000000..4d70f6466
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/logbuffer.go
@@ -0,0 +1,99 @@
+package server
+
+import "sync"
+
+// LogBuffer is a thread-safe ring buffer that stores the most recent N log lines.
+// It supports incremental reads via LinesSince and tracks a runID that increments
+// on each Reset (used to detect gateway restarts).
+type LogBuffer struct {
+ mu sync.RWMutex
+ lines []string
+ cap int
+ total int // total lines ever appended in current run
+ runID int
+}
+
+// NewLogBuffer creates a LogBuffer with the given capacity.
+func NewLogBuffer(capacity int) *LogBuffer {
+ return &LogBuffer{
+ lines: make([]string, 0, capacity),
+ cap: capacity,
+ }
+}
+
+// Append adds a line to the buffer. If the buffer is full, the oldest line is evicted.
+func (b *LogBuffer) Append(line string) {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+
+ if len(b.lines) < b.cap {
+ b.lines = append(b.lines, line)
+ } else {
+ b.lines[b.total%b.cap] = line
+ }
+
+ b.total++
+}
+
+// Reset clears the buffer and increments the runID. Call this when starting a new gateway process.
+func (b *LogBuffer) Reset() {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+
+ b.lines = b.lines[:0]
+ b.total = 0
+ b.runID++
+}
+
+// LinesSince returns lines appended after the given offset, the current total count, and the runID.
+// If offset >= total, no lines are returned. If offset is too old (evicted), all buffered lines are returned.
+func (b *LogBuffer) LinesSince(offset int) (lines []string, total int, runID int) {
+ b.mu.RLock()
+ defer b.mu.RUnlock()
+
+ total = b.total
+ runID = b.runID
+
+ if offset >= b.total {
+ return nil, total, runID
+ }
+
+ buffered := len(b.lines)
+
+ // How many new lines since offset
+ newCount := b.total - offset
+ if newCount > buffered {
+ newCount = buffered
+ }
+
+ result := make([]string, newCount)
+
+ if b.total <= b.cap {
+ // Buffer hasn't wrapped yet — simple slice
+ copy(result, b.lines[buffered-newCount:])
+ } else {
+ // Buffer has wrapped — read from ring
+ start := (b.total - newCount) % b.cap
+ for i := range newCount {
+ result[i] = b.lines[(start+i)%b.cap]
+ }
+ }
+
+ return result, total, runID
+}
+
+// RunID returns the current run identifier.
+func (b *LogBuffer) RunID() int {
+ b.mu.RLock()
+ defer b.mu.RUnlock()
+
+ return b.runID
+}
+
+// Total returns the total number of lines appended in the current run.
+func (b *LogBuffer) Total() int {
+ b.mu.RLock()
+ defer b.mu.RUnlock()
+
+ return b.total
+}
diff --git a/cmd/picoclaw-launcher/internal/server/logbuffer_test.go b/cmd/picoclaw-launcher/internal/server/logbuffer_test.go
new file mode 100644
index 000000000..dc525be16
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/logbuffer_test.go
@@ -0,0 +1,116 @@
+package server
+
+import (
+ "fmt"
+ "sync"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+)
+
+func TestLogBuffer_Basic(t *testing.T) {
+ buf := NewLogBuffer(5)
+
+ // Empty buffer
+ lines, total, runID := buf.LinesSince(0)
+ assert.Nil(t, lines)
+ assert.Equal(t, 0, total)
+ assert.Equal(t, 0, runID)
+
+ // Append some lines
+ buf.Append("line1")
+ buf.Append("line2")
+ buf.Append("line3")
+
+ lines, total, runID = buf.LinesSince(0)
+ assert.Equal(t, []string{"line1", "line2", "line3"}, lines)
+ assert.Equal(t, 3, total)
+ assert.Equal(t, 0, runID)
+
+ // Incremental read
+ lines, total, _ = buf.LinesSince(2)
+ assert.Equal(t, []string{"line3"}, lines)
+ assert.Equal(t, 3, total)
+
+ // No new lines
+ lines, total, _ = buf.LinesSince(3)
+ assert.Nil(t, lines)
+ assert.Equal(t, 3, total)
+}
+
+func TestLogBuffer_Wrap(t *testing.T) {
+ buf := NewLogBuffer(3)
+
+ buf.Append("a")
+ buf.Append("b")
+ buf.Append("c")
+ buf.Append("d") // evicts "a"
+ buf.Append("e") // evicts "b"
+
+ lines, total, _ := buf.LinesSince(0)
+ assert.Equal(t, []string{"c", "d", "e"}, lines)
+ assert.Equal(t, 5, total)
+
+ // Incremental after wrap
+ lines, total, _ = buf.LinesSince(3)
+ assert.Equal(t, []string{"d", "e"}, lines)
+ assert.Equal(t, 5, total)
+
+ // Offset too old (before buffer start), get all buffered
+ lines, total, _ = buf.LinesSince(1)
+ assert.Equal(t, []string{"c", "d", "e"}, lines)
+ assert.Equal(t, 5, total)
+}
+
+func TestLogBuffer_Reset(t *testing.T) {
+ buf := NewLogBuffer(5)
+
+ buf.Append("before")
+ assert.Equal(t, 0, buf.RunID())
+
+ buf.Reset()
+ assert.Equal(t, 1, buf.RunID())
+ assert.Equal(t, 0, buf.Total())
+
+ lines, total, runID := buf.LinesSince(0)
+ assert.Nil(t, lines)
+ assert.Equal(t, 0, total)
+ assert.Equal(t, 1, runID)
+
+ buf.Append("after")
+ lines, total, runID = buf.LinesSince(0)
+ assert.Equal(t, []string{"after"}, lines)
+ assert.Equal(t, 1, total)
+ assert.Equal(t, 1, runID)
+}
+
+func TestLogBuffer_Concurrent(t *testing.T) {
+ buf := NewLogBuffer(100)
+ var wg sync.WaitGroup
+
+ // 10 writers
+ for i := range 10 {
+ wg.Add(1)
+ go func(id int) {
+ defer wg.Done()
+ for j := range 50 {
+ buf.Append(fmt.Sprintf("writer-%d-line-%d", id, j))
+ }
+ }(i)
+ }
+
+ // 5 readers
+ for range 5 {
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ for range 100 {
+ buf.LinesSince(0)
+ }
+ }()
+ }
+
+ wg.Wait()
+
+ assert.Equal(t, 500, buf.Total())
+}
diff --git a/cmd/picoclaw-launcher/internal/server/process.go b/cmd/picoclaw-launcher/internal/server/process.go
new file mode 100644
index 000000000..bc2129bf5
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/process.go
@@ -0,0 +1,232 @@
+package server
+
+import (
+ "bufio"
+ "encoding/json"
+ "fmt"
+ "io"
+ "log"
+ "net"
+ "net/http"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "runtime"
+ "strconv"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+// gatewayLogs stores captured stdout/stderr from the gateway process launched by the launcher.
+var gatewayLogs = NewLogBuffer(200)
+
+// RegisterProcessAPI registers endpoints to start, stop and check status of the picoclaw gateway.
+func RegisterProcessAPI(mux *http.ServeMux, absPath string) {
+ mux.HandleFunc("GET /api/process/status", func(w http.ResponseWriter, r *http.Request) {
+ handleStatusGateway(w, r, absPath)
+ })
+ mux.HandleFunc("POST /api/process/start", handleStartGateway)
+ mux.HandleFunc("POST /api/process/stop", handleStopGateway)
+}
+
+func handleStartGateway(w http.ResponseWriter, r *http.Request) {
+ // Locate picoclaw executable:
+ // 1. Try same directory as current executable
+ // 2. Fallback to just "picoclaw" (relies on $PATH)
+ execPath := "picoclaw"
+
+ if exe, err := os.Executable(); err == nil {
+ dir := filepath.Dir(exe)
+ candidate := filepath.Join(dir, "picoclaw")
+ if runtime.GOOS == "windows" {
+ candidate += ".exe"
+ }
+
+ if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+ execPath = candidate
+ }
+ }
+
+ cmd := exec.Command(execPath, "gateway")
+
+ stdoutPipe, err := cmd.StdoutPipe()
+ if err != nil {
+ log.Printf("Failed to create stdout pipe: %v\n", err)
+ http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ stderrPipe, err := cmd.StderrPipe()
+ if err != nil {
+ log.Printf("Failed to create stderr pipe: %v\n", err)
+ http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ // Clear old logs and increment runID before starting
+ gatewayLogs.Reset()
+
+ if err := cmd.Start(); err != nil {
+ log.Printf("Failed to start picoclaw gateway: %v\n", err)
+ http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ // Read stdout and stderr into the log buffer
+ go scanPipe(stdoutPipe, gatewayLogs)
+ go scanPipe(stderrPipe, gatewayLogs)
+
+ // Wait for the process to exit in the background to avoid zombies
+ go func() {
+ if err := cmd.Wait(); err != nil {
+ log.Printf("Gateway process exited: %v\n", err)
+ }
+ }()
+
+ log.Printf("Started picoclaw gateway (PID: %d) from %s\n", cmd.Process.Pid, execPath)
+
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]any{
+ "status": "ok",
+ "pid": cmd.Process.Pid,
+ })
+}
+
+// scanPipe reads lines from r and appends them to buf. It returns when r reaches EOF.
+func scanPipe(r io.Reader, buf *LogBuffer) {
+ scanner := bufio.NewScanner(r)
+ scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024) // up to 1MB per line
+
+ for scanner.Scan() {
+ buf.Append(scanner.Text())
+ }
+}
+
+func handleStopGateway(w http.ResponseWriter, r *http.Request) {
+ var err error
+ if runtime.GOOS == "windows" {
+ // Kill via taskkill finding picoclaw.exe (though it might kill this config tool if it's named picoclaw-launcher.exe...? No, /IM does exact match usually, but just to be safe let's stop exactly picoclaw.exe)
+ // Alternatively, we use powershell to kill processes with commandline containing 'gateway'
+ psCmd := `Get-WmiObject Win32_Process | Where-Object { $_.CommandLine -match 'picoclaw.*gateway' } | ForEach-Object { Stop-Process $_.ProcessId -Force }`
+ err = exec.Command("powershell", "-Command", psCmd).Run()
+ } else {
+ // Linux/macOS
+ err = exec.Command("pkill", "-f", "picoclaw gateway").Run()
+ }
+
+ if err != nil {
+ log.Printf("Warning: Failed to stop gateway (perhaps not running?): %v\n", err)
+ // We still return 200 OK because pkill returns an error if no process was found
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]any{
+ "status": "ok", // or "not_found"
+ "msg": "Stop command executed, but returned error (process might not be running).",
+ "error": err.Error(),
+ })
+ return
+ }
+
+ log.Printf("Stopped picoclaw gateway processes.\n")
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]string{
+ "status": "ok",
+ })
+}
+
+func handleStatusGateway(w http.ResponseWriter, r *http.Request, absPath string) {
+ cfg, cfgErr := config.LoadConfig(absPath)
+ host := "127.0.0.1"
+ port := 18790
+ if cfgErr == nil && cfg != nil {
+ if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
+ host = cfg.Gateway.Host
+ }
+ if cfg.Gateway.Port != 0 {
+ port = cfg.Gateway.Port
+ }
+ }
+
+ url := fmt.Sprintf("http://%s/health", net.JoinHostPort(host, strconv.Itoa(port)))
+ client := http.Client{Timeout: 2 * time.Second}
+ resp, err := client.Get(url)
+
+ // Build the response data map
+ data := map[string]any{}
+
+ if err != nil {
+ data["process_status"] = "stopped"
+ data["error"] = err.Error()
+ } else {
+ defer resp.Body.Close()
+
+ if resp.StatusCode != http.StatusOK {
+ data["process_status"] = "error"
+ data["status_code"] = resp.StatusCode
+ } else {
+ var healthData map[string]any
+ if decErr := json.NewDecoder(resp.Body).Decode(&healthData); decErr != nil {
+ data["process_status"] = "error"
+ data["error"] = "invalid response from gateway"
+ } else {
+ // Gateway is running and responded properly — merge health data
+ for k, v := range healthData {
+ data[k] = v
+ }
+ data["process_status"] = "running"
+ }
+ }
+ }
+
+ // Append log data from the buffer
+ appendLogData(r, data)
+
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(data)
+}
+
+// appendLogData reads log_offset and log_run_id query params from the request and
+// populates the response data map with incremental log lines.
+func appendLogData(r *http.Request, data map[string]any) {
+ clientOffset := 0
+ clientRunID := -1
+
+ if v := r.URL.Query().Get("log_offset"); v != "" {
+ if n, err := strconv.Atoi(v); err == nil {
+ clientOffset = n
+ }
+ }
+
+ if v := r.URL.Query().Get("log_run_id"); v != "" {
+ if n, err := strconv.Atoi(v); err == nil {
+ clientRunID = n
+ }
+ }
+
+ runID := gatewayLogs.RunID()
+
+ // If runID is 0 (never reset = never launched from this launcher), report no source
+ if runID == 0 {
+ data["logs"] = []string{}
+ data["log_total"] = 0
+ data["log_run_id"] = 0
+ data["log_source"] = "none"
+ return
+ }
+
+ // If the client's runID doesn't match, send all buffered lines (gateway restarted)
+ offset := clientOffset
+ if clientRunID != runID {
+ offset = 0
+ }
+
+ lines, total, runID := gatewayLogs.LinesSince(offset)
+ if lines == nil {
+ lines = []string{}
+ }
+
+ data["logs"] = lines
+ data["log_total"] = total
+ data["log_run_id"] = runID
+ data["log_source"] = "launcher"
+}
diff --git a/cmd/picoclaw-launcher/internal/server/server.go b/cmd/picoclaw-launcher/internal/server/server.go
new file mode 100644
index 000000000..4fc68f04c
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/server.go
@@ -0,0 +1,196 @@
+package server
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+ "log"
+ "net/http"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/auth"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+const DefaultPort = "18800"
+
+// providerStatus represents the auth status of a single provider in API responses.
+type providerStatus struct {
+ Provider string `json:"provider"`
+ AuthMethod string `json:"auth_method"`
+ Status string `json:"status"`
+ AccountID string `json:"account_id,omitempty"`
+ Email string `json:"email,omitempty"`
+ ProjectID string `json:"project_id,omitempty"`
+ ExpiresAt string `json:"expires_at,omitempty"`
+}
+
+// ── Route registration ───────────────────────────────────────────
+
+func RegisterConfigAPI(mux *http.ServeMux, absPath string) {
+ // GET /api/config — read config
+ mux.HandleFunc("GET /api/config", func(w http.ResponseWriter, r *http.Request) {
+ cfg, err := config.LoadConfig(absPath)
+ if err != nil {
+ http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ resp := map[string]any{
+ "config": cfg,
+ "path": absPath,
+ }
+ enc := json.NewEncoder(w)
+ enc.SetIndent("", " ")
+ if err := enc.Encode(resp); err != nil {
+ log.Printf("Failed to encode response: %v", err)
+ }
+ })
+
+ // PUT /api/config — save config
+ mux.HandleFunc("PUT /api/config", func(w http.ResponseWriter, r *http.Request) {
+ body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+ if err != nil {
+ http.Error(w, "Failed to read request body", http.StatusBadRequest)
+ return
+ }
+ defer r.Body.Close()
+
+ var cfg config.Config
+ if err := json.Unmarshal(body, &cfg); err != nil {
+ http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+ return
+ }
+
+ if err := config.SaveConfig(absPath, &cfg); err != nil {
+ http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+ })
+}
+
+func RegisterAuthAPI(mux *http.ServeMux, absPath string) {
+ // GET /api/auth/status — all authenticated providers + pending login state
+ mux.HandleFunc("GET /api/auth/status", func(w http.ResponseWriter, r *http.Request) {
+ store, err := auth.LoadStore()
+ if err != nil {
+ http.Error(w, fmt.Sprintf("Failed to load auth store: %v", err), http.StatusInternalServerError)
+ return
+ }
+
+ result := []providerStatus{}
+ for name, cred := range store.Credentials {
+ status := "active"
+ if cred.IsExpired() {
+ status = "expired"
+ } else if cred.NeedsRefresh() {
+ status = "needs_refresh"
+ }
+ ps := providerStatus{
+ Provider: name,
+ AuthMethod: cred.AuthMethod,
+ Status: status,
+ AccountID: cred.AccountID,
+ Email: cred.Email,
+ ProjectID: cred.ProjectID,
+ }
+ if !cred.ExpiresAt.IsZero() {
+ ps.ExpiresAt = cred.ExpiresAt.Format(time.RFC3339)
+ }
+ result = append(result, ps)
+ }
+
+ // Include pending device code state
+ var pendingDevice map[string]any
+ activeDeviceSessionMu.Lock()
+ if activeDeviceSession != nil {
+ activeDeviceSession.mu.Lock()
+ pendingDevice = map[string]any{
+ "provider": activeDeviceSession.Provider,
+ "status": activeDeviceSession.Status,
+ "device_url": activeDeviceSession.Info.VerifyURL,
+ "user_code": activeDeviceSession.Info.UserCode,
+ }
+ if activeDeviceSession.Error != "" {
+ pendingDevice["error"] = activeDeviceSession.Error
+ }
+ if activeDeviceSession.Done {
+ activeDeviceSession.mu.Unlock()
+ activeDeviceSession = nil
+ } else {
+ activeDeviceSession.mu.Unlock()
+ }
+ }
+ activeDeviceSessionMu.Unlock()
+
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]any{
+ "providers": result,
+ "pending_device": pendingDevice,
+ })
+ })
+
+ // POST /api/auth/login — initiate provider login
+ mux.HandleFunc("POST /api/auth/login", func(w http.ResponseWriter, r *http.Request) {
+ var req struct {
+ Provider string `json:"provider"`
+ Token string `json:"token,omitempty"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ http.Error(w, "Invalid request body", http.StatusBadRequest)
+ return
+ }
+
+ switch req.Provider {
+ case "openai":
+ handleOpenAILogin(w, absPath)
+ case "anthropic":
+ handleAnthropicLogin(w, req.Token, absPath)
+ case "google-antigravity", "antigravity":
+ handleGoogleAntigravityLogin(w, r, absPath)
+ default:
+ http.Error(
+ w,
+ fmt.Sprintf(
+ "Unsupported provider: %s (supported: openai, anthropic, google-antigravity)",
+ req.Provider,
+ ),
+ http.StatusBadRequest,
+ )
+ }
+ })
+
+ // POST /api/auth/logout — logout a provider
+ mux.HandleFunc("POST /api/auth/logout", func(w http.ResponseWriter, r *http.Request) {
+ var req struct {
+ Provider string `json:"provider"`
+ }
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ http.Error(w, "Invalid request body", http.StatusBadRequest)
+ return
+ }
+
+ if req.Provider == "" {
+ if err := auth.DeleteAllCredentials(); err != nil {
+ http.Error(w, fmt.Sprintf("Failed to logout: %v", err), http.StatusInternalServerError)
+ return
+ }
+ clearAllAuthMethodsInConfig(absPath)
+ } else {
+ if err := auth.DeleteCredential(req.Provider); err != nil {
+ http.Error(w, fmt.Sprintf("Failed to logout: %v", err), http.StatusInternalServerError)
+ return
+ }
+ clearAuthMethodInConfig(absPath, req.Provider)
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+ })
+
+ // GET /auth/callback — OAuth browser callback for Google Antigravity
+ mux.HandleFunc("GET /auth/callback", handleOAuthCallback)
+}
diff --git a/cmd/picoclaw-launcher/internal/server/server_test.go b/cmd/picoclaw-launcher/internal/server/server_test.go
new file mode 100644
index 000000000..c87e93d8c
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/server_test.go
@@ -0,0 +1,247 @@
+package server
+
+import (
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+// ── Config API tests ─────────────────────────────────────────────
+
+func setupConfigMux(t *testing.T, cfg *config.Config) (*http.ServeMux, string) {
+ t.Helper()
+ dir := t.TempDir()
+ path := filepath.Join(dir, "config.json")
+ data, err := json.MarshalIndent(cfg, "", " ")
+ if err != nil {
+ t.Fatalf("marshal config: %v", err)
+ }
+ if err := os.WriteFile(path, data, 0o600); err != nil {
+ t.Fatalf("write config: %v", err)
+ }
+
+ mux := http.NewServeMux()
+ RegisterConfigAPI(mux, path)
+ RegisterAuthAPI(mux, path)
+ return mux, path
+}
+
+func TestGetConfig(t *testing.T) {
+ cfg := &config.Config{
+ ModelList: []config.ModelConfig{
+ {ModelName: "gpt-4o", Model: "openai/gpt-4o"},
+ },
+ }
+ mux, path := setupConfigMux(t, cfg)
+
+ req := httptest.NewRequest("GET", "/api/config", nil)
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("GET /api/config: expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+
+ var resp struct {
+ Config config.Config `json:"config"`
+ Path string `json:"path"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("decode response: %v", err)
+ }
+
+ if resp.Path != path {
+ t.Errorf("expected path %q, got %q", path, resp.Path)
+ }
+ if len(resp.Config.ModelList) != 1 {
+ t.Errorf("expected 1 model, got %d", len(resp.Config.ModelList))
+ }
+}
+
+func TestGetConfig_MissingFile_ReturnsDefault(t *testing.T) {
+ mux := http.NewServeMux()
+ RegisterConfigAPI(mux, "/tmp/nonexistent-picoclaw-launcher-test/config.json")
+
+ req := httptest.NewRequest("GET", "/api/config", nil)
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ // LoadConfig returns a default empty config when file is missing
+ if w.Code != http.StatusOK {
+ t.Errorf("expected 200 for missing file (default config), got %d", w.Code)
+ }
+}
+
+func TestPutConfig(t *testing.T) {
+ cfg := &config.Config{}
+ mux, path := setupConfigMux(t, cfg)
+
+ newCfg := config.Config{
+ ModelList: []config.ModelConfig{
+ {ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
+ },
+ }
+ body, _ := json.Marshal(newCfg)
+
+ req := httptest.NewRequest("PUT", "/api/config", strings.NewReader(string(body)))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("PUT /api/config: expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+
+ saved, err := config.LoadConfig(path)
+ if err != nil {
+ t.Fatalf("load saved config: %v", err)
+ }
+ if len(saved.ModelList) != 1 {
+ t.Fatalf("expected 1 model saved, got %d", len(saved.ModelList))
+ }
+ if saved.ModelList[0].Model != "anthropic/claude-sonnet-4.6" {
+ t.Errorf("expected model anthropic/claude-sonnet-4.6, got %q", saved.ModelList[0].Model)
+ }
+}
+
+func TestPutConfig_InvalidJSON(t *testing.T) {
+ cfg := &config.Config{}
+ mux, _ := setupConfigMux(t, cfg)
+
+ req := httptest.NewRequest("PUT", "/api/config", strings.NewReader("{invalid"))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Errorf("expected 400 for invalid JSON, got %d", w.Code)
+ }
+}
+
+// ── Auth API tests ───────────────────────────────────────────────
+
+func TestAuthStatus(t *testing.T) {
+ cfg := &config.Config{}
+ mux, _ := setupConfigMux(t, cfg)
+
+ req := httptest.NewRequest("GET", "/api/auth/status", nil)
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("GET /api/auth/status: expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+
+ var resp struct {
+ Providers []providerStatus `json:"providers"`
+ PendingDevice map[string]any `json:"pending_device"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("decode response: %v", err)
+ }
+
+ // providers should be a non-nil list (could be empty)
+ if resp.Providers == nil {
+ t.Error("providers should not be nil")
+ }
+}
+
+func TestAuthLogin_UnsupportedProvider(t *testing.T) {
+ cfg := &config.Config{}
+ mux, _ := setupConfigMux(t, cfg)
+
+ body := `{"provider": "unsupported"}`
+ req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Errorf("expected 400 for unsupported provider, got %d", w.Code)
+ }
+}
+
+func TestAuthLogin_AnthropicNoToken(t *testing.T) {
+ cfg := &config.Config{}
+ mux, _ := setupConfigMux(t, cfg)
+
+ body := `{"provider": "anthropic"}`
+ req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Errorf("expected 400 for anthropic without token, got %d", w.Code)
+ }
+}
+
+func TestAuthLogin_InvalidBody(t *testing.T) {
+ cfg := &config.Config{}
+ mux, _ := setupConfigMux(t, cfg)
+
+ req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader("{bad"))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Errorf("expected 400 for invalid JSON body, got %d", w.Code)
+ }
+}
+
+func TestAuthLogout_InvalidBody(t *testing.T) {
+ cfg := &config.Config{}
+ mux, _ := setupConfigMux(t, cfg)
+
+ req := httptest.NewRequest("POST", "/api/auth/logout", strings.NewReader("{bad"))
+ req.Header.Set("Content-Type", "application/json")
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Errorf("expected 400 for invalid body, got %d", w.Code)
+ }
+}
+
+func TestOAuthCallback_InvalidState(t *testing.T) {
+ cfg := &config.Config{}
+ mux, _ := setupConfigMux(t, cfg)
+
+ req := httptest.NewRequest("GET", "/auth/callback?state=invalid&code=test", nil)
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Errorf("expected 400 for invalid state, got %d", w.Code)
+ }
+}
+
+// ── Utility tests ────────────────────────────────────────────────
+
+func TestDefaultConfigPath(t *testing.T) {
+ path := DefaultConfigPath()
+ if path == "" {
+ t.Error("defaultConfigPath should not return empty")
+ }
+ if !strings.HasSuffix(path, filepath.Join(".picoclaw", "config.json")) {
+ t.Errorf("expected path ending with .picoclaw/config.json, got %q", path)
+ }
+}
+
+func TestGetLocalIP(t *testing.T) {
+ // Just ensure it doesn't panic; IP may or may not be available
+ ip := GetLocalIP()
+ if ip != "" {
+ // If returned, should look like an IP
+ if !strings.Contains(ip, ".") {
+ t.Errorf("getLocalIP returned non-IPv4 looking string: %q", ip)
+ }
+ }
+}
diff --git a/cmd/picoclaw-launcher/internal/server/utils.go b/cmd/picoclaw-launcher/internal/server/utils.go
new file mode 100644
index 000000000..a46adbece
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/server/utils.go
@@ -0,0 +1,28 @@
+package server
+
+import (
+ "net"
+ "os"
+ "path/filepath"
+)
+
+func DefaultConfigPath() string {
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return "config.json"
+ }
+ return filepath.Join(home, ".picoclaw", "config.json")
+}
+
+func GetLocalIP() string {
+ addrs, err := net.InterfaceAddrs()
+ if err != nil {
+ return ""
+ }
+ for _, a := range addrs {
+ if ipnet, ok := a.(*net.IPNet); ok && !ipnet.IP.IsLoopback() && ipnet.IP.To4() != nil {
+ return ipnet.IP.String()
+ }
+ }
+ return ""
+}
diff --git a/cmd/picoclaw-launcher/internal/ui/index.html b/cmd/picoclaw-launcher/internal/ui/index.html
new file mode 100644
index 000000000..93893fd75
--- /dev/null
+++ b/cmd/picoclaw-launcher/internal/ui/index.html
@@ -0,0 +1,1999 @@
+
+
+
+
+
+
+
+ PicoClaw Config
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Models
+
Manage LLM model configurations. Models without an API key are grayed out. Only available models can be set as primary.
+
+
+
+
+
+
+
+
Provider Authentication
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Gateway Logs
+
Real-time output from the gateway process.
+
+
+
No logs available. Start the gateway to see output here.
+
+
+
+
+
+
Raw JSON
+
Directly edit the configuration file.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
$1")
-
- text = regexp.MustCompile(`^[-*]\s+`).ReplaceAllString(text, "• ")
-
- for i, code := range inlineCodes.codes {
- escaped := escapeHTML(code)
- text = strings.ReplaceAll(text, fmt.Sprintf("\x00IC%d\x00", i), fmt.Sprintf("%s", escaped))
- }
-
- for i, code := range codeBlocks.codes {
- escaped := escapeHTML(code)
- text = strings.ReplaceAll(
- text,
- fmt.Sprintf("\x00CB%d\x00", i),
- fmt.Sprintf("%s
", escaped),
- )
- }
-
- return text
-}
-
-type codeBlockMatch struct {
- text string
- codes []string
-}
-
-func extractCodeBlocks(text string) codeBlockMatch {
- re := regexp.MustCompile("```[\\w]*\\n?([\\s\\S]*?)```")
- matches := re.FindAllStringSubmatch(text, -1)
-
- codes := make([]string, 0, len(matches))
- for _, match := range matches {
- codes = append(codes, match[1])
- }
-
- i := 0
- text = re.ReplaceAllStringFunc(text, func(m string) string {
- placeholder := fmt.Sprintf("\x00CB%d\x00", i)
- i++
- return placeholder
- })
-
- return codeBlockMatch{text: text, codes: codes}
-}
-
-type inlineCodeMatch struct {
- text string
- codes []string
-}
-
-func extractInlineCodes(text string) inlineCodeMatch {
- re := regexp.MustCompile("`([^`]+)`")
- matches := re.FindAllStringSubmatch(text, -1)
-
- codes := make([]string, 0, len(matches))
- for _, match := range matches {
- codes = append(codes, match[1])
- }
-
- i := 0
- text = re.ReplaceAllStringFunc(text, func(m string) string {
- placeholder := fmt.Sprintf("\x00IC%d\x00", i)
- i++
- return placeholder
- })
-
- return inlineCodeMatch{text: text, codes: codes}
-}
-
-func escapeHTML(text string) string {
- text = strings.ReplaceAll(text, "&", "&")
- text = strings.ReplaceAll(text, "<", "<")
- text = strings.ReplaceAll(text, ">", ">")
- return text
-}
diff --git a/pkg/channels/telegram/init.go b/pkg/channels/telegram/init.go
new file mode 100644
index 000000000..ac87bb805
--- /dev/null
+++ b/pkg/channels/telegram/init.go
@@ -0,0 +1,13 @@
+package telegram
+
+import (
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/channels"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+ channels.RegisterFactory("telegram", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+ return NewTelegramChannel(cfg, b)
+ })
+}
diff --git a/pkg/channels/telegram/telegram.go b/pkg/channels/telegram/telegram.go
new file mode 100644
index 000000000..f328f32b8
--- /dev/null
+++ b/pkg/channels/telegram/telegram.go
@@ -0,0 +1,769 @@
+package telegram
+
+import (
+ "context"
+ "fmt"
+ "net/http"
+ "net/url"
+ "os"
+ "regexp"
+ "slices"
+ "strconv"
+ "strings"
+ "time"
+
+ "github.com/mymmrac/telego"
+ th "github.com/mymmrac/telego/telegohandler"
+ tu "github.com/mymmrac/telego/telegoutil"
+
+ "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"
+ "github.com/sipeed/picoclaw/pkg/media"
+ "github.com/sipeed/picoclaw/pkg/utils"
+)
+
+var (
+ reHeading = regexp.MustCompile(`^#{1,6}\s+(.+)$`)
+ reBlockquote = regexp.MustCompile(`^>\s*(.*)$`)
+ reLink = regexp.MustCompile(`\[([^\]]+)\]\(([^)]+)\)`)
+ reBoldStar = regexp.MustCompile(`\*\*(.+?)\*\*`)
+ reBoldUnder = regexp.MustCompile(`__(.+?)__`)
+ reItalic = regexp.MustCompile(`_([^_]+)_`)
+ reStrike = regexp.MustCompile(`~~(.+?)~~`)
+ reListItem = regexp.MustCompile(`^[-*]\s+`)
+ reCodeBlock = regexp.MustCompile("```[\\w]*\\n?([\\s\\S]*?)```")
+ reInlineCode = regexp.MustCompile("`([^`]+)`")
+)
+
+type TelegramChannel struct {
+ *channels.BaseChannel
+ bot *telego.Bot
+ bh *th.BotHandler
+ commands TelegramCommander
+ config *config.Config
+ chatIDs map[string]int64
+ ctx context.Context
+ cancel context.CancelFunc
+}
+
+func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
+ var opts []telego.BotOption
+ telegramCfg := cfg.Channels.Telegram
+
+ if telegramCfg.Proxy != "" {
+ proxyURL, parseErr := url.Parse(telegramCfg.Proxy)
+ if parseErr != nil {
+ return nil, fmt.Errorf("invalid proxy URL %q: %w", telegramCfg.Proxy, parseErr)
+ }
+ opts = append(opts, telego.WithHTTPClient(&http.Client{
+ Transport: &http.Transport{
+ Proxy: http.ProxyURL(proxyURL),
+ },
+ }))
+ } else if os.Getenv("HTTP_PROXY") != "" || os.Getenv("HTTPS_PROXY") != "" {
+ // Use environment proxy if configured
+ opts = append(opts, telego.WithHTTPClient(&http.Client{
+ Transport: &http.Transport{
+ Proxy: http.ProxyFromEnvironment,
+ },
+ }))
+ }
+
+ if baseURL := strings.TrimRight(strings.TrimSpace(telegramCfg.BaseURL), "/"); baseURL != "" {
+ opts = append(opts, telego.WithAPIServer(baseURL))
+ }
+
+ bot, err := telego.NewBot(telegramCfg.Token, opts...)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create telegram bot: %w", err)
+ }
+
+ base := channels.NewBaseChannel(
+ "telegram",
+ telegramCfg,
+ bus,
+ telegramCfg.AllowFrom,
+ channels.WithMaxMessageLength(4096),
+ channels.WithGroupTrigger(telegramCfg.GroupTrigger),
+ channels.WithReasoningChannelID(telegramCfg.ReasoningChannelID),
+ )
+
+ return &TelegramChannel{
+ BaseChannel: base,
+ commands: NewTelegramCommands(bot, cfg),
+ bot: bot,
+ config: cfg,
+ chatIDs: make(map[string]int64),
+ }, nil
+}
+
+func (c *TelegramChannel) Start(ctx context.Context) error {
+ logger.InfoC("telegram", "Starting Telegram bot (polling mode)...")
+
+ c.ctx, c.cancel = context.WithCancel(ctx)
+
+ if err := c.initBotCommands(c.ctx); err != nil {
+ logger.WarnCF("telegram", "Failed to initialize bot commands", map[string]any{
+ "error": err.Error(),
+ })
+ }
+
+ updates, err := c.bot.UpdatesViaLongPolling(c.ctx, &telego.GetUpdatesParams{
+ Timeout: 30,
+ })
+ if err != nil {
+ c.cancel()
+ return fmt.Errorf("failed to start long polling: %w", err)
+ }
+
+ bh, err := th.NewBotHandler(c.bot, updates)
+ if err != nil {
+ c.cancel()
+ return fmt.Errorf("failed to create bot handler: %w", err)
+ }
+ c.bh = bh
+
+ bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
+ return c.commands.Start(ctx, message)
+ }, th.CommandEqual("start"))
+ bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
+ return c.commands.Help(ctx, message)
+ }, th.CommandEqual("help"))
+
+ bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
+ return c.commands.Show(ctx, message)
+ }, th.CommandEqual("show"))
+
+ bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
+ return c.commands.List(ctx, message)
+ }, th.CommandEqual("list"))
+
+ bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
+ return c.handleMessage(ctx, &message)
+ }, th.AnyMessage())
+
+ c.SetRunning(true)
+ logger.InfoCF("telegram", "Telegram bot connected", map[string]any{
+ "username": c.bot.Username(),
+ })
+
+ go func() {
+ if err = bh.Start(); err != nil {
+ logger.ErrorCF("telegram", "Bot handler failed", map[string]any{
+ "error": err.Error(),
+ })
+ }
+ }()
+
+ return nil
+}
+
+func (c *TelegramChannel) Stop(ctx context.Context) error {
+ logger.InfoC("telegram", "Stopping Telegram bot...")
+ c.SetRunning(false)
+
+ // Stop the bot handler
+ if c.bh != nil {
+ _ = c.bh.StopWithContext(ctx)
+ }
+
+ // Cancel our context (stops long polling)
+ if c.cancel != nil {
+ c.cancel()
+ }
+
+ return nil
+}
+
+func (c *TelegramChannel) initBotCommands(ctx context.Context) error {
+ currentCommands, err := c.bot.GetMyCommands(ctx, &telego.GetMyCommandsParams{
+ Scope: tu.ScopeDefault(),
+ })
+ if err != nil {
+ return fmt.Errorf("get commands: %w", err)
+ }
+
+ commands := []telego.BotCommand{
+ {
+ Command: "start",
+ Description: "Start the bot",
+ },
+ {
+ Command: "help",
+ Description: "Show a help message",
+ },
+ {
+ Command: "show",
+ Description: "Show current configuration",
+ },
+ {
+ Command: "list",
+ Description: "List available options",
+ },
+ }
+
+ // Setting commands on each start will hit the rate limit very quickly, that's why we check if an update is needed
+ if !slices.Equal(currentCommands, commands) {
+ logger.InfoC("telegram", "Updating bot commands")
+
+ err = c.bot.SetMyCommands(ctx, &telego.SetMyCommandsParams{
+ Commands: commands,
+ Scope: tu.ScopeDefault(),
+ })
+ if err != nil {
+ return fmt.Errorf("set commands: %w", err)
+ }
+ } else {
+ logger.DebugC("telegram", "Bot commands are up to date")
+ }
+
+ return nil
+}
+
+func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+ if !c.IsRunning() {
+ return channels.ErrNotRunning
+ }
+
+ chatID, err := parseChatID(msg.ChatID)
+ if err != nil {
+ return fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed)
+ }
+
+ htmlContent := markdownToTelegramHTML(msg.Content)
+
+ // Typing/placeholder handled by Manager.preSend — just send the message
+ tgMsg := tu.Message(tu.ID(chatID), htmlContent)
+ tgMsg.ParseMode = telego.ModeHTML
+
+ if _, err = c.bot.SendMessage(ctx, tgMsg); err != nil {
+ logger.ErrorCF("telegram", "HTML parse failed, falling back to plain text", map[string]any{
+ "error": err.Error(),
+ })
+ tgMsg.ParseMode = ""
+ if _, err = c.bot.SendMessage(ctx, tgMsg); err != nil {
+ return fmt.Errorf("telegram send: %w", channels.ErrTemporary)
+ }
+ }
+
+ return nil
+}
+
+// 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.
+func (c *TelegramChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+ cid, err := parseChatID(chatID)
+ if err != nil {
+ return func() {}, err
+ }
+
+ // Send the first typing action immediately
+ _ = c.bot.SendChatAction(ctx, tu.ChatAction(tu.ID(cid), telego.ChatActionTyping))
+
+ typingCtx, cancel := context.WithCancel(ctx)
+ go func() {
+ ticker := time.NewTicker(4 * time.Second)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-typingCtx.Done():
+ return
+ case <-ticker.C:
+ _ = c.bot.SendChatAction(typingCtx, tu.ChatAction(tu.ID(cid), telego.ChatActionTyping))
+ }
+ }
+ }()
+
+ return cancel, nil
+}
+
+// EditMessage implements channels.MessageEditor.
+func (c *TelegramChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error {
+ cid, err := parseChatID(chatID)
+ if err != nil {
+ return err
+ }
+ mid, err := strconv.Atoi(messageID)
+ if err != nil {
+ return err
+ }
+ htmlContent := markdownToTelegramHTML(content)
+ editMsg := tu.EditMessageText(tu.ID(cid), mid, htmlContent)
+ editMsg.ParseMode = telego.ModeHTML
+ _, err = c.bot.EditMessageText(ctx, editMsg)
+ return err
+}
+
+// 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).
+func (c *TelegramChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+ phCfg := c.config.Channels.Telegram.Placeholder
+ if !phCfg.Enabled {
+ return "", nil
+ }
+
+ text := phCfg.Text
+ if text == "" {
+ text = "Thinking... 💭"
+ }
+
+ cid, err := parseChatID(chatID)
+ if err != nil {
+ return "", err
+ }
+
+ pMsg, err := c.bot.SendMessage(ctx, tu.Message(tu.ID(cid), text))
+ if err != nil {
+ return "", err
+ }
+
+ return fmt.Sprintf("%d", pMsg.MessageID), nil
+}
+
+// SendMedia implements the channels.MediaSender interface.
+func (c *TelegramChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+ if !c.IsRunning() {
+ return channels.ErrNotRunning
+ }
+
+ chatID, err := parseChatID(msg.ChatID)
+ if err != nil {
+ return fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed)
+ }
+
+ store := c.GetMediaStore()
+ if store == nil {
+ return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+ }
+
+ for _, part := range msg.Parts {
+ localPath, err := store.Resolve(part.Ref)
+ if err != nil {
+ logger.ErrorCF("telegram", "Failed to resolve media ref", map[string]any{
+ "ref": part.Ref,
+ "error": err.Error(),
+ })
+ continue
+ }
+
+ file, err := os.Open(localPath)
+ if err != nil {
+ logger.ErrorCF("telegram", "Failed to open media file", map[string]any{
+ "path": localPath,
+ "error": err.Error(),
+ })
+ continue
+ }
+
+ switch part.Type {
+ case "image":
+ params := &telego.SendPhotoParams{
+ ChatID: tu.ID(chatID),
+ Photo: telego.InputFile{File: file},
+ Caption: part.Caption,
+ }
+ _, err = c.bot.SendPhoto(ctx, params)
+ case "audio":
+ params := &telego.SendAudioParams{
+ ChatID: tu.ID(chatID),
+ Audio: telego.InputFile{File: file},
+ Caption: part.Caption,
+ }
+ _, err = c.bot.SendAudio(ctx, params)
+ case "video":
+ params := &telego.SendVideoParams{
+ ChatID: tu.ID(chatID),
+ Video: telego.InputFile{File: file},
+ Caption: part.Caption,
+ }
+ _, err = c.bot.SendVideo(ctx, params)
+ default: // "file" or unknown types
+ params := &telego.SendDocumentParams{
+ ChatID: tu.ID(chatID),
+ Document: telego.InputFile{File: file},
+ Caption: part.Caption,
+ }
+ _, err = c.bot.SendDocument(ctx, params)
+ }
+
+ file.Close()
+
+ if err != nil {
+ logger.ErrorCF("telegram", "Failed to send media", map[string]any{
+ "type": part.Type,
+ "error": err.Error(),
+ })
+ return fmt.Errorf("telegram send media: %w", channels.ErrTemporary)
+ }
+ }
+
+ return nil
+}
+
+func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Message) error {
+ if message == nil {
+ return fmt.Errorf("message is nil")
+ }
+
+ user := message.From
+ if user == nil {
+ return fmt.Errorf("message sender (user) is nil")
+ }
+
+ platformID := fmt.Sprintf("%d", user.ID)
+ sender := bus.SenderInfo{
+ Platform: "telegram",
+ PlatformID: platformID,
+ CanonicalID: identity.BuildCanonicalID("telegram", platformID),
+ Username: user.Username,
+ DisplayName: user.FirstName,
+ }
+
+ // check allowlist to avoid downloading attachments for rejected users
+ if !c.IsAllowedSender(sender) {
+ logger.DebugCF("telegram", "Message rejected by allowlist", map[string]any{
+ "user_id": platformID,
+ })
+ return nil
+ }
+
+ chatID := message.Chat.ID
+ c.chatIDs[platformID] = chatID
+
+ content := ""
+ mediaPaths := []string{}
+
+ chatIDStr := fmt.Sprintf("%d", chatID)
+ messageIDStr := fmt.Sprintf("%d", message.MessageID)
+ scope := channels.BuildMediaScope("telegram", chatIDStr, messageIDStr)
+
+ // Helper to register a local file with the media store
+ storeMedia := func(localPath, filename string) string {
+ if store := c.GetMediaStore(); store != nil {
+ ref, err := store.Store(localPath, media.MediaMeta{
+ Filename: filename,
+ Source: "telegram",
+ }, scope)
+ if err == nil {
+ return ref
+ }
+ }
+ return localPath // fallback: use raw path
+ }
+
+ if message.Text != "" {
+ content += message.Text
+ }
+
+ if message.Caption != "" {
+ if content != "" {
+ content += "\n"
+ }
+ content += message.Caption
+ }
+
+ if len(message.Photo) > 0 {
+ photo := message.Photo[len(message.Photo)-1]
+ photoPath := c.downloadPhoto(ctx, photo.FileID)
+ if photoPath != "" {
+ mediaPaths = append(mediaPaths, storeMedia(photoPath, "photo.jpg"))
+ if content != "" {
+ content += "\n"
+ }
+ content += "[image: photo]"
+ }
+ }
+
+ if message.Voice != nil {
+ voicePath := c.downloadFile(ctx, message.Voice.FileID, ".ogg")
+ if voicePath != "" {
+ mediaPaths = append(mediaPaths, storeMedia(voicePath, "voice.ogg"))
+
+ if content != "" {
+ content += "\n"
+ }
+ content += "[voice]"
+ }
+ }
+
+ if message.Audio != nil {
+ audioPath := c.downloadFile(ctx, message.Audio.FileID, ".mp3")
+ if audioPath != "" {
+ mediaPaths = append(mediaPaths, storeMedia(audioPath, "audio.mp3"))
+ if content != "" {
+ content += "\n"
+ }
+ content += "[audio]"
+ }
+ }
+
+ if message.Document != nil {
+ docPath := c.downloadFile(ctx, message.Document.FileID, "")
+ if docPath != "" {
+ mediaPaths = append(mediaPaths, storeMedia(docPath, "document"))
+ if content != "" {
+ content += "\n"
+ }
+ content += "[file]"
+ }
+ }
+
+ if content == "" {
+ content = "[empty message]"
+ }
+
+ // In group chats, apply unified group trigger filtering
+ if message.Chat.Type != "private" {
+ isMentioned := c.isBotMentioned(message)
+ if isMentioned {
+ content = c.stripBotMention(content)
+ }
+ respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
+ if !respond {
+ return nil
+ }
+ content = cleaned
+ }
+
+ logger.DebugCF("telegram", "Received message", map[string]any{
+ "sender_id": sender.CanonicalID,
+ "chat_id": fmt.Sprintf("%d", chatID),
+ "preview": utils.Truncate(content, 50),
+ })
+
+ // Placeholder is now auto-triggered by BaseChannel.HandleMessage via PlaceholderCapable
+
+ peerKind := "direct"
+ peerID := fmt.Sprintf("%d", user.ID)
+ if message.Chat.Type != "private" {
+ peerKind = "group"
+ peerID = fmt.Sprintf("%d", chatID)
+ }
+
+ peer := bus.Peer{Kind: peerKind, ID: peerID}
+ messageID := fmt.Sprintf("%d", message.MessageID)
+
+ metadata := map[string]string{
+ "user_id": fmt.Sprintf("%d", user.ID),
+ "username": user.Username,
+ "first_name": user.FirstName,
+ "is_group": fmt.Sprintf("%t", message.Chat.Type != "private"),
+ }
+
+ c.HandleMessage(c.ctx,
+ peer,
+ messageID,
+ platformID,
+ fmt.Sprintf("%d", chatID),
+ content,
+ mediaPaths,
+ metadata,
+ sender,
+ )
+ return nil
+}
+
+func (c *TelegramChannel) downloadPhoto(ctx context.Context, fileID string) string {
+ file, err := c.bot.GetFile(ctx, &telego.GetFileParams{FileID: fileID})
+ if err != nil {
+ logger.ErrorCF("telegram", "Failed to get photo file", map[string]any{
+ "error": err.Error(),
+ })
+ return ""
+ }
+
+ return c.downloadFileWithInfo(file, ".jpg")
+}
+
+func (c *TelegramChannel) downloadFileWithInfo(file *telego.File, ext string) string {
+ if file.FilePath == "" {
+ return ""
+ }
+
+ url := c.bot.FileDownloadURL(file.FilePath)
+ logger.DebugCF("telegram", "File URL", map[string]any{"url": url})
+
+ // Use FilePath as filename for better identification
+ filename := file.FilePath + ext
+ return utils.DownloadFile(url, filename, utils.DownloadOptions{
+ LoggerPrefix: "telegram",
+ })
+}
+
+func (c *TelegramChannel) downloadFile(ctx context.Context, fileID, ext string) string {
+ file, err := c.bot.GetFile(ctx, &telego.GetFileParams{FileID: fileID})
+ if err != nil {
+ logger.ErrorCF("telegram", "Failed to get file", map[string]any{
+ "error": err.Error(),
+ })
+ return ""
+ }
+
+ return c.downloadFileWithInfo(file, ext)
+}
+
+func parseChatID(chatIDStr string) (int64, error) {
+ var id int64
+ _, err := fmt.Sscanf(chatIDStr, "%d", &id)
+ return id, err
+}
+
+func markdownToTelegramHTML(text string) string {
+ if text == "" {
+ return ""
+ }
+
+ codeBlocks := extractCodeBlocks(text)
+ text = codeBlocks.text
+
+ inlineCodes := extractInlineCodes(text)
+ text = inlineCodes.text
+
+ text = reHeading.ReplaceAllString(text, "$1")
+
+ text = reBlockquote.ReplaceAllString(text, "$1")
+
+ text = escapeHTML(text)
+
+ text = reLink.ReplaceAllString(text, `$1`)
+
+ text = reBoldStar.ReplaceAllString(text, "$1")
+
+ text = reBoldUnder.ReplaceAllString(text, "$1")
+
+ text = reItalic.ReplaceAllStringFunc(text, func(s string) string {
+ match := reItalic.FindStringSubmatch(s)
+ if len(match) < 2 {
+ return s
+ }
+ return "" + match[1] + ""
+ })
+
+ text = reStrike.ReplaceAllString(text, "$1")
+
+ text = reListItem.ReplaceAllString(text, "• ")
+
+ for i, code := range inlineCodes.codes {
+ escaped := escapeHTML(code)
+ text = strings.ReplaceAll(text, fmt.Sprintf("\x00IC%d\x00", i), fmt.Sprintf("%s", escaped))
+ }
+
+ for i, code := range codeBlocks.codes {
+ escaped := escapeHTML(code)
+ text = strings.ReplaceAll(
+ text,
+ fmt.Sprintf("\x00CB%d\x00", i),
+ fmt.Sprintf("%s
", escaped),
+ )
+ }
+
+ return text
+}
+
+type codeBlockMatch struct {
+ text string
+ codes []string
+}
+
+func extractCodeBlocks(text string) codeBlockMatch {
+ matches := reCodeBlock.FindAllStringSubmatch(text, -1)
+
+ codes := make([]string, 0, len(matches))
+ for _, match := range matches {
+ codes = append(codes, match[1])
+ }
+
+ i := 0
+ text = reCodeBlock.ReplaceAllStringFunc(text, func(m string) string {
+ placeholder := fmt.Sprintf("\x00CB%d\x00", i)
+ i++
+ return placeholder
+ })
+
+ return codeBlockMatch{text: text, codes: codes}
+}
+
+type inlineCodeMatch struct {
+ text string
+ codes []string
+}
+
+func extractInlineCodes(text string) inlineCodeMatch {
+ matches := reInlineCode.FindAllStringSubmatch(text, -1)
+
+ codes := make([]string, 0, len(matches))
+ for _, match := range matches {
+ codes = append(codes, match[1])
+ }
+
+ i := 0
+ text = reInlineCode.ReplaceAllStringFunc(text, func(m string) string {
+ placeholder := fmt.Sprintf("\x00IC%d\x00", i)
+ i++
+ return placeholder
+ })
+
+ return inlineCodeMatch{text: text, codes: codes}
+}
+
+func escapeHTML(text string) string {
+ text = strings.ReplaceAll(text, "&", "&")
+ text = strings.ReplaceAll(text, "<", "<")
+ text = strings.ReplaceAll(text, ">", ">")
+ return text
+}
+
+// isBotMentioned checks if the bot is mentioned in the message via entities.
+func (c *TelegramChannel) isBotMentioned(message *telego.Message) bool {
+ botUsername := c.bot.Username()
+ if botUsername == "" {
+ return false
+ }
+
+ entities := message.Entities
+ if entities == nil {
+ entities = message.CaptionEntities
+ }
+
+ for _, entity := range entities {
+ if entity.Type == "mention" {
+ // Extract the mention text from the message
+ text := message.Text
+ if text == "" {
+ text = message.Caption
+ }
+ runes := []rune(text)
+ end := entity.Offset + entity.Length
+ if end <= len(runes) {
+ mention := string(runes[entity.Offset:end])
+ if strings.EqualFold(mention, "@"+botUsername) {
+ return true
+ }
+ }
+ }
+ if entity.Type == "text_mention" && entity.User != nil {
+ if entity.User.Username == botUsername {
+ return true
+ }
+ }
+ }
+ return false
+}
+
+// stripBotMention removes the @bot mention from the content.
+func (c *TelegramChannel) stripBotMention(content string) string {
+ botUsername := c.bot.Username()
+ if botUsername == "" {
+ return content
+ }
+ // Case-insensitive replacement
+ re := regexp.MustCompile(`(?i)@` + regexp.QuoteMeta(botUsername))
+ content = re.ReplaceAllString(content, "")
+ return strings.TrimSpace(content)
+}
diff --git a/pkg/channels/telegram_commands.go b/pkg/channels/telegram/telegram_commands.go
similarity index 98%
rename from pkg/channels/telegram_commands.go
rename to pkg/channels/telegram/telegram_commands.go
index f28434f46..496fc5e4f 100644
--- a/pkg/channels/telegram_commands.go
+++ b/pkg/channels/telegram/telegram_commands.go
@@ -1,4 +1,4 @@
-package channels
+package telegram
import (
"context"
@@ -119,7 +119,7 @@ func (c *cmd) List(ctx context.Context, message telego.Message) error {
if provider == "" {
provider = "configured default"
}
- response = fmt.Sprintf("Configured Model: %s\nProvider: %s\n\nTo change models, update config.yaml",
+ response = fmt.Sprintf("Configured Model: %s\nProvider: %s\n\nTo change models, update config.json",
c.config.Agents.Defaults.GetModelName(), provider)
case "channels":
diff --git a/pkg/channels/webhook.go b/pkg/channels/webhook.go
new file mode 100644
index 000000000..3cf27baf6
--- /dev/null
+++ b/pkg/channels/webhook.go
@@ -0,0 +1,20 @@
+package channels
+
+import "net/http"
+
+// WebhookHandler is an optional interface for channels that receive messages
+// via HTTP webhooks. Manager discovers channels implementing this interface
+// and registers them on the shared HTTP server.
+type WebhookHandler interface {
+ // WebhookPath returns the path to mount this handler on the shared server.
+ // Examples: "/webhook/line", "/webhook/wecom"
+ WebhookPath() string
+ http.Handler // ServeHTTP(w http.ResponseWriter, r *http.Request)
+}
+
+// HealthChecker is an optional interface for channels that expose
+// a health check endpoint on the shared HTTP server.
+type HealthChecker interface {
+ HealthPath() string
+ HealthHandler(w http.ResponseWriter, r *http.Request)
+}
diff --git a/pkg/channels/wecom/aibot.go b/pkg/channels/wecom/aibot.go
new file mode 100644
index 000000000..6c5aca40b
--- /dev/null
+++ b/pkg/channels/wecom/aibot.go
@@ -0,0 +1,1014 @@
+package wecom
+
+import (
+ "bytes"
+ "context"
+ "crypto/rand"
+ "encoding/base64"
+ "encoding/json"
+ "fmt"
+ "io"
+ "math/big"
+ "net/http"
+ "strings"
+ "sync"
+ "time"
+
+ "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"
+ "github.com/sipeed/picoclaw/pkg/utils"
+)
+
+// WeComAIBotChannel implements the Channel interface for WeCom AI Bot (企业微信智能机器人)
+type WeComAIBotChannel struct {
+ *channels.BaseChannel
+ config config.WeComAIBotConfig
+ ctx context.Context
+ cancel context.CancelFunc
+ streamTasks map[string]*streamTask // streamID -> task (for poll lookups)
+ chatTasks map[string][]*streamTask // chatID -> in-flight tasks queue (FIFO)
+ taskMu sync.RWMutex
+}
+
+// streamTask represents a streaming task for AI Bot.
+//
+// Mutable fields (Finished, StreamClosed, StreamClosedAt) must be read/written
+// while holding WeComAIBotChannel.taskMu. Immutable fields (StreamID, ChatID,
+// ResponseURL, Question, CreatedTime, Deadline, answerCh, ctx, cancel) are set
+// once at creation and never modified, so they are safe to read without a lock.
+type streamTask struct {
+ // immutable after creation
+ StreamID string
+ ChatID string // used by Send() to find this task
+ ResponseURL string // temporary URL for proactive reply (valid 1 hour, use once)
+ Question string
+ CreatedTime time.Time
+ Deadline time.Time // ~30s, we close the stream here and switch to response_url
+ answerCh chan string // receives agent reply from Send()
+ ctx context.Context // canceled when task is removed; used to interrupt the agent goroutine
+ cancel context.CancelFunc // call on task removal to cancel ctx
+
+ // mutable — guarded by WeComAIBotChannel.taskMu
+ StreamClosed bool // stream returned finish:true; waiting for agent to reply via response_url
+ StreamClosedAt time.Time // set when StreamClosed becomes true; used for accelerated cleanup
+ Finished bool // fully done
+}
+
+// WeComAIBotMessage represents the decrypted JSON message from WeCom AI Bot
+// Ref: https://developer.work.weixin.qq.com/document/path/100719
+type WeComAIBotMessage struct {
+ MsgID string `json:"msgid"`
+ AIBotID string `json:"aibotid"`
+ ChatID string `json:"chatid"` // only for group chat
+ ChatType string `json:"chattype"` // "single" or "group"
+ From struct {
+ UserID string `json:"userid"`
+ } `json:"from"`
+ ResponseURL string `json:"response_url"` // temporary URL for proactive reply
+ MsgType string `json:"msgtype"`
+ // text message
+ Text *struct {
+ Content string `json:"content"`
+ } `json:"text,omitempty"`
+ // stream polling refresh
+ Stream *struct {
+ ID string `json:"id"`
+ } `json:"stream,omitempty"`
+ // image message
+ Image *struct {
+ URL string `json:"url"`
+ } `json:"image,omitempty"`
+ // mixed message (text + image)
+ Mixed *struct {
+ MsgItem []struct {
+ MsgType string `json:"msgtype"`
+ Text *struct {
+ Content string `json:"content"`
+ } `json:"text,omitempty"`
+ Image *struct {
+ URL string `json:"url"`
+ } `json:"image,omitempty"`
+ } `json:"msg_item"`
+ } `json:"mixed,omitempty"`
+ // event field
+ Event *struct {
+ EventType string `json:"eventtype"`
+ } `json:"event,omitempty"`
+}
+
+// WeComAIBotMsgItemImage holds the image payload inside a stream message item.
+type WeComAIBotMsgItemImage struct {
+ Base64 string `json:"base64"`
+ MD5 string `json:"md5"`
+}
+
+// WeComAIBotMsgItem is a single item inside a stream's msg_item list.
+type WeComAIBotMsgItem struct {
+ MsgType string `json:"msgtype"`
+ Image *WeComAIBotMsgItemImage `json:"image,omitempty"`
+}
+
+// WeComAIBotStreamInfo represents the detailed stream content in streaming responses.
+type WeComAIBotStreamInfo struct {
+ ID string `json:"id"`
+ Finish bool `json:"finish"`
+ Content string `json:"content,omitempty"`
+ MsgItem []WeComAIBotMsgItem `json:"msg_item,omitempty"`
+}
+
+// WeComAIBotStreamResponse represents the streaming response format
+type WeComAIBotStreamResponse struct {
+ MsgType string `json:"msgtype"`
+ Stream WeComAIBotStreamInfo `json:"stream"`
+}
+
+// WeComAIBotEncryptedResponse represents the encrypted response wrapper
+// Fields match WXBizJsonMsgCrypt.generate() in Python SDK
+type WeComAIBotEncryptedResponse struct {
+ Encrypt string `json:"encrypt"`
+ MsgSignature string `json:"msgsignature"`
+ Timestamp string `json:"timestamp"`
+ Nonce string `json:"nonce"`
+}
+
+// NewWeComAIBotChannel creates a new WeCom AI Bot channel instance
+func NewWeComAIBotChannel(
+ cfg config.WeComAIBotConfig,
+ messageBus *bus.MessageBus,
+) (*WeComAIBotChannel, error) {
+ if cfg.Token == "" || cfg.EncodingAESKey == "" {
+ return nil, fmt.Errorf("token and encoding_aes_key are required for WeCom AI Bot")
+ }
+
+ base := channels.NewBaseChannel("wecom_aibot", cfg, messageBus, cfg.AllowFrom,
+ channels.WithMaxMessageLength(2048),
+ channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+ )
+
+ return &WeComAIBotChannel{
+ BaseChannel: base,
+ config: cfg,
+ streamTasks: make(map[string]*streamTask),
+ chatTasks: make(map[string][]*streamTask),
+ }, nil
+}
+
+// Name returns the channel name
+func (c *WeComAIBotChannel) Name() string {
+ return "wecom_aibot"
+}
+
+// Start initializes the WeCom AI Bot channel
+func (c *WeComAIBotChannel) Start(ctx context.Context) error {
+ logger.InfoC("wecom_aibot", "Starting WeCom AI Bot channel...")
+
+ c.ctx, c.cancel = context.WithCancel(ctx)
+
+ // Start cleanup goroutine for old tasks
+ go c.cleanupLoop()
+
+ c.SetRunning(true)
+ logger.InfoC("wecom_aibot", "WeCom AI Bot channel started")
+
+ return nil
+}
+
+// Stop gracefully stops the WeCom AI Bot channel
+func (c *WeComAIBotChannel) Stop(ctx context.Context) error {
+ logger.InfoC("wecom_aibot", "Stopping WeCom AI Bot channel...")
+
+ if c.cancel != nil {
+ c.cancel()
+ }
+
+ c.SetRunning(false)
+ logger.InfoC("wecom_aibot", "WeCom AI Bot channel stopped")
+ return nil
+}
+
+// Send delivers the agent reply into the active streamTask for msg.ChatID.
+// It writes into the earliest unfinished task in the queue (FIFO per chatID).
+// If the stream has already closed (deadline passed), it posts directly to response_url.
+func (c *WeComAIBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+ if !c.IsRunning() {
+ return channels.ErrNotRunning
+ }
+ c.taskMu.Lock()
+ queue := c.chatTasks[msg.ChatID]
+ // Only compact Finished tasks at the head of the queue.
+ // Tasks that are Finished in the middle are NOT removed here: doing a full
+ // scan on every Send() call would be O(n) and is unnecessary given that
+ // removeTask() always splices the task out of the queue immediately.
+ // Any Finished task left stranded in the middle (e.g. due to an unexpected
+ // code path) will be collected by cleanupOldTasks.
+ for len(queue) > 0 && queue[0].Finished {
+ queue = queue[1:]
+ }
+ c.chatTasks[msg.ChatID] = queue
+ var task *streamTask
+ var streamClosed bool
+ var responseURL string
+ if len(queue) > 0 {
+ task = queue[0]
+ // Read mutable fields while holding c.taskMu to avoid data races.
+ streamClosed = task.StreamClosed
+ responseURL = task.ResponseURL
+ }
+ c.taskMu.Unlock()
+
+ if task == nil {
+ logger.DebugCF(
+ "wecom_aibot",
+ "Send: no active task for chat (may have timed out)",
+ map[string]any{
+ "chat_id": msg.ChatID,
+ },
+ )
+ return nil
+ }
+
+ if streamClosed {
+ // Stream already ended with a "please wait" notice; send the real reply via response_url.
+ // Note: task.StreamID and task.ChatID are immutable, safe to read without a lock.
+ logger.InfoCF("wecom_aibot", "Sending reply via response_url", map[string]any{
+ "stream_id": task.StreamID,
+ "chat_id": msg.ChatID,
+ })
+ if responseURL != "" {
+ if err := c.sendViaResponseURL(responseURL, msg.Content); err != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to send via response_url", map[string]any{
+ "error": err,
+ "stream_id": task.StreamID,
+ })
+ c.removeTask(task)
+ return fmt.Errorf("response_url delivery failed: %w", channels.ErrSendFailed)
+ }
+ } else {
+ logger.WarnCF("wecom_aibot", "Stream closed but no response_url available", map[string]any{
+ "stream_id": task.StreamID,
+ })
+ }
+ c.removeTask(task)
+ return nil
+ }
+
+ // Stream still open: deliver via answerCh for the next poll response.
+ select {
+ case task.answerCh <- msg.Content:
+ case <-task.ctx.Done():
+ // Task was canceled (cleanup removed it); silently drop the reply.
+ return nil
+ case <-ctx.Done():
+ return ctx.Err()
+ }
+ return nil
+}
+
+// WebhookPath returns the path for registering on the shared HTTP server
+func (c *WeComAIBotChannel) WebhookPath() string {
+ if c.config.WebhookPath == "" {
+ return "/webhook/wecom-aibot"
+ }
+ return c.config.WebhookPath
+}
+
+// ServeHTTP implements http.Handler for the shared HTTP server
+func (c *WeComAIBotChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+ c.handleWebhook(w, r)
+}
+
+// HealthPath returns the health check endpoint path
+func (c *WeComAIBotChannel) HealthPath() string {
+ return c.WebhookPath() + "/health"
+}
+
+// HealthHandler handles health check requests
+func (c *WeComAIBotChannel) HealthHandler(w http.ResponseWriter, r *http.Request) {
+ c.handleHealth(w, r)
+}
+
+// handleWebhook handles incoming webhook requests from WeCom AI Bot
+func (c *WeComAIBotChannel) handleWebhook(w http.ResponseWriter, r *http.Request) {
+ ctx := r.Context()
+
+ // Log all incoming requests for debugging
+ logger.DebugCF("wecom_aibot", "Received webhook request", map[string]any{
+ "method": r.Method,
+ "path": r.URL.Path,
+ "query": r.URL.RawQuery,
+ })
+
+ switch r.Method {
+ case http.MethodGet:
+ // URL verification
+ c.handleVerification(ctx, w, r)
+ case http.MethodPost:
+ // Message callback
+ c.handleMessageCallback(ctx, w, r)
+ default:
+ http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+ }
+}
+
+// handleVerification handles the URL verification request from WeCom
+func (c *WeComAIBotChannel) handleVerification(
+ ctx context.Context,
+ w http.ResponseWriter,
+ r *http.Request,
+) {
+ msgSignature := r.URL.Query().Get("msg_signature")
+ timestamp := r.URL.Query().Get("timestamp")
+ nonce := r.URL.Query().Get("nonce")
+ echostr := r.URL.Query().Get("echostr")
+
+ logger.DebugCF("wecom_aibot", "URL verification request", map[string]any{
+ "msg_signature": msgSignature,
+ "timestamp": timestamp,
+ "nonce": nonce,
+ })
+
+ // Verify signature
+ 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
+ }
+
+ // Decrypt echostr
+ // For WeCom AI Bot (智能机器人), receiveid should be empty string
+ decrypted, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
+ if err != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to decrypt echostr", map[string]any{
+ "error": err,
+ })
+ http.Error(w, "Decryption failed", http.StatusInternalServerError)
+ return
+ }
+
+ // Remove BOM and whitespace as per WeCom documentation
+ decrypted = strings.TrimPrefix(decrypted, "\ufeff")
+ decrypted = strings.TrimSpace(decrypted)
+
+ logger.InfoC("wecom_aibot", "URL verification successful")
+ w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+ w.WriteHeader(http.StatusOK)
+ w.Write([]byte(decrypted))
+}
+
+// handleMessageCallback handles incoming messages from WeCom AI Bot
+func (c *WeComAIBotChannel) handleMessageCallback(
+ ctx context.Context,
+ w http.ResponseWriter,
+ r *http.Request,
+) {
+ msgSignature := r.URL.Query().Get("msg_signature")
+ timestamp := r.URL.Query().Get("timestamp")
+ nonce := r.URL.Query().Get("nonce")
+
+ // Read request body (limit to 4 MB to prevent memory exhaustion)
+ const maxBodySize = 4 << 20 // 4 MB
+ body, err := io.ReadAll(io.LimitReader(r.Body, maxBodySize+1))
+ if err != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to read request body", map[string]any{
+ "error": err,
+ })
+ http.Error(w, "Failed to read body", http.StatusBadRequest)
+ return
+ }
+ if len(body) > maxBodySize {
+ http.Error(w, "Request body too large", http.StatusRequestEntityTooLarge)
+ return
+ }
+
+ // Parse JSON body to get encrypted message
+ // Format: {"encrypt": "base64_encrypted_string"}
+ var encryptedMsg struct {
+ Encrypt string `json:"encrypt"`
+ }
+ if unmarshalErr := json.Unmarshal(body, &encryptedMsg); unmarshalErr != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to parse JSON body", map[string]any{
+ "error": unmarshalErr,
+ "body": string(body),
+ })
+ http.Error(w, "Failed to parse JSON", http.StatusBadRequest)
+ return
+ }
+
+ // Verify signature
+ 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
+ }
+
+ // Decrypt message
+ // For WeCom AI Bot (智能机器人), receiveid is empty string
+ decrypted, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
+ if err != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to decrypt message", map[string]any{
+ "error": err,
+ })
+ http.Error(w, "Decryption failed", http.StatusInternalServerError)
+ return
+ }
+
+ // Parse decrypted JSON message
+ var msg WeComAIBotMessage
+ if unmarshalErr := json.Unmarshal([]byte(decrypted), &msg); unmarshalErr != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to parse decrypted JSON", map[string]any{
+ "error": unmarshalErr,
+ "decrypted": decrypted,
+ })
+ http.Error(w, "Failed to parse message", http.StatusInternalServerError)
+ return
+ }
+
+ logger.DebugCF("wecom_aibot", "Decrypted message", map[string]any{
+ "msgtype": msg.MsgType,
+ })
+
+ // Process the message and get streaming response
+ response := c.processMessage(ctx, msg, timestamp, nonce)
+
+ // Check if response is empty (e.g. due to unsupported message type)
+ if response == "" {
+ response = c.encryptEmptyResponse(timestamp, nonce)
+ }
+
+ // Return encrypted JSON response
+ w.Header().Set("Content-Type", "application/json; charset=utf-8")
+ w.WriteHeader(http.StatusOK)
+ w.Write([]byte(response))
+}
+
+// processMessage processes the received message and returns encrypted response
+func (c *WeComAIBotChannel) processMessage(
+ ctx context.Context,
+ msg WeComAIBotMessage,
+ timestamp, nonce string,
+) string {
+ logger.DebugCF("wecom_aibot", "Processing message", map[string]any{
+ "msgtype": msg.MsgType,
+ })
+
+ switch msg.MsgType {
+ case "text":
+ return c.handleTextMessage(ctx, msg, timestamp, nonce)
+ case "stream":
+ return c.handleStreamMessage(ctx, msg, timestamp, nonce)
+ case "image":
+ return c.handleImageMessage(ctx, msg, timestamp, nonce)
+ case "mixed":
+ return c.handleMixedMessage(ctx, msg, timestamp, nonce)
+ case "event":
+ return c.handleEventMessage(ctx, msg, timestamp, nonce)
+ default:
+ logger.WarnCF("wecom_aibot", "Unsupported message type", map[string]any{
+ "msgtype": msg.MsgType,
+ })
+ return c.encryptResponse("", timestamp, nonce, WeComAIBotStreamResponse{
+ MsgType: "stream",
+ Stream: WeComAIBotStreamInfo{
+ ID: c.generateStreamID(),
+ Finish: true,
+ Content: "Unsupported message type: " + msg.MsgType,
+ },
+ })
+ }
+}
+
+// handleTextMessage handles text messages by starting a new streaming task
+func (c *WeComAIBotChannel) handleTextMessage(
+ ctx context.Context,
+ msg WeComAIBotMessage,
+ timestamp, nonce string,
+) string {
+ if msg.Text == nil {
+ logger.ErrorC("wecom_aibot", "text message missing text field")
+ return c.encryptEmptyResponse(timestamp, nonce)
+ }
+
+ content := msg.Text.Content
+ userID := msg.From.UserID
+ if userID == "" {
+ userID = "unknown"
+ }
+
+ // chatID: group chat uses chatid, single chat uses userid
+ chatID := msg.ChatID
+ if chatID == "" {
+ chatID = userID
+ }
+
+ streamID := c.generateStreamID()
+
+ // WeCom stops sending stream-refresh callbacks after 6 minutes.
+ // Set a slightly shorter deadline so we can send a timeout notice before it gives up.
+ deadline := time.Now().Add(30 * time.Second)
+
+ // Each task gets its own context derived from the channel lifetime context.
+ // Canceling taskCancel interrupts the agent goroutine when the task is removed.
+ taskCtx, taskCancel := context.WithCancel(c.ctx)
+
+ task := &streamTask{
+ StreamID: streamID,
+ ChatID: chatID,
+ ResponseURL: msg.ResponseURL,
+ Question: content,
+ CreatedTime: time.Now(),
+ Deadline: deadline,
+ Finished: false,
+ answerCh: make(chan string, 1),
+ ctx: taskCtx,
+ cancel: taskCancel,
+ }
+
+ c.taskMu.Lock()
+ c.streamTasks[streamID] = task
+ c.chatTasks[chatID] = append(c.chatTasks[chatID], task)
+ c.taskMu.Unlock()
+
+ // Publish to agent asynchronously; agent will call Send() with reply.
+ // Use task.ctx (not c.ctx) so the agent goroutine is canceled when the task is removed.
+ go func() {
+ sender := bus.SenderInfo{
+ Platform: "wecom_aibot",
+ PlatformID: userID,
+ CanonicalID: identity.BuildCanonicalID("wecom_aibot", userID),
+ DisplayName: userID,
+ }
+ peerKind := "direct"
+ if msg.ChatType == "group" {
+ peerKind = "group"
+ }
+ peer := bus.Peer{Kind: peerKind, ID: chatID}
+ metadata := map[string]string{
+ "channel": "wecom_aibot",
+ "chat_type": msg.ChatType,
+ "msg_type": "text",
+ "msgid": msg.MsgID,
+ "aibotid": msg.AIBotID,
+ "stream_id": streamID,
+ "response_url": msg.ResponseURL,
+ }
+ c.HandleMessage(task.ctx, peer, msg.MsgID, userID, chatID,
+ content, nil, metadata, sender)
+ }()
+
+ // Return first streaming response immediately (finish=false, content empty)
+ return c.getStreamResponse(task, timestamp, nonce)
+}
+
+// handleStreamMessage handles stream polling requests
+func (c *WeComAIBotChannel) handleStreamMessage(
+ ctx context.Context,
+ msg WeComAIBotMessage,
+ timestamp, nonce string,
+) string {
+ if msg.Stream == nil {
+ logger.ErrorC("wecom_aibot", "Stream message missing stream field")
+ return c.encryptEmptyResponse(timestamp, nonce)
+ }
+
+ streamID := msg.Stream.ID
+
+ c.taskMu.RLock()
+ task, exists := c.streamTasks[streamID]
+ c.taskMu.RUnlock()
+
+ if !exists {
+ logger.DebugCF(
+ "wecom_aibot",
+ "Stream task not found (may be from previous session)",
+ map[string]any{
+ "stream_id": streamID,
+ },
+ )
+ return c.encryptResponse(streamID, timestamp, nonce, WeComAIBotStreamResponse{
+ MsgType: "stream",
+ Stream: WeComAIBotStreamInfo{
+ ID: streamID,
+ Finish: true,
+ Content: "Task not found or already finished. Please resend your message to start a new session.",
+ },
+ })
+ }
+
+ // Get next response
+ return c.getStreamResponse(task, timestamp, nonce)
+}
+
+// handleImageMessage handles image messages
+func (c *WeComAIBotChannel) handleImageMessage(
+ ctx context.Context,
+ msg WeComAIBotMessage,
+ timestamp, nonce string,
+) string {
+ logger.WarnC("wecom_aibot", "Image message type not yet fully implemented")
+ if msg.Image == nil {
+ logger.ErrorC("wecom_aibot", "Image message missing image field")
+ return c.encryptEmptyResponse(timestamp, nonce)
+ }
+
+ imageURL := msg.Image.URL
+
+ // For now, just acknowledge receipt without echoing the image
+ return c.encryptResponse("", timestamp, nonce, WeComAIBotStreamResponse{
+ MsgType: "stream",
+ Stream: WeComAIBotStreamInfo{
+ ID: c.generateStreamID(),
+ Finish: true,
+ Content: fmt.Sprintf(
+ "Image received (URL: %s), but image messages are not yet supported",
+ imageURL,
+ ),
+ },
+ })
+}
+
+// handleMixedMessage handles mixed (text + image) messages
+func (c *WeComAIBotChannel) handleMixedMessage(
+ ctx context.Context,
+ msg WeComAIBotMessage,
+ timestamp, nonce string,
+) string {
+ logger.WarnC("wecom_aibot", "Mixed message type not yet fully implemented")
+ return c.encryptResponse("", timestamp, nonce, WeComAIBotStreamResponse{
+ MsgType: "stream",
+ Stream: WeComAIBotStreamInfo{
+ ID: c.generateStreamID(),
+ Finish: true,
+ Content: "Mixed message type is not yet supported",
+ },
+ })
+}
+
+// handleEventMessage handles event messages
+func (c *WeComAIBotChannel) handleEventMessage(
+ ctx context.Context,
+ msg WeComAIBotMessage,
+ timestamp, nonce string,
+) string {
+ eventType := ""
+ if msg.Event != nil {
+ eventType = msg.Event.EventType
+ }
+ logger.DebugCF("wecom_aibot", "Received event", map[string]any{
+ "event_type": eventType,
+ })
+
+ // Send welcome message when user opens the chat window
+ if eventType == "enter_chat" && c.config.WelcomeMessage != "" {
+ streamID := c.generateStreamID()
+ return c.encryptResponse(streamID, timestamp, nonce, WeComAIBotStreamResponse{
+ MsgType: "stream",
+ Stream: WeComAIBotStreamInfo{
+ ID: streamID,
+ Finish: true,
+ Content: c.config.WelcomeMessage,
+ },
+ })
+ }
+
+ return c.encryptEmptyResponse(timestamp, nonce)
+}
+
+// getStreamResponse gets the next streaming response for a task.
+// - If agent replied: return finish=true with the real answer.
+// - If deadline passed: return finish=true with a "please wait" notice, keep task alive for response_url.
+// - Otherwise: return finish=false (empty), client will poll again.
+func (c *WeComAIBotChannel) getStreamResponse(task *streamTask, timestamp, nonce string) string {
+ var content string
+ var finish bool
+ var closeStreamOnly bool // close stream but do NOT remove task (response_url still pending)
+
+ select {
+ case answer := <-task.answerCh:
+ // Agent replied before deadline — normal finish.
+ content = answer
+ finish = true
+ 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."
+ finish = true
+ closeStreamOnly = true
+ logger.InfoCF(
+ "wecom_aibot",
+ "Stream deadline reached, switching to response_url mode",
+ map[string]any{
+ "stream_id": task.StreamID,
+ "chat_id": task.ChatID,
+ "response_url": task.ResponseURL != "",
+ },
+ )
+ }
+ // else: still waiting, return finish=false
+ }
+
+ if finish && !closeStreamOnly {
+ // Normal finish: remove from all maps.
+ c.removeTask(task)
+ } else if closeStreamOnly {
+ // Mark stream as closed and remove from streamTasks under a single lock
+ // to keep StreamClosed/StreamClosedAt consistent with map membership.
+ c.taskMu.Lock()
+ task.StreamClosed = true
+ task.StreamClosedAt = time.Now()
+ delete(c.streamTasks, task.StreamID)
+ c.taskMu.Unlock()
+ }
+
+ response := WeComAIBotStreamResponse{
+ MsgType: "stream",
+ Stream: WeComAIBotStreamInfo{
+ ID: task.StreamID,
+ Finish: finish,
+ Content: content,
+ },
+ }
+
+ return c.encryptResponse(task.StreamID, timestamp, nonce, response)
+}
+
+// removeTask removes a task from both streamTasks and chatTasks, marks it finished,
+// and cancels its context to interrupt the associated agent goroutine.
+func (c *WeComAIBotChannel) removeTask(task *streamTask) {
+ // Cancel first so the agent goroutine stops as soon as possible,
+ // before we acquire the write lock.
+ task.cancel()
+
+ c.taskMu.Lock()
+ task.Finished = true // written under c.taskMu, consistent with all readers
+ delete(c.streamTasks, task.StreamID)
+ queue := c.chatTasks[task.ChatID]
+ for i, t := range queue {
+ if t == task {
+ c.chatTasks[task.ChatID] = append(queue[:i], queue[i+1:]...)
+ break
+ }
+ }
+ if len(c.chatTasks[task.ChatID]) == 0 {
+ delete(c.chatTasks, task.ChatID)
+ }
+ c.taskMu.Unlock()
+}
+
+// sendViaResponseURL posts a markdown reply to the WeCom response_url.
+// response_url is valid for 1 hour and can only be used once per callback.
+// Returned errors are wrapped with channels.ErrRateLimit, channels.ErrTemporary,
+// or channels.ErrSendFailed so the manager can apply the right retry policy.
+func (c *WeComAIBotChannel) sendViaResponseURL(responseURL, content string) error {
+ payload := map[string]any{
+ "msgtype": "markdown",
+ "markdown": map[string]string{
+ "content": content,
+ },
+ }
+ body, err := json.Marshal(payload)
+ if err != nil {
+ return fmt.Errorf("failed to marshal payload: %w", err)
+ }
+
+ ctx, cancel := context.WithTimeout(c.ctx, 15*time.Second)
+ defer cancel()
+
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, responseURL, bytes.NewBuffer(body))
+ if err != nil {
+ return fmt.Errorf("failed to create request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/json; charset=utf-8")
+
+ client := &http.Client{Timeout: 15 * time.Second}
+ resp, err := client.Do(req)
+ if err != nil {
+ return fmt.Errorf("post to response_url failed: %w: %w", channels.ErrTemporary, err)
+ }
+ defer resp.Body.Close()
+
+ if resp.StatusCode == http.StatusOK {
+ return nil
+ }
+
+ respBody, _ := io.ReadAll(resp.Body)
+ switch {
+ case resp.StatusCode == http.StatusTooManyRequests:
+ return fmt.Errorf("response_url rate limited (%d): %s: %w",
+ resp.StatusCode, respBody, channels.ErrRateLimit)
+ case resp.StatusCode >= 500:
+ return fmt.Errorf("response_url server error (%d): %s: %w",
+ resp.StatusCode, respBody, channels.ErrTemporary)
+ default:
+ return fmt.Errorf("response_url returned %d: %s: %w",
+ resp.StatusCode, respBody, channels.ErrSendFailed)
+ }
+}
+
+// encryptResponse encrypts a streaming response
+func (c *WeComAIBotChannel) encryptResponse(
+ streamID, timestamp, nonce string,
+ response WeComAIBotStreamResponse,
+) string {
+ // Marshal response to JSON
+ plaintext, err := json.Marshal(response)
+ if err != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to marshal response", map[string]any{
+ "error": err,
+ })
+ return ""
+ }
+
+ logger.DebugCF("wecom_aibot", "Encrypting response", map[string]any{
+ "stream_id": streamID,
+ "finish": response.Stream.Finish,
+ "preview": utils.Truncate(response.Stream.Content, 100),
+ })
+
+ // Encrypt message
+ encrypted, err := c.encryptMessage(string(plaintext), "")
+ if err != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to encrypt message", map[string]any{
+ "error": err,
+ })
+ return ""
+ }
+
+ // Generate signature
+ signature := computeSignature(c.config.Token, timestamp, nonce, encrypted)
+
+ // Build encrypted response
+ encryptedResp := WeComAIBotEncryptedResponse{
+ Encrypt: encrypted,
+ MsgSignature: signature,
+ Timestamp: timestamp,
+ Nonce: nonce,
+ }
+
+ respJSON, err := json.Marshal(encryptedResp)
+ if err != nil {
+ logger.ErrorCF("wecom_aibot", "Failed to marshal encrypted response", map[string]any{
+ "error": err,
+ })
+ return ""
+ }
+
+ logger.DebugCF("wecom_aibot", "Response encrypted", map[string]any{
+ "stream_id": streamID,
+ })
+
+ return string(respJSON)
+}
+
+// encryptEmptyResponse returns a minimal valid encrypted response
+func (c *WeComAIBotChannel) encryptEmptyResponse(timestamp, nonce string) string {
+ // Construct a zero-value stream response and encrypt it so that
+ // WeCom always receives a syntactically valid encrypted JSON object.
+ emptyResp := WeComAIBotStreamResponse{}
+ return c.encryptResponse("", timestamp, nonce, emptyResp)
+}
+
+// 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)
+ if err != nil {
+ return "", err
+ }
+
+ frame, err := packWeComFrame(plaintext, receiveid)
+ if err != nil {
+ return "", err
+ }
+
+ // PKCS7 padding then AES-CBC encrypt
+ paddedFrame := pkcs7Pad(frame, blockSize)
+ ciphertext, err := encryptAESCBC(aesKey, paddedFrame)
+ if err != nil {
+ return "", err
+ }
+
+ return base64.StdEncoding.EncodeToString(ciphertext), nil
+}
+
+// generateStreamID generates a random stream ID
+func (c *WeComAIBotChannel) generateStreamID() string {
+ const letters = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+ b := make([]byte, 10)
+ for i := range b {
+ n, _ := rand.Int(rand.Reader, big.NewInt(int64(len(letters))))
+ b[i] = letters[n.Int64()]
+ }
+ return string(b)
+}
+
+// cleanupLoop periodically cleans up old streaming tasks
+func (c *WeComAIBotChannel) cleanupLoop() {
+ ticker := time.NewTicker(5 * time.Minute)
+ defer ticker.Stop()
+
+ for {
+ select {
+ case <-ticker.C:
+ c.cleanupOldTasks()
+ case <-c.ctx.Done():
+ return
+ }
+ }
+}
+
+// cleanupOldTasks removes tasks that have exceeded their expected lifetime:
+// - Active tasks (in streamTasks): cleaned up after 1 hour (response_url validity window).
+// - StreamClosed tasks (in chatTasks only): cleaned up after streamClosedGracePeriod.
+// These tasks are waiting for the agent to call Send() via response_url. If the agent
+// crashes or times out without calling Send(), we must not let them accumulate indefinitely.
+// The grace period is generous enough to cover typical LLM latency but far shorter than 1 hour,
+// preventing chatTasks from filling up when many requests time out in quick succession.
+const (
+ streamClosedGracePeriod = 10 * time.Minute // max wait for agent after stream closes
+ taskMaxLifetime = 1 * time.Hour // absolute max (≈ response_url validity)
+)
+
+func (c *WeComAIBotChannel) cleanupOldTasks() {
+ c.taskMu.Lock()
+ defer c.taskMu.Unlock()
+
+ now := time.Now()
+ cutoff := now.Add(-taskMaxLifetime)
+ for id, task := range c.streamTasks {
+ if task.CreatedTime.Before(cutoff) {
+ delete(c.streamTasks, id)
+ task.cancel() // interrupt agent goroutine still waiting for LLM
+ queue := c.chatTasks[task.ChatID]
+ for i, t := range queue {
+ if t == task {
+ c.chatTasks[task.ChatID] = append(queue[:i], queue[i+1:]...)
+ break
+ }
+ }
+ if len(c.chatTasks[task.ChatID]) == 0 {
+ delete(c.chatTasks, task.ChatID)
+ }
+ logger.DebugCF("wecom_aibot", "Cleaned up expired task", map[string]any{
+ "stream_id": id,
+ })
+ }
+ }
+ // Clean up StreamClosed tasks from chatTasks.
+ // Two expiry conditions are checked:
+ // 1. Absolute expiry: task was created more than taskMaxLifetime ago.
+ // 2. Grace expiry: stream closed more than streamClosedGracePeriod ago
+ // (agent had enough time to reply; it is not coming back).
+ for chatID, queue := range c.chatTasks {
+ filtered := queue[:0]
+ for i, t := range queue {
+ absoluteExpired := t.CreatedTime.Before(cutoff)
+ graceExpired := t.StreamClosed &&
+ !t.StreamClosedAt.IsZero() &&
+ t.StreamClosedAt.Before(now.Add(-streamClosedGracePeriod))
+ if t.Finished {
+ // Finished tasks should have been removed by removeTask().
+ // Finding one here (especially not at position 0) means an
+ // unexpected code path left it stranded, causing the queue to
+ // grow silently. Log a warning so it is visible, then drop it.
+ if i > 0 {
+ logger.WarnCF("wecom_aibot",
+ "Found stranded Finished task in the middle of chatTasks queue; "+
+ "this should not happen — removeTask() should have spliced it out",
+ map[string]any{
+ "chat_id": chatID,
+ "stream_id": t.StreamID,
+ "position": i,
+ })
+ }
+ // The task is already finished; its context was already canceled
+ // by removeTask(), so no further action is required.
+ continue
+ } else if !absoluteExpired && !graceExpired {
+ filtered = append(filtered, t)
+ } else {
+ t.cancel() // cancel any lingering agent goroutine
+ }
+ }
+ if len(filtered) == 0 {
+ delete(c.chatTasks, chatID)
+ } else {
+ c.chatTasks[chatID] = filtered
+ }
+ }
+}
+
+// handleHealth handles health check requests
+func (c *WeComAIBotChannel) handleHealth(w http.ResponseWriter, r *http.Request) {
+ status := "ok"
+ if !c.IsRunning() {
+ status = "not running"
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ json.NewEncoder(w).Encode(map[string]string{
+ "status": status,
+ })
+}
diff --git a/pkg/channels/wecom/aibot_test.go b/pkg/channels/wecom/aibot_test.go
new file mode 100644
index 000000000..6f0664187
--- /dev/null
+++ b/pkg/channels/wecom/aibot_test.go
@@ -0,0 +1,210 @@
+package wecom
+
+import (
+ "context"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestNewWeComAIBotChannel(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",
+ }
+
+ messageBus := bus.NewMessageBus()
+ ch, err := NewWeComAIBotChannel(cfg, messageBus)
+ if err != nil {
+ t.Fatalf("Expected no error, got %v", err)
+ }
+
+ if ch == nil {
+ t.Fatal("Expected channel to be created")
+ }
+
+ if ch.Name() != "wecom_aibot" {
+ t.Errorf("Expected name 'wecom_aibot', got '%s'", ch.Name())
+ }
+ })
+
+ t.Run("error with missing token", func(t *testing.T) {
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ EncodingAESKey: "testkey1234567890123456789012345678901234567",
+ }
+
+ messageBus := bus.NewMessageBus()
+ _, err := NewWeComAIBotChannel(cfg, messageBus)
+
+ if err == nil {
+ t.Fatal("Expected error for missing token, got nil")
+ }
+ })
+
+ t.Run("error with missing encoding key", func(t *testing.T) {
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ Token: "test_token",
+ }
+
+ messageBus := bus.NewMessageBus()
+ _, err := NewWeComAIBotChannel(cfg, messageBus)
+
+ if err == nil {
+ t.Fatal("Expected error for missing encoding key, got nil")
+ }
+ })
+}
+
+func TestWeComAIBotChannelStartStop(t *testing.T) {
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ Token: "test_token",
+ EncodingAESKey: "testkey1234567890123456789012345678901234567",
+ }
+
+ messageBus := bus.NewMessageBus()
+ ch, err := NewWeComAIBotChannel(cfg, messageBus)
+ if err != nil {
+ t.Fatalf("Failed to create channel: %v", err)
+ }
+
+ ctx := context.Background()
+
+ // Test Start
+ if err := ch.Start(ctx); err != nil {
+ t.Fatalf("Failed to start channel: %v", err)
+ }
+
+ if !ch.IsRunning() {
+ t.Error("Expected channel to be running")
+ }
+
+ // Test Stop
+ if err := ch.Stop(ctx); err != nil {
+ t.Fatalf("Failed to stop channel: %v", err)
+ }
+
+ if ch.IsRunning() {
+ t.Error("Expected channel to be stopped")
+ }
+}
+
+func TestWeComAIBotChannelWebhookPath(t *testing.T) {
+ t.Run("default path", func(t *testing.T) {
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ Token: "test_token",
+ EncodingAESKey: "testkey1234567890123456789012345678901234567",
+ }
+
+ messageBus := bus.NewMessageBus()
+ ch, _ := NewWeComAIBotChannel(cfg, messageBus)
+
+ expectedPath := "/webhook/wecom-aibot"
+ if ch.WebhookPath() != expectedPath {
+ t.Errorf("Expected webhook path '%s', got '%s'", expectedPath, ch.WebhookPath())
+ }
+ })
+
+ t.Run("custom path", func(t *testing.T) {
+ customPath := "/custom/webhook"
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ Token: "test_token",
+ EncodingAESKey: "testkey1234567890123456789012345678901234567",
+ WebhookPath: customPath,
+ }
+
+ messageBus := bus.NewMessageBus()
+ ch, _ := NewWeComAIBotChannel(cfg, messageBus)
+
+ if ch.WebhookPath() != customPath {
+ t.Errorf("Expected webhook path '%s', got '%s'", customPath, ch.WebhookPath())
+ }
+ })
+}
+
+func TestGenerateStreamID(t *testing.T) {
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ Token: "test_token",
+ EncodingAESKey: "testkey1234567890123456789012345678901234567",
+ }
+
+ messageBus := bus.NewMessageBus()
+ ch, _ := NewWeComAIBotChannel(cfg, messageBus)
+
+ // Generate multiple IDs and check they are unique
+ ids := make(map[string]bool)
+ for i := 0; i < 100; i++ {
+ id := ch.generateStreamID()
+
+ if len(id) != 10 {
+ t.Errorf("Expected stream ID length 10, got %d", len(id))
+ }
+
+ if ids[id] {
+ t.Errorf("Duplicate stream ID generated: %s", id)
+ }
+ ids[id] = true
+ }
+}
+
+func TestEncryptDecrypt(t *testing.T) {
+ // Use a valid 43-character base64 key (企业微信标准格式)
+ cfg := config.WeComAIBotConfig{
+ Enabled: true,
+ Token: "test_token",
+ EncodingAESKey: "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG", // 43 characters
+ }
+
+ messageBus := bus.NewMessageBus()
+ ch, _ := NewWeComAIBotChannel(cfg, messageBus)
+
+ plaintext := "Hello, World!"
+ receiveid := ""
+
+ // Encrypt
+ encrypted, err := ch.encryptMessage(plaintext, receiveid)
+ if err != nil {
+ t.Fatalf("Failed to encrypt message: %v", err)
+ }
+
+ if encrypted == "" {
+ t.Fatal("Encrypted message is empty")
+ }
+
+ // Decrypt
+ decrypted, err := decryptMessageWithVerify(encrypted, cfg.EncodingAESKey, receiveid)
+ if err != nil {
+ t.Fatalf("Failed to decrypt message: %v", err)
+ }
+
+ if decrypted != plaintext {
+ t.Errorf("Expected decrypted message '%s', got '%s'", plaintext, decrypted)
+ }
+}
+
+func TestGenerateSignature(t *testing.T) {
+ token := "test_token"
+ timestamp := "1234567890"
+ nonce := "test_nonce"
+ encrypt := "encrypted_msg"
+
+ signature := computeSignature(token, timestamp, nonce, encrypt)
+
+ if signature == "" {
+ t.Error("Generated signature is empty")
+ }
+
+ // Verify signature using verifySignature function
+ if !verifySignature(token, signature, timestamp, nonce, encrypt) {
+ t.Error("Generated signature does not verify correctly")
+ }
+}
diff --git a/pkg/channels/wecom_app.go b/pkg/channels/wecom/app.go
similarity index 65%
rename from pkg/channels/wecom_app.go
rename to pkg/channels/wecom/app.go
index 302603445..717815b9f 100644
--- a/pkg/channels/wecom_app.go
+++ b/pkg/channels/wecom/app.go
@@ -1,8 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// WeCom App (企业微信自建应用) channel implementation
-// Supports receiving messages via webhook callback and sending messages proactively
-
-package channels
+package wecom
import (
"bytes"
@@ -11,14 +7,19 @@ import (
"encoding/xml"
"fmt"
"io"
+ "mime/multipart"
"net/http"
"net/url"
+ "os"
+ "path/filepath"
"strings"
"sync"
"time"
"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"
"github.com/sipeed/picoclaw/pkg/utils"
)
@@ -29,16 +30,15 @@ const (
// WeComAppChannel implements the Channel interface for WeCom App (企业微信自建应用)
type WeComAppChannel struct {
- *BaseChannel
+ *channels.BaseChannel
config config.WeComAppConfig
- server *http.Server
+ client *http.Client
accessToken string
tokenExpiry time.Time
tokenMu sync.RWMutex
ctx context.Context
cancel context.CancelFunc
- processedMsgs map[string]bool // Message deduplication: msg_id -> processed
- msgMu sync.RWMutex
+ processedMsgs *MessageDeduplicator
}
// WeComXMLMessage represents the XML message structure from WeCom
@@ -123,12 +123,27 @@ func NewWeComAppChannel(cfg config.WeComAppConfig, messageBus *bus.MessageBus) (
return nil, fmt.Errorf("wecom_app corp_id, corp_secret and agent_id are required")
}
- base := NewBaseChannel("wecom_app", cfg, messageBus, cfg.AllowFrom)
+ base := channels.NewBaseChannel("wecom_app", cfg, messageBus, cfg.AllowFrom,
+ channels.WithMaxMessageLength(2048),
+ channels.WithGroupTrigger(cfg.GroupTrigger),
+ channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+ )
+ // Client timeout must be >= the configured ReplyTimeout so the
+ // per-request context deadline is always the effective limit.
+ clientTimeout := 30 * time.Second
+ if d := time.Duration(cfg.ReplyTimeout) * time.Second; d > clientTimeout {
+ clientTimeout = d
+ }
+
+ ctx, cancel := context.WithCancel(context.Background())
return &WeComAppChannel{
BaseChannel: base,
config: cfg,
- processedMsgs: make(map[string]bool),
+ client: &http.Client{Timeout: clientTimeout},
+ ctx: ctx,
+ cancel: cancel,
+ processedMsgs: NewMessageDeduplicator(wecomMaxProcessedMessages),
}, nil
}
@@ -137,10 +152,14 @@ func (c *WeComAppChannel) Name() string {
return "wecom_app"
}
-// Start initializes the WeCom App channel with HTTP webhook server
+// Start initializes the WeCom App channel
func (c *WeComAppChannel) Start(ctx context.Context) error {
logger.InfoC("wecom_app", "Starting WeCom App channel...")
+ // Cancel the context created in the constructor to avoid a resource leak.
+ if c.cancel != nil {
+ c.cancel()
+ }
c.ctx, c.cancel = context.WithCancel(ctx)
// Get initial access token
@@ -153,37 +172,8 @@ func (c *WeComAppChannel) Start(ctx context.Context) error {
// Start token refresh goroutine
go c.tokenRefreshLoop()
- // Setup HTTP server for webhook
- mux := http.NewServeMux()
- webhookPath := c.config.WebhookPath
- if webhookPath == "" {
- webhookPath = "/webhook/wecom-app"
- }
- mux.HandleFunc(webhookPath, c.handleWebhook)
-
- // Health check endpoint
- mux.HandleFunc("/health/wecom-app", c.handleHealth)
-
- addr := fmt.Sprintf("%s:%d", c.config.WebhookHost, c.config.WebhookPort)
- c.server = &http.Server{
- Addr: addr,
- Handler: mux,
- }
-
- c.setRunning(true)
- logger.InfoCF("wecom_app", "WeCom App channel started", map[string]any{
- "address": addr,
- "path": webhookPath,
- })
-
- // Start server in goroutine
- go func() {
- if err := c.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
- logger.ErrorCF("wecom_app", "HTTP server error", map[string]any{
- "error": err.Error(),
- })
- }
- }()
+ c.SetRunning(true)
+ logger.InfoC("wecom_app", "WeCom App channel started")
return nil
}
@@ -196,13 +186,7 @@ func (c *WeComAppChannel) Stop(ctx context.Context) error {
c.cancel()
}
- if c.server != nil {
- shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
- defer cancel()
- c.server.Shutdown(shutdownCtx)
- }
-
- c.setRunning(false)
+ c.SetRunning(false)
logger.InfoC("wecom_app", "WeCom App channel stopped")
return nil
}
@@ -210,7 +194,7 @@ func (c *WeComAppChannel) Stop(ctx context.Context) error {
// Send sends a message to WeCom user proactively using access token
func (c *WeComAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
if !c.IsRunning() {
- return fmt.Errorf("wecom_app channel not running")
+ return channels.ErrNotRunning
}
accessToken := c.getAccessToken()
@@ -226,6 +210,222 @@ func (c *WeComAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
return c.sendTextMessage(ctx, accessToken, msg.ChatID, msg.Content)
}
+// SendMedia implements the channels.MediaSender interface.
+func (c *WeComAppChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+ if !c.IsRunning() {
+ return channels.ErrNotRunning
+ }
+
+ accessToken := c.getAccessToken()
+ if accessToken == "" {
+ return fmt.Errorf("no valid access token available: %w", channels.ErrTemporary)
+ }
+
+ store := c.GetMediaStore()
+ if store == nil {
+ return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+ }
+
+ for _, part := range msg.Parts {
+ localPath, err := store.Resolve(part.Ref)
+ if err != nil {
+ logger.ErrorCF("wecom_app", "Failed to resolve media ref", map[string]any{
+ "ref": part.Ref,
+ "error": err.Error(),
+ })
+ continue
+ }
+
+ // Map part type to WeCom media type
+ var mediaType string
+ switch part.Type {
+ case "image":
+ mediaType = "image"
+ case "audio":
+ mediaType = "voice"
+ case "video":
+ mediaType = "video"
+ default:
+ mediaType = "file"
+ }
+
+ // Upload media to get media_id
+ mediaID, err := c.uploadMedia(ctx, accessToken, mediaType, localPath)
+ if err != nil {
+ logger.ErrorCF("wecom_app", "Failed to upload media", map[string]any{
+ "type": mediaType,
+ "error": err.Error(),
+ })
+ // Fallback: send caption as text
+ if part.Caption != "" {
+ _ = c.sendTextMessage(ctx, accessToken, msg.ChatID, part.Caption)
+ }
+ continue
+ }
+
+ // Send media message using the media_id
+ if mediaType == "image" {
+ err = c.sendImageMessage(ctx, accessToken, msg.ChatID, mediaID)
+ } else {
+ // For non-image types, send as text fallback with caption
+ caption := part.Caption
+ if caption == "" {
+ caption = fmt.Sprintf("[%s: %s]", part.Type, part.Filename)
+ }
+ err = c.sendTextMessage(ctx, accessToken, msg.ChatID, caption)
+ }
+
+ if err != nil {
+ return err
+ }
+ }
+
+ return nil
+}
+
+// uploadMedia uploads a local file to WeCom temporary media storage.
+func (c *WeComAppChannel) uploadMedia(ctx context.Context, accessToken, mediaType, localPath string) (string, error) {
+ apiURL := fmt.Sprintf("%s/cgi-bin/media/upload?access_token=%s&type=%s",
+ wecomAPIBase, url.QueryEscape(accessToken), url.QueryEscape(mediaType))
+
+ file, err := os.Open(localPath)
+ if err != nil {
+ return "", fmt.Errorf("failed to open file: %w", err)
+ }
+ defer file.Close()
+
+ body := &bytes.Buffer{}
+ writer := multipart.NewWriter(body)
+
+ filename := filepath.Base(localPath)
+ formFile, err := writer.CreateFormFile("media", filename)
+ if err != nil {
+ return "", fmt.Errorf("failed to create form file: %w", err)
+ }
+
+ if _, err = io.Copy(formFile, file); err != nil {
+ return "", fmt.Errorf("failed to copy file content: %w", err)
+ }
+ writer.Close()
+
+ req, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, body)
+ if err != nil {
+ return "", fmt.Errorf("failed to create request: %w", err)
+ }
+ req.Header.Set("Content-Type", writer.FormDataContentType())
+
+ resp, err := c.client.Do(req)
+ if err != nil {
+ return "", channels.ClassifyNetError(err)
+ }
+ defer resp.Body.Close()
+
+ if resp.StatusCode != http.StatusOK {
+ respBody, _ := io.ReadAll(resp.Body)
+ return "", channels.ClassifySendError(resp.StatusCode, fmt.Errorf("wecom upload error: %s", string(respBody)))
+ }
+
+ var result struct {
+ ErrCode int `json:"errcode"`
+ ErrMsg string `json:"errmsg"`
+ MediaID string `json:"media_id"`
+ }
+ if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+ return "", fmt.Errorf("failed to parse upload response: %w", err)
+ }
+
+ if result.ErrCode != 0 {
+ return "", fmt.Errorf("upload API error: %s (code: %d)", result.ErrMsg, result.ErrCode)
+ }
+
+ return result.MediaID, nil
+}
+
+// sendWeComMessage marshals payload and POSTs it to the WeCom message API.
+func (c *WeComAppChannel) sendWeComMessage(ctx context.Context, accessToken string, payload any) error {
+ apiURL := fmt.Sprintf("%s/cgi-bin/message/send?access_token=%s", wecomAPIBase, accessToken)
+
+ jsonData, err := json.Marshal(payload)
+ if err != nil {
+ return fmt.Errorf("failed to marshal message: %w", err)
+ }
+
+ timeout := c.config.ReplyTimeout
+ if timeout <= 0 {
+ timeout = 5
+ }
+
+ reqCtx, cancel := context.WithTimeout(ctx, time.Duration(timeout)*time.Second)
+ defer cancel()
+
+ req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, apiURL, bytes.NewBuffer(jsonData))
+ if err != nil {
+ return fmt.Errorf("failed to create request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+
+ resp, err := c.client.Do(req)
+ if err != nil {
+ return channels.ClassifyNetError(err)
+ }
+ defer resp.Body.Close()
+
+ if resp.StatusCode != http.StatusOK {
+ respBody, _ := io.ReadAll(resp.Body)
+ return channels.ClassifySendError(resp.StatusCode, fmt.Errorf("wecom_app API error: %s", string(respBody)))
+ }
+
+ respBody, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return fmt.Errorf("failed to read response: %w", err)
+ }
+
+ var sendResp WeComSendMessageResponse
+ if err := json.Unmarshal(respBody, &sendResp); err != nil {
+ return fmt.Errorf("failed to parse response: %w", err)
+ }
+
+ if sendResp.ErrCode != 0 {
+ return fmt.Errorf("API error: %s (code: %d)", sendResp.ErrMsg, sendResp.ErrCode)
+ }
+
+ return nil
+}
+
+// sendImageMessage sends an image message using a media_id.
+func (c *WeComAppChannel) sendImageMessage(ctx context.Context, accessToken, userID, mediaID string) error {
+ msg := WeComImageMessage{
+ ToUser: userID,
+ MsgType: "image",
+ AgentID: c.config.AgentID,
+ }
+ msg.Image.MediaID = mediaID
+ return c.sendWeComMessage(ctx, accessToken, msg)
+}
+
+// WebhookPath returns the path for registering on the shared HTTP server.
+func (c *WeComAppChannel) WebhookPath() string {
+ if c.config.WebhookPath != "" {
+ return c.config.WebhookPath
+ }
+ return "/webhook/wecom-app"
+}
+
+// ServeHTTP implements http.Handler for the shared HTTP server.
+func (c *WeComAppChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+ c.handleWebhook(w, r)
+}
+
+// HealthPath returns the health check endpoint path.
+func (c *WeComAppChannel) HealthPath() string {
+ return "/health/wecom-app"
+}
+
+// HealthHandler handles health check requests.
+func (c *WeComAppChannel) HealthHandler(w http.ResponseWriter, r *http.Request) {
+ c.handleHealth(w, r)
+}
+
// handleWebhook handles incoming webhook requests from WeCom
func (c *WeComAppChannel) handleWebhook(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
@@ -279,7 +479,7 @@ func (c *WeComAppChannel) handleVerification(ctx context.Context, w http.Respons
}
// Verify signature
- if !WeComVerifySignature(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,
"msg_signature": msgSignature,
@@ -298,7 +498,7 @@ func (c *WeComAppChannel) handleVerification(ctx context.Context, w http.Respons
"encoding_aes_key": c.config.EncodingAESKey,
"corp_id": c.config.CorpID,
})
- decryptedEchoStr, err := WeComDecryptMessageWithVerify(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(),
@@ -357,7 +557,7 @@ func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.Resp
}
// Verify signature
- if !WeComVerifySignature(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
@@ -365,7 +565,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 := WeComDecryptMessageWithVerify(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(),
@@ -384,8 +584,9 @@ func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.Resp
return
}
- // Process the message with context
- go c.processMessage(ctx, msg)
+ // Process the message with the channel's long-lived context (not the HTTP
+ // request context, which is canceled as soon as we return the response).
+ go c.processMessage(c.ctx, msg)
// Return success response immediately
// WeCom App requires response within configured timeout (default 5 seconds)
@@ -405,29 +606,21 @@ func (c *WeComAppChannel) processMessage(ctx context.Context, msg WeComXMLMessag
// Message deduplication: Use msg_id to prevent duplicate processing
// As per WeCom documentation, use msg_id for deduplication
msgID := fmt.Sprintf("%d", msg.MsgId)
- c.msgMu.Lock()
- if c.processedMsgs[msgID] {
- c.msgMu.Unlock()
+ if !c.processedMsgs.MarkMessageProcessed(msgID) {
logger.DebugCF("wecom_app", "Skipping duplicate message", map[string]any{
"msg_id": msgID,
})
return
}
- c.processedMsgs[msgID] = true
- c.msgMu.Unlock()
-
- // Clean up old messages periodically (keep last 1000)
- if len(c.processedMsgs) > 1000 {
- c.msgMu.Lock()
- c.processedMsgs = make(map[string]bool)
- c.msgMu.Unlock()
- }
senderID := msg.FromUserName
chatID := senderID // WeCom App uses user ID as chat ID for direct messages
// Build metadata
// WeCom App only supports direct messages (private chat)
+ peer := bus.Peer{Kind: "direct", ID: senderID}
+ messageID := fmt.Sprintf("%d", msg.MsgId)
+
metadata := map[string]string{
"msg_type": msg.MsgType,
"msg_id": fmt.Sprintf("%d", msg.MsgId),
@@ -435,8 +628,6 @@ func (c *WeComAppChannel) processMessage(ctx context.Context, msg WeComXMLMessag
"platform": "wecom_app",
"media_id": msg.MediaId,
"create_time": fmt.Sprintf("%d", msg.CreateTime),
- "peer_kind": "direct",
- "peer_id": senderID,
}
content := msg.Content
@@ -447,8 +638,15 @@ func (c *WeComAppChannel) processMessage(ctx context.Context, msg WeComXMLMessag
"preview": utils.Truncate(content, 50),
})
+ // Build sender info
+ appSender := bus.SenderInfo{
+ Platform: "wecom",
+ PlatformID: senderID,
+ CanonicalID: identity.BuildCanonicalID("wecom", senderID),
+ }
+
// Handle the message through the base channel
- c.HandleMessage(senderID, chatID, content, nil, metadata)
+ c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, nil, metadata, appSender)
}
// tokenRefreshLoop periodically refreshes the access token
@@ -516,59 +714,15 @@ func (c *WeComAppChannel) getAccessToken() string {
return c.accessToken
}
-// sendTextMessage sends a text message to a user
+// sendTextMessage sends a text message to a user.
func (c *WeComAppChannel) sendTextMessage(ctx context.Context, accessToken, userID, content string) error {
- apiURL := fmt.Sprintf("%s/cgi-bin/message/send?access_token=%s", wecomAPIBase, accessToken)
-
msg := WeComTextMessage{
ToUser: userID,
MsgType: "text",
AgentID: c.config.AgentID,
}
msg.Text.Content = content
-
- jsonData, err := json.Marshal(msg)
- if err != nil {
- return fmt.Errorf("failed to marshal message: %w", err)
- }
-
- // Use configurable timeout (default 5 seconds)
- timeout := c.config.ReplyTimeout
- if timeout <= 0 {
- timeout = 5
- }
-
- reqCtx, cancel := context.WithTimeout(ctx, time.Duration(timeout)*time.Second)
- defer cancel()
-
- req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, apiURL, bytes.NewBuffer(jsonData))
- if err != nil {
- return fmt.Errorf("failed to create request: %w", err)
- }
- req.Header.Set("Content-Type", "application/json")
-
- client := &http.Client{Timeout: time.Duration(timeout) * time.Second}
- resp, err := client.Do(req)
- if err != nil {
- return fmt.Errorf("failed to send message: %w", err)
- }
- defer resp.Body.Close()
-
- body, err := io.ReadAll(resp.Body)
- if err != nil {
- return fmt.Errorf("failed to read response: %w", err)
- }
-
- var sendResp WeComSendMessageResponse
- if err := json.Unmarshal(body, &sendResp); err != nil {
- return fmt.Errorf("failed to parse response: %w", err)
- }
-
- if sendResp.ErrCode != 0 {
- return fmt.Errorf("API error: %s (code: %d)", sendResp.ErrMsg, sendResp.ErrCode)
- }
-
- return nil
+ return c.sendWeComMessage(ctx, accessToken, msg)
}
// handleHealth handles health check requests
diff --git a/pkg/channels/wecom_app_test.go b/pkg/channels/wecom/app_test.go
similarity index 92%
rename from pkg/channels/wecom_app_test.go
rename to pkg/channels/wecom/app_test.go
index abf15c52b..7f230494f 100644
--- a/pkg/channels/wecom_app_test.go
+++ b/pkg/channels/wecom/app_test.go
@@ -1,7 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// WeCom App (企业微信自建应用) channel tests
-
-package channels
+package wecom
import (
"bytes"
@@ -46,7 +43,7 @@ func encryptTestMessageApp(message, aesKey string) (string, error) {
// Prepare message: random(16) + msg_len(4) + msg + corp_id
random := make([]byte, 0, 16)
- for i := 0; i < 16; i++ {
+ for i := range 16 {
random = append(random, byte(i+1))
}
@@ -197,7 +194,7 @@ func TestWeComAppVerifySignature(t *testing.T) {
msgEncrypt := "test_message"
expectedSig := generateSignatureApp("test_token", timestamp, nonce, msgEncrypt)
- if !WeComVerifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
+ if !verifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
t.Error("valid signature should pass verification")
}
})
@@ -207,7 +204,7 @@ func TestWeComAppVerifySignature(t *testing.T) {
nonce := "test_nonce"
msgEncrypt := "test_message"
- if WeComVerifySignature(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")
}
})
@@ -221,7 +218,7 @@ func TestWeComAppVerifySignature(t *testing.T) {
}
chEmpty, _ := NewWeComAppChannel(cfgEmpty, msgBus)
- if !WeComVerifySignature(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 skip verification and return true")
}
})
@@ -243,7 +240,7 @@ func TestWeComAppDecryptMessage(t *testing.T) {
plainText := "hello world"
encoded := base64.StdEncoding.EncodeToString([]byte(plainText))
- result, err := WeComDecryptMessage(encoded, ch.config.EncodingAESKey)
+ result, err := decryptMessage(encoded, ch.config.EncodingAESKey)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -268,7 +265,7 @@ func TestWeComAppDecryptMessage(t *testing.T) {
t.Fatalf("failed to encrypt test message: %v", err)
}
- result, err := WeComDecryptMessage(encrypted, ch.config.EncodingAESKey)
+ result, err := decryptMessage(encrypted, ch.config.EncodingAESKey)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -286,7 +283,7 @@ func TestWeComAppDecryptMessage(t *testing.T) {
}
ch, _ := NewWeComAppChannel(cfg, msgBus)
- _, err := WeComDecryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
+ _, err := decryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
if err == nil {
t.Error("expected error for invalid base64, got nil")
}
@@ -301,7 +298,7 @@ func TestWeComAppDecryptMessage(t *testing.T) {
}
ch, _ := NewWeComAppChannel(cfg, msgBus)
- _, err := WeComDecryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
+ _, err := decryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
if err == nil {
t.Error("expected error for invalid AES key, got nil")
}
@@ -319,67 +316,13 @@ func TestWeComAppDecryptMessage(t *testing.T) {
// Encrypt a very short message that results in ciphertext less than block size
shortData := make([]byte, 8)
- _, err := WeComDecryptMessage(base64.StdEncoding.EncodeToString(shortData), ch.config.EncodingAESKey)
+ _, err := decryptMessage(base64.StdEncoding.EncodeToString(shortData), ch.config.EncodingAESKey)
if err == nil {
t.Error("expected error for short ciphertext, got nil")
}
})
}
-func TestWeComAppPKCS7Unpad(t *testing.T) {
- tests := []struct {
- name string
- input []byte
- expected []byte
- }{
- {
- name: "empty input",
- input: []byte{},
- expected: []byte{},
- },
- {
- name: "valid padding 3 bytes",
- input: append([]byte("hello"), bytes.Repeat([]byte{3}, 3)...),
- expected: []byte("hello"),
- },
- {
- name: "valid padding 16 bytes (full block)",
- input: append([]byte("123456789012345"), bytes.Repeat([]byte{16}, 16)...),
- expected: []byte("123456789012345"),
- },
- {
- name: "invalid padding larger than data",
- input: []byte{20},
- expected: nil, // should return error
- },
- {
- name: "invalid padding zero",
- input: append([]byte("test"), byte(0)),
- expected: nil, // should return error
- },
- }
-
- for _, tt := range tests {
- t.Run(tt.name, func(t *testing.T) {
- result, err := pkcs7UnpadWeCom(tt.input)
- if tt.expected == nil {
- // This case should return an error
- if err == nil {
- t.Errorf("pkcs7Unpad() expected error for invalid padding, got result: %v", result)
- }
- return
- }
- if err != nil {
- t.Errorf("pkcs7Unpad() unexpected error: %v", err)
- return
- }
- if !bytes.Equal(result, tt.expected) {
- t.Errorf("pkcs7Unpad() = %v, want %v", result, tt.expected)
- }
- })
- }
-}
-
func TestWeComAppHandleVerification(t *testing.T) {
msgBus := bus.NewMessageBus()
aesKey := generateTestAESKeyApp()
@@ -852,6 +795,28 @@ func TestWeComAppMessageStructures(t *testing.T) {
}
})
+ t.Run("WeComImageMessage structure", func(t *testing.T) {
+ msg := WeComImageMessage{
+ ToUser: "user123",
+ MsgType: "image",
+ AgentID: 1000002,
+ }
+ msg.Image.MediaID = "media_123456"
+
+ if msg.Image.MediaID != "media_123456" {
+ t.Errorf("Image.MediaID = %q, want %q", msg.Image.MediaID, "media_123456")
+ }
+ if msg.ToUser != "user123" {
+ t.Errorf("ToUser = %q, want %q", msg.ToUser, "user123")
+ }
+ if msg.MsgType != "image" {
+ t.Errorf("MsgType = %q, want %q", msg.MsgType, "image")
+ }
+ if msg.AgentID != 1000002 {
+ t.Errorf("AgentID = %d, want %d", msg.AgentID, 1000002)
+ }
+ })
+
t.Run("WeComAccessTokenResponse structure", func(t *testing.T) {
jsonData := `{
"errcode": 0,
diff --git a/pkg/channels/wecom.go b/pkg/channels/wecom/bot.go
similarity index 62%
rename from pkg/channels/wecom.go
rename to pkg/channels/wecom/bot.go
index f8daf89de..9126a847d 100644
--- a/pkg/channels/wecom.go
+++ b/pkg/channels/wecom/bot.go
@@ -1,29 +1,20 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// WeCom Bot (企业微信智能机器人) channel implementation
-// Uses webhook callback mode for receiving messages and webhook API for sending replies
-
-package channels
+package wecom
import (
"bytes"
"context"
- "crypto/aes"
- "crypto/cipher"
- "crypto/sha1"
- "encoding/base64"
- "encoding/binary"
"encoding/json"
"encoding/xml"
"fmt"
"io"
"net/http"
- "sort"
"strings"
- "sync"
"time"
"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"
"github.com/sipeed/picoclaw/pkg/utils"
)
@@ -31,13 +22,12 @@ import (
// WeComBotChannel implements the Channel interface for WeCom Bot (企业微信智能机器人)
// Uses webhook callback mode - simpler than WeCom App but only supports passive replies
type WeComBotChannel struct {
- *BaseChannel
+ *channels.BaseChannel
config config.WeComConfig
- server *http.Server
+ client *http.Client
ctx context.Context
cancel context.CancelFunc
- processedMsgs map[string]bool // Message deduplication: msg_id -> processed
- msgMu sync.RWMutex
+ processedMsgs *MessageDeduplicator
}
// WeComBotMessage represents the JSON message structure from WeCom Bot (AIBOT)
@@ -96,12 +86,27 @@ func NewWeComBotChannel(cfg config.WeComConfig, messageBus *bus.MessageBus) (*We
return nil, fmt.Errorf("wecom token and webhook_url are required")
}
- base := NewBaseChannel("wecom", cfg, messageBus, cfg.AllowFrom)
+ base := channels.NewBaseChannel("wecom", cfg, messageBus, cfg.AllowFrom,
+ channels.WithMaxMessageLength(2048),
+ channels.WithGroupTrigger(cfg.GroupTrigger),
+ channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+ )
+ // Client timeout must be >= the configured ReplyTimeout so the
+ // per-request context deadline is always the effective limit.
+ clientTimeout := 30 * time.Second
+ if d := time.Duration(cfg.ReplyTimeout) * time.Second; d > clientTimeout {
+ clientTimeout = d
+ }
+
+ ctx, cancel := context.WithCancel(context.Background())
return &WeComBotChannel{
BaseChannel: base,
config: cfg,
- processedMsgs: make(map[string]bool),
+ client: &http.Client{Timeout: clientTimeout},
+ ctx: ctx,
+ cancel: cancel,
+ processedMsgs: NewMessageDeduplicator(wecomMaxProcessedMessages),
}, nil
}
@@ -110,43 +115,18 @@ func (c *WeComBotChannel) Name() string {
return "wecom"
}
-// Start initializes the WeCom Bot channel with HTTP webhook server
+// Start initializes the WeCom Bot channel
func (c *WeComBotChannel) Start(ctx context.Context) error {
logger.InfoC("wecom", "Starting WeCom Bot channel...")
+ // Cancel the context created in the constructor to avoid a resource leak.
+ if c.cancel != nil {
+ c.cancel()
+ }
c.ctx, c.cancel = context.WithCancel(ctx)
- // Setup HTTP server for webhook
- mux := http.NewServeMux()
- webhookPath := c.config.WebhookPath
- if webhookPath == "" {
- webhookPath = "/webhook/wecom"
- }
- mux.HandleFunc(webhookPath, c.handleWebhook)
-
- // Health check endpoint
- mux.HandleFunc("/health/wecom", c.handleHealth)
-
- addr := fmt.Sprintf("%s:%d", c.config.WebhookHost, c.config.WebhookPort)
- c.server = &http.Server{
- Addr: addr,
- Handler: mux,
- }
-
- c.setRunning(true)
- logger.InfoCF("wecom", "WeCom Bot channel started", map[string]any{
- "address": addr,
- "path": webhookPath,
- })
-
- // Start server in goroutine
- go func() {
- if err := c.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
- logger.ErrorCF("wecom", "HTTP server error", map[string]any{
- "error": err.Error(),
- })
- }
- }()
+ c.SetRunning(true)
+ logger.InfoC("wecom", "WeCom Bot channel started")
return nil
}
@@ -159,13 +139,7 @@ func (c *WeComBotChannel) Stop(ctx context.Context) error {
c.cancel()
}
- if c.server != nil {
- shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
- defer cancel()
- c.server.Shutdown(shutdownCtx)
- }
-
- c.setRunning(false)
+ c.SetRunning(false)
logger.InfoC("wecom", "WeCom Bot channel stopped")
return nil
}
@@ -175,7 +149,7 @@ func (c *WeComBotChannel) Stop(ctx context.Context) error {
// For delayed responses, we use the webhook URL
func (c *WeComBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
if !c.IsRunning() {
- return fmt.Errorf("wecom channel not running")
+ return channels.ErrNotRunning
}
logger.DebugCF("wecom", "Sending message via webhook", map[string]any{
@@ -186,6 +160,29 @@ func (c *WeComBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
return c.sendWebhookReply(ctx, msg.ChatID, msg.Content)
}
+// WebhookPath returns the path for registering on the shared HTTP server.
+func (c *WeComBotChannel) WebhookPath() string {
+ if c.config.WebhookPath != "" {
+ return c.config.WebhookPath
+ }
+ return "/webhook/wecom"
+}
+
+// ServeHTTP implements http.Handler for the shared HTTP server.
+func (c *WeComBotChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+ c.handleWebhook(w, r)
+}
+
+// HealthPath returns the health check endpoint path.
+func (c *WeComBotChannel) HealthPath() string {
+ return "/health/wecom"
+}
+
+// HealthHandler handles health check requests.
+func (c *WeComBotChannel) HealthHandler(w http.ResponseWriter, r *http.Request) {
+ c.handleHealth(w, r)
+}
+
// handleWebhook handles incoming webhook requests from WeCom
func (c *WeComBotChannel) handleWebhook(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
@@ -219,7 +216,7 @@ func (c *WeComBotChannel) handleVerification(ctx context.Context, w http.Respons
}
// Verify signature
- if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
+ if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
logger.WarnC("wecom", "Signature verification failed")
http.Error(w, "Invalid signature", http.StatusForbidden)
return
@@ -228,7 +225,7 @@ func (c *WeComBotChannel) handleVerification(ctx context.Context, w http.Respons
// Decrypt echostr
// For AIBOT (智能机器人), receiveid should be empty string ""
// Reference: https://developer.work.weixin.qq.com/document/path/101033
- decryptedEchoStr, err := WeComDecryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
+ decryptedEchoStr, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
if err != nil {
logger.ErrorCF("wecom", "Failed to decrypt echostr", map[string]any{
"error": err.Error(),
@@ -281,7 +278,7 @@ func (c *WeComBotChannel) handleMessageCallback(ctx context.Context, w http.Resp
}
// Verify signature
- if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
+ if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
logger.WarnC("wecom", "Message signature verification failed")
http.Error(w, "Invalid signature", http.StatusForbidden)
return
@@ -290,7 +287,7 @@ func (c *WeComBotChannel) handleMessageCallback(ctx context.Context, w http.Resp
// Decrypt message
// For AIBOT (智能机器人), receiveid should be empty string ""
// Reference: https://developer.work.weixin.qq.com/document/path/101033
- decryptedMsg, err := WeComDecryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
+ decryptedMsg, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
if err != nil {
logger.ErrorCF("wecom", "Failed to decrypt message", map[string]any{
"error": err.Error(),
@@ -309,8 +306,9 @@ func (c *WeComBotChannel) handleMessageCallback(ctx context.Context, w http.Resp
return
}
- // Process the message asynchronously with context
- go c.processMessage(ctx, msg)
+ // Process the message with the channel's long-lived context (not the HTTP
+ // request context, which is canceled as soon as we return the response).
+ go c.processMessage(c.ctx, msg)
// Return success response immediately
// WeCom Bot requires response within configured timeout (default 5 seconds)
@@ -330,23 +328,12 @@ func (c *WeComBotChannel) processMessage(ctx context.Context, msg WeComBotMessag
// Message deduplication: Use msg_id to prevent duplicate processing
msgID := msg.MsgID
- c.msgMu.Lock()
- if c.processedMsgs[msgID] {
- c.msgMu.Unlock()
+ if !c.processedMsgs.MarkMessageProcessed(msgID) {
logger.DebugCF("wecom", "Skipping duplicate message", map[string]any{
"msg_id": msgID,
})
return
}
- c.processedMsgs[msgID] = true
- c.msgMu.Unlock()
-
- // Clean up old messages periodically (keep last 1000)
- if len(c.processedMsgs) > 1000 {
- c.msgMu.Lock()
- c.processedMsgs = make(map[string]bool)
- c.msgMu.Unlock()
- }
senderID := msg.From.UserID
@@ -387,12 +374,21 @@ func (c *WeComBotChannel) processMessage(ctx context.Context, msg WeComBotMessag
}
// Build metadata
+ peer := bus.Peer{Kind: peerKind, ID: peerID}
+
+ // In group chats, apply unified group trigger filtering
+ if isGroupChat {
+ respond, cleaned := c.ShouldRespondInGroup(false, content)
+ if !respond {
+ return
+ }
+ content = cleaned
+ }
+
metadata := map[string]string{
"msg_type": msg.MsgType,
"msg_id": msg.MsgID,
"platform": "wecom",
- "peer_kind": peerKind,
- "peer_id": peerID,
"response_url": msg.ResponseURL,
}
if isGroupChat {
@@ -408,8 +404,19 @@ func (c *WeComBotChannel) processMessage(ctx context.Context, msg WeComBotMessag
"preview": utils.Truncate(content, 50),
})
+ // Build sender info
+ sender := bus.SenderInfo{
+ Platform: "wecom",
+ PlatformID: senderID,
+ CanonicalID: identity.BuildCanonicalID("wecom", senderID),
+ }
+
+ if !c.IsAllowedSender(sender) {
+ return
+ }
+
// Handle the message through the base channel
- c.HandleMessage(senderID, chatID, content, nil, metadata)
+ c.HandleMessage(ctx, peer, msg.MsgID, senderID, chatID, content, nil, metadata, sender)
}
// sendWebhookReply sends a reply using the webhook URL
@@ -439,13 +446,17 @@ func (c *WeComBotChannel) sendWebhookReply(ctx context.Context, userID, content
}
req.Header.Set("Content-Type", "application/json")
- client := &http.Client{Timeout: time.Duration(timeout) * time.Second}
- resp, err := client.Do(req)
+ resp, err := c.client.Do(req)
if err != nil {
- return fmt.Errorf("failed to send webhook reply: %w", err)
+ return channels.ClassifyNetError(err)
}
defer resp.Body.Close()
+ if resp.StatusCode != http.StatusOK {
+ body, _ := io.ReadAll(resp.Body)
+ return channels.ClassifySendError(resp.StatusCode, fmt.Errorf("webhook API error: %s", string(body)))
+ }
+
body, err := io.ReadAll(resp.Body)
if err != nil {
return fmt.Errorf("failed to read response: %w", err)
@@ -477,129 +488,3 @@ func (c *WeComBotChannel) handleHealth(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(status)
}
-
-// WeCom common utilities for both WeCom Bot and WeCom App
-// The following functions were moved from wecom_common.go
-
-// WeComVerifySignature verifies the message signature for WeCom
-// This is a common function used by both WeCom Bot and WeCom App
-func WeComVerifySignature(token, msgSignature, timestamp, nonce, msgEncrypt string) bool {
- if token == "" {
- return true // Skip verification if token is not set
- }
-
- // Sort parameters
- params := []string{token, timestamp, nonce, msgEncrypt}
- sort.Strings(params)
-
- // Concatenate
- str := strings.Join(params, "")
-
- // SHA1 hash
- hash := sha1.Sum([]byte(str))
- expectedSignature := fmt.Sprintf("%x", hash)
-
- return expectedSignature == msgSignature
-}
-
-// WeComDecryptMessage decrypts the encrypted message using AES
-// This is a common function used by both WeCom Bot and WeCom App
-// For AIBOT, receiveid should be the aibotid; for other apps, it should be corp_id
-func WeComDecryptMessage(encryptedMsg, encodingAESKey string) (string, error) {
- return WeComDecryptMessageWithVerify(encryptedMsg, encodingAESKey, "")
-}
-
-// WeComDecryptMessageWithVerify decrypts the encrypted message and optionally verifies receiveid
-// receiveid: for AIBOT use aibotid, for WeCom App use corp_id. If empty, skip verification.
-func WeComDecryptMessageWithVerify(encryptedMsg, encodingAESKey, receiveid string) (string, error) {
- if encodingAESKey == "" {
- // No encryption, return as is (base64 decode)
- decoded, err := base64.StdEncoding.DecodeString(encryptedMsg)
- if err != nil {
- return "", err
- }
- return string(decoded), nil
- }
-
- // Decode AES key (base64)
- aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=")
- if err != nil {
- return "", fmt.Errorf("failed to decode AES key: %w", err)
- }
-
- // Decode encrypted message
- cipherText, err := base64.StdEncoding.DecodeString(encryptedMsg)
- if err != nil {
- return "", fmt.Errorf("failed to decode message: %w", err)
- }
-
- // AES decrypt
- block, err := aes.NewCipher(aesKey)
- if err != nil {
- return "", fmt.Errorf("failed to create cipher: %w", err)
- }
-
- if len(cipherText) < aes.BlockSize {
- return "", fmt.Errorf("ciphertext too short")
- }
-
- // IV is the first 16 bytes of AESKey
- iv := aesKey[:aes.BlockSize]
- mode := cipher.NewCBCDecrypter(block, iv)
- plainText := make([]byte, len(cipherText))
- mode.CryptBlocks(plainText, cipherText)
-
- // Remove PKCS7 padding
- plainText, err = pkcs7UnpadWeCom(plainText)
- if err != nil {
- return "", fmt.Errorf("failed to unpad: %w", err)
- }
-
- // Parse message structure
- // Format: random(16) + msg_len(4) + msg + receiveid
- if len(plainText) < 20 {
- return "", fmt.Errorf("decrypted message too short")
- }
-
- msgLen := binary.BigEndian.Uint32(plainText[16:20])
- if int(msgLen) > len(plainText)-20 {
- return "", fmt.Errorf("invalid message length")
- }
-
- msg := plainText[20 : 20+msgLen]
-
- // Verify receiveid if provided
- if receiveid != "" && len(plainText) > 20+int(msgLen) {
- actualReceiveID := string(plainText[20+msgLen:])
- if actualReceiveID != receiveid {
- return "", fmt.Errorf("receiveid mismatch: expected %s, got %s", receiveid, actualReceiveID)
- }
- }
-
- return string(msg), nil
-}
-
-// pkcs7UnpadWeCom removes PKCS7 padding with validation
-// WeCom uses block size of 32 (not standard AES block size of 16)
-const wecomBlockSize = 32
-
-func pkcs7UnpadWeCom(data []byte) ([]byte, error) {
- if len(data) == 0 {
- return data, nil
- }
- padding := int(data[len(data)-1])
- // WeCom uses 32-byte block size for PKCS7 padding
- if padding == 0 || padding > wecomBlockSize {
- return nil, fmt.Errorf("invalid padding size: %d", padding)
- }
- if padding > len(data) {
- return nil, fmt.Errorf("padding size larger than data")
- }
- // Verify all padding bytes
- for i := 0; i < padding; i++ {
- if data[len(data)-1-i] != byte(padding) {
- return nil, fmt.Errorf("invalid padding byte at position %d", i)
- }
- }
- return data[:len(data)-padding], nil
-}
diff --git a/pkg/channels/wecom_test.go b/pkg/channels/wecom/bot_test.go
similarity index 91%
rename from pkg/channels/wecom_test.go
rename to pkg/channels/wecom/bot_test.go
index 8afa7e8c3..c053578b1 100644
--- a/pkg/channels/wecom_test.go
+++ b/pkg/channels/wecom/bot_test.go
@@ -1,7 +1,4 @@
-// PicoClaw - Ultra-lightweight personal AI agent
-// WeCom Bot (企业微信智能机器人) channel tests
-
-package channels
+package wecom
import (
"bytes"
@@ -45,7 +42,7 @@ func encryptTestMessage(message, aesKey string) (string, error) {
// Prepare message: random(16) + msg_len(4) + msg + receiveid
random := make([]byte, 0, 16)
- for i := 0; i < 16; i++ {
+ for i := range 16 {
random = append(random, byte(i))
}
@@ -177,7 +174,7 @@ func TestWeComBotVerifySignature(t *testing.T) {
msgEncrypt := "test_message"
expectedSig := generateSignature("test_token", timestamp, nonce, msgEncrypt)
- if !WeComVerifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
+ if !verifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
t.Error("valid signature should pass verification")
}
})
@@ -187,7 +184,7 @@ func TestWeComBotVerifySignature(t *testing.T) {
nonce := "test_nonce"
msgEncrypt := "test_message"
- if WeComVerifySignature(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")
}
})
@@ -202,7 +199,7 @@ func TestWeComBotVerifySignature(t *testing.T) {
config: cfgEmpty,
}
- if !WeComVerifySignature(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 skip verification and return true")
}
})
@@ -223,7 +220,7 @@ func TestWeComBotDecryptMessage(t *testing.T) {
plainText := "hello world"
encoded := base64.StdEncoding.EncodeToString([]byte(plainText))
- result, err := WeComDecryptMessage(encoded, ch.config.EncodingAESKey)
+ result, err := decryptMessage(encoded, ch.config.EncodingAESKey)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -247,7 +244,7 @@ func TestWeComBotDecryptMessage(t *testing.T) {
t.Fatalf("failed to encrypt test message: %v", err)
}
- result, err := WeComDecryptMessage(encrypted, ch.config.EncodingAESKey)
+ result, err := decryptMessage(encrypted, ch.config.EncodingAESKey)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -264,7 +261,7 @@ func TestWeComBotDecryptMessage(t *testing.T) {
}
ch, _ := NewWeComBotChannel(cfg, msgBus)
- _, err := WeComDecryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
+ _, err := decryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
if err == nil {
t.Error("expected error for invalid base64, got nil")
}
@@ -278,7 +275,7 @@ func TestWeComBotDecryptMessage(t *testing.T) {
}
ch, _ := NewWeComBotChannel(cfg, msgBus)
- _, err := WeComDecryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
+ _, err := decryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
if err == nil {
t.Error("expected error for invalid AES key, got nil")
}
@@ -320,20 +317,20 @@ func TestWeComBotPKCS7Unpad(t *testing.T) {
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
- result, err := pkcs7UnpadWeCom(tt.input)
+ result, err := pkcs7Unpad(tt.input)
if tt.expected == nil {
// This case should return an error
if err == nil {
- t.Errorf("pkcs7UnpadWeCom() expected error for invalid padding, got result: %v", result)
+ t.Errorf("pkcs7Unpad() expected error for invalid padding, got result: %v", result)
}
return
}
if err != nil {
- t.Errorf("pkcs7UnpadWeCom() unexpected error: %v", err)
+ t.Errorf("pkcs7Unpad() unexpected error: %v", err)
return
}
if !bytes.Equal(result, tt.expected) {
- t.Errorf("pkcs7UnpadWeCom() = %v, want %v", result, tt.expected)
+ t.Errorf("pkcs7Unpad() = %v, want %v", result, tt.expected)
}
})
}
@@ -415,22 +412,9 @@ func TestWeComBotHandleMessageCallback(t *testing.T) {
}
ch, _ := NewWeComBotChannel(cfg, msgBus)
- t.Run("valid direct message callback", func(t *testing.T) {
- // Create JSON message for direct chat (single)
- jsonMsg := `{
- "msgid": "test_msg_id_123",
- "aibotid": "test_aibot_id",
- "chattype": "single",
- "from": {"userid": "user123"},
- "response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
- "msgtype": "text",
- "text": {"content": "Hello World"}
- }`
-
- // Encrypt message
+ runBotMessageCallback := func(t *testing.T, jsonMsg string) *httptest.ResponseRecorder {
+ t.Helper()
encrypted, _ := encryptTestMessage(jsonMsg, aesKey)
-
- // Create encrypted XML wrapper
encryptedWrapper := struct {
XMLName xml.Name `xml:"xml"`
Encrypt string `xml:"Encrypt"`
@@ -438,20 +422,29 @@ func TestWeComBotHandleMessageCallback(t *testing.T) {
Encrypt: encrypted,
}
wrapperData, _ := xml.Marshal(encryptedWrapper)
-
timestamp := "1234567890"
nonce := "test_nonce"
signature := generateSignature("test_token", timestamp, nonce, encrypted)
-
req := httptest.NewRequest(
http.MethodPost,
"/webhook/wecom?msg_signature="+signature+"×tamp="+timestamp+"&nonce="+nonce,
bytes.NewReader(wrapperData),
)
w := httptest.NewRecorder()
-
ch.handleMessageCallback(context.Background(), w, req)
+ return w
+ }
+ t.Run("valid direct message callback", func(t *testing.T) {
+ w := runBotMessageCallback(t, `{
+ "msgid": "test_msg_id_123",
+ "aibotid": "test_aibot_id",
+ "chattype": "single",
+ "from": {"userid": "user123"},
+ "response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+ "msgtype": "text",
+ "text": {"content": "Hello World"}
+ }`)
if w.Code != http.StatusOK {
t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
}
@@ -461,8 +454,7 @@ func TestWeComBotHandleMessageCallback(t *testing.T) {
})
t.Run("valid group message callback", func(t *testing.T) {
- // Create JSON message for group chat
- jsonMsg := `{
+ w := runBotMessageCallback(t, `{
"msgid": "test_msg_id_456",
"aibotid": "test_aibot_id",
"chatid": "group_chat_id_123",
@@ -471,33 +463,7 @@ func TestWeComBotHandleMessageCallback(t *testing.T) {
"response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
"msgtype": "text",
"text": {"content": "Hello Group"}
- }`
-
- // Encrypt message
- encrypted, _ := encryptTestMessage(jsonMsg, aesKey)
-
- // Create encrypted XML wrapper
- encryptedWrapper := struct {
- XMLName xml.Name `xml:"xml"`
- Encrypt string `xml:"Encrypt"`
- }{
- Encrypt: encrypted,
- }
- wrapperData, _ := xml.Marshal(encryptedWrapper)
-
- timestamp := "1234567890"
- nonce := "test_nonce"
- signature := generateSignature("test_token", timestamp, nonce, encrypted)
-
- req := httptest.NewRequest(
- http.MethodPost,
- "/webhook/wecom?msg_signature="+signature+"×tamp="+timestamp+"&nonce="+nonce,
- bytes.NewReader(wrapperData),
- )
- w := httptest.NewRecorder()
-
- ch.handleMessageCallback(context.Background(), w, req)
-
+ }`)
if w.Code != http.StatusOK {
t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
}
diff --git a/pkg/channels/wecom/common.go b/pkg/channels/wecom/common.go
new file mode 100644
index 000000000..6510e6f81
--- /dev/null
+++ b/pkg/channels/wecom/common.go
@@ -0,0 +1,199 @@
+package wecom
+
+import (
+ "bytes"
+ "crypto/aes"
+ "crypto/cipher"
+ "crypto/rand"
+ "crypto/sha1"
+ "encoding/base64"
+ "encoding/binary"
+ "fmt"
+ "math/big"
+ "sort"
+ "strings"
+)
+
+// blockSize is the PKCS7 block size used by WeCom (32)
+const blockSize = 32
+
+// computeSignature computes the WeCom message signature from the given parameters.
+// It sorts [token, timestamp, nonce, encrypt], concatenates them and returns the SHA1 hex digest.
+func computeSignature(token, timestamp, nonce, encrypt string) string {
+ params := []string{token, timestamp, nonce, encrypt}
+ sort.Strings(params)
+ str := strings.Join(params, "")
+ hash := sha1.Sum([]byte(str))
+ return fmt.Sprintf("%x", hash)
+}
+
+// verifySignature verifies the message signature for WeCom
+// This is a common function used by both WeCom Bot and WeCom App
+func verifySignature(token, msgSignature, timestamp, nonce, msgEncrypt string) bool {
+ if token == "" {
+ return true // Skip verification if token is not set
+ }
+ return computeSignature(token, timestamp, nonce, msgEncrypt) == msgSignature
+}
+
+// decryptMessage decrypts the encrypted message using AES
+// For AIBOT, receiveid should be the aibotid; for other apps, it should be corp_id
+func decryptMessage(encryptedMsg, encodingAESKey string) (string, error) {
+ return decryptMessageWithVerify(encryptedMsg, encodingAESKey, "")
+}
+
+// decryptMessageWithVerify decrypts the encrypted message and optionally verifies receiveid
+// receiveid: for AIBOT use aibotid, for WeCom App use corp_id. If empty, skip verification.
+func decryptMessageWithVerify(encryptedMsg, encodingAESKey, receiveid string) (string, error) {
+ if encodingAESKey == "" {
+ // No encryption, return as is (base64 decode)
+ decoded, err := base64.StdEncoding.DecodeString(encryptedMsg)
+ if err != nil {
+ return "", err
+ }
+ return string(decoded), nil
+ }
+
+ aesKey, err := decodeWeComAESKey(encodingAESKey)
+ if err != nil {
+ return "", err
+ }
+
+ cipherText, err := base64.StdEncoding.DecodeString(encryptedMsg)
+ if err != nil {
+ return "", fmt.Errorf("failed to decode message: %w", err)
+ }
+
+ plainText, err := decryptAESCBC(aesKey, cipherText)
+ if err != nil {
+ return "", err
+ }
+
+ return unpackWeComFrame(plainText, receiveid)
+}
+
+// decodeWeComAESKey base64-decodes the 43-character EncodingAESKey (trailing "=" is
+// appended automatically) and validates that the result is exactly 32 bytes.
+// It is the single place that handles this repeated pattern in both encrypt and decrypt paths.
+func decodeWeComAESKey(encodingAESKey string) ([]byte, error) {
+ aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=")
+ if err != nil {
+ return nil, fmt.Errorf("failed to decode AES key: %w", err)
+ }
+ if len(aesKey) != 32 {
+ return nil, fmt.Errorf("invalid AES key length: %d", len(aesKey))
+ }
+ return aesKey, nil
+}
+
+// encryptAESCBC encrypts plaintext using AES-CBC with the given key, mirroring
+// decryptAESCBC. IV = aesKey[:aes.BlockSize]. The caller must PKCS7-pad the
+// plaintext to a multiple of aes.BlockSize before calling.
+func encryptAESCBC(aesKey, plaintext []byte) ([]byte, error) {
+ block, err := aes.NewCipher(aesKey)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create cipher: %w", err)
+ }
+ iv := aesKey[:aes.BlockSize]
+ ciphertext := make([]byte, len(plaintext))
+ cipher.NewCBCEncrypter(block, iv).CryptBlocks(ciphertext, plaintext)
+ return ciphertext, nil
+}
+
+// packWeComFrame builds the WeCom wire format:
+//
+// random(16 ASCII digits) + msg_len(4, big-endian) + msg + receiveid
+func packWeComFrame(msg, receiveid string) ([]byte, error) {
+ randomBytes := make([]byte, 16)
+ for i := range 16 {
+ n, err := rand.Int(rand.Reader, big.NewInt(10))
+ if err != nil {
+ return nil, fmt.Errorf("failed to generate random: %w", err)
+ }
+ randomBytes[i] = byte('0' + n.Int64())
+ }
+ msgBytes := []byte(msg)
+ msgLenBytes := make([]byte, 4)
+ binary.BigEndian.PutUint32(msgLenBytes, uint32(len(msgBytes)))
+ var buf bytes.Buffer
+ buf.Write(randomBytes)
+ buf.Write(msgLenBytes)
+ buf.Write(msgBytes)
+ buf.WriteString(receiveid)
+ return buf.Bytes(), nil
+}
+
+// unpackWeComFrame parses the WeCom wire format produced by packWeComFrame.
+// If receiveid is non-empty it verifies the frame's trailing receiveid field.
+func unpackWeComFrame(data []byte, receiveid string) (string, error) {
+ if len(data) < 20 {
+ return "", fmt.Errorf("decrypted frame too short: %d bytes", len(data))
+ }
+ msgLen := binary.BigEndian.Uint32(data[16:20])
+ if int(msgLen) > len(data)-20 {
+ return "", fmt.Errorf("invalid message length: %d", msgLen)
+ }
+ msg := data[20 : 20+msgLen]
+ if receiveid != "" && len(data) > 20+int(msgLen) {
+ actualReceiveID := string(data[20+msgLen:])
+ if actualReceiveID != receiveid {
+ return "", fmt.Errorf("receiveid mismatch: expected %s, got %s", receiveid, actualReceiveID)
+ }
+ }
+ return string(msg), nil
+}
+
+// decryptAESCBC decrypts ciphertext using AES-CBC with the given key.
+// IV = aesKey[:aes.BlockSize]. PKCS7 padding is stripped from the returned plaintext.
+func decryptAESCBC(aesKey, ciphertext []byte) ([]byte, error) {
+ if len(ciphertext) == 0 {
+ return nil, fmt.Errorf("ciphertext is empty")
+ }
+ if len(ciphertext)%aes.BlockSize != 0 {
+ return nil, fmt.Errorf("ciphertext length %d is not a multiple of block size", len(ciphertext))
+ }
+ block, err := aes.NewCipher(aesKey)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create cipher: %w", err)
+ }
+ iv := aesKey[:aes.BlockSize]
+ plaintext := make([]byte, len(ciphertext))
+ cipher.NewCBCDecrypter(block, iv).CryptBlocks(plaintext, ciphertext)
+ plaintext, err = pkcs7Unpad(plaintext)
+ if err != nil {
+ return nil, fmt.Errorf("failed to unpad: %w", err)
+ }
+ return plaintext, nil
+}
+
+// pkcs7Pad adds PKCS7 padding
+func pkcs7Pad(data []byte, blockSize int) []byte {
+ padding := blockSize - (len(data) % blockSize)
+ if padding == 0 {
+ padding = blockSize
+ }
+ padText := bytes.Repeat([]byte{byte(padding)}, padding)
+ return append(data, padText...)
+}
+
+// pkcs7Unpad removes PKCS7 padding with validation
+func pkcs7Unpad(data []byte) ([]byte, error) {
+ if len(data) == 0 {
+ return data, nil
+ }
+ padding := int(data[len(data)-1])
+ // WeCom uses 32-byte block size for PKCS7 padding
+ if padding == 0 || padding > blockSize {
+ return nil, fmt.Errorf("invalid padding size: %d", padding)
+ }
+ if padding > len(data) {
+ return nil, fmt.Errorf("padding size larger than data")
+ }
+ // Verify all padding bytes
+ for i := range padding {
+ if data[len(data)-1-i] != byte(padding) {
+ return nil, fmt.Errorf("invalid padding byte at position %d", i)
+ }
+ }
+ return data[:len(data)-padding], nil
+}
diff --git a/pkg/channels/wecom/dedupe.go b/pkg/channels/wecom/dedupe.go
new file mode 100644
index 000000000..865be668e
--- /dev/null
+++ b/pkg/channels/wecom/dedupe.go
@@ -0,0 +1,54 @@
+package wecom
+
+import "sync"
+
+const wecomMaxProcessedMessages = 1000
+
+// MessageDeduplicator provides thread-safe message deduplication using a circular queue (ring buffer)
+// combined with a hash map. This ensures fast O(1) lookups while naturally evicting the oldest
+// messages without causing "amnesia cliffs" when the limit is reached.
+type MessageDeduplicator struct {
+ mu sync.Mutex
+ msgs map[string]bool
+ ring []string
+ idx int
+ max int
+}
+
+// NewMessageDeduplicator creates a new deduplicator with the specified capacity.
+func NewMessageDeduplicator(maxEntries int) *MessageDeduplicator {
+ if maxEntries <= 0 {
+ maxEntries = wecomMaxProcessedMessages
+ }
+ return &MessageDeduplicator{
+ msgs: make(map[string]bool, maxEntries),
+ ring: make([]string, maxEntries),
+ max: maxEntries,
+ }
+}
+
+// MarkMessageProcessed marks msgID as processed and returns false for duplicates.
+func (d *MessageDeduplicator) MarkMessageProcessed(msgID string) bool {
+ d.mu.Lock()
+ defer d.mu.Unlock()
+
+ // 1. Check for duplicate
+ if d.msgs[msgID] {
+ return false
+ }
+
+ // 2. Evict the oldest message at our current ring position (if any)
+ oldestID := d.ring[d.idx]
+ if oldestID != "" {
+ delete(d.msgs, oldestID)
+ }
+
+ // 3. Store the new message
+ d.msgs[msgID] = true
+ d.ring[d.idx] = msgID
+
+ // 4. Advance the circle queue index
+ d.idx = (d.idx + 1) % d.max
+
+ return true
+}
diff --git a/pkg/channels/wecom/dedupe_test.go b/pkg/channels/wecom/dedupe_test.go
new file mode 100644
index 000000000..10dff4cfe
--- /dev/null
+++ b/pkg/channels/wecom/dedupe_test.go
@@ -0,0 +1,83 @@
+package wecom
+
+import (
+ "sync"
+ "testing"
+)
+
+func TestMessageDeduplicator_DuplicateDetection(t *testing.T) {
+ d := NewMessageDeduplicator(wecomMaxProcessedMessages)
+
+ if ok := d.MarkMessageProcessed("msg-1"); !ok {
+ t.Fatalf("first message should be accepted")
+ }
+
+ if ok := d.MarkMessageProcessed("msg-1"); ok {
+ t.Fatalf("duplicate message should be rejected")
+ }
+}
+
+func TestMessageDeduplicator_ConcurrentSameMessage(t *testing.T) {
+ d := NewMessageDeduplicator(wecomMaxProcessedMessages)
+
+ const goroutines = 64
+ var wg sync.WaitGroup
+ wg.Add(goroutines)
+
+ results := make(chan bool, goroutines)
+ for i := 0; i < goroutines; i++ {
+ go func() {
+ defer wg.Done()
+ results <- d.MarkMessageProcessed("msg-concurrent")
+ }()
+ }
+
+ wg.Wait()
+ close(results)
+
+ successes := 0
+ for ok := range results {
+ if ok {
+ successes++
+ }
+ }
+
+ if successes != 1 {
+ t.Fatalf("expected exactly 1 successful mark, got %d", successes)
+ }
+}
+
+func TestMessageDeduplicator_CircularQueueEviction(t *testing.T) {
+ // Create a deduplicator with a very small capacity to test eviction easily.
+ capacity := 3
+ d := NewMessageDeduplicator(capacity)
+
+ // Fill the queue.
+ d.MarkMessageProcessed("msg-1")
+ d.MarkMessageProcessed("msg-2")
+ d.MarkMessageProcessed("msg-3")
+
+ // At this point, the queue is full. msg-1 is the oldest.
+ if len(d.msgs) != 3 {
+ t.Fatalf("expected map size to be 3, got %d", len(d.msgs))
+ }
+
+ // This should evict msg-1 and add msg-4.
+ if ok := d.MarkMessageProcessed("msg-4"); !ok {
+ t.Fatalf("msg-4 should be accepted")
+ }
+
+ if len(d.msgs) != 3 {
+ t.Fatalf("expected map size to remain at max capacity (3), got %d", len(d.msgs))
+ }
+
+ // msg-1 should now be forgotten (evicted).
+ if ok := d.MarkMessageProcessed("msg-1"); !ok {
+ t.Fatalf("msg-1 should be accepted again because it was evicted")
+ }
+
+ // msg-2 should have been evicted when we added msg-1 back.
+ if ok := d.MarkMessageProcessed("msg-2"); !ok {
+ t.Fatalf("msg-2 should be accepted again because it was evicted")
+ }
+}
diff --git a/pkg/channels/wecom/init.go b/pkg/channels/wecom/init.go
new file mode 100644
index 000000000..bc5a70fa3
--- /dev/null
+++ b/pkg/channels/wecom/init.go
@@ -0,0 +1,19 @@
+package wecom
+
+import (
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/channels"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+ channels.RegisterFactory("wecom", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+ return NewWeComBotChannel(cfg.Channels.WeCom, b)
+ })
+ channels.RegisterFactory("wecom_app", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+ return NewWeComAppChannel(cfg.Channels.WeComApp, b)
+ })
+ channels.RegisterFactory("wecom_aibot", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+ return NewWeComAIBotChannel(cfg.Channels.WeComAIBot, b)
+ })
+}
diff --git a/pkg/channels/whatsapp/init.go b/pkg/channels/whatsapp/init.go
new file mode 100644
index 000000000..d9c2669c3
--- /dev/null
+++ b/pkg/channels/whatsapp/init.go
@@ -0,0 +1,13 @@
+package whatsapp
+
+import (
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/channels"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+ channels.RegisterFactory("whatsapp", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+ return NewWhatsAppChannel(cfg.Channels.WhatsApp, b)
+ })
+}
diff --git a/pkg/channels/whatsapp.go b/pkg/channels/whatsapp/whatsapp.go
similarity index 54%
rename from pkg/channels/whatsapp.go
rename to pkg/channels/whatsapp/whatsapp.go
index 2dc4017ac..70b3e02bf 100644
--- a/pkg/channels/whatsapp.go
+++ b/pkg/channels/whatsapp/whatsapp.go
@@ -1,31 +1,42 @@
-package channels
+package whatsapp
import (
"context"
"encoding/json"
"fmt"
- "log"
"sync"
"time"
"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"
"github.com/sipeed/picoclaw/pkg/utils"
)
type WhatsAppChannel struct {
- *BaseChannel
+ *channels.BaseChannel
conn *websocket.Conn
config config.WhatsAppConfig
url string
+ ctx context.Context
+ cancel context.CancelFunc
mu sync.Mutex
connected bool
}
func NewWhatsAppChannel(cfg config.WhatsAppConfig, bus *bus.MessageBus) (*WhatsAppChannel, error) {
- base := NewBaseChannel("whatsapp", cfg, bus, cfg.AllowFrom)
+ base := channels.NewBaseChannel(
+ "whatsapp",
+ cfg,
+ bus,
+ cfg.AllowFrom,
+ channels.WithMaxMessageLength(65536),
+ channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+ )
return &WhatsAppChannel{
BaseChannel: base,
@@ -36,7 +47,11 @@ func NewWhatsAppChannel(cfg config.WhatsAppConfig, bus *bus.MessageBus) (*WhatsA
}
func (c *WhatsAppChannel) Start(ctx context.Context) error {
- log.Printf("Starting WhatsApp channel connecting to %s...", c.url)
+ logger.InfoCF("whatsapp", "Starting WhatsApp channel", map[string]any{
+ "bridge_url": c.url,
+ })
+
+ c.ctx, c.cancel = context.WithCancel(ctx)
dialer := websocket.DefaultDialer
dialer.HandshakeTimeout = 10 * time.Second
@@ -46,6 +61,7 @@ func (c *WhatsAppChannel) Start(ctx context.Context) error {
resp.Body.Close()
}
if err != nil {
+ c.cancel()
return fmt.Errorf("failed to connect to WhatsApp bridge: %w", err)
}
@@ -54,39 +70,57 @@ func (c *WhatsAppChannel) Start(ctx context.Context) error {
c.connected = true
c.mu.Unlock()
- c.setRunning(true)
- log.Println("WhatsApp channel connected")
+ c.SetRunning(true)
+ logger.InfoC("whatsapp", "WhatsApp channel connected")
- go c.listen(ctx)
+ go c.listen()
return nil
}
func (c *WhatsAppChannel) Stop(ctx context.Context) error {
- log.Println("Stopping WhatsApp channel...")
+ logger.InfoC("whatsapp", "Stopping WhatsApp channel...")
+
+ // Cancel context first to signal listen goroutine to exit
+ if c.cancel != nil {
+ c.cancel()
+ }
c.mu.Lock()
defer c.mu.Unlock()
if c.conn != nil {
if err := c.conn.Close(); err != nil {
- log.Printf("Error closing WhatsApp connection: %v", err)
+ logger.ErrorCF("whatsapp", "Error closing WhatsApp connection", map[string]any{
+ "error": err.Error(),
+ })
}
c.conn = nil
}
c.connected = false
- c.setRunning(false)
+ c.SetRunning(false)
return nil
}
func (c *WhatsAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+ if !c.IsRunning() {
+ return channels.ErrNotRunning
+ }
+
+ // Check ctx before acquiring lock
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ default:
+ }
+
c.mu.Lock()
defer c.mu.Unlock()
if c.conn == nil {
- return fmt.Errorf("whatsapp connection not established")
+ return fmt.Errorf("whatsapp connection not established: %w", channels.ErrTemporary)
}
payload := map[string]any{
@@ -100,17 +134,20 @@ func (c *WhatsAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
return fmt.Errorf("failed to marshal message: %w", err)
}
+ _ = c.conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
if err := c.conn.WriteMessage(websocket.TextMessage, data); err != nil {
- return fmt.Errorf("failed to send message: %w", err)
+ _ = c.conn.SetWriteDeadline(time.Time{})
+ return fmt.Errorf("whatsapp send: %w", channels.ErrTemporary)
}
+ _ = c.conn.SetWriteDeadline(time.Time{})
return nil
}
-func (c *WhatsAppChannel) listen(ctx context.Context) {
+func (c *WhatsAppChannel) listen() {
for {
select {
- case <-ctx.Done():
+ case <-c.ctx.Done():
return
default:
c.mu.Lock()
@@ -124,14 +161,18 @@ func (c *WhatsAppChannel) listen(ctx context.Context) {
_, message, err := conn.ReadMessage()
if err != nil {
- log.Printf("WhatsApp read error: %v", err)
+ logger.ErrorCF("whatsapp", "WhatsApp read error", map[string]any{
+ "error": err.Error(),
+ })
time.Sleep(2 * time.Second)
continue
}
var msg map[string]any
if err := json.Unmarshal(message, &msg); err != nil {
- log.Printf("Failed to unmarshal WhatsApp message: %v", err)
+ logger.ErrorCF("whatsapp", "Failed to unmarshal WhatsApp message", map[string]any{
+ "error": err.Error(),
+ })
continue
}
@@ -174,22 +215,38 @@ func (c *WhatsAppChannel) handleIncomingMessage(msg map[string]any) {
}
metadata := make(map[string]string)
- if messageID, ok := msg["id"].(string); ok {
- metadata["message_id"] = messageID
+ var messageID string
+ if mid, ok := msg["id"].(string); ok {
+ messageID = mid
}
if userName, ok := msg["from_name"].(string); ok {
metadata["user_name"] = userName
}
+ var peer bus.Peer
if chatID == senderID {
- metadata["peer_kind"] = "direct"
- metadata["peer_id"] = senderID
+ peer = bus.Peer{Kind: "direct", ID: senderID}
} else {
- metadata["peer_kind"] = "group"
- metadata["peer_id"] = chatID
+ peer = bus.Peer{Kind: "group", ID: chatID}
}
- log.Printf("WhatsApp message from %s: %s...", senderID, utils.Truncate(content, 50))
+ logger.InfoCF("whatsapp", "WhatsApp message received", map[string]any{
+ "sender": senderID,
+ "preview": utils.Truncate(content, 50),
+ })
- c.HandleMessage(senderID, chatID, content, mediaPaths, metadata)
+ sender := bus.SenderInfo{
+ Platform: "whatsapp",
+ PlatformID: senderID,
+ CanonicalID: identity.BuildCanonicalID("whatsapp", senderID),
+ }
+ if display, ok := metadata["user_name"]; ok {
+ sender.DisplayName = display
+ }
+
+ if !c.IsAllowedSender(sender) {
+ return
+ }
+
+ c.HandleMessage(c.ctx, peer, messageID, senderID, chatID, content, mediaPaths, metadata, sender)
}
diff --git a/pkg/channels/whatsapp_native/init.go b/pkg/channels/whatsapp_native/init.go
new file mode 100644
index 000000000..df13e8539
--- /dev/null
+++ b/pkg/channels/whatsapp_native/init.go
@@ -0,0 +1,20 @@
+package whatsapp
+
+import (
+ "path/filepath"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/channels"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+ channels.RegisterFactory("whatsapp_native", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+ waCfg := cfg.Channels.WhatsApp
+ storePath := waCfg.SessionStorePath
+ if storePath == "" {
+ storePath = filepath.Join(cfg.WorkspacePath(), "whatsapp")
+ }
+ return NewWhatsAppNativeChannel(waCfg, b, storePath)
+ })
+}
diff --git a/pkg/channels/whatsapp_native/whatsapp_native.go b/pkg/channels/whatsapp_native/whatsapp_native.go
new file mode 100644
index 000000000..188a7c8fa
--- /dev/null
+++ b/pkg/channels/whatsapp_native/whatsapp_native.go
@@ -0,0 +1,448 @@
+//go:build whatsapp_native
+
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package whatsapp
+
+import (
+ "context"
+ "database/sql"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/mdp/qrterminal/v3"
+ "go.mau.fi/whatsmeow"
+ "go.mau.fi/whatsmeow/proto/waE2E"
+ "go.mau.fi/whatsmeow/store/sqlstore"
+ "go.mau.fi/whatsmeow/types"
+ "go.mau.fi/whatsmeow/types/events"
+ waLog "go.mau.fi/whatsmeow/util/log"
+ "google.golang.org/protobuf/proto"
+ _ "modernc.org/sqlite"
+
+ "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"
+ "github.com/sipeed/picoclaw/pkg/utils"
+)
+
+const (
+ sqliteDriver = "sqlite"
+ whatsappDBName = "store.db"
+
+ reconnectInitial = 5 * time.Second
+ reconnectMax = 5 * time.Minute
+ reconnectMultiplier = 2.0
+)
+
+// WhatsAppNativeChannel implements the WhatsApp channel using whatsmeow (in-process, no external bridge).
+type WhatsAppNativeChannel struct {
+ *channels.BaseChannel
+ config config.WhatsAppConfig
+ storePath string
+ client *whatsmeow.Client
+ container *sqlstore.Container
+ mu sync.Mutex
+ runCtx context.Context
+ runCancel context.CancelFunc
+ reconnectMu sync.Mutex
+ reconnecting bool
+ stopping atomic.Bool // set once Stop begins; prevents new wg.Add calls
+ wg sync.WaitGroup // tracks background goroutines (QR handler, reconnect)
+}
+
+// NewWhatsAppNativeChannel creates a WhatsApp channel that uses whatsmeow for connection.
+// storePath is the directory for the SQLite session store (e.g. workspace/whatsapp).
+func NewWhatsAppNativeChannel(
+ cfg config.WhatsAppConfig,
+ bus *bus.MessageBus,
+ storePath string,
+) (channels.Channel, error) {
+ base := channels.NewBaseChannel("whatsapp_native", cfg, bus, cfg.AllowFrom, channels.WithMaxMessageLength(65536))
+ if storePath == "" {
+ storePath = "whatsapp"
+ }
+ c := &WhatsAppNativeChannel{
+ BaseChannel: base,
+ config: cfg,
+ storePath: storePath,
+ }
+ return c, nil
+}
+
+func (c *WhatsAppNativeChannel) Start(ctx context.Context) error {
+ logger.InfoCF("whatsapp", "Starting WhatsApp native channel (whatsmeow)", map[string]any{"store": c.storePath})
+
+ // Reset lifecycle state from any previous Stop() so a restarted channel
+ // behaves correctly. Use reconnectMu to be consistent with eventHandler
+ // and Stop() which coordinate under the same lock.
+ c.reconnectMu.Lock()
+ c.stopping.Store(false)
+ c.reconnecting = false
+ c.reconnectMu.Unlock()
+
+ if err := os.MkdirAll(c.storePath, 0o700); err != nil {
+ return fmt.Errorf("create session store dir: %w", err)
+ }
+
+ dbPath := filepath.Join(c.storePath, whatsappDBName)
+ connStr := "file:" + dbPath + "?_foreign_keys=on"
+
+ db, err := sql.Open(sqliteDriver, connStr)
+ if err != nil {
+ return fmt.Errorf("open whatsapp store: %w", err)
+ }
+ db.SetMaxOpenConns(1)
+ db.SetMaxIdleConns(1)
+ if _, err = db.ExecContext(ctx, "PRAGMA foreign_keys = ON"); err != nil {
+ _ = db.Close()
+ return fmt.Errorf("enable foreign keys: %w", err)
+ }
+
+ waLogger := waLog.Stdout("WhatsApp", "WARN", true)
+ container := sqlstore.NewWithDB(db, sqliteDriver, waLogger)
+ if err = container.Upgrade(ctx); err != nil {
+ _ = db.Close()
+ return fmt.Errorf("open whatsapp store: %w", err)
+ }
+
+ deviceStore, err := container.GetFirstDevice(ctx)
+ if err != nil {
+ _ = container.Close()
+ return fmt.Errorf("get device store: %w", err)
+ }
+
+ client := whatsmeow.NewClient(deviceStore, waLogger)
+
+ // Create runCtx/runCancel BEFORE registering event handler and starting
+ // goroutines so that Stop() can cancel them at any time, including during
+ // the QR-login flow.
+ c.runCtx, c.runCancel = context.WithCancel(ctx)
+
+ client.AddEventHandler(c.eventHandler)
+
+ c.mu.Lock()
+ c.container = container
+ c.client = client
+ c.mu.Unlock()
+
+ // cleanupOnError clears struct references and releases resources when
+ // Start() fails after fields are already assigned. This prevents
+ // Stop() from operating on stale references (double-close, disconnect
+ // of a partially-initialized client, or stray event handler callbacks).
+ startOK := false
+ defer func() {
+ if startOK {
+ return
+ }
+ c.runCancel()
+ client.Disconnect()
+ c.mu.Lock()
+ c.client = nil
+ c.container = nil
+ c.mu.Unlock()
+ _ = container.Close()
+ }()
+
+ if client.Store.ID == nil {
+ qrChan, err := client.GetQRChannel(c.runCtx)
+ if err != nil {
+ return fmt.Errorf("get QR channel: %w", err)
+ }
+ if err := client.Connect(); err != nil {
+ return fmt.Errorf("connect: %w", err)
+ }
+ // Handle QR events in a background goroutine so Start() returns
+ // promptly. The goroutine is tracked via c.wg and respects
+ // c.runCtx for cancellation.
+ // Guard wg.Add with reconnectMu + stopping check (same protocol
+ // as eventHandler) so a concurrent Stop() cannot enter wg.Wait()
+ // while we call wg.Add(1).
+ c.reconnectMu.Lock()
+ if c.stopping.Load() {
+ c.reconnectMu.Unlock()
+ return fmt.Errorf("channel stopped during QR setup")
+ }
+ c.wg.Add(1)
+ c.reconnectMu.Unlock()
+ go func() {
+ defer c.wg.Done()
+ for {
+ select {
+ case <-c.runCtx.Done():
+ return
+ case evt, ok := <-qrChan:
+ if !ok {
+ return
+ }
+ if evt.Event == "code" {
+ logger.InfoCF("whatsapp", "Scan this QR code with WhatsApp (Linked Devices):", nil)
+ qrterminal.GenerateWithConfig(evt.Code, qrterminal.Config{
+ Level: qrterminal.L,
+ Writer: os.Stdout,
+ HalfBlocks: true,
+ })
+ } else {
+ logger.InfoCF("whatsapp", "WhatsApp login event", map[string]any{"event": evt.Event})
+ }
+ }
+ }
+ }()
+ } else {
+ if err := client.Connect(); err != nil {
+ return fmt.Errorf("connect: %w", err)
+ }
+ }
+
+ startOK = true
+ c.SetRunning(true)
+ logger.InfoC("whatsapp", "WhatsApp native channel connected")
+ return nil
+}
+
+func (c *WhatsAppNativeChannel) Stop(ctx context.Context) error {
+ logger.InfoC("whatsapp", "Stopping WhatsApp native channel")
+
+ // Mark as stopping under reconnectMu so the flag is visible to
+ // eventHandler atomically with respect to its wg.Add(1) call.
+ // This closes the TOCTOU window where eventHandler could check
+ // stopping (false), then Stop sets it true + enters wg.Wait,
+ // then eventHandler calls wg.Add(1) — causing a panic.
+ c.reconnectMu.Lock()
+ c.stopping.Store(true)
+ c.reconnectMu.Unlock()
+
+ if c.runCancel != nil {
+ c.runCancel()
+ }
+
+ // Disconnect the client first so any blocking Connect()/reconnect loops
+ // can be interrupted before we wait on the goroutines.
+ c.mu.Lock()
+ client := c.client
+ container := c.container
+ c.mu.Unlock()
+
+ if client != nil {
+ client.Disconnect()
+ }
+
+ // Wait for background goroutines (QR handler, reconnect) to finish in a
+ // context-aware way so Stop can be bounded by ctx.
+ done := make(chan struct{})
+ go func() {
+ c.wg.Wait()
+ close(done)
+ }()
+
+ select {
+ case <-done:
+ // All goroutines have finished.
+ case <-ctx.Done():
+ // Context canceled or timed out; log and proceed with best-effort cleanup.
+ logger.WarnC("whatsapp", fmt.Sprintf("Stop context canceled before all goroutines finished: %v", ctx.Err()))
+ }
+
+ // Now it is safe to clear and close resources.
+ c.mu.Lock()
+ c.client = nil
+ c.container = nil
+ c.mu.Unlock()
+
+ if container != nil {
+ _ = container.Close()
+ }
+ c.SetRunning(false)
+ return nil
+}
+
+func (c *WhatsAppNativeChannel) eventHandler(evt any) {
+ switch evt.(type) {
+ case *events.Message:
+ c.handleIncoming(evt.(*events.Message))
+ case *events.Disconnected:
+ logger.InfoCF("whatsapp", "WhatsApp disconnected, will attempt reconnection", nil)
+ c.reconnectMu.Lock()
+ if c.reconnecting {
+ c.reconnectMu.Unlock()
+ return
+ }
+ // Check stopping while holding the lock so the check and wg.Add
+ // are atomic with respect to Stop() setting the flag + calling
+ // wg.Wait(). This prevents the TOCTOU race.
+ if c.stopping.Load() {
+ c.reconnectMu.Unlock()
+ return
+ }
+ c.reconnecting = true
+ c.wg.Add(1)
+ c.reconnectMu.Unlock()
+ go func() {
+ defer c.wg.Done()
+ c.reconnectWithBackoff()
+ }()
+ }
+}
+
+func (c *WhatsAppNativeChannel) reconnectWithBackoff() {
+ defer func() {
+ c.reconnectMu.Lock()
+ c.reconnecting = false
+ c.reconnectMu.Unlock()
+ }()
+
+ backoff := reconnectInitial
+ for {
+ select {
+ case <-c.runCtx.Done():
+ return
+ default:
+ }
+
+ c.mu.Lock()
+ client := c.client
+ c.mu.Unlock()
+ if client == nil {
+ return
+ }
+
+ logger.InfoCF("whatsapp", "WhatsApp reconnecting", map[string]any{"backoff": backoff.String()})
+ err := client.Connect()
+ if err == nil {
+ logger.InfoC("whatsapp", "WhatsApp reconnected")
+ return
+ }
+
+ logger.WarnCF("whatsapp", "WhatsApp reconnect failed", map[string]any{"error": err.Error()})
+
+ select {
+ case <-c.runCtx.Done():
+ return
+ case <-time.After(backoff):
+ if backoff < reconnectMax {
+ next := time.Duration(float64(backoff) * reconnectMultiplier)
+ if next > reconnectMax {
+ next = reconnectMax
+ }
+ backoff = next
+ }
+ }
+ }
+}
+
+func (c *WhatsAppNativeChannel) handleIncoming(evt *events.Message) {
+ if evt.Message == nil {
+ return
+ }
+ senderID := evt.Info.Sender.String()
+ chatID := evt.Info.Chat.String()
+ content := evt.Message.GetConversation()
+ if content == "" && evt.Message.ExtendedTextMessage != nil {
+ content = evt.Message.ExtendedTextMessage.GetText()
+ }
+ content = utils.SanitizeMessageContent(content)
+
+ if content == "" {
+ return
+ }
+
+ var mediaPaths []string
+
+ metadata := make(map[string]string)
+ metadata["message_id"] = evt.Info.ID
+ if evt.Info.PushName != "" {
+ metadata["user_name"] = evt.Info.PushName
+ }
+ if evt.Info.Chat.Server == types.GroupServer {
+ metadata["peer_kind"] = "group"
+ metadata["peer_id"] = chatID
+ } else {
+ metadata["peer_kind"] = "direct"
+ metadata["peer_id"] = senderID
+ }
+
+ peerKind := "direct"
+ if evt.Info.Chat.Server == types.GroupServer {
+ peerKind = "group"
+ }
+ peer := bus.Peer{Kind: peerKind, ID: chatID}
+ messageID := evt.Info.ID
+ sender := bus.SenderInfo{
+ Platform: "whatsapp",
+ PlatformID: senderID,
+ CanonicalID: identity.BuildCanonicalID("whatsapp", senderID),
+ DisplayName: evt.Info.PushName,
+ }
+
+ if !c.IsAllowedSender(sender) {
+ return
+ }
+
+ logger.DebugCF(
+ "whatsapp",
+ "WhatsApp message received",
+ map[string]any{"sender_id": senderID, "content_preview": utils.Truncate(content, 50)},
+ )
+ c.HandleMessage(c.runCtx, peer, messageID, senderID, chatID, content, mediaPaths, metadata, sender)
+}
+
+func (c *WhatsAppNativeChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+ if !c.IsRunning() {
+ return channels.ErrNotRunning
+ }
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ default:
+ }
+
+ c.mu.Lock()
+ client := c.client
+ c.mu.Unlock()
+
+ if client == nil || !client.IsConnected() {
+ return fmt.Errorf("whatsapp connection not established: %w", channels.ErrTemporary)
+ }
+
+ // Detect unpaired state: the client is connected (to WhatsApp servers)
+ // but has not completed QR-login yet, so sending would fail.
+ if client.Store.ID == nil {
+ return fmt.Errorf("whatsapp not yet paired (QR login pending): %w", channels.ErrTemporary)
+ }
+
+ to, err := parseJID(msg.ChatID)
+ if err != nil {
+ return fmt.Errorf("invalid chat id %q: %w", msg.ChatID, err)
+ }
+
+ waMsg := &waE2E.Message{
+ Conversation: proto.String(msg.Content),
+ }
+
+ if _, err = client.SendMessage(ctx, to, waMsg); err != nil {
+ return fmt.Errorf("whatsapp send: %w", channels.ErrTemporary)
+ }
+ return nil
+}
+
+// parseJID converts a chat ID (phone number or JID string) to types.JID.
+func parseJID(s string) (types.JID, error) {
+ s = strings.TrimSpace(s)
+ if s == "" {
+ return types.JID{}, fmt.Errorf("empty chat id")
+ }
+ if strings.Contains(s, "@") {
+ return types.ParseJID(s)
+ }
+ return types.NewJID(s, types.DefaultUserServer), nil
+}
diff --git a/pkg/channels/whatsapp_native/whatsapp_native_stub.go b/pkg/channels/whatsapp_native/whatsapp_native_stub.go
new file mode 100644
index 000000000..984af23e7
--- /dev/null
+++ b/pkg/channels/whatsapp_native/whatsapp_native_stub.go
@@ -0,0 +1,21 @@
+//go:build !whatsapp_native
+
+package whatsapp
+
+import (
+ "fmt"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+ "github.com/sipeed/picoclaw/pkg/channels"
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+// NewWhatsAppNativeChannel returns an error when the binary was not built with -tags whatsapp_native.
+// Build with: go build -tags whatsapp_native ./cmd/...
+func NewWhatsAppNativeChannel(
+ cfg config.WhatsAppConfig,
+ bus *bus.MessageBus,
+ storePath string,
+) (channels.Channel, error) {
+ return nil, fmt.Errorf("whatsapp native not compiled in; build with -tags whatsapp_native")
+}
diff --git a/pkg/config/config.go b/pkg/config/config.go
index f7c78136b..6cabddafc 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -4,10 +4,11 @@ import (
"encoding/json"
"fmt"
"os"
- "path/filepath"
"sync/atomic"
"github.com/caarlos0/env/v11"
+
+ "github.com/sipeed/picoclaw/pkg/fileutil"
)
// rrCounter is a global counter for round-robin load balancing across models.
@@ -167,17 +168,30 @@ type SessionConfig struct {
}
type AgentDefaults struct {
- Workspace string `json:"workspace" env:"PICOCLAW_AGENTS_DEFAULTS_WORKSPACE"`
- RestrictToWorkspace bool `json:"restrict_to_workspace" env:"PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_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,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"`
- Temperature *float64 `json:"temperature,omitempty" env:"PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE"`
- MaxToolIterations int `json:"max_tool_iterations" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS"`
+ 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"`
+}
+
+const DefaultMaxMediaSize = 20 * 1024 * 1024 // 20 MB
+
+func (d *AgentDefaults) GetMaxMediaSize() int {
+ if d.MaxMediaSize > 0 {
+ return d.MaxMediaSize
+ }
+ return DefaultMaxMediaSize
}
// GetModelName returns the effective model name for the agent defaults.
@@ -190,120 +204,201 @@ func (d *AgentDefaults) GetModelName() string {
}
type ChannelsConfig struct {
- WhatsApp WhatsAppConfig `json:"whatsapp"`
- Telegram TelegramConfig `json:"telegram"`
- Feishu FeishuConfig `json:"feishu"`
- Discord DiscordConfig `json:"discord"`
- MaixCam MaixCamConfig `json:"maixcam"`
- QQ QQConfig `json:"qq"`
- DingTalk DingTalkConfig `json:"dingtalk"`
- Slack SlackConfig `json:"slack"`
- LINE LINEConfig `json:"line"`
- OneBot OneBotConfig `json:"onebot"`
- WeCom WeComConfig `json:"wecom"`
- WeComApp WeComAppConfig `json:"wecom_app"`
+ WhatsApp WhatsAppConfig `json:"whatsapp"`
+ Telegram TelegramConfig `json:"telegram"`
+ Feishu FeishuConfig `json:"feishu"`
+ Discord DiscordConfig `json:"discord"`
+ MaixCam MaixCamConfig `json:"maixcam"`
+ QQ QQConfig `json:"qq"`
+ DingTalk DingTalkConfig `json:"dingtalk"`
+ Slack SlackConfig `json:"slack"`
+ LINE LINEConfig `json:"line"`
+ OneBot OneBotConfig `json:"onebot"`
+ WeCom WeComConfig `json:"wecom"`
+ WeComApp WeComAppConfig `json:"wecom_app"`
+ WeComAIBot WeComAIBotConfig `json:"wecom_aibot"`
+ Pico PicoConfig `json:"pico"`
+}
+
+// GroupTriggerConfig controls when the bot responds in group chats.
+type GroupTriggerConfig struct {
+ MentionOnly bool `json:"mention_only,omitempty"`
+ Prefixes []string `json:"prefixes,omitempty"`
+}
+
+// TypingConfig controls typing indicator behavior (Phase 10).
+type TypingConfig struct {
+ Enabled bool `json:"enabled,omitempty"`
+}
+
+// PlaceholderConfig controls placeholder message behavior (Phase 10).
+type PlaceholderConfig struct {
+ Enabled bool `json:"enabled,omitempty"`
+ Text string `json:"text,omitempty"`
}
type WhatsAppConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WHATSAPP_ENABLED"`
- BridgeURL string `json:"bridge_url" env:"PICOCLAW_CHANNELS_WHATSAPP_BRIDGE_URL"`
- AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WHATSAPP_ALLOW_FROM"`
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WHATSAPP_ENABLED"`
+ BridgeURL string `json:"bridge_url" env:"PICOCLAW_CHANNELS_WHATSAPP_BRIDGE_URL"`
+ UseNative bool `json:"use_native" env:"PICOCLAW_CHANNELS_WHATSAPP_USE_NATIVE"`
+ SessionStorePath string `json:"session_store_path" env:"PICOCLAW_CHANNELS_WHATSAPP_SESSION_STORE_PATH"`
+ AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WHATSAPP_ALLOW_FROM"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WHATSAPP_REASONING_CHANNEL_ID"`
}
type TelegramConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
- Token string `json:"token" env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
- Proxy string `json:"proxy" env:"PICOCLAW_CHANNELS_TELEGRAM_PROXY"`
- AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_TELEGRAM_ALLOW_FROM"`
+ 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"`
}
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"`
- AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
+ 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"`
}
type DiscordConfig struct {
- Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
- Token string `json:"token" env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
- AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_DISCORD_ALLOW_FROM"`
- MentionOnly bool `json:"mention_only" env:"PICOCLAW_CHANNELS_DISCORD_MENTION_ONLY"`
+ 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"`
}
type MaixCamConfig 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"`
+ 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"`
}
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"`
- AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_QQ_ALLOW_FROM"`
+ 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"`
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_QQ_REASONING_CHANNEL_ID"`
}
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"`
- AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_DINGTALK_ALLOW_FROM"`
+ 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"`
}
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"`
- AllowFrom FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_SLACK_ALLOW_FROM"`
+ 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"`
}
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"`
- 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"`
+ 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"`
}
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"`
- 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"`
+ 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"`
}
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"`
- 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"`
+ 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"`
}
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"`
- 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"`
+ 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"`
+}
+
+type WeComAIBotConfig struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ENABLED"`
+ Token string `json:"token" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_TOKEN"`
+ 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"` // Maximum streaming steps
+ WelcomeMessage string `json:"welcome_message" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WELCOME_MESSAGE"` // Sent on enter_chat event; empty = no welcome
+ ReasoningChannelID string `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REASONING_CHANNEL_ID"`
+}
+
+type PicoConfig 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"`
}
type HeartbeatConfig struct {
@@ -319,6 +414,7 @@ type DevicesConfig struct {
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"`
@@ -342,6 +438,7 @@ type ProvidersConfig struct {
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 == "" &&
@@ -371,11 +468,12 @@ func (p ProvidersConfig) MarshalJSON() ([]byte, error) {
}
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"`
- 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`
+ 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 {
@@ -406,6 +504,7 @@ type ModelConfig struct {
// 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"`
}
// Validate checks if the ModelConfig has all required fields.
@@ -454,15 +553,27 @@ type SearXNGConfig struct {
MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_SEARXNG_MAX_RESULTS"`
}
+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"`
+ // 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"`
+}
+
type WebToolsConfig struct {
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"`
// Proxy is an optional proxy URL for web tools (http/https/socks5/socks5h).
// For authenticated proxies, prefer HTTP_PROXY/HTTPS_PROXY env vars instead of embedding credentials in config.
- Proxy string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_WEB_PROXY"`
+ Proxy string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_WEB_PROXY"`
+ FetchLimitBytes int64 `json:"fetch_limit_bytes,omitempty" env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"`
}
type CronToolsConfig struct {
@@ -470,15 +581,26 @@ type CronToolsConfig struct {
}
type ExecConfig struct {
- EnableDenyPatterns bool `json:"enable_deny_patterns" env:"PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS"`
- CustomDenyPatterns []string `json:"custom_deny_patterns" env:"PICOCLAW_TOOLS_EXEC_CUSTOM_DENY_PATTERNS"`
+ EnableDenyPatterns bool `json:"enable_deny_patterns" env:"PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS"`
+ CustomDenyPatterns []string `json:"custom_deny_patterns" env:"PICOCLAW_TOOLS_EXEC_CUSTOM_DENY_PATTERNS"`
+ CustomAllowPatterns []string `json:"custom_allow_patterns" env:"PICOCLAW_TOOLS_EXEC_CUSTOM_ALLOW_PATTERNS"`
+}
+
+type MediaCleanupConfig struct {
+ Enabled bool `json:"enabled" env:"PICOCLAW_MEDIA_CLEANUP_ENABLED"`
+ MaxAge int `json:"max_age_minutes" env:"PICOCLAW_MEDIA_CLEANUP_MAX_AGE"`
+ Interval int `json:"interval_minutes" env:"PICOCLAW_MEDIA_CLEANUP_INTERVAL"`
}
type ToolsConfig struct {
- Web WebToolsConfig `json:"web"`
- Cron CronToolsConfig `json:"cron"`
- Exec ExecConfig `json:"exec"`
- Skills SkillsToolsConfig `json:"skills"`
+ 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 WebToolsConfig `json:"web"`
+ Cron CronToolsConfig `json:"cron"`
+ Exec ExecConfig `json:"exec"`
+ Skills SkillsToolsConfig `json:"skills"`
+ MediaCleanup MediaCleanupConfig `json:"media_cleanup"`
+ MCP MCPConfig `json:"mcp"`
}
type SkillsToolsConfig struct {
@@ -508,6 +630,34 @@ type ClawHubRegistryConfig struct {
MaxResponseSize int `json:"max_response_size" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_MAX_RESPONSE_SIZE"`
}
+// MCPServerConfig defines configuration for a single MCP server
+type MCPServerConfig struct {
+ // Enabled indicates whether this MCP server is active
+ Enabled bool `json:"enabled"`
+ // Command is the executable to run (e.g., "npx", "python", "/path/to/server")
+ Command string `json:"command"`
+ // Args are the arguments to pass to the command
+ Args []string `json:"args,omitempty"`
+ // Env are environment variables to set for the server process (stdio only)
+ Env map[string]string `json:"env,omitempty"`
+ // EnvFile is the path to a file containing environment variables (stdio only)
+ EnvFile string `json:"env_file,omitempty"`
+ // Type is "stdio", "sse", or "http" (default: stdio if command is set, sse if url is set)
+ Type string `json:"type,omitempty"`
+ // URL is used for SSE/HTTP transport
+ URL string `json:"url,omitempty"`
+ // Headers are HTTP headers to send with requests (sse/http only)
+ Headers map[string]string `json:"headers,omitempty"`
+}
+
+// MCPConfig defines configuration for all MCP servers
+type MCPConfig struct {
+ // Enabled globally enables/disables MCP integration
+ Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_MCP_ENABLED"`
+ // Servers is a map of server name to server configuration
+ Servers map[string]MCPServerConfig `json:"servers,omitempty"`
+}
+
func LoadConfig(path string) (*Config, error) {
cfg := DefaultConfig()
@@ -541,6 +691,9 @@ func LoadConfig(path string) (*Config, error) {
return nil, err
}
+ // 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)
@@ -554,18 +707,27 @@ func LoadConfig(path string) (*Config, error) {
return cfg, nil
}
+func (c *Config) 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 SaveConfig(path string, cfg *Config) error {
data, err := json.MarshalIndent(cfg, "", " ")
if err != nil {
return err
}
- dir := filepath.Dir(path)
- if err := os.MkdirAll(dir, 0o755); err != nil {
- return err
- }
-
- return os.WriteFile(path, data, 0o600)
+ // Use unified atomic write utility with explicit sync for flash storage reliability.
+ return fileutil.WriteFileAtomic(path, data, 0o600)
}
func (c *Config) WorkspacePath() string {
@@ -663,25 +825,7 @@ func (c *Config) findMatches(modelName string) []ModelConfig {
// HasProvidersConfig checks if any provider in the old providers config has configuration.
func (c *Config) HasProvidersConfig() bool {
- v := c.Providers
- return v.Anthropic.APIKey != "" || v.Anthropic.APIBase != "" ||
- v.OpenAI.APIKey != "" || v.OpenAI.APIBase != "" ||
- v.OpenRouter.APIKey != "" || v.OpenRouter.APIBase != "" ||
- v.Groq.APIKey != "" || v.Groq.APIBase != "" ||
- v.Zhipu.APIKey != "" || v.Zhipu.APIBase != "" ||
- v.VLLM.APIKey != "" || v.VLLM.APIBase != "" ||
- v.Gemini.APIKey != "" || v.Gemini.APIBase != "" ||
- v.Nvidia.APIKey != "" || v.Nvidia.APIBase != "" ||
- v.Ollama.APIKey != "" || v.Ollama.APIBase != "" ||
- v.Moonshot.APIKey != "" || v.Moonshot.APIBase != "" ||
- v.ShengSuanYun.APIKey != "" || v.ShengSuanYun.APIBase != "" ||
- v.DeepSeek.APIKey != "" || v.DeepSeek.APIBase != "" ||
- v.Cerebras.APIKey != "" || v.Cerebras.APIBase != "" ||
- v.VolcEngine.APIKey != "" || v.VolcEngine.APIBase != "" ||
- v.GitHubCopilot.APIKey != "" || v.GitHubCopilot.APIBase != "" ||
- v.Antigravity.APIKey != "" || v.Antigravity.APIBase != "" ||
- v.Qwen.APIKey != "" || v.Qwen.APIBase != "" ||
- v.Mistral.APIKey != "" || v.Mistral.APIBase != ""
+ return !c.Providers.IsEmpty()
}
// ValidateModelList validates all ModelConfig entries in the model_list.
diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go
index 223ac798d..10ebc7c90 100644
--- a/pkg/config/config_test.go
+++ b/pkg/config/config_test.go
@@ -5,6 +5,7 @@ import (
"os"
"path/filepath"
"runtime"
+ "strings"
"testing"
)
@@ -210,8 +211,8 @@ func TestDefaultConfig_WorkspacePath(t *testing.T) {
func TestDefaultConfig_Model(t *testing.T) {
cfg := DefaultConfig()
- if cfg.Agents.Defaults.Model == "" {
- t.Error("Model should not be empty")
+ if cfg.Agents.Defaults.Model != "" {
+ t.Error("Model should be empty")
}
}
@@ -324,6 +325,25 @@ func TestSaveConfig_FilePermissions(t *testing.T) {
}
}
+func TestSaveConfig_IncludesEmptyLegacyModelField(t *testing.T) {
+ tmpDir := t.TempDir()
+ path := filepath.Join(tmpDir, "config.json")
+
+ cfg := DefaultConfig()
+ if err := SaveConfig(path, cfg); err != nil {
+ t.Fatalf("SaveConfig failed: %v", err)
+ }
+
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("ReadFile failed: %v", err)
+ }
+
+ if !strings.Contains(string(data), `"model": ""`) {
+ t.Fatalf("saved config should include empty legacy model field, got: %s", string(data))
+ }
+}
+
// TestConfig_Complete verifies all config fields are set
func TestConfig_Complete(t *testing.T) {
cfg := DefaultConfig()
@@ -331,8 +351,8 @@ 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 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")
@@ -413,3 +433,49 @@ func TestLoadConfig_WebToolsProxy(t *testing.T) {
t.Fatalf("Tools.Web.Proxy = %q, want %q", cfg.Tools.Web.Proxy, "http://127.0.0.1:7890")
}
}
+
+// TestDefaultConfig_DMScope verifies the default dm_scope value
+// TestDefaultConfig_SummarizationThresholds verifies summarization defaults
+func TestDefaultConfig_SummarizationThresholds(t *testing.T) {
+ cfg := DefaultConfig()
+
+ if cfg.Agents.Defaults.SummarizeMessageThreshold != 20 {
+ t.Errorf("SummarizeMessageThreshold = %d, want 20", cfg.Agents.Defaults.SummarizeMessageThreshold)
+ }
+ if cfg.Agents.Defaults.SummarizeTokenPercent != 75 {
+ t.Errorf("SummarizeTokenPercent = %d, want 75", cfg.Agents.Defaults.SummarizeTokenPercent)
+ }
+}
+
+func TestDefaultConfig_DMScope(t *testing.T) {
+ cfg := DefaultConfig()
+
+ if cfg.Session.DMScope != "per-channel-peer" {
+ t.Errorf("Session.DMScope = %q, want 'per-channel-peer'", cfg.Session.DMScope)
+ }
+}
+
+func TestDefaultConfig_WorkspacePath_Default(t *testing.T) {
+ // Unset to ensure we test the default
+ t.Setenv("PICOCLAW_HOME", "")
+ // Set a known home for consistent test results
+ t.Setenv("HOME", "/tmp/home")
+
+ cfg := DefaultConfig()
+ want := filepath.Join("/tmp/home", ".picoclaw", "workspace")
+
+ if cfg.Agents.Defaults.Workspace != want {
+ t.Errorf("Default workspace path = %q, want %q", cfg.Agents.Defaults.Workspace, want)
+ }
+}
+
+func TestDefaultConfig_WorkspacePath_WithPicoclawHome(t *testing.T) {
+ t.Setenv("PICOCLAW_HOME", "/custom/picoclaw/home")
+
+ cfg := DefaultConfig()
+ want := "/custom/picoclaw/home/workspace"
+
+ if cfg.Agents.Defaults.Workspace != want {
+ t.Errorf("Workspace path with PICOCLAW_HOME = %q, want %q", cfg.Agents.Defaults.Workspace, want)
+ }
+}
diff --git a/pkg/config/defaults.go b/pkg/config/defaults.go
index 47c51fc9d..19d877dea 100644
--- a/pkg/config/defaults.go
+++ b/pkg/config/defaults.go
@@ -5,34 +5,59 @@
package config
+import (
+ "os"
+ "path/filepath"
+)
+
// DefaultConfig returns the default configuration for PicoClaw.
func DefaultConfig() *Config {
+ // Determine the base path for the workspace.
+ // Priority: $PICOCLAW_HOME > ~/.picoclaw
+ var homePath string
+ if picoclawHome := os.Getenv("PICOCLAW_HOME"); picoclawHome != "" {
+ homePath = picoclawHome
+ } else {
+ userHome, _ := os.UserHomeDir()
+ homePath = filepath.Join(userHome, ".picoclaw")
+ }
+ workspacePath := filepath.Join(homePath, "workspace")
+
return &Config{
Agents: AgentsConfig{
Defaults: AgentDefaults{
- Workspace: "~/.picoclaw/workspace",
- RestrictToWorkspace: true,
- Provider: "",
- Model: "glm-4.7",
- MaxTokens: 8192,
- Temperature: nil, // nil means use provider default
- MaxToolIterations: 20,
+ Workspace: workspacePath,
+ RestrictToWorkspace: true,
+ Provider: "",
+ Model: "",
+ MaxTokens: 32768,
+ Temperature: nil, // nil means use provider default
+ MaxToolIterations: 50,
+ SummarizeMessageThreshold: 20,
+ SummarizeTokenPercent: 75,
},
},
Bindings: []AgentBinding{},
Session: SessionConfig{
- DMScope: "main",
+ DMScope: "per-channel-peer",
},
Channels: ChannelsConfig{
WhatsApp: WhatsAppConfig{
- Enabled: false,
- BridgeURL: "ws://localhost:3001",
- AllowFrom: FlexibleStringSlice{},
+ Enabled: false,
+ BridgeURL: "ws://localhost:3001",
+ UseNative: false,
+ SessionStorePath: "",
+ AllowFrom: FlexibleStringSlice{},
},
Telegram: TelegramConfig{
Enabled: false,
Token: "",
AllowFrom: FlexibleStringSlice{},
+ Typing: TypingConfig{Enabled: true},
+ Placeholder: PlaceholderConfig{
+ Enabled: true,
+ Text: "Thinking... 💭",
+ },
},
Feishu: FeishuConfig{
Enabled: false,
@@ -80,6 +105,7 @@ func DefaultConfig() *Config {
WebhookPort: 18791,
WebhookPath: "/webhook/line",
AllowFrom: FlexibleStringSlice{},
+ GroupTrigger: GroupTriggerConfig{MentionOnly: true},
},
OneBot: OneBotConfig{
Enabled: false,
@@ -113,6 +139,25 @@ func DefaultConfig() *Config {
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?",
+ },
+ Pico: PicoConfig{
+ Enabled: false,
+ Token: "",
+ PingInterval: 30,
+ ReadTimeout: 60,
+ WriteTimeout: 10,
+ MaxConnections: 100,
+ AllowFrom: FlexibleStringSlice{},
+ },
},
Providers: ProvidersConfig{
OpenAI: OpenAIProviderConfig{WebSearch: true},
@@ -276,8 +321,14 @@ func DefaultConfig() *Config {
Port: 18790,
},
Tools: ToolsConfig{
+ MediaCleanup: MediaCleanupConfig{
+ Enabled: true,
+ MaxAge: 30,
+ Interval: 5,
+ },
Web: WebToolsConfig{
- Proxy: "",
+ Proxy: "",
+ FetchLimitBytes: 10 * 1024 * 1024, // 10MB by default
Brave: BraveConfig{
Enabled: false,
APIKey: "",
@@ -297,6 +348,13 @@ func DefaultConfig() *Config {
BaseURL: "",
MaxResults: 5,
},
+ GLMSearch: GLMSearchConfig{
+ Enabled: false,
+ APIKey: "",
+ BaseURL: "https://open.bigmodel.cn/api/paas/v4/web_search",
+ SearchEngine: "search_std",
+ MaxResults: 5,
+ },
},
Cron: CronToolsConfig{
ExecTimeoutMinutes: 5,
@@ -317,6 +375,10 @@ func DefaultConfig() *Config {
TTLSeconds: 300,
},
},
+ MCP: MCPConfig{
+ Enabled: false,
+ Servers: map[string]MCPServerConfig{},
+ },
},
Heartbeat: HeartbeatConfig{
Enabled: true,
diff --git a/pkg/config/migration.go b/pkg/config/migration.go
index 70e1de438..772f714fd 100644
--- a/pkg/config/migration.go
+++ b/pkg/config/migration.go
@@ -60,12 +60,13 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "openai",
- Model: "openai/gpt-5.2",
- APIKey: p.OpenAI.APIKey,
- APIBase: p.OpenAI.APIBase,
- Proxy: p.OpenAI.Proxy,
- AuthMethod: p.OpenAI.AuthMethod,
+ ModelName: "openai",
+ Model: "openai/gpt-5.2",
+ APIKey: p.OpenAI.APIKey,
+ APIBase: p.OpenAI.APIBase,
+ Proxy: p.OpenAI.Proxy,
+ RequestTimeout: p.OpenAI.RequestTimeout,
+ AuthMethod: p.OpenAI.AuthMethod,
}, true
},
},
@@ -77,12 +78,30 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "anthropic",
- Model: "anthropic/claude-sonnet-4.6",
- APIKey: p.Anthropic.APIKey,
- APIBase: p.Anthropic.APIBase,
- Proxy: p.Anthropic.Proxy,
- AuthMethod: p.Anthropic.AuthMethod,
+ ModelName: "anthropic",
+ Model: "anthropic/claude-sonnet-4.6",
+ APIKey: p.Anthropic.APIKey,
+ APIBase: p.Anthropic.APIBase,
+ Proxy: p.Anthropic.Proxy,
+ RequestTimeout: p.Anthropic.RequestTimeout,
+ AuthMethod: p.Anthropic.AuthMethod,
+ }, true
+ },
+ },
+ {
+ providerNames: []string{"litellm"},
+ protocol: "litellm",
+ buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+ if p.LiteLLM.APIKey == "" && p.LiteLLM.APIBase == "" {
+ return ModelConfig{}, false
+ }
+ return ModelConfig{
+ ModelName: "litellm",
+ Model: "litellm/auto",
+ APIKey: p.LiteLLM.APIKey,
+ APIBase: p.LiteLLM.APIBase,
+ Proxy: p.LiteLLM.Proxy,
+ RequestTimeout: p.LiteLLM.RequestTimeout,
}, true
},
},
@@ -94,11 +113,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "openrouter",
- Model: "openrouter/auto",
- APIKey: p.OpenRouter.APIKey,
- APIBase: p.OpenRouter.APIBase,
- Proxy: p.OpenRouter.Proxy,
+ ModelName: "openrouter",
+ Model: "openrouter/auto",
+ APIKey: p.OpenRouter.APIKey,
+ APIBase: p.OpenRouter.APIBase,
+ Proxy: p.OpenRouter.Proxy,
+ RequestTimeout: p.OpenRouter.RequestTimeout,
}, true
},
},
@@ -110,11 +130,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "groq",
- Model: "groq/llama-3.1-70b-versatile",
- APIKey: p.Groq.APIKey,
- APIBase: p.Groq.APIBase,
- Proxy: p.Groq.Proxy,
+ ModelName: "groq",
+ Model: "groq/llama-3.1-70b-versatile",
+ APIKey: p.Groq.APIKey,
+ APIBase: p.Groq.APIBase,
+ Proxy: p.Groq.Proxy,
+ RequestTimeout: p.Groq.RequestTimeout,
}, true
},
},
@@ -126,11 +147,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "zhipu",
- Model: "zhipu/glm-4",
- APIKey: p.Zhipu.APIKey,
- APIBase: p.Zhipu.APIBase,
- Proxy: p.Zhipu.Proxy,
+ ModelName: "zhipu",
+ Model: "zhipu/glm-4",
+ APIKey: p.Zhipu.APIKey,
+ APIBase: p.Zhipu.APIBase,
+ Proxy: p.Zhipu.Proxy,
+ RequestTimeout: p.Zhipu.RequestTimeout,
}, true
},
},
@@ -142,11 +164,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "vllm",
- Model: "vllm/auto",
- APIKey: p.VLLM.APIKey,
- APIBase: p.VLLM.APIBase,
- Proxy: p.VLLM.Proxy,
+ ModelName: "vllm",
+ Model: "vllm/auto",
+ APIKey: p.VLLM.APIKey,
+ APIBase: p.VLLM.APIBase,
+ Proxy: p.VLLM.Proxy,
+ RequestTimeout: p.VLLM.RequestTimeout,
}, true
},
},
@@ -158,11 +181,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "gemini",
- Model: "gemini/gemini-pro",
- APIKey: p.Gemini.APIKey,
- APIBase: p.Gemini.APIBase,
- Proxy: p.Gemini.Proxy,
+ ModelName: "gemini",
+ Model: "gemini/gemini-pro",
+ APIKey: p.Gemini.APIKey,
+ APIBase: p.Gemini.APIBase,
+ Proxy: p.Gemini.Proxy,
+ RequestTimeout: p.Gemini.RequestTimeout,
}, true
},
},
@@ -174,11 +198,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "nvidia",
- Model: "nvidia/meta/llama-3.1-8b-instruct",
- APIKey: p.Nvidia.APIKey,
- APIBase: p.Nvidia.APIBase,
- Proxy: p.Nvidia.Proxy,
+ ModelName: "nvidia",
+ Model: "nvidia/meta/llama-3.1-8b-instruct",
+ APIKey: p.Nvidia.APIKey,
+ APIBase: p.Nvidia.APIBase,
+ Proxy: p.Nvidia.Proxy,
+ RequestTimeout: p.Nvidia.RequestTimeout,
}, true
},
},
@@ -190,11 +215,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "ollama",
- Model: "ollama/llama3",
- APIKey: p.Ollama.APIKey,
- APIBase: p.Ollama.APIBase,
- Proxy: p.Ollama.Proxy,
+ ModelName: "ollama",
+ Model: "ollama/llama3",
+ APIKey: p.Ollama.APIKey,
+ APIBase: p.Ollama.APIBase,
+ Proxy: p.Ollama.Proxy,
+ RequestTimeout: p.Ollama.RequestTimeout,
}, true
},
},
@@ -206,11 +232,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "moonshot",
- Model: "moonshot/kimi",
- APIKey: p.Moonshot.APIKey,
- APIBase: p.Moonshot.APIBase,
- Proxy: p.Moonshot.Proxy,
+ ModelName: "moonshot",
+ Model: "moonshot/kimi",
+ APIKey: p.Moonshot.APIKey,
+ APIBase: p.Moonshot.APIBase,
+ Proxy: p.Moonshot.Proxy,
+ RequestTimeout: p.Moonshot.RequestTimeout,
}, true
},
},
@@ -222,11 +249,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "shengsuanyun",
- Model: "shengsuanyun/auto",
- APIKey: p.ShengSuanYun.APIKey,
- APIBase: p.ShengSuanYun.APIBase,
- Proxy: p.ShengSuanYun.Proxy,
+ ModelName: "shengsuanyun",
+ Model: "shengsuanyun/auto",
+ APIKey: p.ShengSuanYun.APIKey,
+ APIBase: p.ShengSuanYun.APIBase,
+ Proxy: p.ShengSuanYun.Proxy,
+ RequestTimeout: p.ShengSuanYun.RequestTimeout,
}, true
},
},
@@ -238,11 +266,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "deepseek",
- Model: "deepseek/deepseek-chat",
- APIKey: p.DeepSeek.APIKey,
- APIBase: p.DeepSeek.APIBase,
- Proxy: p.DeepSeek.Proxy,
+ ModelName: "deepseek",
+ Model: "deepseek/deepseek-chat",
+ APIKey: p.DeepSeek.APIKey,
+ APIBase: p.DeepSeek.APIBase,
+ Proxy: p.DeepSeek.Proxy,
+ RequestTimeout: p.DeepSeek.RequestTimeout,
}, true
},
},
@@ -254,11 +283,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "cerebras",
- Model: "cerebras/llama-3.3-70b",
- APIKey: p.Cerebras.APIKey,
- APIBase: p.Cerebras.APIBase,
- Proxy: p.Cerebras.Proxy,
+ ModelName: "cerebras",
+ Model: "cerebras/llama-3.3-70b",
+ APIKey: p.Cerebras.APIKey,
+ APIBase: p.Cerebras.APIBase,
+ Proxy: p.Cerebras.Proxy,
+ RequestTimeout: p.Cerebras.RequestTimeout,
}, true
},
},
@@ -270,11 +300,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "volcengine",
- Model: "volcengine/doubao-pro",
- APIKey: p.VolcEngine.APIKey,
- APIBase: p.VolcEngine.APIBase,
- Proxy: p.VolcEngine.Proxy,
+ ModelName: "volcengine",
+ Model: "volcengine/doubao-pro",
+ APIKey: p.VolcEngine.APIKey,
+ APIBase: p.VolcEngine.APIBase,
+ Proxy: p.VolcEngine.Proxy,
+ RequestTimeout: p.VolcEngine.RequestTimeout,
}, true
},
},
@@ -316,11 +347,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "qwen",
- Model: "qwen/qwen-max",
- APIKey: p.Qwen.APIKey,
- APIBase: p.Qwen.APIBase,
- Proxy: p.Qwen.Proxy,
+ ModelName: "qwen",
+ Model: "qwen/qwen-max",
+ APIKey: p.Qwen.APIKey,
+ APIBase: p.Qwen.APIBase,
+ Proxy: p.Qwen.Proxy,
+ RequestTimeout: p.Qwen.RequestTimeout,
}, true
},
},
@@ -332,11 +364,12 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
return ModelConfig{}, false
}
return ModelConfig{
- ModelName: "mistral",
- Model: "mistral/mistral-small-latest",
- APIKey: p.Mistral.APIKey,
- APIBase: p.Mistral.APIBase,
- Proxy: p.Mistral.Proxy,
+ ModelName: "mistral",
+ Model: "mistral/mistral-small-latest",
+ APIKey: p.Mistral.APIKey,
+ APIBase: p.Mistral.APIBase,
+ Proxy: p.Mistral.Proxy,
+ RequestTimeout: p.Mistral.RequestTimeout,
}, true
},
},
diff --git a/pkg/config/migration_test.go b/pkg/config/migration_test.go
index 42165cb71..e24e9fa1d 100644
--- a/pkg/config/migration_test.go
+++ b/pkg/config/migration_test.go
@@ -63,6 +63,33 @@ func TestConvertProvidersToModelList_Anthropic(t *testing.T) {
}
}
+func TestConvertProvidersToModelList_LiteLLM(t *testing.T) {
+ cfg := &Config{
+ Providers: ProvidersConfig{
+ LiteLLM: ProviderConfig{
+ APIKey: "litellm-key",
+ APIBase: "http://localhost:4000/v1",
+ },
+ },
+ }
+
+ result := ConvertProvidersToModelList(cfg)
+
+ if len(result) != 1 {
+ t.Fatalf("len(result) = %d, want 1", len(result))
+ }
+
+ if result[0].ModelName != "litellm" {
+ t.Errorf("ModelName = %q, want %q", result[0].ModelName, "litellm")
+ }
+ if result[0].Model != "litellm/auto" {
+ t.Errorf("Model = %q, want %q", result[0].Model, "litellm/auto")
+ }
+ if result[0].APIBase != "http://localhost:4000/v1" {
+ t.Errorf("APIBase = %q, want %q", result[0].APIBase, "http://localhost:4000/v1")
+ }
+}
+
func TestConvertProvidersToModelList_Multiple(t *testing.T) {
cfg := &Config{
Providers: ProvidersConfig{
@@ -115,6 +142,7 @@ 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"},
@@ -137,9 +165,9 @@ func TestConvertProvidersToModelList_AllProviders(t *testing.T) {
result := ConvertProvidersToModelList(cfg)
- // All 18 providers should be converted
- if len(result) != 18 {
- t.Errorf("len(result) = %d, want 18", len(result))
+ // All 19 providers should be converted
+ if len(result) != 19 {
+ t.Errorf("len(result) = %d, want 19", len(result))
}
}
@@ -166,6 +194,27 @@ func TestConvertProvidersToModelList_Proxy(t *testing.T) {
}
}
+func TestConvertProvidersToModelList_RequestTimeout(t *testing.T) {
+ cfg := &Config{
+ Providers: ProvidersConfig{
+ Ollama: ProviderConfig{
+ APIKey: "ollama-key",
+ RequestTimeout: 300,
+ },
+ },
+ }
+
+ result := ConvertProvidersToModelList(cfg)
+
+ if len(result) != 1 {
+ t.Fatalf("len(result) = %d, want 1", len(result))
+ }
+
+ if result[0].RequestTimeout != 300 {
+ t.Errorf("RequestTimeout = %d, want %d", result[0].RequestTimeout, 300)
+ }
+}
+
func TestConvertProvidersToModelList_AuthMethod(t *testing.T) {
cfg := &Config{
Providers: ProvidersConfig{
diff --git a/pkg/config/model_config_test.go b/pkg/config/model_config_test.go
index 99eea2782..da6e506f8 100644
--- a/pkg/config/model_config_test.go
+++ b/pkg/config/model_config_test.go
@@ -64,7 +64,7 @@ func TestGetModelConfig_RoundRobin(t *testing.T) {
// Test round-robin distribution
results := make(map[string]int)
- for i := 0; i < 30; i++ {
+ for range 30 {
result, err := cfg.GetModelConfig("lb-model")
if err != nil {
t.Fatalf("GetModelConfig() error = %v", err)
@@ -94,17 +94,15 @@ func TestGetModelConfig_Concurrent(t *testing.T) {
var wg sync.WaitGroup
errors := make(chan error, goroutines*iterations)
- for i := 0; i < goroutines; i++ {
- wg.Add(1)
- go func() {
- defer wg.Done()
- for j := 0; j < iterations; j++ {
+ for range goroutines {
+ wg.Go(func() {
+ for range iterations {
_, err := cfg.GetModelConfig("concurrent-model")
if err != nil {
errors <- err
}
}
- }()
+ })
}
wg.Wait()
@@ -365,3 +363,38 @@ func TestConfig_ValidateModelList(t *testing.T) {
})
}
}
+
+func TestModelConfig_RequestTimeoutParsing(t *testing.T) {
+ jsonData := `{
+ "model_name": "slow-local",
+ "model": "openai/local-model",
+ "api_base": "http://localhost:11434/v1",
+ "request_timeout": 300
+ }`
+
+ var cfg ModelConfig
+ if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
+ t.Fatalf("Unmarshal() error = %v", err)
+ }
+
+ if cfg.RequestTimeout != 300 {
+ t.Fatalf("RequestTimeout = %d, want 300", cfg.RequestTimeout)
+ }
+}
+
+func TestModelConfig_RequestTimeoutDefaultZeroValue(t *testing.T) {
+ jsonData := `{
+ "model_name": "default-timeout",
+ "model": "openai/gpt-4o",
+ "api_key": "test-key"
+ }`
+
+ var cfg ModelConfig
+ if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
+ t.Fatalf("Unmarshal() error = %v", err)
+ }
+
+ if cfg.RequestTimeout != 0 {
+ t.Fatalf("RequestTimeout = %d, want 0", cfg.RequestTimeout)
+ }
+}
diff --git a/pkg/cron/service.go b/pkg/cron/service.go
index e699a44b5..6962041c1 100644
--- a/pkg/cron/service.go
+++ b/pkg/cron/service.go
@@ -7,11 +7,12 @@ import (
"fmt"
"log"
"os"
- "path/filepath"
"sync"
"time"
"github.com/adhocore/gronx"
+
+ "github.com/sipeed/picoclaw/pkg/fileutil"
)
type CronSchedule struct {
@@ -330,17 +331,13 @@ func (cs *CronService) loadStore() error {
}
func (cs *CronService) saveStoreUnsafe() error {
- dir := filepath.Dir(cs.storePath)
- if err := os.MkdirAll(dir, 0o755); err != nil {
- return err
- }
-
data, err := json.MarshalIndent(cs.store, "", " ")
if err != nil {
return err
}
- return os.WriteFile(cs.storePath, data, 0o600)
+ // Use unified atomic write utility with explicit sync for flash storage reliability.
+ return fileutil.WriteFileAtomic(cs.storePath, data, 0o600)
}
func (cs *CronService) AddJob(
diff --git a/pkg/devices/service.go b/pkg/devices/service.go
index 1541d3c57..1bafe6085 100644
--- a/pkg/devices/service.go
+++ b/pkg/devices/service.go
@@ -4,6 +4,7 @@ import (
"context"
"strings"
"sync"
+ "time"
"github.com/sipeed/picoclaw/pkg/bus"
"github.com/sipeed/picoclaw/pkg/constants"
@@ -127,7 +128,9 @@ func (s *Service) sendNotification(ev *events.DeviceEvent) {
}
msg := ev.FormatMessage()
- msgBus.PublishOutbound(bus.OutboundMessage{
+ pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer pubCancel()
+ msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
Channel: platform,
ChatID: userID,
Content: msg,
diff --git a/pkg/fileutil/file.go b/pkg/fileutil/file.go
new file mode 100644
index 000000000..7ca872374
--- /dev/null
+++ b/pkg/fileutil/file.go
@@ -0,0 +1,119 @@
+// 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 fileutil provides file manipulation utilities.
+package fileutil
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "time"
+)
+
+// WriteFileAtomic atomically writes data to a file using a temp file + rename pattern.
+//
+// This guarantees that the target file is either:
+// - Completely written with the new data
+// - Unchanged (if any step fails before rename)
+//
+// The function:
+// 1. Creates a temp file in the same directory (original untouched)
+// 2. Writes data to temp file
+// 3. Syncs data to disk (critical for SD cards/flash storage)
+// 4. Sets file permissions
+// 5. Syncs directory metadata (ensures rename is durable)
+// 6. Atomically renames temp file to target path
+//
+// Safety guarantees:
+// - Original file is NEVER modified until successful rename
+// - Temp file is always cleaned up on error
+// - Data is flushed to physical storage before rename
+// - Directory entry is synced to prevent orphaned inodes
+//
+// Parameters:
+// - path: Target file path
+// - data: Data to write
+// - perm: File permission mode (e.g., 0o600 for secure, 0o644 for readable)
+//
+// Returns:
+// - Error if any step fails, nil on success
+//
+// Example:
+//
+// // Secure config file (owner read/write only)
+// err := utils.WriteFileAtomic("config.json", data, 0o600)
+//
+// // Public readable file
+// err := utils.WriteFileAtomic("public.txt", data, 0o644)
+func WriteFileAtomic(path string, data []byte, perm os.FileMode) error {
+ dir := filepath.Dir(path)
+ if err := os.MkdirAll(dir, 0o755); err != nil {
+ return fmt.Errorf("failed to create directory: %w", err)
+ }
+
+ // Create temp file in the same directory (ensures atomic rename works)
+ // Using a hidden prefix (.tmp-) to avoid issues with some tools
+ tmpFile, err := os.OpenFile(
+ filepath.Join(dir, fmt.Sprintf(".tmp-%d-%d", os.Getpid(), time.Now().UnixNano())),
+ os.O_WRONLY|os.O_CREATE|os.O_EXCL,
+ perm,
+ )
+ if err != nil {
+ return fmt.Errorf("failed to create temp file: %w", err)
+ }
+
+ tmpPath := tmpFile.Name()
+ cleanup := true
+
+ defer func() {
+ if cleanup {
+ tmpFile.Close()
+ _ = os.Remove(tmpPath)
+ }
+ }()
+
+ // Write data to temp file
+ // Note: Original file is untouched at this point
+ if _, err := tmpFile.Write(data); err != nil {
+ return fmt.Errorf("failed to write temp file: %w", err)
+ }
+
+ // CRITICAL: Force sync to storage medium before any other operations.
+ // This ensures data is physically written to disk, not just cached.
+ // Essential for SD cards, eMMC, and other flash storage on edge devices.
+ if err := tmpFile.Sync(); err != nil {
+ return fmt.Errorf("failed to sync temp file: %w", err)
+ }
+
+ // Set file permissions before closing
+ if err := tmpFile.Chmod(perm); err != nil {
+ return fmt.Errorf("failed to set permissions: %w", err)
+ }
+
+ // Close file before rename (required on Windows)
+ if err := tmpFile.Close(); err != nil {
+ return fmt.Errorf("failed to close temp file: %w", err)
+ }
+
+ // Atomic rename: temp file becomes the target
+ // On POSIX: rename() is atomic
+ // On Windows: Rename() is atomic for files
+ if err := os.Rename(tmpPath, path); err != nil {
+ return fmt.Errorf("failed to rename temp file: %w", err)
+ }
+
+ // Sync directory to ensure rename is durable
+ // This prevents the renamed file from disappearing after a crash
+ if dirFile, err := os.Open(dir); err == nil {
+ _ = dirFile.Sync()
+ dirFile.Close()
+ }
+
+ // Success: skip cleanup (file was renamed, no temp to remove)
+ cleanup = false
+ return nil
+}
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 77b36034d..5609ebdf6 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"fmt"
+ "maps"
"net/http"
"sync"
"time"
@@ -122,9 +123,7 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
s.mu.RLock()
ready := s.ready
checks := make(map[string]Check)
- for k, v := range s.checks {
- checks[k] = v
- }
+ maps.Copy(checks, s.checks)
s.mu.RUnlock()
if !ready {
@@ -156,6 +155,13 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
})
}
+// RegisterOnMux registers /health and /ready handlers onto the given mux.
+// This allows the health endpoints to be served by a shared HTTP server.
+func (s *Server) RegisterOnMux(mux *http.ServeMux) {
+ mux.HandleFunc("/health", s.healthHandler)
+ mux.HandleFunc("/ready", s.readyHandler)
+}
+
func statusString(ok bool) string {
if ok {
return "ok"
diff --git a/pkg/heartbeat/service.go b/pkg/heartbeat/service.go
index e05a9fdbf..09c93fc6b 100644
--- a/pkg/heartbeat/service.go
+++ b/pkg/heartbeat/service.go
@@ -7,6 +7,7 @@
package heartbeat
import (
+ "context"
"fmt"
"os"
"path/filepath"
@@ -16,6 +17,7 @@ import (
"github.com/sipeed/picoclaw/pkg/bus"
"github.com/sipeed/picoclaw/pkg/constants"
+ "github.com/sipeed/picoclaw/pkg/fileutil"
"github.com/sipeed/picoclaw/pkg/logger"
"github.com/sipeed/picoclaw/pkg/state"
"github.com/sipeed/picoclaw/pkg/tools"
@@ -275,7 +277,7 @@ This file contains tasks for the heartbeat service to check periodically.
Add your heartbeat tasks below this line:
`
- if err := os.WriteFile(heartbeatPath, []byte(defaultContent), 0o644); err != nil {
+ if err := fileutil.WriteFileAtomic(heartbeatPath, []byte(defaultContent), 0o644); err != nil {
hs.logErrorf("Failed to create default HEARTBEAT.md: %v", err)
} else {
hs.logInfof("Created default HEARTBEAT.md template")
@@ -307,7 +309,9 @@ func (hs *HeartbeatService) sendResponse(response string) {
return
}
- msgBus.PublishOutbound(bus.OutboundMessage{
+ pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer pubCancel()
+ msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
Channel: platform,
ChatID: userID,
Content: response,
diff --git a/pkg/heartbeat/service_test.go b/pkg/heartbeat/service_test.go
index a7aef8c3a..3b7eeeefb 100644
--- a/pkg/heartbeat/service_test.go
+++ b/pkg/heartbeat/service_test.go
@@ -47,79 +47,63 @@ func TestExecuteHeartbeat_Async(t *testing.T) {
}
}
-func TestExecuteHeartbeat_Error(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.stopChan = make(chan struct{}) // Enable for testing
-
- hs.SetHandler(func(prompt, channel, chatID string) *tools.ToolResult {
- return &tools.ToolResult{
- ForLLM: "Heartbeat failed: connection error",
- ForUser: "",
- Silent: false,
- IsError: true,
- Async: false,
- }
- })
-
- // Create HEARTBEAT.md
- os.WriteFile(filepath.Join(tmpDir, "HEARTBEAT.md"), []byte("Test task"), 0o644)
-
- hs.executeHeartbeat()
-
- // Check log file for error message
- logFile := filepath.Join(tmpDir, "heartbeat.log")
- data, err := os.ReadFile(logFile)
- if err != nil {
- t.Fatalf("Failed to read log file: %v", err)
+func TestExecuteHeartbeat_ResultLogging(t *testing.T) {
+ tests := []struct {
+ name string
+ result *tools.ToolResult
+ wantLog string
+ }{
+ {
+ name: "error result",
+ result: &tools.ToolResult{
+ ForLLM: "Heartbeat failed: connection error",
+ ForUser: "",
+ Silent: false,
+ IsError: true,
+ Async: false,
+ },
+ wantLog: "error message",
+ },
+ {
+ name: "silent result",
+ result: &tools.ToolResult{
+ ForLLM: "Heartbeat completed successfully",
+ ForUser: "",
+ Silent: true,
+ IsError: false,
+ Async: false,
+ },
+ wantLog: "completion message",
+ },
}
- logContent := string(data)
- if logContent == "" {
- t.Error("Expected log file to contain error message")
- }
-}
+ for _, tt := range tests {
+ t.Run(tt.name, func(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)
-func TestExecuteHeartbeat_Silent(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.stopChan = make(chan struct{}) // Enable for testing
- hs := NewHeartbeatService(tmpDir, 30, true)
- hs.stopChan = make(chan struct{}) // Enable for testing
+ hs.SetHandler(func(prompt, channel, chatID string) *tools.ToolResult {
+ return tt.result
+ })
- hs.SetHandler(func(prompt, channel, chatID string) *tools.ToolResult {
- return &tools.ToolResult{
- ForLLM: "Heartbeat completed successfully",
- ForUser: "",
- Silent: true,
- IsError: false,
- Async: false,
- }
- })
+ os.WriteFile(filepath.Join(tmpDir, "HEARTBEAT.md"), []byte("Test task"), 0o644)
+ hs.executeHeartbeat()
- // Create HEARTBEAT.md
- os.WriteFile(filepath.Join(tmpDir, "HEARTBEAT.md"), []byte("Test task"), 0o644)
-
- hs.executeHeartbeat()
-
- // Check log file for completion message
- logFile := filepath.Join(tmpDir, "heartbeat.log")
- data, err := os.ReadFile(logFile)
- if err != nil {
- t.Fatalf("Failed to read log file: %v", err)
- }
-
- logContent := string(data)
- if logContent == "" {
- t.Error("Expected log file to contain completion message")
+ logFile := filepath.Join(tmpDir, "heartbeat.log")
+ data, err := os.ReadFile(logFile)
+ if err != nil {
+ t.Fatalf("Failed to read log file: %v", err)
+ }
+ if string(data) == "" {
+ t.Errorf("Expected log file to contain %s", tt.wantLog)
+ }
+ })
}
}
diff --git a/pkg/identity/identity.go b/pkg/identity/identity.go
new file mode 100644
index 000000000..6bc09c210
--- /dev/null
+++ b/pkg/identity/identity.go
@@ -0,0 +1,107 @@
+// Package identity provides unified user identity utilities for PicoClaw.
+// It introduces a canonical "platform:id" format and matching logic
+// that is backward-compatible with all legacy allow-list formats.
+package identity
+
+import (
+ "strings"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+)
+
+// BuildCanonicalID constructs a canonical "platform:id" identifier.
+// Both platform and platformID are lowercased and trimmed.
+func BuildCanonicalID(platform, platformID string) string {
+ p := strings.ToLower(strings.TrimSpace(platform))
+ id := strings.TrimSpace(platformID)
+ if p == "" || id == "" {
+ return ""
+ }
+ return p + ":" + id
+}
+
+// ParseCanonicalID splits a canonical ID ("platform:id") into its parts.
+// Returns ok=false if the input does not contain a colon separator.
+func ParseCanonicalID(canonical string) (platform, id string, ok bool) {
+ canonical = strings.TrimSpace(canonical)
+ idx := strings.Index(canonical, ":")
+ if idx <= 0 || idx == len(canonical)-1 {
+ return "", "", false
+ }
+ return canonical[:idx], canonical[idx+1:], true
+}
+
+// MatchAllowed checks whether the given sender matches a single allow-list entry.
+// It is backward-compatible with all legacy formats:
+//
+// - "123456" → matches sender.PlatformID
+// - "@alice" → matches sender.Username
+// - "123456|alice" → matches PlatformID or Username
+// - "telegram:123456" → exact match on sender.CanonicalID
+func MatchAllowed(sender bus.SenderInfo, allowed string) bool {
+ allowed = strings.TrimSpace(allowed)
+ if allowed == "" {
+ return false
+ }
+
+ // Try canonical match first: "platform:id" format
+ if platform, id, ok := ParseCanonicalID(allowed); ok {
+ // Only treat as canonical if the platform portion looks like a known platform name
+ // (not a pure-numeric string, which could be a compound ID)
+ if !isNumeric(platform) {
+ candidate := BuildCanonicalID(platform, id)
+ if candidate != "" && sender.CanonicalID != "" {
+ return strings.EqualFold(sender.CanonicalID, candidate)
+ }
+ // If sender has no canonical ID, try matching platform + platformID
+ return strings.EqualFold(platform, sender.Platform) &&
+ sender.PlatformID == id
+ }
+ }
+
+ // Strip leading "@" for username matching
+ trimmed := strings.TrimPrefix(allowed, "@")
+
+ // Split compound "id|username" format
+ allowedID := trimmed
+ allowedUser := ""
+ if idx := strings.Index(trimmed, "|"); idx > 0 {
+ allowedID = trimmed[:idx]
+ allowedUser = trimmed[idx+1:]
+ }
+
+ // Match against PlatformID
+ if sender.PlatformID != "" && sender.PlatformID == allowedID {
+ return true
+ }
+
+ // Match against Username
+ if sender.Username != "" {
+ if sender.Username == trimmed || sender.Username == allowedUser {
+ return true
+ }
+ }
+
+ // Match compound sender format against allowed parts
+ if allowedUser != "" && sender.PlatformID != "" && sender.PlatformID == allowedID {
+ return true
+ }
+ if allowedUser != "" && sender.Username != "" && sender.Username == allowedUser {
+ return true
+ }
+
+ return false
+}
+
+// isNumeric returns true if s consists entirely of digits.
+func isNumeric(s string) bool {
+ if s == "" {
+ return false
+ }
+ for _, r := range s {
+ if r < '0' || r > '9' {
+ return false
+ }
+ }
+ return true
+}
diff --git a/pkg/identity/identity_test.go b/pkg/identity/identity_test.go
new file mode 100644
index 000000000..3d24bd794
--- /dev/null
+++ b/pkg/identity/identity_test.go
@@ -0,0 +1,229 @@
+package identity
+
+import (
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/bus"
+)
+
+func TestBuildCanonicalID(t *testing.T) {
+ tests := []struct {
+ platform string
+ platformID string
+ want string
+ }{
+ {"telegram", "123456", "telegram:123456"},
+ {"Discord", "98765432", "discord:98765432"},
+ {"SLACK", "U123ABC", "slack:U123ABC"},
+ {"", "123", ""},
+ {"telegram", "", ""},
+ {" telegram ", " 123 ", "telegram:123"},
+ }
+
+ for _, tt := range tests {
+ got := BuildCanonicalID(tt.platform, tt.platformID)
+ if got != tt.want {
+ t.Errorf("BuildCanonicalID(%q, %q) = %q, want %q",
+ tt.platform, tt.platformID, got, tt.want)
+ }
+ }
+}
+
+func TestParseCanonicalID(t *testing.T) {
+ tests := []struct {
+ input string
+ wantPlatform string
+ wantID string
+ wantOk bool
+ }{
+ {"telegram:123456", "telegram", "123456", true},
+ {"discord:98765432", "discord", "98765432", true},
+ {"slack:U123ABC", "slack", "U123ABC", true},
+ {"nocolon", "", "", false},
+ {"", "", "", false},
+ {":missing", "", "", false},
+ {"missing:", "", "", false},
+ }
+
+ for _, tt := range tests {
+ platform, id, ok := ParseCanonicalID(tt.input)
+ if ok != tt.wantOk || platform != tt.wantPlatform || id != tt.wantID {
+ t.Errorf("ParseCanonicalID(%q) = (%q, %q, %v), want (%q, %q, %v)",
+ tt.input, platform, id, ok,
+ tt.wantPlatform, tt.wantID, tt.wantOk)
+ }
+ }
+}
+
+func TestMatchAllowed(t *testing.T) {
+ telegramSender := bus.SenderInfo{
+ Platform: "telegram",
+ PlatformID: "123456",
+ CanonicalID: "telegram:123456",
+ Username: "alice",
+ DisplayName: "Alice Smith",
+ }
+
+ discordSender := bus.SenderInfo{
+ Platform: "discord",
+ PlatformID: "98765432",
+ CanonicalID: "discord:98765432",
+ Username: "bob",
+ DisplayName: "bob#1234",
+ }
+
+ noCanonicalSender := bus.SenderInfo{
+ Platform: "telegram",
+ PlatformID: "999",
+ Username: "carol",
+ }
+
+ tests := []struct {
+ name string
+ sender bus.SenderInfo
+ allowed string
+ want bool
+ }{
+ // Pure numeric ID matching
+ {
+ name: "numeric ID matches PlatformID",
+ sender: telegramSender,
+ allowed: "123456",
+ want: true,
+ },
+ {
+ name: "numeric ID does not match",
+ sender: telegramSender,
+ allowed: "654321",
+ want: false,
+ },
+ // Username matching
+ {
+ name: "@username matches Username",
+ sender: telegramSender,
+ allowed: "@alice",
+ want: true,
+ },
+ {
+ name: "@username does not match",
+ sender: telegramSender,
+ allowed: "@bob",
+ want: false,
+ },
+ // Compound format "id|username"
+ {
+ name: "compound matches by ID",
+ sender: telegramSender,
+ allowed: "123456|alice",
+ want: true,
+ },
+ {
+ name: "compound matches by username",
+ sender: telegramSender,
+ allowed: "999|alice",
+ want: true,
+ },
+ {
+ name: "compound does not match",
+ sender: telegramSender,
+ allowed: "654321|bob",
+ want: false,
+ },
+ // Canonical format "platform:id"
+ {
+ name: "canonical matches exactly",
+ sender: telegramSender,
+ allowed: "telegram:123456",
+ want: true,
+ },
+ {
+ name: "canonical case-insensitive platform",
+ sender: telegramSender,
+ allowed: "Telegram:123456",
+ want: true,
+ },
+ {
+ name: "canonical wrong platform",
+ sender: telegramSender,
+ allowed: "discord:123456",
+ want: false,
+ },
+ {
+ name: "canonical wrong ID",
+ sender: telegramSender,
+ allowed: "telegram:654321",
+ want: false,
+ },
+ // Cross-platform canonical
+ {
+ name: "discord canonical match",
+ sender: discordSender,
+ allowed: "discord:98765432",
+ want: true,
+ },
+ {
+ name: "telegram canonical does not match discord sender",
+ sender: discordSender,
+ allowed: "telegram:98765432",
+ want: false,
+ },
+ // Sender without canonical ID
+ {
+ name: "canonical match falls back to platform+platformID",
+ sender: noCanonicalSender,
+ allowed: "telegram:999",
+ want: true,
+ },
+ {
+ name: "platform mismatch on fallback",
+ sender: noCanonicalSender,
+ allowed: "discord:999",
+ want: false,
+ },
+ // Empty allowed string
+ {
+ name: "empty allowed never matches",
+ sender: telegramSender,
+ allowed: "",
+ want: false,
+ },
+ // Whitespace handling
+ {
+ name: "trimmed allowed matches",
+ sender: telegramSender,
+ allowed: " 123456 ",
+ want: true,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := MatchAllowed(tt.sender, tt.allowed)
+ if got != tt.want {
+ t.Errorf("MatchAllowed(%+v, %q) = %v, want %v",
+ tt.sender, tt.allowed, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestIsNumeric(t *testing.T) {
+ tests := []struct {
+ input string
+ want bool
+ }{
+ {"123456", true},
+ {"0", true},
+ {"", false},
+ {"abc", false},
+ {"12a34", false},
+ {"telegram", false},
+ }
+
+ for _, tt := range tests {
+ got := isNumeric(tt.input)
+ if got != tt.want {
+ t.Errorf("isNumeric(%q) = %v, want %v", tt.input, got, tt.want)
+ }
+ }
+}
diff --git a/pkg/mcp/manager.go b/pkg/mcp/manager.go
new file mode 100644
index 000000000..7b63cc979
--- /dev/null
+++ b/pkg/mcp/manager.go
@@ -0,0 +1,532 @@
+package mcp
+
+import (
+ "bufio"
+ "context"
+ "errors"
+ "fmt"
+ "net/http"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "strings"
+ "sync"
+ "sync/atomic"
+
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// headerTransport is an http.RoundTripper that adds custom headers to requests
+type headerTransport struct {
+ base http.RoundTripper
+ headers map[string]string
+}
+
+func (t *headerTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+ // Clone the request to avoid modifying the original
+ req = req.Clone(req.Context())
+
+ // Add custom headers
+ for key, value := range t.headers {
+ req.Header.Set(key, value)
+ }
+
+ // Use the base transport
+ base := t.base
+ if base == nil {
+ base = http.DefaultTransport
+ }
+ return base.RoundTrip(req)
+}
+
+// loadEnvFile loads environment variables from a file in .env format
+// Each line should be in the format: KEY=value
+// Lines starting with # are comments
+// Empty lines are ignored
+func loadEnvFile(path string) (map[string]string, error) {
+ file, err := os.Open(path)
+ if err != nil {
+ return nil, fmt.Errorf("failed to open env file: %w", err)
+ }
+ defer file.Close()
+
+ envVars := make(map[string]string)
+ scanner := bufio.NewScanner(file)
+ lineNum := 0
+
+ for scanner.Scan() {
+ lineNum++
+ line := strings.TrimSpace(scanner.Text())
+
+ // Skip empty lines and comments
+ if line == "" || strings.HasPrefix(line, "#") {
+ continue
+ }
+
+ // Parse KEY=value
+ parts := strings.SplitN(line, "=", 2)
+ if len(parts) != 2 {
+ return nil, fmt.Errorf("invalid format at line %d: %s", lineNum, line)
+ }
+
+ key := strings.TrimSpace(parts[0])
+ value := strings.TrimSpace(parts[1])
+
+ if key == "" {
+ return nil, fmt.Errorf("invalid format at line %d: empty key", lineNum)
+ }
+
+ // Remove surrounding quotes if present
+ if len(value) >= 2 {
+ if (value[0] == '"' && value[len(value)-1] == '"') ||
+ (value[0] == '\'' && value[len(value)-1] == '\'') {
+ value = value[1 : len(value)-1]
+ }
+ }
+
+ envVars[key] = value
+ }
+
+ if err := scanner.Err(); err != nil {
+ return nil, fmt.Errorf("error reading env file: %w", err)
+ }
+
+ return envVars, nil
+}
+
+// ServerConnection represents a connection to an MCP server
+type ServerConnection struct {
+ Name string
+ Client *mcp.Client
+ Session *mcp.ClientSession
+ Tools []*mcp.Tool
+}
+
+// Manager manages multiple MCP server connections
+type Manager struct {
+ servers map[string]*ServerConnection
+ mu sync.RWMutex
+ closed atomic.Bool // changed from bool to atomic.Bool to avoid TOCTOU race
+ wg sync.WaitGroup // tracks in-flight CallTool calls
+}
+
+// NewManager creates a new MCP manager
+func NewManager() *Manager {
+ return &Manager{
+ servers: make(map[string]*ServerConnection),
+ }
+}
+
+// LoadFromConfig loads MCP servers from configuration
+func (m *Manager) LoadFromConfig(ctx context.Context, cfg *config.Config) error {
+ return m.LoadFromMCPConfig(ctx, cfg.Tools.MCP, cfg.WorkspacePath())
+}
+
+// LoadFromMCPConfig loads MCP servers from MCP configuration and workspace path.
+// This is the minimal dependency version that doesn't require the full Config object.
+func (m *Manager) LoadFromMCPConfig(
+ ctx context.Context,
+ mcpCfg config.MCPConfig,
+ workspacePath string,
+) error {
+ if !mcpCfg.Enabled {
+ logger.InfoCF("mcp", "MCP integration is disabled", nil)
+ return nil
+ }
+
+ if len(mcpCfg.Servers) == 0 {
+ logger.InfoCF("mcp", "No MCP servers configured", nil)
+ return nil
+ }
+
+ logger.InfoCF("mcp", "Initializing MCP servers",
+ map[string]any{
+ "count": len(mcpCfg.Servers),
+ })
+
+ var wg sync.WaitGroup
+ errs := make(chan error, len(mcpCfg.Servers))
+ enabledCount := 0
+
+ for name, serverCfg := range mcpCfg.Servers {
+ if !serverCfg.Enabled {
+ logger.DebugCF("mcp", "Skipping disabled server",
+ map[string]any{
+ "server": name,
+ })
+ continue
+ }
+
+ enabledCount++
+ wg.Add(1)
+ go func(name string, serverCfg config.MCPServerConfig, workspace string) {
+ defer wg.Done()
+
+ // Resolve relative envFile paths relative to workspace
+ if serverCfg.EnvFile != "" && !filepath.IsAbs(serverCfg.EnvFile) {
+ if workspace == "" {
+ err := fmt.Errorf(
+ "workspace path is empty while resolving relative envFile %q for server %s",
+ serverCfg.EnvFile,
+ name,
+ )
+ logger.ErrorCF("mcp", "Invalid MCP server configuration",
+ map[string]any{
+ "server": name,
+ "env_file": serverCfg.EnvFile,
+ "error": err.Error(),
+ })
+ errs <- err
+ return
+ }
+ serverCfg.EnvFile = filepath.Join(workspace, serverCfg.EnvFile)
+ }
+
+ if err := m.ConnectServer(ctx, name, serverCfg); err != nil {
+ logger.ErrorCF("mcp", "Failed to connect to MCP server",
+ map[string]any{
+ "server": name,
+ "error": err.Error(),
+ })
+ errs <- fmt.Errorf("failed to connect to server %s: %w", name, err)
+ }
+ }(name, serverCfg, workspacePath)
+ }
+
+ wg.Wait()
+ close(errs)
+
+ // Collect errors
+ var allErrors []error
+ for err := range errs {
+ allErrors = append(allErrors, err)
+ }
+
+ connectedCount := len(m.GetServers())
+
+ // If all enabled servers failed to connect, return aggregated error
+ if enabledCount > 0 && connectedCount == 0 {
+ logger.ErrorCF("mcp", "All MCP servers failed to connect",
+ map[string]any{
+ "failed": len(allErrors),
+ "total": enabledCount,
+ })
+ return errors.Join(allErrors...)
+ }
+
+ if len(allErrors) > 0 {
+ logger.WarnCF("mcp", "Some MCP servers failed to connect",
+ map[string]any{
+ "failed": len(allErrors),
+ "connected": connectedCount,
+ "total": enabledCount,
+ })
+ // Don't fail completely if some servers successfully connected
+ }
+
+ logger.InfoCF("mcp", "MCP server initialization complete",
+ map[string]any{
+ "connected": connectedCount,
+ "total": enabledCount,
+ })
+
+ return nil
+}
+
+// ConnectServer connects to a single MCP server
+func (m *Manager) ConnectServer(
+ ctx context.Context,
+ name string,
+ cfg config.MCPServerConfig,
+) error {
+ logger.InfoCF("mcp", "Connecting to MCP server",
+ map[string]any{
+ "server": name,
+ "command": cfg.Command,
+ "args_count": len(cfg.Args),
+ })
+
+ // Create client
+ client := mcp.NewClient(&mcp.Implementation{
+ Name: "picoclaw",
+ Version: "1.0.0",
+ }, nil)
+
+ // Create transport based on configuration
+ // Auto-detect transport type if not explicitly specified
+ var transport mcp.Transport
+ transportType := cfg.Type
+
+ // Auto-detect: if URL is provided, use SSE; if command is provided, use stdio
+ if transportType == "" {
+ if cfg.URL != "" {
+ transportType = "sse"
+ } else if cfg.Command != "" {
+ transportType = "stdio"
+ } else {
+ return fmt.Errorf("either URL or command must be provided")
+ }
+ }
+
+ switch transportType {
+ case "sse", "http":
+ if cfg.URL == "" {
+ return fmt.Errorf("URL is required for SSE/HTTP transport")
+ }
+ logger.DebugCF("mcp", "Using SSE/HTTP transport",
+ map[string]any{
+ "server": name,
+ "url": cfg.URL,
+ })
+
+ sseTransport := &mcp.StreamableClientTransport{
+ Endpoint: cfg.URL,
+ }
+
+ // Add custom headers if provided
+ if len(cfg.Headers) > 0 {
+ // Create a custom HTTP client with header-injecting transport
+ sseTransport.HTTPClient = &http.Client{
+ Transport: &headerTransport{
+ base: http.DefaultTransport,
+ headers: cfg.Headers,
+ },
+ }
+ logger.DebugCF("mcp", "Added custom HTTP headers",
+ map[string]any{
+ "server": name,
+ "header_count": len(cfg.Headers),
+ })
+ }
+
+ transport = sseTransport
+ case "stdio":
+ if cfg.Command == "" {
+ return fmt.Errorf("command is required for stdio transport")
+ }
+ logger.DebugCF("mcp", "Using stdio transport",
+ map[string]any{
+ "server": name,
+ "command": cfg.Command,
+ })
+ // Create command with context
+ cmd := exec.CommandContext(ctx, cfg.Command, cfg.Args...)
+
+ // Build environment variables with proper override semantics
+ // Use a map to ensure config variables override file variables
+ envMap := make(map[string]string)
+
+ // Start with parent process environment
+ for _, e := range cmd.Environ() {
+ if idx := strings.Index(e, "="); idx > 0 {
+ envMap[e[:idx]] = e[idx+1:]
+ }
+ }
+
+ // Load environment variables from file if specified
+ if cfg.EnvFile != "" {
+ envVars, err := loadEnvFile(cfg.EnvFile)
+ if err != nil {
+ return fmt.Errorf("failed to load env file %s: %w", cfg.EnvFile, err)
+ }
+ for k, v := range envVars {
+ envMap[k] = v
+ }
+ logger.DebugCF("mcp", "Loaded environment variables from file",
+ map[string]any{
+ "server": name,
+ "envFile": cfg.EnvFile,
+ "var_count": len(envVars),
+ })
+ }
+
+ // Environment variables from config override those from file
+ for k, v := range cfg.Env {
+ envMap[k] = v
+ }
+
+ // Convert map to slice
+ env := make([]string, 0, len(envMap))
+ for k, v := range envMap {
+ env = append(env, fmt.Sprintf("%s=%s", k, v))
+ }
+ cmd.Env = env
+
+ transport = &mcp.CommandTransport{Command: cmd}
+ default:
+ return fmt.Errorf(
+ "unsupported transport type: %s (supported: stdio, sse, http)",
+ transportType,
+ )
+ }
+
+ // Connect to server
+ session, err := client.Connect(ctx, transport, nil)
+ if err != nil {
+ return fmt.Errorf("failed to connect: %w", err)
+ }
+
+ // Get server info
+ initResult := session.InitializeResult()
+ logger.InfoCF("mcp", "Connected to MCP server",
+ map[string]any{
+ "server": name,
+ "serverName": initResult.ServerInfo.Name,
+ "serverVersion": initResult.ServerInfo.Version,
+ "protocol": initResult.ProtocolVersion,
+ })
+
+ // List available tools if supported
+ var tools []*mcp.Tool
+ if initResult.Capabilities.Tools != nil {
+ for tool, err := range session.Tools(ctx, nil) {
+ if err != nil {
+ logger.WarnCF("mcp", "Error listing tool",
+ map[string]any{
+ "server": name,
+ "error": err.Error(),
+ })
+ continue
+ }
+ tools = append(tools, tool)
+ }
+
+ logger.InfoCF("mcp", "Listed tools from MCP server",
+ map[string]any{
+ "server": name,
+ "toolCount": len(tools),
+ })
+ }
+
+ // Store connection
+ m.mu.Lock()
+ m.servers[name] = &ServerConnection{
+ Name: name,
+ Client: client,
+ Session: session,
+ Tools: tools,
+ }
+ m.mu.Unlock()
+
+ return nil
+}
+
+// GetServers returns all connected servers
+func (m *Manager) GetServers() map[string]*ServerConnection {
+ m.mu.RLock()
+ defer m.mu.RUnlock()
+
+ result := make(map[string]*ServerConnection, len(m.servers))
+ for k, v := range m.servers {
+ result[k] = v
+ }
+ return result
+}
+
+// GetServer returns a specific server connection
+func (m *Manager) GetServer(name string) (*ServerConnection, bool) {
+ m.mu.RLock()
+ defer m.mu.RUnlock()
+
+ conn, ok := m.servers[name]
+ return conn, ok
+}
+
+// CallTool calls a tool on a specific server
+func (m *Manager) CallTool(
+ ctx context.Context,
+ serverName, toolName string,
+ arguments map[string]any,
+) (*mcp.CallToolResult, error) {
+ // Check if closed before acquiring lock (fast path)
+ if m.closed.Load() {
+ return nil, fmt.Errorf("manager is closed")
+ }
+
+ m.mu.RLock()
+ // Double-check after acquiring lock to prevent TOCTOU race
+ if m.closed.Load() {
+ m.mu.RUnlock()
+ return nil, fmt.Errorf("manager is closed")
+ }
+ conn, ok := m.servers[serverName]
+ if ok {
+ m.wg.Add(1) // Add to WaitGroup while holding the lock
+ }
+ m.mu.RUnlock()
+
+ if !ok {
+ return nil, fmt.Errorf("server %s not found", serverName)
+ }
+ defer m.wg.Done()
+
+ params := &mcp.CallToolParams{
+ Name: toolName,
+ Arguments: arguments,
+ }
+
+ result, err := conn.Session.CallTool(ctx, params)
+ if err != nil {
+ return nil, fmt.Errorf("failed to call tool: %w", err)
+ }
+
+ return result, nil
+}
+
+// Close closes all server connections
+func (m *Manager) Close() error {
+ // Use Swap to atomically set closed=true and get the previous value
+ // This prevents TOCTOU race with CallTool's closed check
+ if m.closed.Swap(true) {
+ return nil // already closed
+ }
+
+ // Wait for all in-flight CallTool calls to finish before closing sessions
+ // After closed=true is set, no new CallTool can start (they check closed first)
+ m.wg.Wait()
+
+ m.mu.Lock()
+ defer m.mu.Unlock()
+
+ logger.InfoCF("mcp", "Closing all MCP server connections",
+ map[string]any{
+ "count": len(m.servers),
+ })
+
+ var errs []error
+ for name, conn := range m.servers {
+ if err := conn.Session.Close(); err != nil {
+ logger.ErrorCF("mcp", "Failed to close server connection",
+ map[string]any{
+ "server": name,
+ "error": err.Error(),
+ })
+ errs = append(errs, fmt.Errorf("server %s: %w", name, err))
+ }
+ }
+
+ m.servers = make(map[string]*ServerConnection)
+
+ if len(errs) > 0 {
+ return fmt.Errorf("failed to close %d server(s): %w", len(errs), errors.Join(errs...))
+ }
+
+ return nil
+}
+
+// GetAllTools returns all tools from all connected servers
+func (m *Manager) GetAllTools() map[string][]*mcp.Tool {
+ m.mu.RLock()
+ defer m.mu.RUnlock()
+
+ result := make(map[string][]*mcp.Tool)
+ for name, conn := range m.servers {
+ if len(conn.Tools) > 0 {
+ result[name] = conn.Tools
+ }
+ }
+ return result
+}
diff --git a/pkg/mcp/manager_test.go b/pkg/mcp/manager_test.go
new file mode 100644
index 000000000..8ce81d09e
--- /dev/null
+++ b/pkg/mcp/manager_test.go
@@ -0,0 +1,298 @@
+package mcp
+
+import (
+ "context"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestLoadEnvFile(t *testing.T) {
+ tests := []struct {
+ name string
+ content string
+ expected map[string]string
+ expectErr bool
+ }{
+ {
+ name: "basic env file",
+ content: `API_KEY=secret123
+DATABASE_URL=postgres://localhost/db
+PORT=8080`,
+ expected: map[string]string{
+ "API_KEY": "secret123",
+ "DATABASE_URL": "postgres://localhost/db",
+ "PORT": "8080",
+ },
+ expectErr: false,
+ },
+ {
+ name: "with comments and empty lines",
+ content: `# This is a comment
+API_KEY=secret123
+
+# Another comment
+DATABASE_URL=postgres://localhost/db
+
+PORT=8080`,
+ expected: map[string]string{
+ "API_KEY": "secret123",
+ "DATABASE_URL": "postgres://localhost/db",
+ "PORT": "8080",
+ },
+ expectErr: false,
+ },
+ {
+ name: "with quoted values",
+ content: `API_KEY="secret with spaces"
+NAME='single quoted'
+PLAIN=no-quotes`,
+ expected: map[string]string{
+ "API_KEY": "secret with spaces",
+ "NAME": "single quoted",
+ "PLAIN": "no-quotes",
+ },
+ expectErr: false,
+ },
+ {
+ name: "with spaces around equals",
+ content: `API_KEY = secret123
+DATABASE_URL= postgres://localhost/db
+PORT =8080`,
+ expected: map[string]string{
+ "API_KEY": "secret123",
+ "DATABASE_URL": "postgres://localhost/db",
+ "PORT": "8080",
+ },
+ expectErr: false,
+ },
+ {
+ name: "invalid format - no equals",
+ content: `INVALID_LINE`,
+ expectErr: true,
+ },
+ {
+ name: "empty file",
+ content: ``,
+ expected: map[string]string{},
+ expectErr: false,
+ },
+ {
+ name: "only comments",
+ content: `# Comment 1
+# Comment 2`,
+ expected: map[string]string{},
+ expectErr: false,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ tmpDir := t.TempDir()
+ envFile := filepath.Join(tmpDir, ".env")
+
+ if err := os.WriteFile(envFile, []byte(tt.content), 0o644); err != nil {
+ t.Fatalf("Failed to create test file: %v", err)
+ }
+
+ result, err := loadEnvFile(envFile)
+
+ if tt.expectErr {
+ if err == nil {
+ t.Errorf("Expected error but got none")
+ }
+ return
+ }
+
+ if err != nil {
+ t.Errorf("Unexpected error: %v", err)
+ return
+ }
+
+ if len(result) != len(tt.expected) {
+ t.Errorf("Expected %d variables, got %d", len(tt.expected), len(result))
+ }
+
+ for key, expectedValue := range tt.expected {
+ if actualValue, ok := result[key]; !ok {
+ t.Errorf("Expected key %s not found", key)
+ } else if actualValue != expectedValue {
+ t.Errorf("For key %s: expected %q, got %q", key, expectedValue, actualValue)
+ }
+ }
+ })
+ }
+}
+
+func TestLoadEnvFileNotFound(t *testing.T) {
+ _, err := loadEnvFile("/nonexistent/file.env")
+ if err == nil {
+ t.Error("Expected error for nonexistent file")
+ }
+}
+
+func TestEnvFilePriority(t *testing.T) {
+ // Create a temporary .env file
+ tmpDir := t.TempDir()
+ envFile := filepath.Join(tmpDir, ".env")
+
+ envContent := `API_KEY=from_file
+DATABASE_URL=from_file
+SHARED_VAR=from_file`
+
+ if err := os.WriteFile(envFile, []byte(envContent), 0o644); err != nil {
+ t.Fatalf("Failed to create .env file: %v", err)
+ }
+
+ // Load envFile
+ envVars, err := loadEnvFile(envFile)
+ if err != nil {
+ t.Fatalf("Failed to load env file: %v", err)
+ }
+
+ // Verify envFile variables
+ if envVars["API_KEY"] != "from_file" {
+ t.Errorf("Expected API_KEY=from_file, got %s", envVars["API_KEY"])
+ }
+
+ // Simulate config.Env overriding envFile
+ configEnv := map[string]string{
+ "SHARED_VAR": "from_config",
+ "NEW_VAR": "from_config",
+ }
+
+ // Merge: envFile first, then config overrides
+ merged := make(map[string]string)
+ for k, v := range envVars {
+ merged[k] = v
+ }
+ for k, v := range configEnv {
+ merged[k] = v
+ }
+
+ // Verify priority: config.Env should override envFile
+ if merged["SHARED_VAR"] != "from_config" {
+ t.Errorf(
+ "Expected SHARED_VAR=from_config (config should override file), got %s",
+ merged["SHARED_VAR"],
+ )
+ }
+ if merged["API_KEY"] != "from_file" {
+ t.Errorf("Expected API_KEY=from_file, got %s", merged["API_KEY"])
+ }
+ if merged["NEW_VAR"] != "from_config" {
+ t.Errorf("Expected NEW_VAR=from_config, got %s", merged["NEW_VAR"])
+ }
+}
+
+func TestLoadFromMCPConfig_EmptyWorkspaceWithRelativeEnvFile(t *testing.T) {
+ mgr := NewManager()
+
+ mcpCfg := config.MCPConfig{
+ Enabled: true,
+ Servers: map[string]config.MCPServerConfig{
+ "test-server": {
+ Enabled: true,
+ Command: "echo",
+ Args: []string{"ok"},
+ EnvFile: ".env",
+ },
+ },
+ }
+
+ err := mgr.LoadFromMCPConfig(context.Background(), mcpCfg, "")
+ if err == nil {
+ t.Fatal("expected error for relative env_file with empty workspace path, got nil")
+ }
+
+ if !strings.Contains(err.Error(), "workspace path is empty") {
+ t.Fatalf("expected workspace path validation error, got: %v", err)
+ }
+}
+
+func TestNewManager_InitialState(t *testing.T) {
+ mgr := NewManager()
+ if mgr == nil {
+ t.Fatal("expected manager instance, got nil")
+ }
+ if len(mgr.GetServers()) != 0 {
+ t.Fatalf("expected no servers on new manager, got %d", len(mgr.GetServers()))
+ }
+}
+
+func TestLoadFromMCPConfig_DisabledOrEmptyServers(t *testing.T) {
+ mgr := NewManager()
+
+ err := mgr.LoadFromMCPConfig(context.Background(), config.MCPConfig{Enabled: false}, "/tmp")
+ if err != nil {
+ t.Fatalf("expected nil error when MCP disabled, got: %v", err)
+ }
+
+ err = mgr.LoadFromMCPConfig(context.Background(), config.MCPConfig{Enabled: true}, "/tmp")
+ if err != nil {
+ t.Fatalf("expected nil error when no servers configured, got: %v", err)
+ }
+}
+
+func TestGetServers_ReturnsCopy(t *testing.T) {
+ mgr := NewManager()
+ mgr.servers["s1"] = &ServerConnection{Name: "s1"}
+
+ servers := mgr.GetServers()
+ delete(servers, "s1")
+
+ if _, ok := mgr.GetServer("s1"); !ok {
+ t.Fatal("expected internal manager state to remain unchanged")
+ }
+}
+
+func TestGetAllTools_FiltersEmptyTools(t *testing.T) {
+ mgr := NewManager()
+ mgr.servers["empty"] = &ServerConnection{Name: "empty", Tools: nil}
+ mgr.servers["with-tools"] = &ServerConnection{Name: "with-tools", Tools: []*sdkmcp.Tool{{}}}
+
+ all := mgr.GetAllTools()
+ if _, ok := all["empty"]; ok {
+ t.Fatal("expected server without tools to be excluded")
+ }
+ if _, ok := all["with-tools"]; !ok {
+ t.Fatal("expected server with tools to be included")
+ }
+}
+
+func TestCallTool_ErrorsForClosedOrMissingServer(t *testing.T) {
+ t.Run("manager closed", func(t *testing.T) {
+ mgr := NewManager()
+ mgr.closed.Store(true)
+
+ _, err := mgr.CallTool(context.Background(), "s1", "tool", nil)
+ if err == nil || !strings.Contains(err.Error(), "manager is closed") {
+ t.Fatalf("expected manager closed error, got: %v", err)
+ }
+ })
+
+ t.Run("server missing", func(t *testing.T) {
+ mgr := NewManager()
+
+ _, err := mgr.CallTool(context.Background(), "missing", "tool", nil)
+ if err == nil || !strings.Contains(err.Error(), "not found") {
+ t.Fatalf("expected server not found error, got: %v", err)
+ }
+ })
+}
+
+func TestClose_IdempotentOnEmptyManager(t *testing.T) {
+ mgr := NewManager()
+
+ if err := mgr.Close(); err != nil {
+ t.Fatalf("first close should succeed, got: %v", err)
+ }
+ if err := mgr.Close(); err != nil {
+ t.Fatalf("second close should be idempotent, got: %v", err)
+ }
+}
diff --git a/pkg/media/store.go b/pkg/media/store.go
new file mode 100644
index 000000000..30220986c
--- /dev/null
+++ b/pkg/media/store.go
@@ -0,0 +1,271 @@
+package media
+
+import (
+ "fmt"
+ "os"
+ "sync"
+ "time"
+
+ "github.com/google/uuid"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// MediaMeta holds metadata about a stored media file.
+type MediaMeta struct {
+ Filename string
+ ContentType string
+ Source string // "telegram", "discord", "tool:image-gen", etc.
+}
+
+// MediaStore manages the lifecycle of media files associated with processing scopes.
+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.
+ Store(localPath string, meta MediaMeta, scope string) (ref string, err error)
+
+ // Resolve returns the local file path for a given ref.
+ Resolve(ref string) (localPath string, err error)
+
+ // ResolveWithMeta returns the local file path and metadata for a given ref.
+ ResolveWithMeta(ref string) (localPath string, meta MediaMeta, err error)
+
+ // ReleaseAll deletes all files registered under the given scope
+ // and removes the mapping entries. File-not-exist errors are ignored.
+ ReleaseAll(scope string) error
+}
+
+// mediaEntry holds the path and metadata for a stored media file.
+type mediaEntry struct {
+ path string
+ meta MediaMeta
+ storedAt time.Time
+}
+
+// MediaCleanerConfig configures the background TTL cleanup.
+type MediaCleanerConfig struct {
+ Enabled bool
+ MaxAge time.Duration
+ Interval time.Duration
+}
+
+// FileMediaStore is a pure in-memory implementation of MediaStore.
+// Files are expected to already exist on disk (e.g. in /tmp/picoclaw_media/).
+type FileMediaStore struct {
+ mu sync.RWMutex
+ refs map[string]mediaEntry
+ scopeToRefs map[string]map[string]struct{}
+ refToScope map[string]string
+
+ cleanerCfg MediaCleanerConfig
+ stop chan struct{}
+ startOnce sync.Once
+ stopOnce sync.Once
+ nowFunc func() time.Time // for testing
+}
+
+// NewFileMediaStore creates a new FileMediaStore without background cleanup.
+func NewFileMediaStore() *FileMediaStore {
+ return &FileMediaStore{
+ refs: make(map[string]mediaEntry),
+ scopeToRefs: make(map[string]map[string]struct{}),
+ refToScope: make(map[string]string),
+ nowFunc: time.Now,
+ }
+}
+
+// NewFileMediaStoreWithCleanup creates a FileMediaStore with TTL-based background cleanup.
+func NewFileMediaStoreWithCleanup(cfg MediaCleanerConfig) *FileMediaStore {
+ return &FileMediaStore{
+ refs: make(map[string]mediaEntry),
+ scopeToRefs: make(map[string]map[string]struct{}),
+ refToScope: make(map[string]string),
+ cleanerCfg: cfg,
+ stop: make(chan struct{}),
+ nowFunc: time.Now,
+ }
+}
+
+// Store registers a local file under the given scope. The file must exist.
+func (s *FileMediaStore) Store(localPath string, meta MediaMeta, scope string) (string, error) {
+ if _, err := os.Stat(localPath); err != nil {
+ return "", fmt.Errorf("media store: %s: %w", localPath, err)
+ }
+
+ ref := "media://" + uuid.New().String()
+
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ s.refs[ref] = mediaEntry{path: localPath, meta: meta, storedAt: s.nowFunc()}
+ if s.scopeToRefs[scope] == nil {
+ s.scopeToRefs[scope] = make(map[string]struct{})
+ }
+ s.scopeToRefs[scope][ref] = struct{}{}
+ s.refToScope[ref] = scope
+
+ return ref, nil
+}
+
+// Resolve returns the local path for the given ref.
+func (s *FileMediaStore) Resolve(ref string) (string, error) {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+
+ entry, ok := s.refs[ref]
+ if !ok {
+ return "", fmt.Errorf("media store: unknown ref: %s", ref)
+ }
+ return entry.path, nil
+}
+
+// ResolveWithMeta returns the local path and metadata for the given ref.
+func (s *FileMediaStore) ResolveWithMeta(ref string) (string, MediaMeta, error) {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+
+ entry, ok := s.refs[ref]
+ if !ok {
+ return "", MediaMeta{}, fmt.Errorf("media store: unknown ref: %s", ref)
+ }
+ return entry.path, entry.meta, nil
+}
+
+// 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.
+func (s *FileMediaStore) ReleaseAll(scope string) error {
+ // Phase 1: collect paths and remove from maps under lock
+ var paths []string
+
+ s.mu.Lock()
+ refs, ok := s.scopeToRefs[scope]
+ if !ok {
+ s.mu.Unlock()
+ return nil
+ }
+
+ for ref := range refs {
+ if entry, exists := s.refs[ref]; exists {
+ paths = append(paths, entry.path)
+ }
+ delete(s.refs, ref)
+ delete(s.refToScope, ref)
+ }
+ delete(s.scopeToRefs, scope)
+ s.mu.Unlock()
+
+ // Phase 2: delete files without holding the lock
+ for _, p := range paths {
+ if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
+ logger.WarnCF("media", "release: failed to remove file", map[string]any{
+ "path": p,
+ "error": err.Error(),
+ })
+ }
+ }
+
+ return nil
+}
+
+// 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.
+func (s *FileMediaStore) CleanExpired() int {
+ if s.cleanerCfg.MaxAge <= 0 {
+ return 0
+ }
+
+ // Phase 1: collect expired entries under lock
+ type expiredEntry struct {
+ ref string
+ path string
+ }
+
+ s.mu.Lock()
+ cutoff := s.nowFunc().Add(-s.cleanerCfg.MaxAge)
+ var expired []expiredEntry
+
+ 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)
+ if len(scopeRefs) == 0 {
+ delete(s.scopeToRefs, scope)
+ }
+ }
+ }
+
+ delete(s.refs, ref)
+ delete(s.refToScope, ref)
+ }
+ }
+ 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) {
+ logger.WarnCF("media", "cleanup: failed to remove file", map[string]any{
+ "path": e.path,
+ "error": err.Error(),
+ })
+ }
+ }
+
+ return len(expired)
+}
+
+// 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() {
+ if !s.cleanerCfg.Enabled || s.stop == nil {
+ return
+ }
+ if s.cleanerCfg.Interval <= 0 || s.cleanerCfg.MaxAge <= 0 {
+ logger.WarnCF("media", "cleanup: skipped due to invalid config", map[string]any{
+ "interval": s.cleanerCfg.Interval.String(),
+ "max_age": s.cleanerCfg.MaxAge.String(),
+ })
+ return
+ }
+
+ s.startOnce.Do(func() {
+ logger.InfoCF("media", "cleanup enabled", map[string]any{
+ "interval": s.cleanerCfg.Interval.String(),
+ "max_age": s.cleanerCfg.MaxAge.String(),
+ })
+
+ go func() {
+ ticker := time.NewTicker(s.cleanerCfg.Interval)
+ defer ticker.Stop()
+
+ for {
+ select {
+ case <-ticker.C:
+ if n := s.CleanExpired(); n > 0 {
+ logger.InfoCF("media", "cleanup: removed expired entries", map[string]any{
+ "count": n,
+ })
+ }
+ case <-s.stop:
+ return
+ }
+ }
+ }()
+ })
+}
+
+// Stop terminates the background cleanup goroutine.
+// Safe to call multiple times; only the first call closes the channel.
+func (s *FileMediaStore) Stop() {
+ if s.stop == nil {
+ return
+ }
+ s.stopOnce.Do(func() {
+ close(s.stop)
+ })
+}
diff --git a/pkg/media/store_test.go b/pkg/media/store_test.go
new file mode 100644
index 000000000..1dcfdf350
--- /dev/null
+++ b/pkg/media/store_test.go
@@ -0,0 +1,530 @@
+package media
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "testing"
+ "time"
+)
+
+func createTempFile(t *testing.T, dir, name string) string {
+ t.Helper()
+ path := filepath.Join(dir, name)
+ if err := os.WriteFile(path, []byte("test content"), 0o644); err != nil {
+ t.Fatalf("failed to create temp file: %v", err)
+ }
+ return path
+}
+
+func TestStoreAndResolve(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ path := createTempFile(t, dir, "photo.jpg")
+
+ ref, err := store.Store(path, MediaMeta{Filename: "photo.jpg", Source: "telegram"}, "scope1")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+
+ if !strings.HasPrefix(ref, "media://") {
+ t.Errorf("ref should start with media://, got %q", ref)
+ }
+
+ resolved, err := store.Resolve(ref)
+ if err != nil {
+ t.Fatalf("Resolve failed: %v", err)
+ }
+ if resolved != path {
+ t.Errorf("Resolve returned %q, want %q", resolved, path)
+ }
+}
+
+func TestReleaseAll(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ paths := make([]string, 3)
+ refs := make([]string, 3)
+ for i := range 3 {
+ paths[i] = createTempFile(t, dir, strings.Repeat("a", i+1)+".jpg")
+ var err error
+ refs[i], err = store.Store(paths[i], MediaMeta{Source: "test"}, "scope1")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+ }
+
+ if err := store.ReleaseAll("scope1"); err != nil {
+ t.Fatalf("ReleaseAll failed: %v", err)
+ }
+
+ // Files should be deleted
+ for _, p := range paths {
+ if _, err := os.Stat(p); !os.IsNotExist(err) {
+ t.Errorf("file %q should have been deleted", p)
+ }
+ }
+
+ // Refs should be unresolvable
+ for _, ref := range refs {
+ if _, err := store.Resolve(ref); err == nil {
+ t.Errorf("Resolve(%q) should fail after ReleaseAll", ref)
+ }
+ }
+}
+
+func TestMultiScopeIsolation(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ pathA := createTempFile(t, dir, "fileA.jpg")
+ pathB := createTempFile(t, dir, "fileB.jpg")
+
+ refA, _ := store.Store(pathA, MediaMeta{Source: "test"}, "scopeA")
+ refB, _ := store.Store(pathB, MediaMeta{Source: "test"}, "scopeB")
+
+ // Release only scopeA
+ if err := store.ReleaseAll("scopeA"); err != nil {
+ t.Fatalf("ReleaseAll(scopeA) failed: %v", err)
+ }
+
+ // scopeA file should be gone
+ if _, err := os.Stat(pathA); !os.IsNotExist(err) {
+ t.Error("file A should have been deleted")
+ }
+ if _, err := store.Resolve(refA); err == nil {
+ t.Error("refA should be unresolvable after release")
+ }
+
+ // scopeB file should still exist
+ if _, err := os.Stat(pathB); err != nil {
+ t.Error("file B should still exist")
+ }
+ resolved, err := store.Resolve(refB)
+ if err != nil {
+ t.Fatalf("refB should still resolve: %v", err)
+ }
+ if resolved != pathB {
+ t.Errorf("resolved %q, want %q", resolved, pathB)
+ }
+}
+
+func TestReleaseAllIdempotent(t *testing.T) {
+ store := NewFileMediaStore()
+
+ // ReleaseAll on non-existent scope should not error
+ if err := store.ReleaseAll("nonexistent"); err != nil {
+ t.Fatalf("ReleaseAll on empty scope should not error: %v", err)
+ }
+
+ // Create and release, then release again
+ dir := t.TempDir()
+ path := createTempFile(t, dir, "file.jpg")
+ _, _ = store.Store(path, MediaMeta{Source: "test"}, "scope1")
+
+ if err := store.ReleaseAll("scope1"); err != nil {
+ t.Fatalf("first ReleaseAll failed: %v", err)
+ }
+ if err := store.ReleaseAll("scope1"); err != nil {
+ t.Fatalf("second ReleaseAll should not error: %v", err)
+ }
+}
+
+func TestReleaseAllCleansMappingsIfRefsMissing(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ path := createTempFile(t, dir, "file.jpg")
+ ref, err := store.Store(path, MediaMeta{Source: "test"}, "scope1")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+
+ // Simulate internal inconsistency: scopeToRefs/refToScope contains ref but refs map doesn't.
+ store.mu.Lock()
+ delete(store.refs, ref)
+ store.mu.Unlock()
+
+ if err := store.ReleaseAll("scope1"); err != nil {
+ t.Fatalf("ReleaseAll failed: %v", err)
+ }
+
+ // ReleaseAll should still clean mappings (even if it can't delete the file without the path).
+ store.mu.RLock()
+ defer store.mu.RUnlock()
+ if _, ok := store.refToScope[ref]; ok {
+ t.Error("refToScope should not contain ref after ReleaseAll")
+ }
+ if _, ok := store.scopeToRefs["scope1"]; ok {
+ t.Error("scopeToRefs should not contain scope1 after ReleaseAll")
+ }
+}
+
+func TestStoreNonexistentFile(t *testing.T) {
+ store := NewFileMediaStore()
+
+ _, err := store.Store("/nonexistent/path/file.jpg", MediaMeta{Source: "test"}, "scope1")
+ if err == nil {
+ t.Error("Store should fail for nonexistent file")
+ }
+ // Error message should include the underlying os error, not just "file does not exist"
+ if !strings.Contains(err.Error(), "no such file or directory") &&
+ !strings.Contains(err.Error(), "cannot find") {
+ t.Errorf("Error should contain OS error detail, got: %v", err)
+ }
+}
+
+func TestResolveWithMeta(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ path := createTempFile(t, dir, "image.png")
+ meta := MediaMeta{
+ Filename: "image.png",
+ ContentType: "image/png",
+ Source: "telegram",
+ }
+
+ ref, err := store.Store(path, meta, "scope1")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+
+ resolvedPath, resolvedMeta, err := store.ResolveWithMeta(ref)
+ if err != nil {
+ t.Fatalf("ResolveWithMeta failed: %v", err)
+ }
+ if resolvedPath != path {
+ t.Errorf("ResolveWithMeta path = %q, want %q", resolvedPath, path)
+ }
+ if resolvedMeta.Filename != meta.Filename {
+ t.Errorf("ResolveWithMeta Filename = %q, want %q", resolvedMeta.Filename, meta.Filename)
+ }
+ if resolvedMeta.ContentType != meta.ContentType {
+ t.Errorf("ResolveWithMeta ContentType = %q, want %q", resolvedMeta.ContentType, meta.ContentType)
+ }
+ if resolvedMeta.Source != meta.Source {
+ t.Errorf("ResolveWithMeta Source = %q, want %q", resolvedMeta.Source, meta.Source)
+ }
+
+ // Unknown ref should fail
+ _, _, err = store.ResolveWithMeta("media://nonexistent")
+ if err == nil {
+ t.Error("ResolveWithMeta should fail for unknown ref")
+ }
+}
+
+func TestConcurrentSafety(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ const goroutines = 20
+ const filesPerGoroutine = 5
+
+ var wg sync.WaitGroup
+ wg.Add(goroutines)
+
+ for g := range goroutines {
+ go func(gIdx int) {
+ defer wg.Done()
+ scope := strings.Repeat("s", gIdx+1)
+
+ for i := range filesPerGoroutine {
+ path := createTempFile(t, dir, strings.Repeat("f", gIdx*filesPerGoroutine+i+1)+".tmp")
+ ref, err := store.Store(path, MediaMeta{Source: "test"}, scope)
+ if err != nil {
+ t.Errorf("Store failed: %v", err)
+ return
+ }
+
+ if _, err := store.Resolve(ref); err != nil {
+ t.Errorf("Resolve failed: %v", err)
+ }
+ }
+
+ if err := store.ReleaseAll(scope); err != nil {
+ t.Errorf("ReleaseAll failed: %v", err)
+ }
+ }(g)
+ }
+
+ wg.Wait()
+}
+
+// --- TTL cleanup tests ---
+
+func newTestStoreWithCleanup(maxAge time.Duration) *FileMediaStore {
+ s := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+ Enabled: true,
+ MaxAge: maxAge,
+ Interval: time.Hour, // won't tick in tests
+ })
+ return s
+}
+
+func TestCleanExpiredRemovesOldEntries(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, "old.jpg")
+ ref, err := store.Store(path, MediaMeta{Source: "test"}, "scope1")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+
+ // Advance clock to present
+ 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 ref should be unresolvable")
+ }
+ if _, err := os.Stat(path); !os.IsNotExist(err) {
+ t.Error("expired file should be deleted")
+ }
+}
+
+func TestCleanExpiredKeepsNonExpired(t *testing.T) {
+ dir := t.TempDir()
+ now := time.Now()
+ store := newTestStoreWithCleanup(10 * time.Minute)
+ store.nowFunc = func() time.Time { return now }
+
+ path := createTempFile(t, dir, "fresh.jpg")
+ ref, err := store.Store(path, MediaMeta{Source: "test"}, "scope1")
+ if err != nil {
+ t.Fatalf("Store failed: %v", err)
+ }
+
+ removed := store.CleanExpired()
+ if removed != 0 {
+ t.Errorf("expected 0 removed, got %d", removed)
+ }
+
+ if _, err := store.Resolve(ref); err != nil {
+ t.Errorf("fresh ref should still resolve: %v", err)
+ }
+ if _, err := os.Stat(path); err != nil {
+ t.Error("fresh file should still exist")
+ }
+}
+
+func TestCleanExpiredMixedAges(t *testing.T) {
+ dir := t.TempDir()
+ now := time.Now()
+ store := newTestStoreWithCleanup(10 * time.Minute)
+
+ // Store old entry
+ store.nowFunc = func() time.Time { return now.Add(-20 * time.Minute) }
+ oldPath := createTempFile(t, dir, "old.jpg")
+ oldRef, _ := store.Store(oldPath, MediaMeta{Source: "test"}, "scope1")
+
+ // Store fresh entry
+ store.nowFunc = func() time.Time { return now }
+ freshPath := createTempFile(t, dir, "fresh.jpg")
+ freshRef, _ := store.Store(freshPath, MediaMeta{Source: "test"}, "scope1")
+
+ 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")
+ }
+ if _, err := store.Resolve(freshRef); err != nil {
+ t.Errorf("fresh ref should still resolve: %v", err)
+ }
+}
+
+func TestCleanExpiredCleansEmptyScopes(t *testing.T) {
+ dir := t.TempDir()
+ now := time.Now()
+ store := newTestStoreWithCleanup(10 * time.Minute)
+
+ // Store old entry as the only one in scope
+ store.nowFunc = func() time.Time { return now.Add(-20 * time.Minute) }
+ path := createTempFile(t, dir, "only.jpg")
+ store.Store(path, MediaMeta{Source: "test"}, "lonely_scope")
+
+ store.nowFunc = func() time.Time { return now }
+ store.CleanExpired()
+
+ store.mu.RLock()
+ defer store.mu.RUnlock()
+ if _, ok := store.scopeToRefs["lonely_scope"]; ok {
+ t.Error("empty scope should be cleaned up")
+ }
+}
+
+func TestStartStopLifecycle(t *testing.T) {
+ store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+ Enabled: true,
+ MaxAge: time.Minute,
+ Interval: 50 * time.Millisecond,
+ })
+
+ // Start and stop should not panic
+ store.Start()
+ // Double start should not spawn a second goroutine
+ store.Start()
+ time.Sleep(100 * time.Millisecond)
+ store.Stop()
+
+ // Double stop should not panic
+ store.Stop()
+}
+
+func TestCleanExpiredZeroMaxAge(t *testing.T) {
+ store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+ Enabled: true,
+ MaxAge: 0,
+ Interval: time.Hour,
+ })
+
+ dir := t.TempDir()
+ path := createTempFile(t, dir, "file.jpg")
+ ref, _ := store.Store(path, MediaMeta{Source: "test"}, "scope1")
+
+ // Zero MaxAge should be a no-op
+ removed := store.CleanExpired()
+ if removed != 0 {
+ t.Errorf("expected 0 removed with zero MaxAge, got %d", removed)
+ }
+ if _, err := store.Resolve(ref); err != nil {
+ t.Errorf("ref should still resolve: %v", err)
+ }
+}
+
+func TestStartDisabledIsNoop(t *testing.T) {
+ store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+ Enabled: false,
+ MaxAge: time.Minute,
+ Interval: time.Minute,
+ })
+ // Should not start any goroutine or panic
+ store.Start()
+ store.Stop()
+}
+
+func TestStartZeroIntervalNoPanic(t *testing.T) {
+ store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+ Enabled: true,
+ MaxAge: time.Minute,
+ Interval: 0,
+ })
+ // Zero interval should not panic (time.NewTicker panics on <= 0)
+ store.Start()
+ store.Stop()
+}
+
+func TestStartZeroMaxAgeNoPanic(t *testing.T) {
+ store := NewFileMediaStoreWithCleanup(MediaCleanerConfig{
+ Enabled: true,
+ MaxAge: 0,
+ Interval: time.Minute,
+ })
+ store.Start()
+ store.Stop()
+}
+
+func TestConcurrentCleanupSafety(t *testing.T) {
+ dir := t.TempDir()
+ store := newTestStoreWithCleanup(50 * time.Millisecond)
+ store.nowFunc = time.Now
+
+ const workers = 10
+ const ops = 20
+ var wg sync.WaitGroup
+ wg.Add(workers * 4)
+
+ // Store workers
+ for w := range workers {
+ go func(wIdx int) {
+ defer wg.Done()
+ scope := fmt.Sprintf("scope-%d", wIdx)
+ for i := range ops {
+ p := createTempFile(t, dir, fmt.Sprintf("w%d-f%d.tmp", wIdx, i))
+ store.Store(p, MediaMeta{Source: "test"}, scope)
+ }
+ }(w)
+ }
+
+ // Resolve workers
+ for range workers {
+ go func() {
+ defer wg.Done()
+ for range ops {
+ store.Resolve("media://nonexistent")
+ }
+ }()
+ }
+
+ // ReleaseAll workers
+ for w := range workers {
+ go func(wIdx int) {
+ defer wg.Done()
+ for range ops {
+ store.ReleaseAll(fmt.Sprintf("scope-%d", wIdx))
+ }
+ }(w)
+ }
+
+ // CleanExpired workers
+ for range workers {
+ go func() {
+ defer wg.Done()
+ for range ops {
+ store.CleanExpired()
+ }
+ }()
+ }
+
+ wg.Wait()
+}
+
+func TestRefToScopeConsistency(t *testing.T) {
+ dir := t.TempDir()
+ store := NewFileMediaStore()
+
+ // Store entries in two scopes
+ ref1, _ := store.Store(createTempFile(t, dir, "a.jpg"), MediaMeta{Source: "test"}, "s1")
+ ref2, _ := store.Store(createTempFile(t, dir, "b.jpg"), MediaMeta{Source: "test"}, "s1")
+ ref3, _ := store.Store(createTempFile(t, dir, "c.jpg"), MediaMeta{Source: "test"}, "s2")
+
+ store.mu.RLock()
+ checkRef := func(ref, expectedScope string) {
+ t.Helper()
+ if scope, ok := store.refToScope[ref]; !ok || scope != expectedScope {
+ t.Errorf("refToScope[%s] = %q, want %q", ref, scope, expectedScope)
+ }
+ }
+ checkRef(ref1, "s1")
+ checkRef(ref2, "s1")
+ checkRef(ref3, "s2")
+ store.mu.RUnlock()
+
+ // Release s1 and verify refToScope is cleaned
+ store.ReleaseAll("s1")
+
+ store.mu.RLock()
+ defer store.mu.RUnlock()
+ if _, ok := store.refToScope[ref1]; ok {
+ t.Error("refToScope should not contain ref1 after ReleaseAll")
+ }
+ if _, ok := store.refToScope[ref2]; ok {
+ t.Error("refToScope should not contain ref2 after ReleaseAll")
+ }
+ if _, ok := store.refToScope[ref3]; !ok {
+ t.Error("refToScope should still contain ref3")
+ }
+}
diff --git a/pkg/memory/jsonl.go b/pkg/memory/jsonl.go
new file mode 100644
index 000000000..e12e2c5ab
--- /dev/null
+++ b/pkg/memory/jsonl.go
@@ -0,0 +1,460 @@
+package memory
+
+import (
+ "bufio"
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "hash/fnv"
+ "log"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/fileutil"
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+const (
+ // numLockShards is the fixed number of mutexes used to serialize
+ // per-session access. Using a sharded array instead of a map keeps
+ // memory bounded regardless of how many sessions are created over
+ // the lifetime of the process — important for a long-running daemon.
+ numLockShards = 64
+
+ // maxLineSize is the maximum size of a single JSON line in a .jsonl
+ // file. Tool results (read_file, web search, etc.) can be large, so
+ // we set a generous limit. The scanner starts at 64 KB and grows
+ // only as needed up to this cap.
+ maxLineSize = 10 * 1024 * 1024 // 10 MB
+)
+
+// sessionMeta holds per-session metadata stored in a .meta.json file.
+type sessionMeta struct {
+ Key string `json:"key"`
+ Summary string `json:"summary"`
+ Skip int `json:"skip"`
+ Count int `json:"count"`
+ CreatedAt time.Time `json:"created_at"`
+ UpdatedAt time.Time `json:"updated_at"`
+}
+
+// JSONLStore implements Store using append-only JSONL files.
+//
+// Each session is stored as two files:
+//
+// {sanitized_key}.jsonl — one JSON-encoded message per line, append-only
+// {sanitized_key}.meta.json — session metadata (summary, logical truncation offset)
+//
+// Messages are never physically deleted from the JSONL file. Instead,
+// TruncateHistory records a "skip" offset in the metadata file and
+// GetHistory ignores lines before that offset. This keeps all writes
+// append-only, which is both fast and crash-safe.
+type JSONLStore struct {
+ dir string
+ locks [numLockShards]sync.Mutex
+}
+
+// NewJSONLStore creates a new JSONL-backed store rooted at dir.
+func NewJSONLStore(dir string) (*JSONLStore, error) {
+ err := os.MkdirAll(dir, 0o755)
+ if err != nil {
+ return nil, fmt.Errorf("memory: create directory: %w", err)
+ }
+ return &JSONLStore{dir: dir}, nil
+}
+
+// sessionLock returns a mutex for the given session key.
+// Keys are mapped to a fixed pool of shards via FNV hash, so
+// memory usage is O(1) regardless of total session count.
+func (s *JSONLStore) sessionLock(key string) *sync.Mutex {
+ h := fnv.New32a()
+ h.Write([]byte(key))
+ return &s.locks[h.Sum32()%numLockShards]
+}
+
+func (s *JSONLStore) jsonlPath(key string) string {
+ return filepath.Join(s.dir, sanitizeKey(key)+".jsonl")
+}
+
+func (s *JSONLStore) metaPath(key string) string {
+ return filepath.Join(s.dir, sanitizeKey(key)+".meta.json")
+}
+
+// sanitizeKey converts a session key to a safe filename component.
+// Mirrors pkg/session.sanitizeFilename so that migration paths match.
+//
+// Note: this is a lossy mapping — "telegram:123" and "telegram_123"
+// both produce the same filename. This is an intentional tradeoff:
+// keys with colons (e.g. from channels) are by far the common case,
+// and a bidirectional encoding (like URL-encoding) would complicate
+// file listings and debugging.
+func sanitizeKey(key string) string {
+ return strings.ReplaceAll(key, ":", "_")
+}
+
+// readMeta loads the metadata file for a session.
+// Returns a zero-value sessionMeta if the file does not exist.
+func (s *JSONLStore) readMeta(key string) (sessionMeta, error) {
+ data, err := os.ReadFile(s.metaPath(key))
+ if os.IsNotExist(err) {
+ return sessionMeta{Key: key}, nil
+ }
+ if err != nil {
+ return sessionMeta{}, fmt.Errorf("memory: read meta: %w", err)
+ }
+ var meta sessionMeta
+ err = json.Unmarshal(data, &meta)
+ if err != nil {
+ return sessionMeta{}, fmt.Errorf("memory: decode meta: %w", err)
+ }
+ return meta, nil
+}
+
+// writeMeta atomically writes the metadata file using the project's
+// standard WriteFileAtomic (temp + fsync + rename).
+func (s *JSONLStore) writeMeta(key string, meta sessionMeta) error {
+ data, err := json.MarshalIndent(meta, "", " ")
+ if err != nil {
+ return fmt.Errorf("memory: encode meta: %w", err)
+ }
+ return fileutil.WriteFileAtomic(s.metaPath(key), data, 0o644)
+}
+
+// readMessages reads valid JSON lines from a .jsonl file, skipping
+// the first `skip` lines without unmarshaling them. This avoids the
+// cost of json.Unmarshal on logically truncated messages.
+// Malformed trailing lines (e.g. from a crash) are silently skipped.
+func readMessages(path string, skip int) ([]providers.Message, error) {
+ f, err := os.Open(path)
+ if os.IsNotExist(err) {
+ return []providers.Message{}, nil
+ }
+ if err != nil {
+ return nil, fmt.Errorf("memory: open jsonl: %w", err)
+ }
+ defer f.Close()
+
+ var msgs []providers.Message
+ scanner := bufio.NewScanner(f)
+ // Allow large lines for tool results (read_file, web search, etc.).
+ scanner.Buffer(make([]byte, 0, 64*1024), maxLineSize)
+
+ lineNum := 0
+ for scanner.Scan() {
+ line := scanner.Bytes()
+ if len(line) == 0 {
+ continue
+ }
+ lineNum++
+ if lineNum <= skip {
+ continue
+ }
+ var msg providers.Message
+ if err := json.Unmarshal(line, &msg); err != nil {
+ // Corrupt line — likely a partial write from a crash.
+ // Log so operators know data was skipped, but don't
+ // fail the entire read; this is the standard JSONL
+ // recovery pattern.
+ log.Printf("memory: skipping corrupt line %d in %s: %v",
+ lineNum, filepath.Base(path), err)
+ continue
+ }
+ msgs = append(msgs, msg)
+ }
+ if scanner.Err() != nil {
+ return nil, fmt.Errorf("memory: scan jsonl: %w", scanner.Err())
+ }
+
+ if msgs == nil {
+ msgs = []providers.Message{}
+ }
+ return msgs, nil
+}
+
+// countLines counts the total number of non-empty lines in a .jsonl file.
+// Used by TruncateHistory to reconcile a stale meta.Count without
+// the overhead of unmarshaling every message.
+func countLines(path string) (int, error) {
+ f, err := os.Open(path)
+ if os.IsNotExist(err) {
+ return 0, nil
+ }
+ if err != nil {
+ return 0, fmt.Errorf("memory: open jsonl: %w", err)
+ }
+ defer f.Close()
+
+ n := 0
+ scanner := bufio.NewScanner(f)
+ scanner.Buffer(make([]byte, 0, 64*1024), maxLineSize)
+ for scanner.Scan() {
+ if len(scanner.Bytes()) > 0 {
+ n++
+ }
+ }
+ return n, scanner.Err()
+}
+
+func (s *JSONLStore) AddMessage(
+ _ context.Context, sessionKey, role, content string,
+) error {
+ return s.addMsg(sessionKey, providers.Message{
+ Role: role,
+ Content: content,
+ })
+}
+
+func (s *JSONLStore) AddFullMessage(
+ _ context.Context, sessionKey string, msg providers.Message,
+) error {
+ return s.addMsg(sessionKey, msg)
+}
+
+// addMsg is the shared implementation for AddMessage and AddFullMessage.
+func (s *JSONLStore) addMsg(sessionKey string, msg providers.Message) error {
+ l := s.sessionLock(sessionKey)
+ l.Lock()
+ defer l.Unlock()
+
+ // Append the message as a single JSON line.
+ line, err := json.Marshal(msg)
+ if err != nil {
+ return fmt.Errorf("memory: marshal message: %w", err)
+ }
+ line = append(line, '\n')
+
+ f, err := os.OpenFile(
+ s.jsonlPath(sessionKey),
+ os.O_CREATE|os.O_WRONLY|os.O_APPEND,
+ 0o644,
+ )
+ if err != nil {
+ return fmt.Errorf("memory: open jsonl for append: %w", err)
+ }
+ _, writeErr := f.Write(line)
+ if writeErr != nil {
+ f.Close()
+ return fmt.Errorf("memory: append message: %w", writeErr)
+ }
+ // Flush to physical storage before closing. This matches the
+ // durability guarantee of writeMeta and rewriteJSONL (which use
+ // WriteFileAtomic with fsync). Without Sync, a power loss could
+ // leave the append in the kernel page cache only — lost on reboot.
+ if syncErr := f.Sync(); syncErr != nil {
+ f.Close()
+ return fmt.Errorf("memory: sync jsonl: %w", syncErr)
+ }
+ if closeErr := f.Close(); closeErr != nil {
+ return fmt.Errorf("memory: close jsonl: %w", closeErr)
+ }
+
+ // Update metadata.
+ meta, err := s.readMeta(sessionKey)
+ if err != nil {
+ return err
+ }
+ now := time.Now()
+ if meta.Count == 0 && meta.CreatedAt.IsZero() {
+ meta.CreatedAt = now
+ }
+ meta.Count++
+ meta.UpdatedAt = now
+
+ return s.writeMeta(sessionKey, meta)
+}
+
+func (s *JSONLStore) GetHistory(
+ _ context.Context, sessionKey string,
+) ([]providers.Message, error) {
+ l := s.sessionLock(sessionKey)
+ l.Lock()
+ defer l.Unlock()
+
+ meta, err := s.readMeta(sessionKey)
+ if err != nil {
+ return nil, err
+ }
+
+ // Pass meta.Skip so readMessages skips those lines without
+ // unmarshaling them — avoids wasted CPU on truncated messages.
+ msgs, err := readMessages(s.jsonlPath(sessionKey), meta.Skip)
+ if err != nil {
+ return nil, err
+ }
+
+ return msgs, nil
+}
+
+func (s *JSONLStore) GetSummary(
+ _ context.Context, sessionKey string,
+) (string, error) {
+ l := s.sessionLock(sessionKey)
+ l.Lock()
+ defer l.Unlock()
+
+ meta, err := s.readMeta(sessionKey)
+ if err != nil {
+ return "", err
+ }
+ return meta.Summary, nil
+}
+
+func (s *JSONLStore) SetSummary(
+ _ context.Context, sessionKey, summary string,
+) error {
+ l := s.sessionLock(sessionKey)
+ l.Lock()
+ defer l.Unlock()
+
+ meta, err := s.readMeta(sessionKey)
+ if err != nil {
+ return err
+ }
+ now := time.Now()
+ if meta.CreatedAt.IsZero() {
+ meta.CreatedAt = now
+ }
+ meta.Summary = summary
+ meta.UpdatedAt = now
+
+ return s.writeMeta(sessionKey, meta)
+}
+
+func (s *JSONLStore) TruncateHistory(
+ _ context.Context, sessionKey string, keepLast int,
+) error {
+ l := s.sessionLock(sessionKey)
+ l.Lock()
+ defer l.Unlock()
+
+ meta, err := s.readMeta(sessionKey)
+ if err != nil {
+ return err
+ }
+
+ // Always reconcile meta.Count with the actual line count on disk.
+ // A crash between the JSONL append and the meta update in addMsg
+ // leaves meta.Count stale (e.g. file has 101 lines but meta says
+ // 100). Counting lines is cheap — no unmarshal, just a scan — and
+ // TruncateHistory is not a hot path, so always re-count.
+ n, countErr := countLines(s.jsonlPath(sessionKey))
+ if countErr != nil {
+ return countErr
+ }
+ meta.Count = n
+
+ if keepLast <= 0 {
+ meta.Skip = meta.Count
+ } else {
+ effective := meta.Count - meta.Skip
+ if keepLast < effective {
+ meta.Skip = meta.Count - keepLast
+ }
+ }
+ meta.UpdatedAt = time.Now()
+
+ return s.writeMeta(sessionKey, meta)
+}
+
+func (s *JSONLStore) SetHistory(
+ _ context.Context,
+ sessionKey string,
+ history []providers.Message,
+) error {
+ l := s.sessionLock(sessionKey)
+ l.Lock()
+ defer l.Unlock()
+
+ meta, err := s.readMeta(sessionKey)
+ if err != nil {
+ return err
+ }
+ now := time.Now()
+ if meta.CreatedAt.IsZero() {
+ meta.CreatedAt = now
+ }
+ meta.Skip = 0
+ meta.Count = len(history)
+ meta.UpdatedAt = now
+
+ // Write meta BEFORE rewriting the JSONL file. If we crash between
+ // the two writes, meta has Skip=0 and the old file is still intact,
+ // so GetHistory reads from line 1 — returning "too many" messages
+ // rather than losing data. The next SetHistory call corrects this.
+ err = s.writeMeta(sessionKey, meta)
+ if err != nil {
+ return err
+ }
+
+ return s.rewriteJSONL(sessionKey, history)
+}
+
+// Compact physically rewrites the JSONL file, dropping all logically
+// skipped lines. This reclaims disk space that accumulates after
+// repeated TruncateHistory calls.
+//
+// It is safe to call at any time; if there is nothing to compact
+// (skip == 0) the method returns immediately.
+func (s *JSONLStore) Compact(
+ _ context.Context, sessionKey string,
+) error {
+ l := s.sessionLock(sessionKey)
+ l.Lock()
+ defer l.Unlock()
+
+ meta, err := s.readMeta(sessionKey)
+ if err != nil {
+ return err
+ }
+ if meta.Skip == 0 {
+ return nil
+ }
+
+ // Read only the active messages, skipping truncated lines
+ // without unmarshaling them.
+ active, err := readMessages(s.jsonlPath(sessionKey), meta.Skip)
+ if err != nil {
+ return err
+ }
+
+ // Write meta BEFORE rewriting the JSONL file. If the process
+ // crashes between the two writes, meta has Skip=0 and the old
+ // (uncompacted) file is still intact, so GetHistory reads from
+ // line 1 — returning previously-truncated messages rather than
+ // losing data. The next Compact or TruncateHistory corrects this.
+ meta.Skip = 0
+ meta.Count = len(active)
+ meta.UpdatedAt = time.Now()
+
+ err = s.writeMeta(sessionKey, meta)
+ if err != nil {
+ return err
+ }
+
+ return s.rewriteJSONL(sessionKey, active)
+}
+
+// rewriteJSONL atomically replaces the JSONL file with the given messages
+// using the project's standard WriteFileAtomic (temp + fsync + rename).
+func (s *JSONLStore) rewriteJSONL(
+ sessionKey string, msgs []providers.Message,
+) error {
+ var buf bytes.Buffer
+ for i, msg := range msgs {
+ line, err := json.Marshal(msg)
+ if err != nil {
+ return fmt.Errorf("memory: marshal message %d: %w", i, err)
+ }
+ buf.Write(line)
+ buf.WriteByte('\n')
+ }
+ return fileutil.WriteFileAtomic(s.jsonlPath(sessionKey), buf.Bytes(), 0o644)
+}
+
+func (s *JSONLStore) Close() error {
+ return nil
+}
diff --git a/pkg/memory/jsonl_test.go b/pkg/memory/jsonl_test.go
new file mode 100644
index 000000000..356ff14ff
--- /dev/null
+++ b/pkg/memory/jsonl_test.go
@@ -0,0 +1,835 @@
+package memory
+
+import (
+ "context"
+ "os"
+ "path/filepath"
+ "sync"
+ "testing"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func newTestStore(t *testing.T) *JSONLStore {
+ t.Helper()
+ store, err := NewJSONLStore(t.TempDir())
+ if err != nil {
+ t.Fatalf("NewJSONLStore: %v", err)
+ }
+ return store
+}
+
+func TestNewJSONLStore_CreatesDirectory(t *testing.T) {
+ dir := filepath.Join(t.TempDir(), "nested", "sessions")
+ store, err := NewJSONLStore(dir)
+ if err != nil {
+ t.Fatalf("NewJSONLStore: %v", err)
+ }
+ defer store.Close()
+
+ info, err := os.Stat(dir)
+ if err != nil {
+ t.Fatalf("Stat: %v", err)
+ }
+ if !info.IsDir() {
+ t.Errorf("expected directory, got file")
+ }
+}
+
+func TestAddMessage_BasicRoundtrip(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ err := store.AddMessage(ctx, "s1", "user", "hello")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ err = store.AddMessage(ctx, "s1", "assistant", "hi there")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "s1")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 2 {
+ t.Fatalf("expected 2 messages, got %d", len(history))
+ }
+ if history[0].Role != "user" || history[0].Content != "hello" {
+ t.Errorf("msg[0] = %+v", history[0])
+ }
+ if history[1].Role != "assistant" || history[1].Content != "hi there" {
+ t.Errorf("msg[1] = %+v", history[1])
+ }
+}
+
+func TestAddMessage_AutoCreatesSession(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // Adding a message to a non-existent session should work.
+ err := store.AddMessage(ctx, "new-session", "user", "first message")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "new-session")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Fatalf("expected 1 message, got %d", len(history))
+ }
+}
+
+func TestAddFullMessage_WithToolCalls(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ msg := providers.Message{
+ Role: "assistant",
+ Content: "Let me search that.",
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "call_abc",
+ Type: "function",
+ Function: &providers.FunctionCall{
+ Name: "web_search",
+ Arguments: `{"q":"golang jsonl"}`,
+ },
+ },
+ },
+ }
+
+ err := store.AddFullMessage(ctx, "tc", msg)
+ if err != nil {
+ t.Fatalf("AddFullMessage: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "tc")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Fatalf("expected 1, got %d", len(history))
+ }
+ if len(history[0].ToolCalls) != 1 {
+ t.Fatalf("expected 1 tool call, got %d", len(history[0].ToolCalls))
+ }
+ tc := history[0].ToolCalls[0]
+ if tc.ID != "call_abc" {
+ t.Errorf("tool call ID = %q", tc.ID)
+ }
+ if tc.Function == nil || tc.Function.Name != "web_search" {
+ t.Errorf("tool call function = %+v", tc.Function)
+ }
+}
+
+func TestAddFullMessage_ToolCallID(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ msg := providers.Message{
+ Role: "tool",
+ Content: "search results here",
+ ToolCallID: "call_abc",
+ }
+
+ err := store.AddFullMessage(ctx, "tr", msg)
+ if err != nil {
+ t.Fatalf("AddFullMessage: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "tr")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Fatalf("expected 1, got %d", len(history))
+ }
+ if history[0].ToolCallID != "call_abc" {
+ t.Errorf("ToolCallID = %q", history[0].ToolCallID)
+ }
+}
+
+func TestGetHistory_EmptySession(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ history, err := store.GetHistory(ctx, "nonexistent")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if history == nil {
+ t.Fatal("expected non-nil empty slice")
+ }
+ if len(history) != 0 {
+ t.Errorf("expected 0 messages, got %d", len(history))
+ }
+}
+
+func TestGetHistory_Ordering(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ for i := 0; i < 5; i++ {
+ err := store.AddMessage(
+ ctx, "order",
+ "user",
+ string(rune('a'+i)),
+ )
+ if err != nil {
+ t.Fatalf("AddMessage(%d): %v", i, err)
+ }
+ }
+
+ history, err := store.GetHistory(ctx, "order")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 5 {
+ t.Fatalf("expected 5, got %d", len(history))
+ }
+ for i := 0; i < 5; i++ {
+ expected := string(rune('a' + i))
+ if history[i].Content != expected {
+ t.Errorf("msg[%d].Content = %q, want %q", i, history[i].Content, expected)
+ }
+ }
+}
+
+func TestSetSummary_GetSummary(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // No summary yet.
+ summary, err := store.GetSummary(ctx, "s1")
+ if err != nil {
+ t.Fatalf("GetSummary: %v", err)
+ }
+ if summary != "" {
+ t.Errorf("expected empty, got %q", summary)
+ }
+
+ // Set a summary.
+ err = store.SetSummary(ctx, "s1", "talked about Go")
+ if err != nil {
+ t.Fatalf("SetSummary: %v", err)
+ }
+
+ summary, err = store.GetSummary(ctx, "s1")
+ if err != nil {
+ t.Fatalf("GetSummary: %v", err)
+ }
+ if summary != "talked about Go" {
+ t.Errorf("summary = %q", summary)
+ }
+
+ // Update summary.
+ err = store.SetSummary(ctx, "s1", "updated summary")
+ if err != nil {
+ t.Fatalf("SetSummary: %v", err)
+ }
+
+ summary, err = store.GetSummary(ctx, "s1")
+ if err != nil {
+ t.Fatalf("GetSummary: %v", err)
+ }
+ if summary != "updated summary" {
+ t.Errorf("summary = %q", summary)
+ }
+}
+
+func TestTruncateHistory_KeepLast(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ for i := 0; i < 10; i++ {
+ err := store.AddMessage(
+ ctx, "trunc",
+ "user",
+ string(rune('a'+i)),
+ )
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+
+ err := store.TruncateHistory(ctx, "trunc", 4)
+ if err != nil {
+ t.Fatalf("TruncateHistory: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "trunc")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 4 {
+ t.Fatalf("expected 4, got %d", len(history))
+ }
+ // Should be the last 4: g, h, i, j
+ if history[0].Content != "g" {
+ t.Errorf("first kept = %q, want 'g'", history[0].Content)
+ }
+ if history[3].Content != "j" {
+ t.Errorf("last kept = %q, want 'j'", history[3].Content)
+ }
+}
+
+func TestTruncateHistory_KeepZero(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ for i := 0; i < 5; i++ {
+ err := store.AddMessage(ctx, "empty", "user", "msg")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+
+ err := store.TruncateHistory(ctx, "empty", 0)
+ if err != nil {
+ t.Fatalf("TruncateHistory: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "empty")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 0 {
+ t.Errorf("expected 0, got %d", len(history))
+ }
+}
+
+func TestTruncateHistory_KeepMoreThanExists(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ for i := 0; i < 3; i++ {
+ err := store.AddMessage(ctx, "few", "user", "msg")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+
+ // Keep 100, but only 3 exist — should keep all.
+ err := store.TruncateHistory(ctx, "few", 100)
+ if err != nil {
+ t.Fatalf("TruncateHistory: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "few")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 3 {
+ t.Errorf("expected 3, got %d", len(history))
+ }
+}
+
+func TestSetHistory_ReplacesAll(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // Add some initial messages.
+ for i := 0; i < 5; i++ {
+ err := store.AddMessage(ctx, "replace", "user", "old")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+
+ // Replace with new history.
+ newHistory := []providers.Message{
+ {Role: "user", Content: "new1"},
+ {Role: "assistant", Content: "new2"},
+ }
+ err := store.SetHistory(ctx, "replace", newHistory)
+ if err != nil {
+ t.Fatalf("SetHistory: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "replace")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 2 {
+ t.Fatalf("expected 2, got %d", len(history))
+ }
+ if history[0].Content != "new1" || history[1].Content != "new2" {
+ t.Errorf("history = %+v", history)
+ }
+}
+
+func TestSetHistory_ResetsSkip(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // Add messages and truncate.
+ for i := 0; i < 10; i++ {
+ err := store.AddMessage(ctx, "skip-reset", "user", "old")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+ err := store.TruncateHistory(ctx, "skip-reset", 3)
+ if err != nil {
+ t.Fatalf("TruncateHistory: %v", err)
+ }
+
+ // SetHistory should reset skip to 0.
+ newHistory := []providers.Message{
+ {Role: "user", Content: "fresh"},
+ }
+ err = store.SetHistory(ctx, "skip-reset", newHistory)
+ if err != nil {
+ t.Fatalf("SetHistory: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "skip-reset")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Fatalf("expected 1, got %d", len(history))
+ }
+ if history[0].Content != "fresh" {
+ t.Errorf("content = %q", history[0].Content)
+ }
+}
+
+func TestColonInKey(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ err := store.AddMessage(ctx, "telegram:123", "user", "hi")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "telegram:123")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Fatalf("expected 1, got %d", len(history))
+ }
+
+ // Verify the file is named with underscore.
+ jsonlFile := filepath.Join(store.dir, "telegram_123.jsonl")
+ if _, statErr := os.Stat(jsonlFile); statErr != nil {
+ t.Errorf("expected file %s to exist: %v", jsonlFile, statErr)
+ }
+}
+
+func TestCompact_RemovesSkippedMessages(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // Write 10 messages, then truncate to keep last 3.
+ for i := 0; i < 10; i++ {
+ err := store.AddMessage(ctx, "compact", "user", string(rune('a'+i)))
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+ err := store.TruncateHistory(ctx, "compact", 3)
+ if err != nil {
+ t.Fatalf("TruncateHistory: %v", err)
+ }
+
+ // Before compact: file still has 10 lines.
+ allOnDisk, err := readMessages(store.jsonlPath("compact"), 0)
+ if err != nil {
+ t.Fatalf("readMessages: %v", err)
+ }
+ if len(allOnDisk) != 10 {
+ t.Fatalf("before compact: expected 10 on disk, got %d", len(allOnDisk))
+ }
+
+ // Compact.
+ err = store.Compact(ctx, "compact")
+ if err != nil {
+ t.Fatalf("Compact: %v", err)
+ }
+
+ // After compact: file should have only 3 lines.
+ allOnDisk, err = readMessages(store.jsonlPath("compact"), 0)
+ if err != nil {
+ t.Fatalf("readMessages: %v", err)
+ }
+ if len(allOnDisk) != 3 {
+ t.Fatalf("after compact: expected 3 on disk, got %d", len(allOnDisk))
+ }
+
+ // GetHistory should still return the same 3 messages.
+ history, err := store.GetHistory(ctx, "compact")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 3 {
+ t.Fatalf("expected 3, got %d", len(history))
+ }
+ if history[0].Content != "h" || history[2].Content != "j" {
+ t.Errorf("wrong content: %+v", history)
+ }
+}
+
+func TestCompact_NoOpWhenNoSkip(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ for i := 0; i < 5; i++ {
+ err := store.AddMessage(ctx, "noop", "user", "msg")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+
+ // Compact without prior truncation — should be a no-op.
+ err := store.Compact(ctx, "noop")
+ if err != nil {
+ t.Fatalf("Compact: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "noop")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 5 {
+ t.Errorf("expected 5, got %d", len(history))
+ }
+}
+
+func TestCompact_ThenAppend(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ for i := 0; i < 8; i++ {
+ err := store.AddMessage(ctx, "cap", "user", string(rune('a'+i)))
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+
+ err := store.TruncateHistory(ctx, "cap", 2)
+ if err != nil {
+ t.Fatalf("TruncateHistory: %v", err)
+ }
+ err = store.Compact(ctx, "cap")
+ if err != nil {
+ t.Fatalf("Compact: %v", err)
+ }
+
+ // Append after compaction should work correctly.
+ err = store.AddMessage(ctx, "cap", "user", "new")
+ if err != nil {
+ t.Fatalf("AddMessage after compact: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "cap")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 3 {
+ t.Fatalf("expected 3, got %d", len(history))
+ }
+ // g, h (kept from truncation), new (appended after compaction).
+ if history[0].Content != "g" {
+ t.Errorf("first = %q, want 'g'", history[0].Content)
+ }
+ if history[2].Content != "new" {
+ t.Errorf("last = %q, want 'new'", history[2].Content)
+ }
+}
+
+func TestTruncateHistory_StaleMetaCount(t *testing.T) {
+ // Simulates a crash between JSONL append and meta update in addMsg:
+ // file has N+1 lines but meta.Count is still N. TruncateHistory must
+ // reconcile with the real line count so that keepLast is accurate.
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // Write 10 messages normally (meta.Count = 10).
+ for i := 0; i < 10; i++ {
+ err := store.AddMessage(ctx, "stale", "user", string(rune('a'+i)))
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+
+ // Simulate crash: append a line to JSONL but do NOT update meta.
+ // This leaves meta.Count = 10 while the file has 11 lines.
+ jsonlPath := store.jsonlPath("stale")
+ f, err := os.OpenFile(jsonlPath, os.O_WRONLY|os.O_APPEND, 0o644)
+ if err != nil {
+ t.Fatalf("open for append: %v", err)
+ }
+ _, err = f.WriteString(`{"role":"user","content":"orphan"}` + "\n")
+ if err != nil {
+ t.Fatalf("write orphan: %v", err)
+ }
+ f.Close()
+
+ // TruncateHistory(keepLast=4) should keep the last 4 of 11 lines,
+ // not the last 4 of 10.
+ err = store.TruncateHistory(ctx, "stale", 4)
+ if err != nil {
+ t.Fatalf("TruncateHistory: %v", err)
+ }
+
+ history, err := store.GetHistory(ctx, "stale")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 4 {
+ t.Fatalf("expected 4, got %d", len(history))
+ }
+ // Last 4 of [a,b,c,d,e,f,g,h,i,j,orphan] = [h,i,j,orphan]
+ if history[0].Content != "h" {
+ t.Errorf("first kept = %q, want 'h'", history[0].Content)
+ }
+ if history[3].Content != "orphan" {
+ t.Errorf("last kept = %q, want 'orphan'", history[3].Content)
+ }
+}
+
+func TestCrashRecovery_PartialLine(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // Write a valid message first.
+ err := store.AddMessage(ctx, "crash", "user", "valid")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+
+ // Simulate a crash by appending a partial JSON line directly.
+ jsonlPath := store.jsonlPath("crash")
+ f, err := os.OpenFile(jsonlPath, os.O_WRONLY|os.O_APPEND, 0o644)
+ if err != nil {
+ t.Fatalf("open for append: %v", err)
+ }
+ _, err = f.WriteString(`{"role":"user","content":"incomple`)
+ if err != nil {
+ t.Fatalf("write partial: %v", err)
+ }
+ f.Close()
+
+ // GetHistory should return only the valid message.
+ history, err := store.GetHistory(ctx, "crash")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Fatalf("expected 1 valid message, got %d", len(history))
+ }
+ if history[0].Content != "valid" {
+ t.Errorf("content = %q", history[0].Content)
+ }
+}
+
+func TestPersistence_AcrossInstances(t *testing.T) {
+ dir := t.TempDir()
+ ctx := context.Background()
+
+ // Write with first instance.
+ store1, err := NewJSONLStore(dir)
+ if err != nil {
+ t.Fatalf("NewJSONLStore: %v", err)
+ }
+ err = store1.AddMessage(ctx, "persist", "user", "remember me")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ err = store1.SetSummary(ctx, "persist", "a test session")
+ if err != nil {
+ t.Fatalf("SetSummary: %v", err)
+ }
+ store1.Close()
+
+ // Read with second instance.
+ store2, err := NewJSONLStore(dir)
+ if err != nil {
+ t.Fatalf("NewJSONLStore: %v", err)
+ }
+ defer store2.Close()
+
+ history, err := store2.GetHistory(ctx, "persist")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 || history[0].Content != "remember me" {
+ t.Errorf("history = %+v", history)
+ }
+
+ summary, err := store2.GetSummary(ctx, "persist")
+ if err != nil {
+ t.Fatalf("GetSummary: %v", err)
+ }
+ if summary != "a test session" {
+ t.Errorf("summary = %q", summary)
+ }
+}
+
+func TestConcurrent_AddAndRead(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ var wg sync.WaitGroup
+ const goroutines = 10
+ const msgsPerGoroutine = 20
+
+ // Concurrent writes.
+ for g := 0; g < goroutines; g++ {
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ for i := 0; i < msgsPerGoroutine; i++ {
+ _ = store.AddMessage(ctx, "concurrent", "user", "msg")
+ }
+ }()
+ }
+ wg.Wait()
+
+ history, err := store.GetHistory(ctx, "concurrent")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ expected := goroutines * msgsPerGoroutine
+ if len(history) != expected {
+ t.Errorf("expected %d messages, got %d", expected, len(history))
+ }
+}
+
+func TestConcurrent_SummarizeRace(t *testing.T) {
+ // Simulates the #704 race: one goroutine adds messages while
+ // another truncates + sets summary — like summarizeSession().
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // Seed with some messages.
+ for i := 0; i < 20; i++ {
+ err := store.AddMessage(ctx, "race", "user", "seed")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ }
+
+ var wg sync.WaitGroup
+
+ // Writer goroutine (main agent loop).
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ for i := 0; i < 50; i++ {
+ _ = store.AddMessage(ctx, "race", "user", "new")
+ }
+ }()
+
+ // Summarizer goroutine (background task).
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ for i := 0; i < 10; i++ {
+ _ = store.SetSummary(ctx, "race", "summary")
+ _ = store.TruncateHistory(ctx, "race", 5)
+ }
+ }()
+
+ wg.Wait()
+
+ // Verify the store is still in a consistent state.
+ _, err := store.GetHistory(ctx, "race")
+ if err != nil {
+ t.Fatalf("GetHistory after race: %v", err)
+ }
+ _, err = store.GetSummary(ctx, "race")
+ if err != nil {
+ t.Fatalf("GetSummary after race: %v", err)
+ }
+}
+
+func TestMultipleSessions_Isolation(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ err := store.AddMessage(ctx, "s1", "user", "msg for s1")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+ err = store.AddMessage(ctx, "s2", "user", "msg for s2")
+ if err != nil {
+ t.Fatalf("AddMessage: %v", err)
+ }
+
+ h1, err := store.GetHistory(ctx, "s1")
+ if err != nil {
+ t.Fatalf("GetHistory s1: %v", err)
+ }
+ h2, err := store.GetHistory(ctx, "s2")
+ if err != nil {
+ t.Fatalf("GetHistory s2: %v", err)
+ }
+
+ if len(h1) != 1 || h1[0].Content != "msg for s1" {
+ t.Errorf("s1 history = %+v", h1)
+ }
+ if len(h2) != 1 || h2[0].Content != "msg for s2" {
+ t.Errorf("s2 history = %+v", h2)
+ }
+}
+
+func BenchmarkAddMessage(b *testing.B) {
+ dir := b.TempDir()
+ store, err := NewJSONLStore(dir)
+ if err != nil {
+ b.Fatalf("NewJSONLStore: %v", err)
+ }
+ defer store.Close()
+ ctx := context.Background()
+
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ _ = store.AddMessage(ctx, "bench", "user", "benchmark message content")
+ }
+}
+
+func BenchmarkGetHistory_100(b *testing.B) {
+ dir := b.TempDir()
+ store, err := NewJSONLStore(dir)
+ if err != nil {
+ b.Fatalf("NewJSONLStore: %v", err)
+ }
+ defer store.Close()
+ ctx := context.Background()
+
+ for i := 0; i < 100; i++ {
+ _ = store.AddMessage(ctx, "bench", "user", "message content")
+ }
+
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ _, _ = store.GetHistory(ctx, "bench")
+ }
+}
+
+func BenchmarkGetHistory_1000(b *testing.B) {
+ dir := b.TempDir()
+ store, err := NewJSONLStore(dir)
+ if err != nil {
+ b.Fatalf("NewJSONLStore: %v", err)
+ }
+ defer store.Close()
+ ctx := context.Background()
+
+ for i := 0; i < 1000; i++ {
+ _ = store.AddMessage(ctx, "bench", "user", "message content")
+ }
+
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ _, _ = store.GetHistory(ctx, "bench")
+ }
+}
diff --git a/pkg/memory/migration.go b/pkg/memory/migration.go
new file mode 100644
index 000000000..c9d5176ab
--- /dev/null
+++ b/pkg/memory/migration.go
@@ -0,0 +1,108 @@
+package memory
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "log"
+ "os"
+ "path/filepath"
+ "strings"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// jsonSession mirrors pkg/session.Session for migration purposes.
+type jsonSession struct {
+ Key string `json:"key"`
+ Messages []providers.Message `json:"messages"`
+ Summary string `json:"summary,omitempty"`
+ Created time.Time `json:"created"`
+ Updated time.Time `json:"updated"`
+}
+
+// MigrateFromJSON reads legacy sessions/*.json files from sessionsDir,
+// writes them into the Store, and renames each migrated file to
+// .json.migrated as a backup. Returns the number of sessions migrated.
+//
+// Files that fail to parse are logged and skipped. Already-migrated
+// files (.json.migrated) are ignored, making the function idempotent.
+func MigrateFromJSON(
+ ctx context.Context, sessionsDir string, store Store,
+) (int, error) {
+ entries, err := os.ReadDir(sessionsDir)
+ if os.IsNotExist(err) {
+ return 0, nil
+ }
+ if err != nil {
+ return 0, fmt.Errorf("memory: read sessions dir: %w", err)
+ }
+
+ migrated := 0
+ for _, entry := range entries {
+ if entry.IsDir() {
+ continue
+ }
+ name := entry.Name()
+ if !strings.HasSuffix(name, ".json") {
+ continue
+ }
+ // Skip already-migrated files.
+ if strings.HasSuffix(name, ".migrated") {
+ continue
+ }
+
+ srcPath := filepath.Join(sessionsDir, name)
+
+ data, readErr := os.ReadFile(srcPath)
+ if readErr != nil {
+ log.Printf("memory: migrate: skip %s: %v", name, readErr)
+ continue
+ }
+
+ var sess jsonSession
+ if parseErr := json.Unmarshal(data, &sess); parseErr != nil {
+ log.Printf("memory: migrate: skip %s: %v", name, parseErr)
+ continue
+ }
+
+ // Use the key from the JSON content, not the filename.
+ // Filenames are sanitized (":" → "_") but keys are not.
+ key := sess.Key
+ if key == "" {
+ key = strings.TrimSuffix(name, ".json")
+ }
+
+ // Use SetHistory (atomic replace) instead of per-message
+ // AddFullMessage. This makes migration idempotent: if the
+ // process crashes after writing messages but before the
+ // rename below, a retry replaces the partial data cleanly
+ // instead of duplicating messages.
+ if setErr := store.SetHistory(ctx, key, sess.Messages); setErr != nil {
+ return migrated, fmt.Errorf(
+ "memory: migrate %s: set history: %w",
+ name, setErr,
+ )
+ }
+
+ if sess.Summary != "" {
+ if sumErr := store.SetSummary(ctx, key, sess.Summary); sumErr != nil {
+ return migrated, fmt.Errorf(
+ "memory: migrate %s: set summary: %w",
+ name, sumErr,
+ )
+ }
+ }
+
+ // Rename to .migrated as backup (not delete).
+ renameErr := os.Rename(srcPath, srcPath+".migrated")
+ if renameErr != nil {
+ log.Printf("memory: migrate: rename %s: %v", name, renameErr)
+ }
+
+ migrated++
+ }
+
+ return migrated, nil
+}
diff --git a/pkg/memory/migration_test.go b/pkg/memory/migration_test.go
new file mode 100644
index 000000000..3170758b7
--- /dev/null
+++ b/pkg/memory/migration_test.go
@@ -0,0 +1,384 @@
+package memory
+
+import (
+ "context"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "testing"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func writeJSONSession(
+ t *testing.T, dir string, filename string, sess jsonSession,
+) {
+ t.Helper()
+ data, err := json.MarshalIndent(sess, "", " ")
+ if err != nil {
+ t.Fatalf("marshal session: %v", err)
+ }
+ err = os.WriteFile(filepath.Join(dir, filename), data, 0o644)
+ if err != nil {
+ t.Fatalf("write session file: %v", err)
+ }
+}
+
+func TestMigrateFromJSON_Basic(t *testing.T) {
+ sessionsDir := t.TempDir()
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ writeJSONSession(t, sessionsDir, "test.json", jsonSession{
+ Key: "test",
+ Messages: []providers.Message{
+ {Role: "user", Content: "hello"},
+ {Role: "assistant", Content: "hi"},
+ },
+ Summary: "A greeting.",
+ Created: time.Now(),
+ Updated: time.Now(),
+ })
+
+ count, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("MigrateFromJSON: %v", err)
+ }
+ if count != 1 {
+ t.Errorf("expected 1 migrated, got %d", count)
+ }
+
+ history, err := store.GetHistory(ctx, "test")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 2 {
+ t.Fatalf("expected 2 messages, got %d", len(history))
+ }
+ if history[0].Content != "hello" || history[1].Content != "hi" {
+ t.Errorf("unexpected messages: %+v", history)
+ }
+
+ summary, err := store.GetSummary(ctx, "test")
+ if err != nil {
+ t.Fatalf("GetSummary: %v", err)
+ }
+ if summary != "A greeting." {
+ t.Errorf("summary = %q", summary)
+ }
+}
+
+func TestMigrateFromJSON_WithToolCalls(t *testing.T) {
+ sessionsDir := t.TempDir()
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ writeJSONSession(t, sessionsDir, "tools.json", jsonSession{
+ Key: "tools",
+ Messages: []providers.Message{
+ {
+ Role: "assistant",
+ Content: "Searching...",
+ ToolCalls: []providers.ToolCall{
+ {
+ ID: "call_1",
+ Type: "function",
+ Function: &providers.FunctionCall{
+ Name: "web_search",
+ Arguments: `{"q":"test"}`,
+ },
+ },
+ },
+ },
+ {
+ Role: "tool",
+ Content: "result",
+ ToolCallID: "call_1",
+ },
+ },
+ Created: time.Now(),
+ Updated: time.Now(),
+ })
+
+ count, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("MigrateFromJSON: %v", err)
+ }
+ if count != 1 {
+ t.Errorf("expected 1, got %d", count)
+ }
+
+ history, err := store.GetHistory(ctx, "tools")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 2 {
+ t.Fatalf("expected 2 messages, got %d", len(history))
+ }
+ if len(history[0].ToolCalls) != 1 {
+ t.Fatalf("expected 1 tool call, got %d", len(history[0].ToolCalls))
+ }
+ if history[0].ToolCalls[0].Function.Name != "web_search" {
+ t.Errorf("function = %q", history[0].ToolCalls[0].Function.Name)
+ }
+ if history[1].ToolCallID != "call_1" {
+ t.Errorf("ToolCallID = %q", history[1].ToolCallID)
+ }
+}
+
+func TestMigrateFromJSON_MultipleFiles(t *testing.T) {
+ sessionsDir := t.TempDir()
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ for i := 0; i < 3; i++ {
+ key := string(rune('a' + i))
+ writeJSONSession(t, sessionsDir, key+".json", jsonSession{
+ Key: key,
+ Messages: []providers.Message{{Role: "user", Content: "msg " + key}},
+ Created: time.Now(),
+ Updated: time.Now(),
+ })
+ }
+
+ count, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("MigrateFromJSON: %v", err)
+ }
+ if count != 3 {
+ t.Errorf("expected 3, got %d", count)
+ }
+
+ for i := 0; i < 3; i++ {
+ key := string(rune('a' + i))
+ history, histErr := store.GetHistory(ctx, key)
+ if histErr != nil {
+ t.Fatalf("GetHistory(%q): %v", key, histErr)
+ }
+ if len(history) != 1 {
+ t.Errorf("session %q: expected 1 msg, got %d", key, len(history))
+ }
+ }
+}
+
+func TestMigrateFromJSON_InvalidJSON(t *testing.T) {
+ sessionsDir := t.TempDir()
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // One valid, one invalid.
+ writeJSONSession(t, sessionsDir, "good.json", jsonSession{
+ Key: "good",
+ Messages: []providers.Message{{Role: "user", Content: "ok"}},
+ Created: time.Now(),
+ Updated: time.Now(),
+ })
+ err := os.WriteFile(
+ filepath.Join(sessionsDir, "bad.json"),
+ []byte("{invalid json"),
+ 0o644,
+ )
+ if err != nil {
+ t.Fatalf("write bad file: %v", err)
+ }
+
+ count, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("MigrateFromJSON: %v", err)
+ }
+ if count != 1 {
+ t.Errorf("expected 1 (bad file skipped), got %d", count)
+ }
+
+ history, err := store.GetHistory(ctx, "good")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Errorf("expected 1 message, got %d", len(history))
+ }
+}
+
+func TestMigrateFromJSON_RenamesFiles(t *testing.T) {
+ sessionsDir := t.TempDir()
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ writeJSONSession(t, sessionsDir, "rename.json", jsonSession{
+ Key: "rename",
+ Messages: []providers.Message{{Role: "user", Content: "hi"}},
+ Created: time.Now(),
+ Updated: time.Now(),
+ })
+
+ _, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("MigrateFromJSON: %v", err)
+ }
+
+ // Original .json should not exist.
+ _, statErr := os.Stat(filepath.Join(sessionsDir, "rename.json"))
+ if !os.IsNotExist(statErr) {
+ t.Error("rename.json should have been renamed")
+ }
+ // .json.migrated should exist.
+ _, statErr = os.Stat(
+ filepath.Join(sessionsDir, "rename.json.migrated"),
+ )
+ if statErr != nil {
+ t.Errorf("rename.json.migrated should exist: %v", statErr)
+ }
+}
+
+func TestMigrateFromJSON_Idempotent(t *testing.T) {
+ sessionsDir := t.TempDir()
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ writeJSONSession(t, sessionsDir, "idem.json", jsonSession{
+ Key: "idem",
+ Messages: []providers.Message{{Role: "user", Content: "once"}},
+ Created: time.Now(),
+ Updated: time.Now(),
+ })
+
+ count1, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("first migration: %v", err)
+ }
+ if count1 != 1 {
+ t.Errorf("first run: expected 1, got %d", count1)
+ }
+
+ // Second run should find only .migrated files, skip them.
+ count2, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("second migration: %v", err)
+ }
+ if count2 != 0 {
+ t.Errorf("second run: expected 0, got %d", count2)
+ }
+
+ history, err := store.GetHistory(ctx, "idem")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Errorf("expected 1 message, got %d", len(history))
+ }
+}
+
+func TestMigrateFromJSON_ColonInKey(t *testing.T) {
+ sessionsDir := t.TempDir()
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ // File is named telegram_123 (sanitized), but the key inside is telegram:123.
+ writeJSONSession(t, sessionsDir, "telegram_123.json", jsonSession{
+ Key: "telegram:123",
+ Messages: []providers.Message{{Role: "user", Content: "from telegram"}},
+ Created: time.Now(),
+ Updated: time.Now(),
+ })
+
+ count, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("MigrateFromJSON: %v", err)
+ }
+ if count != 1 {
+ t.Errorf("expected 1, got %d", count)
+ }
+
+ // Accessible via the original key "telegram:123".
+ history, err := store.GetHistory(ctx, "telegram:123")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history) != 1 {
+ t.Fatalf("expected 1 message, got %d", len(history))
+ }
+ if history[0].Content != "from telegram" {
+ t.Errorf("content = %q", history[0].Content)
+ }
+
+ // In the file-based store, "telegram:123" and "telegram_123" both
+ // sanitize to the same filename, so they share storage. This is
+ // expected — the colon-to-underscore mapping is a one-way function.
+ history2, err := store.GetHistory(ctx, "telegram_123")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ if len(history2) != 1 {
+ t.Errorf("expected 1 (same file), got %d", len(history2))
+ }
+}
+
+func TestMigrateFromJSON_RetryAfterCrash(t *testing.T) {
+ // Simulates a crash during migration: first run writes messages
+ // but doesn't rename the .json file. Second run must replace
+ // (not duplicate) the messages thanks to SetHistory semantics.
+ sessionsDir := t.TempDir()
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ writeJSONSession(t, sessionsDir, "retry.json", jsonSession{
+ Key: "retry",
+ Messages: []providers.Message{
+ {Role: "user", Content: "one"},
+ {Role: "assistant", Content: "two"},
+ },
+ Created: time.Now(),
+ Updated: time.Now(),
+ })
+
+ // First migration succeeds — writes messages and renames file.
+ count, err := MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("first migration: %v", err)
+ }
+ if count != 1 {
+ t.Fatalf("expected 1, got %d", count)
+ }
+
+ // Simulate "crash before rename": restore the .json file.
+ src := filepath.Join(sessionsDir, "retry.json.migrated")
+ dst := filepath.Join(sessionsDir, "retry.json")
+ if renameErr := os.Rename(src, dst); renameErr != nil {
+ t.Fatalf("restore .json: %v", renameErr)
+ }
+
+ // Second migration should re-import without duplicating messages.
+ count, err = MigrateFromJSON(ctx, sessionsDir, store)
+ if err != nil {
+ t.Fatalf("second migration: %v", err)
+ }
+ if count != 1 {
+ t.Fatalf("expected 1, got %d", count)
+ }
+
+ history, err := store.GetHistory(ctx, "retry")
+ if err != nil {
+ t.Fatalf("GetHistory: %v", err)
+ }
+ // Must be exactly 2 messages (not 4 from duplication).
+ if len(history) != 2 {
+ t.Fatalf("expected 2 messages (no duplicates), got %d", len(history))
+ }
+ if history[0].Content != "one" || history[1].Content != "two" {
+ t.Errorf("unexpected messages: %+v", history)
+ }
+}
+
+func TestMigrateFromJSON_NonexistentDir(t *testing.T) {
+ store := newTestStore(t)
+ ctx := context.Background()
+
+ count, err := MigrateFromJSON(ctx, "/nonexistent/path", store)
+ if err != nil {
+ t.Fatalf("MigrateFromJSON: %v", err)
+ }
+ if count != 0 {
+ t.Errorf("expected 0, got %d", count)
+ }
+}
diff --git a/pkg/memory/store.go b/pkg/memory/store.go
new file mode 100644
index 000000000..b6e11707d
--- /dev/null
+++ b/pkg/memory/store.go
@@ -0,0 +1,42 @@
+package memory
+
+import (
+ "context"
+
+ "github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// Store defines an interface for persistent session storage.
+// Each method is an atomic operation — there is no separate Save() call.
+type Store interface {
+ // AddMessage appends a simple text message to a session.
+ AddMessage(ctx context.Context, sessionKey, role, content string) error
+
+ // AddFullMessage appends a complete message (with tool calls, etc.) to a session.
+ AddFullMessage(ctx context.Context, sessionKey string, msg providers.Message) error
+
+ // GetHistory returns all messages for a session in insertion order.
+ // Returns an empty slice (not nil) if the session does not exist.
+ GetHistory(ctx context.Context, sessionKey string) ([]providers.Message, error)
+
+ // GetSummary returns the conversation summary for a session.
+ // Returns an empty string if no summary exists.
+ GetSummary(ctx context.Context, sessionKey string) (string, error)
+
+ // SetSummary updates the conversation summary for a session.
+ SetSummary(ctx context.Context, sessionKey, summary string) error
+
+ // TruncateHistory removes all but the last keepLast messages from a session.
+ // If keepLast <= 0, all messages are removed.
+ TruncateHistory(ctx context.Context, sessionKey string, keepLast int) error
+
+ // SetHistory replaces all messages in a session with the provided history.
+ SetHistory(ctx context.Context, sessionKey string, history []providers.Message) error
+
+ // Compact reclaims storage by physically removing logically truncated
+ // data. Backends that do not accumulate dead data may return nil.
+ Compact(ctx context.Context, sessionKey string) error
+
+ // Close releases any resources held by the store.
+ Close() error
+}
diff --git a/pkg/migrate/config.go b/pkg/migrate/config.go
deleted file mode 100644
index 869b39827..000000000
--- a/pkg/migrate/config.go
+++ /dev/null
@@ -1,408 +0,0 @@
-package migrate
-
-import (
- "encoding/json"
- "fmt"
- "os"
- "path/filepath"
- "strings"
- "unicode"
-
- "github.com/sipeed/picoclaw/pkg/config"
-)
-
-var supportedProviders = map[string]bool{
- "anthropic": true,
- "openai": true,
- "openrouter": true,
- "groq": true,
- "zhipu": true,
- "vllm": true,
- "gemini": true,
- "qwen": true,
- "deepseek": true,
- "github_copilot": true,
- "mistral": true,
-}
-
-var supportedChannels = map[string]bool{
- "telegram": true,
- "discord": true,
- "whatsapp": true,
- "feishu": true,
- "qq": true,
- "dingtalk": true,
- "maixcam": true,
-}
-
-func findOpenClawConfig(openclawHome string) (string, error) {
- candidates := []string{
- filepath.Join(openclawHome, "openclaw.json"),
- filepath.Join(openclawHome, "config.json"),
- }
- for _, p := range candidates {
- if _, err := os.Stat(p); err == nil {
- return p, nil
- }
- }
- return "", fmt.Errorf("no config file found in %s (tried openclaw.json, config.json)", openclawHome)
-}
-
-func LoadOpenClawConfig(configPath string) (map[string]any, error) {
- data, err := os.ReadFile(configPath)
- if err != nil {
- return nil, fmt.Errorf("reading OpenClaw config: %w", err)
- }
-
- var raw map[string]any
- if err := json.Unmarshal(data, &raw); err != nil {
- return nil, fmt.Errorf("parsing OpenClaw config: %w", err)
- }
-
- converted := convertKeysToSnake(raw)
- result, ok := converted.(map[string]any)
- if !ok {
- return nil, fmt.Errorf("unexpected config format")
- }
- return result, nil
-}
-
-func ConvertConfig(data map[string]any) (*config.Config, []string, error) {
- cfg := config.DefaultConfig()
- var warnings []string
-
- if agents, ok := getMap(data, "agents"); ok {
- if defaults, ok := getMap(agents, "defaults"); ok {
- // Prefer model_name, fallback to model for backward compatibility
- if v, ok := getString(defaults, "model_name"); ok {
- cfg.Agents.Defaults.ModelName = v
- } else if v, ok := getString(defaults, "model"); ok {
- cfg.Agents.Defaults.Model = v
- }
- if v, ok := getFloat(defaults, "max_tokens"); ok {
- cfg.Agents.Defaults.MaxTokens = int(v)
- }
- if v, ok := getFloat(defaults, "temperature"); ok {
- cfg.Agents.Defaults.Temperature = &v
- }
- if v, ok := getFloat(defaults, "max_tool_iterations"); ok {
- cfg.Agents.Defaults.MaxToolIterations = int(v)
- }
- if v, ok := getString(defaults, "workspace"); ok {
- cfg.Agents.Defaults.Workspace = rewriteWorkspacePath(v)
- }
- }
- }
-
- if providers, ok := getMap(data, "providers"); ok {
- for name, val := range providers {
- pMap, ok := val.(map[string]any)
- if !ok {
- continue
- }
- apiKey, _ := getString(pMap, "api_key")
- apiBase, _ := getString(pMap, "api_base")
-
- if !supportedProviders[name] {
- if apiKey != "" || apiBase != "" {
- warnings = append(warnings, fmt.Sprintf("Provider '%s' not supported in PicoClaw, skipping", name))
- }
- continue
- }
-
- pc := config.ProviderConfig{APIKey: apiKey, APIBase: apiBase}
- switch name {
- case "anthropic":
- cfg.Providers.Anthropic = pc
- case "openai":
- cfg.Providers.OpenAI = config.OpenAIProviderConfig{
- ProviderConfig: pc,
- WebSearch: getBoolOrDefault(pMap, "web_search", true),
- }
- case "openrouter":
- cfg.Providers.OpenRouter = pc
- case "groq":
- cfg.Providers.Groq = pc
- case "zhipu":
- cfg.Providers.Zhipu = pc
- case "vllm":
- cfg.Providers.VLLM = pc
- case "gemini":
- cfg.Providers.Gemini = pc
- }
- }
- }
-
- if channels, ok := getMap(data, "channels"); ok {
- for name, val := range channels {
- cMap, ok := val.(map[string]any)
- if !ok {
- continue
- }
- if !supportedChannels[name] {
- warnings = append(warnings, fmt.Sprintf("Channel '%s' not supported in PicoClaw, skipping", name))
- continue
- }
- enabled, _ := getBool(cMap, "enabled")
- allowFrom := getStringSlice(cMap, "allow_from")
-
- switch name {
- case "telegram":
- cfg.Channels.Telegram.Enabled = enabled
- cfg.Channels.Telegram.AllowFrom = allowFrom
- if v, ok := getString(cMap, "token"); ok {
- cfg.Channels.Telegram.Token = v
- }
- case "discord":
- cfg.Channels.Discord.Enabled = enabled
- cfg.Channels.Discord.AllowFrom = allowFrom
- if v, ok := getString(cMap, "token"); ok {
- cfg.Channels.Discord.Token = v
- }
- case "whatsapp":
- cfg.Channels.WhatsApp.Enabled = enabled
- cfg.Channels.WhatsApp.AllowFrom = allowFrom
- if v, ok := getString(cMap, "bridge_url"); ok {
- cfg.Channels.WhatsApp.BridgeURL = v
- }
- case "feishu":
- cfg.Channels.Feishu.Enabled = enabled
- cfg.Channels.Feishu.AllowFrom = allowFrom
- if v, ok := getString(cMap, "app_id"); ok {
- cfg.Channels.Feishu.AppID = v
- }
- if v, ok := getString(cMap, "app_secret"); ok {
- cfg.Channels.Feishu.AppSecret = v
- }
- if v, ok := getString(cMap, "encrypt_key"); ok {
- cfg.Channels.Feishu.EncryptKey = v
- }
- if v, ok := getString(cMap, "verification_token"); ok {
- cfg.Channels.Feishu.VerificationToken = v
- }
- case "qq":
- cfg.Channels.QQ.Enabled = enabled
- cfg.Channels.QQ.AllowFrom = allowFrom
- if v, ok := getString(cMap, "app_id"); ok {
- cfg.Channels.QQ.AppID = v
- }
- if v, ok := getString(cMap, "app_secret"); ok {
- cfg.Channels.QQ.AppSecret = v
- }
- case "dingtalk":
- cfg.Channels.DingTalk.Enabled = enabled
- cfg.Channels.DingTalk.AllowFrom = allowFrom
- if v, ok := getString(cMap, "client_id"); ok {
- cfg.Channels.DingTalk.ClientID = v
- }
- if v, ok := getString(cMap, "client_secret"); ok {
- cfg.Channels.DingTalk.ClientSecret = v
- }
- case "maixcam":
- cfg.Channels.MaixCam.Enabled = enabled
- cfg.Channels.MaixCam.AllowFrom = allowFrom
- if v, ok := getString(cMap, "host"); ok {
- cfg.Channels.MaixCam.Host = v
- }
- if v, ok := getFloat(cMap, "port"); ok {
- cfg.Channels.MaixCam.Port = int(v)
- }
- }
- }
- }
-
- if gateway, ok := getMap(data, "gateway"); ok {
- if v, ok := getString(gateway, "host"); ok {
- cfg.Gateway.Host = v
- }
- if v, ok := getFloat(gateway, "port"); ok {
- cfg.Gateway.Port = int(v)
- }
- }
-
- if tools, ok := getMap(data, "tools"); ok {
- if web, ok := getMap(tools, "web"); ok {
- // Migrate old "search" config to "brave" if api_key is present
- if search, ok := getMap(web, "search"); ok {
- if v, ok := getString(search, "api_key"); ok {
- cfg.Tools.Web.Brave.APIKey = v
- if v != "" {
- cfg.Tools.Web.Brave.Enabled = true
- }
- }
- if v, ok := getFloat(search, "max_results"); ok {
- cfg.Tools.Web.Brave.MaxResults = int(v)
- cfg.Tools.Web.DuckDuckGo.MaxResults = int(v)
- }
- }
- }
- }
-
- return cfg, warnings, nil
-}
-
-func MergeConfig(existing, incoming *config.Config) *config.Config {
- if existing.Providers.Anthropic.APIKey == "" {
- existing.Providers.Anthropic = incoming.Providers.Anthropic
- }
- if existing.Providers.OpenAI.APIKey == "" {
- existing.Providers.OpenAI = incoming.Providers.OpenAI
- }
- if existing.Providers.OpenRouter.APIKey == "" {
- existing.Providers.OpenRouter = incoming.Providers.OpenRouter
- }
- if existing.Providers.Groq.APIKey == "" {
- existing.Providers.Groq = incoming.Providers.Groq
- }
- if existing.Providers.Zhipu.APIKey == "" {
- existing.Providers.Zhipu = incoming.Providers.Zhipu
- }
- if existing.Providers.VLLM.APIKey == "" && existing.Providers.VLLM.APIBase == "" {
- existing.Providers.VLLM = incoming.Providers.VLLM
- }
- if existing.Providers.Gemini.APIKey == "" {
- existing.Providers.Gemini = incoming.Providers.Gemini
- }
- if existing.Providers.DeepSeek.APIKey == "" {
- existing.Providers.DeepSeek = incoming.Providers.DeepSeek
- }
- if existing.Providers.GitHubCopilot.APIBase == "" {
- existing.Providers.GitHubCopilot = incoming.Providers.GitHubCopilot
- }
- if existing.Providers.Qwen.APIKey == "" {
- existing.Providers.Qwen = incoming.Providers.Qwen
- }
-
- if !existing.Channels.Telegram.Enabled && incoming.Channels.Telegram.Enabled {
- existing.Channels.Telegram = incoming.Channels.Telegram
- }
- if !existing.Channels.Discord.Enabled && incoming.Channels.Discord.Enabled {
- existing.Channels.Discord = incoming.Channels.Discord
- }
- if !existing.Channels.WhatsApp.Enabled && incoming.Channels.WhatsApp.Enabled {
- existing.Channels.WhatsApp = incoming.Channels.WhatsApp
- }
- if !existing.Channels.Feishu.Enabled && incoming.Channels.Feishu.Enabled {
- existing.Channels.Feishu = incoming.Channels.Feishu
- }
- if !existing.Channels.QQ.Enabled && incoming.Channels.QQ.Enabled {
- existing.Channels.QQ = incoming.Channels.QQ
- }
- if !existing.Channels.DingTalk.Enabled && incoming.Channels.DingTalk.Enabled {
- existing.Channels.DingTalk = incoming.Channels.DingTalk
- }
- if !existing.Channels.MaixCam.Enabled && incoming.Channels.MaixCam.Enabled {
- existing.Channels.MaixCam = incoming.Channels.MaixCam
- }
-
- if existing.Tools.Web.Brave.APIKey == "" {
- existing.Tools.Web.Brave = incoming.Tools.Web.Brave
- }
-
- return existing
-}
-
-func camelToSnake(s string) string {
- var result strings.Builder
- for i, r := range s {
- if unicode.IsUpper(r) {
- if i > 0 {
- prev := rune(s[i-1])
- if unicode.IsLower(prev) || unicode.IsDigit(prev) {
- result.WriteRune('_')
- } else if unicode.IsUpper(prev) && i+1 < len(s) && unicode.IsLower(rune(s[i+1])) {
- result.WriteRune('_')
- }
- }
- result.WriteRune(unicode.ToLower(r))
- } else {
- result.WriteRune(r)
- }
- }
- return result.String()
-}
-
-func convertKeysToSnake(data any) any {
- switch v := data.(type) {
- case map[string]any:
- result := make(map[string]any, len(v))
- for key, val := range v {
- result[camelToSnake(key)] = convertKeysToSnake(val)
- }
- return result
- case []any:
- result := make([]any, len(v))
- for i, val := range v {
- result[i] = convertKeysToSnake(val)
- }
- return result
- default:
- return data
- }
-}
-
-func rewriteWorkspacePath(path string) string {
- path = strings.Replace(path, ".openclaw", ".picoclaw", 1)
- return path
-}
-
-func getMap(data map[string]any, key string) (map[string]any, bool) {
- v, ok := data[key]
- if !ok {
- return nil, false
- }
- m, ok := v.(map[string]any)
- return m, ok
-}
-
-func getString(data map[string]any, key string) (string, bool) {
- v, ok := data[key]
- if !ok {
- return "", false
- }
- s, ok := v.(string)
- return s, ok
-}
-
-func getFloat(data map[string]any, key string) (float64, bool) {
- v, ok := data[key]
- if !ok {
- return 0, false
- }
- f, ok := v.(float64)
- return f, ok
-}
-
-func getBool(data map[string]any, key string) (bool, bool) {
- v, ok := data[key]
- if !ok {
- return false, false
- }
- b, ok := v.(bool)
- return b, ok
-}
-
-func getBoolOrDefault(data map[string]any, key string, defaultVal bool) bool {
- if v, ok := getBool(data, key); ok {
- return v
- }
- return defaultVal
-}
-
-func getStringSlice(data map[string]any, key string) []string {
- v, ok := data[key]
- if !ok {
- return []string{}
- }
- arr, ok := v.([]any)
- if !ok {
- return []string{}
- }
- result := make([]string, 0, len(arr))
- for _, item := range arr {
- if s, ok := item.(string); ok {
- result = append(result, s)
- }
- }
- return result
-}
diff --git a/pkg/migrate/workspace.go b/pkg/migrate/internal/common.go
similarity index 55%
rename from pkg/migrate/workspace.go
rename to pkg/migrate/internal/common.go
index f45748fac..c77ab9f26 100644
--- a/pkg/migrate/workspace.go
+++ b/pkg/migrate/internal/common.go
@@ -1,24 +1,50 @@
-package migrate
+package internal
import (
+ "fmt"
+ "io"
"os"
"path/filepath"
)
-var migrateableFiles = []string{
- "AGENTS.md",
- "SOUL.md",
- "USER.md",
- "TOOLS.md",
- "HEARTBEAT.md",
+func ResolveTargetHome(override string) (string, error) {
+ if override != "" {
+ return ExpandHome(override), nil
+ }
+ if envHome := os.Getenv("PICOCLAW_HOME"); envHome != "" {
+ return ExpandHome(envHome), nil
+ }
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return "", fmt.Errorf("resolving home directory: %w", err)
+ }
+ return filepath.Join(home, ".picoclaw"), nil
}
-var migrateableDirs = []string{
- "memory",
- "skills",
+func ExpandHome(path string) string {
+ if path == "" {
+ return path
+ }
+ if path[0] == '~' {
+ home, _ := os.UserHomeDir()
+ if len(path) > 1 && path[1] == '/' {
+ return home + path[1:]
+ }
+ return home
+ }
+ return path
}
-func PlanWorkspaceMigration(srcWorkspace, dstWorkspace string, force bool) ([]Action, error) {
+func ResolveWorkspace(homeDir string) string {
+ return filepath.Join(homeDir, "workspace")
+}
+
+func PlanWorkspaceMigration(
+ srcWorkspace, dstWorkspace string,
+ migrateableFiles []string,
+ migrateableDirs []string,
+ force bool,
+) ([]Action, error) {
var actions []Action
for _, filename := range migrateableFiles {
@@ -50,7 +76,7 @@ func planFileCopy(src, dst string, force bool) Action {
return Action{
Type: ActionSkip,
Source: src,
- Destination: dst,
+ Target: dst,
Description: "source file not found",
}
}
@@ -60,7 +86,7 @@ func planFileCopy(src, dst string, force bool) Action {
return Action{
Type: ActionBackup,
Source: src,
- Destination: dst,
+ Target: dst,
Description: "destination exists, will backup and overwrite",
}
}
@@ -68,7 +94,7 @@ func planFileCopy(src, dst string, force bool) Action {
return Action{
Type: ActionCopy,
Source: src,
- Destination: dst,
+ Target: dst,
Description: "copy file",
}
}
@@ -91,7 +117,7 @@ func planDirCopy(srcDir, dstDir string, force bool) ([]Action, error) {
if info.IsDir() {
actions = append(actions, Action{
Type: ActionCreateDir,
- Destination: dst,
+ Target: dst,
Description: "create directory",
})
return nil
@@ -104,3 +130,33 @@ func planDirCopy(srcDir, dstDir string, force bool) ([]Action, error) {
return actions, err
}
+
+func RelPath(path, base string) string {
+ rel, err := filepath.Rel(base, path)
+ if err != nil {
+ return filepath.Base(path)
+ }
+ return rel
+}
+
+func CopyFile(src, dst string) error {
+ srcFile, err := os.Open(src)
+ if err != nil {
+ return err
+ }
+ defer srcFile.Close()
+
+ info, err := srcFile.Stat()
+ if err != nil {
+ return err
+ }
+
+ dstFile, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
+ if err != nil {
+ return err
+ }
+ defer dstFile.Close()
+
+ _, err = io.Copy(dstFile, srcFile)
+ return err
+}
diff --git a/pkg/migrate/internal/common_test.go b/pkg/migrate/internal/common_test.go
new file mode 100644
index 000000000..a67293c19
--- /dev/null
+++ b/pkg/migrate/internal/common_test.go
@@ -0,0 +1,186 @@
+package internal
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestExpandHome(t *testing.T) {
+ tests := []struct {
+ input string
+ expected string
+ }{
+ {"", ""},
+ {"/absolute/path", "/absolute/path"},
+ {"relative/path", "relative/path"},
+ }
+
+ for _, tt := range tests {
+ result := ExpandHome(tt.input)
+ assert.Equal(t, tt.expected, result)
+ }
+}
+
+func TestExpandHomeWithTilde(t *testing.T) {
+ home, err := os.UserHomeDir()
+ require.NoError(t, err)
+
+ result := ExpandHome("~/path")
+ assert.Equal(t, home+"/path", result)
+
+ result = ExpandHome("~")
+ assert.Equal(t, home, result)
+}
+
+func TestResolveWorkspace(t *testing.T) {
+ result := ResolveWorkspace("/home/user/.picoclaw")
+ assert.Equal(t, "/home/user/.picoclaw/workspace", result)
+}
+
+func TestRelPath(t *testing.T) {
+ result := RelPath("/home/user/.picoclaw/workspace/file.txt", "/home/user/.picoclaw")
+ assert.Equal(t, "workspace/file.txt", result)
+}
+
+func TestRelPathError(t *testing.T) {
+ result := RelPath("relative/path", "/different/base")
+ assert.Equal(t, "path", result)
+}
+
+func TestResolveTargetHome(t *testing.T) {
+ home, err := os.UserHomeDir()
+ require.NoError(t, err)
+
+ result, err := ResolveTargetHome("")
+ require.NoError(t, err)
+ assert.Equal(t, filepath.Join(home, ".picoclaw"), result)
+}
+
+func TestResolveTargetHomeWithOverride(t *testing.T) {
+ result, err := ResolveTargetHome("/custom/path")
+ require.NoError(t, err)
+ assert.Equal(t, "/custom/path", result)
+}
+
+func TestCopyFile(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ sourceFile := filepath.Join(tmpDir, "source.txt")
+ err := os.WriteFile(sourceFile, []byte("test content"), 0o644)
+ require.NoError(t, err)
+
+ dstFile := filepath.Join(tmpDir, "dest.txt")
+ err = CopyFile(sourceFile, dstFile)
+ require.NoError(t, err)
+
+ content, err := os.ReadFile(dstFile)
+ require.NoError(t, err)
+ assert.Equal(t, "test content", string(content))
+}
+
+func TestCopyFileSourceNotFound(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ err := CopyFile(filepath.Join(tmpDir, "nonexistent.txt"), filepath.Join(tmpDir, "dest.txt"))
+ require.Error(t, err)
+}
+
+func TestPlanWorkspaceMigration(t *testing.T) {
+ tmpDir := t.TempDir()
+ srcWorkspace := filepath.Join(tmpDir, "src", "workspace")
+ dstWorkspace := filepath.Join(tmpDir, "dst", "workspace")
+
+ err := os.MkdirAll(srcWorkspace, 0o755)
+ require.NoError(t, err)
+
+ err = os.WriteFile(filepath.Join(srcWorkspace, "file1.txt"), []byte("content"), 0o644)
+ require.NoError(t, err)
+
+ err = os.MkdirAll(filepath.Join(srcWorkspace, "subdir"), 0o755)
+ require.NoError(t, err)
+
+ err = os.WriteFile(filepath.Join(srcWorkspace, "subdir", "file2.txt"), []byte("content"), 0o644)
+ require.NoError(t, err)
+
+ actions, err := PlanWorkspaceMigration(
+ srcWorkspace,
+ dstWorkspace,
+ []string{"file1.txt"},
+ []string{"subdir"},
+ false,
+ )
+ require.NoError(t, err)
+
+ assert.GreaterOrEqual(t, len(actions), 1)
+}
+
+func TestPlanWorkspaceMigrationExistingFile(t *testing.T) {
+ tests := []struct {
+ name string
+ force bool
+ wantActionType ActionType
+ }{
+ {
+ name: "backup when not forced",
+ force: false,
+ wantActionType: ActionBackup,
+ },
+ {
+ name: "copy when forced",
+ force: true,
+ wantActionType: ActionCopy,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ tmpDir := t.TempDir()
+ srcWorkspace := filepath.Join(tmpDir, "src", "workspace")
+ dstWorkspace := filepath.Join(tmpDir, "dst", "workspace")
+
+ err := os.MkdirAll(srcWorkspace, 0o755)
+ require.NoError(t, err)
+
+ err = os.MkdirAll(dstWorkspace, 0o755)
+ require.NoError(t, err)
+
+ err = os.WriteFile(filepath.Join(srcWorkspace, "file1.txt"), []byte("source"), 0o644)
+ require.NoError(t, err)
+
+ err = os.WriteFile(filepath.Join(dstWorkspace, "file1.txt"), []byte("existing"), 0o644)
+ require.NoError(t, err)
+
+ actions, err := PlanWorkspaceMigration(
+ srcWorkspace,
+ dstWorkspace,
+ []string{"file1.txt"},
+ []string{},
+ tt.force,
+ )
+ require.NoError(t, err)
+
+ require.GreaterOrEqual(t, len(actions), 1)
+ assert.Equal(t, tt.wantActionType, actions[0].Type)
+ })
+ }
+}
+
+func TestPlanWorkspaceMigrationNonExistentSource(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ actions, err := PlanWorkspaceMigration(
+ filepath.Join(tmpDir, "nonexistent"),
+ filepath.Join(tmpDir, "dst", "workspace"),
+ []string{"file1.txt"},
+ []string{},
+ false,
+ )
+ require.NoError(t, err)
+ require.Len(t, actions, 1)
+ assert.Equal(t, ActionSkip, actions[0].Type)
+ assert.Contains(t, actions[0].Description, "source file not found")
+}
diff --git a/pkg/migrate/internal/types.go b/pkg/migrate/internal/types.go
new file mode 100644
index 000000000..e86a4dea1
--- /dev/null
+++ b/pkg/migrate/internal/types.go
@@ -0,0 +1,52 @@
+package internal
+
+type Options struct {
+ DryRun bool
+ ConfigOnly bool
+ WorkspaceOnly bool
+ Force bool
+ Refresh bool
+ Source string
+ SourceHome string
+ TargetHome string
+}
+
+type Operation interface {
+ GetSourceName() string
+ GetSourceHome() (string, error)
+ GetSourceWorkspace() (string, error)
+ GetSourceConfigFile() (string, error)
+ ExecuteConfigMigration(srcConfigPath, dstConfigPath string) error
+ GetMigrateableFiles() []string
+ GetMigrateableDirs() []string
+}
+
+type HandlerFactory func(opts Options) Operation
+
+type ActionType int
+
+const (
+ ActionCopy ActionType = iota
+ ActionSkip
+ ActionBackup
+ ActionConvertConfig
+ ActionCreateDir
+ ActionMergeConfig
+)
+
+type Action struct {
+ Type ActionType
+ Source string
+ Target string
+ Description string
+}
+
+type Result struct {
+ FilesCopied int
+ FilesSkipped int
+ BackupsCreated int
+ ConfigMigrated bool
+ DirsCreated int
+ Warnings []string
+ Errors []error
+}
diff --git a/pkg/migrate/migrate.go b/pkg/migrate/migrate.go
index cfa82b7d7..51fecf438 100644
--- a/pkg/migrate/migrate.go
+++ b/pkg/migrate/migrate.go
@@ -2,53 +2,73 @@ package migrate
import (
"fmt"
- "io"
"os"
"path/filepath"
"strings"
- "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/migrate/internal"
+ "github.com/sipeed/picoclaw/pkg/migrate/sources/openclaw"
)
-type ActionType int
+type (
+ Options = internal.Options
+ Operation = internal.Operation
+ ActionType = internal.ActionType
+ Action = internal.Action
+ Result = internal.Result
+ HandlerFactory = internal.HandlerFactory
+)
const (
- ActionCopy ActionType = iota
- ActionSkip
- ActionBackup
- ActionConvertConfig
- ActionCreateDir
- ActionMergeConfig
+ ActionCopy = internal.ActionCopy
+ ActionSkip = internal.ActionSkip
+ ActionBackup = internal.ActionBackup
+ ActionConvertConfig = internal.ActionConvertConfig
+ ActionCreateDir = internal.ActionCreateDir
+ ActionMergeConfig = internal.ActionMergeConfig
)
-type Options struct {
- DryRun bool
- ConfigOnly bool
- WorkspaceOnly bool
- Force bool
- Refresh bool
- OpenClawHome string
- PicoClawHome string
+type MigrateInstance struct {
+ options Options
+ handlers map[string]Operation
}
-type Action struct {
- Type ActionType
- Source string
- Destination string
- Description string
+func NewMigrateInstance(opts Options) *MigrateInstance {
+ instance := &MigrateInstance{
+ options: opts,
+ handlers: make(map[string]Operation),
+ }
+
+ openclaw_handler, err := openclaw.NewOpenclawHandler(opts)
+ if err == nil {
+ instance.Register(openclaw_handler.GetSourceName(), openclaw_handler)
+ }
+
+ return instance
}
-type Result struct {
- FilesCopied int
- FilesSkipped int
- BackupsCreated int
- ConfigMigrated bool
- DirsCreated int
- Warnings []string
- Errors []error
+func (m *MigrateInstance) Register(moduleName string, module Operation) {
+ m.handlers[moduleName] = module
}
-func Run(opts Options) (*Result, error) {
+func (m *MigrateInstance) getCurrentHandler() (Operation, error) {
+ source := m.options.Source
+ if source == "" {
+ source = "openclaw"
+ }
+ handler, ok := m.handlers[source]
+ if !ok {
+ return nil, fmt.Errorf("Source '%s' not found", source)
+ }
+ return handler, nil
+}
+
+func (m *MigrateInstance) Run(opts Options) (*Result, error) {
+ handler, err := m.getCurrentHandler()
+ if err != nil {
+ return nil, err
+ }
+
if opts.ConfigOnly && opts.WorkspaceOnly {
return nil, fmt.Errorf("--config-only and --workspace-only are mutually exclusive")
}
@@ -57,28 +77,28 @@ func Run(opts Options) (*Result, error) {
opts.WorkspaceOnly = true
}
- openclawHome, err := resolveOpenClawHome(opts.OpenClawHome)
+ sourceHome, err := handler.GetSourceHome()
if err != nil {
return nil, err
}
- picoClawHome, err := resolvePicoClawHome(opts.PicoClawHome)
+ targetHome, err := internal.ResolveTargetHome(opts.TargetHome)
if err != nil {
return nil, err
}
- if _, err = os.Stat(openclawHome); os.IsNotExist(err) {
- return nil, fmt.Errorf("OpenClaw installation not found at %s", openclawHome)
+ if _, err = os.Stat(sourceHome); os.IsNotExist(err) {
+ return nil, fmt.Errorf("Source installation not found at %s", sourceHome)
}
- actions, warnings, err := Plan(opts, openclawHome, picoClawHome)
+ actions, warnings, err := m.Plan(opts, sourceHome, targetHome)
if err != nil {
return nil, err
}
- fmt.Println("Migrating from OpenClaw to PicoClaw")
- fmt.Printf(" Source: %s\n", openclawHome)
- fmt.Printf(" Destination: %s\n", picoClawHome)
+ fmt.Println("Migrating from Source to PicoClaw")
+ fmt.Printf(" Source: %s\n", sourceHome)
+ fmt.Printf(" Target: %s\n", targetHome)
fmt.Println()
if opts.DryRun {
@@ -95,19 +115,23 @@ func Run(opts Options) (*Result, error) {
fmt.Println()
}
- result := Execute(actions, openclawHome, picoClawHome)
+ result := m.Execute(actions, sourceHome, targetHome)
result.Warnings = warnings
return result, nil
}
-func Plan(opts Options, openclawHome, picoClawHome string) ([]Action, []string, error) {
+func (m *MigrateInstance) Plan(opts Options, sourceHome, targetHome string) ([]Action, []string, error) {
var actions []Action
var warnings []string
+ handler, err := m.getCurrentHandler()
+ if err != nil {
+ return nil, nil, err
+ }
force := opts.Force || opts.Refresh
if !opts.WorkspaceOnly {
- configPath, err := findOpenClawConfig(openclawHome)
+ configPath, err := handler.GetSourceConfigFile()
if err != nil {
if opts.ConfigOnly {
return nil, nil, err
@@ -117,91 +141,95 @@ func Plan(opts Options, openclawHome, picoClawHome string) ([]Action, []string,
actions = append(actions, Action{
Type: ActionConvertConfig,
Source: configPath,
- Destination: filepath.Join(picoClawHome, "config.json"),
- Description: "convert OpenClaw config to PicoClaw format",
+ Target: filepath.Join(targetHome, "config.json"),
+ Description: "convert Source config to PicoClaw format",
})
-
- data, err := LoadOpenClawConfig(configPath)
- if err == nil {
- _, configWarnings, _ := ConvertConfig(data)
- warnings = append(warnings, configWarnings...)
- }
}
}
if !opts.ConfigOnly {
- srcWorkspace := resolveWorkspace(openclawHome)
- dstWorkspace := resolveWorkspace(picoClawHome)
+ srcWorkspace, err := handler.GetSourceWorkspace()
+ if err != nil {
+ return nil, nil, fmt.Errorf("getting source workspace: %w", err)
+ }
+ dstWorkspace := internal.ResolveWorkspace(targetHome)
if _, err := os.Stat(srcWorkspace); err == nil {
- wsActions, err := PlanWorkspaceMigration(srcWorkspace, dstWorkspace, force)
+ wsActions, err := internal.PlanWorkspaceMigration(srcWorkspace, dstWorkspace,
+ handler.GetMigrateableFiles(),
+ handler.GetMigrateableDirs(),
+ force)
if err != nil {
return nil, nil, fmt.Errorf("planning workspace migration: %w", err)
}
actions = append(actions, wsActions...)
} else {
- warnings = append(warnings, "OpenClaw workspace directory not found, skipping workspace migration")
+ warnings = append(warnings, "Source workspace directory not found, skipping workspace migration")
}
}
return actions, warnings, nil
}
-func Execute(actions []Action, openclawHome, picoClawHome string) *Result {
+func (m *MigrateInstance) Execute(actions []Action, sourceHome, targetHome string) *Result {
result := &Result{}
+ handler, err := m.getCurrentHandler()
+ if err != nil {
+ return result
+ }
for _, action := range actions {
switch action.Type {
case ActionConvertConfig:
- if err := executeConfigMigration(action.Source, action.Destination, picoClawHome); err != nil {
+ if err := handler.ExecuteConfigMigration(action.Source, action.Target); err != nil {
result.Errors = append(result.Errors, fmt.Errorf("config migration: %w", err))
fmt.Printf(" ✗ Config migration failed: %v\n", err)
} else {
result.ConfigMigrated = true
- fmt.Printf(" ✓ Converted config: %s\n", action.Destination)
+ fmt.Printf(" ✓ Converted config: %s\n", action.Target)
}
case ActionCreateDir:
- if err := os.MkdirAll(action.Destination, 0o755); err != nil {
+ if err := os.MkdirAll(action.Target, 0o755); err != nil {
result.Errors = append(result.Errors, err)
} else {
result.DirsCreated++
}
case ActionBackup:
- bakPath := action.Destination + ".bak"
- if err := copyFile(action.Destination, bakPath); err != nil {
- result.Errors = append(result.Errors, fmt.Errorf("backup %s: %w", action.Destination, err))
- fmt.Printf(" ✗ Backup failed: %s\n", action.Destination)
+ bakPath := action.Target + ".bak"
+ if err := internal.CopyFile(action.Target, bakPath); err != nil {
+ result.Errors = append(result.Errors, fmt.Errorf("backup %s: %w", action.Target, err))
+ fmt.Printf(" ✗ Backup failed: %s\n", action.Target)
continue
}
result.BackupsCreated++
fmt.Printf(
" ✓ Backed up %s -> %s.bak\n",
- filepath.Base(action.Destination),
- filepath.Base(action.Destination),
+ filepath.Base(action.Target),
+ filepath.Base(action.Target),
)
- if err := os.MkdirAll(filepath.Dir(action.Destination), 0o755); err != nil {
+ if err := os.MkdirAll(filepath.Dir(action.Target), 0o755); err != nil {
result.Errors = append(result.Errors, err)
continue
}
- if err := copyFile(action.Source, action.Destination); err != nil {
+ if err := internal.CopyFile(action.Source, action.Target); err != nil {
result.Errors = append(result.Errors, fmt.Errorf("copy %s: %w", action.Source, err))
fmt.Printf(" ✗ Copy failed: %s\n", action.Source)
} else {
result.FilesCopied++
- fmt.Printf(" ✓ Copied %s\n", relPath(action.Source, openclawHome))
+ fmt.Printf(" ✓ Copied %s\n", internal.RelPath(action.Source, sourceHome))
}
case ActionCopy:
- if err := os.MkdirAll(filepath.Dir(action.Destination), 0o755); err != nil {
+ if err := os.MkdirAll(filepath.Dir(action.Target), 0o755); err != nil {
result.Errors = append(result.Errors, err)
continue
}
- if err := copyFile(action.Source, action.Destination); err != nil {
+ if err := internal.CopyFile(action.Source, action.Target); err != nil {
result.Errors = append(result.Errors, fmt.Errorf("copy %s: %w", action.Source, err))
fmt.Printf(" ✗ Copy failed: %s\n", action.Source)
} else {
result.FilesCopied++
- fmt.Printf(" ✓ Copied %s\n", relPath(action.Source, openclawHome))
+ fmt.Printf(" ✓ Copied %s\n", internal.RelPath(action.Source, sourceHome))
}
case ActionSkip:
result.FilesSkipped++
@@ -211,31 +239,6 @@ func Execute(actions []Action, openclawHome, picoClawHome string) *Result {
return result
}
-func executeConfigMigration(srcConfigPath, dstConfigPath, picoClawHome string) error {
- data, err := LoadOpenClawConfig(srcConfigPath)
- if err != nil {
- return err
- }
-
- incoming, _, err := ConvertConfig(data)
- if err != nil {
- return err
- }
-
- if _, err := os.Stat(dstConfigPath); err == nil {
- existing, err := config.LoadConfig(dstConfigPath)
- if err != nil {
- return fmt.Errorf("loading existing PicoClaw config: %w", err)
- }
- incoming = MergeConfig(existing, incoming)
- }
-
- if err := os.MkdirAll(filepath.Dir(dstConfigPath), 0o755); err != nil {
- return err
- }
- return config.SaveConfig(dstConfigPath, incoming)
-}
-
func Confirm() bool {
fmt.Print("Proceed with migration? (y/n): ")
var response string
@@ -243,49 +246,7 @@ func Confirm() bool {
return strings.ToLower(strings.TrimSpace(response)) == "y"
}
-func PrintPlan(actions []Action, warnings []string) {
- fmt.Println("Planned actions:")
- copies := 0
- skips := 0
- backups := 0
- configCount := 0
-
- for _, action := range actions {
- switch action.Type {
- case ActionConvertConfig:
- fmt.Printf(" [config] %s -> %s\n", action.Source, action.Destination)
- configCount++
- case ActionCopy:
- fmt.Printf(" [copy] %s\n", filepath.Base(action.Source))
- copies++
- case ActionBackup:
- fmt.Printf(" [backup] %s (exists, will backup and overwrite)\n", filepath.Base(action.Destination))
- backups++
- copies++
- case ActionSkip:
- if action.Description != "" {
- fmt.Printf(" [skip] %s (%s)\n", filepath.Base(action.Source), action.Description)
- }
- skips++
- case ActionCreateDir:
- fmt.Printf(" [mkdir] %s\n", action.Destination)
- }
- }
-
- if len(warnings) > 0 {
- fmt.Println()
- fmt.Println("Warnings:")
- for _, w := range warnings {
- fmt.Printf(" - %s\n", w)
- }
- }
-
- fmt.Println()
- fmt.Printf("%d files to copy, %d configs to convert, %d backups needed, %d skipped\n",
- copies, configCount, backups, skips)
-}
-
-func PrintSummary(result *Result) {
+func (m *MigrateInstance) PrintSummary(result *Result) {
fmt.Println()
parts := []string{}
if result.FilesCopied > 0 {
@@ -316,83 +277,44 @@ func PrintSummary(result *Result) {
}
}
-func resolveOpenClawHome(override string) (string, error) {
- if override != "" {
- return expandHome(override), nil
- }
- if envHome := os.Getenv("OPENCLAW_HOME"); envHome != "" {
- return expandHome(envHome), nil
- }
- home, err := os.UserHomeDir()
- if err != nil {
- return "", fmt.Errorf("resolving home directory: %w", err)
- }
- return filepath.Join(home, ".openclaw"), nil
-}
+func PrintPlan(actions []Action, warnings []string) {
+ fmt.Println("Planned actions:")
+ copies := 0
+ skips := 0
+ backups := 0
+ configCount := 0
-func resolvePicoClawHome(override string) (string, error) {
- if override != "" {
- return expandHome(override), nil
- }
- if envHome := os.Getenv("PICOCLAW_HOME"); envHome != "" {
- return expandHome(envHome), nil
- }
- home, err := os.UserHomeDir()
- if err != nil {
- return "", fmt.Errorf("resolving home directory: %w", err)
- }
- return filepath.Join(home, ".picoclaw"), nil
-}
-
-func resolveWorkspace(homeDir string) string {
- return filepath.Join(homeDir, "workspace")
-}
-
-func expandHome(path string) string {
- if path == "" {
- return path
- }
- if path[0] == '~' {
- home, _ := os.UserHomeDir()
- if len(path) > 1 && path[1] == '/' {
- return home + path[1:]
+ for _, action := range actions {
+ switch action.Type {
+ case ActionConvertConfig:
+ fmt.Printf(" [config] %s -> %s\n", action.Source, action.Target)
+ configCount++
+ case ActionCopy:
+ fmt.Printf(" [copy] %s\n", filepath.Base(action.Source))
+ copies++
+ case ActionBackup:
+ fmt.Printf(" [backup] %s (exists, will backup and overwrite)\n", filepath.Base(action.Target))
+ backups++
+ copies++
+ case ActionSkip:
+ if action.Description != "" {
+ fmt.Printf(" [skip] %s (%s)\n", filepath.Base(action.Source), action.Description)
+ }
+ skips++
+ case ActionCreateDir:
+ fmt.Printf(" [mkdir] %s\n", action.Target)
}
- return home
}
- return path
-}
-
-func backupFile(path string) error {
- bakPath := path + ".bak"
- return copyFile(path, bakPath)
-}
-
-func copyFile(src, dst string) error {
- srcFile, err := os.Open(src)
- if err != nil {
- return err
- }
- defer srcFile.Close()
-
- info, err := srcFile.Stat()
- if err != nil {
- return err
- }
-
- dstFile, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode())
- if err != nil {
- return err
- }
- defer dstFile.Close()
-
- _, err = io.Copy(dstFile, srcFile)
- return err
-}
-
-func relPath(path, base string) string {
- rel, err := filepath.Rel(base, path)
- if err != nil {
- return filepath.Base(path)
- }
- return rel
+
+ if len(warnings) > 0 {
+ fmt.Println()
+ fmt.Println("Warnings:")
+ for _, w := range warnings {
+ fmt.Printf(" - %s\n", w)
+ }
+ }
+
+ fmt.Println()
+ fmt.Printf("%d files to copy, %d configs to convert, %d backups needed, %d skipped\n",
+ copies, configCount, backups, skips)
}
diff --git a/pkg/migrate/migrate_test.go b/pkg/migrate/migrate_test.go
index b6b3d70aa..fc9c2c3a7 100644
--- a/pkg/migrate/migrate_test.go
+++ b/pkg/migrate/migrate_test.go
@@ -1,875 +1,411 @@
package migrate
import (
- "encoding/json"
"os"
"path/filepath"
"testing"
- "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
)
-func TestCamelToSnake(t *testing.T) {
- tests := []struct {
- name string
- input string
- want string
- }{
- {"simple", "apiKey", "api_key"},
- {"two words", "apiBase", "api_base"},
- {"three words", "maxToolIterations", "max_tool_iterations"},
- {"already snake", "api_key", "api_key"},
- {"single word", "enabled", "enabled"},
- {"all lower", "model", "model"},
- {"consecutive caps", "apiURL", "api_url"},
- {"starts upper", "Model", "model"},
- {"bridge url", "bridgeUrl", "bridge_url"},
- {"client id", "clientId", "client_id"},
- {"app secret", "appSecret", "app_secret"},
- {"verification token", "verificationToken", "verification_token"},
- {"allow from", "allowFrom", "allow_from"},
- }
- for _, tt := range tests {
- t.Run(tt.name, func(t *testing.T) {
- got := camelToSnake(tt.input)
- if got != tt.want {
- t.Errorf("camelToSnake(%q) = %q, want %q", tt.input, got, tt.want)
- }
- })
+func TestNewMigrateInstance(t *testing.T) {
+ opts := Options{
+ Source: "openclaw",
}
+ instance := NewMigrateInstance(opts)
+ require.NotNil(t, instance)
+ assert.Equal(t, "openclaw", instance.options.Source)
}
-func TestConvertKeysToSnake(t *testing.T) {
- input := map[string]any{
- "apiKey": "test-key",
- "apiBase": "https://example.com",
- "nested": map[string]any{
- "maxTokens": float64(8192),
- "allowFrom": []any{"user1", "user2"},
- "deeperLevel": map[string]any{
- "clientId": "abc",
- },
- },
- }
+func TestMigrateInstanceRegister(t *testing.T) {
+ instance := NewMigrateInstance(Options{})
+ require.NotNil(t, instance)
- result := convertKeysToSnake(input)
- m, ok := result.(map[string]any)
- if !ok {
- t.Fatal("expected map[string]interface{}")
- }
+ mockHandler := &mockOperation{}
+ instance.Register("test-source", mockHandler)
- if _, ok = m["api_key"]; !ok {
- t.Error("expected key 'api_key' after conversion")
- }
- if _, ok = m["api_base"]; !ok {
- t.Error("expected key 'api_base' after conversion")
- }
-
- nested, ok := m["nested"].(map[string]any)
- if !ok {
- t.Fatal("expected nested map")
- }
- if _, ok = nested["max_tokens"]; !ok {
- t.Error("expected key 'max_tokens' in nested map")
- }
- if _, ok = nested["allow_from"]; !ok {
- t.Error("expected key 'allow_from' in nested map")
- }
-
- deeper, ok := nested["deeper_level"].(map[string]any)
- if !ok {
- t.Fatal("expected deeper_level map")
- }
- if _, ok := deeper["client_id"]; !ok {
- t.Error("expected key 'client_id' in deeper level")
- }
+ handler, ok := instance.handlers["test-source"]
+ require.True(t, ok)
+ assert.Equal(t, mockHandler, handler)
}
-func TestLoadOpenClawConfig(t *testing.T) {
+func TestMigrateInstanceGetCurrentHandler(t *testing.T) {
tmpDir := t.TempDir()
configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
- openclawConfig := map[string]any{
- "providers": map[string]any{
- "anthropic": map[string]any{
- "apiKey": "sk-ant-test123",
- "apiBase": "https://api.anthropic.com",
- },
- },
- "agents": map[string]any{
- "defaults": map[string]any{
- "maxTokens": float64(4096),
- "model": "claude-3-opus",
- },
- },
- }
+ instance := NewMigrateInstance(Options{SourceHome: tmpDir})
+ require.NotNil(t, instance)
- data, err := json.Marshal(openclawConfig)
- if err != nil {
- t.Fatal(err)
- }
- if err = os.WriteFile(configPath, data, 0o644); err != nil {
- t.Fatal(err)
- }
-
- result, err := LoadOpenClawConfig(configPath)
- if err != nil {
- t.Fatalf("LoadOpenClawConfig: %v", err)
- }
-
- providers, ok := result["providers"].(map[string]any)
- if !ok {
- t.Fatal("expected providers map")
- }
- anthropic, ok := providers["anthropic"].(map[string]any)
- if !ok {
- t.Fatal("expected anthropic map")
- }
- if anthropic["api_key"] != "sk-ant-test123" {
- t.Errorf("api_key = %v, want sk-ant-test123", anthropic["api_key"])
- }
-
- agents, ok := result["agents"].(map[string]any)
- if !ok {
- t.Fatal("expected agents map")
- }
- defaults, ok := agents["defaults"].(map[string]any)
- if !ok {
- t.Fatal("expected defaults map")
- }
- if defaults["max_tokens"] != float64(4096) {
- t.Errorf("max_tokens = %v, want 4096", defaults["max_tokens"])
- }
+ handler, err := instance.getCurrentHandler()
+ require.NoError(t, err)
+ require.NotNil(t, handler)
+ assert.Equal(t, "openclaw", handler.GetSourceName())
}
-func TestConvertConfig(t *testing.T) {
- t.Run("providers mapping", func(t *testing.T) {
- data := map[string]any{
- "providers": map[string]any{
- "anthropic": map[string]any{
- "api_key": "sk-ant-test",
- "api_base": "https://api.anthropic.com",
- },
- "openrouter": map[string]any{
- "api_key": "sk-or-test",
- },
- "groq": map[string]any{
- "api_key": "gsk-test",
- },
- },
- }
-
- cfg, warnings, err := ConvertConfig(data)
- if err != nil {
- t.Fatalf("ConvertConfig: %v", err)
- }
- if len(warnings) != 0 {
- t.Errorf("expected no warnings, got %v", warnings)
- }
- if cfg.Providers.Anthropic.APIKey != "sk-ant-test" {
- t.Errorf("Anthropic.APIKey = %q, want %q", cfg.Providers.Anthropic.APIKey, "sk-ant-test")
- }
- if cfg.Providers.OpenRouter.APIKey != "sk-or-test" {
- t.Errorf("OpenRouter.APIKey = %q, want %q", cfg.Providers.OpenRouter.APIKey, "sk-or-test")
- }
- if cfg.Providers.Groq.APIKey != "gsk-test" {
- t.Errorf("Groq.APIKey = %q, want %q", cfg.Providers.Groq.APIKey, "gsk-test")
- }
- })
-
- t.Run("unsupported provider warning", func(t *testing.T) {
- data := map[string]any{
- "providers": map[string]any{
- "unknown_provider": map[string]any{
- "api_key": "sk-test",
- },
- },
- }
-
- _, warnings, err := ConvertConfig(data)
- if err != nil {
- t.Fatalf("ConvertConfig: %v", err)
- }
- if len(warnings) != 1 {
- t.Fatalf("expected 1 warning, got %d", len(warnings))
- }
- if warnings[0] != "Provider 'unknown_provider' not supported in PicoClaw, skipping" {
- t.Errorf("unexpected warning: %s", warnings[0])
- }
- })
-
- t.Run("channels mapping", func(t *testing.T) {
- data := map[string]any{
- "channels": map[string]any{
- "telegram": map[string]any{
- "enabled": true,
- "token": "tg-token-123",
- "allow_from": []any{"user1"},
- },
- "discord": map[string]any{
- "enabled": true,
- "token": "disc-token-456",
- },
- },
- }
-
- cfg, _, err := ConvertConfig(data)
- if err != nil {
- t.Fatalf("ConvertConfig: %v", err)
- }
- if !cfg.Channels.Telegram.Enabled {
- t.Error("Telegram should be enabled")
- }
- if cfg.Channels.Telegram.Token != "tg-token-123" {
- t.Errorf("Telegram.Token = %q, want %q", cfg.Channels.Telegram.Token, "tg-token-123")
- }
- if len(cfg.Channels.Telegram.AllowFrom) != 1 || cfg.Channels.Telegram.AllowFrom[0] != "user1" {
- t.Errorf("Telegram.AllowFrom = %v, want [user1]", cfg.Channels.Telegram.AllowFrom)
- }
- if !cfg.Channels.Discord.Enabled {
- t.Error("Discord should be enabled")
- }
- })
-
- t.Run("unsupported channel warning", func(t *testing.T) {
- data := map[string]any{
- "channels": map[string]any{
- "email": map[string]any{
- "enabled": true,
- },
- },
- }
-
- _, warnings, err := ConvertConfig(data)
- if err != nil {
- t.Fatalf("ConvertConfig: %v", err)
- }
- if len(warnings) != 1 {
- t.Fatalf("expected 1 warning, got %d", len(warnings))
- }
- if warnings[0] != "Channel 'email' not supported in PicoClaw, skipping" {
- t.Errorf("unexpected warning: %s", warnings[0])
- }
- })
-
- t.Run("agent defaults", func(t *testing.T) {
- data := map[string]any{
- "agents": map[string]any{
- "defaults": map[string]any{
- "model": "claude-3-opus",
- "max_tokens": float64(4096),
- "temperature": 0.5,
- "max_tool_iterations": float64(10),
- "workspace": "~/.openclaw/workspace",
- },
- },
- }
-
- cfg, _, err := ConvertConfig(data)
- if err != nil {
- t.Fatalf("ConvertConfig: %v", err)
- }
- if cfg.Agents.Defaults.Model != "claude-3-opus" {
- t.Errorf("Model = %q, want %q", cfg.Agents.Defaults.Model, "claude-3-opus")
- }
- if cfg.Agents.Defaults.MaxTokens != 4096 {
- t.Errorf("MaxTokens = %d, want %d", cfg.Agents.Defaults.MaxTokens, 4096)
- }
- if cfg.Agents.Defaults.Temperature == nil {
- t.Fatalf("Temperature is nil, want %f", 0.5)
- }
- if *cfg.Agents.Defaults.Temperature != 0.5 {
- t.Errorf("Temperature = %f, want %f", *cfg.Agents.Defaults.Temperature, 0.5)
- }
- if cfg.Agents.Defaults.Workspace != "~/.picoclaw/workspace" {
- t.Errorf("Workspace = %q, want %q", cfg.Agents.Defaults.Workspace, "~/.picoclaw/workspace")
- }
- })
-
- t.Run("empty config", func(t *testing.T) {
- data := map[string]any{}
-
- cfg, warnings, err := ConvertConfig(data)
- if err != nil {
- t.Fatalf("ConvertConfig: %v", err)
- }
- if len(warnings) != 0 {
- t.Errorf("expected no warnings, got %v", warnings)
- }
- if cfg.Agents.Defaults.Model != "glm-4.7" {
- t.Errorf("default model should be glm-4.7, got %q", cfg.Agents.Defaults.Model)
- }
- })
-}
-
-func TestSupportedProvidersCompatibility(t *testing.T) {
- expected := []string{
- "anthropic",
- "openai",
- "openrouter",
- "groq",
- "zhipu",
- "vllm",
- "gemini",
- }
-
- for _, provider := range expected {
- if !supportedProviders[provider] {
- t.Fatalf("supportedProviders missing expected key %q", provider)
- }
- }
-}
-
-func TestMergeConfig(t *testing.T) {
- t.Run("fills empty fields", func(t *testing.T) {
- existing := config.DefaultConfig()
- incoming := config.DefaultConfig()
- incoming.Providers.Anthropic.APIKey = "sk-ant-incoming"
- incoming.Providers.OpenRouter.APIKey = "sk-or-incoming"
-
- result := MergeConfig(existing, incoming)
- if result.Providers.Anthropic.APIKey != "sk-ant-incoming" {
- t.Errorf("Anthropic.APIKey = %q, want %q", result.Providers.Anthropic.APIKey, "sk-ant-incoming")
- }
- if result.Providers.OpenRouter.APIKey != "sk-or-incoming" {
- t.Errorf("OpenRouter.APIKey = %q, want %q", result.Providers.OpenRouter.APIKey, "sk-or-incoming")
- }
- })
-
- t.Run("preserves existing non-empty fields", func(t *testing.T) {
- existing := config.DefaultConfig()
- existing.Providers.Anthropic.APIKey = "sk-ant-existing"
-
- incoming := config.DefaultConfig()
- incoming.Providers.Anthropic.APIKey = "sk-ant-incoming"
- incoming.Providers.OpenAI.APIKey = "sk-oai-incoming"
-
- result := MergeConfig(existing, incoming)
- if result.Providers.Anthropic.APIKey != "sk-ant-existing" {
- t.Errorf("Anthropic.APIKey should be preserved, got %q", result.Providers.Anthropic.APIKey)
- }
- if result.Providers.OpenAI.APIKey != "sk-oai-incoming" {
- t.Errorf("OpenAI.APIKey should be filled, got %q", result.Providers.OpenAI.APIKey)
- }
- })
-
- t.Run("merges enabled channels", func(t *testing.T) {
- existing := config.DefaultConfig()
- incoming := config.DefaultConfig()
- incoming.Channels.Telegram.Enabled = true
- incoming.Channels.Telegram.Token = "tg-token"
-
- result := MergeConfig(existing, incoming)
- if !result.Channels.Telegram.Enabled {
- t.Error("Telegram should be enabled after merge")
- }
- if result.Channels.Telegram.Token != "tg-token" {
- t.Errorf("Telegram.Token = %q, want %q", result.Channels.Telegram.Token, "tg-token")
- }
- })
-
- t.Run("preserves existing enabled channels", func(t *testing.T) {
- existing := config.DefaultConfig()
- existing.Channels.Telegram.Enabled = true
- existing.Channels.Telegram.Token = "existing-token"
-
- incoming := config.DefaultConfig()
- incoming.Channels.Telegram.Enabled = true
- incoming.Channels.Telegram.Token = "incoming-token"
-
- result := MergeConfig(existing, incoming)
- if result.Channels.Telegram.Token != "existing-token" {
- t.Errorf("Telegram.Token should be preserved, got %q", result.Channels.Telegram.Token)
- }
- })
-}
-
-func TestPlanWorkspaceMigration(t *testing.T) {
- t.Run("copies available files", func(t *testing.T) {
- srcDir := t.TempDir()
- dstDir := t.TempDir()
-
- os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents"), 0o644)
- os.WriteFile(filepath.Join(srcDir, "SOUL.md"), []byte("# Soul"), 0o644)
- os.WriteFile(filepath.Join(srcDir, "USER.md"), []byte("# User"), 0o644)
-
- actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
- if err != nil {
- t.Fatalf("PlanWorkspaceMigration: %v", err)
- }
-
- copyCount := 0
- skipCount := 0
- for _, a := range actions {
- if a.Type == ActionCopy {
- copyCount++
- }
- if a.Type == ActionSkip {
- skipCount++
- }
- }
- if copyCount != 3 {
- t.Errorf("expected 3 copies, got %d", copyCount)
- }
- if skipCount != 2 {
- t.Errorf("expected 2 skips (TOOLS.md, HEARTBEAT.md), got %d", skipCount)
- }
- })
-
- t.Run("plans backup for existing destination files", func(t *testing.T) {
- srcDir := t.TempDir()
- dstDir := t.TempDir()
-
- os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents from OpenClaw"), 0o644)
- os.WriteFile(filepath.Join(dstDir, "AGENTS.md"), []byte("# Existing Agents"), 0o644)
-
- actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
- if err != nil {
- t.Fatalf("PlanWorkspaceMigration: %v", err)
- }
-
- backupCount := 0
- for _, a := range actions {
- if a.Type == ActionBackup && filepath.Base(a.Destination) == "AGENTS.md" {
- backupCount++
- }
- }
- if backupCount != 1 {
- t.Errorf("expected 1 backup action for AGENTS.md, got %d", backupCount)
- }
- })
-
- t.Run("force skips backup", func(t *testing.T) {
- srcDir := t.TempDir()
- dstDir := t.TempDir()
-
- os.WriteFile(filepath.Join(srcDir, "AGENTS.md"), []byte("# Agents"), 0o644)
- os.WriteFile(filepath.Join(dstDir, "AGENTS.md"), []byte("# Existing"), 0o644)
-
- actions, err := PlanWorkspaceMigration(srcDir, dstDir, true)
- if err != nil {
- t.Fatalf("PlanWorkspaceMigration: %v", err)
- }
-
- for _, a := range actions {
- if a.Type == ActionBackup {
- t.Error("expected no backup actions with force=true")
- }
- }
- })
-
- t.Run("handles memory directory", func(t *testing.T) {
- srcDir := t.TempDir()
- dstDir := t.TempDir()
-
- memDir := filepath.Join(srcDir, "memory")
- os.MkdirAll(memDir, 0o755)
- os.WriteFile(filepath.Join(memDir, "MEMORY.md"), []byte("# Memory"), 0o644)
-
- actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
- if err != nil {
- t.Fatalf("PlanWorkspaceMigration: %v", err)
- }
-
- hasCopy := false
- hasDir := false
- for _, a := range actions {
- if a.Type == ActionCopy && filepath.Base(a.Source) == "MEMORY.md" {
- hasCopy = true
- }
- if a.Type == ActionCreateDir {
- hasDir = true
- }
- }
- if !hasCopy {
- t.Error("expected copy action for memory/MEMORY.md")
- }
- if !hasDir {
- t.Error("expected create dir action for memory/")
- }
- })
-
- t.Run("handles skills directory", func(t *testing.T) {
- srcDir := t.TempDir()
- dstDir := t.TempDir()
-
- skillDir := filepath.Join(srcDir, "skills", "weather")
- os.MkdirAll(skillDir, 0o755)
- os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("# Weather"), 0o644)
-
- actions, err := PlanWorkspaceMigration(srcDir, dstDir, false)
- if err != nil {
- t.Fatalf("PlanWorkspaceMigration: %v", err)
- }
-
- hasCopy := false
- for _, a := range actions {
- if a.Type == ActionCopy && filepath.Base(a.Source) == "SKILL.md" {
- hasCopy = true
- }
- }
- if !hasCopy {
- t.Error("expected copy action for skills/weather/SKILL.md")
- }
- })
-}
-
-func TestFindOpenClawConfig(t *testing.T) {
- t.Run("finds openclaw.json", func(t *testing.T) {
- tmpDir := t.TempDir()
- configPath := filepath.Join(tmpDir, "openclaw.json")
- os.WriteFile(configPath, []byte("{}"), 0o644)
-
- found, err := findOpenClawConfig(tmpDir)
- if err != nil {
- t.Fatalf("findOpenClawConfig: %v", err)
- }
- if found != configPath {
- t.Errorf("found %q, want %q", found, configPath)
- }
- })
-
- t.Run("falls back to config.json", func(t *testing.T) {
- tmpDir := t.TempDir()
- configPath := filepath.Join(tmpDir, "config.json")
- os.WriteFile(configPath, []byte("{}"), 0o644)
-
- found, err := findOpenClawConfig(tmpDir)
- if err != nil {
- t.Fatalf("findOpenClawConfig: %v", err)
- }
- if found != configPath {
- t.Errorf("found %q, want %q", found, configPath)
- }
- })
-
- t.Run("prefers openclaw.json over config.json", func(t *testing.T) {
- tmpDir := t.TempDir()
- openclawPath := filepath.Join(tmpDir, "openclaw.json")
- os.WriteFile(openclawPath, []byte("{}"), 0o644)
- os.WriteFile(filepath.Join(tmpDir, "config.json"), []byte("{}"), 0o644)
-
- found, err := findOpenClawConfig(tmpDir)
- if err != nil {
- t.Fatalf("findOpenClawConfig: %v", err)
- }
- if found != openclawPath {
- t.Errorf("should prefer openclaw.json, got %q", found)
- }
- })
-
- t.Run("error when no config found", func(t *testing.T) {
- tmpDir := t.TempDir()
-
- _, err := findOpenClawConfig(tmpDir)
- if err == nil {
- t.Fatal("expected error when no config found")
- }
- })
-}
-
-func TestRewriteWorkspacePath(t *testing.T) {
- tests := []struct {
- name string
- input string
- want string
- }{
- {"default path", "~/.openclaw/workspace", "~/.picoclaw/workspace"},
- {"custom path", "/custom/path", "/custom/path"},
- {"empty", "", ""},
- }
- for _, tt := range tests {
- t.Run(tt.name, func(t *testing.T) {
- got := rewriteWorkspacePath(tt.input)
- if got != tt.want {
- t.Errorf("rewriteWorkspacePath(%q) = %q, want %q", tt.input, got, tt.want)
- }
- })
- }
-}
-
-func TestRunDryRun(t *testing.T) {
- openclawHome := t.TempDir()
- picoClawHome := t.TempDir()
-
- wsDir := filepath.Join(openclawHome, "workspace")
- os.MkdirAll(wsDir, 0o755)
- os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0o644)
- os.WriteFile(filepath.Join(wsDir, "AGENTS.md"), []byte("# Agents"), 0o644)
-
- configData := map[string]any{
- "providers": map[string]any{
- "anthropic": map[string]any{
- "apiKey": "test-key",
- },
- },
- }
- data, _ := json.Marshal(configData)
- os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0o644)
+func TestMigrateInstanceGetCurrentHandlerWithSource(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
opts := Options{
- DryRun: true,
- OpenClawHome: openclawHome,
- PicoClawHome: picoClawHome,
+ Source: "openclaw",
+ SourceHome: tmpDir,
}
+ instance := NewMigrateInstance(opts)
- result, err := Run(opts)
- if err != nil {
- t.Fatalf("Run: %v", err)
- }
-
- picoWs := filepath.Join(picoClawHome, "workspace")
- if _, err := os.Stat(filepath.Join(picoWs, "SOUL.md")); !os.IsNotExist(err) {
- t.Error("dry run should not create files")
- }
- if _, err := os.Stat(filepath.Join(picoClawHome, "config.json")); !os.IsNotExist(err) {
- t.Error("dry run should not create config")
- }
-
- _ = result
+ handler, err := instance.getCurrentHandler()
+ require.NoError(t, err)
+ require.NotNil(t, handler)
+ assert.Equal(t, "openclaw", handler.GetSourceName())
}
-func TestRunFullMigration(t *testing.T) {
- openclawHome := t.TempDir()
- picoClawHome := t.TempDir()
-
- wsDir := filepath.Join(openclawHome, "workspace")
- os.MkdirAll(wsDir, 0o755)
- os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul from OpenClaw"), 0o644)
- os.WriteFile(filepath.Join(wsDir, "AGENTS.md"), []byte("# Agents from OpenClaw"), 0o644)
- os.WriteFile(filepath.Join(wsDir, "USER.md"), []byte("# User from OpenClaw"), 0o644)
-
- memDir := filepath.Join(wsDir, "memory")
- os.MkdirAll(memDir, 0o755)
- os.WriteFile(filepath.Join(memDir, "MEMORY.md"), []byte("# Memory notes"), 0o644)
-
- configData := map[string]any{
- "providers": map[string]any{
- "anthropic": map[string]any{
- "apiKey": "sk-ant-migrate-test",
- },
- "openrouter": map[string]any{
- "apiKey": "sk-or-migrate-test",
- },
- },
- "channels": map[string]any{
- "telegram": map[string]any{
- "enabled": true,
- "token": "tg-migrate-test",
- },
- },
- }
- data, _ := json.Marshal(configData)
- os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0o644)
-
- opts := Options{
- Force: true,
- OpenClawHome: openclawHome,
- PicoClawHome: picoClawHome,
+func TestMigrateInstanceGetCurrentHandlerNotFound(t *testing.T) {
+ instance := &MigrateInstance{
+ options: Options{},
+ handlers: make(map[string]Operation),
}
- result, err := Run(opts)
- if err != nil {
- t.Fatalf("Run: %v", err)
- }
-
- picoWs := filepath.Join(picoClawHome, "workspace")
-
- soulData, err := os.ReadFile(filepath.Join(picoWs, "SOUL.md"))
- if err != nil {
- t.Fatalf("reading SOUL.md: %v", err)
- }
- if string(soulData) != "# Soul from OpenClaw" {
- t.Errorf("SOUL.md content = %q, want %q", string(soulData), "# Soul from OpenClaw")
- }
-
- agentsData, err := os.ReadFile(filepath.Join(picoWs, "AGENTS.md"))
- if err != nil {
- t.Fatalf("reading AGENTS.md: %v", err)
- }
- if string(agentsData) != "# Agents from OpenClaw" {
- t.Errorf("AGENTS.md content = %q", string(agentsData))
- }
-
- memData, err := os.ReadFile(filepath.Join(picoWs, "memory", "MEMORY.md"))
- if err != nil {
- t.Fatalf("reading memory/MEMORY.md: %v", err)
- }
- if string(memData) != "# Memory notes" {
- t.Errorf("MEMORY.md content = %q", string(memData))
- }
-
- picoConfig, err := config.LoadConfig(filepath.Join(picoClawHome, "config.json"))
- if err != nil {
- t.Fatalf("loading PicoClaw config: %v", err)
- }
- if picoConfig.Providers.Anthropic.APIKey != "sk-ant-migrate-test" {
- t.Errorf("Anthropic.APIKey = %q, want %q", picoConfig.Providers.Anthropic.APIKey, "sk-ant-migrate-test")
- }
- if picoConfig.Providers.OpenRouter.APIKey != "sk-or-migrate-test" {
- t.Errorf("OpenRouter.APIKey = %q, want %q", picoConfig.Providers.OpenRouter.APIKey, "sk-or-migrate-test")
- }
- if !picoConfig.Channels.Telegram.Enabled {
- t.Error("Telegram should be enabled")
- }
- if picoConfig.Channels.Telegram.Token != "tg-migrate-test" {
- t.Errorf("Telegram.Token = %q, want %q", picoConfig.Channels.Telegram.Token, "tg-migrate-test")
- }
-
- if result.FilesCopied < 3 {
- t.Errorf("expected at least 3 files copied, got %d", result.FilesCopied)
- }
- if !result.ConfigMigrated {
- t.Error("config should have been migrated")
- }
- if len(result.Errors) > 0 {
- t.Errorf("expected no errors, got %v", result.Errors)
- }
+ _, err := instance.getCurrentHandler()
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "not found")
}
-func TestRunOpenClawNotFound(t *testing.T) {
- opts := Options{
- OpenClawHome: "/nonexistent/path/to/openclaw",
- PicoClawHome: t.TempDir(),
+func TestMigrateInstancePlanWithInvalidSource(t *testing.T) {
+ instance := &MigrateInstance{
+ options: Options{},
+ handlers: make(map[string]Operation),
}
- _, err := Run(opts)
- if err == nil {
- t.Fatal("expected error when OpenClaw not found")
- }
+ _, _, err := instance.Plan(Options{}, "/tmp/source", "/tmp/target")
+ require.Error(t, err)
}
-func TestRunMutuallyExclusiveFlags(t *testing.T) {
- opts := Options{
+func TestMigrateInstancePlanConfigOnlyAndWorkspaceOnlyMutuallyExclusive(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ instance := NewMigrateInstance(Options{SourceHome: tmpDir})
+ require.NotNil(t, instance)
+
+ _, err = instance.Run(Options{
ConfigOnly: true,
WorkspaceOnly: true,
- }
-
- _, err := Run(opts)
- if err == nil {
- t.Fatal("expected error for mutually exclusive flags")
- }
+ })
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "mutually exclusive")
}
-func TestBackupFile(t *testing.T) {
+func TestMigrateInstancePlanRefreshSetsWorkspaceOnly(t *testing.T) {
+ opts := Options{
+ Refresh: true,
+ SourceHome: "/tmp/nonexistent",
+ }
+ instance := NewMigrateInstance(opts)
+ require.NotNil(t, instance)
+
+ _, err := instance.Run(opts)
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "not found")
+}
+
+func TestMigrateInstancePlanSourceNotFound(t *testing.T) {
+ opts := Options{
+ SourceHome: "/tmp/nonexistent-source-home",
+ }
+ instance := NewMigrateInstance(opts)
+
+ _, err := instance.Run(opts)
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "not found")
+}
+
+func TestMigrateInstanceExecute(t *testing.T) {
tmpDir := t.TempDir()
- filePath := filepath.Join(tmpDir, "test.md")
- os.WriteFile(filePath, []byte("original content"), 0o644)
+ sourceDir := filepath.Join(tmpDir, "source")
+ targetDir := filepath.Join(tmpDir, "target")
+ workspaceDir := filepath.Join(sourceDir, "workspace")
- if err := backupFile(filePath); err != nil {
- t.Fatalf("backupFile: %v", err)
+ err := os.MkdirAll(workspaceDir, 0o755)
+ require.NoError(t, err)
+
+ err = os.WriteFile(filepath.Join(workspaceDir, "test.txt"), []byte("test"), 0o644)
+ require.NoError(t, err)
+
+ instance := &MigrateInstance{
+ options: Options{Source: "mock"},
+ handlers: make(map[string]Operation),
}
+ instance.Register("mock", &mockOperation{sourceHome: sourceDir, sourceWs: workspaceDir})
- bakPath := filePath + ".bak"
- bakData, err := os.ReadFile(bakPath)
- if err != nil {
- t.Fatalf("reading backup: %v", err)
- }
- if string(bakData) != "original content" {
- t.Errorf("backup content = %q, want %q", string(bakData), "original content")
- }
-}
-
-func TestCopyFile(t *testing.T) {
- tmpDir := t.TempDir()
- srcPath := filepath.Join(tmpDir, "src.md")
- dstPath := filepath.Join(tmpDir, "dst.md")
-
- os.WriteFile(srcPath, []byte("file content"), 0o644)
-
- if err := copyFile(srcPath, dstPath); err != nil {
- t.Fatalf("copyFile: %v", err)
- }
-
- data, err := os.ReadFile(dstPath)
- if err != nil {
- t.Fatalf("reading copy: %v", err)
- }
- if string(data) != "file content" {
- t.Errorf("copy content = %q, want %q", string(data), "file content")
- }
-}
-
-func TestRunConfigOnly(t *testing.T) {
- openclawHome := t.TempDir()
- picoClawHome := t.TempDir()
-
- wsDir := filepath.Join(openclawHome, "workspace")
- os.MkdirAll(wsDir, 0o755)
- os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0o644)
-
- configData := map[string]any{
- "providers": map[string]any{
- "anthropic": map[string]any{
- "apiKey": "sk-config-only",
- },
+ actions := []Action{
+ {
+ Type: ActionCopy,
+ Source: filepath.Join(workspaceDir, "test.txt"),
+ Target: filepath.Join(targetDir, "workspace", "test.txt"),
+ Description: "copy file",
},
}
- data, _ := json.Marshal(configData)
- os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0o644)
- opts := Options{
- Force: true,
- ConfigOnly: true,
- OpenClawHome: openclawHome,
- PicoClawHome: picoClawHome,
- }
+ result := instance.Execute(actions, workspaceDir, targetDir)
+ require.NotNil(t, result)
+ assert.Equal(t, 1, result.FilesCopied)
- result, err := Run(opts)
- if err != nil {
- t.Fatalf("Run: %v", err)
- }
-
- if !result.ConfigMigrated {
- t.Error("config should have been migrated")
- }
-
- picoWs := filepath.Join(picoClawHome, "workspace")
- if _, err := os.Stat(filepath.Join(picoWs, "SOUL.md")); !os.IsNotExist(err) {
- t.Error("config-only should not copy workspace files")
- }
+ _, err = os.Stat(filepath.Join(targetDir, "workspace", "test.txt"))
+ assert.NoError(t, err)
}
-func TestRunWorkspaceOnly(t *testing.T) {
- openclawHome := t.TempDir()
- picoClawHome := t.TempDir()
+func TestMigrateInstanceExecuteWithInvalidSource(t *testing.T) {
+ tmpDir := t.TempDir()
+ sourceDir := filepath.Join(tmpDir, "source")
+ err := os.MkdirAll(sourceDir, 0o755)
+ require.NoError(t, err)
- wsDir := filepath.Join(openclawHome, "workspace")
- os.MkdirAll(wsDir, 0o755)
- os.WriteFile(filepath.Join(wsDir, "SOUL.md"), []byte("# Soul"), 0o644)
+ instance := &MigrateInstance{
+ options: Options{Source: "mock"},
+ handlers: make(map[string]Operation),
+ }
+ instance.Register("mock", &mockOperation{sourceHome: sourceDir})
- configData := map[string]any{
- "providers": map[string]any{
- "anthropic": map[string]any{
- "apiKey": "sk-ws-only",
- },
+ actions := []Action{
+ {
+ Type: ActionCopy,
+ Source: filepath.Join(sourceDir, "nonexistent.txt"),
+ Target: filepath.Join(tmpDir, "target.txt"),
+ Description: "copy file",
},
}
- data, _ := json.Marshal(configData)
- os.WriteFile(filepath.Join(openclawHome, "openclaw.json"), data, 0o644)
- opts := Options{
- Force: true,
- WorkspaceOnly: true,
- OpenClawHome: openclawHome,
- PicoClawHome: picoClawHome,
- }
-
- result, err := Run(opts)
- if err != nil {
- t.Fatalf("Run: %v", err)
- }
-
- if result.ConfigMigrated {
- t.Error("workspace-only should not migrate config")
- }
-
- picoWs := filepath.Join(picoClawHome, "workspace")
- soulData, err := os.ReadFile(filepath.Join(picoWs, "SOUL.md"))
- if err != nil {
- t.Fatalf("reading SOUL.md: %v", err)
- }
- if string(soulData) != "# Soul" {
- t.Errorf("SOUL.md content = %q", string(soulData))
- }
+ result := instance.Execute(actions, sourceDir, tmpDir)
+ require.NotNil(t, result)
+ assert.Equal(t, 0, result.FilesCopied)
+ assert.Greater(t, len(result.Errors), 0)
+}
+
+func TestMigrateInstanceExecuteCreateDir(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ instance := &MigrateInstance{
+ options: Options{Source: "mock"},
+ handlers: make(map[string]Operation),
+ }
+ instance.Register("mock", &mockOperation{})
+
+ actions := []Action{
+ {
+ Type: ActionCreateDir,
+ Target: filepath.Join(tmpDir, "new", "dir"),
+ Description: "create directory",
+ },
+ }
+
+ result := instance.Execute(actions, "", "")
+ require.NotNil(t, result)
+ assert.Equal(t, 1, result.DirsCreated)
+
+ _, err := os.Stat(filepath.Join(tmpDir, "new", "dir"))
+ assert.NoError(t, err)
+}
+
+func TestMigrateInstanceExecuteBackup(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ sourceFile := filepath.Join(tmpDir, "source.txt")
+ targetFile := filepath.Join(tmpDir, "target.txt")
+
+ err := os.WriteFile(sourceFile, []byte("source"), 0o644)
+ require.NoError(t, err)
+
+ err = os.WriteFile(targetFile, []byte("target"), 0o644)
+ require.NoError(t, err)
+
+ instance := &MigrateInstance{
+ options: Options{Source: "mock"},
+ handlers: make(map[string]Operation),
+ }
+ instance.Register("mock", &mockOperation{})
+
+ actions := []Action{
+ {
+ Type: ActionBackup,
+ Source: sourceFile,
+ Target: targetFile,
+ Description: "backup and overwrite",
+ },
+ }
+
+ result := instance.Execute(actions, tmpDir, tmpDir)
+ require.NotNil(t, result)
+ assert.Equal(t, 1, result.BackupsCreated)
+ assert.Equal(t, 1, result.FilesCopied)
+
+ bakFile := targetFile + ".bak"
+ _, err = os.Stat(bakFile)
+ assert.NoError(t, err)
+
+ content, err := os.ReadFile(targetFile)
+ assert.NoError(t, err)
+ assert.Equal(t, "source", string(content))
+}
+
+func TestMigrateInstanceExecuteSkip(t *testing.T) {
+ instance := &MigrateInstance{
+ options: Options{Source: "mock"},
+ handlers: make(map[string]Operation),
+ }
+ instance.Register("mock", &mockOperation{})
+
+ actions := []Action{
+ {
+ Type: ActionSkip,
+ Source: "/tmp/source.txt",
+ Target: "/tmp/target.txt",
+ Description: "skip file",
+ },
+ }
+
+ result := instance.Execute(actions, "", "")
+ require.NotNil(t, result)
+ assert.Equal(t, 1, result.FilesSkipped)
+}
+
+func TestMigrateInstancePrintSummary(t *testing.T) {
+ instance := NewMigrateInstance(Options{})
+
+ result := &Result{
+ FilesCopied: 5,
+ ConfigMigrated: true,
+ BackupsCreated: 2,
+ FilesSkipped: 3,
+ Warnings: []string{"warning 1"},
+ Errors: []error{},
+ }
+
+ instance.PrintSummary(result)
+}
+
+func TestMigrateInstancePrintSummaryWithErrors(t *testing.T) {
+ instance := NewMigrateInstance(Options{})
+
+ result := &Result{
+ FilesCopied: 0,
+ ConfigMigrated: false,
+ BackupsCreated: 0,
+ FilesSkipped: 0,
+ Warnings: []string{},
+ Errors: []error{assert.AnError},
+ }
+
+ instance.PrintSummary(result)
+}
+
+func TestMigrateInstancePrintSummaryNoActions(t *testing.T) {
+ instance := NewMigrateInstance(Options{})
+
+ result := &Result{
+ FilesCopied: 0,
+ ConfigMigrated: false,
+ BackupsCreated: 0,
+ FilesSkipped: 0,
+ Warnings: []string{},
+ Errors: []error{},
+ }
+
+ instance.PrintSummary(result)
+}
+
+func TestPrintPlan(t *testing.T) {
+ actions := []Action{
+ {
+ Type: ActionConvertConfig,
+ Source: "/source/config.json",
+ Target: "/target/config.json",
+ Description: "convert config",
+ },
+ {
+ Type: ActionCopy,
+ Source: "/source/file.txt",
+ Target: "/target/file.txt",
+ Description: "copy file",
+ },
+ {
+ Type: ActionBackup,
+ Source: "/source/existing.txt",
+ Target: "/target/existing.txt",
+ Description: "backup and overwrite",
+ },
+ {
+ Type: ActionSkip,
+ Source: "/source/skipped.txt",
+ Target: "/target/skipped.txt",
+ Description: "skip file",
+ },
+ {
+ Type: ActionCreateDir,
+ Target: "/target/newdir",
+ Description: "create directory",
+ },
+ }
+
+ warnings := []string{
+ "Warning: source directory not found",
+ }
+
+ PrintPlan(actions, warnings)
+}
+
+func TestPrintPlanEmpty(t *testing.T) {
+ PrintPlan([]Action{}, []string{})
+}
+
+type mockOperation struct {
+ sourceHome string
+ sourceConfig string
+ sourceWs string
+ migrateFiles []string
+ migrateDirs []string
+}
+
+func (m *mockOperation) GetSourceName() string { return "mock" }
+func (m *mockOperation) GetSourceHome() (string, error) {
+ if m.sourceHome != "" {
+ return m.sourceHome, nil
+ }
+ return "/tmp/mock", nil
+}
+
+func (m *mockOperation) GetSourceWorkspace() (string, error) {
+ if m.sourceWs != "" {
+ return m.sourceWs, nil
+ }
+ if m.sourceHome != "" {
+ return filepath.Join(m.sourceHome, "workspace"), nil
+ }
+ return "/tmp/mock/workspace", nil
+}
+
+func (m *mockOperation) GetSourceConfigFile() (string, error) {
+ if m.sourceConfig != "" {
+ return m.sourceConfig, nil
+ }
+ return "/tmp/mock/config.json", nil
+}
+func (m *mockOperation) ExecuteConfigMigration(src, dst string) error { return nil }
+func (m *mockOperation) GetMigrateableFiles() []string {
+ if m.migrateFiles != nil {
+ return m.migrateFiles
+ }
+ return []string{}
+}
+
+func (m *mockOperation) GetMigrateableDirs() []string {
+ if m.migrateDirs != nil {
+ return m.migrateDirs
+ }
+ return []string{}
}
diff --git a/pkg/migrate/sources/openclaw/common.go b/pkg/migrate/sources/openclaw/common.go
new file mode 100644
index 000000000..dddd98089
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/common.go
@@ -0,0 +1,29 @@
+package openclaw
+
+var migrateableFiles = []string{
+ "AGENTS.md",
+ "SOUL.md",
+ "USER.md",
+ "TOOLS.md",
+ "HEARTBEAT.md",
+}
+
+var migrateableDirs = []string{
+ "memory",
+ "skills",
+}
+
+var supportedChannels = map[string]bool{
+ "whatsapp": true,
+ "telegram": true,
+ "feishu": true,
+ "discord": true,
+ "maixcam": true,
+ "qq": true,
+ "dingtalk": true,
+ "slack": true,
+ "line": true,
+ "onebot": true,
+ "wecom": true,
+ "wecom_app": true,
+}
diff --git a/pkg/migrate/sources/openclaw/openclaw_config.go b/pkg/migrate/sources/openclaw/openclaw_config.go
new file mode 100644
index 000000000..39ad48fad
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/openclaw_config.go
@@ -0,0 +1,1074 @@
+package openclaw
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+)
+
+type OpenClawConfig struct {
+ Auth *OpenClawAuth `json:"auth"`
+ Models *OpenClawModels `json:"models"`
+ Agents *OpenClawAgents `json:"agents"`
+ Tools *OpenClawTools `json:"tools"`
+ Channels *OpenClawChannels `json:"channels"`
+ Cron json.RawMessage `json:"cron"`
+ Hooks json.RawMessage `json:"hooks"`
+ Skills *OpenClawSkills `json:"skills"`
+ Memory json.RawMessage `json:"memory"`
+ Session json.RawMessage `json:"session"`
+}
+
+type OpenClawAuth struct {
+ Profiles json.RawMessage `json:"profiles"`
+ Order json.RawMessage `json:"order"`
+}
+
+type OpenClawModels struct {
+ Providers map[string]json.RawMessage `json:"providers"`
+}
+
+type ProviderConfig struct {
+ BaseUrl string `json:"baseUrl"`
+ Api string `json:"api"`
+ Models []ModelConfig `json:"models"`
+ ApiKey string `json:"apiKey"`
+}
+
+type OpenClawModelConfig struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Reasoning bool `json:"reasoning"`
+ Input []string `json:"input"`
+ Cost Cost `json:"cost"`
+ ContextWindow int `json:"contextWindow"`
+ MaxTokens int `json:"maxTokens"`
+ Api string `json:"api,omitempty"`
+}
+
+type Cost struct {
+ Input float64 `json:"input"`
+ Output float64 `json:"output"`
+ CacheRead float64 `json:"cacheRead"`
+ CacheWrite float64 `json:"cacheWrite"`
+}
+
+type OpenClawTools struct {
+ Profile *string `json:"profile"`
+ Allow []string `json:"allow"`
+ Deny []string `json:"deny"`
+}
+
+type OpenClawAgents struct {
+ Defaults *OpenClawAgentDefaults `json:"defaults"`
+ List []OpenClawAgentEntry `json:"list"`
+}
+
+type OpenClawAgentDefaults struct {
+ Model *OpenClawAgentModel `json:"model"`
+ Workspace *string `json:"workspace"`
+ Tools *OpenClawAgentTools `json:"tools"`
+ Identity *string `json:"identity"`
+}
+
+type OpenClawAgentModel struct {
+ Simple string `json:"-"`
+ Primary *string `json:"primary"`
+ Fallbacks []string `json:"fallbacks"`
+}
+
+func (m *OpenClawAgentModel) GetPrimary() string {
+ if m.Simple != "" {
+ return m.Simple
+ }
+ if m.Primary != nil {
+ return *m.Primary
+ }
+ return ""
+}
+
+func (m *OpenClawAgentModel) GetFallbacks() []string {
+ return m.Fallbacks
+}
+
+type OpenClawAgentEntry struct {
+ ID string `json:"id"`
+ Name *string `json:"name"`
+ Model *OpenClawAgentModel `json:"model"`
+ Tools *OpenClawAgentTools `json:"tools"`
+ Workspace *string `json:"workspace"`
+ Skills []string `json:"skills"`
+ Identity *string `json:"identity"`
+}
+
+type OpenClawAgentTools struct {
+ Profile *string `json:"profile"`
+ Allow []string `json:"allow"`
+ Deny []string `json:"deny"`
+ AlsoAllow []string `json:"alsoAllow"`
+}
+
+type OpenClawChannels struct {
+ Telegram *OpenClawTelegramConfig `json:"telegram"`
+ Discord *OpenClawDiscordConfig `json:"discord"`
+ Slack *OpenClawSlackConfig `json:"slack"`
+ WhatsApp *OpenClawWhatsAppConfig `json:"whatsapp"`
+ Signal *OpenClawSignalConfig `json:"signal"`
+ Matrix *OpenClawMatrixConfig `json:"matrix"`
+ GoogleChat *OpenClawGoogleChatConfig `json:"googlechat"`
+ Teams *OpenClawTeamsConfig `json:"msteams"`
+ IRC *OpenClawIrcConfig `json:"irc"`
+ Mattermost *OpenClawMattermostConfig `json:"mattermost"`
+ Feishu *OpenClawFeishuConfig `json:"feishu"`
+ IMessage *OpenClawIMessageConfig `json:"imessage"`
+ BlueBubbles *OpenClawBlueBubblesConfig `json:"bluebubbles"`
+ QQ *OpenClawQQConfig `json:"qq"`
+ DingTalk *OpenClawDingTalkConfig `json:"dingtalk"`
+ MaixCam *OpenClawMaixCamConfig `json:"maixcam"`
+}
+
+type OpenClawTelegramConfig struct {
+ BotToken *string `json:"botToken"`
+ AllowFrom []string `json:"allowFrom"`
+ GroupPolicy *string `json:"groupPolicy"`
+ DmPolicy *string `json:"dmPolicy"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawDiscordConfig struct {
+ Token *string `json:"token"`
+ Guilds json.RawMessage `json:"guilds"`
+ DmPolicy *string `json:"dmPolicy"`
+ GroupPolicy *string `json:"groupPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawSlackConfig struct {
+ BotToken *string `json:"botToken"`
+ AppToken *string `json:"appToken"`
+ DmPolicy *string `json:"dmPolicy"`
+ GroupPolicy *string `json:"groupPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawWhatsAppConfig struct {
+ AuthDir *string `json:"authDir"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ GroupPolicy *string `json:"groupPolicy"`
+ Enabled *bool `json:"enabled"`
+ BridgeURL *string `json:"bridgeUrl"`
+}
+
+type OpenClawSignalConfig struct {
+ HttpUrl *string `json:"httpUrl"`
+ HttpHost *string `json:"httpHost"`
+ HttpPort *int `json:"httpPort"`
+ Account *string `json:"account"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawMatrixConfig struct {
+ Homeserver *string `json:"homeserver"`
+ UserID *string `json:"userId"`
+ AccessToken *string `json:"accessToken"`
+ Rooms []string `json:"rooms"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawGoogleChatConfig struct {
+ ServiceAccountFile *string `json:"serviceAccountFile"`
+ WebhookPath *string `json:"webhookPath"`
+ BotUser *string `json:"botUser"`
+ DmPolicy *string `json:"dmPolicy"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawTeamsConfig struct {
+ AppID *string `json:"appId"`
+ AppPassword *string `json:"appPassword"`
+ TenantID *string `json:"tenantId"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawIrcConfig struct {
+ Host *string `json:"host"`
+ Port *int `json:"port"`
+ TLS *bool `json:"tls"`
+ Nick *string `json:"nick"`
+ Password *string `json:"password"`
+ Channels []string `json:"channels"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawMattermostConfig struct {
+ BotToken *string `json:"botToken"`
+ BaseURL *string `json:"baseUrl"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawFeishuConfig struct {
+ AppID *string `json:"appId"`
+ AppSecret *string `json:"appSecret"`
+ Domain *string `json:"domain"`
+ DmPolicy *string `json:"dmPolicy"`
+ Enabled *bool `json:"enabled"`
+ VerificationToken *string `json:"verificationToken"`
+ EncryptKey *string `json:"encryptKey"`
+ AllowFrom []string `json:"allowFrom"`
+}
+
+type OpenClawIMessageConfig struct {
+ CliPath *string `json:"cliPath"`
+ DbPath *string `json:"dbPath"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawBlueBubblesConfig struct {
+ ServerURL *string `json:"serverUrl"`
+ Password *string `json:"password"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawQQConfig struct {
+ AppID *string `json:"appId"`
+ AppSecret *string `json:"appSecret"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawDingTalkConfig struct {
+ AppID *string `json:"appId"`
+ AppSecret *string `json:"appSecret"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawMaixCamConfig struct {
+ Host *string `json:"host"`
+ Port *int `json:"port"`
+ DmPolicy *string `json:"dmPolicy"`
+ AllowFrom []string `json:"allowFrom"`
+ Enabled *bool `json:"enabled"`
+}
+
+type OpenClawSkills struct {
+ Entries map[string]json.RawMessage `json:"entries"`
+ Load json.RawMessage `json:"load"`
+}
+
+type OpenClawProviderConfig struct {
+ APIKey string `json:"api_key"`
+ BaseURL string `json:"base_url"`
+}
+
+func (c *OpenClawConfig) GetEnabled() bool {
+ return true
+}
+
+func LoadOpenClawConfig(path string) (*OpenClawConfig, error) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return nil, fmt.Errorf("failed to read config: %w", err)
+ }
+
+ var config OpenClawConfig
+ if err := json.Unmarshal(data, &config); err != nil {
+ return nil, fmt.Errorf("failed to parse JSON: %w", err)
+ }
+
+ return &config, nil
+}
+
+func LoadOpenClawConfigFromDir(dir string) (*OpenClawConfig, error) {
+ candidates := []string{
+ filepath.Join(dir, "openclaw.json"),
+ filepath.Join(dir, "config.json"),
+ }
+
+ for _, p := range candidates {
+ if _, err := os.Stat(p); err == nil {
+ return LoadOpenClawConfig(p)
+ }
+ }
+
+ return nil, fmt.Errorf("no config file found in %s", dir)
+}
+
+func GetProviderConfig(models *OpenClawModels) map[string]OpenClawProviderConfig {
+ result := make(map[string]OpenClawProviderConfig)
+ if models == nil || models.Providers == nil {
+ return result
+ }
+
+ for name, raw := range models.Providers {
+ var prov OpenClawProviderConfig
+ if err := json.Unmarshal(raw, &prov); err != nil {
+ continue
+ }
+ mappedName := mapProvider(name)
+ result[mappedName] = prov
+ }
+
+ return result
+}
+
+func GetProviderConfigFromDir(dir string) map[string]ProviderConfig {
+ result := make(map[string]ProviderConfig)
+ p := filepath.Join(dir, "agents", "main", "agent", "models.json")
+
+ if _, err := os.Stat(p); err != nil {
+ return result
+ }
+
+ data, err := os.ReadFile(p)
+ if err != nil {
+ return result
+ }
+ var models OpenClawModels
+ if err := json.Unmarshal(data, &models); err != nil {
+ return result
+ }
+
+ for name, raw := range models.Providers {
+ var prov ProviderConfig
+ if err := json.Unmarshal(raw, &prov); err != nil {
+ continue
+ }
+ mappedName := mapProvider(name)
+ result[mappedName] = prov
+ }
+ return result
+}
+
+func (c *OpenClawConfig) IsChannelEnabled(name string) bool {
+ switch name {
+ case "telegram":
+ return c.Channels.Telegram == nil || c.Channels.Telegram.Enabled == nil || *c.Channels.Telegram.Enabled
+ case "discord":
+ return c.Channels.Discord == nil || c.Channels.Discord.Enabled == nil || *c.Channels.Discord.Enabled
+ case "slack":
+ return c.Channels.Slack == nil || c.Channels.Slack.Enabled == nil || *c.Channels.Slack.Enabled
+ case "whatsapp":
+ return c.Channels.WhatsApp == nil || c.Channels.WhatsApp.Enabled == nil || *c.Channels.WhatsApp.Enabled
+ case "feishu":
+ return c.Channels.Feishu == nil || c.Channels.Feishu.Enabled == nil || *c.Channels.Feishu.Enabled
+ default:
+ return false
+ }
+}
+
+func GetChannelAllowFrom(ch any) []string {
+ switch c := ch.(type) {
+ case *OpenClawTelegramConfig:
+ if c == nil {
+ return nil
+ }
+ return c.AllowFrom
+ case *OpenClawDiscordConfig:
+ if c == nil {
+ return nil
+ }
+ return c.AllowFrom
+ case *OpenClawSlackConfig:
+ if c == nil {
+ return nil
+ }
+ return c.AllowFrom
+ case *OpenClawWhatsAppConfig:
+ if c == nil {
+ return nil
+ }
+ return c.AllowFrom
+ case *OpenClawFeishuConfig:
+ if c == nil {
+ return nil
+ }
+ return c.AllowFrom
+ default:
+ return nil
+ }
+}
+
+func (c *OpenClawConfig) GetDefaultModel() (provider, model string) {
+ if c.Agents == nil || c.Agents.Defaults == nil || c.Agents.Defaults.Model == nil {
+ return "anthropic", "claude-sonnet-4-20250514"
+ }
+
+ primary := c.Agents.Defaults.Model.GetPrimary()
+ if primary == "" {
+ return "anthropic", "claude-sonnet-4-20250514"
+ }
+
+ parts := strings.Split(primary, "/")
+ if len(parts) > 1 {
+ return mapProvider(parts[0]), parts[1]
+ }
+
+ return "anthropic", primary
+}
+
+func (c *OpenClawConfig) GetDefaultWorkspace() string {
+ if c.Agents == nil || c.Agents.Defaults == nil || c.Agents.Defaults.Workspace == nil {
+ return ""
+ }
+ return rewriteWorkspacePath(*c.Agents.Defaults.Workspace)
+}
+
+func (c *OpenClawConfig) GetAgents() []OpenClawAgentEntry {
+ if c.Agents == nil {
+ return nil
+ }
+ return c.Agents.List
+}
+
+func (c *OpenClawConfig) HasSkills() bool {
+ return c.Skills != nil && c.Skills.Entries != nil && len(c.Skills.Entries) > 0
+}
+
+func (c *OpenClawConfig) HasMemory() bool {
+ return c.Memory != nil && len(c.Memory) > 0
+}
+
+func (c *OpenClawConfig) HasCron() bool {
+ return c.Cron != nil && len(c.Cron) > 0
+}
+
+func (c *OpenClawConfig) HasHooks() bool {
+ return c.Hooks != nil && len(c.Hooks) > 0
+}
+
+func (c *OpenClawConfig) HasSession() bool {
+ return c.Session != nil && len(c.Session) > 0
+}
+
+func (c *OpenClawConfig) HasAuthProfiles() bool {
+ return c.Auth != nil && c.Auth.Profiles != nil && len(c.Auth.Profiles) > 0
+}
+
+func (c *OpenClawConfig) ConvertToPicoClaw(sourceHome string) (*PicoClawConfig, []string, error) {
+ cfg := &PicoClawConfig{}
+ var warnings []string
+
+ provider, modelName := c.GetDefaultModel()
+ cfg.Agents.Defaults.Workspace = c.GetDefaultWorkspace()
+ cfg.Agents.Defaults.ModelName = modelName
+
+ providerConfigs := GetProviderConfigFromDir(sourceHome)
+ defaultAPIKey := ""
+ defaultBaseURL := ""
+
+ if provCfg, ok := providerConfigs[provider]; ok {
+ defaultAPIKey = provCfg.ApiKey
+ defaultBaseURL = provCfg.BaseUrl
+ }
+
+ cfg.ModelList = []ModelConfig{
+ {
+ ModelName: modelName,
+ Model: fmt.Sprintf("%s/%s", provider, modelName),
+ APIKey: defaultAPIKey,
+ APIBase: defaultBaseURL,
+ },
+ }
+
+ for provName, provCfg := range providerConfigs {
+ if provName == provider {
+ continue
+ }
+ if provCfg.ApiKey != "" {
+ continue
+ }
+ cfg.ModelList = append(cfg.ModelList, ModelConfig{
+ ModelName: fmt.Sprintf("%s", provName),
+ Model: fmt.Sprintf("%s/%s", provName, provName),
+ APIKey: provCfg.ApiKey,
+ APIBase: provCfg.BaseUrl,
+ })
+ }
+
+ cfg.Channels = c.convertChannels(&warnings)
+
+ agentList := c.convertAgents(&warnings)
+ if len(agentList) > 0 {
+ cfg.Agents.List = agentList
+ }
+
+ if c.HasSkills() {
+ warnings = append(
+ warnings,
+ fmt.Sprintf(
+ "Skills (%d entries) not automatically migrated - reinstall via picoclaw CLI",
+ len(c.Skills.Entries),
+ ),
+ )
+ }
+ if c.HasMemory() {
+ warnings = append(warnings, "Memory backend config not migrated - PicoClaw uses SQLite with vector embeddings")
+ }
+ if c.HasCron() {
+ warnings = append(
+ warnings,
+ "Cron job scheduling not supported in PicoClaw - consider using external schedulers",
+ )
+ }
+ if c.HasHooks() {
+ warnings = append(warnings, "Webhook hooks not supported in PicoClaw - use event system instead")
+ }
+ if c.HasSession() {
+ warnings = append(warnings, "Session scope config differs - PicoClaw uses per-agent sessions by default")
+ }
+ if c.HasAuthProfiles() {
+ warnings = append(
+ warnings,
+ "Auth profiles (API keys, OAuth tokens) not migrated for security - set env vars manually",
+ )
+ }
+
+ return cfg, warnings, nil
+}
+
+type ModelConfig struct {
+ ModelName string `json:"model_name"`
+ Model string `json:"model"`
+ APIBase string `json:"api_base,omitempty"`
+ APIKey string `json:"api_key"`
+ Proxy string `json:"proxy,omitempty"`
+}
+
+type PicoClawConfig struct {
+ Agents AgentsConfig `json:"agents"`
+ Bindings []AgentBinding `json:"bindings,omitempty"`
+ Channels ChannelsConfig `json:"channels"`
+ ModelList []ModelConfig `json:"model_list"`
+ Gateway GatewayConfig `json:"gateway"`
+ Tools ToolsConfig `json:"tools"`
+}
+
+type AgentsConfig struct {
+ Defaults AgentDefaults `json:"defaults"`
+ List []AgentConfig `json:"list,omitempty"`
+}
+
+type AgentDefaults struct {
+ Workspace string `json:"workspace"`
+ RestrictToWorkspace bool `json:"restrict_to_workspace"`
+ Provider string `json:"provider"`
+ ModelName string `json:"model_name"`
+ Model string `json:"model,omitempty"`
+ ModelFallbacks []string `json:"model_fallbacks,omitempty"`
+ ImageModel string `json:"image_model,omitempty"`
+ ImageModelFallbacks []string `json:"image_model_fallbacks,omitempty"`
+ MaxTokens int `json:"max_tokens"`
+ Temperature *float64 `json:"temperature,omitempty"`
+ MaxToolIterations int `json:"max_tool_iterations"`
+}
+
+type AgentConfig struct {
+ ID string `json:"id"`
+ Default bool `json:"default,omitempty"`
+ Name string `json:"name,omitempty"`
+ Workspace string `json:"workspace,omitempty"`
+ Model *AgentModelConfig `json:"model,omitempty"`
+ Skills []string `json:"skills,omitempty"`
+}
+
+type AgentModelConfig struct {
+ Primary string `json:"primary,omitempty"`
+ Fallbacks []string `json:"fallbacks,omitempty"`
+}
+
+type AgentBinding struct {
+ AgentID string `json:"agent_id"`
+ Match BindingMatch `json:"match"`
+}
+
+type BindingMatch struct {
+ Channel string `json:"channel"`
+ AccountID string `json:"account_id,omitempty"`
+ Peer *PeerMatch `json:"peer,omitempty"`
+ GuildID string `json:"guild_id,omitempty"`
+ TeamID string `json:"team_id,omitempty"`
+}
+
+type PeerMatch struct {
+ Kind string `json:"kind"`
+ ID string `json:"id"`
+}
+
+type ChannelsConfig struct {
+ WhatsApp WhatsAppConfig `json:"whatsapp"`
+ Telegram TelegramConfig `json:"telegram"`
+ Feishu FeishuConfig `json:"feishu"`
+ Discord DiscordConfig `json:"discord"`
+ MaixCam MaixCamConfig `json:"maixcam"`
+ QQ QQConfig `json:"qq"`
+ DingTalk DingTalkConfig `json:"dingtalk"`
+ Slack SlackConfig `json:"slack"`
+ LINE LINEConfig `json:"line"`
+}
+
+type WhatsAppConfig struct {
+ Enabled bool `json:"enabled"`
+ BridgeURL string `json:"bridge_url"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type TelegramConfig struct {
+ Enabled bool `json:"enabled"`
+ Token string `json:"token"`
+ Proxy string `json:"proxy"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type FeishuConfig struct {
+ Enabled bool `json:"enabled"`
+ AppID string `json:"app_id"`
+ AppSecret string `json:"app_secret"`
+ EncryptKey string `json:"encrypt_key"`
+ VerificationToken string `json:"verification_token"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type DiscordConfig struct {
+ Enabled bool `json:"enabled"`
+ Token string `json:"token"`
+ MentionOnly bool `json:"mention_only"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type MaixCamConfig struct {
+ Enabled bool `json:"enabled"`
+ Host string `json:"host"`
+ Port int `json:"port"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type QQConfig struct {
+ Enabled bool `json:"enabled"`
+ AppID string `json:"app_id"`
+ AppSecret string `json:"app_secret"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type DingTalkConfig struct {
+ Enabled bool `json:"enabled"`
+ ClientID string `json:"client_id"`
+ ClientSecret string `json:"client_secret"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type SlackConfig struct {
+ Enabled bool `json:"enabled"`
+ BotToken string `json:"bot_token"`
+ AppToken string `json:"app_token"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type LINEConfig struct {
+ Enabled bool `json:"enabled"`
+ ChannelSecret string `json:"channel_secret"`
+ ChannelAccessToken string `json:"channel_access_token"`
+ WebhookHost string `json:"webhook_host"`
+ WebhookPort int `json:"webhook_port"`
+ WebhookPath string `json:"webhook_path"`
+ AllowFrom []string `json:"allow_from"`
+}
+
+type GatewayConfig struct {
+ Host string `json:"host"`
+ Port int `json:"port"`
+}
+
+type ToolsConfig struct {
+ Web WebToolsConfig `json:"web"`
+ Cron CronConfig `json:"cron"`
+ Exec ExecConfig `json:"exec"`
+}
+
+type WebToolsConfig struct {
+ Brave BraveConfig `json:"brave"`
+ Tavily TavilyConfig `json:"tavily"`
+ DuckDuckGo DuckDuckGoConfig `json:"duckduckgo"`
+ Perplexity PerplexityConfig `json:"perplexity"`
+ Proxy string `json:"proxy,omitempty"`
+}
+
+type BraveConfig struct {
+ Enabled bool `json:"enabled"`
+ APIKey string `json:"api_key"`
+ MaxResults int `json:"max_results"`
+}
+
+type TavilyConfig struct {
+ Enabled bool `json:"enabled"`
+ APIKey string `json:"api_key"`
+ BaseURL string `json:"base_url"`
+ MaxResults int `json:"max_results"`
+}
+
+type DuckDuckGoConfig struct {
+ Enabled bool `json:"enabled"`
+ MaxResults int `json:"max_results"`
+}
+
+type PerplexityConfig struct {
+ Enabled bool `json:"enabled"`
+ APIKey string `json:"api_key"`
+ MaxResults int `json:"max_results"`
+}
+
+type CronConfig struct {
+ ExecTimeoutMinutes int `json:"exec_timeout_minutes"`
+}
+
+type ExecConfig struct {
+ EnableDenyPatterns bool `json:"enable_deny_patterns"`
+ CustomDenyPatterns []string `json:"custom_deny_patterns"`
+}
+
+func (c *OpenClawConfig) convertChannels(warnings *[]string) ChannelsConfig {
+ channels := ChannelsConfig{}
+
+ if c.Channels == nil {
+ return channels
+ }
+
+ if c.Channels.Telegram != nil {
+ enabled := c.Channels.Telegram.Enabled == nil || *c.Channels.Telegram.Enabled
+ channels.Telegram = TelegramConfig{
+ Enabled: enabled,
+ AllowFrom: c.Channels.Telegram.AllowFrom,
+ }
+ if c.Channels.Telegram.BotToken != nil {
+ channels.Telegram.Token = *c.Channels.Telegram.BotToken
+ }
+ }
+
+ if c.Channels.Discord != nil {
+ enabled := c.Channels.Discord.Enabled == nil || *c.Channels.Discord.Enabled
+ channels.Discord = DiscordConfig{
+ Enabled: enabled,
+ AllowFrom: c.Channels.Discord.AllowFrom,
+ }
+ if c.Channels.Discord.Token != nil {
+ channels.Discord.Token = *c.Channels.Discord.Token
+ }
+ }
+
+ if c.Channels.Slack != nil {
+ enabled := c.Channels.Slack.Enabled == nil || *c.Channels.Slack.Enabled
+ channels.Slack = SlackConfig{
+ Enabled: enabled,
+ AllowFrom: c.Channels.Slack.AllowFrom,
+ }
+ if c.Channels.Slack.BotToken != nil {
+ channels.Slack.BotToken = *c.Channels.Slack.BotToken
+ }
+ if c.Channels.Slack.AppToken != nil {
+ channels.Slack.AppToken = *c.Channels.Slack.AppToken
+ }
+ }
+
+ if c.Channels.WhatsApp != nil {
+ enabled := c.Channels.WhatsApp.Enabled == nil || *c.Channels.WhatsApp.Enabled
+ channels.WhatsApp = WhatsAppConfig{
+ Enabled: enabled,
+ AllowFrom: c.Channels.WhatsApp.AllowFrom,
+ }
+ if c.Channels.WhatsApp.BridgeURL != nil {
+ channels.WhatsApp.BridgeURL = *c.Channels.WhatsApp.BridgeURL
+ }
+ }
+
+ if c.Channels.Feishu != nil {
+ enabled := c.Channels.Feishu.Enabled == nil || *c.Channels.Feishu.Enabled
+ channels.Feishu = FeishuConfig{
+ Enabled: enabled,
+ AllowFrom: c.Channels.Feishu.AllowFrom,
+ }
+ if c.Channels.Feishu.AppID != nil {
+ channels.Feishu.AppID = *c.Channels.Feishu.AppID
+ }
+ if c.Channels.Feishu.AppSecret != nil {
+ channels.Feishu.AppSecret = *c.Channels.Feishu.AppSecret
+ }
+ if c.Channels.Feishu.EncryptKey != nil {
+ channels.Feishu.EncryptKey = *c.Channels.Feishu.EncryptKey
+ }
+ if c.Channels.Feishu.VerificationToken != nil {
+ channels.Feishu.VerificationToken = *c.Channels.Feishu.VerificationToken
+ }
+ }
+
+ if c.Channels.QQ != nil && supportedChannels["qq"] {
+ channels.QQ = QQConfig{
+ Enabled: true,
+ AllowFrom: c.Channels.QQ.AllowFrom,
+ }
+ if c.Channels.QQ.AppID != nil {
+ channels.QQ.AppID = *c.Channels.QQ.AppID
+ }
+ if c.Channels.QQ.AppSecret != nil {
+ channels.QQ.AppSecret = *c.Channels.QQ.AppSecret
+ }
+ }
+
+ if c.Channels.DingTalk != nil && supportedChannels["dingtalk"] {
+ channels.DingTalk = DingTalkConfig{
+ Enabled: true,
+ AllowFrom: c.Channels.DingTalk.AllowFrom,
+ }
+ if c.Channels.DingTalk.AppID != nil {
+ channels.DingTalk.ClientID = *c.Channels.DingTalk.AppID
+ }
+ if c.Channels.DingTalk.AppSecret != nil {
+ channels.DingTalk.ClientSecret = *c.Channels.DingTalk.AppSecret
+ }
+ }
+
+ if c.Channels.MaixCam != nil && supportedChannels["maixcam"] {
+ channels.MaixCam = MaixCamConfig{
+ Enabled: true,
+ AllowFrom: c.Channels.MaixCam.AllowFrom,
+ }
+ if c.Channels.MaixCam.Host != nil {
+ channels.MaixCam.Host = *c.Channels.MaixCam.Host
+ }
+ if c.Channels.MaixCam.Port != nil {
+ channels.MaixCam.Port = *c.Channels.MaixCam.Port
+ }
+ }
+
+ if c.Channels.Signal != nil {
+ *warnings = append(*warnings, "Channel 'signal': No PicoClaw adapter available")
+ }
+ if c.Channels.Matrix != nil {
+ *warnings = append(*warnings, "Channel 'matrix': No PicoClaw adapter available")
+ }
+ if c.Channels.IRC != nil {
+ *warnings = append(*warnings, "Channel 'irc': No PicoClaw adapter available")
+ }
+ if c.Channels.Mattermost != nil {
+ *warnings = append(*warnings, "Channel 'mattermost': No PicoClaw adapter available")
+ }
+ if c.Channels.IMessage != nil {
+ *warnings = append(*warnings, "Channel 'imessage': macOS-only channel - requires manual setup")
+ }
+ if c.Channels.BlueBubbles != nil {
+ *warnings = append(
+ *warnings,
+ "Channel 'bluebubbles': No PicoClaw adapter available - consider iMessage instead",
+ )
+ }
+
+ return channels
+}
+
+func (c *OpenClawConfig) convertAgents(warnings *[]string) []AgentConfig {
+ var agents []AgentConfig
+
+ if c.Agents == nil {
+ return agents
+ }
+
+ for _, entry := range c.Agents.List {
+ agentID := entry.ID
+ if agentID == "" {
+ continue
+ }
+
+ agentName := agentID
+ if entry.Name != nil {
+ agentName = *entry.Name
+ }
+
+ agentCfg := AgentConfig{
+ ID: agentID,
+ Name: agentName,
+ Default: len(agents) == 0,
+ }
+
+ if entry.Workspace != nil {
+ agentCfg.Workspace = rewriteWorkspacePath(*entry.Workspace)
+ }
+
+ if entry.Model != nil {
+ primary := entry.Model.GetPrimary()
+ if primary != "" {
+ agentCfg.Model = &AgentModelConfig{
+ Primary: primary,
+ Fallbacks: entry.Model.GetFallbacks(),
+ }
+ }
+ }
+
+ if len(entry.Skills) > 0 {
+ agentCfg.Skills = entry.Skills
+ }
+
+ agents = append(agents, agentCfg)
+ }
+
+ return agents
+}
+
+func (c *PicoClawConfig) ToStandardConfig() *config.Config {
+ cfg := config.DefaultConfig()
+
+ cfg.Agents.Defaults.Workspace = c.Agents.Defaults.Workspace
+ cfg.Agents.Defaults.Provider = c.Agents.Defaults.Provider
+ cfg.Agents.Defaults.ModelName = c.Agents.Defaults.ModelName
+ cfg.Agents.Defaults.ModelFallbacks = c.Agents.Defaults.ModelFallbacks
+
+ for _, m := range c.ModelList {
+ cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+ ModelName: m.ModelName,
+ Model: m.Model,
+ APIBase: m.APIBase,
+ APIKey: m.APIKey,
+ Proxy: m.Proxy,
+ })
+ }
+
+ cfg.Channels = c.Channels.ToStandardChannels()
+ cfg.Gateway = c.Gateway.ToStandardGateway()
+ cfg.Tools = c.Tools.ToStandardTools()
+
+ cfg.Agents.List = make([]config.AgentConfig, len(c.Agents.List))
+ for i, a := range c.Agents.List {
+ cfg.Agents.List[i] = config.AgentConfig{
+ ID: a.ID,
+ Default: a.Default,
+ Name: a.Name,
+ Workspace: a.Workspace,
+ Skills: a.Skills,
+ }
+ if a.Model != nil {
+ cfg.Agents.List[i].Model = &config.AgentModelConfig{
+ Primary: a.Model.Primary,
+ Fallbacks: a.Model.Fallbacks,
+ }
+ }
+ }
+
+ return cfg
+}
+
+func (c ChannelsConfig) ToStandardChannels() config.ChannelsConfig {
+ return config.ChannelsConfig{
+ WhatsApp: config.WhatsAppConfig{
+ 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,
+ },
+ 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,
+ },
+ 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,
+ },
+ }
+}
+
+func (c GatewayConfig) ToStandardGateway() config.GatewayConfig {
+ return config.GatewayConfig{
+ Host: c.Host,
+ Port: c.Port,
+ }
+}
+
+func (c ToolsConfig) ToStandardTools() config.ToolsConfig {
+ return config.ToolsConfig{
+ Web: config.WebToolsConfig{
+ Brave: config.BraveConfig{
+ Enabled: c.Web.Brave.Enabled,
+ APIKey: c.Web.Brave.APIKey,
+ 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,
+ },
+ 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,
+ },
+ Cron: config.CronToolsConfig{
+ ExecTimeoutMinutes: c.Cron.ExecTimeoutMinutes,
+ },
+ Exec: config.ExecConfig{
+ EnableDenyPatterns: c.Exec.EnableDenyPatterns,
+ CustomDenyPatterns: c.Exec.CustomDenyPatterns,
+ },
+ }
+}
diff --git a/pkg/migrate/sources/openclaw/openclaw_config_test.go b/pkg/migrate/sources/openclaw/openclaw_config_test.go
new file mode 100644
index 000000000..7d884522c
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/openclaw_config_test.go
@@ -0,0 +1,714 @@
+package openclaw
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+func TestLoadOpenClawConfig(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+
+ testConfig := `{
+ "agents": {
+ "defaults": {
+ "model": {
+ "primary": "anthropic/claude-sonnet-4-20250514"
+ },
+ "workspace": "~/.openclaw/workspace"
+ },
+ "list": [
+ {
+ "id": "main",
+ "name": "Main Agent",
+ "model": {
+ "primary": "openai/gpt-4o",
+ "fallbacks": ["claude-3-opus"]
+ }
+ }
+ ]
+ },
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "botToken": "test-token",
+ "allowFrom": ["user1", "user2"]
+ },
+ "discord": {
+ "enabled": true,
+ "token": "discord-token"
+ }
+ },
+ "models": {
+ "providers": {
+ "anthropic": {
+ "api_key": "sk-ant-test",
+ "base_url": "https://api.anthropic.com"
+ },
+ "openai": {
+ "api_key": "sk-test"
+ }
+ }
+ }
+ }`
+
+ err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+ if err != nil {
+ t.Fatalf("failed to write test config: %v", err)
+ }
+
+ cfg, err := LoadOpenClawConfig(configPath)
+ if err != nil {
+ t.Fatalf("failed to load config: %v", err)
+ }
+
+ if cfg.Agents == nil {
+ t.Error("agents should not be nil")
+ }
+
+ if cfg.Agents.Defaults == nil {
+ t.Error("agents.defaults should not be nil")
+ }
+
+ provider, model := cfg.GetDefaultModel()
+ if provider != "anthropic" {
+ t.Errorf("expected provider 'anthropic', got '%s'", provider)
+ }
+ if model != "claude-sonnet-4-20250514" {
+ t.Errorf("expected model 'claude-sonnet-4-20250514', got '%s'", model)
+ }
+
+ workspace := cfg.GetDefaultWorkspace()
+ if workspace != "~/.picoclaw/workspace" {
+ t.Errorf("expected workspace '~/.picoclaw/workspace', got '%s'", workspace)
+ }
+
+ agents := cfg.GetAgents()
+ if len(agents) != 1 {
+ t.Errorf("expected 1 agent, got %d", len(agents))
+ }
+ if agents[0].ID != "main" {
+ t.Errorf("expected agent id 'main', got '%s'", agents[0].ID)
+ }
+
+ if cfg.Channels == nil {
+ t.Error("channels should not be nil")
+ }
+ if cfg.Channels.Telegram == nil {
+ t.Error("telegram channel should not be nil")
+ }
+ if cfg.Channels.Telegram.BotToken == nil || *cfg.Channels.Telegram.BotToken != "test-token" {
+ t.Error("telegram bot token not parsed correctly")
+ }
+}
+
+func TestGetProviderConfig(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+
+ testConfig := `{
+ "models": {
+ "providers": {
+ "anthropic": {
+ "api_key": "sk-ant-test",
+ "base_url": "https://api.anthropic.com",
+ "max_tokens": 4096
+ },
+ "openai": {
+ "api_key": "sk-test",
+ "base_url": "https://api.openai.com"
+ }
+ }
+ }
+ }`
+
+ err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+ if err != nil {
+ t.Fatalf("failed to write test config: %v", err)
+ }
+
+ cfg, err := LoadOpenClawConfig(configPath)
+ if err != nil {
+ t.Fatalf("failed to load config: %v", err)
+ }
+
+ providers := GetProviderConfig(cfg.Models)
+ if len(providers) != 2 {
+ t.Errorf("expected 2 providers, got %d", len(providers))
+ }
+
+ if anthropic, ok := providers["anthropic"]; ok {
+ if anthropic.APIKey != "sk-ant-test" {
+ t.Errorf("expected anthropic api_key 'sk-ant-test', got '%s'", anthropic.APIKey)
+ }
+ if anthropic.BaseURL != "https://api.anthropic.com" {
+ t.Errorf("expected anthropic base_url 'https://api.anthropic.com', got '%s'", anthropic.BaseURL)
+ }
+ } else {
+ t.Error("anthropic provider not found")
+ }
+
+ if openai, ok := providers["openai"]; ok {
+ if openai.APIKey != "sk-test" {
+ t.Errorf("expected openai api_key 'sk-test', got '%s'", openai.APIKey)
+ }
+ } else {
+ t.Error("openai provider not found")
+ }
+}
+
+func TestConvertToPicoClaw(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+
+ testConfig := `{
+ "agents": {
+ "defaults": {
+ "model": {
+ "primary": "anthropic/claude-sonnet-4-20250514"
+ },
+ "workspace": "~/.openclaw/workspace"
+ },
+ "list": [
+ {
+ "id": "main",
+ "name": "Main Agent"
+ },
+ {
+ "id": "assistant",
+ "name": "Assistant",
+ "skills": ["skill1", "skill2"]
+ }
+ ]
+ },
+ "channels": {
+ "telegram": {
+ "enabled": true,
+ "botToken": "test-token",
+ "allowFrom": ["user1", "user2"]
+ },
+ "discord": {
+ "enabled": false,
+ "token": "discord-token"
+ },
+ "whatsapp": {
+ "enabled": true,
+ "bridgeUrl": "http://localhost:3000"
+ },
+ "feishu": {
+ "enabled": true,
+ "appId": "app-id",
+ "appSecret": "app-secret",
+ "allowFrom": ["user3"]
+ },
+ "signal": {
+ "enabled": true
+ }
+ },
+ "models": {
+ "providers": {
+ "anthropic": {
+ "api_key": "sk-ant-test"
+ },
+ "openai": {
+ "api_key": "sk-test"
+ }
+ }
+ },
+ "skills": {
+ "entries": {
+ "skill1": {}
+ }
+ },
+ "memory": {"enabled": true},
+ "cron": {"enabled": true}
+ }`
+
+ err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+ if err != nil {
+ t.Fatalf("failed to write test config: %v", err)
+ }
+
+ cfg, err := LoadOpenClawConfig(configPath)
+ if err != nil {
+ t.Fatalf("failed to load config: %v", err)
+ }
+
+ picoCfg, warnings, err := cfg.ConvertToPicoClaw("")
+ if err != nil {
+ t.Fatalf("failed to convert config: %v", err)
+ }
+
+ if picoCfg.Agents.Defaults.ModelName != "claude-sonnet-4-20250514" {
+ t.Errorf("expected model 'claude-sonnet-4-20250514', got '%s'", picoCfg.Agents.Defaults.ModelName)
+ }
+ if picoCfg.Agents.Defaults.Workspace != "~/.picoclaw/workspace" {
+ t.Errorf("expected workspace '~/.picoclaw/workspace', got '%s'", picoCfg.Agents.Defaults.Workspace)
+ }
+
+ if len(picoCfg.Agents.List) != 2 {
+ t.Errorf("expected 2 agents, got %d", len(picoCfg.Agents.List))
+ }
+ if picoCfg.Agents.List[0].ID != "main" {
+ t.Errorf("expected first agent id 'main', got '%s'", picoCfg.Agents.List[0].ID)
+ }
+ if picoCfg.Agents.List[1].Skills == nil || len(picoCfg.Agents.List[1].Skills) != 2 {
+ t.Errorf("expected 2 skills for assistant agent")
+ }
+
+ if !picoCfg.Channels.Telegram.Enabled {
+ t.Error("telegram should be enabled")
+ }
+ if picoCfg.Channels.Telegram.Token != "test-token" {
+ t.Errorf("expected telegram token 'test-token', got '%s'", picoCfg.Channels.Telegram.Token)
+ }
+
+ if picoCfg.Channels.WhatsApp.BridgeURL != "http://localhost:3000" {
+ t.Errorf("expected whatsapp bridge URL 'http://localhost:3000', got '%s'", picoCfg.Channels.WhatsApp.BridgeURL)
+ }
+
+ if picoCfg.Channels.Feishu.AppID != "app-id" {
+ t.Errorf("expected feishu app ID 'app-id', got '%s'", picoCfg.Channels.Feishu.AppID)
+ }
+
+ if len(picoCfg.ModelList) != 1 {
+ t.Errorf("expected 1 model config (no models.json provided), got %d", len(picoCfg.ModelList))
+ }
+
+ foundWarning := false
+ for _, w := range warnings {
+ if len(w) > 0 {
+ foundWarning = true
+ break
+ }
+ }
+ if !foundWarning {
+ t.Log("warnings should be generated for skills, memory, cron, and unsupported channels")
+ }
+}
+
+func TestConvertToPicoClawWithQQAndDingTalk(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+
+ testConfig := `{
+ "agents": {
+ "defaults": {
+ "model": {
+ "primary": "anthropic/claude-sonnet-4-20250514"
+ }
+ }
+ },
+ "channels": {
+ "qq": {
+ "enabled": true,
+ "appId": "qq-app-id",
+ "appSecret": "qq-app-secret"
+ },
+ "dingtalk": {
+ "enabled": true,
+ "appId": "ding-app-id",
+ "appSecret": "ding-app-secret"
+ },
+ "maixcam": {
+ "enabled": true,
+ "host": "192.168.1.100",
+ "port": 9000
+ },
+ "slack": {
+ "enabled": true,
+ "botToken": "xoxb-test",
+ "appToken": "xapp-test"
+ }
+ }
+ }`
+
+ err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+ if err != nil {
+ t.Fatalf("failed to write test config: %v", err)
+ }
+
+ cfg, err := LoadOpenClawConfig(configPath)
+ if err != nil {
+ t.Fatalf("failed to load config: %v", err)
+ }
+
+ picoCfg, _, err := cfg.ConvertToPicoClaw("")
+ if err != nil {
+ t.Fatalf("failed to convert config: %v", err)
+ }
+
+ if !picoCfg.Channels.QQ.Enabled {
+ t.Error("qq should be enabled")
+ }
+ if picoCfg.Channels.QQ.AppID != "qq-app-id" {
+ t.Errorf("expected qq app ID 'qq-app-id', got '%s'", picoCfg.Channels.QQ.AppID)
+ }
+
+ if !picoCfg.Channels.DingTalk.Enabled {
+ t.Error("dingtalk should be enabled")
+ }
+ if picoCfg.Channels.DingTalk.ClientID != "ding-app-id" {
+ t.Errorf("expected dingtalk client ID 'ding-app-id', got '%s'", picoCfg.Channels.DingTalk.ClientID)
+ }
+
+ if !picoCfg.Channels.MaixCam.Enabled {
+ t.Error("maixcam should be enabled")
+ }
+ if picoCfg.Channels.MaixCam.Host != "192.168.1.100" {
+ t.Errorf("expected maixcam host '192.168.1.100', got '%s'", picoCfg.Channels.MaixCam.Host)
+ }
+ if picoCfg.Channels.MaixCam.Port != 9000 {
+ t.Errorf("expected maixcam port 9000, got %d", picoCfg.Channels.MaixCam.Port)
+ }
+
+ if !picoCfg.Channels.Slack.Enabled {
+ t.Error("slack should be enabled")
+ }
+ if picoCfg.Channels.Slack.BotToken != "xoxb-test" {
+ t.Errorf("expected slack bot token 'xoxb-test', got '%s'", picoCfg.Channels.Slack.BotToken)
+ }
+ if picoCfg.Channels.Slack.AppToken != "xapp-test" {
+ t.Errorf("expected slack app token 'xapp-test', got '%s'", picoCfg.Channels.Slack.AppToken)
+ }
+}
+
+func TestOpenClawAgentModel(t *testing.T) {
+ model := &OpenClawAgentModel{
+ Primary: strPtr("anthropic/claude-3-opus"),
+ Fallbacks: []string{"claude-3-sonnet", "claude-3-haiku"},
+ }
+
+ primary := model.GetPrimary()
+ if primary != "anthropic/claude-3-opus" {
+ t.Errorf("expected primary 'anthropic/claude-3-opus', got '%s'", primary)
+ }
+
+ fallbacks := model.GetFallbacks()
+ if len(fallbacks) != 2 {
+ t.Errorf("expected 2 fallbacks, got %d", len(fallbacks))
+ }
+
+ model2 := &OpenClawAgentModel{
+ Simple: "claude-3-opus",
+ }
+
+ primary2 := model2.GetPrimary()
+ if primary2 != "claude-3-opus" {
+ t.Errorf("expected primary 'claude-3-opus' from Simple, got '%s'", primary2)
+ }
+}
+
+func TestChannelEnabled(t *testing.T) {
+ cfg := &OpenClawConfig{
+ Channels: &OpenClawChannels{
+ Telegram: &OpenClawTelegramConfig{
+ Enabled: boolPtr(true),
+ },
+ Discord: &OpenClawDiscordConfig{
+ Enabled: boolPtr(false),
+ },
+ Slack: &OpenClawSlackConfig{
+ Enabled: boolPtr(true),
+ },
+ },
+ }
+
+ if !cfg.IsChannelEnabled("telegram") {
+ t.Error("telegram should be enabled")
+ }
+ if cfg.IsChannelEnabled("discord") {
+ t.Error("discord should be disabled")
+ }
+ if !cfg.IsChannelEnabled("slack") {
+ t.Error("slack should be enabled (explicitly set)")
+ }
+ if cfg.IsChannelEnabled("line") {
+ t.Error("line should return false (not in switch cases)")
+ }
+}
+
+func TestGetDefaultModel(t *testing.T) {
+ cfg := &OpenClawConfig{
+ Agents: &OpenClawAgents{
+ Defaults: &OpenClawAgentDefaults{
+ Model: &OpenClawAgentModel{
+ Primary: strPtr("openai/gpt-4"),
+ },
+ },
+ },
+ }
+
+ provider, model := cfg.GetDefaultModel()
+ if provider != "openai" {
+ t.Errorf("expected provider 'openai', got '%s'", provider)
+ }
+ if model != "gpt-4" {
+ t.Errorf("expected model 'gpt-4', got '%s'", model)
+ }
+}
+
+func TestGetDefaultModelWithNoDefaults(t *testing.T) {
+ cfg := &OpenClawConfig{}
+
+ provider, model := cfg.GetDefaultModel()
+ if provider != "anthropic" {
+ t.Errorf("expected default provider 'anthropic', got '%s'", provider)
+ }
+ if model != "claude-sonnet-4-20250514" {
+ t.Errorf("expected default model 'claude-sonnet-4-20250514', got '%s'", model)
+ }
+}
+
+func TestHasFunctions(t *testing.T) {
+ cfg := &OpenClawConfig{
+ Skills: &OpenClawSkills{Entries: map[string]json.RawMessage{"skill1": nil}},
+ Memory: json.RawMessage(`{"enabled": true}`),
+ Cron: json.RawMessage(`{"enabled": true}`),
+ Hooks: json.RawMessage(`{"enabled": true}`),
+ Session: json.RawMessage(`{"enabled": true}`),
+ Auth: &OpenClawAuth{Profiles: json.RawMessage(`{"profile1": {}}`)},
+ }
+
+ if !cfg.HasSkills() {
+ t.Error("should have skills")
+ }
+ if !cfg.HasMemory() {
+ t.Error("should have memory")
+ }
+ if !cfg.HasCron() {
+ t.Error("should have cron")
+ }
+ if !cfg.HasHooks() {
+ t.Error("should have hooks")
+ }
+ if !cfg.HasSession() {
+ t.Error("should have session")
+ }
+ if !cfg.HasAuthProfiles() {
+ t.Error("should have auth profiles")
+ }
+
+ cfg2 := &OpenClawConfig{}
+ if cfg2.HasSkills() {
+ t.Error("should not have skills")
+ }
+ if cfg2.HasMemory() {
+ t.Error("should not have memory")
+ }
+}
+
+func TestLoadOpenClawConfigFromDir(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+
+ testConfig := `{"agents": {}}`
+ err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+ if err != nil {
+ t.Fatalf("failed to write test config: %v", err)
+ }
+
+ cfg, err := LoadOpenClawConfigFromDir(tmpDir)
+ if err != nil {
+ t.Fatalf("failed to load config from dir: %v", err)
+ }
+
+ if cfg.Agents == nil {
+ t.Error("agents should not be nil")
+ }
+
+ _, err = LoadOpenClawConfigFromDir("/nonexistent/dir")
+ if err == nil {
+ t.Error("should return error for nonexistent dir")
+ }
+}
+
+func TestToStandardConfig(t *testing.T) {
+ picoCfg := &PicoClawConfig{
+ Agents: AgentsConfig{
+ Defaults: AgentDefaults{
+ Provider: "anthropic",
+ ModelName: "claude-sonnet-4-20250514",
+ Workspace: "~/.picoclaw/workspace",
+ },
+ List: []AgentConfig{
+ {
+ ID: "main",
+ Name: "Main Agent",
+ Default: true,
+ },
+ },
+ },
+ ModelList: []ModelConfig{
+ {
+ ModelName: "claude-sonnet-4-20250514",
+ Model: "anthropic/claude-sonnet-4-20250514",
+ APIKey: "sk-ant-test",
+ },
+ },
+ Channels: ChannelsConfig{
+ Telegram: TelegramConfig{
+ Enabled: true,
+ Token: "test-token",
+ AllowFrom: []string{"user1"},
+ },
+ WhatsApp: WhatsAppConfig{
+ Enabled: true,
+ BridgeURL: "http://localhost:3000",
+ },
+ },
+ Gateway: GatewayConfig{
+ Host: "0.0.0.0",
+ Port: 8080,
+ },
+ }
+
+ stdCfg := picoCfg.ToStandardConfig()
+
+ if stdCfg.Agents.Defaults.Provider != "anthropic" {
+ t.Errorf("expected provider 'anthropic', got '%s'", stdCfg.Agents.Defaults.Provider)
+ }
+ if stdCfg.Agents.Defaults.ModelName != "claude-sonnet-4-20250514" {
+ t.Errorf("expected model name 'claude-sonnet-4-20250514', got '%s'", stdCfg.Agents.Defaults.ModelName)
+ }
+ if stdCfg.Agents.Defaults.Workspace != "~/.picoclaw/workspace" {
+ t.Errorf("expected workspace '~/.picoclaw/workspace', got '%s'", stdCfg.Agents.Defaults.Workspace)
+ }
+
+ if len(stdCfg.Agents.List) != 1 {
+ t.Errorf("expected 1 agent, got %d", len(stdCfg.Agents.List))
+ }
+ if stdCfg.Agents.List[0].ID != "main" {
+ t.Errorf("expected agent id 'main', got '%s'", stdCfg.Agents.List[0].ID)
+ }
+
+ foundModel := false
+ var foundAPIKey string
+ for _, m := range stdCfg.ModelList {
+ if m.ModelName == "claude-sonnet-4-20250514" {
+ foundModel = true
+ foundAPIKey = m.APIKey
+ break
+ }
+ }
+ if !foundModel {
+ t.Error("expected to find claude-sonnet-4-20250514 model config")
+ }
+ if foundAPIKey != "sk-ant-test" {
+ t.Errorf("expected api key 'sk-ant-test', got '%s'", foundAPIKey)
+ }
+
+ 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.Gateway.Port != 8080 {
+ t.Errorf("expected gateway port 8080, got %d", stdCfg.Gateway.Port)
+ }
+}
+
+func TestLoadProviderConfigFromAgentsDir(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ agentsDir := filepath.Join(tmpDir, "agents", "main", "agent")
+ err := os.MkdirAll(agentsDir, 0o755)
+ if err != nil {
+ t.Fatalf("failed to create agents dir: %v", err)
+ }
+
+ modelsJSON := `{
+ "providers": {
+ "anthropic": {
+ "baseUrl": "https://api.anthropic.com",
+ "api": "anthropic",
+ "apiKey": "sk-ant-from-models",
+ "models": [
+ {
+ "id": "claude-sonnet-4-20250514",
+ "name": "Claude Sonnet 4"
+ }
+ ]
+ },
+ "openai": {
+ "baseUrl": "https://api.openai.com",
+ "api": "openai",
+ "apiKey": "sk-from-models",
+ "models": [
+ {
+ "id": "gpt-4o",
+ "name": "GPT-4o"
+ }
+ ]
+ },
+ "zhipu": {
+ "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
+ "api": "openai",
+ "apiKey": "zhipu-key",
+ "models": []
+ }
+ }
+ }`
+
+ err = os.WriteFile(filepath.Join(agentsDir, "models.json"), []byte(modelsJSON), 0o644)
+ if err != nil {
+ t.Fatalf("failed to write models.json: %v", err)
+ }
+
+ providers := GetProviderConfigFromDir(tmpDir)
+ if len(providers) != 3 {
+ t.Errorf("expected 3 providers, got %d", len(providers))
+ }
+
+ if anthropic, ok := providers["anthropic"]; ok {
+ if anthropic.ApiKey != "sk-ant-from-models" {
+ t.Errorf("expected anthropic apiKey 'sk-ant-from-models', got '%s'", anthropic.ApiKey)
+ }
+ if anthropic.BaseUrl != "https://api.anthropic.com" {
+ t.Errorf("expected anthropic baseUrl 'https://api.anthropic.com', got '%s'", anthropic.BaseUrl)
+ }
+ } else {
+ t.Error("anthropic provider not found")
+ }
+
+ if openai, ok := providers["openai"]; ok {
+ if openai.ApiKey != "sk-from-models" {
+ t.Errorf("expected openai apiKey 'sk-from-models', got '%s'", openai.ApiKey)
+ }
+ if openai.BaseUrl != "https://api.openai.com" {
+ t.Errorf("expected openai baseUrl 'https://api.openai.com', got '%s'", openai.BaseUrl)
+ }
+ } else {
+ t.Error("openai provider not found")
+ }
+
+ if zhipu, ok := providers["zhipu"]; ok {
+ if zhipu.ApiKey != "zhipu-key" {
+ t.Errorf("expected zhipu apiKey 'zhipu-key', got '%s'", zhipu.ApiKey)
+ }
+ if zhipu.BaseUrl != "https://open.bigmodel.cn/api/paas/v4" {
+ t.Errorf("expected zhipu baseUrl 'https://open.bigmodel.cn/api/paas/v4', got '%s'", zhipu.BaseUrl)
+ }
+ } else {
+ t.Error("zhipu provider not found")
+ }
+}
+
+func TestGetProviderConfigFromDirNotExist(t *testing.T) {
+ providers := GetProviderConfigFromDir("/nonexistent/path")
+ if len(providers) != 0 {
+ t.Errorf("expected 0 providers for nonexistent path, got %d", len(providers))
+ }
+}
+
+func strPtr(s string) *string {
+ return &s
+}
+
+func boolPtr(b bool) *bool {
+ return &b
+}
diff --git a/pkg/migrate/sources/openclaw/openclaw_handler.go b/pkg/migrate/sources/openclaw/openclaw_handler.go
new file mode 100644
index 000000000..aaff119f1
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/openclaw_handler.go
@@ -0,0 +1,148 @@
+package openclaw
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/sipeed/picoclaw/pkg/config"
+ "github.com/sipeed/picoclaw/pkg/migrate/internal"
+)
+
+var providerMapping = map[string]string{
+ "anthropic": "anthropic",
+ "claude": "anthropic",
+ "openai": "openai",
+ "gpt": "openai",
+ "groq": "groq",
+ "ollama": "ollama",
+ "openrouter": "openrouter",
+ "deepseek": "deepseek",
+ "together": "together",
+ "mistral": "mistral",
+ "fireworks": "fireworks",
+ "google": "google",
+ "gemini": "google",
+ "xai": "xai",
+ "grok": "xai",
+ "cerebras": "cerebras",
+ "sambanova": "sambanova",
+}
+
+type OpenclawHandler struct {
+ opts Options
+ sourceConfigFile string
+ sourceWorkspace string
+}
+
+type (
+ Options = internal.Options
+ Action = internal.Action
+ Result = internal.Result
+ Operation = internal.Operation
+)
+
+func NewOpenclawHandler(opts Options) (Operation, error) {
+ home, err := resolveSourceHome(opts.SourceHome)
+ if err != nil {
+ return nil, err
+ }
+ opts.SourceHome = home
+
+ configFile, err := findSourceConfig(home)
+ if err != nil {
+ return nil, err
+ }
+ return &OpenclawHandler{
+ opts: opts,
+ sourceWorkspace: filepath.Join(opts.SourceHome, "workspace"),
+ sourceConfigFile: configFile,
+ }, nil
+}
+
+func (o *OpenclawHandler) GetSourceName() string {
+ return "openclaw"
+}
+
+func (o *OpenclawHandler) GetSourceHome() (string, error) {
+ return o.opts.SourceHome, nil
+}
+
+func (o *OpenclawHandler) GetSourceWorkspace() (string, error) {
+ return o.sourceWorkspace, nil
+}
+
+func (o *OpenclawHandler) GetSourceConfigFile() (string, error) {
+ return o.sourceConfigFile, nil
+}
+
+func (o *OpenclawHandler) GetMigrateableFiles() []string {
+ return migrateableFiles
+}
+
+func (o *OpenclawHandler) GetMigrateableDirs() []string {
+ return migrateableDirs
+}
+
+func (o *OpenclawHandler) ExecuteConfigMigration(srcConfigPath, dstConfigPath string) error {
+ openclawCfg, err := LoadOpenClawConfig(srcConfigPath)
+ if err != nil {
+ return err
+ }
+
+ picoCfg, warnings, err := openclawCfg.ConvertToPicoClaw(o.opts.SourceHome)
+ if err != nil {
+ return err
+ }
+
+ for _, w := range warnings {
+ fmt.Printf(" Warning: %s\n", w)
+ }
+
+ incoming := picoCfg.ToStandardConfig()
+ if err := os.MkdirAll(filepath.Dir(dstConfigPath), 0o755); err != nil {
+ return err
+ }
+
+ return config.SaveConfig(dstConfigPath, incoming)
+}
+
+func resolveSourceHome(override string) (string, error) {
+ if override != "" {
+ return internal.ExpandHome(override), nil
+ }
+ if envHome := os.Getenv("OPENCLAW_HOME"); envHome != "" {
+ return internal.ExpandHome(envHome), nil
+ }
+ home, err := os.UserHomeDir()
+ if err != nil {
+ return "", fmt.Errorf("resolving home directory: %w", err)
+ }
+ return filepath.Join(home, ".openclaw"), nil
+}
+
+func findSourceConfig(sourceHome string) (string, error) {
+ candidates := []string{
+ filepath.Join(sourceHome, "openclaw.json"),
+ filepath.Join(sourceHome, "config.json"),
+ }
+ for _, p := range candidates {
+ if _, err := os.Stat(p); err == nil {
+ return p, nil
+ }
+ }
+ return "", fmt.Errorf("no config file found in %s (tried openclaw.json, config.json)", sourceHome)
+}
+
+func rewriteWorkspacePath(path string) string {
+ path = strings.Replace(path, ".openclaw", ".picoclaw", 1)
+ return path
+}
+
+func mapProvider(provider string) string {
+ if mapped, ok := providerMapping[strings.ToLower(provider)]; ok {
+ return mapped
+ }
+ return strings.ToLower(provider)
+}
diff --git a/pkg/migrate/sources/openclaw/openclaw_handler_test.go b/pkg/migrate/sources/openclaw/openclaw_handler_test.go
new file mode 100644
index 000000000..35bd09be0
--- /dev/null
+++ b/pkg/migrate/sources/openclaw/openclaw_handler_test.go
@@ -0,0 +1,247 @@
+package openclaw
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestNewOpenclawHandler(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ handler, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.NoError(t, err)
+ require.NotNil(t, handler)
+}
+
+func TestNewOpenclawHandlerNoConfig(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ _, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.Error(t, err)
+}
+
+func TestOpenclawHandlerGetSourceName(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ handler, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.NoError(t, err)
+
+ assert.Equal(t, "openclaw", handler.GetSourceName())
+}
+
+func TestOpenclawHandlerGetSourceHome(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ handler, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.NoError(t, err)
+
+ home, err := handler.GetSourceHome()
+ require.NoError(t, err)
+ assert.Equal(t, tmpDir, home)
+}
+
+func TestOpenclawHandlerGetSourceWorkspace(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ handler, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.NoError(t, err)
+
+ workspace, err := handler.GetSourceWorkspace()
+ require.NoError(t, err)
+ assert.Equal(t, filepath.Join(tmpDir, "workspace"), workspace)
+}
+
+func TestOpenclawHandlerGetSourceConfigFile(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ handler, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.NoError(t, err)
+
+ configFile, err := handler.GetSourceConfigFile()
+ require.NoError(t, err)
+ assert.Equal(t, configPath, configFile)
+}
+
+func TestOpenclawHandlerGetSourceConfigFileWithConfigJson(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ handler, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.NoError(t, err)
+
+ configFile, err := handler.GetSourceConfigFile()
+ require.NoError(t, err)
+ assert.Equal(t, configPath, configFile)
+}
+
+func TestOpenclawHandlerGetMigrateableFiles(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ handler, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.NoError(t, err)
+
+ files := handler.GetMigrateableFiles()
+ assert.NotEmpty(t, files)
+ assert.Contains(t, files, "AGENTS.md")
+ assert.Contains(t, files, "SOUL.md")
+ assert.Contains(t, files, "USER.md")
+}
+
+func TestOpenclawHandlerGetMigrateableDirs(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ handler, err := NewOpenclawHandler(Options{
+ SourceHome: tmpDir,
+ })
+ require.NoError(t, err)
+
+ dirs := handler.GetMigrateableDirs()
+ assert.NotEmpty(t, dirs)
+ assert.Contains(t, dirs, "memory")
+ assert.Contains(t, dirs, "skills")
+}
+
+func TestResolveSourceHome(t *testing.T) {
+ result, err := resolveSourceHome("/custom/path")
+ require.NoError(t, err)
+ assert.Equal(t, "/custom/path", result)
+}
+
+func TestResolveSourceHomeWithEnvVar(t *testing.T) {
+ t.Setenv("OPENCLAW_HOME", "/env/path")
+
+ result, err := resolveSourceHome("")
+ require.NoError(t, err)
+ assert.Equal(t, "/env/path", result)
+}
+
+func TestResolveSourceHomeWithTilde(t *testing.T) {
+ home, err := os.UserHomeDir()
+ require.NoError(t, err)
+
+ result, err := resolveSourceHome("~/openclaw")
+ require.NoError(t, err)
+ assert.Equal(t, filepath.Join(home, "openclaw"), result)
+}
+
+func TestFindSourceConfig(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "openclaw.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ result, err := findSourceConfig(tmpDir)
+ require.NoError(t, err)
+ assert.Equal(t, configPath, result)
+}
+
+func TestFindSourceConfigWithConfigJson(t *testing.T) {
+ tmpDir := t.TempDir()
+ configPath := filepath.Join(tmpDir, "config.json")
+ err := os.WriteFile(configPath, []byte("{}"), 0o644)
+ require.NoError(t, err)
+
+ result, err := findSourceConfig(tmpDir)
+ require.NoError(t, err)
+ assert.Equal(t, configPath, result)
+}
+
+func TestFindSourceConfigNotFound(t *testing.T) {
+ tmpDir := t.TempDir()
+
+ _, err := findSourceConfig(tmpDir)
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "no config file found")
+}
+
+func TestMapProvider(t *testing.T) {
+ tests := []struct {
+ input string
+ expected string
+ }{
+ {"anthropic", "anthropic"},
+ {"claude", "anthropic"},
+ {"openai", "openai"},
+ {"gpt", "openai"},
+ {"groq", "groq"},
+ {"ollama", "ollama"},
+ {"openrouter", "openrouter"},
+ {"deepseek", "deepseek"},
+ {"together", "together"},
+ {"mistral", "mistral"},
+ {"fireworks", "fireworks"},
+ {"google", "google"},
+ {"gemini", "google"},
+ {"xai", "xai"},
+ {"grok", "xai"},
+ {"cerebras", "cerebras"},
+ {"sambanova", "sambanova"},
+ {"unknown", "unknown"},
+ {"", ""},
+ }
+
+ for _, tt := range tests {
+ result := mapProvider(tt.input)
+ assert.Equal(t, tt.expected, result, "mapProvider(%q)", tt.input)
+ }
+}
+
+func TestRewriteWorkspacePath(t *testing.T) {
+ tests := []struct {
+ input string
+ expected string
+ }{
+ {"~/.openclaw/workspace", "~/.picoclaw/workspace"},
+ {"/home/user/.openclaw/workspace", "/home/user/.picoclaw/workspace"},
+ {"/path/without/openclaw/change", "/path/without/openclaw/change"},
+ {"", ""},
+ }
+
+ for _, tt := range tests {
+ result := rewriteWorkspacePath(tt.input)
+ assert.Equal(t, tt.expected, result, "rewriteWorkspacePath(%q)", tt.input)
+ }
+}
diff --git a/pkg/providers/anthropic/provider.go b/pkg/providers/anthropic/provider.go
index 9162174c9..1bb15f771 100644
--- a/pkg/providers/anthropic/provider.go
+++ b/pkg/providers/anthropic/provider.go
@@ -212,14 +212,14 @@ func translateTools(tools []ToolDefinition) []anthropic.ToolUnionParam {
}
func parseResponse(resp *anthropic.Message) *LLMResponse {
- var content string
+ var content strings.Builder
var toolCalls []ToolCall
for _, block := range resp.Content {
switch block.Type {
case "text":
tb := block.AsText()
- content += tb.Text
+ content.WriteString(tb.Text)
case "tool_use":
tu := block.AsToolUse()
var args map[string]any
@@ -246,7 +246,7 @@ func parseResponse(resp *anthropic.Message) *LLMResponse {
}
return &LLMResponse{
- Content: content,
+ Content: content.String(),
ToolCalls: toolCalls,
FinishReason: finishReason,
Usage: &UsageInfo{
@@ -264,8 +264,8 @@ func normalizeBaseURL(apiBase string) string {
}
base = strings.TrimRight(base, "/")
- if strings.HasSuffix(base, "/v1") {
- base = strings.TrimSuffix(base, "/v1")
+ if before, ok := strings.CutSuffix(base, "/v1"); ok {
+ base = before
}
if base == "" {
return defaultBaseURL
diff --git a/pkg/providers/claude_cli_provider.go b/pkg/providers/claude_cli_provider.go
index 74ec33b98..6c4f6a767 100644
--- a/pkg/providers/claude_cli_provider.go
+++ b/pkg/providers/claude_cli_provider.go
@@ -100,44 +100,12 @@ func (p *ClaudeCliProvider) buildSystemPrompt(messages []Message, tools []ToolDe
}
if len(tools) > 0 {
- parts = append(parts, p.buildToolsPrompt(tools))
+ parts = append(parts, buildCLIToolsPrompt(tools))
}
return strings.Join(parts, "\n\n")
}
-// buildToolsPrompt creates the tool definitions section for the system prompt.
-func (p *ClaudeCliProvider) buildToolsPrompt(tools []ToolDefinition) string {
- var sb strings.Builder
-
- sb.WriteString("## Available Tools\n\n")
- sb.WriteString("When you need to use a tool, respond with ONLY a JSON object:\n\n")
- sb.WriteString("```json\n")
- sb.WriteString(
- `{"tool_calls":[{"id":"call_xxx","type":"function","function":{"name":"tool_name","arguments":"{...}"}}]}`,
- )
- sb.WriteString("\n```\n\n")
- sb.WriteString("CRITICAL: The 'arguments' field MUST be a JSON-encoded STRING.\n\n")
- sb.WriteString("### Tool Definitions:\n\n")
-
- for _, tool := range tools {
- if tool.Type != "function" {
- continue
- }
- sb.WriteString(fmt.Sprintf("#### %s\n", tool.Function.Name))
- if tool.Function.Description != "" {
- sb.WriteString(fmt.Sprintf("Description: %s\n", tool.Function.Description))
- }
- if len(tool.Function.Parameters) > 0 {
- paramsJSON, _ := json.Marshal(tool.Function.Parameters)
- sb.WriteString(fmt.Sprintf("Parameters:\n```json\n%s\n```\n", string(paramsJSON)))
- }
- sb.WriteString("\n")
- }
-
- return sb.String()
-}
-
// parseClaudeCliResponse parses the JSON output from the claude CLI.
func (p *ClaudeCliProvider) parseClaudeCliResponse(output string) (*LLMResponse, error) {
var resp claudeCliJSONResponse
diff --git a/pkg/providers/claude_cli_provider_test.go b/pkg/providers/claude_cli_provider_test.go
index 3a3cafaca..d4d648f5a 100644
--- a/pkg/providers/claude_cli_provider_test.go
+++ b/pkg/providers/claude_cli_provider_test.go
@@ -660,12 +660,11 @@ func TestBuildSystemPrompt_ToolsOnlyNoSystem(t *testing.T) {
// --- buildToolsPrompt tests ---
func TestBuildToolsPrompt_SkipsNonFunction(t *testing.T) {
- p := NewClaudeCliProvider("/workspace")
tools := []ToolDefinition{
{Type: "other", Function: ToolFunctionDefinition{Name: "skip_me"}},
{Type: "function", Function: ToolFunctionDefinition{Name: "include_me", Description: "Included"}},
}
- got := p.buildToolsPrompt(tools)
+ got := buildCLIToolsPrompt(tools)
if strings.Contains(got, "skip_me") {
t.Error("buildToolsPrompt() should skip non-function tools")
}
@@ -675,11 +674,10 @@ func TestBuildToolsPrompt_SkipsNonFunction(t *testing.T) {
}
func TestBuildToolsPrompt_NoDescription(t *testing.T) {
- p := NewClaudeCliProvider("/workspace")
tools := []ToolDefinition{
{Type: "function", Function: ToolFunctionDefinition{Name: "bare_tool"}},
}
- got := p.buildToolsPrompt(tools)
+ got := buildCLIToolsPrompt(tools)
if !strings.Contains(got, "bare_tool") {
t.Error("should include tool name")
}
@@ -689,14 +687,13 @@ func TestBuildToolsPrompt_NoDescription(t *testing.T) {
}
func TestBuildToolsPrompt_NoParameters(t *testing.T) {
- p := NewClaudeCliProvider("/workspace")
tools := []ToolDefinition{
{Type: "function", Function: ToolFunctionDefinition{
Name: "no_params_tool",
Description: "A tool with no parameters",
}},
}
- got := p.buildToolsPrompt(tools)
+ got := buildCLIToolsPrompt(tools)
if strings.Contains(got, "Parameters:") {
t.Error("should not include Parameters: section when nil")
}
diff --git a/pkg/providers/codex_cli_provider.go b/pkg/providers/codex_cli_provider.go
index 4c783ece5..13f53ad9e 100644
--- a/pkg/providers/codex_cli_provider.go
+++ b/pkg/providers/codex_cli_provider.go
@@ -115,7 +115,7 @@ func (p *CodexCliProvider) buildPrompt(messages []Message, tools []ToolDefinitio
}
if len(tools) > 0 {
- sb.WriteString(p.buildToolsPrompt(tools))
+ sb.WriteString(buildCLIToolsPrompt(tools))
sb.WriteString("\n\n")
}
@@ -128,38 +128,6 @@ func (p *CodexCliProvider) buildPrompt(messages []Message, tools []ToolDefinitio
return sb.String()
}
-// buildToolsPrompt creates a tool definitions section for the prompt.
-func (p *CodexCliProvider) buildToolsPrompt(tools []ToolDefinition) string {
- var sb strings.Builder
-
- sb.WriteString("## Available Tools\n\n")
- sb.WriteString("When you need to use a tool, respond with ONLY a JSON object:\n\n")
- sb.WriteString("```json\n")
- sb.WriteString(
- `{"tool_calls":[{"id":"call_xxx","type":"function","function":{"name":"tool_name","arguments":"{...}"}}]}`,
- )
- sb.WriteString("\n```\n\n")
- sb.WriteString("CRITICAL: The 'arguments' field MUST be a JSON-encoded STRING.\n\n")
- sb.WriteString("### Tool Definitions:\n\n")
-
- for _, tool := range tools {
- if tool.Type != "function" {
- continue
- }
- sb.WriteString(fmt.Sprintf("#### %s\n", tool.Function.Name))
- if tool.Function.Description != "" {
- sb.WriteString(fmt.Sprintf("Description: %s\n", tool.Function.Description))
- }
- if len(tool.Function.Parameters) > 0 {
- paramsJSON, _ := json.Marshal(tool.Function.Parameters)
- sb.WriteString(fmt.Sprintf("Parameters:\n```json\n%s\n```\n", string(paramsJSON)))
- }
- sb.WriteString("\n")
- }
-
- return sb.String()
-}
-
// codexEvent represents a single JSONL event from `codex exec --json`.
type codexEvent struct {
Type string `json:"type"`
diff --git a/pkg/providers/codex_provider.go b/pkg/providers/codex_provider.go
index dcc740ba4..47618300a 100644
--- a/pkg/providers/codex_provider.go
+++ b/pkg/providers/codex_provider.go
@@ -163,8 +163,8 @@ func resolveCodexModel(model string) (string, string) {
return codexDefaultModel, "empty model"
}
- if strings.HasPrefix(m, "openai/") {
- m = strings.TrimPrefix(m, "openai/")
+ if after, ok := strings.CutPrefix(m, "openai/"); ok {
+ m = after
} else if strings.Contains(m, "/") {
return codexDefaultModel, "non-openai model namespace"
}
diff --git a/pkg/providers/cooldown_test.go b/pkg/providers/cooldown_test.go
index 47f43ad5c..b517e7feb 100644
--- a/pkg/providers/cooldown_test.go
+++ b/pkg/providers/cooldown_test.go
@@ -138,7 +138,7 @@ func TestCooldown_FailureWindowReset(t *testing.T) {
ct, current := newTestTracker(now)
// 4 errors → 1h cooldown
- for i := 0; i < 4; i++ {
+ for range 4 {
ct.MarkFailure("openai", FailoverRateLimit)
*current = current.Add(2 * time.Second) // small advance between errors
}
@@ -230,7 +230,7 @@ func TestCooldown_ConcurrentAccess(t *testing.T) {
ct := NewCooldownTracker()
var wg sync.WaitGroup
- for i := 0; i < 100; i++ {
+ for range 100 {
wg.Add(3)
go func() {
defer wg.Done()
diff --git a/pkg/providers/error_classifier.go b/pkg/providers/error_classifier.go
index a0f003006..fd9bf1e81 100644
--- a/pkg/providers/error_classifier.go
+++ b/pkg/providers/error_classifier.go
@@ -6,6 +6,13 @@ import (
"strings"
)
+// Common patterns in Go HTTP error messages
+var httpStatusPatterns = []*regexp.Regexp{
+ regexp.MustCompile(`status[:\s]+(\d{3})`),
+ regexp.MustCompile(`http[/\s]+\d*\.?\d*\s+(\d{3})`),
+ regexp.MustCompile(`\b([3-5]\d{2})\b`),
+}
+
// errorPattern defines a single pattern (string or regex) for error classification.
type errorPattern struct {
substring string
@@ -198,20 +205,13 @@ func classifyByMessage(msg string) FailoverReason {
}
// extractHTTPStatus extracts an HTTP status code from an error message.
-// Looks for patterns like "status: 429", "status 429", "HTTP 429", or standalone "429".
+// Looks for patterns like "status: 429", "status 429", "http/1.1 429", "http 429", or standalone "429".
func extractHTTPStatus(msg string) int {
- // Common patterns in Go HTTP error messages
- patterns := []*regexp.Regexp{
- regexp.MustCompile(`status[:\s]+(\d{3})`),
- regexp.MustCompile(`HTTP[/\s]+\d*\.?\d*\s+(\d{3})`),
- }
-
- for _, p := range patterns {
+ for _, p := range httpStatusPatterns {
if m := p.FindStringSubmatch(msg); len(m) > 1 {
return parseDigits(m[1])
}
}
-
return 0
}
diff --git a/pkg/providers/error_classifier_test.go b/pkg/providers/error_classifier_test.go
index 865aea57a..67d9af62b 100644
--- a/pkg/providers/error_classifier_test.go
+++ b/pkg/providers/error_classifier_test.go
@@ -305,7 +305,8 @@ func TestExtractHTTPStatus(t *testing.T) {
}{
{"status: 429 rate limited", 429},
{"status 401 unauthorized", 401},
- {"HTTP/1.1 502 Bad Gateway", 502},
+ {"http/1.1 502 bad gateway", 502},
+ {"error 429", 429},
{"no status code here", 0},
{"random number 12345", 0},
}
diff --git a/pkg/providers/factory.go b/pkg/providers/factory.go
index 11af14da4..5b3e42b9e 100644
--- a/pkg/providers/factory.go
+++ b/pkg/providers/factory.go
@@ -102,6 +102,15 @@ func resolveProviderSelection(cfg *config.Config) (providerSelection, error) {
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
diff --git a/pkg/providers/factory_provider.go b/pkg/providers/factory_provider.go
index 7d5566eef..155317a3b 100644
--- a/pkg/providers/factory_provider.go
+++ b/pkg/providers/factory_provider.go
@@ -53,7 +53,7 @@ func ExtractProtocol(model string) (protocol, modelID string) {
// CreateProviderFromConfig creates a provider based on the ModelConfig.
// It uses the protocol prefix in the Model field to determine which provider to create.
-// Supported protocols: openai, anthropic, antigravity, claude-cli, codex-cli, github-copilot
+// Supported protocols: openai, litellm, anthropic, antigravity, claude-cli, codex-cli, github-copilot
// Returns the provider, the model ID (without protocol prefix), and any error.
func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, error) {
if cfg == nil {
@@ -84,9 +84,15 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
if apiBase == "" {
apiBase = getDefaultAPIBase(protocol)
}
- return NewHTTPProviderWithMaxTokensField(cfg.APIKey, apiBase, cfg.Proxy, cfg.MaxTokensField), modelID, nil
+ return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+ cfg.APIKey,
+ apiBase,
+ cfg.Proxy,
+ cfg.MaxTokensField,
+ cfg.RequestTimeout,
+ ), modelID, nil
- case "openrouter", "groq", "zhipu", "gemini", "nvidia",
+ case "litellm", "openrouter", "groq", "zhipu", "gemini", "nvidia",
"ollama", "moonshot", "shengsuanyun", "deepseek", "cerebras",
"volcengine", "vllm", "qwen", "mistral":
// All other OpenAI-compatible HTTP providers
@@ -97,7 +103,13 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
if apiBase == "" {
apiBase = getDefaultAPIBase(protocol)
}
- return NewHTTPProviderWithMaxTokensField(cfg.APIKey, apiBase, cfg.Proxy, cfg.MaxTokensField), modelID, nil
+ return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+ cfg.APIKey,
+ apiBase,
+ cfg.Proxy,
+ cfg.MaxTokensField,
+ cfg.RequestTimeout,
+ ), modelID, nil
case "anthropic":
if cfg.AuthMethod == "oauth" || cfg.AuthMethod == "token" {
@@ -116,7 +128,13 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
if cfg.APIKey == "" {
return nil, "", fmt.Errorf("api_key is required for anthropic protocol (model: %s)", cfg.Model)
}
- return NewHTTPProviderWithMaxTokensField(cfg.APIKey, apiBase, cfg.Proxy, cfg.MaxTokensField), modelID, nil
+ return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+ cfg.APIKey,
+ apiBase,
+ cfg.Proxy,
+ cfg.MaxTokensField,
+ cfg.RequestTimeout,
+ ), modelID, nil
case "antigravity":
return NewAntigravityProvider(), modelID, nil
@@ -162,6 +180,8 @@ func getDefaultAPIBase(protocol string) string {
return "https://api.openai.com/v1"
case "openrouter":
return "https://openrouter.ai/api/v1"
+ case "litellm":
+ return "http://localhost:4000/v1"
case "groq":
return "https://api.groq.com/openai/v1"
case "zhipu":
diff --git a/pkg/providers/factory_provider_test.go b/pkg/providers/factory_provider_test.go
index 6b133101a..78389f331 100644
--- a/pkg/providers/factory_provider_test.go
+++ b/pkg/providers/factory_provider_test.go
@@ -6,7 +6,11 @@
package providers
import (
+ "net/http"
+ "net/http/httptest"
+ "strings"
"testing"
+ "time"
"github.com/sipeed/picoclaw/pkg/config"
)
@@ -131,6 +135,32 @@ func TestCreateProviderFromConfig_DefaultAPIBase(t *testing.T) {
}
}
+func TestGetDefaultAPIBase_LiteLLM(t *testing.T) {
+ if got := getDefaultAPIBase("litellm"); got != "http://localhost:4000/v1" {
+ t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", "litellm", got, "http://localhost:4000/v1")
+ }
+}
+
+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",
+ }
+
+ 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 != "my-proxy-alias" {
+ t.Errorf("modelID = %q, want %q", modelID, "my-proxy-alias")
+ }
+}
+
func TestCreateProviderFromConfig_Anthropic(t *testing.T) {
cfg := &config.ModelConfig{
ModelName: "test-anthropic",
@@ -247,3 +277,42 @@ func TestCreateProviderFromConfig_EmptyModel(t *testing.T) {
t.Fatal("CreateProviderFromConfig() expected error for empty model")
}
}
+
+func TestCreateProviderFromConfig_RequestTimeoutPropagation(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ time.Sleep(1500 * time.Millisecond)
+ 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-timeout",
+ Model: "openai/gpt-4o",
+ APIBase: server.URL,
+ RequestTimeout: 1,
+ }
+
+ provider, modelID, err := CreateProviderFromConfig(cfg)
+ if err != nil {
+ t.Fatalf("CreateProviderFromConfig() error = %v", err)
+ }
+ if modelID != "gpt-4o" {
+ t.Fatalf("modelID = %q, want %q", modelID, "gpt-4o")
+ }
+
+ _, err = provider.Chat(
+ t.Context(),
+ []Message{{Role: "user", Content: "hi"}},
+ nil,
+ modelID,
+ nil,
+ )
+ if err == nil {
+ t.Fatal("Chat() expected timeout error, got nil")
+ }
+ errMsg := err.Error()
+ if !strings.Contains(errMsg, "context deadline exceeded") && !strings.Contains(errMsg, "Client.Timeout exceeded") {
+ t.Fatalf("Chat() error = %q, want timeout-related error", errMsg)
+ }
+}
diff --git a/pkg/providers/factory_test.go b/pkg/providers/factory_test.go
index 5680f23b3..f7a916d9e 100644
--- a/pkg/providers/factory_test.go
+++ b/pkg/providers/factory_test.go
@@ -17,6 +17,27 @@ func TestResolveProviderSelection(t *testing.T) {
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) {
diff --git a/pkg/providers/fallback.go b/pkg/providers/fallback.go
index ecd451ec9..7ba563b66 100644
--- a/pkg/providers/fallback.go
+++ b/pkg/providers/fallback.go
@@ -43,11 +43,26 @@ func NewFallbackChain(cooldown *CooldownTracker) *FallbackChain {
// ResolveCandidates parses model config into a deduplicated candidate list.
func ResolveCandidates(cfg ModelConfig, defaultProvider string) []FallbackCandidate {
+ return ResolveCandidatesWithLookup(cfg, defaultProvider, nil)
+}
+
+func ResolveCandidatesWithLookup(
+ cfg ModelConfig,
+ defaultProvider string,
+ lookup func(raw string) (resolved string, ok bool),
+) []FallbackCandidate {
seen := make(map[string]bool)
var candidates []FallbackCandidate
addCandidate := func(raw string) {
- ref := ParseModelRef(raw, defaultProvider)
+ candidateRaw := strings.TrimSpace(raw)
+ if lookup != nil {
+ if resolved, ok := lookup(candidateRaw); ok {
+ candidateRaw = resolved
+ }
+ }
+
+ ref := ParseModelRef(candidateRaw, defaultProvider)
if ref == nil {
return
}
diff --git a/pkg/providers/fallback_test.go b/pkg/providers/fallback_test.go
index ebba054ef..1783ebcb5 100644
--- a/pkg/providers/fallback_test.go
+++ b/pkg/providers/fallback_test.go
@@ -453,6 +453,75 @@ func TestResolveCandidates_EmptyPrimary(t *testing.T) {
}
}
+func TestResolveCandidatesWithLookup_AliasResolvesToNestedModel(t *testing.T) {
+ cfg := ModelConfig{
+ Primary: "step-3.5-flash",
+ Fallbacks: nil,
+ }
+
+ lookup := func(raw string) (string, bool) {
+ if raw == "step-3.5-flash" {
+ return "openrouter/stepfun/step-3.5-flash:free", true
+ }
+ return "", false
+ }
+
+ candidates := ResolveCandidatesWithLookup(cfg, "", lookup)
+ if len(candidates) != 1 {
+ t.Fatalf("candidates = %d, want 1", len(candidates))
+ }
+ if candidates[0].Provider != "openrouter" {
+ t.Fatalf("provider = %q, want openrouter", candidates[0].Provider)
+ }
+ if candidates[0].Model != "stepfun/step-3.5-flash:free" {
+ t.Fatalf("model = %q, want stepfun/step-3.5-flash:free", candidates[0].Model)
+ }
+}
+
+func TestResolveCandidatesWithLookup_DeduplicateAfterLookup(t *testing.T) {
+ cfg := ModelConfig{
+ Primary: "step-3.5-flash",
+ Fallbacks: []string{"openrouter/stepfun/step-3.5-flash:free"},
+ }
+
+ lookup := func(raw string) (string, bool) {
+ if raw == "step-3.5-flash" {
+ return "openrouter/stepfun/step-3.5-flash:free", true
+ }
+ return "", false
+ }
+
+ candidates := ResolveCandidatesWithLookup(cfg, "", lookup)
+ if len(candidates) != 1 {
+ t.Fatalf("candidates = %d, want 1", len(candidates))
+ }
+}
+
+func TestResolveCandidatesWithLookup_AliasWithoutProtocolUsesDefaultProvider(t *testing.T) {
+ cfg := ModelConfig{
+ Primary: "glm-5",
+ Fallbacks: nil,
+ }
+
+ lookup := func(raw string) (string, bool) {
+ if raw == "glm-5" {
+ return "glm-5", true
+ }
+ return "", false
+ }
+
+ candidates := ResolveCandidatesWithLookup(cfg, "openai", lookup)
+ if len(candidates) != 1 {
+ t.Fatalf("candidates = %d, want 1", len(candidates))
+ }
+ if candidates[0].Provider != "openai" {
+ t.Fatalf("provider = %q, want openai", candidates[0].Provider)
+ }
+ if candidates[0].Model != "glm-5" {
+ t.Fatalf("model = %q, want glm-5", candidates[0].Model)
+ }
+}
+
func TestFallbackExhaustedError_Message(t *testing.T) {
e := &FallbackExhaustedError{
Attempts: []FallbackAttempt{
diff --git a/pkg/providers/github_copilot_provider.go b/pkg/providers/github_copilot_provider.go
index 3fb15db2f..6d642b2b5 100644
--- a/pkg/providers/github_copilot_provider.go
+++ b/pkg/providers/github_copilot_provider.go
@@ -26,8 +26,9 @@ func NewGitHubCopilotProvider(uri string, connectMode string, model string) (*Gi
switch connectMode {
case "stdio":
- // TODO:
- return nil, fmt.Errorf("stdio mode not implemented")
+ // TODO: Implement stdio mode for GitHub Copilot provider
+ // See https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md for details
+ return nil, fmt.Errorf("stdio mode not implemented for GitHub Copilot provider; please use 'grpc' mode instead")
case "grpc":
client := copilot.NewClient(&copilot.ClientOptions{
CLIUrl: uri,
@@ -100,9 +101,12 @@ func (p *GitHubCopilotProvider) Chat(
return nil, fmt.Errorf("provider closed")
}
- resp, _ := session.SendAndWait(ctx, copilot.MessageOptions{
+ resp, err := session.SendAndWait(ctx, copilot.MessageOptions{
Prompt: string(fullcontent),
})
+ if err != nil {
+ return nil, fmt.Errorf("failed to send message to copilot: %w", err)
+ }
if resp == nil {
return nil, fmt.Errorf("empty response from copilot")
diff --git a/pkg/providers/http_provider.go b/pkg/providers/http_provider.go
index d0c4344f3..5c328f418 100644
--- a/pkg/providers/http_provider.go
+++ b/pkg/providers/http_provider.go
@@ -8,6 +8,7 @@ package providers
import (
"context"
+ "time"
"github.com/sipeed/picoclaw/pkg/providers/openai_compat"
)
@@ -23,8 +24,21 @@ func NewHTTPProvider(apiKey, apiBase, proxy string) *HTTPProvider {
}
func NewHTTPProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *HTTPProvider {
+ return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(apiKey, apiBase, proxy, maxTokensField, 0)
+}
+
+func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+ apiKey, apiBase, proxy, maxTokensField string,
+ requestTimeoutSeconds int,
+) *HTTPProvider {
return &HTTPProvider{
- delegate: openai_compat.NewProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField),
+ delegate: openai_compat.NewProvider(
+ apiKey,
+ apiBase,
+ proxy,
+ openai_compat.WithMaxTokensField(maxTokensField),
+ openai_compat.WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+ ),
}
}
diff --git a/pkg/providers/legacy_provider.go b/pkg/providers/legacy_provider.go
index 23f137538..26905159f 100644
--- a/pkg/providers/legacy_provider.go
+++ b/pkg/providers/legacy_provider.go
@@ -18,9 +18,21 @@ import (
func CreateProvider(cfg *config.Config) (LLMProvider, string, error) {
model := cfg.Agents.Defaults.GetModelName()
- // Ensure model_list is populated (should be done by LoadConfig, but handle edge cases)
- if len(cfg.ModelList) == 0 && cfg.HasProvidersConfig() {
- cfg.ModelList = config.ConvertProvidersToModelList(cfg)
+ // 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
diff --git a/pkg/providers/openai_compat/provider.go b/pkg/providers/openai_compat/provider.go
index 087d3506e..ff9109e96 100644
--- a/pkg/providers/openai_compat/provider.go
+++ b/pkg/providers/openai_compat/provider.go
@@ -25,6 +25,7 @@ type (
ToolFunctionDefinition = protocoltypes.ToolFunctionDefinition
ExtraContent = protocoltypes.ExtraContent
GoogleExtra = protocoltypes.GoogleExtra
+ ReasoningDetail = protocoltypes.ReasoningDetail
)
type Provider struct {
@@ -34,13 +35,27 @@ type Provider struct {
httpClient *http.Client
}
-func NewProvider(apiKey, apiBase, proxy string) *Provider {
- return NewProviderWithMaxTokensField(apiKey, apiBase, proxy, "")
+type Option func(*Provider)
+
+const defaultRequestTimeout = 120 * time.Second
+
+func WithMaxTokensField(maxTokensField string) Option {
+ return func(p *Provider) {
+ p.maxTokensField = maxTokensField
+ }
}
-func NewProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *Provider {
+func WithRequestTimeout(timeout time.Duration) Option {
+ return func(p *Provider) {
+ if timeout > 0 {
+ p.httpClient.Timeout = timeout
+ }
+ }
+}
+
+func NewProvider(apiKey, apiBase, proxy string, opts ...Option) *Provider {
client := &http.Client{
- Timeout: 120 * time.Second,
+ Timeout: defaultRequestTimeout,
}
if proxy != "" {
@@ -54,12 +69,36 @@ func NewProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string
}
}
- return &Provider{
- apiKey: apiKey,
- apiBase: strings.TrimRight(apiBase, "/"),
- maxTokensField: maxTokensField,
- httpClient: client,
+ p := &Provider{
+ apiKey: apiKey,
+ apiBase: strings.TrimRight(apiBase, "/"),
+ httpClient: client,
}
+
+ for _, opt := range opts {
+ if opt != nil {
+ opt(p)
+ }
+ }
+
+ return p
+}
+
+func NewProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *Provider {
+ return NewProvider(apiKey, apiBase, proxy, WithMaxTokensField(maxTokensField))
+}
+
+func NewProviderWithMaxTokensFieldAndTimeout(
+ apiKey, apiBase, proxy, maxTokensField string,
+ requestTimeoutSeconds int,
+) *Provider {
+ return NewProvider(
+ apiKey,
+ apiBase,
+ proxy,
+ WithMaxTokensField(maxTokensField),
+ WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+ )
}
func (p *Provider) Chat(
@@ -77,7 +116,7 @@ func (p *Provider) Chat(
requestBody := map[string]any{
"model": model,
- "messages": stripSystemParts(messages),
+ "messages": serializeMessages(messages),
}
if len(tools) > 0 {
@@ -160,8 +199,10 @@ func parseResponse(body []byte) (*LLMResponse, error) {
var apiResponse struct {
Choices []struct {
Message struct {
- Content string `json:"content"`
- ReasoningContent string `json:"reasoning_content"`
+ Content string `json:"content"`
+ ReasoningContent string `json:"reasoning_content"`
+ Reasoning string `json:"reasoning"`
+ ReasoningDetails []ReasoningDetail `json:"reasoning_details"`
ToolCalls []struct {
ID string `json:"id"`
Type string `json:"type"`
@@ -236,6 +277,8 @@ func parseResponse(body []byte) (*LLMResponse, error) {
return &LLMResponse{
Content: choice.Message.Content,
ReasoningContent: choice.Message.ReasoningContent,
+ Reasoning: choice.Message.Reasoning,
+ ReasoningDetails: choice.Message.ReasoningDetails,
ToolCalls: toolCalls,
FinishReason: choice.FinishReason,
Usage: apiResponse.Usage,
@@ -246,31 +289,69 @@ func parseResponse(body []byte) (*LLMResponse, error) {
// It mirrors protocoltypes.Message but omits SystemParts, which is an
// internal field that would be unknown to third-party endpoints.
type openaiMessage struct {
- Role string `json:"role"`
- Content string `json:"content"`
- ToolCalls []ToolCall `json:"tool_calls,omitempty"`
- ToolCallID string `json:"tool_call_id,omitempty"`
+ Role string `json:"role"`
+ Content string `json:"content"`
+ ReasoningContent string `json:"reasoning_content,omitempty"`
+ ToolCalls []ToolCall `json:"tool_calls,omitempty"`
+ ToolCallID string `json:"tool_call_id,omitempty"`
}
-// stripSystemParts converts []Message to []openaiMessage, dropping the
-// SystemParts field so it doesn't leak into the JSON payload sent to
-// OpenAI-compatible APIs (some strict endpoints reject unknown fields).
-func stripSystemParts(messages []Message) []openaiMessage {
- out := make([]openaiMessage, len(messages))
- for i, m := range messages {
- out[i] = openaiMessage{
- Role: m.Role,
- Content: m.Content,
- ToolCalls: m.ToolCalls,
- ToolCallID: m.ToolCallID,
+// serializeMessages converts internal Message structs to the OpenAI wire format.
+// - Strips SystemParts (unknown to third-party endpoints)
+// - Converts messages with Media to multipart content format (text + image_url parts)
+// - Preserves ToolCallID, ToolCalls, and ReasoningContent for all messages
+func serializeMessages(messages []Message) []any {
+ out := make([]any, 0, len(messages))
+ for _, m := range messages {
+ if len(m.Media) == 0 {
+ out = append(out, openaiMessage{
+ Role: m.Role,
+ Content: m.Content,
+ ReasoningContent: m.ReasoningContent,
+ ToolCalls: m.ToolCalls,
+ ToolCallID: m.ToolCallID,
+ })
+ continue
}
+
+ // Multipart content format for messages with media
+ parts := make([]map[string]any, 0, 1+len(m.Media))
+ if m.Content != "" {
+ parts = append(parts, map[string]any{
+ "type": "text",
+ "text": m.Content,
+ })
+ }
+ for _, mediaURL := range m.Media {
+ parts = append(parts, map[string]any{
+ "type": "image_url",
+ "image_url": map[string]any{
+ "url": mediaURL,
+ },
+ })
+ }
+
+ msg := map[string]any{
+ "role": m.Role,
+ "content": parts,
+ }
+ if m.ToolCallID != "" {
+ msg["tool_call_id"] = m.ToolCallID
+ }
+ if len(m.ToolCalls) > 0 {
+ msg["tool_calls"] = m.ToolCalls
+ }
+ if m.ReasoningContent != "" {
+ msg["reasoning_content"] = m.ReasoningContent
+ }
+ out = append(out, msg)
}
return out
}
func normalizeModel(model, apiBase string) string {
- idx := strings.Index(model, "/")
- if idx == -1 {
+ before, after, ok := strings.Cut(model, "/")
+ if !ok {
return model
}
@@ -278,10 +359,10 @@ func normalizeModel(model, apiBase string) string {
return model
}
- prefix := strings.ToLower(model[:idx])
+ prefix := strings.ToLower(before)
switch prefix {
- case "moonshot", "nvidia", "groq", "ollama", "deepseek", "google", "openrouter", "zhipu", "mistral":
- return model[idx+1:]
+ case "litellm", "moonshot", "nvidia", "groq", "ollama", "deepseek", "google", "openrouter", "zhipu", "mistral":
+ return after
default:
return model
}
diff --git a/pkg/providers/openai_compat/provider_test.go b/pkg/providers/openai_compat/provider_test.go
index 594a48213..174bcf00d 100644
--- a/pkg/providers/openai_compat/provider_test.go
+++ b/pkg/providers/openai_compat/provider_test.go
@@ -5,7 +5,11 @@ import (
"net/http"
"net/http/httptest"
"net/url"
+ "strings"
"testing"
+ "time"
+
+ "github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
)
func TestProviderChat_UsesMaxCompletionTokensForGLM(t *testing.T) {
@@ -145,6 +149,56 @@ func TestProviderChat_ParsesReasoningContent(t *testing.T) {
}
}
+func TestProviderChat_PreservesReasoningContentInHistory(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()
+
+ p := NewProvider("key", server.URL, "")
+
+ // Simulate a multi-turn conversation where the assistant's previous
+ // reply included reasoning_content (e.g. from kimi-k2.5).
+ messages := []Message{
+ {Role: "user", Content: "What is 1+1?"},
+ {Role: "assistant", Content: "2", ReasoningContent: "Let me think... 1+1=2"},
+ {Role: "user", Content: "What about 2+2?"},
+ }
+
+ _, err := p.Chat(t.Context(), messages, nil, "kimi-k2.5", nil)
+ if err != nil {
+ t.Fatalf("Chat() error = %v", err)
+ }
+
+ // Verify reasoning_content is preserved in the serialized request.
+ reqMessages, ok := requestBody["messages"].([]any)
+ if !ok {
+ t.Fatalf("messages is not []any: %T", requestBody["messages"])
+ }
+ assistantMsg, ok := reqMessages[1].(map[string]any)
+ if !ok {
+ t.Fatalf("assistant message is not map[string]any: %T", reqMessages[1])
+ }
+ if assistantMsg["reasoning_content"] != "Let me think... 1+1=2" {
+ t.Errorf("reasoning_content not preserved in request, got %v", assistantMsg["reasoning_content"])
+ }
+}
+
func TestProviderChat_HTTPError(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
http.Error(w, "bad request", http.StatusBadRequest)
@@ -205,6 +259,11 @@ func TestProviderChat_StripsGroqAndOllamaPrefixes(t *testing.T) {
input string
wantModel string
}{
+ {
+ name: "strips litellm prefix and preserves proxy model name",
+ input: "litellm/my-proxy-alias",
+ wantModel: "my-proxy-alias",
+ },
{
name: "strips groq prefix and keeps nested model",
input: "groq/openai/gpt-oss-120b",
@@ -325,3 +384,132 @@ func TestNormalizeModel_UsesAPIBase(t *testing.T) {
t.Fatalf("normalizeModel(openrouter) = %q, want %q", got, "openrouter/auto")
}
}
+
+func TestProvider_RequestTimeoutDefault(t *testing.T) {
+ p := NewProviderWithMaxTokensFieldAndTimeout("key", "https://example.com/v1", "", "", 0)
+ if p.httpClient.Timeout != defaultRequestTimeout {
+ t.Fatalf("http timeout = %v, want %v", p.httpClient.Timeout, defaultRequestTimeout)
+ }
+}
+
+func TestProvider_RequestTimeoutOverride(t *testing.T) {
+ p := NewProviderWithMaxTokensFieldAndTimeout("key", "https://example.com/v1", "", "", 300)
+ if p.httpClient.Timeout != 300*time.Second {
+ t.Fatalf("http timeout = %v, want %v", p.httpClient.Timeout, 300*time.Second)
+ }
+}
+
+func TestProvider_FunctionalOptionMaxTokensField(t *testing.T) {
+ p := NewProvider("key", "https://example.com/v1", "", WithMaxTokensField("max_completion_tokens"))
+ if p.maxTokensField != "max_completion_tokens" {
+ t.Fatalf("maxTokensField = %q, want %q", p.maxTokensField, "max_completion_tokens")
+ }
+}
+
+func TestProvider_FunctionalOptionRequestTimeout(t *testing.T) {
+ p := NewProvider("key", "https://example.com/v1", "", WithRequestTimeout(45*time.Second))
+ if p.httpClient.Timeout != 45*time.Second {
+ t.Fatalf("http timeout = %v, want %v", p.httpClient.Timeout, 45*time.Second)
+ }
+}
+
+func TestProvider_FunctionalOptionRequestTimeoutNonPositive(t *testing.T) {
+ p := NewProvider("key", "https://example.com/v1", "", WithRequestTimeout(-1*time.Second))
+ if p.httpClient.Timeout != defaultRequestTimeout {
+ t.Fatalf("http timeout = %v, want %v", p.httpClient.Timeout, defaultRequestTimeout)
+ }
+}
+
+func TestSerializeMessages_PlainText(t *testing.T) {
+ messages := []protocoltypes.Message{
+ {Role: "user", Content: "hello"},
+ {Role: "assistant", Content: "hi", ReasoningContent: "thinking..."},
+ }
+ result := serializeMessages(messages)
+
+ data, err := json.Marshal(result)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ var msgs []map[string]any
+ json.Unmarshal(data, &msgs)
+
+ if msgs[0]["content"] != "hello" {
+ t.Fatalf("expected plain string content, got %v", msgs[0]["content"])
+ }
+ if msgs[1]["reasoning_content"] != "thinking..." {
+ t.Fatalf("reasoning_content not preserved, got %v", msgs[1]["reasoning_content"])
+ }
+}
+
+func TestSerializeMessages_WithMedia(t *testing.T) {
+ messages := []protocoltypes.Message{
+ {Role: "user", Content: "describe this", Media: []string{"data:image/png;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))
+ }
+
+ textPart := content[0].(map[string]any)
+ if textPart["type"] != "text" || textPart["text"] != "describe this" {
+ t.Fatalf("text part mismatch: %v", textPart)
+ }
+
+ imgPart := content[1].(map[string]any)
+ if imgPart["type"] != "image_url" {
+ t.Fatalf("expected image_url type, got %v", imgPart["type"])
+ }
+ imgURL := imgPart["image_url"].(map[string]any)
+ if imgURL["url"] != "data:image/png;base64,abc123" {
+ t.Fatalf("image url mismatch: %v", imgURL["url"])
+ }
+}
+
+func TestSerializeMessages_MediaWithToolCallID(t *testing.T) {
+ messages := []protocoltypes.Message{
+ {Role: "tool", Content: "image result", Media: []string{"data:image/png;base64,xyz"}, ToolCallID: "call_1"},
+ }
+ result := serializeMessages(messages)
+
+ data, _ := json.Marshal(result)
+ var msgs []map[string]any
+ json.Unmarshal(data, &msgs)
+
+ if msgs[0]["tool_call_id"] != "call_1" {
+ t.Fatalf("tool_call_id not preserved with media, got %v", msgs[0]["tool_call_id"])
+ }
+ // Content should be multipart array
+ if _, ok := msgs[0]["content"].([]any); !ok {
+ t.Fatalf("expected array content, got %T", msgs[0]["content"])
+ }
+}
+
+func TestSerializeMessages_StripsSystemParts(t *testing.T) {
+ messages := []protocoltypes.Message{
+ {
+ Role: "system",
+ Content: "you are helpful",
+ SystemParts: []protocoltypes.ContentBlock{
+ {Type: "text", Text: "you are helpful"},
+ },
+ },
+ }
+ result := serializeMessages(messages)
+
+ data, _ := json.Marshal(result)
+ raw := string(data)
+ if strings.Contains(raw, "system_parts") {
+ t.Fatal("system_parts should not appear in serialized output")
+ }
+}
diff --git a/pkg/providers/protocoltypes/types.go b/pkg/providers/protocoltypes/types.go
index 33f052c5a..194c1aa6f 100644
--- a/pkg/providers/protocoltypes/types.go
+++ b/pkg/providers/protocoltypes/types.go
@@ -25,11 +25,20 @@ type FunctionCall struct {
}
type LLMResponse struct {
- Content string `json:"content"`
- ReasoningContent string `json:"reasoning_content,omitempty"`
- ToolCalls []ToolCall `json:"tool_calls,omitempty"`
- FinishReason string `json:"finish_reason"`
- Usage *UsageInfo `json:"usage,omitempty"`
+ Content string `json:"content"`
+ ReasoningContent string `json:"reasoning_content,omitempty"`
+ ToolCalls []ToolCall `json:"tool_calls,omitempty"`
+ FinishReason string `json:"finish_reason"`
+ Usage *UsageInfo `json:"usage,omitempty"`
+ Reasoning string `json:"reasoning"`
+ ReasoningDetails []ReasoningDetail `json:"reasoning_details"`
+}
+
+type ReasoningDetail struct {
+ Format string `json:"format"`
+ Index int `json:"index"`
+ Type string `json:"type"`
+ Text string `json:"text"`
}
type UsageInfo struct {
@@ -56,6 +65,7 @@ type ContentBlock struct {
type Message struct {
Role string `json:"role"`
Content string `json:"content"`
+ Media []string `json:"media,omitempty"`
ReasoningContent string `json:"reasoning_content,omitempty"`
SystemParts []ContentBlock `json:"system_parts,omitempty"` // structured system blocks for cache-aware adapters
ToolCalls []ToolCall `json:"tool_calls,omitempty"`
diff --git a/pkg/providers/toolcall_utils.go b/pkg/providers/toolcall_utils.go
index 49218b1b1..a33e1eb5c 100644
--- a/pkg/providers/toolcall_utils.go
+++ b/pkg/providers/toolcall_utils.go
@@ -5,7 +5,43 @@
package providers
-import "encoding/json"
+import (
+ "encoding/json"
+ "fmt"
+ "strings"
+)
+
+// buildCLIToolsPrompt creates the tool definitions section for a CLI provider system prompt.
+func buildCLIToolsPrompt(tools []ToolDefinition) string {
+ var sb strings.Builder
+
+ sb.WriteString("## Available Tools\n\n")
+ sb.WriteString("When you need to use a tool, respond with ONLY a JSON object:\n\n")
+ sb.WriteString("```json\n")
+ sb.WriteString(
+ `{"tool_calls":[{"id":"call_xxx","type":"function","function":{"name":"tool_name","arguments":"{...}"}}]}`,
+ )
+ sb.WriteString("\n```\n\n")
+ sb.WriteString("CRITICAL: The 'arguments' field MUST be a JSON-encoded STRING.\n\n")
+ sb.WriteString("### Tool Definitions:\n\n")
+
+ for _, tool := range tools {
+ if tool.Type != "function" {
+ continue
+ }
+ sb.WriteString(fmt.Sprintf("#### %s\n", tool.Function.Name))
+ if tool.Function.Description != "" {
+ sb.WriteString(fmt.Sprintf("Description: %s\n", tool.Function.Description))
+ }
+ if len(tool.Function.Parameters) > 0 {
+ paramsJSON, _ := json.Marshal(tool.Function.Parameters)
+ sb.WriteString(fmt.Sprintf("Parameters:\n```json\n%s\n```\n", string(paramsJSON)))
+ }
+ sb.WriteString("\n")
+ }
+
+ return sb.String()
+}
// NormalizeToolCall normalizes a ToolCall to ensure all fields are properly populated.
// It handles cases where Name/Arguments might be in different locations (top-level vs Function)
diff --git a/pkg/routing/agent_id_test.go b/pkg/routing/agent_id_test.go
index 050fe0645..f9a65c969 100644
--- a/pkg/routing/agent_id_test.go
+++ b/pkg/routing/agent_id_test.go
@@ -1,6 +1,9 @@
package routing
-import "testing"
+import (
+ "strings"
+ "testing"
+)
func TestNormalizeAgentID_Empty(t *testing.T) {
if got := NormalizeAgentID(""); got != DefaultAgentID {
@@ -57,11 +60,11 @@ func TestNormalizeAgentID_AllInvalid(t *testing.T) {
}
func TestNormalizeAgentID_TruncatesAt64(t *testing.T) {
- long := ""
- for i := 0; i < 100; i++ {
- long += "a"
+ var long strings.Builder
+ for range 100 {
+ long.WriteString("a")
}
- got := NormalizeAgentID(long)
+ got := NormalizeAgentID(long.String())
if len(got) > MaxAgentIDLength {
t.Errorf("length = %d, want <= %d", len(got), MaxAgentIDLength)
}
diff --git a/pkg/routing/session_key.go b/pkg/routing/session_key.go
index e12f0d1d8..eab592bec 100644
--- a/pkg/routing/session_key.go
+++ b/pkg/routing/session_key.go
@@ -163,6 +163,15 @@ func resolveLinkedPeerID(identityLinks map[string][]string, channel, peerID stri
scopedCandidate := fmt.Sprintf("%s:%s", channel, strings.ToLower(peerID))
candidates[scopedCandidate] = true
}
+
+ // If peerID is already in canonical "platform:id" format, also add the
+ // bare ID part as a candidate for backward compatibility with identity_links
+ // that use raw IDs (e.g. "123" instead of "telegram:123").
+ if idx := strings.Index(rawCandidate, ":"); idx > 0 && idx < len(rawCandidate)-1 {
+ bareID := rawCandidate[idx+1:]
+ candidates[bareID] = true
+ }
+
if len(candidates) == 0 {
return ""
}
diff --git a/pkg/routing/session_key_test.go b/pkg/routing/session_key_test.go
index 81e4ce018..ad7a1ca02 100644
--- a/pkg/routing/session_key_test.go
+++ b/pkg/routing/session_key_test.go
@@ -115,6 +115,51 @@ func TestBuildAgentPeerSessionKey_IdentityLink(t *testing.T) {
}
}
+func TestResolveLinkedPeerID_CanonicalPeerID(t *testing.T) {
+ // When peerID is already in canonical "platform:id" format,
+ // it should match identity_links that use the bare ID.
+ links := map[string][]string{
+ "john": {"123"},
+ }
+ got := resolveLinkedPeerID(links, "telegram", "telegram:123")
+ if got != "john" {
+ t.Errorf("resolveLinkedPeerID with canonical peerID = %q, want %q", got, "john")
+ }
+}
+
+func TestResolveLinkedPeerID_CanonicalInLinks(t *testing.T) {
+ // When identity_links contain canonical IDs and peerID is canonical too
+ links := map[string][]string{
+ "john": {"telegram:123", "discord:456"},
+ }
+ got := resolveLinkedPeerID(links, "telegram", "telegram:123")
+ if got != "john" {
+ t.Errorf("resolveLinkedPeerID canonical in links = %q, want %q", got, "john")
+ }
+}
+
+func TestResolveLinkedPeerID_BarePeerIDMatchesCanonicalLink(t *testing.T) {
+ // When peerID is bare "123" and links have "telegram:123",
+ // the scoped candidate "telegram:123" should match.
+ links := map[string][]string{
+ "john": {"telegram:123"},
+ }
+ got := resolveLinkedPeerID(links, "telegram", "123")
+ if got != "john" {
+ t.Errorf("resolveLinkedPeerID bare peer matches canonical link = %q, want %q", got, "john")
+ }
+}
+
+func TestResolveLinkedPeerID_NoMatch(t *testing.T) {
+ links := map[string][]string{
+ "john": {"telegram:123"},
+ }
+ got := resolveLinkedPeerID(links, "discord", "999")
+ if got != "" {
+ t.Errorf("resolveLinkedPeerID no match = %q, want empty", got)
+ }
+}
+
func TestParseAgentSessionKey_Valid(t *testing.T) {
parsed := ParseAgentSessionKey("agent:sales:telegram:direct:user123")
if parsed == nil {
diff --git a/pkg/skills/installer.go b/pkg/skills/installer.go
index 3210509df..c9f19f25d 100644
--- a/pkg/skills/installer.go
+++ b/pkg/skills/installer.go
@@ -2,27 +2,21 @@ package skills
import (
"context"
- "encoding/json"
"fmt"
"io"
"net/http"
"os"
"path/filepath"
"time"
+
+ "github.com/sipeed/picoclaw/pkg/fileutil"
+ "github.com/sipeed/picoclaw/pkg/utils"
)
type SkillInstaller struct {
workspace string
}
-type AvailableSkill struct {
- Name string `json:"name"`
- Repository string `json:"repository"`
- Description string `json:"description"`
- Author string `json:"author"`
- Tags []string `json:"tags"`
-}
-
func NewSkillInstaller(workspace string) *SkillInstaller {
return &SkillInstaller{
workspace: workspace,
@@ -44,7 +38,7 @@ func (si *SkillInstaller) InstallFromGitHub(ctx context.Context, repo string) er
return fmt.Errorf("failed to create request: %w", err)
}
- resp, err := client.Do(req)
+ resp, err := utils.DoRequestWithRetry(client, req)
if err != nil {
return fmt.Errorf("failed to fetch skill: %w", err)
}
@@ -64,7 +58,9 @@ func (si *SkillInstaller) InstallFromGitHub(ctx context.Context, repo string) er
}
skillPath := filepath.Join(skillDir, "SKILL.md")
- if err := os.WriteFile(skillPath, body, 0o644); err != nil {
+
+ // Use unified atomic write utility with explicit sync for flash storage reliability.
+ if err := fileutil.WriteFileAtomic(skillPath, body, 0o600); err != nil {
return fmt.Errorf("failed to write skill file: %w", err)
}
@@ -84,35 +80,3 @@ func (si *SkillInstaller) Uninstall(skillName string) error {
return nil
}
-
-func (si *SkillInstaller) ListAvailableSkills(ctx context.Context) ([]AvailableSkill, error) {
- url := "https://raw.githubusercontent.com/sipeed/picoclaw-skills/main/skills.json"
-
- client := &http.Client{Timeout: 15 * time.Second}
- req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
- if err != nil {
- return nil, fmt.Errorf("failed to create request: %w", err)
- }
-
- resp, err := client.Do(req)
- if err != nil {
- return nil, fmt.Errorf("failed to fetch skills list: %w", err)
- }
- defer resp.Body.Close()
-
- if resp.StatusCode != 200 {
- return nil, fmt.Errorf("failed to fetch skills list: HTTP %d", resp.StatusCode)
- }
-
- body, err := io.ReadAll(resp.Body)
- if err != nil {
- return nil, fmt.Errorf("failed to read response: %w", err)
- }
-
- var skills []AvailableSkill
- if err := json.Unmarshal(body, &skills); err != nil {
- return nil, fmt.Errorf("failed to parse skills list: %w", err)
- }
-
- return skills, nil
-}
diff --git a/pkg/skills/loader.go b/pkg/skills/loader.go
index 5749d8983..30d84635a 100644
--- a/pkg/skills/loader.go
+++ b/pkg/skills/loader.go
@@ -13,7 +13,11 @@ import (
"github.com/sipeed/picoclaw/pkg/logger"
)
-var namePattern = regexp.MustCompile(`^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$`)
+var (
+ namePattern = regexp.MustCompile(`^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$`)
+ reFrontmatter = regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---`)
+ reStripFrontmatter = regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---(?:\r\n|\n|\r)*`)
+)
const (
MaxNameLength = 64
@@ -60,6 +64,29 @@ type SkillsLoader struct {
builtinSkills string // builtin skills
}
+// SkillRoots returns all unique skill root directories used by this loader.
+// The order follows resolution priority: workspace > global > builtin.
+func (sl *SkillsLoader) SkillRoots() []string {
+ roots := []string{sl.workspaceSkills, sl.globalSkills, sl.builtinSkills}
+ seen := make(map[string]struct{}, len(roots))
+ out := make([]string, 0, len(roots))
+
+ for _, root := range roots {
+ trimmed := strings.TrimSpace(root)
+ if trimmed == "" {
+ continue
+ }
+ clean := filepath.Clean(trimmed)
+ if _, ok := seen[clean]; ok {
+ continue
+ }
+ seen[clean] = struct{}{}
+ out = append(out, clean)
+ }
+
+ return out
+}
+
func NewSkillsLoader(workspace string, globalSkills string, builtinSkills string) *SkillsLoader {
return &SkillsLoader{
workspace: workspace,
@@ -236,7 +263,7 @@ func (sl *SkillsLoader) parseSimpleYAML(content string) map[string]string {
normalized := strings.ReplaceAll(content, "\r\n", "\n")
normalized = strings.ReplaceAll(normalized, "\r", "\n")
- for _, line := range strings.Split(normalized, "\n") {
+ for line := range strings.SplitSeq(normalized, "\n") {
line = strings.TrimSpace(line)
if line == "" || strings.HasPrefix(line, "#") {
continue
@@ -257,10 +284,7 @@ func (sl *SkillsLoader) parseSimpleYAML(content string) map[string]string {
func (sl *SkillsLoader) extractFrontmatter(content string) string {
// Support \n (Unix), \r\n (Windows), and \r (classic Mac) line endings for frontmatter blocks
- // (?s) enables DOTALL so . matches newlines;
- // ^--- at start, then ... --- at start of line, honoring all three line ending types
- re := regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---`)
- match := re.FindStringSubmatch(content)
+ match := reFrontmatter.FindStringSubmatch(content)
if len(match) > 1 {
return match[1]
}
@@ -268,12 +292,7 @@ func (sl *SkillsLoader) extractFrontmatter(content string) string {
}
func (sl *SkillsLoader) stripFrontmatter(content string) string {
- // Support \n (Unix), \r\n (Windows), and \r (classic Mac) line endings for frontmatter blocks
- // (?s) enables DOTALL so . matches newlines;
- // ^--- at start, then ... --- at start of line, honoring all three line ending types
- // Match zero or more trailing line endings after closing --- (handles both with and without blank lines)
- re := regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---(?:\r\n|\n|\r)*`)
- return re.ReplaceAllString(content, "")
+ return reStripFrontmatter.ReplaceAllString(content, "")
}
func escapeXML(s string) string {
diff --git a/pkg/skills/loader_test.go b/pkg/skills/loader_test.go
index 9428bea62..31619f9c2 100644
--- a/pkg/skills/loader_test.go
+++ b/pkg/skills/loader_test.go
@@ -326,3 +326,19 @@ func TestStripFrontmatter(t *testing.T) {
})
}
}
+
+func TestSkillRootsTrimsWhitespaceAndDedups(t *testing.T) {
+ tmp := t.TempDir()
+ workspace := filepath.Join(tmp, "workspace")
+ global := filepath.Join(tmp, "global")
+ builtin := filepath.Join(tmp, "builtin")
+
+ sl := NewSkillsLoader(workspace, " "+global+" ", "\t"+builtin+"\n")
+ roots := sl.SkillRoots()
+
+ assert.Equal(t, []string{
+ filepath.Join(workspace, "skills"),
+ global,
+ builtin,
+ }, roots)
+}
diff --git a/pkg/skills/search_cache.go b/pkg/skills/search_cache.go
index 5d7d2797e..1686e3f98 100644
--- a/pkg/skills/search_cache.go
+++ b/pkg/skills/search_cache.go
@@ -1,7 +1,7 @@
package skills
import (
- "sort"
+ "slices"
"strings"
"sync"
"time"
@@ -183,7 +183,7 @@ func buildTrigrams(s string) []uint32 {
}
// Sort and Deduplication
- sort.Slice(trigrams, func(i, j int) bool { return trigrams[i] < trigrams[j] })
+ slices.Sort(trigrams)
n := 1
for i := 1; i < len(trigrams); i++ {
if trigrams[i] != trigrams[i-1] {
diff --git a/pkg/skills/search_cache_test.go b/pkg/skills/search_cache_test.go
index 816bdfb93..6bbb0e6eb 100644
--- a/pkg/skills/search_cache_test.go
+++ b/pkg/skills/search_cache_test.go
@@ -153,7 +153,7 @@ func TestSearchCacheConcurrency(t *testing.T) {
// Concurrent writes
go func() {
- for i := 0; i < 100; i++ {
+ for i := range 100 {
cache.Put("query-write-"+string(rune('a'+i%26)), []SearchResult{{Slug: "x"}})
}
done <- struct{}{}
@@ -161,7 +161,7 @@ func TestSearchCacheConcurrency(t *testing.T) {
// Concurrent reads
go func() {
- for i := 0; i < 100; i++ {
+ for range 100 {
cache.Get("query-write-a")
}
done <- struct{}{}
diff --git a/pkg/state/state.go b/pkg/state/state.go
index 1a92f82ed..57f371f12 100644
--- a/pkg/state/state.go
+++ b/pkg/state/state.go
@@ -8,6 +8,8 @@ import (
"path/filepath"
"sync"
"time"
+
+ "github.com/sipeed/picoclaw/pkg/fileutil"
)
// State represents the persistent state for a workspace.
@@ -38,7 +40,9 @@ func NewManager(workspace string) *Manager {
oldStateFile := filepath.Join(workspace, "state.json")
// Create state directory if it doesn't exist
- os.MkdirAll(stateDir, 0o755)
+ if err := os.MkdirAll(stateDir, 0o755); err != nil {
+ log.Fatalf("[FATAL] state: failed to create state directory: %v", err)
+ }
sm := &Manager{
workspace: workspace,
@@ -52,13 +56,17 @@ func NewManager(workspace string) *Manager {
if data, err := os.ReadFile(oldStateFile); err == nil {
if err := json.Unmarshal(data, sm.state); err == nil {
// Migrate to new location
- sm.saveAtomic()
+ if err := sm.saveAtomic(); err != nil {
+ log.Printf("[WARN] state: failed to save state: %v", err)
+ }
log.Printf("[INFO] state: migrated state from %s to %s", oldStateFile, stateFile)
}
}
} else {
// Load from new location
- sm.load()
+ if err := sm.load(); err != nil {
+ log.Printf("[WARN] state: failed to load state: %v", err)
+ }
}
return sm
@@ -124,33 +132,20 @@ func (sm *Manager) GetTimestamp() time.Time {
// saveAtomic performs an atomic save using temp file + rename.
// This ensures that the state file is never corrupted:
// 1. Write to a temp file
-// 2. Rename temp file to target (atomic on POSIX systems)
-// 3. If rename fails, cleanup the temp file
+// 2. Sync to disk (critical for SD cards/flash storage)
+// 3. Rename temp file to target (atomic on POSIX systems)
+// 4. If rename fails, cleanup the temp file
//
// Must be called with the lock held.
func (sm *Manager) saveAtomic() error {
- // Create temp file in the same directory as the target
- tempFile := sm.stateFile + ".tmp"
-
- // Marshal state to JSON
+ // Use unified atomic write utility with explicit sync for flash storage reliability.
+ // Using 0o600 (owner read/write only) for secure default permissions.
data, err := json.MarshalIndent(sm.state, "", " ")
if err != nil {
return fmt.Errorf("failed to marshal state: %w", err)
}
- // Write to temp file
- if err := os.WriteFile(tempFile, data, 0o644); err != nil {
- return fmt.Errorf("failed to write temp file: %w", err)
- }
-
- // Atomic rename from temp to target
- if err := os.Rename(tempFile, sm.stateFile); err != nil {
- // Cleanup temp file if rename fails
- os.Remove(tempFile)
- return fmt.Errorf("failed to rename temp file: %w", err)
- }
-
- return nil
+ return fileutil.WriteFileAtomic(sm.stateFile, data, 0o600)
}
// load loads the state from disk.
diff --git a/pkg/state/state_test.go b/pkg/state/state_test.go
index f717a5bb4..e5e116ef6 100644
--- a/pkg/state/state_test.go
+++ b/pkg/state/state_test.go
@@ -2,8 +2,10 @@ package state
import (
"encoding/json"
+ "errors"
"fmt"
"os"
+ "os/exec"
"path/filepath"
"testing"
)
@@ -135,7 +137,7 @@ func TestConcurrentAccess(t *testing.T) {
// Test concurrent writes
done := make(chan bool, 10)
- for i := 0; i < 10; i++ {
+ for i := range 10 {
go func(idx int) {
channel := fmt.Sprintf("channel-%d", idx)
sm.SetLastChannel(channel)
@@ -144,7 +146,7 @@ func TestConcurrentAccess(t *testing.T) {
}
// Wait for all goroutines to complete
- for i := 0; i < 10; i++ {
+ for range 10 {
<-done
}
@@ -214,3 +216,39 @@ func TestNewManager_EmptyWorkspace(t *testing.T) {
t.Error("Expected zero timestamp for new state")
}
}
+
+func TestNewManager_MkdirFailureCrashes(t *testing.T) {
+ // Since log.Fatalf calls os.Exit(1), we cannot test it normally
+ // Otherwise, the test suite would stop altogether.
+ // We use the standard pattern of Go: rerun this test in a subprocess.
+ if os.Getenv("BE_CRASHER") == "1" {
+ tmpDir := os.Getenv("CRASH_DIR")
+
+ statePath := filepath.Join(tmpDir, "state")
+ if err := os.WriteFile(statePath, []byte("I'm a file, not a folder"), 0o644); err != nil {
+ fmt.Printf("setup failed: %v", err)
+ os.Exit(0)
+ }
+
+ NewManager(tmpDir)
+ os.Exit(0)
+ }
+
+ tmpDir, err := os.MkdirTemp("", "state-crash-test-*")
+ if err != nil {
+ t.Fatalf("Failed to create temp dir: %v", err)
+ }
+ defer os.RemoveAll(tmpDir)
+
+ cmd := exec.Command(os.Args[0], "-test.run=TestNewManager_MkdirFailureCrashes")
+ cmd.Env = append(os.Environ(), "BE_CRASHER=1", "CRASH_DIR="+tmpDir)
+
+ err = cmd.Run()
+
+ var e *exec.ExitError
+ if errors.As(err, &e) && !e.Success() {
+ return
+ }
+
+ t.Fatalf("The process ended without error, a crash was expected via os.Exit(1). Err: %v", err)
+}
diff --git a/pkg/tools/cron.go b/pkg/tools/cron.go
index 562fffc84..6888d1326 100644
--- a/pkg/tools/cron.go
+++ b/pkg/tools/cron.go
@@ -3,6 +3,7 @@ package tools
import (
"context"
"fmt"
+ "strings"
"sync"
"time"
@@ -33,15 +34,19 @@ type CronTool struct {
func NewCronTool(
cronService *cron.CronService, executor JobExecutor, msgBus *bus.MessageBus, workspace string, restrict bool,
execTimeout time.Duration, config *config.Config,
-) *CronTool {
- execTool := NewExecToolWithConfig(workspace, restrict, config)
+) (*CronTool, error) {
+ execTool, err := NewExecToolWithConfig(workspace, restrict, config)
+ if err != nil {
+ return nil, fmt.Errorf("unable to configure exec tool: %w", err)
+ }
+
execTool.SetTimeout(execTimeout)
return &CronTool{
cronService: cronService,
executor: executor,
msgBus: msgBus,
execTool: execTool,
- }
+ }, nil
}
// Name returns the tool name
@@ -218,7 +223,8 @@ func (t *CronTool) listJobs() *ToolResult {
return SilentResult("No scheduled jobs")
}
- result := "Scheduled jobs:\n"
+ var result strings.Builder
+ result.WriteString("Scheduled jobs:\n")
for _, j := range jobs {
var scheduleInfo string
if j.Schedule.Kind == "every" && j.Schedule.EveryMS != nil {
@@ -230,10 +236,10 @@ func (t *CronTool) listJobs() *ToolResult {
} else {
scheduleInfo = "unknown"
}
- result += fmt.Sprintf("- %s (id: %s, %s)\n", j.Name, j.ID, scheduleInfo)
+ result.WriteString(fmt.Sprintf("- %s (id: %s, %s)\n", j.Name, j.ID, scheduleInfo))
}
- return SilentResult(result)
+ return SilentResult(result.String())
}
func (t *CronTool) removeJob(args map[string]any) *ToolResult {
@@ -294,7 +300,9 @@ func (t *CronTool) ExecuteJob(ctx context.Context, job *cron.CronJob) string {
output = fmt.Sprintf("Scheduled command '%s' executed:\n%s", job.Payload.Command, result.ForLLM)
}
- t.msgBus.PublishOutbound(bus.OutboundMessage{
+ pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer pubCancel()
+ t.msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
Channel: channel,
ChatID: chatID,
Content: output,
@@ -304,7 +312,9 @@ func (t *CronTool) ExecuteJob(ctx context.Context, job *cron.CronJob) string {
// If deliver=true, send message directly without agent processing
if job.Payload.Deliver {
- t.msgBus.PublishOutbound(bus.OutboundMessage{
+ pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer pubCancel()
+ t.msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
Channel: channel,
ChatID: chatID,
Content: job.Payload.Message,
diff --git a/pkg/tools/edit.go b/pkg/tools/edit.go
index d3ab267bf..d5bebf4a2 100644
--- a/pkg/tools/edit.go
+++ b/pkg/tools/edit.go
@@ -5,6 +5,7 @@ import (
"errors"
"fmt"
"io/fs"
+ "regexp"
"strings"
)
@@ -15,14 +16,12 @@ type EditFileTool struct {
}
// NewEditFileTool creates a new EditFileTool with optional directory restriction.
-func NewEditFileTool(workspace string, restrict bool) *EditFileTool {
- var fs fileSystem
- if restrict {
- fs = &sandboxFs{workspace: workspace}
- } else {
- fs = &hostFs{}
+func NewEditFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *EditFileTool {
+ var patterns []*regexp.Regexp
+ if len(allowPaths) > 0 {
+ patterns = allowPaths[0]
}
- return &EditFileTool{fs: fs}
+ return &EditFileTool{fs: buildFs(workspace, restrict, patterns)}
}
func (t *EditFileTool) Name() string {
@@ -80,14 +79,12 @@ type AppendFileTool struct {
fs fileSystem
}
-func NewAppendFileTool(workspace string, restrict bool) *AppendFileTool {
- var fs fileSystem
- if restrict {
- fs = &sandboxFs{workspace: workspace}
- } else {
- fs = &hostFs{}
+func NewAppendFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *AppendFileTool {
+ var patterns []*regexp.Regexp
+ if len(allowPaths) > 0 {
+ patterns = allowPaths[0]
}
- return &AppendFileTool{fs: fs}
+ return &AppendFileTool{fs: buildFs(workspace, restrict, patterns)}
}
func (t *AppendFileTool) Name() string {
diff --git a/pkg/tools/filesystem.go b/pkg/tools/filesystem.go
index 37db8b4ae..cd8da3195 100644
--- a/pkg/tools/filesystem.go
+++ b/pkg/tools/filesystem.go
@@ -6,8 +6,11 @@ import (
"io/fs"
"os"
"path/filepath"
+ "regexp"
"strings"
"time"
+
+ "github.com/sipeed/picoclaw/pkg/fileutil"
)
// validatePath ensures the given path is within the workspace if restrict is true.
@@ -85,14 +88,12 @@ type ReadFileTool struct {
fs fileSystem
}
-func NewReadFileTool(workspace string, restrict bool) *ReadFileTool {
- var fs fileSystem
- if restrict {
- fs = &sandboxFs{workspace: workspace}
- } else {
- fs = &hostFs{}
+func NewReadFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *ReadFileTool {
+ var patterns []*regexp.Regexp
+ if len(allowPaths) > 0 {
+ patterns = allowPaths[0]
}
- return &ReadFileTool{fs: fs}
+ return &ReadFileTool{fs: buildFs(workspace, restrict, patterns)}
}
func (t *ReadFileTool) Name() string {
@@ -133,14 +134,12 @@ type WriteFileTool struct {
fs fileSystem
}
-func NewWriteFileTool(workspace string, restrict bool) *WriteFileTool {
- var fs fileSystem
- if restrict {
- fs = &sandboxFs{workspace: workspace}
- } else {
- fs = &hostFs{}
+func NewWriteFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *WriteFileTool {
+ var patterns []*regexp.Regexp
+ if len(allowPaths) > 0 {
+ patterns = allowPaths[0]
}
- return &WriteFileTool{fs: fs}
+ return &WriteFileTool{fs: buildFs(workspace, restrict, patterns)}
}
func (t *WriteFileTool) Name() string {
@@ -190,14 +189,12 @@ type ListDirTool struct {
fs fileSystem
}
-func NewListDirTool(workspace string, restrict bool) *ListDirTool {
- var fs fileSystem
- if restrict {
- fs = &sandboxFs{workspace: workspace}
- } else {
- fs = &hostFs{}
+func NewListDirTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *ListDirTool {
+ var patterns []*regexp.Regexp
+ if len(allowPaths) > 0 {
+ patterns = allowPaths[0]
}
- return &ListDirTool{fs: fs}
+ return &ListDirTool{fs: buildFs(workspace, restrict, patterns)}
}
func (t *ListDirTool) Name() string {
@@ -276,25 +273,9 @@ func (h *hostFs) ReadDir(path string) ([]os.DirEntry, error) {
}
func (h *hostFs) WriteFile(path string, data []byte) error {
- dir := filepath.Dir(path)
- if err := os.MkdirAll(dir, 0o755); err != nil {
- return fmt.Errorf("failed to create parent directories: %w", err)
- }
-
- // We use a "write-then-rename" pattern here to ensure an atomic write.
- // This prevents the target file from being left in a truncated or partial state
- // if the operation is interrupted, as the rename operation is atomic on Linux.
- tmpPath := fmt.Sprintf("%s.%d.tmp", path, time.Now().UnixNano())
- if err := os.WriteFile(tmpPath, data, 0o644); err != nil {
- os.Remove(tmpPath) // Ensure cleanup of partial/empty temp file
- return fmt.Errorf("failed to write temp file: %w", err)
- }
-
- if err := os.Rename(tmpPath, path); err != nil {
- os.Remove(tmpPath)
- return fmt.Errorf("failed to replace original file: %w", err)
- }
- return nil
+ // Use unified atomic write utility with explicit sync for flash storage reliability.
+ // Using 0o600 (owner read/write only) for secure default permissions.
+ return fileutil.WriteFileAtomic(path, data, 0o600)
}
// sandboxFs is a sandboxed fileSystem that operates within a strictly defined workspace using os.Root.
@@ -351,20 +332,46 @@ func (r *sandboxFs) WriteFile(path string, data []byte) error {
}
}
- // We use a "write-then-rename" pattern here to ensure an atomic write.
- // This prevents the target file from being left in a truncated or partial state
- // if the operation is interrupted, as the rename operation is atomic on Linux.
- tmpRelPath := fmt.Sprintf("%s.%d.tmp", relPath, time.Now().UnixNano())
+ // Use atomic write pattern with explicit sync for flash storage reliability.
+ // Using 0o600 (owner read/write only) for secure default permissions.
+ tmpRelPath := fmt.Sprintf(".tmp-%d-%d", os.Getpid(), time.Now().UnixNano())
- if err := root.WriteFile(tmpRelPath, data, 0o644); err != nil {
- root.Remove(tmpRelPath) // Ensure cleanup of partial/empty temp file
- return fmt.Errorf("failed to write to temp file: %w", err)
+ tmpFile, err := root.OpenFile(tmpRelPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
+ if err != nil {
+ root.Remove(tmpRelPath)
+ return fmt.Errorf("failed to open temp file: %w", err)
+ }
+
+ if _, err := tmpFile.Write(data); err != nil {
+ tmpFile.Close()
+ root.Remove(tmpRelPath)
+ return fmt.Errorf("failed to write temp file: %w", err)
+ }
+
+ // CRITICAL: Force sync to storage medium before rename.
+ // This ensures data is physically written to disk, not just cached.
+ if err := tmpFile.Sync(); err != nil {
+ tmpFile.Close()
+ root.Remove(tmpRelPath)
+ return fmt.Errorf("failed to sync temp file: %w", err)
+ }
+
+ if err := tmpFile.Close(); err != nil {
+ root.Remove(tmpRelPath)
+ return fmt.Errorf("failed to close temp file: %w", err)
}
if err := root.Rename(tmpRelPath, relPath); err != nil {
root.Remove(tmpRelPath)
return fmt.Errorf("failed to rename temp file over target: %w", err)
}
+
+ // Sync directory to ensure rename is durable
+ if dirFile, err := root.Open("."); err == nil {
+ _ = dirFile.Sync()
+ dirFile.Close()
+ }
+
return nil
})
}
@@ -382,6 +389,57 @@ func (r *sandboxFs) ReadDir(path string) ([]os.DirEntry, error) {
return entries, err
}
+// whitelistFs wraps a sandboxFs and allows access to specific paths outside
+// the workspace when they match any of the provided patterns.
+type whitelistFs struct {
+ sandbox *sandboxFs
+ host hostFs
+ patterns []*regexp.Regexp
+}
+
+func (w *whitelistFs) matches(path string) bool {
+ for _, p := range w.patterns {
+ if p.MatchString(path) {
+ return true
+ }
+ }
+ return false
+}
+
+func (w *whitelistFs) ReadFile(path string) ([]byte, error) {
+ if w.matches(path) {
+ return w.host.ReadFile(path)
+ }
+ return w.sandbox.ReadFile(path)
+}
+
+func (w *whitelistFs) WriteFile(path string, data []byte) error {
+ if w.matches(path) {
+ return w.host.WriteFile(path, data)
+ }
+ return w.sandbox.WriteFile(path, data)
+}
+
+func (w *whitelistFs) ReadDir(path string) ([]os.DirEntry, error) {
+ if w.matches(path) {
+ return w.host.ReadDir(path)
+ }
+ return w.sandbox.ReadDir(path)
+}
+
+// buildFs returns the appropriate fileSystem implementation based on restriction
+// settings and optional path whitelist patterns.
+func buildFs(workspace string, restrict bool, patterns []*regexp.Regexp) fileSystem {
+ if !restrict {
+ return &hostFs{}
+ }
+ sandbox := &sandboxFs{workspace: workspace}
+ if len(patterns) > 0 {
+ return &whitelistFs{sandbox: sandbox, patterns: patterns}
+ }
+ return sandbox
+}
+
// Helper to get a safe relative path for os.Root usage
func getSafeRelPath(workspace, path string) (string, error) {
if workspace == "" {
diff --git a/pkg/tools/filesystem_test.go b/pkg/tools/filesystem_test.go
index 6f896e22d..666004cd4 100644
--- a/pkg/tools/filesystem_test.go
+++ b/pkg/tools/filesystem_test.go
@@ -5,6 +5,7 @@ import (
"io"
"os"
"path/filepath"
+ "regexp"
"strings"
"testing"
@@ -486,3 +487,36 @@ func TestRootRW_Write(t *testing.T) {
assert.NoError(t, err)
assert.Equal(t, newData, content)
}
+
+// TestWhitelistFs_AllowsMatchingPaths verifies that whitelistFs allows access to
+// paths matching the whitelist patterns while blocking non-matching paths.
+func TestWhitelistFs_AllowsMatchingPaths(t *testing.T) {
+ workspace := t.TempDir()
+ outsideDir := t.TempDir()
+ outsideFile := filepath.Join(outsideDir, "allowed.txt")
+ os.WriteFile(outsideFile, []byte("outside content"), 0o644)
+
+ // Pattern allows access to the outsideDir.
+ patterns := []*regexp.Regexp{regexp.MustCompile(`^` + regexp.QuoteMeta(outsideDir))}
+
+ tool := NewReadFileTool(workspace, true, patterns)
+
+ // Read from whitelisted path should succeed.
+ result := tool.Execute(context.Background(), map[string]any{"path": outsideFile})
+ if result.IsError {
+ t.Errorf("expected whitelisted path to be readable, got: %s", result.ForLLM)
+ }
+ if !strings.Contains(result.ForLLM, "outside content") {
+ t.Errorf("expected file content, got: %s", result.ForLLM)
+ }
+
+ // Read from non-whitelisted path outside workspace should fail.
+ otherDir := t.TempDir()
+ otherFile := filepath.Join(otherDir, "blocked.txt")
+ os.WriteFile(otherFile, []byte("blocked"), 0o644)
+
+ result = tool.Execute(context.Background(), map[string]any{"path": otherFile})
+ if !result.IsError {
+ t.Errorf("expected non-whitelisted path to be blocked, got: %s", result.ForLLM)
+ }
+}
diff --git a/pkg/tools/mcp_tool.go b/pkg/tools/mcp_tool.go
new file mode 100644
index 000000000..6e53cf354
--- /dev/null
+++ b/pkg/tools/mcp_tool.go
@@ -0,0 +1,246 @@
+package tools
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "hash/fnv"
+ "strings"
+
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// MCPManager defines the interface for MCP manager operations
+// This allows for easier testing with mock implementations
+type MCPManager interface {
+ CallTool(
+ ctx context.Context,
+ serverName, toolName string,
+ arguments map[string]any,
+ ) (*mcp.CallToolResult, error)
+}
+
+// MCPTool wraps an MCP tool to implement the Tool interface
+type MCPTool struct {
+ manager MCPManager
+ serverName string
+ tool *mcp.Tool
+}
+
+// NewMCPTool creates a new MCP tool wrapper
+func NewMCPTool(manager MCPManager, serverName string, tool *mcp.Tool) *MCPTool {
+ return &MCPTool{
+ manager: manager,
+ serverName: serverName,
+ tool: tool,
+ }
+}
+
+// sanitizeIdentifierComponent normalizes a string so it can be safely used
+// as part of a tool/function identifier for downstream providers.
+// It:
+// - lowercases the string
+// - replaces any character not in [a-z0-9_-] with '_'
+// - collapses multiple consecutive '_' into a single '_'
+// - trims leading/trailing '_'
+// - falls back to "unnamed" if the result is empty
+// - truncates overly long components to a reasonable length
+func sanitizeIdentifierComponent(s string) string {
+ const maxLen = 64
+
+ s = strings.ToLower(s)
+ var b strings.Builder
+ b.Grow(len(s))
+
+ prevUnderscore := false
+ for _, r := range s {
+ isAllowed := (r >= 'a' && r <= 'z') ||
+ (r >= '0' && r <= '9') ||
+ r == '_' || r == '-'
+
+ if !isAllowed {
+ // Normalize any disallowed character to '_'
+ if !prevUnderscore {
+ b.WriteRune('_')
+ prevUnderscore = true
+ }
+ continue
+ }
+
+ if r == '_' {
+ if prevUnderscore {
+ continue
+ }
+ prevUnderscore = true
+ } else {
+ prevUnderscore = false
+ }
+
+ b.WriteRune(r)
+ }
+
+ result := strings.Trim(b.String(), "_")
+ if result == "" {
+ result = "unnamed"
+ }
+
+ if len(result) > maxLen {
+ result = result[:maxLen]
+ }
+
+ return result
+}
+
+// Name returns the tool name, prefixed with the server name.
+// The total length is capped at 64 characters (OpenAI-compatible API limit).
+// A short hash of the original (unsanitized) server and tool names is appended
+// whenever sanitization is lossy or the name is truncated, ensuring that two
+// names which differ only in disallowed characters remain distinct after sanitization.
+func (t *MCPTool) Name() string {
+ // Prefix with server name to avoid conflicts, and sanitize components
+ sanitizedServer := sanitizeIdentifierComponent(t.serverName)
+ sanitizedTool := sanitizeIdentifierComponent(t.tool.Name)
+ full := fmt.Sprintf("mcp_%s_%s", sanitizedServer, sanitizedTool)
+
+ // Check if sanitization was lossless (only lowercasing, no char replacement/truncation)
+ lossless := strings.ToLower(t.serverName) == sanitizedServer &&
+ strings.ToLower(t.tool.Name) == sanitizedTool
+
+ const maxTotal = 64
+ if lossless && len(full) <= maxTotal {
+ return full
+ }
+
+ // Sanitization was lossy or name too long: append hash of the ORIGINAL names
+ // (not the sanitized names) so different originals always yield different hashes.
+ h := fnv.New32a()
+ _, _ = h.Write([]byte(t.serverName + "\x00" + t.tool.Name))
+ suffix := fmt.Sprintf("%08x", h.Sum32()) // 8 chars
+
+ base := full
+ if len(base) > maxTotal-9 {
+ base = strings.TrimRight(full[:maxTotal-9], "_")
+ }
+ return base + "_" + suffix
+}
+
+// Description returns the tool description
+func (t *MCPTool) Description() string {
+ desc := t.tool.Description
+ if desc == "" {
+ desc = fmt.Sprintf("MCP tool from %s server", t.serverName)
+ }
+ // Add server info to description
+ return fmt.Sprintf("[MCP:%s] %s", t.serverName, desc)
+}
+
+// Parameters returns the tool parameters schema
+func (t *MCPTool) Parameters() map[string]any {
+ // The InputSchema is already a JSON Schema object
+ schema := t.tool.InputSchema
+
+ // Handle nil schema
+ if schema == nil {
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{},
+ "required": []string{},
+ }
+ }
+
+ // Try direct conversion first (fast path)
+ if schemaMap, ok := schema.(map[string]any); ok {
+ return schemaMap
+ }
+
+ // Handle json.RawMessage and []byte - unmarshal directly
+ var jsonData []byte
+ if rawMsg, ok := schema.(json.RawMessage); ok {
+ jsonData = rawMsg
+ } else if bytes, ok := schema.([]byte); ok {
+ jsonData = bytes
+ }
+
+ if jsonData != nil {
+ var result map[string]any
+ if err := json.Unmarshal(jsonData, &result); err == nil {
+ return result
+ }
+ // Fallback on error
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{},
+ "required": []string{},
+ }
+ }
+
+ // For other types (structs, etc.), convert via JSON marshal/unmarshal
+ var err error
+ jsonData, err = json.Marshal(schema)
+ if err != nil {
+ // Fallback to empty schema if marshaling fails
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{},
+ "required": []string{},
+ }
+ }
+
+ var result map[string]any
+ if err := json.Unmarshal(jsonData, &result); err != nil {
+ // Fallback to empty schema if unmarshaling fails
+ return map[string]any{
+ "type": "object",
+ "properties": map[string]any{},
+ "required": []string{},
+ }
+ }
+
+ return result
+}
+
+// Execute executes the MCP tool
+func (t *MCPTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
+ result, err := t.manager.CallTool(ctx, t.serverName, t.tool.Name, args)
+ if err != nil {
+ return ErrorResult(fmt.Sprintf("MCP tool execution failed: %v", err)).WithError(err)
+ }
+
+ if result == nil {
+ nilErr := fmt.Errorf("MCP tool returned nil result without error")
+ return ErrorResult("MCP tool execution failed: nil result").WithError(nilErr)
+ }
+
+ // Handle error result from server
+ if result.IsError {
+ errMsg := extractContentText(result.Content)
+ return ErrorResult(fmt.Sprintf("MCP tool returned error: %s", errMsg)).
+ WithError(fmt.Errorf("MCP tool error: %s", errMsg))
+ }
+
+ // Extract text content from result
+ output := extractContentText(result.Content)
+
+ return &ToolResult{
+ ForLLM: output,
+ IsError: false,
+ }
+}
+
+// extractContentText extracts text from MCP content array
+func extractContentText(content []mcp.Content) string {
+ var parts []string
+ for _, c := range content {
+ switch v := c.(type) {
+ case *mcp.TextContent:
+ parts = append(parts, v.Text)
+ case *mcp.ImageContent:
+ // For images, just indicate that an image was returned
+ parts = append(parts, fmt.Sprintf("[Image: %s]", v.MIMEType))
+ default:
+ // For other content types, use string representation
+ parts = append(parts, fmt.Sprintf("[Content: %T]", v))
+ }
+ }
+ return strings.Join(parts, "\n")
+}
diff --git a/pkg/tools/mcp_tool_test.go b/pkg/tools/mcp_tool_test.go
new file mode 100644
index 000000000..95bb0f992
--- /dev/null
+++ b/pkg/tools/mcp_tool_test.go
@@ -0,0 +1,492 @@
+package tools
+
+import (
+ "context"
+ "fmt"
+ "strings"
+ "testing"
+
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// MockMCPManager is a mock implementation of MCPManager interface for testing
+type MockMCPManager struct {
+ callToolFunc func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error)
+}
+
+func (m *MockMCPManager) CallTool(
+ ctx context.Context,
+ serverName, toolName string,
+ arguments map[string]any,
+) (*mcp.CallToolResult, error) {
+ if m.callToolFunc != nil {
+ return m.callToolFunc(ctx, serverName, toolName, arguments)
+ }
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "mock result"},
+ },
+ IsError: false,
+ }, nil
+}
+
+// TestNewMCPTool verifies MCP tool creation
+func TestNewMCPTool(t *testing.T) {
+ manager := &MockMCPManager{}
+ tool := &mcp.Tool{
+ Name: "test_tool",
+ Description: "A test tool",
+ InputSchema: map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "input": map[string]any{
+ "type": "string",
+ "description": "Test input",
+ },
+ },
+ },
+ }
+
+ mcpTool := NewMCPTool(manager, "test_server", tool)
+
+ if mcpTool == nil {
+ t.Fatal("NewMCPTool should not return nil")
+ }
+ // Verify tool properties we can access
+ if mcpTool.Name() != "mcp_test_server_test_tool" {
+ t.Errorf("Expected tool name with prefix, got '%s'", mcpTool.Name())
+ }
+}
+
+// TestMCPTool_Name verifies tool name with server prefix
+func TestMCPTool_Name(t *testing.T) {
+ tests := []struct {
+ name string
+ serverName string
+ toolName string
+ expected string
+ }{
+ {
+ name: "simple name",
+ serverName: "github",
+ toolName: "create_issue",
+ expected: "mcp_github_create_issue",
+ },
+ {
+ name: "filesystem server",
+ serverName: "filesystem",
+ toolName: "read_file",
+ expected: "mcp_filesystem_read_file",
+ },
+ {
+ name: "remote server",
+ serverName: "remote-api",
+ toolName: "fetch_data",
+ expected: "mcp_remote-api_fetch_data",
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ manager := &MockMCPManager{}
+ tool := &mcp.Tool{Name: tt.toolName}
+ mcpTool := NewMCPTool(manager, tt.serverName, tool)
+
+ result := mcpTool.Name()
+ if result != tt.expected {
+ t.Errorf("Expected name '%s', got '%s'", tt.expected, result)
+ }
+ })
+ }
+}
+
+// TestMCPTool_Description verifies tool description generation
+func TestMCPTool_Description(t *testing.T) {
+ tests := []struct {
+ name string
+ serverName string
+ toolDescription string
+ expectContains []string
+ }{
+ {
+ name: "with description",
+ serverName: "github",
+ toolDescription: "Create a GitHub issue",
+ expectContains: []string{"[MCP:github]", "Create a GitHub issue"},
+ },
+ {
+ name: "empty description",
+ serverName: "filesystem",
+ toolDescription: "",
+ expectContains: []string{"[MCP:filesystem]", "MCP tool from filesystem server"},
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ manager := &MockMCPManager{}
+ tool := &mcp.Tool{
+ Name: "test_tool",
+ Description: tt.toolDescription,
+ }
+ mcpTool := NewMCPTool(manager, tt.serverName, tool)
+
+ result := mcpTool.Description()
+
+ for _, expected := range tt.expectContains {
+ if !strings.Contains(result, expected) {
+ t.Errorf("Description should contain '%s', got: %s", expected, result)
+ }
+ }
+ })
+ }
+}
+
+// TestMCPTool_Parameters verifies parameter schema conversion
+func TestMCPTool_Parameters(t *testing.T) {
+ tests := []struct {
+ name string
+ inputSchema any
+ expectType string
+ checkProperty string
+ expectProperty bool
+ }{
+ {
+ name: "map schema",
+ inputSchema: map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "query": map[string]any{
+ "type": "string",
+ "description": "Search query",
+ },
+ },
+ "required": []string{"query"},
+ },
+ expectType: "object",
+ checkProperty: "query",
+ expectProperty: true,
+ },
+ {
+ name: "nil schema",
+ inputSchema: nil,
+ expectType: "object",
+ expectProperty: false,
+ },
+ {
+ name: "json.RawMessage schema",
+ inputSchema: []byte(`{
+ "type": "object",
+ "properties": {
+ "repo": {
+ "type": "string",
+ "description": "Repository name"
+ },
+ "stars": {
+ "type": "integer",
+ "description": "Minimum stars"
+ }
+ },
+ "required": ["repo"]
+ }`),
+ expectType: "object",
+ checkProperty: "repo",
+ expectProperty: true,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ manager := &MockMCPManager{}
+ tool := &mcp.Tool{
+ Name: "test_tool",
+ InputSchema: tt.inputSchema,
+ }
+ mcpTool := NewMCPTool(manager, "test_server", tool)
+
+ params := mcpTool.Parameters()
+
+ if params == nil {
+ t.Fatal("Parameters should not be nil")
+ }
+
+ if params["type"] != tt.expectType {
+ t.Errorf("Expected type '%s', got '%v'", tt.expectType, params["type"])
+ }
+
+ // Check if property exists when expected
+ if tt.checkProperty != "" {
+ properties, ok := params["properties"].(map[string]any)
+ if !ok && tt.expectProperty {
+ t.Errorf("Expected properties to be a map")
+ return
+ }
+ if ok {
+ _, hasProperty := properties[tt.checkProperty]
+ if hasProperty != tt.expectProperty {
+ t.Errorf("Expected property '%s' existence: %v, got: %v",
+ tt.checkProperty, tt.expectProperty, hasProperty)
+ }
+ }
+ }
+ })
+ }
+}
+
+// TestMCPTool_Execute_Success tests successful tool execution
+func TestMCPTool_Execute_Success(t *testing.T) {
+ manager := &MockMCPManager{
+ callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+ // Verify correct parameters passed
+ if serverName != "github" {
+ t.Errorf("Expected serverName 'github', got '%s'", serverName)
+ }
+ if toolName != "search_repos" {
+ t.Errorf("Expected toolName 'search_repos', got '%s'", toolName)
+ }
+
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "Found 3 repositories"},
+ },
+ IsError: false,
+ }, nil
+ },
+ }
+
+ tool := &mcp.Tool{
+ Name: "search_repos",
+ Description: "Search GitHub repositories",
+ }
+ mcpTool := NewMCPTool(manager, "github", tool)
+
+ ctx := context.Background()
+ args := map[string]any{
+ "query": "golang mcp",
+ }
+
+ result := mcpTool.Execute(ctx, args)
+
+ if result == nil {
+ t.Fatal("Result should not be nil")
+ }
+ if result.IsError {
+ t.Errorf("Expected no error, got error: %s", result.ForLLM)
+ }
+ if result.ForLLM != "Found 3 repositories" {
+ t.Errorf("Expected 'Found 3 repositories', got '%s'", result.ForLLM)
+ }
+}
+
+// TestMCPTool_Execute_ManagerError tests execution when manager returns error
+func TestMCPTool_Execute_ManagerError(t *testing.T) {
+ manager := &MockMCPManager{
+ callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+ return nil, fmt.Errorf("connection failed")
+ },
+ }
+
+ tool := &mcp.Tool{Name: "test_tool"}
+ mcpTool := NewMCPTool(manager, "test_server", tool)
+
+ ctx := context.Background()
+ result := mcpTool.Execute(ctx, map[string]any{})
+
+ if result == nil {
+ t.Fatal("Result should not be nil")
+ }
+ if !result.IsError {
+ t.Error("Expected IsError to be true")
+ }
+ if !strings.Contains(result.ForLLM, "MCP tool execution failed") {
+ t.Errorf("Error message should mention execution failure, got: %s", result.ForLLM)
+ }
+ if !strings.Contains(result.ForLLM, "connection failed") {
+ t.Errorf("Error message should include original error, got: %s", result.ForLLM)
+ }
+}
+
+// TestMCPTool_Execute_ServerError tests execution when server returns error
+func TestMCPTool_Execute_ServerError(t *testing.T) {
+ manager := &MockMCPManager{
+ callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "Invalid API key"},
+ },
+ IsError: true,
+ }, nil
+ },
+ }
+
+ tool := &mcp.Tool{Name: "test_tool"}
+ mcpTool := NewMCPTool(manager, "test_server", tool)
+
+ ctx := context.Background()
+ result := mcpTool.Execute(ctx, map[string]any{})
+
+ if result == nil {
+ t.Fatal("Result should not be nil")
+ }
+ if !result.IsError {
+ t.Error("Expected IsError to be true")
+ }
+ if !strings.Contains(result.ForLLM, "MCP tool returned error") {
+ t.Errorf("Error message should mention server error, got: %s", result.ForLLM)
+ }
+ if !strings.Contains(result.ForLLM, "Invalid API key") {
+ t.Errorf("Error message should include server message, got: %s", result.ForLLM)
+ }
+}
+
+// TestMCPTool_Execute_MultipleContent tests execution with multiple content items
+func TestMCPTool_Execute_MultipleContent(t *testing.T) {
+ manager := &MockMCPManager{
+ callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+ return &mcp.CallToolResult{
+ Content: []mcp.Content{
+ &mcp.TextContent{Text: "First line"},
+ &mcp.TextContent{Text: "Second line"},
+ &mcp.TextContent{Text: "Third line"},
+ },
+ IsError: false,
+ }, nil
+ },
+ }
+
+ tool := &mcp.Tool{Name: "multi_output"}
+ mcpTool := NewMCPTool(manager, "test_server", tool)
+
+ ctx := context.Background()
+ result := mcpTool.Execute(ctx, map[string]any{})
+
+ if result.IsError {
+ t.Errorf("Expected no error, got: %s", result.ForLLM)
+ }
+
+ expected := "First line\nSecond line\nThird line"
+ if result.ForLLM != expected {
+ t.Errorf("Expected '%s', got '%s'", expected, result.ForLLM)
+ }
+}
+
+// TestExtractContentText_TextContent tests text content extraction
+func TestExtractContentText_TextContent(t *testing.T) {
+ content := []mcp.Content{
+ &mcp.TextContent{Text: "Hello World"},
+ &mcp.TextContent{Text: "Second message"},
+ }
+
+ result := extractContentText(content)
+ expected := "Hello World\nSecond message"
+
+ if result != expected {
+ t.Errorf("Expected '%s', got '%s'", expected, result)
+ }
+}
+
+// TestExtractContentText_ImageContent tests image content extraction
+func TestExtractContentText_ImageContent(t *testing.T) {
+ content := []mcp.Content{
+ &mcp.ImageContent{
+ Data: []byte("base64data"),
+ MIMEType: "image/png",
+ },
+ }
+
+ result := extractContentText(content)
+
+ if !strings.Contains(result, "[Image:") {
+ t.Errorf("Expected image indicator, got: %s", result)
+ }
+ if !strings.Contains(result, "image/png") {
+ t.Errorf("Expected MIME type in output, got: %s", result)
+ }
+}
+
+// TestExtractContentText_MixedContent tests mixed content types
+func TestExtractContentText_MixedContent(t *testing.T) {
+ content := []mcp.Content{
+ &mcp.TextContent{Text: "Description"},
+ &mcp.ImageContent{
+ Data: []byte("data"),
+ MIMEType: "image/jpeg",
+ },
+ &mcp.TextContent{Text: "More text"},
+ }
+
+ result := extractContentText(content)
+
+ if !strings.Contains(result, "Description") {
+ t.Errorf("Should contain text content, got: %s", result)
+ }
+ if !strings.Contains(result, "[Image:") {
+ t.Errorf("Should contain image indicator, got: %s", result)
+ }
+ if !strings.Contains(result, "More text") {
+ t.Errorf("Should contain second text, got: %s", result)
+ }
+}
+
+// TestExtractContentText_EmptyContent tests empty content array
+func TestExtractContentText_EmptyContent(t *testing.T) {
+ content := []mcp.Content{}
+
+ result := extractContentText(content)
+
+ if result != "" {
+ t.Errorf("Expected empty string for empty content, got: %s", result)
+ }
+}
+
+// TestMCPTool_InterfaceCompliance verifies MCPTool implements Tool interface
+func TestMCPTool_InterfaceCompliance(t *testing.T) {
+ manager := &MockMCPManager{}
+ tool := &mcp.Tool{Name: "test"}
+ mcpTool := NewMCPTool(manager, "test_server", tool)
+
+ // Verify it implements Tool interface
+ var _ Tool = mcpTool
+}
+
+// TestMCPTool_Parameters_MapSchema tests schema that's already a map
+func TestMCPTool_Parameters_MapSchema(t *testing.T) {
+ manager := &MockMCPManager{}
+ schema := map[string]any{
+ "type": "object",
+ "properties": map[string]any{
+ "name": map[string]any{
+ "type": "string",
+ "description": "The name parameter",
+ },
+ },
+ "required": []string{"name"},
+ }
+
+ tool := &mcp.Tool{
+ Name: "test_tool",
+ InputSchema: schema,
+ }
+ mcpTool := NewMCPTool(manager, "test_server", tool)
+
+ params := mcpTool.Parameters()
+
+ // Should return the schema as-is when it's already a map
+ if params["type"] != "object" {
+ t.Errorf("Expected type 'object', got '%v'", params["type"])
+ }
+
+ props, ok := params["properties"].(map[string]any)
+ if !ok {
+ t.Error("Properties should be a map")
+ }
+
+ nameParam, ok := props["name"].(map[string]any)
+ if !ok {
+ t.Error("Name parameter should exist")
+ }
+
+ if nameParam["type"] != "string" {
+ t.Errorf("Name type should be 'string', got '%v'", nameParam["type"])
+ }
+}
diff --git a/pkg/tools/message.go b/pkg/tools/message.go
index 15ef4ff73..d1e4a373e 100644
--- a/pkg/tools/message.go
+++ b/pkg/tools/message.go
@@ -3,6 +3,7 @@ package tools
import (
"context"
"fmt"
+ "sync/atomic"
)
type SendCallback func(channel, chatID, content string) error
@@ -11,7 +12,7 @@ type MessageTool struct {
sendCallback SendCallback
defaultChannel string
defaultChatID string
- sentInRound bool // Tracks whether a message was sent in the current processing round
+ sentInRound atomic.Bool // Tracks whether a message was sent in the current processing round
}
func NewMessageTool() *MessageTool {
@@ -50,12 +51,12 @@ func (t *MessageTool) Parameters() map[string]any {
func (t *MessageTool) SetContext(channel, chatID string) {
t.defaultChannel = channel
t.defaultChatID = chatID
- t.sentInRound = false // Reset send tracking for new processing round
+ t.sentInRound.Store(false) // Reset send tracking for new processing round
}
// HasSentInRound returns true if the message tool sent a message during the current round.
func (t *MessageTool) HasSentInRound() bool {
- return t.sentInRound
+ return t.sentInRound.Load()
}
func (t *MessageTool) SetSendCallback(callback SendCallback) {
@@ -94,7 +95,7 @@ func (t *MessageTool) Execute(ctx context.Context, args map[string]any) *ToolRes
}
}
- t.sentInRound = true
+ t.sentInRound.Store(true)
// Silent: user already received the message directly
return &ToolResult{
ForLLM: fmt.Sprintf("Message sent to %s:%s", channel, chatID),
diff --git a/pkg/tools/registry.go b/pkg/tools/registry.go
index d37a093a8..0ba983e02 100644
--- a/pkg/tools/registry.go
+++ b/pkg/tools/registry.go
@@ -25,7 +25,12 @@ func NewToolRegistry() *ToolRegistry {
func (r *ToolRegistry) Register(tool Tool) {
r.mu.Lock()
defer r.mu.Unlock()
- r.tools[tool.Name()] = tool
+ name := tool.Name()
+ if _, exists := r.tools[name]; exists {
+ logger.WarnCF("tools", "Tool registration overwrites existing tool",
+ map[string]any{"name": name})
+ }
+ r.tools[name] = tool
}
func (r *ToolRegistry) Get(name string) (Tool, bool) {
diff --git a/pkg/tools/registry_test.go b/pkg/tools/registry_test.go
index 8ae13b20c..8fe88ca78 100644
--- a/pkg/tools/registry_test.go
+++ b/pkg/tools/registry_test.go
@@ -329,7 +329,7 @@ func TestToolRegistry_ConcurrentAccess(t *testing.T) {
r := NewToolRegistry()
var wg sync.WaitGroup
- for i := 0; i < 50; i++ {
+ for i := range 50 {
wg.Add(1)
go func(n int) {
defer wg.Done()
diff --git a/pkg/tools/result.go b/pkg/tools/result.go
index b13055b1c..cab833284 100644
--- a/pkg/tools/result.go
+++ b/pkg/tools/result.go
@@ -30,6 +30,10 @@ type ToolResult struct {
// Err is the underlying error (not JSON serialized).
// Used for internal error handling and logging.
Err error `json:"-"`
+
+ // Media contains media store refs produced by this tool.
+ // When non-empty, the agent will publish these as OutboundMediaMessage.
+ Media []string `json:"media,omitempty"`
}
// NewToolResult creates a basic ToolResult with content for the LLM.
@@ -120,6 +124,19 @@ func UserResult(content string) *ToolResult {
}
}
+// MediaResult creates a ToolResult with media refs for the user.
+// The agent will publish these refs as OutboundMediaMessage.
+//
+// Example:
+//
+// result := MediaResult("Image generated successfully", []string{"media://abc123"})
+func MediaResult(forLLM string, mediaRefs []string) *ToolResult {
+ return &ToolResult{
+ ForLLM: forLLM,
+ Media: mediaRefs,
+ }
+}
+
// MarshalJSON implements custom JSON serialization.
// The Err field is excluded from JSON output via the json:"-" tag.
func (tr *ToolResult) MarshalJSON() ([]byte, error) {
diff --git a/pkg/tools/shell.go b/pkg/tools/shell.go
index ad1664b5b..a0c83eb1e 100644
--- a/pkg/tools/shell.go
+++ b/pkg/tools/shell.go
@@ -21,60 +21,85 @@ type ExecTool struct {
timeout time.Duration
denyPatterns []*regexp.Regexp
allowPatterns []*regexp.Regexp
+ customAllowPatterns []*regexp.Regexp
restrictToWorkspace bool
}
-var defaultDenyPatterns = []*regexp.Regexp{
- regexp.MustCompile(`\brm\s+-[rf]{1,2}\b`),
- regexp.MustCompile(`\bdel\s+/[fq]\b`),
- regexp.MustCompile(`\brmdir\s+/s\b`),
- regexp.MustCompile(`\b(format|mkfs|diskpart)\b\s`), // Match disk wiping commands (must be followed by space/args)
- regexp.MustCompile(`\bdd\s+if=`),
- regexp.MustCompile(`>\s*/dev/sd[a-z]\b`), // Block writes to disk devices (but allow /dev/null)
- regexp.MustCompile(`\b(shutdown|reboot|poweroff)\b`),
- regexp.MustCompile(`:\(\)\s*\{.*\};\s*:`),
- regexp.MustCompile(`\$\([^)]+\)`),
- regexp.MustCompile(`\$\{[^}]+\}`),
- regexp.MustCompile("`[^`]+`"),
- regexp.MustCompile(`\|\s*sh\b`),
- regexp.MustCompile(`\|\s*bash\b`),
- regexp.MustCompile(`;\s*rm\s+-[rf]`),
- regexp.MustCompile(`&&\s*rm\s+-[rf]`),
- regexp.MustCompile(`\|\|\s*rm\s+-[rf]`),
- regexp.MustCompile(`>\s*/dev/null\s*>&?\s*\d?`),
- regexp.MustCompile(`<<\s*EOF`),
- regexp.MustCompile(`\$\(\s*cat\s+`),
- regexp.MustCompile(`\$\(\s*curl\s+`),
- regexp.MustCompile(`\$\(\s*wget\s+`),
- regexp.MustCompile(`\$\(\s*which\s+`),
- regexp.MustCompile(`\bsudo\b`),
- regexp.MustCompile(`\bchmod\s+[0-7]{3,4}\b`),
- regexp.MustCompile(`\bchown\b`),
- regexp.MustCompile(`\bpkill\b`),
- regexp.MustCompile(`\bkillall\b`),
- regexp.MustCompile(`\bkill\s+-[9]\b`),
- regexp.MustCompile(`\bcurl\b.*\|\s*(sh|bash)`),
- regexp.MustCompile(`\bwget\b.*\|\s*(sh|bash)`),
- regexp.MustCompile(`\bnpm\s+install\s+-g\b`),
- regexp.MustCompile(`\bpip\s+install\s+--user\b`),
- regexp.MustCompile(`\bapt\s+(install|remove|purge)\b`),
- regexp.MustCompile(`\byum\s+(install|remove)\b`),
- regexp.MustCompile(`\bdnf\s+(install|remove)\b`),
- regexp.MustCompile(`\bdocker\s+run\b`),
- regexp.MustCompile(`\bdocker\s+exec\b`),
- regexp.MustCompile(`\bgit\s+push\b`),
- regexp.MustCompile(`\bgit\s+force\b`),
- regexp.MustCompile(`\bssh\b.*@`),
- regexp.MustCompile(`\beval\b`),
- regexp.MustCompile(`\bsource\s+.*\.sh\b`),
-}
+var (
+ defaultDenyPatterns = []*regexp.Regexp{
+ regexp.MustCompile(`\brm\s+-[rf]{1,2}\b`),
+ regexp.MustCompile(`\bdel\s+/[fq]\b`),
+ regexp.MustCompile(`\brmdir\s+/s\b`),
+ // Match disk wiping commands (must be followed by space/args)
+ regexp.MustCompile(
+ `\b(format|mkfs|diskpart)\b\s`,
+ ),
+ regexp.MustCompile(`\bdd\s+if=`),
+ // Block writes to block devices (all common naming schemes).
+ regexp.MustCompile(
+ `>\s*/dev/(sd[a-z]|hd[a-z]|vd[a-z]|xvd[a-z]|nvme\d|mmcblk\d|loop\d|dm-\d|md\d|sr\d|nbd\d)`,
+ ),
+ regexp.MustCompile(`\b(shutdown|reboot|poweroff)\b`),
+ regexp.MustCompile(`:\(\)\s*\{.*\};\s*:`),
+ regexp.MustCompile(`\$\([^)]+\)`),
+ regexp.MustCompile(`\$\{[^}]+\}`),
+ regexp.MustCompile("`[^`]+`"),
+ regexp.MustCompile(`\|\s*sh\b`),
+ regexp.MustCompile(`\|\s*bash\b`),
+ regexp.MustCompile(`;\s*rm\s+-[rf]`),
+ regexp.MustCompile(`&&\s*rm\s+-[rf]`),
+ regexp.MustCompile(`\|\|\s*rm\s+-[rf]`),
+ regexp.MustCompile(`<<\s*EOF`),
+ regexp.MustCompile(`\$\(\s*cat\s+`),
+ regexp.MustCompile(`\$\(\s*curl\s+`),
+ regexp.MustCompile(`\$\(\s*wget\s+`),
+ regexp.MustCompile(`\$\(\s*which\s+`),
+ regexp.MustCompile(`\bsudo\b`),
+ regexp.MustCompile(`\bchmod\s+[0-7]{3,4}\b`),
+ regexp.MustCompile(`\bchown\b`),
+ regexp.MustCompile(`\bpkill\b`),
+ regexp.MustCompile(`\bkillall\b`),
+ regexp.MustCompile(`\bkill\s+-[9]\b`),
+ regexp.MustCompile(`\bcurl\b.*\|\s*(sh|bash)`),
+ regexp.MustCompile(`\bwget\b.*\|\s*(sh|bash)`),
+ regexp.MustCompile(`\bnpm\s+install\s+-g\b`),
+ regexp.MustCompile(`\bpip\s+install\s+--user\b`),
+ regexp.MustCompile(`\bapt\s+(install|remove|purge)\b`),
+ regexp.MustCompile(`\byum\s+(install|remove)\b`),
+ regexp.MustCompile(`\bdnf\s+(install|remove)\b`),
+ regexp.MustCompile(`\bdocker\s+run\b`),
+ regexp.MustCompile(`\bdocker\s+exec\b`),
+ regexp.MustCompile(`\bgit\s+push\b`),
+ regexp.MustCompile(`\bgit\s+force\b`),
+ regexp.MustCompile(`\bssh\b.*@`),
+ regexp.MustCompile(`\beval\b`),
+ regexp.MustCompile(`\bsource\s+.*\.sh\b`),
+ }
-func NewExecTool(workingDir string, restrict bool) *ExecTool {
+ // absolutePathPattern matches absolute file paths in commands (Unix and Windows).
+ absolutePathPattern = regexp.MustCompile(`[A-Za-z]:\\[^\\\"']+|/[^\s\"']+`)
+
+ // safePaths are kernel pseudo-devices that are always safe to reference in
+ // commands, regardless of workspace restriction. They contain no user data
+ // and cannot cause destructive writes.
+ safePaths = map[string]bool{
+ "/dev/null": true,
+ "/dev/zero": true,
+ "/dev/random": true,
+ "/dev/urandom": true,
+ "/dev/stdin": true,
+ "/dev/stdout": true,
+ "/dev/stderr": true,
+ }
+)
+
+func NewExecTool(workingDir string, restrict bool) (*ExecTool, error) {
return NewExecToolWithConfig(workingDir, restrict, nil)
}
-func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Config) *ExecTool {
+func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Config) (*ExecTool, error) {
denyPatterns := make([]*regexp.Regexp, 0)
+ customAllowPatterns := make([]*regexp.Regexp, 0)
if config != nil {
execConfig := config.Tools.Exec
@@ -86,8 +111,7 @@ func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Conf
for _, pattern := range execConfig.CustomDenyPatterns {
re, err := regexp.Compile(pattern)
if err != nil {
- fmt.Printf("Invalid custom deny pattern %q: %v\n", pattern, err)
- continue
+ return nil, fmt.Errorf("invalid custom deny pattern %q: %w", pattern, err)
}
denyPatterns = append(denyPatterns, re)
}
@@ -96,6 +120,13 @@ func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Conf
// If deny patterns are disabled, we won't add any patterns, allowing all commands.
fmt.Println("Warning: deny patterns are disabled. All commands will be allowed.")
}
+ for _, pattern := range execConfig.CustomAllowPatterns {
+ re, err := regexp.Compile(pattern)
+ if err != nil {
+ return nil, fmt.Errorf("invalid custom allow pattern %q: %w", pattern, err)
+ }
+ customAllowPatterns = append(customAllowPatterns, re)
+ }
} else {
denyPatterns = append(denyPatterns, defaultDenyPatterns...)
}
@@ -105,8 +136,9 @@ func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Conf
timeout: 60 * time.Second,
denyPatterns: denyPatterns,
allowPatterns: nil,
+ customAllowPatterns: customAllowPatterns,
restrictToWorkspace: restrict,
- }
+ }, nil
}
func (t *ExecTool) Name() string {
@@ -259,9 +291,20 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
cmd := strings.TrimSpace(command)
lower := strings.ToLower(cmd)
- for _, pattern := range t.denyPatterns {
+ // Custom allow patterns exempt a command from deny checks.
+ explicitlyAllowed := false
+ for _, pattern := range t.customAllowPatterns {
if pattern.MatchString(lower) {
- return "Command blocked by safety guard (dangerous pattern detected)"
+ explicitlyAllowed = true
+ break
+ }
+ }
+
+ if !explicitlyAllowed {
+ for _, pattern := range t.denyPatterns {
+ if pattern.MatchString(lower) {
+ return "Command blocked by safety guard (dangerous pattern detected)"
+ }
}
}
@@ -288,8 +331,7 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
return ""
}
- pathPattern := regexp.MustCompile(`[A-Za-z]:\\[^\\\"']+|/[^\s\"']+`)
- matches := pathPattern.FindAllString(cmd, -1)
+ matches := absolutePathPattern.FindAllString(cmd, -1)
for _, raw := range matches {
p, err := filepath.Abs(raw)
@@ -297,6 +339,10 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
continue
}
+ if safePaths[p] {
+ continue
+ }
+
rel, err := filepath.Rel(cwdPath, p)
if err != nil {
continue
diff --git a/pkg/tools/shell_test.go b/pkg/tools/shell_test.go
index 6d35815e8..a6abca8ea 100644
--- a/pkg/tools/shell_test.go
+++ b/pkg/tools/shell_test.go
@@ -7,11 +7,16 @@ import (
"strings"
"testing"
"time"
+
+ "github.com/sipeed/picoclaw/pkg/config"
)
// TestShellTool_Success verifies successful command execution
func TestShellTool_Success(t *testing.T) {
- tool := NewExecTool("", false)
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
ctx := context.Background()
args := map[string]any{
@@ -38,7 +43,10 @@ func TestShellTool_Success(t *testing.T) {
// TestShellTool_Failure verifies failed command execution
func TestShellTool_Failure(t *testing.T) {
- tool := NewExecTool("", false)
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
ctx := context.Background()
args := map[string]any{
@@ -65,7 +73,11 @@ func TestShellTool_Failure(t *testing.T) {
// TestShellTool_Timeout verifies command timeout handling
func TestShellTool_Timeout(t *testing.T) {
- tool := NewExecTool("", false)
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
+
tool.SetTimeout(100 * time.Millisecond)
ctx := context.Background()
@@ -93,7 +105,10 @@ func TestShellTool_WorkingDir(t *testing.T) {
testFile := filepath.Join(tmpDir, "test.txt")
os.WriteFile(testFile, []byte("test content"), 0o644)
- tool := NewExecTool("", false)
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
ctx := context.Background()
args := map[string]any{
@@ -114,7 +129,10 @@ func TestShellTool_WorkingDir(t *testing.T) {
// TestShellTool_DangerousCommand verifies safety guard blocks dangerous commands
func TestShellTool_DangerousCommand(t *testing.T) {
- tool := NewExecTool("", false)
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
ctx := context.Background()
args := map[string]any{
@@ -135,7 +153,10 @@ func TestShellTool_DangerousCommand(t *testing.T) {
// TestShellTool_MissingCommand verifies error handling for missing command
func TestShellTool_MissingCommand(t *testing.T) {
- tool := NewExecTool("", false)
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
ctx := context.Background()
args := map[string]any{}
@@ -150,7 +171,10 @@ func TestShellTool_MissingCommand(t *testing.T) {
// TestShellTool_StderrCapture verifies stderr is captured and included
func TestShellTool_StderrCapture(t *testing.T) {
- tool := NewExecTool("", false)
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
ctx := context.Background()
args := map[string]any{
@@ -170,7 +194,10 @@ func TestShellTool_StderrCapture(t *testing.T) {
// TestShellTool_OutputTruncation verifies long output is truncated
func TestShellTool_OutputTruncation(t *testing.T) {
- tool := NewExecTool("", false)
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
ctx := context.Background()
// Generate long output (>10000 chars)
@@ -198,7 +225,11 @@ func TestShellTool_WorkingDir_OutsideWorkspace(t *testing.T) {
t.Fatalf("failed to create outside dir: %v", err)
}
- tool := NewExecTool(workspace, true)
+ tool, err := NewExecTool(workspace, true)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
+
result := tool.Execute(context.Background(), map[string]any{
"command": "pwd",
"working_dir": outsideDir,
@@ -232,7 +263,11 @@ func TestShellTool_WorkingDir_SymlinkEscape(t *testing.T) {
t.Skipf("symlinks not supported in this environment: %v", err)
}
- tool := NewExecTool(workspace, true)
+ tool, err := NewExecTool(workspace, true)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
+
result := tool.Execute(context.Background(), map[string]any{
"command": "cat secret.txt",
"working_dir": link,
@@ -249,7 +284,11 @@ func TestShellTool_WorkingDir_SymlinkEscape(t *testing.T) {
// TestShellTool_RestrictToWorkspace verifies workspace restriction
func TestShellTool_RestrictToWorkspace(t *testing.T) {
tmpDir := t.TempDir()
- tool := NewExecTool(tmpDir, false)
+ tool, err := NewExecTool(tmpDir, false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
+
tool.SetRestrictToWorkspace(true)
ctx := context.Background()
@@ -272,3 +311,115 @@ func TestShellTool_RestrictToWorkspace(t *testing.T) {
)
}
}
+
+// TestShellTool_DevNullAllowed verifies that /dev/null redirections are not blocked (issue #964).
+func TestShellTool_DevNullAllowed(t *testing.T) {
+ tmpDir := t.TempDir()
+ tool, err := NewExecTool(tmpDir, true)
+ if err != nil {
+ t.Fatalf("unable to configure exec tool: %s", err)
+ }
+
+ commands := []string{
+ "echo hello 2>/dev/null",
+ "echo hello >/dev/null",
+ "echo hello > /dev/null",
+ "echo hello 2> /dev/null",
+ "echo hello >/dev/null 2>&1",
+ "find " + tmpDir + " -name '*.go' 2>/dev/null",
+ }
+
+ for _, cmd := range commands {
+ result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+ if result.IsError && strings.Contains(result.ForLLM, "blocked") {
+ t.Errorf("command should not be blocked: %s\n error: %s", cmd, result.ForLLM)
+ }
+ }
+}
+
+// TestShellTool_BlockDevices verifies that writes to block devices are blocked (issue #965).
+func TestShellTool_BlockDevices(t *testing.T) {
+ tool, err := NewExecTool("", false)
+ if err != nil {
+ t.Fatalf("unable to configure exec tool: %s", err)
+ }
+
+ blocked := []string{
+ "echo x > /dev/sda",
+ "echo x > /dev/hda",
+ "echo x > /dev/vda",
+ "echo x > /dev/xvda",
+ "echo x > /dev/nvme0n1",
+ "echo x > /dev/mmcblk0",
+ "echo x > /dev/loop0",
+ "echo x > /dev/dm-0",
+ "echo x > /dev/md0",
+ "echo x > /dev/sr0",
+ "echo x > /dev/nbd0",
+ }
+
+ for _, cmd := range blocked {
+ result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+ if !result.IsError {
+ t.Errorf("expected block device write to be blocked: %s", cmd)
+ }
+ }
+}
+
+// TestShellTool_SafePathsInWorkspaceRestriction verifies that safe kernel pseudo-devices
+// are allowed even when workspace restriction is active.
+func TestShellTool_SafePathsInWorkspaceRestriction(t *testing.T) {
+ tmpDir := t.TempDir()
+ tool, err := NewExecTool(tmpDir, true)
+ if err != nil {
+ t.Fatalf("unable to configure exec tool: %s", err)
+ }
+
+ // These reference paths outside workspace but should be allowed via safePaths.
+ commands := []string{
+ "cat /dev/urandom | head -c 16 | od",
+ "echo test > /dev/null",
+ "dd if=/dev/zero bs=1 count=1",
+ }
+
+ for _, cmd := range commands {
+ result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+ if result.IsError && strings.Contains(result.ForLLM, "path outside working dir") {
+ t.Errorf("safe path should not be blocked by workspace check: %s\n error: %s", cmd, result.ForLLM)
+ }
+ }
+}
+
+// TestShellTool_CustomAllowPatterns verifies that custom allow patterns exempt
+// commands from deny pattern checks.
+func TestShellTool_CustomAllowPatterns(t *testing.T) {
+ cfg := &config.Config{
+ Tools: config.ToolsConfig{
+ Exec: config.ExecConfig{
+ EnableDenyPatterns: true,
+ CustomAllowPatterns: []string{`\bgit\s+push\s+origin\b`},
+ },
+ },
+ }
+
+ tool, err := NewExecToolWithConfig("", false, cfg)
+ if err != nil {
+ t.Fatalf("unable to configure exec tool: %s", err)
+ }
+
+ // "git push origin main" should be allowed by custom allow pattern.
+ result := tool.Execute(context.Background(), map[string]any{
+ "command": "git push origin main",
+ })
+ if result.IsError && strings.Contains(result.ForLLM, "blocked") {
+ t.Errorf("custom allow pattern should exempt 'git push origin main', got: %s", result.ForLLM)
+ }
+
+ // "git push upstream main" should still be blocked (does not match allow pattern).
+ result = tool.Execute(context.Background(), map[string]any{
+ "command": "git push upstream main",
+ })
+ if !result.IsError {
+ t.Errorf("'git push upstream main' should still be blocked by deny pattern")
+ }
+}
diff --git a/pkg/tools/shell_timeout_unix_test.go b/pkg/tools/shell_timeout_unix_test.go
index 04ef8e441..357e1276e 100644
--- a/pkg/tools/shell_timeout_unix_test.go
+++ b/pkg/tools/shell_timeout_unix_test.go
@@ -22,7 +22,11 @@ func processExists(pid int) bool {
}
func TestShellTool_TimeoutKillsChildProcess(t *testing.T) {
- tool := NewExecTool(t.TempDir(), false)
+ tool, err := NewExecTool(t.TempDir(), false)
+ if err != nil {
+ t.Errorf("unable to configure exec tool: %s", err)
+ }
+
tool.SetTimeout(500 * time.Millisecond)
args := map[string]any{
diff --git a/pkg/tools/skills_install.go b/pkg/tools/skills_install.go
index 55c0b678d..71bfe730b 100644
--- a/pkg/tools/skills_install.go
+++ b/pkg/tools/skills_install.go
@@ -9,6 +9,7 @@ import (
"sync"
"time"
+ "github.com/sipeed/picoclaw/pkg/fileutil"
"github.com/sipeed/picoclaw/pkg/logger"
"github.com/sipeed/picoclaw/pkg/skills"
"github.com/sipeed/picoclaw/pkg/utils"
@@ -197,5 +198,6 @@ func writeOriginMeta(targetDir, registryName, slug, version string) error {
return err
}
- return os.WriteFile(filepath.Join(targetDir, ".skill-origin.json"), data, 0o644)
+ // Use unified atomic write utility with explicit sync for flash storage reliability.
+ return fileutil.WriteFileAtomic(filepath.Join(targetDir, ".skill-origin.json"), data, 0o600)
}
diff --git a/pkg/tools/subagent.go b/pkg/tools/subagent.go
index ad371a649..69f1a49a2 100644
--- a/pkg/tools/subagent.go
+++ b/pkg/tools/subagent.go
@@ -218,7 +218,9 @@ After completing the task, provide a clear summary of what was done.`
// Send announce message back to main agent
if sm.bus != nil {
announceContent := fmt.Sprintf("Task '%s' completed.\n\nResult:\n%s", task.Label, task.Result)
- sm.bus.PublishInbound(bus.InboundMessage{
+ pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer pubCancel()
+ sm.bus.PublishInbound(pubCtx, bus.InboundMessage{
Channel: "system",
SenderID: fmt.Sprintf("subagent:%s", task.ID),
// Format: "original_channel:original_chat_id" for routing back
diff --git a/pkg/tools/toolloop.go b/pkg/tools/toolloop.go
index cdfe0d6ce..244f0d4a2 100644
--- a/pkg/tools/toolloop.go
+++ b/pkg/tools/toolloop.go
@@ -10,6 +10,7 @@ import (
"context"
"encoding/json"
"fmt"
+ "sync"
"github.com/sipeed/picoclaw/pkg/logger"
"github.com/sipeed/picoclaw/pkg/providers"
@@ -121,37 +122,53 @@ func RunToolLoop(
}
messages = append(messages, assistantMsg)
- // 7. Execute tool calls
- for _, tc := range normalizedToolCalls {
- argsJSON, _ := json.Marshal(tc.Arguments)
- argsPreview := utils.Truncate(string(argsJSON), 200)
- logger.InfoCF("toolloop", fmt.Sprintf("Tool call: %s(%s)", tc.Name, argsPreview),
- map[string]any{
- "tool": tc.Name,
- "iteration": iteration,
- })
+ // 7. Execute tool calls in parallel
+ type indexedResult struct {
+ result *ToolResult
+ tc providers.ToolCall
+ }
- // Execute tool (no async callback for subagents - they run independently)
- var toolResult *ToolResult
- if config.Tools != nil {
- toolResult = config.Tools.ExecuteWithContext(ctx, tc.Name, tc.Arguments, channel, chatID, nil)
- } else {
- toolResult = ErrorResult("No tools available")
+ results := make([]indexedResult, len(normalizedToolCalls))
+ var wg sync.WaitGroup
+
+ for i, tc := range normalizedToolCalls {
+ results[i].tc = tc
+
+ wg.Add(1)
+ go func(idx int, tc providers.ToolCall) {
+ defer wg.Done()
+
+ argsJSON, _ := json.Marshal(tc.Arguments)
+ argsPreview := utils.Truncate(string(argsJSON), 200)
+ logger.InfoCF("toolloop", fmt.Sprintf("Tool call: %s(%s)", tc.Name, argsPreview),
+ map[string]any{
+ "tool": tc.Name,
+ "iteration": iteration,
+ })
+
+ var toolResult *ToolResult
+ if config.Tools != nil {
+ toolResult = config.Tools.ExecuteWithContext(ctx, tc.Name, tc.Arguments, channel, chatID, nil)
+ } else {
+ toolResult = ErrorResult("No tools available")
+ }
+ results[idx].result = toolResult
+ }(i, tc)
+ }
+ wg.Wait()
+
+ // Append results in original order
+ for _, r := range results {
+ contentForLLM := r.result.ForLLM
+ if contentForLLM == "" && r.result.Err != nil {
+ contentForLLM = r.result.Err.Error()
}
- // Determine content for LLM
- contentForLLM := toolResult.ForLLM
- if contentForLLM == "" && toolResult.Err != nil {
- contentForLLM = toolResult.Err.Error()
- }
-
- // Add tool result message
- toolResultMsg := providers.Message{
+ messages = append(messages, providers.Message{
Role: "tool",
Content: contentForLLM,
- ToolCallID: tc.ID,
- }
- messages = append(messages, toolResultMsg)
+ ToolCallID: r.tc.ID,
+ })
}
}
diff --git a/pkg/tools/web.go b/pkg/tools/web.go
index e95185599..eeceabd98 100644
--- a/pkg/tools/web.go
+++ b/pkg/tools/web.go
@@ -4,6 +4,7 @@ import (
"bytes"
"context"
"encoding/json"
+ "errors"
"fmt"
"io"
"net/http"
@@ -15,6 +16,27 @@ import (
const (
userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+
+ // HTTP client timeouts for web tool providers.
+ searchTimeout = 10 * time.Second // Brave, Tavily, DuckDuckGo
+ perplexityTimeout = 30 * time.Second // Perplexity (LLM-based, slower)
+ fetchTimeout = 60 * time.Second // WebFetchTool
+
+ defaultMaxChars = 50000
+ maxRedirects = 5
+)
+
+// Pre-compiled regexes for HTML text extraction
+var (
+ reScript = regexp.MustCompile(``)
+ reStyle = regexp.MustCompile(``)
+ reTags = regexp.MustCompile(`<[^>]+>`)
+ reWhitespace = regexp.MustCompile(`[^\S\n]+`)
+ reBlankLines = regexp.MustCompile(`\n{3,}`)
+
+ // DuckDuckGo result extraction
+ reDDGLink = regexp.MustCompile(`]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)`)
+ reDDGSnippet = regexp.MustCompile(`([\s\S]*?)`)
)
// createHTTPClient creates an HTTP client with optional proxy support
@@ -61,6 +83,7 @@ type SearchProvider interface {
type BraveSearchProvider struct {
apiKey string
proxy string
+ client *http.Client
}
func (p *BraveSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
@@ -75,11 +98,7 @@ func (p *BraveSearchProvider) Search(ctx context.Context, query string, count in
req.Header.Set("Accept", "application/json")
req.Header.Set("X-Subscription-Token", p.apiKey)
- client, err := createHTTPClient(p.proxy, 10*time.Second)
- if err != nil {
- return "", fmt.Errorf("failed to create HTTP client: %w", err)
- }
- resp, err := client.Do(req)
+ resp, err := p.client.Do(req)
if err != nil {
return "", fmt.Errorf("request failed: %w", err)
}
@@ -90,6 +109,10 @@ func (p *BraveSearchProvider) Search(ctx context.Context, query string, count in
return "", fmt.Errorf("failed to read response: %w", err)
}
+ if resp.StatusCode != http.StatusOK {
+ return "", fmt.Errorf("brave api error (status %d): %s", resp.StatusCode, string(body))
+ }
+
var searchResp struct {
Web struct {
Results []struct {
@@ -130,6 +153,7 @@ type TavilySearchProvider struct {
apiKey string
baseURL string
proxy string
+ client *http.Client
}
func (p *TavilySearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
@@ -161,11 +185,7 @@ func (p *TavilySearchProvider) Search(ctx context.Context, query string, count i
req.Header.Set("Content-Type", "application/json")
req.Header.Set("User-Agent", userAgent)
- client, err := createHTTPClient(p.proxy, 10*time.Second)
- if err != nil {
- return "", fmt.Errorf("failed to create HTTP client: %w", err)
- }
- resp, err := client.Do(req)
+ resp, err := p.client.Do(req)
if err != nil {
return "", fmt.Errorf("request failed: %w", err)
}
@@ -213,7 +233,8 @@ func (p *TavilySearchProvider) Search(ctx context.Context, query string, count i
}
type DuckDuckGoSearchProvider struct {
- proxy string
+ proxy string
+ client *http.Client
}
func (p *DuckDuckGoSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
@@ -226,11 +247,7 @@ func (p *DuckDuckGoSearchProvider) Search(ctx context.Context, query string, cou
req.Header.Set("User-Agent", userAgent)
- client, err := createHTTPClient(p.proxy, 10*time.Second)
- if err != nil {
- return "", fmt.Errorf("failed to create HTTP client: %w", err)
- }
- resp, err := client.Do(req)
+ resp, err := p.client.Do(req)
if err != nil {
return "", fmt.Errorf("request failed: %w", err)
}
@@ -251,8 +268,7 @@ func (p *DuckDuckGoSearchProvider) extractResults(html string, count int, query
// Try finding the result links directly first, as they are the most critical
// Pattern: Title
// The previous regex was a bit strict. Let's make it more flexible for attributes order/content
- reLink := regexp.MustCompile(`]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)`)
- matches := reLink.FindAllStringSubmatch(html, count+5)
+ matches := reDDGLink.FindAllStringSubmatch(html, count+5)
if len(matches) == 0 {
return fmt.Sprintf("No results found or extraction failed. Query: %s", query), nil
@@ -269,12 +285,11 @@ func (p *DuckDuckGoSearchProvider) extractResults(html string, count int, query
// A better regex approach: iterate through text and find matches in order
// But for now, let's grab all snippets too
- reSnippet := regexp.MustCompile(`([\s\S]*?)`)
- snippetMatches := reSnippet.FindAllStringSubmatch(html, count+5)
+ snippetMatches := reDDGSnippet.FindAllStringSubmatch(html, count+5)
maxItems := min(len(matches), count)
- for i := 0; i < maxItems; i++ {
+ for i := range maxItems {
urlStr := matches[i][1]
title := stripTags(matches[i][2])
title = strings.TrimSpace(title)
@@ -282,9 +297,9 @@ func (p *DuckDuckGoSearchProvider) extractResults(html string, count int, query
// URL decoding if needed
if strings.Contains(urlStr, "uddg=") {
if u, err := url.QueryUnescape(urlStr); err == nil {
- idx := strings.Index(u, "uddg=")
- if idx != -1 {
- urlStr = u[idx+5:]
+ _, after, ok := strings.Cut(u, "uddg=")
+ if ok {
+ urlStr = after
}
}
}
@@ -305,13 +320,13 @@ func (p *DuckDuckGoSearchProvider) extractResults(html string, count int, query
}
func stripTags(content string) string {
- re := regexp.MustCompile(`<[^>]+>`)
- return re.ReplaceAllString(content, "")
+ return reTags.ReplaceAllString(content, "")
}
type PerplexitySearchProvider struct {
apiKey string
proxy string
+ client *http.Client
}
func (p *PerplexitySearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
@@ -346,11 +361,7 @@ func (p *PerplexitySearchProvider) Search(ctx context.Context, query string, cou
req.Header.Set("Authorization", "Bearer "+p.apiKey)
req.Header.Set("User-Agent", userAgent)
- client, err := createHTTPClient(p.proxy, 30*time.Second)
- if err != nil {
- return "", fmt.Errorf("failed to create HTTP client: %w", err)
- }
- resp, err := client.Do(req)
+ resp, err := p.client.Do(req)
if err != nil {
return "", fmt.Errorf("request failed: %w", err)
}
@@ -446,6 +457,88 @@ func (p *SearXNGSearchProvider) Search(ctx context.Context, query string, count
return b.String(), nil
}
+type GLMSearchProvider struct {
+ apiKey string
+ baseURL string
+ searchEngine string
+ proxy string
+ client *http.Client
+}
+
+func (p *GLMSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
+ searchURL := p.baseURL
+ if searchURL == "" {
+ searchURL = "https://open.bigmodel.cn/api/paas/v4/web_search"
+ }
+
+ payload := map[string]any{
+ "search_query": query,
+ "search_engine": p.searchEngine,
+ "search_intent": false,
+ "count": count,
+ "content_size": "medium",
+ }
+
+ 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("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("GLM Search API error (status %d): %s", resp.StatusCode, string(body))
+ }
+
+ var searchResp struct {
+ SearchResult []struct {
+ Title string `json:"title"`
+ Content string `json:"content"`
+ Link string `json:"link"`
+ } `json:"search_result"`
+ }
+
+ if err := json.Unmarshal(body, &searchResp); err != nil {
+ return "", fmt.Errorf("failed to parse response: %w", err)
+ }
+
+ results := searchResp.SearchResult
+ if len(results) == 0 {
+ return fmt.Sprintf("No results for: %s", query), nil
+ }
+
+ var lines []string
+ lines = append(lines, fmt.Sprintf("Results for: %s (via GLM Search)", query))
+ for i, item := range results {
+ if i >= count {
+ break
+ }
+ lines = append(lines, fmt.Sprintf("%d. %s\n %s", i+1, item.Title, item.Link))
+ if item.Content != "" {
+ lines = append(lines, fmt.Sprintf(" %s", item.Content))
+ }
+ }
+
+ return strings.Join(lines, "\n"), nil
+}
+
type WebSearchTool struct {
provider SearchProvider
maxResults int
@@ -467,21 +560,34 @@ type WebSearchToolOptions struct {
SearXNGBaseURL string
SearXNGMaxResults int
SearXNGEnabled bool
+ GLMSearchAPIKey string
+ GLMSearchBaseURL string
+ GLMSearchEngine string
+ GLMSearchMaxResults int
+ GLMSearchEnabled bool
Proxy string
}
-func NewWebSearchTool(opts WebSearchToolOptions) *WebSearchTool {
+func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) {
var provider SearchProvider
maxResults := 5
- // Priority: Perplexity > Brave > SearXNG > Tavily > DuckDuckGo
+ // Priority: Perplexity > Brave > SearXNG > Tavily > DuckDuckGo > GLM Search
if opts.PerplexityEnabled && opts.PerplexityAPIKey != "" {
- provider = &PerplexitySearchProvider{apiKey: opts.PerplexityAPIKey, proxy: opts.Proxy}
+ client, err := createHTTPClient(opts.Proxy, perplexityTimeout)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create HTTP client for Perplexity: %w", err)
+ }
+ provider = &PerplexitySearchProvider{apiKey: opts.PerplexityAPIKey, proxy: opts.Proxy, client: client}
if opts.PerplexityMaxResults > 0 {
maxResults = opts.PerplexityMaxResults
}
} else if opts.BraveEnabled && opts.BraveAPIKey != "" {
- provider = &BraveSearchProvider{apiKey: opts.BraveAPIKey, proxy: opts.Proxy}
+ client, err := createHTTPClient(opts.Proxy, searchTimeout)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create HTTP client for Brave: %w", err)
+ }
+ provider = &BraveSearchProvider{apiKey: opts.BraveAPIKey, proxy: opts.Proxy, client: client}
if opts.BraveMaxResults > 0 {
maxResults = opts.BraveMaxResults
}
@@ -491,27 +597,55 @@ func NewWebSearchTool(opts WebSearchToolOptions) *WebSearchTool {
maxResults = opts.SearXNGMaxResults
}
} else if opts.TavilyEnabled && opts.TavilyAPIKey != "" {
+ client, err := createHTTPClient(opts.Proxy, searchTimeout)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create HTTP client for Tavily: %w", err)
+ }
provider = &TavilySearchProvider{
apiKey: opts.TavilyAPIKey,
baseURL: opts.TavilyBaseURL,
proxy: opts.Proxy,
+ client: client,
}
if opts.TavilyMaxResults > 0 {
maxResults = opts.TavilyMaxResults
}
} else if opts.DuckDuckGoEnabled {
- provider = &DuckDuckGoSearchProvider{proxy: opts.Proxy}
+ client, err := createHTTPClient(opts.Proxy, searchTimeout)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create HTTP client for DuckDuckGo: %w", err)
+ }
+ provider = &DuckDuckGoSearchProvider{proxy: opts.Proxy, client: client}
if opts.DuckDuckGoMaxResults > 0 {
maxResults = opts.DuckDuckGoMaxResults
}
+ } else if opts.GLMSearchEnabled && opts.GLMSearchAPIKey != "" {
+ client, err := createHTTPClient(opts.Proxy, searchTimeout)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create HTTP client for GLM Search: %w", err)
+ }
+ searchEngine := opts.GLMSearchEngine
+ if searchEngine == "" {
+ searchEngine = "search_std"
+ }
+ provider = &GLMSearchProvider{
+ apiKey: opts.GLMSearchAPIKey,
+ baseURL: opts.GLMSearchBaseURL,
+ searchEngine: searchEngine,
+ proxy: opts.Proxy,
+ client: client,
+ }
+ if opts.GLMSearchMaxResults > 0 {
+ maxResults = opts.GLMSearchMaxResults
+ }
} else {
- return nil
+ return nil, nil
}
return &WebSearchTool{
provider: provider,
maxResults: maxResults,
- }
+ }, nil
}
func (t *WebSearchTool) Name() string {
@@ -566,27 +700,40 @@ func (t *WebSearchTool) Execute(ctx context.Context, args map[string]any) *ToolR
}
type WebFetchTool struct {
- maxChars int
- proxy string
+ maxChars int
+ proxy string
+ client *http.Client
+ fetchLimitBytes int64
}
-func NewWebFetchTool(maxChars int) *WebFetchTool {
- if maxChars <= 0 {
- maxChars = 50000
- }
- return &WebFetchTool{
- maxChars: maxChars,
- }
+func NewWebFetchTool(maxChars int, fetchLimitBytes int64) (*WebFetchTool, error) {
+ // createHTTPClient cannot fail with an empty proxy string.
+ return NewWebFetchToolWithProxy(maxChars, "", fetchLimitBytes)
}
-func NewWebFetchToolWithProxy(maxChars int, proxy string) *WebFetchTool {
+func NewWebFetchToolWithProxy(maxChars int, proxy string, fetchLimitBytes int64) (*WebFetchTool, error) {
if maxChars <= 0 {
- maxChars = 50000
+ maxChars = defaultMaxChars
+ }
+ client, err := createHTTPClient(proxy, fetchTimeout)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create HTTP client for web fetch: %w", err)
+ }
+ client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+ if len(via) >= maxRedirects {
+ return fmt.Errorf("stopped after %d redirects", maxRedirects)
+ }
+ return nil
+ }
+ if fetchLimitBytes <= 0 {
+ fetchLimitBytes = 10 * 1024 * 1024 // Security Fallback
}
return &WebFetchTool{
- maxChars: maxChars,
- proxy: proxy,
- }
+ maxChars: maxChars,
+ proxy: proxy,
+ client: client,
+ fetchLimitBytes: fetchLimitBytes,
+ }, nil
}
func (t *WebFetchTool) Name() string {
@@ -648,27 +795,21 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe
req.Header.Set("User-Agent", userAgent)
- client, err := createHTTPClient(t.proxy, 60*time.Second)
- if err != nil {
- return ErrorResult(fmt.Sprintf("failed to create HTTP client: %v", err))
- }
-
- // Configure redirect handling
- client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
- if len(via) >= 5 {
- return fmt.Errorf("stopped after 5 redirects")
- }
- return nil
- }
-
- resp, err := client.Do(req)
+ resp, err := t.client.Do(req)
if err != nil {
return ErrorResult(fmt.Sprintf("request failed: %v", err))
}
+
+ resp.Body = http.MaxBytesReader(nil, resp.Body, t.fetchLimitBytes)
+
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
+ var maxBytesErr *http.MaxBytesError
+ if errors.As(err, &maxBytesErr) {
+ return ErrorResult(fmt.Sprintf("failed to read response: size exceeded %d bytes limit", t.fetchLimitBytes))
+ }
return ErrorResult(fmt.Sprintf("failed to read response: %v", err))
}
@@ -712,31 +853,26 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe
resultJSON, _ := json.MarshalIndent(result, "", " ")
return &ToolResult{
- ForLLM: fmt.Sprintf(
+ ForLLM: string(resultJSON),
+ ForUser: fmt.Sprintf(
"Fetched %d bytes from %s (extractor: %s, truncated: %v)",
len(text),
urlStr,
extractor,
truncated,
),
- ForUser: string(resultJSON),
}
}
func (t *WebFetchTool) extractText(htmlContent string) string {
- re := regexp.MustCompile(``)
- result := re.ReplaceAllLiteralString(htmlContent, "")
- re = regexp.MustCompile(``)
- result = re.ReplaceAllLiteralString(result, "")
- re = regexp.MustCompile(`<[^>]+>`)
- result = re.ReplaceAllLiteralString(result, "")
+ result := reScript.ReplaceAllLiteralString(htmlContent, "")
+ result = reStyle.ReplaceAllLiteralString(result, "")
+ result = reTags.ReplaceAllLiteralString(result, "")
result = strings.TrimSpace(result)
- re = regexp.MustCompile(`[^\S\n]+`)
- result = re.ReplaceAllString(result, " ")
- re = regexp.MustCompile(`\n{3,}`)
- result = re.ReplaceAllString(result, "\n\n")
+ result = reWhitespace.ReplaceAllString(result, " ")
+ result = reBlankLines.ReplaceAllString(result, "\n\n")
lines := strings.Split(result, "\n")
var cleanLines []string
diff --git a/pkg/tools/web_test.go b/pkg/tools/web_test.go
index 2cd79eb24..bdd30d385 100644
--- a/pkg/tools/web_test.go
+++ b/pkg/tools/web_test.go
@@ -1,15 +1,21 @@
package tools
import (
+ "bytes"
"context"
"encoding/json"
+ "fmt"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
+
+ "github.com/sipeed/picoclaw/pkg/logger"
)
+const testFetchLimit = int64(10 * 1024 * 1024)
+
// TestWebTool_WebFetch_Success verifies successful URL fetching
func TestWebTool_WebFetch_Success(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -19,7 +25,11 @@ func TestWebTool_WebFetch_Success(t *testing.T) {
}))
defer server.Close()
- tool := NewWebFetchTool(50000)
+ tool, err := NewWebFetchTool(50000, testFetchLimit)
+ if err != nil {
+ t.Fatalf("Failed to create web fetch tool: %v", err)
+ }
+
ctx := context.Background()
args := map[string]any{
"url": server.URL,
@@ -32,14 +42,14 @@ func TestWebTool_WebFetch_Success(t *testing.T) {
t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
}
- // ForUser should contain the fetched content
- if !strings.Contains(result.ForUser, "Test Page") {
- t.Errorf("Expected ForUser to contain 'Test Page', got: %s", result.ForUser)
+ // ForLLM should contain the fetched content (full JSON result)
+ if !strings.Contains(result.ForLLM, "Test Page") {
+ t.Errorf("Expected ForLLM to contain 'Test Page', got: %s", result.ForLLM)
}
- // ForLLM should contain summary
- if !strings.Contains(result.ForLLM, "bytes") && !strings.Contains(result.ForLLM, "extractor") {
- t.Errorf("Expected ForLLM to contain summary, got: %s", result.ForLLM)
+ // ForUser should contain summary
+ if !strings.Contains(result.ForUser, "bytes") && !strings.Contains(result.ForUser, "extractor") {
+ t.Errorf("Expected ForUser to contain summary, got: %s", result.ForUser)
}
}
@@ -55,7 +65,11 @@ func TestWebTool_WebFetch_JSON(t *testing.T) {
}))
defer server.Close()
- tool := NewWebFetchTool(50000)
+ tool, err := NewWebFetchTool(50000, testFetchLimit)
+ if err != nil {
+ logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+ }
+
ctx := context.Background()
args := map[string]any{
"url": server.URL,
@@ -68,15 +82,19 @@ func TestWebTool_WebFetch_JSON(t *testing.T) {
t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
}
- // ForUser should contain formatted JSON
- if !strings.Contains(result.ForUser, "key") && !strings.Contains(result.ForUser, "value") {
- t.Errorf("Expected ForUser to contain JSON data, got: %s", result.ForUser)
+ // ForLLM should contain formatted JSON
+ if !strings.Contains(result.ForLLM, "key") && !strings.Contains(result.ForLLM, "value") {
+ t.Errorf("Expected ForLLM to contain JSON data, got: %s", result.ForLLM)
}
}
// TestWebTool_WebFetch_InvalidURL verifies error handling for invalid URL
func TestWebTool_WebFetch_InvalidURL(t *testing.T) {
- tool := NewWebFetchTool(50000)
+ tool, err := NewWebFetchTool(50000, testFetchLimit)
+ if err != nil {
+ logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+ }
+
ctx := context.Background()
args := map[string]any{
"url": "not-a-valid-url",
@@ -97,7 +115,11 @@ func TestWebTool_WebFetch_InvalidURL(t *testing.T) {
// TestWebTool_WebFetch_UnsupportedScheme verifies error handling for non-http URLs
func TestWebTool_WebFetch_UnsupportedScheme(t *testing.T) {
- tool := NewWebFetchTool(50000)
+ tool, err := NewWebFetchTool(50000, testFetchLimit)
+ if err != nil {
+ logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+ }
+
ctx := context.Background()
args := map[string]any{
"url": "ftp://example.com/file.txt",
@@ -118,7 +140,11 @@ func TestWebTool_WebFetch_UnsupportedScheme(t *testing.T) {
// TestWebTool_WebFetch_MissingURL verifies error handling for missing URL
func TestWebTool_WebFetch_MissingURL(t *testing.T) {
- tool := NewWebFetchTool(50000)
+ tool, err := NewWebFetchTool(50000, testFetchLimit)
+ if err != nil {
+ logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+ }
+
ctx := context.Background()
args := map[string]any{}
@@ -146,7 +172,11 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
}))
defer server.Close()
- tool := NewWebFetchTool(1000) // Limit to 1000 chars
+ tool, err := NewWebFetchTool(1000, testFetchLimit) // Limit to 1000 chars
+ if err != nil {
+ logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+ }
+
ctx := context.Background()
args := map[string]any{
"url": server.URL,
@@ -159,9 +189,9 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
}
- // ForUser should contain truncated content (not the full 20000 chars)
+ // ForLLM should contain truncated content (not the full 20000 chars)
resultMap := make(map[string]any)
- json.Unmarshal([]byte(result.ForUser), &resultMap)
+ json.Unmarshal([]byte(result.ForLLM), &resultMap)
if text, ok := resultMap["text"].(string); ok {
if len(text) > 1100 { // Allow some margin
t.Errorf("Expected content to be truncated to ~1000 chars, got: %d", len(text))
@@ -174,15 +204,64 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
}
}
+func TestWebFetchTool_PayloadTooLarge(t *testing.T) {
+ // Create a mock HTTP server
+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "text/html")
+ w.WriteHeader(http.StatusOK)
+
+ // Generate a payload intentionally larger than our limit.
+ // Limit: 10 * 1024 * 1024 (10MB). We generate 10MB + 100 bytes of the letter 'A'.
+ largeData := bytes.Repeat([]byte("A"), int(testFetchLimit)+100)
+
+ w.Write(largeData)
+ }))
+ // Ensure the server is shut down at the end of the test
+ defer ts.Close()
+
+ // Initialize the tool
+ tool, err := NewWebFetchTool(50000, testFetchLimit)
+ if err != nil {
+ logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+ }
+
+ // Prepare the arguments pointing to the URL of our local mock server
+ args := map[string]any{
+ "url": ts.URL,
+ }
+
+ // Execute the tool
+ ctx := context.Background()
+ result := tool.Execute(ctx, args)
+
+ // Assuming ErrorResult sets the ForLLM field with the error text.
+ if result == nil {
+ t.Fatal("expected a ToolResult, got nil")
+ }
+
+ // Search for the exact error string we set earlier in the Execute method
+ expectedErrorMsg := fmt.Sprintf("size exceeded %d bytes limit", testFetchLimit)
+
+ if !strings.Contains(result.ForLLM, expectedErrorMsg) && !strings.Contains(result.ForUser, expectedErrorMsg) {
+ t.Errorf("test failed: expected error %q, but got: %+v", expectedErrorMsg, result)
+ }
+}
+
// TestWebTool_WebSearch_NoApiKey verifies that no tool is created when API key is missing
func TestWebTool_WebSearch_NoApiKey(t *testing.T) {
- tool := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: ""})
+ tool, err := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: ""})
+ if err != nil {
+ t.Fatalf("Unexpected error: %v", err)
+ }
if tool != nil {
t.Errorf("Expected nil tool when Brave API key is empty")
}
// Also nil when nothing is enabled
- tool = NewWebSearchTool(WebSearchToolOptions{})
+ tool, err = NewWebSearchTool(WebSearchToolOptions{})
+ if err != nil {
+ t.Fatalf("Unexpected error: %v", err)
+ }
if tool != nil {
t.Errorf("Expected nil tool when no provider is enabled")
}
@@ -190,7 +269,10 @@ func TestWebTool_WebSearch_NoApiKey(t *testing.T) {
// TestWebTool_WebSearch_MissingQuery verifies error handling for missing query
func TestWebTool_WebSearch_MissingQuery(t *testing.T) {
- tool := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: "test-key", BraveMaxResults: 5})
+ tool, err := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: "test-key", BraveMaxResults: 5})
+ if err != nil {
+ t.Fatalf("Unexpected error: %v", err)
+ }
ctx := context.Background()
args := map[string]any{}
@@ -215,7 +297,11 @@ func TestWebTool_WebFetch_HTMLExtraction(t *testing.T) {
}))
defer server.Close()
- tool := NewWebFetchTool(50000)
+ tool, err := NewWebFetchTool(50000, testFetchLimit)
+ if err != nil {
+ logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+ }
+
ctx := context.Background()
args := map[string]any{
"url": server.URL,
@@ -228,14 +314,14 @@ func TestWebTool_WebFetch_HTMLExtraction(t *testing.T) {
t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
}
- // ForUser should contain extracted text (without script/style tags)
- if !strings.Contains(result.ForUser, "Title") && !strings.Contains(result.ForUser, "Content") {
- t.Errorf("Expected ForUser to contain extracted text, got: %s", result.ForUser)
+ // ForLLM should contain extracted text (without script/style tags)
+ if !strings.Contains(result.ForLLM, "Title") && !strings.Contains(result.ForLLM, "Content") {
+ t.Errorf("Expected ForLLM to contain extracted text, got: %s", result.ForLLM)
}
- // Should NOT contain script or style tags
- if strings.Contains(result.ForUser, "