diff --git a/core/.claude/settings.local.json b/core/.claude/settings.local.json new file mode 100644 index 0000000..2737c13 --- /dev/null +++ b/core/.claude/settings.local.json @@ -0,0 +1,158 @@ +{ + "permissions": { + "allow": [ + "Bash(netstat -ano | findstr :8082)", + "Bash(taskkill /PID 17380 /F)", + "Bash(cmd /c \"taskkill /PID 17380 /F\")", + "Bash(powershell -Command \"Stop-Process -Id 17380 -Force\")", + "Bash(taskkill //PID 17380 //F)", + "Bash(netstat -ano | findstr :8082 | head -2)", + "WebSearch", + "mcp__web-search-prime__web_search_prime", + "mcp__web-reader__webReader", + "Bash(curl -s -X POST http://localhost:8082/model/test -H \"Content-Type: application/json\" -d '{\"provider\":\"openai\",\"model\":\"gpt-4\",\"model_type\":\"chat\",\"api_key\":\"test\",\"base_url\":\"https://api.openai.com\"}' 2>&1 || echo \"Failed to connect\")", + "Bash(curl -s http://localhost:8082/model/list 2>&1 | head -100)", + "Bash(cd D:\\\\Code\\\\Project\\\\X-Agents\\\\server && go run ./cmd/api 2>&1 | head -20)", + "Bash(cd /d/Code/Project/X-Agents/server && go build ./cmd/api 2>&1 | head -20)", + "Bash(cd /d/Code/Project/X-Agents/server && go build ./cmd/api 2>&1)", + "Bash(curl -s \"http://localhost:8082/api/chat/sessions?user_id=default-user&limit=50\" 2>&1)", + "Bash(curl -s \"http://localhost:8082/api/agent/list\" 2>&1)", + "Bash(mysql -h localhost -u root -proot x_agents -e \"CREATE TABLE IF NOT EXISTS chat_sessions \\(id VARCHAR\\(36\\) PRIMARY KEY, user_id VARCHAR\\(36\\) NOT NULL, agent_id VARCHAR\\(36\\), title VARCHAR\\(255\\), model_id VARCHAR\\(36\\), status VARCHAR\\(20\\) DEFAULT 'active', created_at DATETIME\\(3\\), updated_at DATETIME\\(3\\), INDEX idx_chat_sessions_user \\(user_id\\), INDEX idx_chat_sessions_agent \\(agent_id\\), INDEX idx_chat_sessions_updated \\(updated_at DESC\\)\\);\" 2>&1)", + "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:8080/api/chat/sessions?user_id=test 2>/dev/null || echo \"Server not running\")", + "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:5173 2>/dev/null || echo \"Frontend not running\")", + "Bash(curl -s \"http://localhost:8082/api/agent/list\" 2>&1 | head -50)", + "Bash(netstat -ano 2>/dev/null | grep -E \"8080|3000\" | head -5 || echo \"Port check failed\")", + "Bash(ls -la /d/Code/Project/X-Agents/server/*.exe 2>/dev/null || ls -la /d/Code/Project/X-Agents/server/server.exe 2>/dev/null || ls -la /d/Code/Project/X-Agents/server/api.exe 2>/dev/null)", + "Bash(tasklist 2>/dev/null | grep -i \"api\\\\|server\" || echo \"No process found\")", + "Bash(taskkill //F //PID 14560 2>&1 || echo \"Process already dead\")", + "Bash(curl -s http://localhost:8080/api/chat/sessions?user_id=test 2>&1)", + "Bash(cd /d/Code/Project/X-Agents/server/cmd/api && go build -o ../api.exe . 2>&1)", + "Bash(sleep 3 && curl -s \"http://localhost:8082/api/chat/sessions?user_id=default-user&limit=50\" 2>&1)", + "Bash(netstat -ano 2>/dev/null | grep 8082 | head -5)", + "Bash(curl -s http://localhost:8082/api/chat/sessions?user_id=test 2>&1)", + "Bash(tasklist 2>/dev/null | grep -i \"api\")", + "Bash(taskkill //F //IM api.exe 2>&1 || echo \"Process killed\")", + "Bash(which mysql:*)", + "Bash(cd /d/Code/Project/X-Agents/server/cmd/api && go build -o ../api_new.exe . 2>&1)", + "Bash(docker ps:*)", + "Bash(docker exec:*)", + "Bash(ls -la /d/Code/Project/X-Agents/server/*.exe 2>/dev/null)", + "Bash(curl -s http://localhost:8082/api/chat/sessions?user_id=test-user-123 2>&1)", + "Bash(cd /d/Code/Project/X-Agents/server/cmd/api && go build -o ../api.exe . 2>&1 && echo \"Build success\")", + "Bash(netstat -ano 2>/dev/null | grep 8082 | head -3)", + "Bash(tasklist 2>/dev/null | grep -i \"go\\\\|api\\\\|server\" | head -10)", + "Bash(curl -s \"http://localhost:8082/api/chat/groups?user_id=default-user\" 2>&1)", + "Bash(sleep 3 && curl -s http://localhost:8082/api/chat/sessions?user_id=test-user-123 2>&1)", + "Bash(curl -s -X POST \"http://localhost:8082/api/chat/sessions\" -H \"Content-Type: application/json\" -d '{\"user_id\":\"default-user\",\"agent_id\":\"test-agent\",\"title\":\"Test Session\"}' 2>&1)", + "Bash(curl -s -X POST \"http://localhost:8082/api/agent/chat\" -H \"Content-Type: application/json\" -d '{\"agent_id\":\"1\",\"message\":\"hello\"}' 2>&1)", + "Bash(curl -s -X POST \"http://localhost:8082/api/agent/chat/stream\" -H \"Content-Type: application/json\" -d '{\"agent_id\":\"1\",\"message\":\"hello\"}' 2>&1 | head -5)", + "Bash(taskkill //F //IM api.exe 2>&1\ncd /d/Code/Project/X-Agents/server/cmd/api && go clean -cache && go build -o ../api.exe . 2>&1)", + "Bash(ls -la /d/Code/Project/X-Agents/server/*.exe)", + "Bash(cd /d/Code/Project/X-Agents/server/cmd/api && go build -o ../api.exe . 2>&1 && ls -la ../api.exe)", + "Bash(taskkill //F //IM api.exe 2>&1 || true\ncd /d/Code/Project/X-Agents/server/cmd/api && go build -o ../api.exe . 2>&1 && echo \"Build success\")", + "Bash(curl -s -X POST \"http://localhost:8082/api/agent/chat/stream\" -H \"Content-Type: application/json\" -d '{\"agent_id\":1,\"message\":\"hello\"}' 2>&1)", + "Bash(curl -s -X POST \"http://localhost:8082/api/agent/chat/stream\" -H \"Content-Type: application/json\" -d '{\"agent_id\":\"1\",\"message\":\"hello\"}' 2>&1)", + "Bash(taskkill //F //IM api.exe 2>&1 || true\ncd /d/Code/Project/X-Agents/server/cmd/api && go build -o ../api.exe . 2>&1\nls -la /d/Code/Project/X-Agents/server/api.exe)", + "Bash(go build:*)", + "Read(//tmp/**)", + "Bash(netstat -ano | grep 8082)", + "Bash(taskkill //F //PID 66476)", + "Bash(sleep 3 && curl -s -X POST http://localhost:8082/api/agent/chat/stream -H \"Content-Type: application/json\" -d '{\"agent_id\": \"1\", \"message\": \"hello\"}' 2>&1 | head -20)", + "Bash(netstat -ano | grep -E \"8081|8001\")", + "Bash(sleep 3 && curl -s http://localhost:8081/docs 2>&1 | head -5)", + "Bash(netstat -ano | grep 8081)", + "Bash(sleep 4 && netstat -ano | grep 8081)", + "Bash(netstat -ano | grep 8001)", + "Bash(taskkill /F /IM api.exe 2>/dev/null; taskkill /F /IM python.exe 2>/dev/null; echo \"Done\")", + "Bash(netstat -ano | findstr 8001)", + "Bash(chmod +x \"D:\\\\Code\\\\Project\\\\X-Agents\\\\start-all.sh\")", + "Bash(sed -i '260,264d' /d/Code/Project/X-Agents/core/agents/agent/loop.py && sed -n '255,270p' /d/Code/Project/X-Agents/core/agents/agent/loop.py)", + "Bash(sed -i '260,261d' /d/Code/Project/X-Agents/core/agents/agent/loop.py && sed -n '255,270p' /d/Code/Project/X-Agents/core/agents/agent/loop.py)", + "Bash(sed -i '259d' /d/Code/Project/X-Agents/core/agents/agent/loop.py && sed -n '255,270p' /d/Code/Project/X-Agents/core/agents/agent/loop.py)", + "Bash(cd /d/Code/Project/X-Agents/core && python -c \"import agents.agent.loop\" 2>&1 | head -20)", + "Bash(PYTHONPATH=/d/Code/Project/X-Agents/core python -c \"from agents.agent.loop import AgentLoop; print\\('OK'\\)\" 2>&1)", + "Bash(PYTHONPATH=/d/Code/Project/X-Agents/core python -c \"from core.agents.agent.loop import AgentLoop; print\\('OK'\\)\" 2>&1)", + "Bash(PYTHONPATH=. python -c \"from core.agents.agent.loop import AgentLoop; print\\('OK'\\)\" 2>&1)", + "Bash(python -c \"import sys; sys.path.insert\\(0, '.'\\); from core.agents.agent.loop import AgentLoop; print\\('OK'\\)\" 2>&1)", + "Bash(cd /d/Code/Project/X-Agents && PYTHONPATH=core python -c \"from core.agents.agent.loop import AgentLoop; print\\('OK'\\)\" 2>&1)", + "Bash(cd /d/Code/Project/X-Agents && PYTHONPATH=\"core;nanobot\" python -c \"from core.agents.agent.loop import AgentLoop; print\\('OK'\\)\" 2>&1 | head -10)", + "Bash(cd /d/Code/Project/X-Agents/core && PYTHONPATH=. python -c \"from core.agents.agent.loop import AgentLoop; print\\('OK'\\)\" 2>&1 | head -10)", + "Bash(PYTHONPATH=. python agents/main.py 2>&1 | head -20)", + "Bash(python agents/main.py 2>&1 | head -20)", + "Bash(python agents/main.py 2>&1 | head -30)", + "Bash(/d/Code/Project/X-Agents/core/agents/venv/Scripts/pip.exe install:*)", + "Bash(/d/Code/Project/X-Agents/core/agents/venv/Scripts/python.exe agents/main.py 2>&1 | head -30)", + "Bash(/d/Code/Project/X-Agents/core/agents/venv/Scripts/python.exe agents/main.py 2>&1 | head -40)", + "Bash(/d/Code/Project/X-Agents/core/agents/venv/Scripts/python.exe agents/main.py 2>&1 | head -50)", + "Bash(cd D:/Code/Project/X-Agents/core && python -c \"from agents.agent.team_agent import TeamAgent; print\\('TeamAgent import OK'\\)\")", + "Bash(cd D:/Code/Project/X-Agents && PYTHONPATH=core python -c \"from agents.agent.team_agent import TeamAgent; print\\('TeamAgent import OK'\\)\")", + "Bash(/d/Code/Project/X-Agents/core/agents/venv/Scripts/python.exe -c \"from agents.main import create_app; print\\('Import successful!'\\)\" 2>&1)", + "Bash(PYTHONPATH=/d/Code/Project/X-Agents/core /d/Code/Project/X-Agents/core/agents/venv/Scripts/python.exe -c \"from agents.main import create_app; print\\('Import successful!'\\)\" 2>&1)", + "Bash(PYTHONPATH=/d/Code/Project/X-Agents/core /d/Code/Project/X-Agents/core/agents/venv/Scripts/python.exe -m agents.main --help 2>&1 | head -20)", + "Bash(pip install:*)", + "Bash(netstat -ano 2>&1 | findstr 8001)", + "Bash(netstat -ano 2>&1 | findstr \"8001\")", + "Bash(taskkill //F //IM python.exe 2>&1 || true)", + "Bash(netstat -ano 2>&1 | findstr 8082)", + "Bash(taskkill //F //PID 25804)", + "Bash(taskkill //F //PID 73424)", + "Bash(taskkill //F //PID 73364)", + "Bash(pip search:*)", + "Bash(taskkill //F //PID 74128)", + "Bash(sleep 5 && curl -s -X POST http://localhost:8082/api/agent/chat/stream -H \"Content-Type: application/json\" -d '{\"agent_id\": \"1\", \"message\": \"hello\"}' 2>&1 | head -10)", + "Bash(taskkill //F //PID 72320)", + "Bash(curl -s -X POST http://localhost:8082/api/agent/team/chat -H \"Content-Type: application/json\" -d '{\"supervisor_agent_id\": 1, \"member_agent_ids\": [1,2,3], \"message\": \"hello team\"}' 2>&1)", + "Bash(netstat -ano 2>&1 | findstr \"8082\")", + "Bash(cd /d/Code/Project/X-Agents/server && timeout 10 go run ./cmd/api 2>&1 || true)", + "Bash(curl -s -X POST http://localhost:8082/api/chat/messages -H \"Content-Type: application/json\" -d '{\"session_id\":\"test-session\",\"role\":\"user\",\"content\":\"hello\"}' 2>&1)", + "Bash(curl -s -X POST http://localhost:8082/api/chat/sessions -H \"Content-Type: application/json\" -d '{\"user_id\":\"test-user\",\"agent_id\":\"test-agent\",\"title\":\"Test Chat\"}' 2>&1)", + "Bash(curl -s -X POST http://localhost:8082/api/chat/messages -H \"Content-Type: application/json\" -d '{\"session_id\":\"8d9e9f73-5b6c-4d3d-ace9-d677dfdc63c3\",\"role\":\"user\",\"content\":\"hello\"}' 2>&1)", + "Bash(curl -s -X POST http://localhost:8082/api/chat/groups -H \"Content-Type: application/json\" -d '{\"user_id\":\"test-user\",\"name\":\"Test Group\",\"description\":\"Test Group Description\",\"agent_ids\":\"[\\\\\"agent1\\\\\",\\\\\"agent2\\\\\"]\"}' 2>&1)", + "Bash(curl -s -X POST \"http://localhost:8082/api/chat/groups/040e742e-aa6c-4d04-b246-d71953294cde/chat\" -H \"Content-Type: application/json\" -d '{\"message\":\"Hello group\",\"user_id\":\"test-user\"}' 2>&1)", + "Bash(curl -s http://localhost:8082/api/agent/list 2>&1 | head -500)", + "Bash(curl -s -X POST http://localhost:8082/api/chat/groups -H \"Content-Type: application/json\" -d '{\"user_id\":\"test-user\",\"name\":\"Test Group Real\",\"description\":\"Test Group with real agents\",\"agent_ids\":\"[\\\\\"64ac115c-df75-4907-9028-a101fd82395e\\\\\",\\\\\"cb150dd3-e745-434d-b62d-341a603c0351\\\\\"]\"}' 2>&1)", + "Bash(curl -s -X POST \"http://localhost:8082/api/chat/groups/7c968861-8d5d-46f0-8c01-b6db31eb263f/chat\" -H \"Content-Type: application/json\" -d '{\"message\":\"Hello agents\",\"user_id\":\"test-user\"}' 2>&1)", + "Bash(cd /d \"D:\\\\Code\\\\Project\\\\X-Agents\\\\server\" && go build -o api.exe ./cmd/api/)", + "Bash(taskkill //F //IM api.exe 2>&1 || true)", + "Bash(cd /d/Code/Project/X-Agents/server && timeout 8 go run ./cmd/api 2>&1 || true)", + "Bash(curl -s http://localhost:8082/api/chat/groups?user_id=1 2>/dev/null || echo \"Go server not running\")", + "Bash(curl -s -X POST http://localhost:8082/api/chat/groups \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"user_id\":\"1\",\"name\":\"测试群聊\",\"agent_ids\":\"[1,2]\"}')", + "Bash(curl -s -X POST http://localhost:8082/api/chat/groups/e118af0b-cd5b-4587-b316-f7bf2831e800/chat \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"message\":\"你好\",\"agent_ids\":\"[1,2]\"}')", + "Bash(curl -s http://localhost:8082/api/agent/list)", + "Bash(curl -s -X POST http://localhost:8082/api/chat/groups \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"user_id\":\"1\",\"name\":\"测试群聊2\",\"agent_ids\":\"[\\\\\"64ac115c-df75-4907-9028-a101fd82395e\\\\\",\\\\\"cb150dd3-e745-434d-b62d-341a603c0351\\\\\"]\"}')", + "Bash(curl -s -X POST http://localhost:8082/api/chat/groups/b51773ab-767d-4226-840c-5960e3ff6a12/chat \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"message\":\"你好，请介绍一下你自己\"}')", + "Bash(curl -s -X POST http://localhost:8082/api/agent/chat/stream \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"agent_id\":\"64ac115c-df75-4907-9028-a101fd82395e\",\"message\":\"你好\"}')", + "Bash(curl -s -X POST http://localhost:8001/api/v1/agent/team/chat \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"supervisor_agent_id\":0,\"member_agent_ids\":[1,2],\"message\":\"你好\",\"user_id\":1,\"strategy\":\"parallel\"}')", + "Bash(sleep 3 && curl -s -X POST http://localhost:8082/api/chat/groups/b51773ab-767d-4226-840c-5960e3ff6a12/chat \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"message\":\"你好测试\"}')", + "Bash(curl -s -X POST http://localhost:8001/api/v1/agent/team/chat \\\\\n -H \"Content-Type: application/json\" \\\\\n -d '{\"supervisor_agent_id\":0,\"member_agent_ids\":[1,2],\"message\":\"hello\",\"user_id\":1,\"strategy\":\"parallel\"}')", + "Bash(netstat -ano | grep 8082 | head -1)", + "Bash(curl -s http://localhost:8001/api/v1/health)", + "Bash(cd D:/Code/Project/X-Agents/server && go clean -cache && go build -o api.exe ./cmd/api/ 2>&1)", + "Bash(taskkill /F /PID 72912 2>/dev/null\nsleep 2\nnetstat -ano | grep 8082)", + "Bash(wmic process:*)", + "Bash(taskkill //F //PID 72912)", + "Bash(cd \"D:\\\\Code\\\\Project\\\\X-Agents\" && ./start-all.bat)", + "Bash(netstat -ano | grep -E \"8080|8081|5173\")", + "Bash(taskkill //F //PID 31372 && taskkill //F //PID 52956 && taskkill //F //PID 35560)", + "Bash(sleep 3 && netstat -ano | grep -E \"8080|8081|5173\" | head -10)", + "Bash(netstat -ano | grep LISTENING | grep -E \"8080|8081|5173\")", + "Bash(netstat -ano | grep -E \"8082|8081|5173\")", + "Bash(sleep 3 && netstat -ano | grep -E \"8081|5173\")", + "Bash(sleep 2 && netstat -ano | grep LISTENING | grep -E \"8000|8001|8081\")", + "Bash(sleep 5 && netstat -ano | grep LISTENING | grep 5173)", + "Bash(netstat -ano)", + "Bash(xargs -I {} taskkill //F //PID {})", + "Bash(cd D:/Code/Project/X-Agents/server && go mod download gorm.io/driver/sqlite3)", + "Bash(cd D:/Code/Project/X-Agents/server && go mod tidy)", + "Bash(cd D:/Code/Project/X-Agents && cmd /c \"start-all.bat\")", + "Bash(timeout /t 10 /nobreak >nul && netstat -ano | findstr \"LISTENING\" | findstr \"8082\")", + "Bash(taskkill //F //IM api.exe 2>/dev/null; taskkill //F //IM node.exe 2>/dev/null; echo \"Ports cleaned\")", + "Bash(taskkill /PID 8604 /F)", + "Bash(taskkill //PID 8604 //F)", + "Bash(cd D:/Code/Project/X-Agents/core/agents && python -m py_compile agent/loop.py)", + "Bash(cd D:/Code/Project/X-Agents/core/agents && python -m py_compile agent/loop.py && echo \"Syntax OK\")", + "Bash(cd D:/Code/Project/X-Agents/core/agents && python -m py_compile agent/loop.py 2>&1)", + "Bash(cd D:/Code/Project/X-Agents/core/agents && python -m py_compile api/routes.py && echo \"OK\")" + ] + } +} diff --git a/core/agents/.env.example b/core/agents/.env.example new file mode 100644 index 0000000..c05e615 --- /dev/null +++ b/core/agents/.env.example @@ -0,0 +1,27 @@ +# X-Agents Python Agent Environment Configuration + +# API Settings +API_HOST=0.0.0.0 +API_PORT=8001 + +# Go Backend URL (for tool sync) +GO_BACKEND_URL=http://localhost:8080 + +# LLM Provider (openai/anthropic) +LLM_PROVIDER=openai + +# LLM API Key (required for actual LLM calls) +LLM_API_KEY=your-api-key-here + +# LLM Model +LLM_MODEL=gpt-4o + +# Optional: Custom LLM Base URL (for proxy/alternative endpoints) +# LLM_BASE_URL=https://api.openai.com/v1 + +# Workspace for agent files +WORKSPACE=./workspace + +# Agent settings +MAX_ITERATIONS=10 +TEMPERATURE=0.7 diff --git a/core/agents/__init__.py b/core/agents/__init__.py new file mode 100644 index 0000000..cc4fc54 --- /dev/null +++ b/core/agents/__init__.py @@ -0,0 +1,7 @@ +"""X-Agents Agent Core Package.""" + +# 注意：不要在这里使用顶层导入，会导致循环依赖问题 +# 如需使用，请在使用时导入： +# from core.agents.agent.loop import AgentLoop + +__all__ = [] diff --git a/core/agents/agent/__init__.py b/core/agents/agent/__init__.py new file mode 100644 index 0000000..0df7403 --- /dev/null +++ b/core/agents/agent/__init__.py @@ -0,0 +1,7 @@ +"""X-Agents Agent Module.""" + +from agents.agent.loop import AgentLoop +from agents.agent.context import ContextBuilder +from agents.agent.memory import AgentMemory, SessionMemory, RemoteMemoryClient + +__all__ = ["AgentLoop", "ContextBuilder", "AgentMemory", "SessionMemory", "RemoteMemoryClient"] diff --git a/core/agents/agent/context.py b/core/agents/agent/context.py new file mode 100644 index 0000000..d913f1d --- /dev/null +++ b/core/agents/agent/context.py @@ -0,0 +1,111 @@ +"""Context builder for assembling agent prompts.""" + +import platform +from pathlib import Path +from typing import Any + + +class ContextBuilder: + """Builds the context (system prompt + messages) for the agent.""" + + def __init__(self, workspace: Path): + """Initialize the context builder. + + Args: + workspace: Workspace directory + """ + self.workspace = workspace + + def build_system_prompt(self) -> str: + """Build the system prompt with identity and runtime info.""" + workspace_path = str(self.workspace.expanduser().resolve()) + system = platform.system() + runtime = f"{system} {platform.machine()}" + + return f"""# X-Agents Assistant + +You are an AI assistant built on the X-Agents platform. + +## Runtime +{runtime} + +## Workspace +Your workspace is at: {workspace_path} + +## Guidelines +- Be helpful and concise +- Think step by step when needed +- Ask for clarification when the request is ambiguous +""" + + def build_messages( + self, + history: list[dict[str, Any]], + current_message: str, + ) -> list[dict[str, Any]]: + """Build the complete message list for an LLM call. + + Args: + history: Conversation history + current_message: Current user message + + Returns: + List of messages for LLM + """ + return [ + {"role": "system", "content": self.build_system_prompt()}, + *history, + {"role": "user", "content": current_message}, + ] + + def add_assistant_message( + self, + messages: list[dict[str, Any]], + content: str | None, + tool_calls: list[dict[str, Any]] | None = None, + reasoning_content: str | None = None, + ) -> list[dict[str, Any]]: + """Add an assistant message to the message list. + + Args: + messages: Current message list + content: Assistant message content + tool_calls: Optional tool calls + reasoning_content: Optional reasoning from model + + Returns: + Updated message list + """ + msg = {"role": "assistant", "content": content or ""} + if tool_calls: + msg["tool_calls"] = tool_calls + if reasoning_content: + msg["reasoning_content"] = reasoning_content + messages.append(msg) + return messages + + def add_tool_result( + self, + messages: list[dict[str, Any]], + tool_call_id: str, + tool_name: str, + result: str, + ) -> list[dict[str, Any]]: + """Add a tool result to the message list. + + Args: + messages: Current message list + tool_call_id: ID of the tool call + tool_name: Name of the tool + result: Tool execution result + + Returns: + Updated message list + """ + messages.append({ + "role": "tool", + "tool_call_id": tool_call_id, + "name": tool_name, + "content": result, + }) + return messages diff --git a/core/agents/agent/intelligent_memory.py b/core/agents/agent/intelligent_memory.py new file mode 100644 index 0000000..1980d67 --- /dev/null +++ b/core/agents/agent/intelligent_memory.py @@ -0,0 +1,521 @@ +"""Intelligent memory summarization and compression system.""" + +import asyncio +import logging +from datetime import datetime, timedelta +from typing import Any +from dataclasses import dataclass, field + +logger = logging.getLogger(__name__) + + +@dataclass +class SummarizationConfig: + """Configuration for memory summarization.""" + # Token thresholds + context_window: int = 200000 # Model's context window + reserve_tokens: int = 20000 # Reserved tokens for system prompt + soft_threshold: int = 4000 # Trigger summarization before hitting limit + + # Summary settings + keep_recent_tokens: int = 20000 # Keep recent N tokens + summary_prompt: str = ( + "Please summarize the following conversation, preserving key information, " + "decisions, and important details. Focus on:\n" + "- User preferences and requirements\n" + "- Important decisions made\n" + "- Technical details and configurations\n" + "- Any follow-up tasks or action items\n\n" + "Conversation:\n{content}\n\n" + "Provide a concise summary:" + ) + + # Evergreen settings + evergreen_importance_threshold: int = 8 # Auto-mark high importance as evergreen + + # Decay settings + decay_days_no_activity: int = 30 # Days without activity before decay starts + decay_factor: float = 0.9 # Importance decay factor per period + + +class MemorySummarizer: + """LLM-based memory summarizer.""" + + def __init__(self, llm_provider=None, config: SummarizationConfig | None = None): + """Initialize memory summarizer. + + Args: + llm_provider: LLM provider for generating summaries + config: Summarization configuration + """ + self.llm_provider = llm_provider + self.config = config or SummarizationConfig() + + async def summarize_conversation( + self, + messages: list[dict[str, Any]], + ) -> str | None: + """Summarize a conversation. + + Args: + messages: List of conversation messages + + Returns: + Summary string or None if failed + """ + if not self.llm_provider: + logger.warning("No LLM provider configured for summarization") + return None + + if not messages: + return None + + # Format messages for summarization + content = self._format_messages(messages) + + # Generate summary using LLM + try: + prompt = self.config.summary_prompt.format(content=content) + response = await self.llm_provider.chat( + messages=[{"role": "user", "content": prompt}], + max_tokens=1024, + temperature=0.5, + ) + + if response and response.content: + return response.content.strip() + except Exception as e: + logger.error(f"Summarization failed: {e}") + + return None + + def _format_messages(self, messages: list[dict[str, Any]]) -> str: + """Format messages for summarization prompt.""" + lines = [] + for msg in messages: + role = msg.get("role", "unknown") + content = msg.get("content", "") + if content: + lines.append(f"{role}: {content[:500]}") # Truncate long messages + return "\n".join(lines) + + def estimate_tokens(self, text: str) -> int: + """Estimate token count (rough approximation). + + Args: + text: Text to estimate + + Returns: + Estimated token count + """ + # Rough estimate: ~4 characters per token + return len(text) // 4 + + +class ContextCompressor: + """Context compression manager for agent memory.""" + + def __init__( + self, + summarizer: MemorySummarizer, + config: SummarizationConfig | None = None, + ): + """Initialize context compressor. + + Args: + summarizer: Memory summarizer + config: Summarization configuration + """ + self.summarizer = summarizer + self.config = config or SummarizationConfig() + self._compaction_count = 0 + + @property + def flush_trigger_tokens(self) -> int: + """Calculate token threshold for triggering memory flush.""" + return ( + self.config.context_window + - self.config.reserve_tokens + - self.config.soft_threshold + ) + + def should_flush(self, current_tokens: int) -> bool: + """Check if memory flush should be triggered. + + Args: + current_tokens: Current token count + + Returns: + True if flush should be triggered + """ + return current_tokens >= self.flush_trigger_tokens + + async def compress_context( + self, + messages: list[dict[str, Any]], + current_tokens: int, + ) -> tuple[list[dict[str, Any]], str | None]: + """Compress context when approaching token limit. + + Args: + messages: Current conversation messages + current_tokens: Current token count + + Returns: + Tuple of (compressed messages, summary) + """ + if not self.should_flush(current_tokens): + return messages, None + + self._compaction_count += 1 + logger.info(f"Triggering context compression (count: {self._compaction_count})") + + # Keep recent messages + recent_messages = self._keep_recent_messages( + messages, + self.config.keep_recent_tokens, + ) + + # Summarize older messages + older_messages = self._get_older_messages( + messages, + self.config.keep_recent_tokens, + ) + + if not older_messages: + return recent_messages, None + + summary = await self.summarizer.summarize_conversation(older_messages) + + # Create compressed context + compressed = recent_messages.copy() + + if summary: + # Add summary as a system message + compressed.insert(0, { + "role": "system", + "content": f"[Previous conversation summary]\n{summary}", + }) + + logger.info(f"Context compressed: {len(older_messages)} messages summarized") + return compressed, summary + + def _keep_recent_messages( + self, + messages: list[dict[str, Any]], + max_tokens: int, + ) -> list[dict[str, Any]]: + """Keep recent messages within token limit.""" + result = [] + total_tokens = 0 + + # Process from newest to oldest + for msg in reversed(messages): + content = msg.get("content", "") + tokens = self.summarizer.estimate_tokens(content) + + if total_tokens + tokens > max_tokens: + break + + result.insert(0, msg) + total_tokens += tokens + + return result + + def _get_older_messages( + self, + messages: list[dict[str, Any]], + keep_tokens: int, + ) -> list[dict[str, Any]]: + """Get older messages that should be summarized.""" + result = [] + total_tokens = 0 + + # Process from oldest to newest + for msg in messages: + content = msg.get("content", "") + tokens = self.summarizer.estimate_tokens(content) + + if total_tokens + tokens > keep_tokens: + result.append(msg) + total_tokens += tokens + + return result + + def get_compaction_count(self) -> int: + """Get number of compactions performed.""" + return self._compaction_count + + +class MemoryDecayManager: + """Memory importance decay manager.""" + + def __init__(self, config: SummarizationConfig | None = None): + """Initialize decay manager. + + Args: + config: Summarization configuration + """ + self.config = config or SummarizationConfig() + + def calculate_decay( + self, + importance: int, + last_accessed: datetime, + is_evergreen: bool = False, + ) -> int: + """Calculate decayed importance. + + Args: + importance: Original importance (1-10) + last_accessed: Last access timestamp + is_evergreen: Whether memory is marked as evergreen + + Returns: + Decayed importance + """ + if is_evergreen: + return importance + + # Calculate days since last access + days_since = (datetime.now() - last_accessed).days + + if days_since < self.config.decay_days_no_activity: + return importance + + # Calculate decay periods + decay_periods = ( + days_since - self.config.decay_days_no_activity + ) // self.config.decay_days_no_activity + + # Apply decay + decay_factor = self.config.decay_factor ** decay_periods + decayed = int(importance * decay_factor) + + # Ensure minimum importance of 1 + return max(1, decayed) + + def should_archive(self, importance: int, last_accessed: datetime) -> bool: + """Check if memory should be archived. + + Args: + importance: Current importance + last_accessed: Last access timestamp + + Returns: + True if should be archived + """ + # Archive if importance has decayed to 1 and no recent access + decayed = self.calculate_decay(importance, last_accessed) + days_since = (datetime.now() - last_accessed).days + + return decayed == 1 and days_since > self.config.decay_days_no_activity * 3 + + +class EvergreenManager: + """Evergreen (persistent) memory manager.""" + + def __init__(self, config: SummarizationConfig | None = None): + """Initialize evergreen manager. + + Args: + config: Summarization configuration + """ + self.config = config or SummarizationConfig() + + def should_mark_evergreen( + self, + importance: int, + memory_type: str, + content: str, + ) -> bool: + """Determine if memory should be marked as evergreen. + + Args: + importance: Importance score + memory_type: Type of memory + content: Memory content + + Returns: + True if should be evergreen + """ + # High importance memories are evergreen + if importance >= self.config.evergreen_importance_threshold: + return True + + # Certain memory types are typically evergreen + evergreen_types = {"preference", "identity", "configuration"} + if memory_type in evergreen_types: + return True + + # Check for evergreen keywords in content + evergreen_keywords = [ + "always", "never", "permanent", "fixed", + "my name is", "i am", "preference", + ] + content_lower = content.lower() + if any(kw in content_lower for kw in evergreen_keywords): + return True + + return False + + def format_evergreen_prompt(self, memories: list[dict[str, Any]]) -> str: + """Format evergreen memories for system prompt. + + Args: + memories: List of evergreen memories + + Returns: + Formatted prompt + """ + if not memories: + return "" + + lines = ["[Evergreen Memories]"] + for mem in memories: + content = mem.get("content", "") + memory_type = mem.get("memory_type", "general") + lines.append(f"- [{memory_type}] {content}") + + return "\n".join(lines) + + +class IntelligentMemorySystem: + """Complete intelligent memory management system.""" + + def __init__( + self, + llm_provider=None, + config: SummarizationConfig | None = None, + ): + """Initialize intelligent memory system. + + Args: + llm_provider: LLM provider for summarization + config: System configuration + """ + self.config = config or SummarizationConfig() + + # Initialize components + self.summarizer = MemorySummarizer(llm_provider, self.config) + self.compressor = ContextCompressor(self.summarizer, self.config) + self.decay_manager = MemoryDecayManager(self.config) + self.evergreen_manager = EvergreenManager(self.config) + + async def process_message( + self, + messages: list[dict[str, Any]], + current_tokens: int, + agent_id: str, + user_id: str = "default", + ) -> tuple[list[dict[str, Any]], dict[str, Any] | None]: + """Process incoming message with intelligent memory management. + + Args: + messages: Current conversation messages + current_tokens: Current token count + agent_id: Agent ID + user_id: User ID + + Returns: + Tuple of (processed messages, memory to save) + """ + # Check if compression needed + processed_messages, summary = await self.compressor.compress_context( + messages, + current_tokens, + ) + + memory_to_save = None + if summary: + memory_to_save = { + "content": f"[Conversation Summary]\n{summary}", + "agent_id": agent_id, + "user_id": user_id, + "memory_type": "summary", + "importance": 5, + } + + return processed_messages, memory_to_save + + def get_evergreen_context( + self, + memories: list[dict[str, Any]], + ) -> str: + """Get evergreen memories formatted for context. + + Args: + memories: List of all memories + + Returns: + Formatted evergreen context + """ + evergreen = [ + m for m in memories + if m.get("is_evergreen", False) + or self.evergreen_manager.should_mark_evergreen( + m.get("importance", 5), + m.get("memory_type", ""), + m.get("content", ""), + ) + ] + return self.evergreen_manager.format_evergreen_prompt(evergreen) + + def apply_decay( + self, + memories: list[dict[str, Any]], + ) -> list[dict[str, Any]]: + """Apply decay to memories. + + Args: + memories: List of memories + + Returns: + Memories with updated importance + """ + updated = [] + for mem in memories: + last_accessed = mem.get("last_accessed_at") + if isinstance(last_accessed, str): + last_accessed = datetime.fromisoformat(last_accessed) + elif not last_accessed: + last_accessed = datetime.now() + + is_evergreen = mem.get("is_evergreen", False) + + new_importance = self.decay_manager.calculate_decay( + mem.get("importance", 5), + last_accessed, + is_evergreen, + ) + + mem["importance"] = new_importance + mem["should_archive"] = self.decay_manager.should_archive( + new_importance, + last_accessed, + ) + updated.append(mem) + + return updated + + +def create_intelligent_memory_system( + llm_provider=None, + context_window: int = 200000, + reserve_tokens: int = 20000, +) -> IntelligentMemorySystem: + """Create intelligent memory system with configuration. + + Args: + llm_provider: LLM provider + context_window: Model context window size + reserve_tokens: Reserved tokens + + Returns: + Configured IntelligentMemorySystem + """ + config = SummarizationConfig( + context_window=context_window, + reserve_tokens=reserve_tokens, + ) + return IntelligentMemorySystem(llm_provider=llm_provider, config=config) diff --git a/core/agents/agent/loop.py b/core/agents/agent/loop.py new file mode 100644 index 0000000..c2dd6fd --- /dev/null +++ b/core/agents/agent/loop.py @@ -0,0 +1,463 @@ +"""Agent run loop - complete implementation.""" + +import asyncio +import json +import logging +import re +from datetime import datetime +from pathlib import Path +from typing import Any, Callable, Awaitable, AsyncGenerator + +from agents.agent.context import ContextBuilder +from agents.agent.memory import AgentMemory +from agents.llm import LLMProvider, LLMResponse, ProviderFactory +from agents.tools import ToolRegistry + +logger = logging.getLogger(__name__) + + +class AgentLoop: + """Agent loop with message processing, LLM calls, tool execution, and streaming.""" + + _TOOL_RESULT_MAX_CHARS = 10000 + + def __init__( + self, + provider: LLMProvider, + model: str, + workspace: Path | None = None, + max_iterations: int = 10, + tools: ToolRegistry | None = None, + ): + """Initialize the agent loop. + + Args: + provider: LLM provider (OpenAI, Anthropic, etc.) + model: Model name to use + workspace: Workspace directory for memory and configs + max_iterations: Maximum tool call iterations + tools: Tool registry (creates default if None) + """ + self.provider = provider + self.model = model + self.workspace = workspace or Path.cwd() + self.max_iterations = max_iterations + self.tools = tools + + self.context = ContextBuilder(self.workspace) + self.memory = AgentMemory(self.workspace) + + async def chat( + self, + message: str, + history: list[dict[str, Any]] | None = None, + session_key: str = "default", + on_progress: Callable[[str], Awaitable[None]] | None = None, + model_id: str | None = None, + model_name: str | None = None, + model_provider: str | None = None, + api_key: str | None = None, + base_url: str | None = None, + use_xbot: bool = False, + ) -> str: + """Process a chat message and return the response. + + Args: + message: User message + history: Conversation history + session_key: Session identifier + on_progress: Optional callback for progress updates + model_id: Model ID (optional) + model_name: Model name (optional) + model_provider: Model provider (optional) + api_key: API key (optional) + base_url: Custom API base URL (optional) + use_xbot: Use xbot mode (optional) + + Returns: + Agent response content + """ + history = history or [] + + # Check if dynamic provider parameters are provided + if api_key or model_provider: + logger.info(f"Using dynamic provider: model_provider={model_provider}, model_name={model_name}, base_url={base_url}") + # Create temporary provider with dynamic parameters + temp_provider = ProviderFactory.create( + provider=model_provider or "openai", + api_key=api_key, + api_base=base_url, + ) + # Use temporary provider and model + temp_model = model_name or temp_provider.get_default_model() + logger.info(f"Created temp provider with model: {temp_model}") + return await self._chat_with_provider( + message=message, + history=history, + session_key=session_key, + on_progress=on_progress, + provider=temp_provider, + model=temp_model, + ) + + # Build messages for LLM + messages = self.context.build_messages( + history=history, + current_message=message, + ) + + # Log which provider is being used + logger.info(f"Using static provider: {type(self.provider).__name__}, model={self.model}") + + # Run the agent loop + final_content, tools_used, all_messages = await self._run_loop( + messages, on_progress + ) + + # Save to history + self._save_history(session_key, all_messages, len(history)) + + return final_content or "No response generated." + + async def _chat_with_provider( + self, + message: str, + history: list[dict[str, Any]] | None = None, + session_key: str = "default", + on_progress: Callable[[str], Awaitable[None]] | None = None, + provider: LLMProvider | None = None, + model: str | None = None, + ) -> str: + """Chat with a specific provider (used for dynamic provider support). + + Args: + message: User message + history: Conversation history + session_key: Session identifier + on_progress: Optional callback for progress updates + provider: LLM provider to use + model: Model name to use + + Returns: + Agent response content + """ + history = history or [] + provider = provider or self.provider + model = model or self.model + + # Build messages for LLM + messages = self.context.build_messages( + history=history, + current_message=message, + ) + + # Run the agent loop with custom provider + final_content, tools_used, all_messages = await self._run_loop( + messages, on_progress, provider=provider, model=model + ) + + # Save to history + self._save_history(session_key, all_messages, len(history)) + + return final_content or "No response generated." + + async def chat_stream( + self, + message: str, + history: list[dict[str, Any]] | None = None, + session_key: str = "default", + model_id: str | None = None, + model_name: str | None = None, + model_provider: str | None = None, + api_key: str | None = None, + base_url: str | None = None, + use_xbot: bool = False, + ) -> AsyncGenerator[str, None]: + """Process a chat message with streaming response. + + Args: + message: User message + history: Conversation history + session_key: Session identifier + model_id: Model ID (optional) + model_name: Model name (optional) + model_provider: Model provider (optional) + api_key: API key (optional) + base_url: Custom API base URL (optional) + use_xbot: Use xbot mode (optional) + + Yields: + Response content chunks + """ + history = history or [] + + # Check if dynamic provider parameters are provided + if api_key or model_provider: + logger.info(f"[stream] Using dynamic provider: model_provider={model_provider}, model_name={model_name}, base_url={base_url}") + # Create temporary provider with dynamic parameters + temp_provider = ProviderFactory.create( + provider=model_provider or "openai", + api_key=api_key, + api_base=base_url, + ) + # Use temporary provider and model + temp_model = model_name or temp_provider.get_default_model() + logger.info(f"[stream] Created temp provider with model: {temp_model}") + async for chunk in self._chat_stream_with_provider( + message=message, + history=history, + session_key=session_key, + provider=temp_provider, + model=temp_model, + ): + yield chunk + return + + # Build messages for LLM + messages = self.context.build_messages( + history=history, + current_message=message, + ) + + # Stream the response + async for chunk in self._run_loop_stream(messages): + yield chunk + + async def _chat_stream_with_provider( + self, + message: str, + history: list[dict[str, Any]] | None = None, + session_key: str = "default", + provider: LLMProvider | None = None, + model: str | None = None, + ) -> AsyncGenerator[str, None]: + """Stream chat with a specific provider (used for dynamic provider support). + + Args: + message: User message + history: Conversation history + session_key: Session identifier + provider: LLM provider to use + model: Model name to use + + Yields: + Response content chunks + """ + history = history or [] + provider = provider or self.provider + model = model or self.model + + # Build messages for LLM + messages = self.context.build_messages( + history=history, + current_message=message, + ) + + # Stream the response with custom provider + async for chunk in self._run_loop_stream(messages, provider=provider, model=model): + yield chunk + + async def _run_loop( + self, + initial_messages: list[dict], + on_progress: Callable[..., Awaitable[None]] | None = None, + provider: LLMProvider | None = None, + model: str | None = None, + ) -> tuple[str | None, list[str], list[dict]]: + """Run the agent iteration loop. + + Args: + initial_messages: Initial message list + on_progress: Progress callback + provider: Optional LLM provider to use (defaults to self.provider) + model: Optional model name to use (defaults to self.model) + + Returns: + Tuple of (final_content, tools_used, all_messages) + """ + messages = initial_messages + iteration = 0 + final_content = None + tools_used: list[str] = [] + provider = provider or self.provider + model = model or self.model + + tool_defs = self.tools.get_definitions() if self.tools else [] + + while iteration < self.max_iterations: + iteration += 1 + + # Call LLM + response = await provider.chat_with_retry( + messages=messages, + tools=tool_defs if tool_defs else None, + model=model, + ) + + if response.has_tool_calls: + # Progress callback for tool calls + if on_progress: + thought = self._strip_think(response.content) + if thought: + await on_progress(thought) + await on_progress(self._tool_hint(response.tool_calls), tool_hint=True) + + # Add assistant message with tool calls + tool_call_dicts = [tc.to_dict() for tc in response.tool_calls] + messages = self.context.add_assistant_message( + messages, + response.content, + tool_call_dicts, + reasoning_content=response.reasoning_content, + ) + + # Execute tools + for tool_call in response.tool_calls: + tools_used.append(tool_call.name) + args = tool_call.arguments + logger.info(f"Tool call: {tool_call.name}({args})") + + # Execute tool + result = await self._execute_tool(tool_call.name, args) + + # Truncate large results + if len(result) > self._TOOL_RESULT_MAX_CHARS: + result = result[:self._TOOL_RESULT_MAX_CHARS] + "\n... (truncated)" + + # Add tool result + messages = self.context.add_tool_result( + messages, tool_call.id, tool_call.name, result + ) + else: + # No tool calls - return the response + clean = self._strip_think(response.content) + + # Handle errors + if response.finish_reason == "error": + logger.error(f"LLM error: {clean}") + final_content = clean or "Sorry, I encountered an error calling the AI model." + break + + messages = self.context.add_assistant_message( + messages, clean, reasoning_content=response.reasoning_content + ) + final_content = clean + break + + if final_content is None and iteration >= self.max_iterations: + logger.warning(f"Max iterations ({self.max_iterations}) reached") + final_content = ( + f"I reached the maximum number of iterations ({self.max_iterations}) " + "without completing the task." + ) + + return final_content, tools_used, messages + + async def _run_loop_stream( + self, + initial_messages: list[dict], + provider: LLMProvider | None = None, + model: str | None = None, + ) -> AsyncGenerator[str, None]: + """Run the agent loop with streaming response. + + Args: + initial_messages: Initial message list + provider: Optional LLM provider to use (defaults to self.provider) + model: Optional model name to use (defaults to self.model) + + Yields: + Response content chunks + """ + provider = provider or self.provider + model = model or self.model + tool_defs = self.tools.get_definitions() if self.tools else [] + + # First call to check for tool calls + response = await provider.chat_with_retry( + messages=initial_messages, + tools=tool_defs if tool_defs else None, + model=model, + ) + + if response.has_tool_calls: + # Execute tools first + for tool_call in response.tool_calls: + logger.info(f"Tool call: {tool_call.name}") + result = await self._execute_tool(tool_call.name, tool_call.arguments) + + # Add to messages + initial_messages = self.context.add_tool_result( + initial_messages, tool_call.id, tool_call.name, result + ) + + # Recursive call after tool execution + async for chunk in self._run_loop_stream(initial_messages, provider=provider, model=model): + yield chunk + else: + # Stream the content + content = self._strip_think(response.content) + if content: + yield content + + async def _execute_tool(self, tool_name: str, args: dict) -> str: + """Execute a tool. + + Args: + tool_name: Name of the tool to execute + args: Tool arguments + + Returns: + Tool execution result + """ + if self.tools: + return await self.tools.execute(tool_name, args) + return json.dumps({"error": "No tools registered"}) + + @staticmethod + def _strip_think(text: str | None) -> str | None: + """Strip think blocks that some models embed in content.""" + if not text: + return None + import re + # Match content between [/INST] or [/CONTINUE] tags commonly used in thinking + patterns = [ + r"[\s\S]*?", + r"<\/?think>", + ] + for pattern in patterns: + text = re.sub(pattern, "", text) + return text.strip() or None + + @staticmethod + def _tool_hint(tool_calls: list) -> str: + """Format tool calls as concise hint.""" + def _fmt(tc): + args = tc.arguments or {} + val = next(iter(args.values()), None) if isinstance(args, dict) else None + if not isinstance(val, str): + return tc.name + return f'{tc.name}("{val[:40]}...")' if len(val) > 40 else f'{tc.name}("{val}")' + return ", ".join(_fmt(tc) for tc in tool_calls) + + def _save_history( + self, + session_key: str, + messages: list[dict], + skip: int = 0, + ) -> None: + """Save messages to history. + + Args: + session_key: Session identifier + messages: Messages to save + skip: Number of messages to skip + """ + for m in messages[skip:]: + role = m.get("role") + content = m.get("content") + + if role == "user" and content: + self.memory.add_to_history("user", str(content)[:1000], session_key) + elif role == "assistant" and content: + self.memory.add_to_history("assistant", str(content)[:1000], session_key) diff --git a/core/agents/agent/memory.py b/core/agents/agent/memory.py new file mode 100644 index 0000000..357468e --- /dev/null +++ b/core/agents/agent/memory.py @@ -0,0 +1,939 @@ +"""Memory management for agent sessions.""" + +import json +import logging +from collections import defaultdict +from datetime import datetime +from pathlib import Path +from typing import Any + +import aiohttp + +logger = logging.getLogger(__name__) + + +class SessionMemory: + """短期会话记忆 - 内存中的会话消息存储，支持 Markdown 持久化""" + + def __init__(self, max_messages: int = 50, workspace: Path | str | None = None): + """初始化会话记忆 + + Args: + max_messages: 每个会话保留的最大消息数 + workspace: 工作区目录，用于持久化会话文件 + """ + self.max_messages = max_messages + self._sessions: dict[str, list[dict[str, Any]]] = defaultdict(list) + + # 持久化支持 + self.workspace = Path(workspace) if workspace else None + self.sessions_dir = None + if self.workspace: + self.sessions_dir = self.workspace / "sessions" + self.sessions_dir.mkdir(parents=True, exist_ok=True) + # 启动时加载所有会话 + self._load_all_sessions() + + def _get_session_file(self, session_id: str) -> Path | None: + """获取会话文件路径""" + if not self.sessions_dir: + return None + # 清理 session_id 中的非法文件名字符 + safe_id = "".join(c if c.isalnum() or c in "-_" else "_" for c in session_id) + return self.sessions_dir / f"{safe_id}.md" + + def _load_all_sessions(self) -> None: + """启动时加载所有会话文件""" + if not self.sessions_dir or not self.sessions_dir.exists(): + return + + for session_file in self.sessions_dir.glob("*.md"): + session_id = session_file.stem + self._load_session(session_id) + logger.info(f"Loaded session from file: {session_id}") + + def _load_session(self, session_id: str) -> list[dict[str, Any]]: + """从文件加载单个会话 + + Args: + session_id: 会话ID + + Returns: + 消息列表 + """ + session_file = self._get_session_file(session_id) + if not session_file or not session_file.exists(): + return [] + + try: + content = session_file.read_text(encoding="utf-8") + messages = [] + lines = content.strip().split("\n") + + current_message = {} + for line in lines: + line = line.strip() + if not line: + continue + + # 解析 "## 消息 N" 格式 + if line.startswith("## 消息"): + # 保存上一条消息 + if current_message: + messages.append(current_message) + + current_message = { + "role": "", + "timestamp": "", + "content": "", + } + continue + + # 解析 "角色: xxx" + if line.startswith("角色:") and current_message is not None: + current_message["role"] = line.split(":", 1)[1].strip() + continue + + # 解析 "时间: xxx" + if line.startswith("时间:") and current_message is not None: + current_message["timestamp"] = line.split(":", 1)[1].strip() + continue + + # 解析 "内容: xxx" + if line.startswith("内容:") and current_message is not None: + current_message["content"] = line.split(":", 1)[1].strip() + continue + + # 保存最后一条消息 + if current_message and current_message.get("role"): + messages.append(current_message) + + # 加载到内存 + if messages: + self._sessions[session_id] = messages[-self.max_messages:] + + return messages + + except Exception as e: + logger.error(f"Error loading session {session_id}: {e}") + return [] + + def _save_session(self, session_id: str) -> None: + """将会话保存到文件 + + Args: + session_id: 会话ID + """ + session_file = self._get_session_file(session_id) + if not session_file: + return + + messages = self._sessions.get(session_id, []) + if not messages: + # 如果会话为空，删除文件 + if session_file.exists(): + session_file.unlink() + return + + # 构建 Markdown 内容（使用产品经理指定的格式） + created_time = messages[0].get("timestamp", datetime.now().isoformat()) if messages else datetime.now().isoformat() + created_time_str = created_time.replace("T", " ") if "T" in created_time else created_time + + lines = [ + f"# 会话: {session_id}", + f"创建时间: {created_time_str}", + "", + ] + + for i, msg in enumerate(messages, 1): + role = msg.get("role", "unknown") + timestamp = msg.get("timestamp", "") + content = msg.get("content", "") + + # 格式化时间 + if "T" in timestamp: + timestamp = timestamp.replace("T", " ") + + lines.append(f"## 消息 {i}") + lines.append(f"角色: {role}") + lines.append(f"时间: {timestamp}") + lines.append(f"内容: {content}") + lines.append("") + + try: + session_file.write_text("\n".join(lines), encoding="utf-8") + except Exception as e: + logger.error(f"Error saving session {session_id}: {e}") + + def add_message(self, session_id: str, role: str, content: str, metadata: dict | None = None) -> None: + """添加消息到会话 + + Args: + session_id: 会话ID + role: 消息角色 (user/assistant/system) + content: 消息内容 + metadata: 附加元数据 + """ + message = { + "role": role, + "content": content, + "timestamp": datetime.now().isoformat(), + } + if metadata: + message["metadata"] = metadata + + session_messages = self._sessions[session_id] + session_messages.append(message) + + # 超过最大消息数时，移除最旧的消息 + if len(session_messages) > self.max_messages: + self._sessions[session_id] = session_messages[-self.max_messages:] + + # 持久化到文件 + self._save_session(session_id) + + def get_history(self, session_id: str, max_messages: int = 0) -> list[dict[str, Any]]: + """获取会话历史 + + Args: + session_id: 会话ID + max_messages: 返回的最大消息数，0表示全部 + + Returns: + 消息列表 + """ + # 如果内存中没有，尝试从文件加载 + if session_id not in self._sessions: + self._load_session(session_id) + + messages = self._sessions.get(session_id, []) + if max_messages > 0 and len(messages) > max_messages: + return messages[-max_messages:] + return messages + + def clear_session(self, session_id: str) -> None: + """清除会话记忆 + + Args: + session_id: 会话ID + """ + if session_id in self._sessions: + del self._sessions[session_id] + + # 删除会话文件 + session_file = self._get_session_file(session_id) + if session_file and session_file.exists(): + session_file.unlink() + + def get_session_count(self) -> int: + """获取当前会话数量""" + return len(self._sessions) + + def list_sessions(self) -> list[str]: + """列出所有会话ID""" + return list(self._sessions.keys()) + + +class RemoteMemoryClient: + """与Go端Memory API对接的客户端""" + + def __init__(self, base_url: str, agent_id: str, user_id: str = "default"): + """初始化远程记忆客户端 + + Args: + base_url: Go服务端地址 + agent_id: Agent ID + user_id: 用户ID + """ + self.base_url = base_url.rstrip("/") + self.agent_id = agent_id + self.user_id = user_id + self._session = None + + async def _get_session(self) -> aiohttp.ClientSession: + """获取或创建aiohttp session""" + if self._session is None or self._session.closed: + self._session = aiohttp.ClientSession() + return self._session + + async def close(self) -> None: + """关闭session""" + if self._session and not self._session.closed: + await self._session.close() + + async def create_memory( + self, + content: str, + memory_type: str = "conversation", + importance: int = 5, + ) -> dict[str, Any] | None: + """创建记忆 + + Args: + content: 记忆内容 + memory_type: 记忆类型 (conversation/experience/lessons) + importance: 重要性评分 1-10 + + Returns: + 创建的记忆对象 + """ + url = f"{self.base_url}/api/agent/{self.agent_id}/memories" + payload = { + "agent_id": self.agent_id, + "user_id": self.user_id, + "content": content, + "memory_type": memory_type, + "importance": importance, + } + + try: + session = await self._get_session() + async with session.post(url, json=payload) as response: + if response.status == 200: + return await response.json() + logger.warning(f"Failed to create memory: {response.status}") + return None + except Exception as e: + logger.error(f"Error creating memory: {e}") + return None + + async def get_memories( + self, + limit: int = 10, + offset: int = 0, + memory_type: str | None = None, + category: str | None = None, + ) -> list[dict[str, Any]]: + """获取记忆列表 + + Args: + limit: 返回数量限制 + offset: 偏移量 + memory_type: 记忆类型筛选 + category: 分类筛选 + + Returns: + 记忆列表 + """ + url = f"{self.base_url}/api/agent/{self.agent_id}/memories" + params = { + "user_id": self.user_id, + "limit": limit, + "offset": offset, + } + if memory_type: + params["memory_type"] = memory_type + if category: + params["category"] = category + + try: + session = await self._get_session() + async with session.get(url, params=params) as response: + if response.status == 200: + result = await response.json() + return result if isinstance(result, list) else result.get("list", []) + return [] + except Exception as e: + logger.error(f"Error getting memories: {e}") + return [] + + async def search_memories( + self, + keyword: str, + tags: str | None = None, + category: str | None = None, + memory_type: str | None = None, + min_score: int = 0, + limit: int = 10, + offset: int = 0, + ) -> list[dict[str, Any]]: + """搜索记忆（关键词搜索） + + Args: + keyword: 搜索关键词 + tags: 标签筛选 + category: 分类筛选 + memory_type: 记忆类型筛选 + min_score: 最低重要性分数 + limit: 返回数量限制 + offset: 偏移量 + + Returns: + 记忆列表 + """ + url = f"{self.base_url}/api/agent/{self.agent_id}/memories/search" + payload = { + "agent_id": self.agent_id, + "user_id": self.user_id, + "keyword": keyword, + "limit": limit, + "offset": offset, + } + if tags: + payload["tags"] = tags + if category: + payload["category"] = category + if memory_type: + payload["memory_type"] = memory_type + if min_score > 0: + payload["min_score"] = min_score + + try: + session = await self._get_session() + async with session.post(url, json=payload) as response: + if response.status == 200: + result = await response.json() + return result.get("list", []) + return [] + except Exception as e: + logger.error(f"Error searching memories: {e}") + return [] + + async def get_categories(self) -> list[str]: + """获取记忆分类列表 + + Returns: + 分类列表 + """ + url = f"{self.base_url}/api/agent/{self.agent_id}/memories/categories" + params = {"user_id": self.user_id} + + try: + session = await self._get_session() + async with session.get(url, params=params) as response: + if response.status == 200: + result = await response.json() + return result.get("categories", []) + return [] + except Exception as e: + logger.error(f"Error getting categories: {e}") + return [] + + async def get_tags(self) -> list[str]: + """获取记忆标签列表 + + Returns: + 标签列表 + """ + url = f"{self.base_url}/api/agent/{self.agent_id}/memories/tags" + params = {"user_id": self.user_id} + + try: + session = await self._get_session() + async with session.get(url, params=params) as response: + if response.status == 200: + result = await response.json() + return result.get("tags", []) + return [] + except Exception as e: + logger.error(f"Error getting tags: {e}") + return [] + + async def delete_memory(self, memory_id: str) -> bool: + """删除记忆 + + Args: + memory_id: 记忆ID + + Returns: + 是否删除成功 + """ + url = f"{self.base_url}/api/agent/{self.agent_id}/memories/{memory_id}" + + try: + session = await self._get_session() + async with session.delete(url) as response: + return response.status == 200 + except Exception as e: + logger.error(f"Error deleting memory: {e}") + return False + + +class AgentMemory: + """Manages agent memory and session history.""" + + def __init__(self, workspace: Path): + """Initialize the memory manager. + + Args: + workspace: Workspace directory for storing memory + """ + self.workspace = workspace + self.memory_dir = workspace / "memory" + self.memory_dir.mkdir(exist_ok=True) + + self.long_term_file = self.memory_dir / "MEMORY.md" + + # Session-specific history + self.sessions_dir = self.memory_dir / "sessions" + self.sessions_dir.mkdir(exist_ok=True) + + # Legacy history file (for backward compatibility) + self.history_file = self.memory_dir / "HISTORY.md" + + def _get_session_file(self, session_key: str) -> Path: + """Get session file path.""" + # Sanitize session_key for filename + safe_key = "".join(c if c.isalnum() or c in "-_" else "_" for c in session_key) + return self.sessions_dir / f"{safe_key}.md" + + def get_memory_context(self) -> str: + """Get long-term memory content. + + Returns: + Memory context string + """ + if self.long_term_file.exists(): + return self.long_term_file.read_text(encoding="utf-8") + return "" + + def add_to_memory(self, content: str) -> None: + """Add content to long-term memory. + + Args: + content: Content to add to memory + """ + with open(self.long_term_file, "a", encoding="utf-8") as f: + f.write(f"\n{content}") + + def add_to_history(self, role: str, content: str, session_key: str | None = None) -> None: + """Add an entry to conversation history. + + Args: + role: Message role (user/assistant) + content: Message content + session_key: Session identifier for session-specific history + """ + timestamp = datetime.now().isoformat() + + # If session_key provided, save to session file + if session_key: + self._add_to_session_history(session_key, role, content, timestamp) + else: + # Legacy: save to global history file + legacy_timestamp = datetime.now().strftime("%Y-%m-%d %H:%M") + entry = f"[{legacy_timestamp}] {role}: {content}\n" + with open(self.history_file, "a", encoding="utf-8") as f: + f.write(entry) + + def _add_to_session_history(self, session_key: str, role: str, content: str, timestamp: str) -> None: + """Add message to session-specific history file.""" + session_file = self._get_session_file(session_key) + + # Format timestamp for display + display_timestamp = timestamp.replace("T", " ") if "T" in timestamp else timestamp + + # Determine header format based on whether file exists + header = "" + if not session_file.exists(): + header = f"# 会话: {session_key}\n创建时间: {display_timestamp}\n\n" + + # Count existing messages to determine message number + msg_count = 1 + if session_file.exists(): + try: + existing = session_file.read_text(encoding="utf-8") + msg_count = existing.count("## 消息") + 1 + except: + pass + + # Format as Markdown (产品经理指定格式) + entry = f"## 消息 {msg_count}\n角色: {role}\n时间: {display_timestamp}\n内容: {content}\n\n" + + with open(session_file, "a", encoding="utf-8") as f: + if header: + f.write(header) + f.write(entry) + + def get_history( + self, + session_key: str | None = None, + max_messages: int = 10, + ) -> list[dict[str, Any]]: + """Get conversation history. + + Args: + session_key: Optional session key for session-specific history + max_messages: Maximum number of messages to return + + Returns: + List of history messages + """ + # If session_key provided, load from session file + if session_key: + return self._get_session_history(session_key, max_messages) + + # Legacy: load from global history file + return self._get_legacy_history(max_messages) + + def _get_session_history(self, session_key: str, max_messages: int) -> list[dict[str, Any]]: + """Get history from session file.""" + session_file = self._get_session_file(session_key) + if not session_file.exists(): + return [] + + try: + content = session_file.read_text(encoding="utf-8") + lines = content.strip().split("\n") + messages = [] + + current_message = {} + for line in lines: + line = line.strip() + if not line: + continue + + # Skip headers + if line.startswith("#"): + continue + + # Parse "## 消息 N" + if line.startswith("## 消息"): + # Save previous message + if current_message and current_message.get("role"): + messages.append(current_message) + + current_message = { + "role": "", + "timestamp": "", + "content": "", + } + continue + + # Parse "角色: xxx" + if line.startswith("角色:") and current_message is not None: + current_message["role"] = line.split(":", 1)[1].strip() + continue + + # Parse "时间: xxx" + if line.startswith("时间:") and current_message is not None: + current_message["timestamp"] = line.split(":", 1)[1].strip() + continue + + # Parse "内容: xxx" + if line.startswith("内容:") and current_message is not None: + current_message["content"] = line.split(":", 1)[1].strip() + continue + + # Content line + if current_message: + if current_message["content"]: + current_message["content"] += "\n" + line + else: + current_message["content"] = line + + # Save last message + if current_message: + messages.append(current_message) + + # Return most recent messages + if max_messages > 0 and len(messages) > max_messages: + return messages[-max_messages:] + return messages + + except Exception as e: + logger.error(f"Error reading session history: {e}") + return [] + + def _get_legacy_history(self, max_messages: int) -> list[dict[str, Any]]: + """Get history from legacy history file.""" + if not self.history_file.exists(): + return [] + + try: + content = self.history_file.read_text(encoding="utf-8") + lines = content.strip().split("\n") + messages = [] + + for line in lines[-max_messages * 2:]: + if ": " in line: + try: + _, rest = line.split("] ", 1) + role, content = rest.split(": ", 1) + messages.append({"role": role, "content": content}) + except ValueError: + continue + + return messages[-max_messages:] if max_messages > 0 else messages + + except Exception as e: + logger.error(f"Error reading legacy history: {e}") + return [] + + def clear_session(self, session_key: str) -> None: + """Clear a specific session's history. + + Args: + session_key: Session key to clear + """ + session_file = self._get_session_file(session_key) + if session_file.exists(): + session_file.unlink() + + for line in lines[-max_messages * 2:]: + if ": " in line: + # Skip timestamp prefix + try: + _, rest = line.split("] ", 1) + role, content = rest.split(": ", 1) + messages.append({"role": role, "content": content}) + except ValueError: + continue + + return messages[-max_messages:] + + return [] + + def clear_session(self, session_key: str) -> None: + """Clear a specific session's history. + + Args: + session_key: Session key to clear + """ + # In a full implementation, you'd handle session-specific storage + pass + + +# Vector memory integration +try: + from .vector_memory import ( + VectorMemoryStore, + HybridMemorySearch, + EmbeddingProvider, + create_vector_memory_store, + ) + VECTOR_MEMORY_AVAILABLE = True +except ImportError: + VectorMemoryStore = None + HybridMemorySearch = None + EmbeddingProvider = None + create_vector_memory_store = None + VECTOR_MEMORY_AVAILABLE = False + + +class EnhancedAgentMemory(AgentMemory): + """Enhanced agent memory with vector search capabilities.""" + + def __init__( + self, + workspace: Path, + enable_vector_search: bool = False, + vector_persist_dir: str | None = None, + embedding_provider: str = "openai", + embedding_model: str = "text-embedding-3-small", + ): + """Initialize enhanced memory manager. + + Args: + workspace: Workspace directory for storing memory + enable_vector_search: Enable vector search (requires dependencies) + vector_persist_dir: Directory for vector store persistence + embedding_provider: Provider type (openai, anthropic, local) + embedding_model: Model name for embeddings + """ + super().__init__(workspace) + + self.enable_vector_search = enable_vector_search and VECTOR_MEMORY_AVAILABLE + self.vector_store = None + self.hybrid_search = None + self._embedding_provider_type = embedding_provider + self._embedding_model = embedding_model + + if self.enable_vector_search: + try: + self.vector_store = create_vector_memory_store( + persist_dir=vector_persist_dir, + provider_type=embedding_provider, + model=embedding_model, + ) + if self.vector_store: + self.hybrid_search = HybridMemorySearch(self.vector_store) + logger.info(f"Vector search enabled for agent memory (provider: {embedding_provider})") + except Exception as e: + logger.warning(f"Failed to initialize vector store: {e}") + self.enable_vector_search = False + + async def add_memory_with_embedding( + self, + content: str, + agent_id: str, + user_id: str = "default", + memory_type: str = "conversation", + importance: int = 5, + ) -> str | None: + """Add memory with automatic embedding. + + Args: + content: Memory content + agent_id: Agent ID + user_id: User ID + memory_type: Type of memory + importance: Importance score (1-10) + + Returns: + Memory ID if vector search enabled + """ + # Also save to markdown file (base class behavior) + self.add_to_memory(content) + + # Add to vector store if enabled + if self.vector_store: + return await self.vector_store.add_memory( + content=content, + agent_id=agent_id, + user_id=user_id, + memory_type=memory_type, + importance=importance, + ) + return None + + async def search_memories( + self, + query: str, + agent_id: str | None = None, + user_id: str | None = None, + n_results: int = 5, + ) -> list[dict[str, Any]]: + """Search memories by semantic similarity. + + Args: + query: Search query + agent_id: Filter by agent ID + user_id: Filter by user ID + n_results: Number of results + + Returns: + List of matching memories + """ + if not self.hybrid_search: + logger.warning("Vector search not enabled") + return [] + + return await self.hybrid_search.search( + query=query, + agent_id=agent_id, + user_id=user_id, + n_results=n_results, + ) + + +# Intelligent memory system integration +try: + from .intelligent_memory import ( + IntelligentMemorySystem, + MemorySummarizer, + ContextCompressor, + MemoryDecayManager, + EvergreenManager, + SummarizationConfig, + create_intelligent_memory_system, + ) + INTELLIGENT_MEMORY_AVAILABLE = True +except ImportError: + IntelligentMemorySystem = None + MemorySummarizer = None + ContextCompressor = None + MemoryDecayManager = None + EvergreenManager = None + SummarizationConfig = None + create_intelligent_memory_system = None + INTELLIGENT_MEMORY_AVAILABLE = False + + +class CompleteAgentMemory: + """Complete agent memory with all features.""" + + def __init__( + self, + workspace: Path, + llm_provider=None, + enable_vector_search: bool = False, + vector_persist_dir: str | None = None, + embedding_provider: str = "openai", + embedding_model: str = "text-embedding-3-small", + context_window: int = 200000, + ): + """Initialize complete memory manager. + + Args: + workspace: Workspace directory + llm_provider: LLM provider for summarization + enable_vector_search: Enable vector search + vector_persist_dir: Vector store persistence directory + embedding_provider: Embedding provider type + embedding_model: Embedding model name + context_window: Model context window size + """ + # Base memory + self.base = AgentMemory(workspace) + + # Enhanced memory with vector search + self.enhanced = None + if enable_vector_search and VECTOR_MEMORY_AVAILABLE: + self.enhanced = EnhancedAgentMemory( + workspace=workspace, + enable_vector_search=True, + vector_persist_dir=vector_persist_dir, + embedding_provider=embedding_provider, + embedding_model=embedding_model, + ) + + # Intelligent memory system + self.intelligent = None + if INTELLIGENT_MEMORY_AVAILABLE: + self.intelligent = create_intelligent_memory_system( + llm_provider=llm_provider, + context_window=context_window, + ) + + # Delegate base methods + def get_memory_context(self) -> str: + return self.base.get_memory_context() + + def add_to_memory(self, content: str) -> None: + self.base.add_to_memory(content) + + def add_to_history(self, role: str, content: str) -> None: + self.base.add_to_history(role, content) + + def get_history(self, session_key: str | None = None, max_messages: int = 10): + return self.base.get_history(session_key, max_messages) + + # Delegate enhanced methods + async def add_memory_with_embedding(self, *args, **kwargs): + if self.enhanced: + return await self.enhanced.add_memory_with_embedding(*args, **kwargs) + return None + + async def search_memories(self, *args, **kwargs): + if self.enhanced: + return await self.enhanced.search_memories(*args, **kwargs) + return [] + + # Intelligent methods + async def process_message( + self, + messages: list[dict], + current_tokens: int, + agent_id: str, + user_id: str = "default", + ): + """Process message with intelligent memory management.""" + if not self.intelligent: + return messages, None + + return await self.intelligent.process_message( + messages, current_tokens, agent_id, user_id + ) + + def get_evergreen_context(self, memories: list[dict]) -> str: + """Get evergreen memories for context.""" + if not self.intelligent: + return "" + return self.intelligent.get_evergreen_context(memories) + + def apply_decay(self, memories: list[dict]) -> list[dict]: + """Apply decay to memories.""" + if not self.intelligent: + return memories + return self.intelligent.apply_decay(memories) diff --git a/core/agents/agent/team_agent.py b/core/agents/agent/team_agent.py new file mode 100644 index 0000000..ef4774f --- /dev/null +++ b/core/agents/agent/team_agent.py @@ -0,0 +1,225 @@ +"""Team agent for multi-agent collaboration.""" + +import asyncio +import logging +from typing import Any + +logger = logging.getLogger(__name__) + + +class TeamAgent: + """Team agent that manages multiple agents for collaborative problem solving. + + Supports different strategies: + - parallel: All agents respond in parallel, results are aggregated + - sequential: Agents respond one by one in sequence + - supervisor: A supervisor agent coordinates the work + """ + + def __init__(self, provider: Any, model: str, workspace: Any): + """Initialize the team agent. + + Args: + provider: LLM provider + model: Model name to use + workspace: Workspace path + """ + self.provider = provider + self.model = model + self.workspace = workspace + + async def chat( + self, + message: str, + session_id: str = "default", + supervisor_agent_id: int = 0, + member_agent_ids: list[int] | None = None, + strategy: str = "parallel", + ) -> dict[str, Any]: + """Process a team chat message. + + Args: + message: User message + session_id: Session identifier + supervisor_agent_id: Supervisor agent ID (for future use) + member_agent_ids: List of member agent IDs to involve + strategy: Collaboration strategy (parallel/sequential/supervisor) + + Returns: + Dict with response and subtask_results + """ + member_agent_ids = member_agent_ids or [] + + logger.info(f"Team chat: strategy={strategy}, members={member_agent_ids}, message={message[:50]}...") + + if strategy == "parallel": + return await self._parallel_chat(message, member_agent_ids, session_id) + elif strategy == "sequential": + return await self._sequential_chat(message, member_agent_ids, session_id) + else: + # Default to parallel + return await self._parallel_chat(message, member_agent_ids, session_id) + + async def _parallel_chat( + self, + message: str, + member_agent_ids: list[int], + session_id: str, + ) -> dict[str, Any]: + """Execute parallel chat with multiple agents. + + Args: + message: User message + member_agent_ids: List of member agent IDs + session_id: Session identifier + + Returns: + Aggregated response from all agents + """ + if not member_agent_ids: + return { + "response": "No member agents specified for team chat.", + "subtask_results": [], + } + + # Create tasks for each agent + tasks = [] + for agent_id in member_agent_ids: + task = self._call_agent(agent_id, message, session_id) + tasks.append(task) + + # Execute all tasks in parallel + results = await asyncio.gather(*tasks, return_exceptions=True) + + # Aggregate results + subtask_results = [] + responses = [] + + for i, result in enumerate(results): + agent_id = member_agent_ids[i] + + if isinstance(result, Exception): + error_msg = f"Agent {agent_id} error: {str(result)}" + logger.error(error_msg) + subtask_results.append({ + "agent_id": agent_id, + "status": "error", + "result": str(result), + }) + else: + subtask_results.append({ + "agent_id": agent_id, + "status": "success", + "result": result, + }) + responses.append(result) + + # Combine responses + if responses: + combined_response = self._aggregate_responses(responses) + else: + combined_response = "All agents failed to respond." + + return { + "response": combined_response, + "subtask_results": subtask_results, + } + + async def _sequential_chat( + self, + message: str, + member_agent_ids: list[int], + session_id: str, + ) -> dict[str, Any]: + """Execute sequential chat with multiple agents. + + Args: + message: User message + member_agent_ids: List of member agent IDs + session_id: Session identifier + + Returns: + Aggregated response from all agents + """ + if not member_agent_ids: + return { + "response": "No member agents specified for team chat.", + "subtask_results": [], + } + + subtask_results = [] + responses = [] + + for agent_id in member_agent_ids: + try: + result = await self._call_agent(agent_id, message, session_id) + subtask_results.append({ + "agent_id": agent_id, + "status": "success", + "result": result, + }) + responses.append(result) + except Exception as e: + error_msg = f"Agent {agent_id} error: {str(e)}" + logger.error(error_msg) + subtask_results.append({ + "agent_id": agent_id, + "status": "error", + "result": str(e), + }) + + # Combine responses + if responses: + combined_response = self._aggregate_responses(responses) + else: + combined_response = "All agents failed to respond." + + return { + "response": combined_response, + "subtask_results": subtask_results, + } + + async def _call_agent( + self, + agent_id: int, + message: str, + session_id: str, + ) -> str: + """Call an individual agent. + + For now, this is a placeholder that simulates agent responses. + In a real implementation, this would call the actual agent. + + Args: + agent_id: Agent ID + message: User message + session_id: Session identifier + + Returns: + Agent response + """ + # Simulate agent processing delay + await asyncio.sleep(0.5) + + # Return a simulated response + return f"Agent {agent_id} processed: {message[:30]}..." + + def _aggregate_responses(self, responses: list[str]) -> str: + """Aggregate multiple agent responses into a single response. + + Args: + responses: List of individual agent responses + + Returns: + Combined response + """ + if len(responses) == 1: + return responses[0] + + header = f"【团队协作结果】共 {len(responses)} 位智能体参与了讨论:\n\n" + body = "" + + for i, resp in enumerate(responses, 1): + body += f"--- 智能体 {i} ---\n{resp}\n\n" + + return header + body diff --git a/core/agents/agent/vector_memory.py b/core/agents/agent/vector_memory.py new file mode 100644 index 0000000..9cc5350 --- /dev/null +++ b/core/agents/agent/vector_memory.py @@ -0,0 +1,504 @@ +"""Vector-based memory retrieval with embedding search.""" + +import asyncio +import logging +import os +import hashlib +from pathlib import Path +from datetime import datetime +from typing import Any +from abc import ABC, abstractmethod + +logger = logging.getLogger(__name__) + +# Try to import optional dependencies +try: + import chromadb + from chromadb.config import Settings + CHROMADB_AVAILABLE = True +except ImportError: + CHROMADB_AVAILABLE = False + logger.warning("chromadb not available, vector search disabled") + + +class EmbeddingProvider(ABC): + """Abstract base class for embedding providers.""" + + @abstractmethod + async def embed(self, texts: list[str]) -> list[list[float]]: + """Generate embeddings for texts.""" + pass + + @abstractmethod + async def embed_single(self, text: str) -> list[float]: + """Generate embedding for a single text.""" + pass + + +class OpenAIEmbeddingProvider(EmbeddingProvider): + """OpenAI embedding provider using API.""" + + def __init__( + self, + api_key: str | None = None, + api_base: str | None = None, + model: str = "text-embedding-3-small", + ): + """Initialize OpenAI embedding provider. + + Args: + api_key: OpenAI API key + api_base: Custom API base URL + model: Embedding model name + """ + self.api_key = api_key or os.getenv("OPENAI_API_KEY") + self.api_base = api_base or os.getenv("OPENAI_API_BASE", "https://api.openai.com/v1") + self.model = model + self._client = None + + @property + def client(self): + """Lazy load OpenAI client.""" + if self._client is None: + try: + from openai import AsyncOpenAI + self._client = AsyncOpenAI( + api_key=self.api_key, + base_url=self.api_base, + ) + except ImportError: + raise RuntimeError("openai package required: pip install openai") + return self._client + + async def embed(self, texts: list[str]) -> list[list[float]]: + """Generate embeddings using OpenAI API.""" + if not texts: + return [] + + try: + response = await self.client.embeddings.create( + model=self.model, + input=texts, + ) + return [data.embedding for data in response.data] + except Exception as e: + logger.error(f"OpenAI embedding error: {e}") + raise + + async def embed_single(self, text: str) -> list[float]: + """Generate embedding for a single text.""" + result = await self.embed([text]) + return result[0] + + +class AnthropicEmbeddingProvider(EmbeddingProvider): + """Anthropic embedding provider using API (via Cohere).""" + + def __init__( + self, + api_key: str | None = None, + model: str = "embed-english-v3.0", + ): + """Initialize Anthropic embedding provider. + + Note: Anthropic doesn't have native embeddings, this uses Cohere as alternative. + """ + self.api_key = api_key or os.getenv("ANTHROPIC_API_KEY") + self.cohere_key = os.getenv("COHERE_API_KEY") + self.model = model + self._client = None + + @property + def client(self): + """Lazy load Cohere client.""" + if self._client is None: + try: + import cohere + self._client = cohere.AsyncClient(self.cohere_key) + except ImportError: + raise RuntimeError("cohere package required: pip install cohere") + return self._client + + async def embed(self, texts: list[str]) -> list[list[float]]: + """Generate embeddings using Cohere API.""" + if not texts: + return [] + + try: + response = await self.client.embed( + texts=texts, + model=self.model, + ) + return response.embeddings + except Exception as e: + logger.error(f"Cohere embedding error: {e}") + raise + + async def embed_single(self, text: str) -> list[float]: + """Generate embedding for a single text.""" + result = await self.embed([text]) + return result[0] + + +class LocalEmbeddingProvider(EmbeddingProvider): + """Local embedding provider using sentence-transformers (optional).""" + + def __init__( + self, + model_name: str = "all-MiniLM-L6-v2", + device: str = "cpu", + ): + """Initialize local embedding provider. + + Args: + model_name: Model name for sentence-transformers + device: Device to use (cpu/cuda) + """ + self.model_name = model_name + self.device = device + self._model = None + self._sentence_transformers_available = False + + try: + from sentence_transformers import SentenceTransformer + self._SentenceTransformer = SentenceTransformer + self._sentence_transformers_available = True + except ImportError: + logger.warning("sentence-transformers not available") + + @property + def model(self): + """Lazy load the embedding model.""" + if self._model is None: + if not self._sentence_transformers_available: + raise RuntimeError("sentence-transformers not installed") + logger.info(f"Loading embedding model: {self.model_name}") + self._model = self._SentenceTransformer(self.model_name, device=self.device) + return self._model + + async def embed(self, texts: list[str]) -> list[list[float]]: + """Generate embeddings for texts.""" + if not texts: + return [] + # Run in executor to avoid blocking + loop = asyncio.get_event_loop() + embeddings = await loop.run_in_executor( + None, + lambda: self.model.encode(texts, convert_to_numpy=True) + ) + return embeddings.tolist() + + async def embed_single(self, text: str) -> list[float]: + """Generate embedding for a single text.""" + result = await self.embed([text]) + return result[0] + + +def create_embedding_provider( + provider_type: str = "openai", + **kwargs, +) -> EmbeddingProvider: + """Create an embedding provider. + + Args: + provider_type: Type of provider (openai, anthropic/cohere, local) + **kwargs: Additional arguments for the provider + + Returns: + EmbeddingProvider instance + """ + provider_type = provider_type.lower() + + if provider_type == "openai": + return OpenAIEmbeddingProvider(**kwargs) + elif provider_type in ("anthropic", "cohere"): + return AnthropicEmbeddingProvider(**kwargs) + elif provider_type == "local": + return LocalEmbeddingProvider(**kwargs) + else: + raise ValueError(f"Unknown provider type: {provider_type}") + + +class VectorMemoryStore: + """Vector-based memory store using ChromaDB.""" + + def __init__( + self, + persist_directory: Path | str | None = None, + collection_name: str = "agent_memories", + embedding_provider: EmbeddingProvider | None = None, + ): + """Initialize vector memory store. + + Args: + persist_directory: Directory to persist ChromaDB data + collection_name: Name of the collection + embedding_provider: Custom embedding provider + """ + if not CHROMADB_AVAILABLE: + raise RuntimeError("chromadb not installed: pip install chromadb") + + self.persist_directory = Path(persist_directory) if persist_directory else None + self.collection_name = collection_name + + # Default to OpenAI provider if not specified + self.embedding_provider = embedding_provider or OpenAIEmbeddingProvider() + + # Initialize ChromaDB client + chroma_settings = Settings( + anonymized_telemetry=False, + allow_reset=True, + ) + + if self.persist_directory: + self.persist_directory.mkdir(parents=True, exist_ok=True) + self._client = chromadb.PersistentClient( + path=str(self.persist_directory), + settings=chroma_settings, + ) + else: + self._client = chromadb.InMemoryClient(settings=chroma_settings) + + # Get or create collection + self._collection = self._client.get_or_create_collection( + name=collection_name, + metadata={"description": "Agent memory embeddings"}, + ) + + logger.info(f"Vector memory store initialized: {collection_name}") + + def _generate_id(self, content: str, agent_id: str) -> str: + """Generate unique ID for a memory entry.""" + raw = f"{agent_id}:{content}:{datetime.now().isoformat()}" + return hashlib.md5(raw.encode()).hexdigest() + + async def add_memory( + self, + content: str, + agent_id: str, + user_id: str = "default", + memory_type: str = "conversation", + importance: int = 5, + ) -> str: + """Add a memory to the vector store. + + Args: + content: Memory content + agent_id: Agent ID + user_id: User ID + memory_type: Type of memory + importance: Importance score (1-10) + + Returns: + Memory ID + """ + memory_id = self._generate_id(content, agent_id) + embedding = await self.embedding_provider.embed_single(content) + + self._collection.add( + ids=[memory_id], + embeddings=[embedding], + documents=[content], + metadatas=[{ + "agent_id": agent_id, + "user_id": user_id, + "memory_type": memory_type, + "importance": importance, + "created_at": datetime.now().isoformat(), + }], + ) + + logger.info(f"Added memory: {memory_id}") + return memory_id + + async def search( + self, + query: str, + agent_id: str | None = None, + user_id: str | None = None, + n_results: int = 5, + ) -> list[dict[str, Any]]: + """Search memories by semantic similarity. + + Args: + query: Search query + agent_id: Filter by agent ID + user_id: Filter by user ID + n_results: Number of results to return + + Returns: + List of matching memories with scores + """ + query_embedding = await self.embedding_provider.embed_single(query) + + # Build where filter + where = {} + if agent_id: + where["agent_id"] = agent_id + if user_id: + where["user_id"] = user_id + + results = self._collection.query( + query_embeddings=[query_embedding], + n_results=n_results, + where=where if where else None, + include=["documents", "metadatas", "distances"], + ) + + memories = [] + if results["ids"] and results["ids"][0]: + for i, mem_id in enumerate(results["ids"][0]): + memories.append({ + "id": mem_id, + "content": results["documents"][0][i], + "metadata": results["metadatas"][0][i], + "distance": results["distances"][0][i], + "score": 1.0 - results["distances"][0][i], # Convert distance to similarity + }) + + return memories + + def delete_memory(self, memory_id: str) -> bool: + """Delete a memory by ID. + + Args: + memory_id: Memory ID + + Returns: + True if deleted + """ + try: + self._client.delete_collection(name=self.collection_name) + self._collection = self._client.get_or_create_collection( + name=self.collection_name, + ) + return True + except Exception as e: + logger.error(f"Error deleting memory: {e}") + return False + + def get_count(self) -> int: + """Get total number of memories. + + Returns: + Memory count + """ + return self._collection.count() + + def clear(self, agent_id: str | None = None) -> int: + """Clear memories. + + Args: + agent_id: If provided, only clear memories for this agent + + Returns: + Number of memories cleared + """ + try: + if agent_id: + # Get all IDs for this agent + results = self._collection.get(where={"agent_id": agent_id}) + if results["ids"]: + self._collection.delete(ids=results["ids"]) + return len(results["ids"]) + else: + self._client.delete_collection(name=self.collection_name) + self._collection = self._client.get_or_create_collection( + name=self.collection_name, + ) + return 0 + except Exception as e: + logger.error(f"Error clearing memories: {e}") + return 0 + + +class HybridMemorySearch: + """Hybrid search combining vector and keyword search.""" + + def __init__( + self, + vector_store: VectorMemoryStore, + keyword_weight: float = 0.3, + vector_weight: float = 0.7, + ): + """Initialize hybrid search. + + Args: + vector_store: Vector memory store + keyword_weight: Weight for keyword search (0-1) + vector_weight: Weight for vector search (0-1) + """ + self.vector_store = vector_store + self.keyword_weight = keyword_weight + self.vector_weight = vector_weight + + # Normalize weights + total = keyword_weight + vector_weight + self.keyword_weight /= total + self.vector_weight /= total + + async def search( + self, + query: str, + agent_id: str | None = None, + user_id: str | None = None, + n_results: int = 5, + ) -> list[dict[str, Any]]: + """Search with hybrid approach. + + For now, this is a simplified implementation using only vector search. + Keyword search (BM25) can be added later with rank_bm25 library. + + Args: + query: Search query + agent_id: Filter by agent ID + user_id: Filter by user ID + n_results: Number of results to return + + Returns: + List of matching memories with combined scores + """ + # Use vector search as primary method + results = await self.vector_store.search( + query=query, + agent_id=agent_id, + user_id=user_id, + n_results=n_results, + ) + + # For future BM25 integration, would merge scores here + return results + + +def create_vector_memory_store( + persist_dir: str | None = None, + provider_type: str = "openai", + **provider_kwargs, +) -> VectorMemoryStore | None: + """Create a vector memory store with default settings. + + Args: + persist_dir: Directory to persist data + provider_type: Type of embedding provider (openai, anthropic, local) + **provider_kwargs: Additional arguments for the provider + + Returns: + VectorMemoryStore instance or None if dependencies missing + """ + if not CHROMADB_AVAILABLE: + logger.warning( + "Vector memory requires chromadb. " + "Install with: pip install chromadb" + ) + return None + + try: + provider = create_embedding_provider(provider_type, **provider_kwargs) + except Exception as e: + logger.warning(f"Failed to create embedding provider: {e}") + return None + + return VectorMemoryStore( + persist_directory=persist_dir, + embedding_provider=provider, + ) diff --git a/core/agents/api/__init__.py b/core/agents/api/__init__.py new file mode 100644 index 0000000..f95fbff --- /dev/null +++ b/core/agents/api/__init__.py @@ -0,0 +1,5 @@ +"""X-Agents API Module.""" + +from agents.api.routes import router + +__all__ = ["router"] diff --git a/core/agents/api/routes.py b/core/agents/api/routes.py new file mode 100644 index 0000000..8bf61cd --- /dev/null +++ b/core/agents/api/routes.py @@ -0,0 +1,316 @@ +"""FastAPI routes for agent communication with Go backend.""" + +import json +import logging +import time +from typing import Any, AsyncGenerator + +from fastapi import APIRouter, HTTPException +from fastapi.middleware.cors import CORSMiddleware +from pydantic import BaseModel + +logger = logging.getLogger(__name__) + +router = APIRouter() + + +# Request/Response models - aligned with Go backend +class ChatRequest(BaseModel): + """Chat request from Go backend. + + Fields aligned with server/internal/service/agent_service.go::AgentChatRequest + """ + agent_id: int + message: str + user_id: int = 0 + session_id: str | None = None + model_id: str | None = None + model_name: str | None = None + model_provider: str | None = None + api_key: str | None = None + base_url: str | None = None + use_xbot: bool = False + + +class ChatResponse(BaseModel): + """Chat response to Go backend. + + Fields aligned with server/internal/service/agent_service.go::AgentChatResponse + """ + agent_id: int + response: str + tool_calls: list = [] + tokens_used: int = 0 + duration_ms: int = 0 + session_id: str + + +class TeamChatRequest(BaseModel): + """Team chat request from Go backend. + + Fields aligned with server/internal/service/agent_service.go::TeamChatRequest + """ + supervisor_agent_id: int + member_agent_ids: list[int] + message: str + user_id: int = 0 + session_id: str | None = None + strategy: str = "parallel" + + +class TeamChatResponse(BaseModel): + """Team chat response to Go backend. + + Fields aligned with server/internal/service/agent_service.go::TeamChatResponse + """ + supervisor_agent_id: int + response: str + subtask_results: list = [] + strategy: str = "parallel" + duration_ms: int = 0 + session_id: str + + +class HealthResponse(BaseModel): + """Health check response.""" + status: str + version: str = "0.1.0" + + +# Global agent instance (to be initialized by main) +_agent = None +_team_agent = None + + +def set_agent(agent: Any) -> None: + """Set the global agent instance. + + Args: + agent: Agent loop instance + """ + global _agent + _agent = agent + + +def set_team_agent(team_agent: Any) -> None: + """Set the global team agent instance. + + Args: + team_agent: Team agent instance + """ + global _team_agent + _team_agent = team_agent + + +def add_cors(app) -> None: + """Add CORS middleware to allow Go backend cross-origin requests. + + Args: + app: FastAPI application instance + """ + app.add_middleware( + CORSMiddleware, + allow_origins=["*"], + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], + ) + + +@router.get("/health", response_model=HealthResponse) +async def health_check() -> HealthResponse: + """Health check endpoint.""" + return HealthResponse(status="ok") + + +@router.post("/agent/chat", response_model=ChatResponse) +async def chat(request: ChatRequest) -> ChatResponse: + """Handle chat requests from Go backend. + + Path: POST /agent/chat + Aligned with Go backend server/internal/service/agent_service.go + + Args: + request: Chat request with agent_id, message, user_id, etc. + + Returns: + Chat response with agent_id, response, tool_calls, tokens_used, duration_ms, session_id + + Raises: + HTTPException: If agent is not initialized or processing fails + """ + if _agent is None: + raise HTTPException(status_code=500, detail="Agent not initialized") + + start_time = time.time() + session_id = request.session_id or f"session_{request.agent_id}_{int(start_time)}" + + try: + # Prepare kwargs for agent.chat() + kwargs = { + "message": request.message, + "session_key": session_id, + } + + # Add optional model configuration + if request.model_id: + kwargs["model_id"] = request.model_id + if request.model_name: + kwargs["model_name"] = request.model_name + if request.model_provider: + kwargs["model_provider"] = request.model_provider + if request.api_key: + kwargs["api_key"] = request.api_key + if request.base_url: + kwargs["base_url"] = request.base_url + if request.use_xbot: + kwargs["use_xbot"] = request.use_xbot + + # Process the message + logger.info(f"[chat] kwargs: model_provider={kwargs.get('model_provider')}, model_name={kwargs.get('model_name')}, api_key={'set' if kwargs.get('api_key') else 'not set'}") + result = await _agent.chat(**kwargs) + logger.info(f"[chat] result type={type(result).__name__}, content={str(result)[:100]}") + + # Extract response content + if isinstance(result, dict): + response_text = result.get("response", result.get("content", str(result))) + tool_calls = result.get("tool_calls", []) + tokens_used = result.get("tokens_used", 0) + else: + response_text = str(result) + tool_calls = [] + tokens_used = 0 + + duration_ms = int((time.time() - start_time) * 1000) + + return ChatResponse( + agent_id=request.agent_id, + response=response_text, + tool_calls=tool_calls, + tokens_used=tokens_used, + duration_ms=duration_ms, + session_id=session_id, + ) + except Exception as e: + logger.exception(f"Error processing chat: {e}") + raise HTTPException(status_code=500, detail=str(e)) + + +@router.post("/agent/chat/stream") +async def chat_stream(request: ChatRequest): + """Handle streaming chat requests from Go backend. + + Path: POST /agent/chat/stream + Returns streaming response using SSE format. + + Args: + request: Chat request with agent_id, message, user_id, etc. + + Yields: + Streaming response chunks in SSE format + """ + if _agent is None: + raise HTTPException(status_code=500, detail="Agent not initialized") + + session_id = request.session_id or f"session_{request.agent_id}_{int(time.time())}" + + async def generate() -> AsyncGenerator[str, None]: + """Generate streaming response.""" + try: + # Prepare kwargs for agent.chat() + kwargs = { + "message": request.message, + "session_key": session_id, + } + + if request.model_id: + kwargs["model_id"] = request.model_id + if request.model_name: + kwargs["model_name"] = request.model_name + if request.model_provider: + kwargs["model_provider"] = request.model_provider + if request.api_key: + kwargs["api_key"] = request.api_key + if request.base_url: + kwargs["base_url"] = request.base_url + if request.use_xbot: + kwargs["use_xbot"] = request.use_xbot + + # Process with streaming + async for chunk in _agent.chat_stream(**kwargs): + # SSE format: "data: \n\n" + yield f"data: {json.dumps(chunk)}\n\n" + + # Send final message + yield f"data: {json.dumps({'done': True, 'session_id': session_id})}\n\n" + + except Exception as e: + logger.exception(f"Error in streaming chat: {e}") + yield f"data: {json.dumps({'error': str(e)})}\n\n" + + from fastapi.responses import StreamingResponse + + return StreamingResponse( + generate(), + media_type="text/event-stream", + headers={ + "Cache-Control": "no-cache", + "Connection": "keep-alive", + "X-Accel-Buffering": "no-cache", # Disable nginx buffering + }, + ) + + +@router.post("/agent/team/chat", response_model=TeamChatResponse) +async def team_chat(request: TeamChatRequest) -> TeamChatResponse: + """Handle team chat requests from Go backend. + + Path: POST /agent/team/chat + Aligned with Go backend server/internal/service/agent_service.go::TeamChat + + Args: + request: Team chat request with supervisor_agent_id, member_agent_ids, message, etc. + + Returns: + Team chat response with supervisor_agent_id, response, subtask_results, strategy, duration_ms, session_id + + Raises: + HTTPException: If team agent is not initialized or processing fails + """ + if _team_agent is None: + raise HTTPException(status_code=500, detail="Team agent not initialized") + + start_time = time.time() + session_id = request.session_id or f"team_session_{request.supervisor_agent_id}_{int(start_time)}" + + try: + # Process the team chat message + result = await _team_agent.chat( + message=request.message, + session_id=session_id, + supervisor_agent_id=request.supervisor_agent_id, + member_agent_ids=request.member_agent_ids, + strategy=request.strategy, + ) + + # Extract response content + if isinstance(result, dict): + response_text = result.get("response", str(result)) + subtask_results = result.get("subtask_results", []) + else: + response_text = str(result) + subtask_results = [] + + duration_ms = int((time.time() - start_time) * 1000) + + return TeamChatResponse( + supervisor_agent_id=request.supervisor_agent_id, + response=response_text, + subtask_results=subtask_results, + strategy=request.strategy, + duration_ms=duration_ms, + session_id=session_id, + ) + except Exception as e: + logger.exception(f"Error processing team chat: {e}") + raise HTTPException(status_code=500, detail=str(e)) diff --git a/core/agents/config.py b/core/agents/config.py new file mode 100644 index 0000000..d4bf9ef --- /dev/null +++ b/core/agents/config.py @@ -0,0 +1,56 @@ +"""Configuration for X-Agents.""" + +import os +from pathlib import Path +from typing import Any + +# 尝试加载 .env 文件 +try: + from dotenv import load_dotenv + # 查找 .env 文件：从当前目录向上查找 + env_paths = [ + Path(__file__).parent.parent.parent / ".env", # X-Agents/.env + Path(__file__).parent.parent / ".env", # core/.env + Path(__file__).parent / ".env", # agents/.env + ] + for env_path in env_paths: + if env_path.exists(): + load_dotenv(env_path) + break +except ImportError: + pass # python-dotenv 未安装时跳过 + + +class Config: + """X-Agents configuration.""" + + # API settings + API_HOST: str = os.getenv("PYTHON_HOST", os.getenv("API_HOST", "0.0.0.0")) + API_PORT: int = int(os.getenv("PYTHON_PORT", os.getenv("API_PORT", "8001"))) + + # LLM settings + LLM_PROVIDER: str = os.getenv("PYTHON_LLM_PROVIDER", os.getenv("LLM_PROVIDER", "openai")) + LLM_MODEL: str = os.getenv("PYTHON_LLM_MODEL", os.getenv("LLM_MODEL", "gpt-4o")) + LLM_API_KEY: str = os.getenv("PYTHON_LLM_API_KEY", os.getenv("LLM_API_KEY", "")) + LLM_BASE_URL: str | None = os.getenv("PYTHON_LLM_BASE_URL", os.getenv("LLM_BASE_URL", None)) + + # Workspace + WORKSPACE: Path = Path(os.getenv("PYTHON_WORKSPACE", os.getenv("WORKSPACE", "./workspace"))) + + # Agent settings + MAX_ITERATIONS: int = int(os.getenv("PYTHON_MAX_ITERATIONS", os.getenv("MAX_ITERATIONS", "10"))) + TEMPERATURE: float = float(os.getenv("PYTHON_TEMPERATURE", os.getenv("TEMPERATURE", "0.7"))) + + def __init__(self, **kwargs: Any): + """Initialize config with overrides. + + Args: + **kwargs: Configuration overrides + """ + for key, value in kwargs.items(): + if hasattr(self, key): + setattr(self, key, value) + + +# Default config instance +config = Config() diff --git a/core/agents/llm.py b/core/agents/llm.py new file mode 100644 index 0000000..aefa3e6 --- /dev/null +++ b/core/agents/llm.py @@ -0,0 +1,482 @@ +"""LLM Provider base classes and implementations.""" + +import asyncio +import json +import logging +from abc import ABC, abstractmethod +from dataclasses import dataclass, field +from typing import Any, AsyncGenerator + +logger = logging.getLogger(__name__) + + +@dataclass +class ToolCallRequest: + """A tool call request from the LLM.""" + id: str + name: str + arguments: dict[str, Any] + + def to_dict(self) -> dict[str, Any]: + """Serialize to dict.""" + return { + "id": self.id, + "type": "function", + "function": { + "name": self.name, + "arguments": json.dumps(self.arguments, ensure_ascii=False), + }, + } + + +@dataclass +class LLMResponse: + """Response from an LLM provider.""" + content: str | None + tool_calls: list[ToolCallRequest] = field(default_factory=list) + finish_reason: str = "stop" + usage: dict[str, int] = field(default_factory=dict) + reasoning_content: str | None = None # For reasoning models + + @property + def has_tool_calls(self) -> bool: + """Check if response contains tool calls.""" + return len(self.tool_calls) > 0 + + +@dataclass +class GenerationSettings: + """Default generation parameters for LLM calls.""" + temperature: float = 0.7 + max_tokens: int = 4096 + + +class LLMProvider(ABC): + """Abstract base class for LLM providers.""" + + _CHAT_RETRY_DELAYS = (1, 2, 4) + _TRANSIENT_ERROR_MARKERS = ( + "429", "rate limit", "500", "502", "503", "504", + "overloaded", "timeout", "timed out", "connection", + "server error", "temporarily unavailable", + ) + + def __init__( + self, + api_key: str | None = None, + api_base: str | None = None, + ): + self.api_key = api_key + self.api_base = api_base + self.generation = GenerationSettings() + + @staticmethod + def _sanitize_messages(messages: list[dict[str, Any]]) -> list[dict[str, Any]]: + """Sanitize messages to remove empty content that causes provider errors.""" + result = [] + for msg in messages: + content = msg.get("content") + if isinstance(content, str) and not content: + clean = dict(msg) + if msg.get("role") == "assistant" and msg.get("tool_calls"): + clean["content"] = None + else: + clean["content"] = "(empty)" + result.append(clean) + continue + result.append(msg) + return result + + @abstractmethod + async def chat( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int = 4096, + temperature: float = 0.7, + stream: bool = False, + ) -> LLMResponse | AsyncGenerator[str, None]: + """Send a chat completion request.""" + pass + + @classmethod + def _is_transient_error(cls, content: str | None) -> bool: + err = (content or "").lower() + return any(marker in err for marker in cls._TRANSIENT_ERROR_MARKERS) + + async def chat_with_retry( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int | None = None, + temperature: float | None = None, + ) -> LLMResponse: + """Call chat() with retry on transient provider failures.""" + max_tokens = max_tokens or self.generation.max_tokens + temperature = temperature or self.generation.temperature + + messages = self._sanitize_messages(messages) + + for attempt, delay in enumerate(self._CHAT_RETRY_DELAYS, start=1): + try: + response = await self.chat( + messages=messages, + tools=tools, + model=model, + max_tokens=max_tokens, + temperature=temperature, + ) + except asyncio.CancelledError: + raise + except Exception as exc: + response = LLMResponse( + content=f"Error calling LLM: {exc}", + finish_reason="error", + ) + + if response.finish_reason != "error": + return response + if not self._is_transient_error(response.content): + return response + + logger.warning( + "LLM transient error (attempt {}/{}), retrying in {}s", + attempt, + len(self._CHAT_RETRY_DELAYS), + delay, + ) + await asyncio.sleep(delay) + + # Last attempt + try: + return await self.chat( + messages=messages, + tools=tools, + model=model, + max_tokens=max_tokens, + temperature=temperature, + ) + except asyncio.CancelledError: + raise + except Exception as exc: + return LLMResponse( + content=f"Error calling LLM: {exc}", + finish_reason="error", + ) + + @abstractmethod + def get_default_model(self) -> str: + """Get the default model for this provider.""" + pass + + +# OpenAI Provider +class OpenAIProvider(LLMProvider): + """OpenAI LLM provider.""" + + def __init__( + self, + api_key: str | None = None, + api_base: str | None = None, + ): + super().__init__(api_key, api_base) + self._client = None + + @property + def client(self): + """Lazy load OpenAI client.""" + if self._client is None: + try: + from openai import AsyncOpenAI + self._client = AsyncOpenAI( + api_key=self.api_key, + base_url=self.api_base, + ) + except ImportError: + raise ImportError("openai package required: pip install openai") + return self._client + + async def chat( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int = 4096, + temperature: float = 0.7, + stream: bool = False, + ) -> LLMResponse: + model = model or self.get_default_model() + + params = { + "model": model, + "messages": messages, + "max_tokens": max_tokens, + "temperature": temperature, + } + + if tools: + params["tools"] = tools + params["tool_choice"] = "auto" + + try: + response = await self.client.chat.completions.create(**params) + + choice = response.choices[0] + msg = choice.message + + tool_calls = [] + if msg.tool_calls: + for tc in msg.tool_calls: + args = tc.function.arguments + if isinstance(args, str): + args = json.loads(args) + tool_calls.append(ToolCallRequest( + id=tc.id, + name=tc.function.name, + arguments=args, + )) + + return LLMResponse( + content=msg.content, + tool_calls=tool_calls, + finish_reason=choice.finish_reason, + usage={ + "prompt_tokens": response.usage.prompt_tokens if response.usage else 0, + "completion_tokens": response.usage.completion_tokens if response.usage else 0, + }, + ) + except Exception as exc: + logger.error(f"OpenAI API error: {exc}") + return LLMResponse( + content=f"Error: {exc}", + finish_reason="error", + ) + + async def chat_stream( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int = 4096, + temperature: float = 0.7, + ) -> AsyncGenerator[str, None]: + """Stream chat completions.""" + model = model or self.get_default_model() + + params = { + "model": model, + "messages": messages, + "max_tokens": max_tokens, + "temperature": temperature, + "stream": True, + } + + if tools: + params["tools"] = tools + + try: + response = await self.client.chat.completions.create(**params) + async for chunk in response: + if chunk.choices and chunk.choices[0].delta.content: + yield chunk.choices[0].delta.content + except Exception as exc: + yield f"Error: {exc}" + + def get_default_model(self) -> str: + return "gpt-4o" + + +# Anthropic Provider +class AnthropicProvider(LLMProvider): + """Anthropic Claude LLM provider.""" + + def __init__( + self, + api_key: str | None = None, + api_base: str | None = None, + ): + super().__init__(api_key, api_base) + self._client = None + + @property + def client(self): + """Lazy load Anthropic client.""" + if self._client is None: + try: + from anthropic import AsyncAnthropic + self._client = AsyncAnthropic( + api_key=self.api_key, + base_url=self.api_base, + ) + except ImportError: + raise ImportError("anthropic package required: pip install anthropic") + return self._client + + def _convert_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]: + """Convert messages to Anthropic format.""" + converted = [] + for msg in messages: + role = msg.get("role") + if role == "system": + # Anthropic puts system in first user message + content = msg.get("content", "") + if converted and converted[0].get("role") == "user": + converted[0]["content"] = f"{content}\n\n{converted[0].content}" + else: + converted.append({"role": "user", "content": f"{content}"}) + else: + # Handle tool results + if role == "tool": + converted.append({ + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": msg.get("tool_call_id"), + "content": msg.get("content", ""), + } + ], + }) + else: + converted.append(msg) + return converted + + def _convert_tools(self, tools: list[dict[str, Any]]) -> list[dict[str, Any]]: + """Convert OpenAI-style tools to Anthropic format.""" + anthropic_tools = [] + for tool in tools: + func = tool.get("function", {}) + anthropic_tools.append({ + "name": func.get("name"), + "description": func.get("description"), + "input_schema": func.get("parameters", {}), + }) + return anthropic_tools + + async def chat( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int = 4096, + temperature: float = 0.7, + stream: bool = False, + ) -> LLMResponse: + model = model or self.get_default_model() + + params = { + "model": model, + "max_tokens": max_tokens, + "temperature": temperature, + "messages": self._convert_messages(messages), + } + + if tools: + params["tools"] = self._convert_tools(tools) + + try: + response = await self.client.messages.create(**params) + + tool_calls = [] + for tc in response.tool_calls: + args = tc.input + if isinstance(args, str): + args = json.loads(args) + tool_calls.append(ToolCallRequest( + id=tc.id, + name=tc.name, + arguments=args, + )) + + # Get content text + content_text = "" + thinking = None + if response.content: + for block in response.content: + if block.type == "text": + content_text = block.text + elif block.type == "thinking": + thinking = block.thinking + + return LLMResponse( + content=content_text, + tool_calls=tool_calls, + finish_reason="stop" if not tool_calls else "tool_use", + reasoning_content=thinking, + usage={ + "input_tokens": response.usage.input_tokens, + "output_tokens": response.usage.output_tokens, + }, + ) + except Exception as exc: + logger.error(f"Anthropic API error: {exc}") + return LLMResponse( + content=f"Error: {exc}", + finish_reason="error", + ) + + async def chat_stream( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int = 4096, + temperature: float = 0.7, + ) -> AsyncGenerator[str, None]: + """Stream chat completions.""" + model = model or self.get_default_model() + + params = { + "model": model, + "max_tokens": max_tokens, + "temperature": temperature, + "messages": self._convert_messages(messages), + "stream": True, + } + + if tools: + params["tools"] = self._convert_tools(tools) + + try: + async with self.client.messages.stream(**params) as stream: + async for text in stream.text_stream: + yield text + except Exception as exc: + yield f"Error: {exc}" + + def get_default_model(self) -> str: + return "claude-sonnet-4-20250514" + + +# Provider factory +class ProviderFactory: + """Factory for creating LLM providers.""" + + _PROVIDERS = { + "openai": OpenAIProvider, + "anthropic": AnthropicProvider, + } + + @classmethod + def create( + cls, + provider: str, + api_key: str | None = None, + api_base: str | None = None, + ) -> LLMProvider: + """Create an LLM provider instance. + + Args: + provider: Provider name (openai, anthropic) + api_key: API key + api_base: Optional base URL for API + + Returns: + LLM provider instance + """ + provider_cls = cls._PROVIDERS.get(provider.lower()) + if not provider_cls: + raise ValueError(f"Unknown provider: {provider}. Available: {list(cls._PROVIDERS.keys())}") + return provider_cls(api_key=api_key, api_base=api_base) diff --git a/core/agents/main.py b/core/agents/main.py new file mode 100644 index 0000000..83840e0 --- /dev/null +++ b/core/agents/main.py @@ -0,0 +1,165 @@ +"""Main entry point for X-Agents agent service.""" + +import logging +import asyncio +import sys +from pathlib import Path + +# Add project root to path (parent of core directory) +project_root = Path(__file__).parent.parent.parent +core_dir = project_root / "core" +sys.path.insert(0, str(project_root)) # for X-Agents root +sys.path.insert(0, str(core_dir)) # for core +sys.path.insert(0, str(core_dir / "nanobot")) # for nanobot + +from fastapi import FastAPI +import uvicorn + +from agents.config import Config +from agents.api.routes import router, set_agent, set_team_agent, add_cors +from agents.agent.loop import AgentLoop +from agents.agent.team_agent import TeamAgent +from agents.llm import ProviderFactory +from agents.tools import create_default_registry + +# Configure logging +logging.basicConfig( + level=logging.INFO, + format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", +) +logger = logging.getLogger(__name__) + + +class SimpleProvider: + """Simple LLM provider placeholder for testing without API keys.""" + + def __init__(self, api_key: str = "", base_url: str | None = None): + self.api_key = api_key + self.base_url = base_url + + async def chat(self, messages: list[dict], model: str, **kwargs) -> dict: + """Simulate LLM chat response. + + Args: + messages: Message list + model: Model name + + Returns: + Simulated response + """ + from agents.llm import LLMResponse + + user_msg = "" + for msg in reversed(messages): + if msg.get("role") == "user": + user_msg = msg.get("content", "") + break + + return LLMResponse( + content=f"I received your message: {user_msg[:50]}... (LLM integration pending)", + tool_calls=[], + finish_reason="stop", + ) + + async def chat_with_retry(self, *args, **kwargs): + return await self.chat(*args, **kwargs) + + def get_default_model(self) -> str: + return "simple" + + +def create_app(config: Config | None = None) -> FastAPI: + """Create and configure the FastAPI application. + + Args: + config: Configuration instance + + Returns: + Configured FastAPI app + """ + config = config or Config() + + app = FastAPI( + title="X-Agents API", + description="Agent API for X-Agents platform", + version="0.1.0", + ) + + # Include routers with /api/v1 prefix (aligned with Go backend paths: /api/agent/chat, /api/agent/chat/stream) + app.include_router(router, prefix="/api/v1") + + # Add CORS middleware to allow Go backend cross-origin requests + add_cors(app) + + # Initialize LLM provider + if config.LLM_API_KEY: + try: + provider = ProviderFactory.create( + provider=config.LLM_PROVIDER, + api_key=config.LLM_API_KEY, + api_base=config.LLM_BASE_URL, + ) + logger.info(f"Using {config.LLM_PROVIDER} provider with model {config.LLM_MODEL}") + except ImportError as e: + logger.warning(f"Failed to import provider package: {e}, using placeholder") + provider = SimpleProvider(api_key=config.LLM_API_KEY) + else: + logger.warning("No LLM_API_KEY provided, using placeholder provider") + provider = SimpleProvider() + + # Create tool registry + tools = create_default_registry() + + # Initialize agent + agent = AgentLoop( + provider=provider, + model=config.LLM_MODEL, + workspace=config.WORKSPACE, + max_iterations=config.MAX_ITERATIONS, + tools=tools, + ) + + set_agent(agent) + + # Initialize team agent for multi-agent collaboration + team_agent = TeamAgent( + provider=provider, + model=config.LLM_MODEL, + workspace=config.WORKSPACE, + ) + set_team_agent(team_agent) + + @app.on_event("startup") + async def startup_event(): + logger.info("X-Agents starting up...") + logger.info(f"Model: {config.LLM_MODEL}") + logger.info(f"Provider: {config.LLM_PROVIDER}") + logger.info(f"Workspace: {config.WORKSPACE}") + logger.info(f"Tools: {tools.tool_names}") + + @app.on_event("shutdown") + async def shutdown_event(): + logger.info("X-Agents shutting down...") + + return app + + +def main(): + """Run the agent service.""" + config = Config() + + # Ensure workspace exists + config.WORKSPACE.mkdir(exist_ok=True) + + app = create_app(config) + + uvicorn.run( + app, + host=config.API_HOST, + port=config.API_PORT, + log_level="info", + ) + + +if __name__ == "__main__": + main() diff --git a/core/agents/providers/__init__.py b/core/agents/providers/__init__.py new file mode 100644 index 0000000..1e013dd --- /dev/null +++ b/core/agents/providers/__init__.py @@ -0,0 +1,7 @@ +"""LLM Provider abstraction for X-Agents.""" + +from agents.providers.base import LLMProvider, LLMResponse, ToolCallRequest +from agents.providers.openai_provider import OpenAIProvider +from agents.providers.anthropic_provider import AnthropicProvider + +__all__ = ["LLMProvider", "LLMResponse", "ToolCallRequest", "OpenAIProvider", "AnthropicProvider"] diff --git a/core/agents/providers/anthropic_provider.py b/core/agents/providers/anthropic_provider.py new file mode 100644 index 0000000..1da5d38 --- /dev/null +++ b/core/agents/providers/anthropic_provider.py @@ -0,0 +1,241 @@ +"""Anthropic LLM provider implementation.""" + +import json +import secrets +import string +from typing import Any + +import aiohttp +from loguru import logger + +from agents.providers.base import LLMProvider, LLMResponse, ToolCallRequest + +_ALNUM = string.ascii_letters + string.digits + + +def _short_tool_id() -> str: + """Generate a 9-char alphanumeric ID for tool calls.""" + return "".join(secrets.choice(_ALNUM) for _ in range(9)) + + +class AnthropicProvider(LLMProvider): + """Anthropic LLM provider using Claude API.""" + + def __init__( + self, + api_key: str | None = None, + api_base: str | None = None, + default_model: str = "claude-sonnet-4-20250514", + ): + super().__init__(api_key, api_base) + self.default_model = default_model + self._session: aiohttp.ClientSession | None = None + + async def _get_session(self) -> aiohttp.ClientSession: + """Get or create aiohttp session.""" + if self._session is None or self._session.closed: + self._session = aiohttp.ClientSession() + return self._session + + async def close(self): + """Close the HTTP session.""" + if self._session and not self._session.closed: + await self._session.close() + + def _convert_messages_to_anthropic(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]: + """Convert messages to Anthropic API format.""" + converted = [] + for msg in messages: + role = msg.get("role") + content = msg.get("content") + + # Handle tool calls in assistant messages + if role == "assistant" and msg.get("tool_calls"): + # Anthropic doesn't support tool_calls in the same way, convert to text + tool_calls_text = "\n".join([ + f"Tool call: {tc.get('name')}({json.dumps(tc.get('arguments', {}))})" + for tc in msg["tool_calls"] + ]) + if content: + content = f"{content}\n\n{tool_calls_text}" + else: + content = tool_calls_text + + # Handle tool results + if role == "tool": + # Convert tool result to Anthropic format + tool_use_id = msg.get("tool_call_id", _short_tool_id()) + converted.append({ + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": content or "(empty)", + }) + continue + + # Skip system messages - they'll be handled separately + if role == "system": + continue + + # Convert content to Anthropic format + if isinstance(content, str): + converted.append({ + "role": role, + "content": content, + }) + elif isinstance(content, list): + # Handle list content + text_parts = [] + for item in content: + if isinstance(item, dict): + if item.get("type") == "text": + text_parts.append(item.get("text", "")) + elif item.get("type") == "tool_use": + # This shouldn't happen in input, but handle it + text_parts.append(f"[tool_use: {item.get('name')}]") + elif item.get("type") == "tool_result": + text_parts.append(item.get("content", "")) + converted.append({ + "role": role, + "content": "\n".join(text_parts), + }) + else: + converted.append({ + "role": role, + "content": str(content) if content else "(empty)", + }) + + return converted + + def _get_system_message(self, messages: list[dict[str, Any]]) -> str | None: + """Extract system message from messages.""" + for msg in messages: + if msg.get("role") == "system": + return msg.get("content") + return None + + async def chat( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int = 4096, + temperature: float = 0.7, + ) -> LLMResponse: + """Send a chat completion request to Anthropic API.""" + model = model or self.default_model + api_base = self.api_base or "https://api.anthropic.com" + url = f"{api_base}/v1/messages" + + headers = { + "Content-Type": "application/json", + "anthropic-version": "2023-06-01", + } + if self.api_key: + headers["x-api-key"] = self.api_key + + # Get system message and convert other messages + system = self._get_system_message(messages) + anthropic_messages = self._convert_messages_to_anthropic(messages) + + payload: dict[str, Any] = { + "model": model, + "messages": anthropic_messages, + "max_tokens": max_tokens, + "temperature": temperature, + } + + if system: + payload["system"] = system + + # Convert tools to Anthropic format if provided + if tools: + anthropic_tools = self._convert_tools(tools) + payload["tools"] = anthropic_tools + + try: + session = await self._get_session() + async with session.post(url, json=payload, headers=headers) as resp: + if resp.status != 200: + error_text = await resp.text() + try: + error_json = json.loads(error_text) + error_msg = error_json.get("error", {}).get("message", error_text) + except json.JSONDecodeError: + error_msg = error_text + return LLMResponse( + content=f"Anthropic API error (status {resp.status}): {error_msg}", + finish_reason="error", + ) + + data = await resp.json() + return self._parse_response(data, tools is not None) + + except aiohttp.ClientError as e: + return LLMResponse( + content=f"Anthropic API connection error: {str(e)}", + finish_reason="error", + ) + except Exception as e: + return LLMResponse( + content=f"Error calling Anthropic: {str(e)}", + finish_reason="error", + ) + + def _convert_tools(self, tools: list[dict[str, Any]]) -> list[dict[str, Any]]: + """Convert OpenAI-style tools to Anthropic format.""" + anthropic_tools = [] + for tool in tools: + func = tool.get("function", {}) + anthropic_tools.append({ + "name": func.get("name", ""), + "description": func.get("description", ""), + "input_schema": func.get("parameters", {"type": "object", "properties": {}}), + }) + return anthropic_tools + + def _parse_response(self, data: dict[str, Any], has_tools: bool = False) -> LLMResponse: + """Parse Anthropic API response into our standard format.""" + content = data.get("content", []) + + # Extract text content + text_content = "" + tool_calls = [] + for block in content: + if block.get("type") == "text": + text_content += block.get("text", "") + elif block.get("type") == "tool_use" and has_tools: + # Convert Anthropic tool_use to our format + args = block.get("input", {}) + tool_calls.append(ToolCallRequest( + id=block.get("id", _short_tool_id()), + name=block.get("name", ""), + arguments=args, + )) + + # Determine finish reason + stop_reason = data.get("stop_reason", "end_turn") + if stop_reason == "tool_use": + finish_reason = "tool_calls" + elif stop_reason == "max_tokens": + finish_reason = "length" + else: + finish_reason = "stop" + + # Parse usage + usage = data.get("usage", {}) + usage_dict = { + "prompt_tokens": usage.get("input_tokens", 0), + "completion_tokens": usage.get("output_tokens", 0), + "total_tokens": usage.get("input_tokens", 0) + usage.get("output_tokens", 0), + } + + return LLMResponse( + content=text_content if text_content else None, + tool_calls=tool_calls, + finish_reason=finish_reason, + usage=usage_dict, + ) + + def get_default_model(self) -> str: + """Get the default model.""" + return self.default_model diff --git a/core/agents/providers/base.py b/core/agents/providers/base.py new file mode 100644 index 0000000..b6fdbfd --- /dev/null +++ b/core/agents/providers/base.py @@ -0,0 +1,225 @@ +"""Base LLM provider interface.""" + +import asyncio +import json +from abc import ABC, abstractmethod +from dataclasses import dataclass, field +from typing import Any + +from loguru import logger + + +@dataclass +class ToolCallRequest: + """A tool call request from the LLM.""" + id: str + name: str + arguments: dict[str, Any] + provider_specific_fields: dict[str, Any] | None = None + + def to_openai_tool_call(self) -> dict[str, Any]: + """Serialize to an OpenAI-style tool_call payload.""" + tool_call = { + "id": self.id, + "type": "function", + "function": { + "name": self.name, + "arguments": json.dumps(self.arguments, ensure_ascii=False), + }, + } + if self.provider_specific_fields: + tool_call["provider_specific_fields"] = self.provider_specific_fields + return tool_call + + +@dataclass +class LLMResponse: + """Response from an LLM provider.""" + content: str | None + tool_calls: list[ToolCallRequest] = field(default_factory=list) + finish_reason: str = "stop" + usage: dict[str, int] = field(default_factory=dict) + reasoning_content: str | None = None # For reasoning models + + @property + def has_tool_calls(self) -> bool: + """Check if response contains tool calls.""" + return len(self.tool_calls) > 0 + + +@dataclass(frozen=True) +class GenerationSettings: + """Default generation parameters for LLM calls.""" + + temperature: float = 0.7 + max_tokens: int = 4096 + + +class LLMProvider(ABC): + """ + Abstract base class for LLM providers. + + Implementations should handle the specifics of each provider's API + while maintaining a consistent interface. + """ + + _CHAT_RETRY_DELAYS = (1, 2, 4) + _TRANSIENT_ERROR_MARKERS = ( + "429", + "rate limit", + "500", + "502", + "503", + "504", + "overloaded", + "timeout", + "timed out", + "connection", + "server error", + "temporarily unavailable", + ) + + _SENTINEL = object() + + def __init__(self, api_key: str | None = None, api_base: str | None = None): + self.api_key = api_key + self.api_base = api_base + self.generation: GenerationSettings = GenerationSettings() + + @staticmethod + def _sanitize_empty_content(messages: list[dict[str, Any]]) -> list[dict[str, Any]]: + """Replace empty text content that causes provider 400 errors.""" + result: list[dict[str, Any]] = [] + for msg in messages: + content = msg.get("content") + + if isinstance(content, str) and not content: + clean = dict(msg) + clean["content"] = None if (msg.get("role") == "assistant" and msg.get("tool_calls")) else "(empty)" + result.append(clean) + continue + + if isinstance(content, list): + filtered = [ + item for item in content + if not ( + isinstance(item, dict) + and item.get("type") in ("text", "input_text", "output_text") + and not item.get("text") + ) + ] + if len(filtered) != len(content): + clean = dict(msg) + if filtered: + clean["content"] = filtered + elif msg.get("role") == "assistant" and msg.get("tool_calls"): + clean["content"] = None + else: + clean["content"] = "(empty)" + result.append(clean) + continue + + if isinstance(content, dict): + clean = dict(msg) + clean["content"] = [content] + result.append(clean) + continue + + result.append(msg) + return result + + @abstractmethod + async def chat( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int = 4096, + temperature: float = 0.7, + ) -> LLMResponse: + """ + Send a chat completion request. + + Args: + messages: List of message dicts with 'role' and 'content'. + tools: Optional list of tool definitions. + model: Model identifier (provider-specific). + max_tokens: Maximum tokens in response. + temperature: Sampling temperature. + + Returns: + LLMResponse with content and/or tool calls. + """ + pass + + @classmethod + def _is_transient_error(cls, content: str | None) -> bool: + err = (content or "").lower() + return any(marker in err for marker in cls._TRANSIENT_ERROR_MARKERS) + + async def chat_with_retry( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: object = _SENTINEL, + temperature: object = _SENTINEL, + ) -> LLMResponse: + """Call chat() with retry on transient provider failures.""" + if max_tokens is self._SENTINEL: + max_tokens = self.generation.max_tokens + if temperature is self._SENTINEL: + temperature = self.generation.temperature + + for attempt, delay in enumerate(self._CHAT_RETRY_DELAYS, start=1): + try: + response = await self.chat( + messages=messages, + tools=tools, + model=model, + max_tokens=max_tokens, + temperature=temperature, + ) + except asyncio.CancelledError: + raise + except Exception as exc: + response = LLMResponse( + content=f"Error calling LLM: {exc}", + finish_reason="error", + ) + + if response.finish_reason != "error": + return response + if not self._is_transient_error(response.content): + return response + + err = (response.content or "").lower() + logger.warning( + "LLM transient error (attempt {}/{}), retrying in {}s: {}", + attempt, + len(self._CHAT_RETRY_DELAYS), + delay, + err[:120], + ) + await asyncio.sleep(delay) + + try: + return await self.chat( + messages=messages, + tools=tools, + model=model, + max_tokens=max_tokens, + temperature=temperature, + ) + except asyncio.CancelledError: + raise + except Exception as exc: + return LLMResponse( + content=f"Error calling LLM: {exc}", + finish_reason="error", + ) + + @abstractmethod + def get_default_model(self) -> str: + """Get the default model for this provider.""" + pass diff --git a/core/agents/providers/openai_provider.py b/core/agents/providers/openai_provider.py new file mode 100644 index 0000000..9761c58 --- /dev/null +++ b/core/agents/providers/openai_provider.py @@ -0,0 +1,150 @@ +"""OpenAI LLM provider implementation.""" + +import json +import secrets +import string +from typing import Any + +import aiohttp +from loguru import logger + +from agents.providers.base import LLMProvider, LLMResponse, ToolCallRequest + +_ALNUM = string.ascii_letters + string.digits + + +def _short_tool_id() -> str: + """Generate a 9-char alphanumeric ID for tool calls.""" + return "".join(secrets.choice(_ALNUM) for _ in range(9)) + + +class OpenAIProvider(LLMProvider): + """OpenAI LLM provider using OpenAI API.""" + + def __init__( + self, + api_key: str | None = None, + api_base: str | None = None, + default_model: str = "gpt-4o", + ): + super().__init__(api_key, api_base) + self.default_model = default_model + self._session: aiohttp.ClientSession | None = None + + async def _get_session(self) -> aiohttp.ClientSession: + """Get or create aiohttp session.""" + if self._session is None or self._session.closed: + self._session = aiohttp.ClientSession() + return self._session + + async def close(self): + """Close the HTTP session.""" + if self._session and not self._session.closed: + await self._session.close() + + async def chat( + self, + messages: list[dict[str, Any]], + tools: list[dict[str, Any]] | None = None, + model: str | None = None, + max_tokens: int = 4096, + temperature: float = 0.7, + ) -> LLMResponse: + """Send a chat completion request to OpenAI API.""" + model = model or self.default_model + api_base = self.api_base or "https://api.openai.com/v1" + url = f"{api_base}/chat/completions" + + headers = { + "Content-Type": "application/json", + } + if self.api_key: + headers["Authorization"] = f"Bearer {self.api_key}" + + # Sanitize messages + messages = self._sanitize_empty_content(messages) + + payload: dict[str, Any] = { + "model": model, + "messages": messages, + "max_tokens": max_tokens, + "temperature": temperature, + } + + if tools: + payload["tools"] = tools + payload["tool_choice"] = "auto" + + try: + session = await self._get_session() + async with session.post(url, json=payload, headers=headers) as resp: + if resp.status != 200: + error_text = await resp.text() + return LLMResponse( + content=f"OpenAI API error (status {resp.status}): {error_text}", + finish_reason="error", + ) + + data = await resp.json() + return self._parse_response(data) + + except aiohttp.ClientError as e: + return LLMResponse( + content=f"OpenAI API connection error: {str(e)}", + finish_reason="error", + ) + except Exception as e: + return LLMResponse( + content=f"Error calling OpenAI: {str(e)}", + finish_reason="error", + ) + + def _parse_response(self, data: dict[str, Any]) -> LLMResponse: + """Parse OpenAI API response into our standard format.""" + choices = data.get("choices", []) + if not choices: + return LLMResponse(content="", finish_reason="stop") + + choice = choices[0] + message = choice.get("message", {}) + content = message.get("content") + finish_reason = choice.get("finish_reason", "stop") + + # Parse tool calls + tool_calls = [] + raw_tool_calls = message.get("tool_calls", []) + for tc in raw_tool_calls: + func = tc.get("function", {}) + args_str = func.get("arguments", "{}") + if isinstance(args_str, str): + try: + args = json.loads(args_str) + except json.JSONDecodeError: + args = {} + else: + args = args_str + + tool_calls.append(ToolCallRequest( + id=tc.get("id", _short_tool_id()), + name=func.get("name", ""), + arguments=args, + )) + + # Parse usage + usage = data.get("usage", {}) + usage_dict = { + "prompt_tokens": usage.get("prompt_tokens", 0), + "completion_tokens": usage.get("completion_tokens", 0), + "total_tokens": usage.get("total_tokens", 0), + } + + return LLMResponse( + content=content, + tool_calls=tool_calls, + finish_reason=finish_reason, + usage=usage_dict, + ) + + def get_default_model(self) -> str: + """Get the default model.""" + return self.default_model diff --git a/core/agents/requirements.txt b/core/agents/requirements.txt new file mode 100644 index 0000000..554a3d3 --- /dev/null +++ b/core/agents/requirements.txt @@ -0,0 +1,19 @@ +# X-Agents Agent Core Dependencies + +# Web framework +fastapi>=0.109.0 +uvicorn>=0.27.0 +pydantic>=2.5.0 + +# LLM providers +openai>=1.12.0 +anthropic>=0.18.0 + +# Async +aiohttp>=3.9.0 + +# Vector search (optional) +chromadb>=0.4.0 + +# Utilities +python-dotenv>=1.0.0 diff --git a/core/agents/skills/__init__.py b/core/agents/skills/__init__.py new file mode 100644 index 0000000..5ad337d --- /dev/null +++ b/core/agents/skills/__init__.py @@ -0,0 +1,6 @@ +"""Skills module for X-Agents.""" + +from agents.skills.loader import SkillsLoader, Skill +from agents.skills.executor import SkillExecutor + +__all__ = ["SkillsLoader", "Skill", "SkillExecutor"] diff --git a/core/agents/skills/executor.py b/core/agents/skills/executor.py new file mode 100644 index 0000000..017d605 --- /dev/null +++ b/core/agents/skills/executor.py @@ -0,0 +1,178 @@ +"""Skill executor for executing skills.""" + +import logging +import re +from dataclasses import dataclass +from typing import Any + +from loguru import logger + +from agents.skills.loader import Skill, SkillsLoader + +logger = logging.getLogger(__name__) + + +@dataclass +class SkillContext: + """Execution context for a skill.""" + skill_id: str + skill_name: str + input_data: dict[str, Any] + user_message: str + + +class SkillExecutor: + """Executes skills based on user input.""" + + def __init__(self, skills_loader: SkillsLoader): + """Initialize skill executor. + + Args: + skills_loader: SkillsLoader instance for loading skills + """ + self.loader = skills_loader + self._skills_prompt_cache: dict[str, str] = {} + + async def find_matching_skills(self, user_message: str) -> list[Skill]: + """Find skills that match the user message. + + Args: + user_message: User's input message + + Returns: + List of matching skills (currently returns all active skills) + """ + # Get all active skills + skills = await self.loader.list_skills() + active_skills = [s for s in skills if s.status == "active"] + return active_skills + + async def execute_skill( + self, + skill_id: str, + context: SkillContext, + ) -> str | None: + """Execute a skill with given context. + + Args: + skill_id: ID of skill to execute + context: Execution context + + Returns: + Execution result as string, or None if failed + """ + skill = await self.loader.load_skill_with_content(skill_id) + if not skill: + logger.warning(f"Skill not found: {skill_id}") + return None + + if skill.status != "active": + logger.warning(f"Skill is not active: {skill_id}") + return None + + # Extract prompt/instructions from skill content + prompt = self._extract_skill_prompt(skill) + + # Replace placeholders in prompt with context + prompt = self._inject_context(prompt, context) + + return prompt + + def _extract_skill_prompt(self, skill: Skill) -> str: + """Extract main prompt/instructions from skill content. + + Args: + skill: Skill object with content + + Returns: + Extracted prompt + """ + content = skill.content + + # Skip frontmatter if present + lines = content.split("\n") + start_line = 0 + if content.startswith("---"): + for i in range(1, len(lines)): + if lines[i].strip() == "---": + start_line = i + 1 + break + + # Join remaining content + main_content = "\n".join(lines[start_line:]) + + # Remove markdown headers but keep content + prompt = re.sub(r"^#+\s+", "", main_content, flags=re.MULTILINE) + + return prompt.strip() + + def _inject_context(self, prompt: str, context: SkillContext) -> str: + """Inject context into prompt template. + + Args: + prompt: Prompt template + context: Execution context + + Returns: + Prompt with context injected + """ + # Replace common placeholders + replacements = { + "{{user_message}}": context.user_message, + "{{skill_name}}": context.skill_name, + "{{input}}": str(context.input_data), + } + + result = prompt + for placeholder, value in replacements.items(): + result = result.replace(placeholder, value) + + return result + + async def get_skill_system_prompt(self, skill_id: str) -> str | None: + """Get system prompt for a skill to be used in LLM context. + + Args: + skill_id: Skill ID + + Returns: + System prompt for the skill, or None if not found + """ + # Check cache + if skill_id in self._skills_prompt_cache: + return self._skills_prompt_cache[skill_id] + + skill = await self.loader.load_skill_with_content(skill_id) + if not skill or skill.status != "active": + return None + + # Extract prompt + prompt = self._extract_skill_prompt(skill) + + # Cache it + self._skills_prompt_cache[skill_id] = prompt + + return prompt + + def build_skills_context(self, skills: list[Skill]) -> str: + """Build context string from multiple skills. + + Args: + skills: List of skills + + Returns: + Combined context string + """ + if not skills: + return "" + + context_parts = ["## Available Skills\n"] + for skill in skills: + context_parts.append(f"### {skill.name}") + context_parts.append(f"{skill.description}\n") + + return "\n".join(context_parts) + + def clear_cache(self) -> None: + """Clear prompt cache.""" + self._skills_prompt_cache.clear() diff --git a/core/agents/skills/loader.py b/core/agents/skills/loader.py new file mode 100644 index 0000000..16125c0 --- /dev/null +++ b/core/agents/skills/loader.py @@ -0,0 +1,252 @@ +"""Skills loader for loading and managing skills from Go backend.""" + +import logging +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +import aiohttp + +logger = logging.getLogger(__name__) + + +@dataclass +class Skill: + """Skill data model.""" + id: str + name: str + description: str + skill_type: str # system/user + status: str # active/inactive + path: str + content: str = "" + + +class SkillsLoader: + """Loads skills from Go backend API and local file system.""" + + def __init__(self, base_url: str): + """Initialize skills loader. + + Args: + base_url: Go backend API base URL + """ + self.base_url = base_url.rstrip("/") + self._session = None + self._skills_cache: dict[str, Skill] = {} + + async def _get_session(self) -> aiohttp.ClientSession: + """Get or create aiohttp session.""" + if self._session is None or self._session.closed: + self._session = aiohttp.ClientSession() + return self._session + + async def close(self) -> None: + """Close the session.""" + if self._session and not self._session.closed: + await self._session.close() + + async def list_skills(self, skill_type: str | None = None) -> list[Skill]: + """List all skills from Go backend. + + Args: + skill_type: Optional filter by skill type (system/user) + + Returns: + List of skills + """ + url = f"{self.base_url}/api/skill/list" + params = {} + if skill_type: + params["type"] = skill_type + + try: + session = await self._get_session() + async with session.get(url, params=params) as response: + if response.status == 200: + result = await response.json() + skills_list = result.get("list", []) + skills = [] + for s in skills_list: + skill = Skill( + id=s.get("id", ""), + name=s.get("skill_name", ""), + description=s.get("skill_desc", ""), + skill_type=s.get("skill_type", "user"), + status=s.get("status", "inactive"), + path=s.get("path", ""), + ) + skills.append(skill) + return skills + logger.warning(f"Failed to list skills: {response.status}") + return [] + except Exception as e: + logger.error(f"Error listing skills: {e}") + return [] + + async def get_skill(self, skill_id: str) -> Skill | None: + """Get a skill by ID. + + Args: + skill_id: Skill ID + + Returns: + Skill object or None if not found + """ + # Check cache first + if skill_id in self._skills_cache: + return self._skills_cache[skill_id] + + url = f"{self.base_url}/api/skill/{skill_id}" + + try: + session = await self._get_session() + async with session.get(url) as response: + if response.status == 200: + result = await response.json() + skill_data = result.get("skill", {}) + skill = Skill( + id=skill_data.get("id", ""), + name=skill_data.get("skill_name", ""), + description=skill_data.get("skill_desc", ""), + skill_type=skill_data.get("skill_type", "user"), + status=skill_data.get("status", "inactive"), + path=skill_data.get("path", ""), + ) + self._skills_cache[skill_id] = skill + return skill + return None + except Exception as e: + logger.error(f"Error getting skill {skill_id}: {e}") + return None + + async def get_skill_content(self, skill_id: str) -> str | None: + """Get skill content (SKILL.md file content). + + Args: + skill_id: Skill ID + + Returns: + Skill content as string, or None if failed + """ + url = f"{self.base_url}/api/skill/content" + params = {"id": skill_id} + + try: + session = await self._get_session() + async with session.get(url, params=params) as response: + if response.status == 200: + content = await response.text() + return content + logger.warning(f"Failed to get skill content: {response.status}") + return None + except Exception as e: + logger.error(f"Error getting skill content: {e}") + return None + + async def sync_skills(self) -> int: + """Manually trigger skills sync from file system. + + Returns: + Number of skills synced + """ + url = f"{self.base_url}/api/skill/sync" + + try: + session = await self._get_session() + async with session.get(url) as response: + if response.status == 200: + result = await response.json() + count = result.get("count", 0) + logger.info(f"Synced {count} skills") + return count + return 0 + except Exception as e: + logger.error(f"Error syncing skills: {e}") + return 0 + + async def load_skill_with_content(self, skill_id: str) -> Skill | None: + """Load skill with its content. + + Args: + skill_id: Skill ID + + Returns: + Skill object with content, or None if failed + """ + skill = await self.get_skill(skill_id) + if skill: + content = await self.get_skill_content(skill_id) + if content: + skill.content = content + return skill + + def load_skill_from_file(self, file_path: str | Path) -> Skill | None: + """Load skill from local file system. + + Args: + file_path: Path to SKILL.md file + + Returns: + Skill object or None if failed + """ + path = Path(file_path) + if not path.exists(): + logger.warning(f"Skill file not found: {path}") + return None + + try: + content = path.read_text(encoding="utf-8") + # Parse frontmatter + name, description = self._parse_frontmatter(content) + + return Skill( + id="", + name=name or path.stem, + description=description or "", + skill_type="user", + status="active", + path=str(path), + content=content, + ) + except Exception as e: + logger.error(f"Error loading skill from file: {e}") + return None + + def _parse_frontmatter(self, content: str) -> tuple[str | None, str | None]: + """Parse YAML frontmatter from skill content. + + Args: + content: Skill markdown content + + Returns: + Tuple of (name, description) + """ + import re + + if not content.startswith("---"): + return None, None + + lines = content.split("\n") + end_idx = 0 + for i in range(1, len(lines)): + if lines[i].strip() == "---": + end_idx = i + break + + if end_idx == 0: + return None, None + + yaml_content = "\n".join(lines[1:end_idx]) + + name_match = re.search(r"name:\s*(.+)", yaml_content) + name = name_match.group(1).strip() if name_match else None + + desc_match = re.search(r"description:\s*(.+)", yaml_content) + description = desc_match.group(1).strip() if desc_match else None + + return name, description + + def clear_cache(self) -> None: + """Clear skills cache.""" + self._skills_cache.clear() diff --git a/core/agents/skills/user/openakita/skills@algorithmic-art/LICENSE.txt b/core/agents/skills/user/openakita/skills@algorithmic-art/LICENSE.txt new file mode 100644 index 0000000..7a4a3ea --- /dev/null +++ b/core/agents/skills/user/openakita/skills@algorithmic-art/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/core/agents/skills/user/openakita/skills@algorithmic-art/SKILL.md b/core/agents/skills/user/openakita/skills@algorithmic-art/SKILL.md new file mode 100644 index 0000000..27f069b --- /dev/null +++ b/core/agents/skills/user/openakita/skills@algorithmic-art/SKILL.md @@ -0,0 +1,405 @@ +--- +name: openakita/skills@algorithmic-art +description: Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations. +license: Complete terms in LICENSE.txt +--- + +Algorithmic philosophies are computational aesthetic movements that are then expressed through code. Output .md files (philosophy), .html files (interactive viewer), and .js files (generative algorithms). + +This happens in two steps: +1. Algorithmic Philosophy Creation (.md file) +2. Express by creating p5.js generative art (.html + .js files) + +First, undertake this task: + +## ALGORITHMIC PHILOSOPHY CREATION + +To begin, create an ALGORITHMIC PHILOSOPHY (not static images or templates) that will be interpreted through: +- Computational processes, emergent behavior, mathematical beauty +- Seeded randomness, noise fields, organic systems +- Particles, flows, fields, forces +- Parametric variation and controlled chaos + +### THE CRITICAL UNDERSTANDING +- What is received: Some subtle input or instructions by the user to take into account, but use as a foundation; it should not constrain creative freedom. +- What is created: An algorithmic philosophy/generative aesthetic movement. +- What happens next: The same version receives the philosophy and EXPRESSES IT IN CODE - creating p5.js sketches that are 90% algorithmic generation, 10% essential parameters. + +Consider this approach: +- Write a manifesto for a generative art movement +- The next phase involves writing the algorithm that brings it to life + +The philosophy must emphasize: Algorithmic expression. Emergent behavior. Computational beauty. Seeded variation. + +### HOW TO GENERATE AN ALGORITHMIC PHILOSOPHY + +**Name the movement** (1-2 words): "Organic Turbulence" / "Quantum Harmonics" / "Emergent Stillness" + +**Articulate the philosophy** (4-6 paragraphs - concise but complete): + +To capture the ALGORITHMIC essence, express how this philosophy manifests through: +- Computational processes and mathematical relationships? +- Noise functions and randomness patterns? +- Particle behaviors and field dynamics? +- Temporal evolution and system states? +- Parametric variation and emergent complexity? + +**CRITICAL GUIDELINES:** +- **Avoid redundancy**: Each algorithmic aspect should be mentioned once. Avoid repeating concepts about noise theory, particle dynamics, or mathematical principles unless adding new depth. +- **Emphasize craftsmanship REPEATEDLY**: The philosophy MUST stress multiple times that the final algorithm should appear as though it took countless hours to develop, was refined with care, and comes from someone at the absolute top of their field. This framing is essential - repeat phrases like "meticulously crafted algorithm," "the product of deep computational expertise," "painstaking optimization," "master-level implementation." +- **Leave creative space**: Be specific about the algorithmic direction, but concise enough that the next Claude has room to make interpretive implementation choices at an extremely high level of craftsmanship. + +The philosophy must guide the next version to express ideas ALGORITHMICALLY, not through static images. Beauty lives in the process, not the final frame. + +### PHILOSOPHY EXAMPLES + +**"Organic Turbulence"** +Philosophy: Chaos constrained by natural law, order emerging from disorder. +Algorithmic expression: Flow fields driven by layered Perlin noise. Thousands of particles following vector forces, their trails accumulating into organic density maps. Multiple noise octaves create turbulent regions and calm zones. Color emerges from velocity and density - fast particles burn bright, slow ones fade to shadow. The algorithm runs until equilibrium - a meticulously tuned balance where every parameter was refined through countless iterations by a master of computational aesthetics. + +**"Quantum Harmonics"** +Philosophy: Discrete entities exhibiting wave-like interference patterns. +Algorithmic expression: Particles initialized on a grid, each carrying a phase value that evolves through sine waves. When particles are near, their phases interfere - constructive interference creates bright nodes, destructive creates voids. Simple harmonic motion generates complex emergent mandalas. The result of painstaking frequency calibration where every ratio was carefully chosen to produce resonant beauty. + +**"Recursive Whispers"** +Philosophy: Self-similarity across scales, infinite depth in finite space. +Algorithmic expression: Branching structures that subdivide recursively. Each branch slightly randomized but constrained by golden ratios. L-systems or recursive subdivision generate tree-like forms that feel both mathematical and organic. Subtle noise perturbations break perfect symmetry. Line weights diminish with each recursion level. Every branching angle the product of deep mathematical exploration. + +**"Field Dynamics"** +Philosophy: Invisible forces made visible through their effects on matter. +Algorithmic expression: Vector fields constructed from mathematical functions or noise. Particles born at edges, flowing along field lines, dying when they reach equilibrium or boundaries. Multiple fields can attract, repel, or rotate particles. The visualization shows only the traces - ghost-like evidence of invisible forces. A computational dance meticulously choreographed through force balance. + +**"Stochastic Crystallization"** +Philosophy: Random processes crystallizing into ordered structures. +Algorithmic expression: Randomized circle packing or Voronoi tessellation. Start with random points, let them evolve through relaxation algorithms. Cells push apart until equilibrium. Color based on cell size, neighbor count, or distance from center. The organic tiling that emerges feels both random and inevitable. Every seed produces unique crystalline beauty - the mark of a master-level generative algorithm. + +*These are condensed examples. The actual algorithmic philosophy should be 4-6 substantial paragraphs.* + +### ESSENTIAL PRINCIPLES +- **ALGORITHMIC PHILOSOPHY**: Creating a computational worldview to be expressed through code +- **PROCESS OVER PRODUCT**: Always emphasize that beauty emerges from the algorithm's execution - each run is unique +- **PARAMETRIC EXPRESSION**: Ideas communicate through mathematical relationships, forces, behaviors - not static composition +- **ARTISTIC FREEDOM**: The next Claude interprets the philosophy algorithmically - provide creative implementation room +- **PURE GENERATIVE ART**: This is about making LIVING ALGORITHMS, not static images with randomness +- **EXPERT CRAFTSMANSHIP**: Repeatedly emphasize the final algorithm must feel meticulously crafted, refined through countless iterations, the product of deep expertise by someone at the absolute top of their field in computational aesthetics + +**The algorithmic philosophy should be 4-6 paragraphs long.** Fill it with poetic computational philosophy that brings together the intended vision. Avoid repeating the same points. Output this algorithmic philosophy as a .md file. + +--- + +## DEDUCING THE CONCEPTUAL SEED + +**CRITICAL STEP**: Before implementing the algorithm, identify the subtle conceptual thread from the original request. + +**THE ESSENTIAL PRINCIPLE**: +The concept is a **subtle, niche reference embedded within the algorithm itself** - not always literal, always sophisticated. Someone familiar with the subject should feel it intuitively, while others simply experience a masterful generative composition. The algorithmic philosophy provides the computational language. The deduced concept provides the soul - the quiet conceptual DNA woven invisibly into parameters, behaviors, and emergence patterns. + +This is **VERY IMPORTANT**: The reference must be so refined that it enhances the work's depth without announcing itself. Think like a jazz musician quoting another song through algorithmic harmony - only those who know will catch it, but everyone appreciates the generative beauty. + +--- + +## P5.JS IMPLEMENTATION + +With the philosophy AND conceptual framework established, express it through code. Pause to gather thoughts before proceeding. Use only the algorithmic philosophy created and the instructions below. + +### ⚠️ STEP 0: READ THE TEMPLATE FIRST ⚠️ + +**CRITICAL: BEFORE writing any HTML:** + +1. **Read** `templates/viewer.html` using the Read tool +2. **Study** the exact structure, styling, and Anthropic branding +3. **Use that file as the LITERAL STARTING POINT** - not just inspiration +4. **Keep all FIXED sections exactly as shown** (header, sidebar structure, Anthropic colors/fonts, seed controls, action buttons) +5. **Replace only the VARIABLE sections** marked in the file's comments (algorithm, parameters, UI controls for parameters) + +**Avoid:** +- ❌ Creating HTML from scratch +- ❌ Inventing custom styling or color schemes +- ❌ Using system fonts or dark themes +- ❌ Changing the sidebar structure + +**Follow these practices:** +- ✅ Copy the template's exact HTML structure +- ✅ Keep Anthropic branding (Poppins/Lora fonts, light colors, gradient backdrop) +- ✅ Maintain the sidebar layout (Seed → Parameters → Colors? → Actions) +- ✅ Replace only the p5.js algorithm and parameter controls + +The template is the foundation. Build on it, don't rebuild it. + +--- + +To create gallery-quality computational art that lives and breathes, use the algorithmic philosophy as the foundation. + +### TECHNICAL REQUIREMENTS + +**Seeded Randomness (Art Blocks Pattern)**: +```javascript +// ALWAYS use a seed for reproducibility +let seed = 12345; // or hash from user input +randomSeed(seed); +noiseSeed(seed); +``` + +**Parameter Structure - FOLLOW THE PHILOSOPHY**: + +To establish parameters that emerge naturally from the algorithmic philosophy, consider: "What qualities of this system can be adjusted?" + +```javascript +let params = { + seed: 12345, // Always include seed for reproducibility + // colors + // Add parameters that control YOUR algorithm: + // - Quantities (how many?) + // - Scales (how big? how fast?) + // - Probabilities (how likely?) + // - Ratios (what proportions?) + // - Angles (what direction?) + // - Thresholds (when does behavior change?) +}; +``` + +**To design effective parameters, focus on the properties the system needs to be tunable rather than thinking in terms of "pattern types".** + +**Core Algorithm - EXPRESS THE PHILOSOPHY**: + +**CRITICAL**: The algorithmic philosophy should dictate what to build. + +To express the philosophy through code, avoid thinking "which pattern should I use?" and instead think "how to express this philosophy through code?" + +If the philosophy is about **organic emergence**, consider using: +- Elements that accumulate or grow over time +- Random processes constrained by natural rules +- Feedback loops and interactions + +If the philosophy is about **mathematical beauty**, consider using: +- Geometric relationships and ratios +- Trigonometric functions and harmonics +- Precise calculations creating unexpected patterns + +If the philosophy is about **controlled chaos**, consider using: +- Random variation within strict boundaries +- Bifurcation and phase transitions +- Order emerging from disorder + +**The algorithm flows from the philosophy, not from a menu of options.** + +To guide the implementation, let the conceptual essence inform creative and original choices. Build something that expresses the vision for this particular request. + +**Canvas Setup**: Standard p5.js structure: +```javascript +function setup() { + createCanvas(1200, 1200); + // Initialize your system +} + +function draw() { + // Your generative algorithm + // Can be static (noLoop) or animated +} +``` + +### CRAFTSMANSHIP REQUIREMENTS + +**CRITICAL**: To achieve mastery, create algorithms that feel like they emerged through countless iterations by a master generative artist. Tune every parameter carefully. Ensure every pattern emerges with purpose. This is NOT random noise - this is CONTROLLED CHAOS refined through deep expertise. + +- **Balance**: Complexity without visual noise, order without rigidity +- **Color Harmony**: Thoughtful palettes, not random RGB values +- **Composition**: Even in randomness, maintain visual hierarchy and flow +- **Performance**: Smooth execution, optimized for real-time if animated +- **Reproducibility**: Same seed ALWAYS produces identical output + +### OUTPUT FORMAT + +Output: +1. **Algorithmic Philosophy** - As markdown or text explaining the generative aesthetic +2. **Single HTML Artifact** - Self-contained interactive generative art built from `templates/viewer.html` (see STEP 0 and next section) + +The HTML artifact contains everything: p5.js (from CDN), the algorithm, parameter controls, and UI - all in one file that works immediately in claude.ai artifacts or any browser. Start from the template file, not from scratch. + +--- + +## INTERACTIVE ARTIFACT CREATION + +**REMINDER: `templates/viewer.html` should have already been read (see STEP 0). Use that file as the starting point.** + +To allow exploration of the generative art, create a single, self-contained HTML artifact. Ensure this artifact works immediately in claude.ai or any browser - no setup required. Embed everything inline. + +### CRITICAL: WHAT'S FIXED VS VARIABLE + +The `templates/viewer.html` file is the foundation. It contains the exact structure and styling needed. + +**FIXED (always include exactly as shown):** +- Layout structure (header, sidebar, main canvas area) +- Anthropic branding (UI colors, fonts, gradients) +- Seed section in sidebar: + - Seed display + - Previous/Next buttons + - Random button + - Jump to seed input + Go button +- Actions section in sidebar: + - Regenerate button + - Reset button + +**VARIABLE (customize for each artwork):** +- The entire p5.js algorithm (setup/draw/classes) +- The parameters object (define what the art needs) +- The Parameters section in sidebar: + - Number of parameter controls + - Parameter names + - Min/max/step values for sliders + - Control types (sliders, inputs, etc.) +- Colors section (optional): + - Some art needs color pickers + - Some art might use fixed colors + - Some art might be monochrome (no color controls needed) + - Decide based on the art's needs + +**Every artwork should have unique parameters and algorithm!** The fixed parts provide consistent UX - everything else expresses the unique vision. + +### REQUIRED FEATURES + +**1. Parameter Controls** +- Sliders for numeric parameters (particle count, noise scale, speed, etc.) +- Color pickers for palette colors +- Real-time updates when parameters change +- Reset button to restore defaults + +**2. Seed Navigation** +- Display current seed number +- "Previous" and "Next" buttons to cycle through seeds +- "Random" button for random seed +- Input field to jump to specific seed +- Generate 100 variations when requested (seeds 1-100) + +**3. Single Artifact Structure** +```html + + + + + + + + +
+
+ +
+ + + +``` + +**CRITICAL**: This is a single artifact. No external files, no imports (except p5.js CDN). Everything inline. + +**4. Implementation Details - BUILD THE SIDEBAR** + +The sidebar structure: + +**1. Seed (FIXED)** - Always include exactly as shown: +- Seed display +- Prev/Next/Random/Jump buttons + +**2. Parameters (VARIABLE)** - Create controls for the art: +```html +
+ + + ... +
+``` +Add as many control-group divs as there are parameters. + +**3. Colors (OPTIONAL/VARIABLE)** - Include if the art needs adjustable colors: +- Add color pickers if users should control palette +- Skip this section if the art uses fixed colors +- Skip if the art is monochrome + +**4. Actions (FIXED)** - Always include exactly as shown: +- Regenerate button +- Reset button +- Download PNG button + +**Requirements**: +- Seed controls must work (prev/next/random/jump/display) +- All parameters must have UI controls +- Regenerate, Reset, Download buttons must work +- Keep Anthropic branding (UI styling, not art colors) + +### USING THE ARTIFACT + +The HTML artifact works immediately: +1. **In claude.ai**: Displayed as an interactive artifact - runs instantly +2. **As a file**: Save and open in any browser - no server needed +3. **Sharing**: Send the HTML file - it's completely self-contained + +--- + +## VARIATIONS & EXPLORATION + +The artifact includes seed navigation by default (prev/next/random buttons), allowing users to explore variations without creating multiple files. If the user wants specific variations highlighted: + +- Include seed presets (buttons for "Variation 1: Seed 42", "Variation 2: Seed 127", etc.) +- Add a "Gallery Mode" that shows thumbnails of multiple seeds side-by-side +- All within the same single artifact + +This is like creating a series of prints from the same plate - the algorithm is consistent, but each seed reveals different facets of its potential. The interactive nature means users discover their own favorites by exploring the seed space. + +--- + +## THE CREATIVE PROCESS + +**User request** → **Algorithmic philosophy** → **Implementation** + +Each request is unique. The process involves: + +1. **Interpret the user's intent** - What aesthetic is being sought? +2. **Create an algorithmic philosophy** (4-6 paragraphs) describing the computational approach +3. **Implement it in code** - Build the algorithm that expresses this philosophy +4. **Design appropriate parameters** - What should be tunable? +5. **Build matching UI controls** - Sliders/inputs for those parameters + +**The constants**: +- Anthropic branding (colors, fonts, layout) +- Seed navigation (always present) +- Self-contained HTML artifact + +**Everything else is variable**: +- The algorithm itself +- The parameters +- The UI controls +- The visual outcome + +To achieve the best results, trust creativity and let the philosophy guide the implementation. + +--- + +## RESOURCES + +This skill includes helpful templates and documentation: + +- **templates/viewer.html**: REQUIRED STARTING POINT for all HTML artifacts. + - This is the foundation - contains the exact structure and Anthropic branding + - **Keep unchanged**: Layout structure, sidebar organization, Anthropic colors/fonts, seed controls, action buttons + - **Replace**: The p5.js algorithm, parameter definitions, and UI controls in Parameters section + - The extensive comments in the file mark exactly what to keep vs replace + +- **templates/generator_template.js**: Reference for p5.js best practices and code structure principles. + - Shows how to organize parameters, use seeded randomness, structure classes + - NOT a pattern menu - use these principles to build unique algorithms + - Embed algorithms inline in the HTML artifact (don't create separate .js files) + +**Critical reminder**: +- The **template is the STARTING POINT**, not inspiration +- The **algorithm is where to create** something unique +- Don't copy the flow field example - build what the philosophy demands +- But DO keep the exact UI structure and Anthropic branding from the template \ No newline at end of file diff --git a/core/agents/skills/user/openakita/skills@algorithmic-art/templates/generator_template.js b/core/agents/skills/user/openakita/skills@algorithmic-art/templates/generator_template.js new file mode 100644 index 0000000..e263fbd --- /dev/null +++ b/core/agents/skills/user/openakita/skills@algorithmic-art/templates/generator_template.js @@ -0,0 +1,223 @@ +/** + * ═══════════════════════════════════════════════════════════════════════════ + * P5.JS GENERATIVE ART - BEST PRACTICES + * ═══════════════════════════════════════════════════════════════════════════ + * + * This file shows STRUCTURE and PRINCIPLES for p5.js generative art. + * It does NOT prescribe what art you should create. + * + * Your algorithmic philosophy should guide what you build. + * These are just best practices for how to structure your code. + * + * ═══════════════════════════════════════════════════════════════════════════ + */ + +// ============================================================================ +// 1. PARAMETER ORGANIZATION +// ============================================================================ +// Keep all tunable parameters in one object +// This makes it easy to: +// - Connect to UI controls +// - Reset to defaults +// - Serialize/save configurations + +let params = { + // Define parameters that match YOUR algorithm + // Examples (customize for your art): + // - Counts: how many elements (particles, circles, branches, etc.) + // - Scales: size, speed, spacing + // - Probabilities: likelihood of events + // - Angles: rotation, direction + // - Colors: palette arrays + + seed: 12345, + // define colorPalette as an array -- choose whatever colors you'd like ['#d97757', '#6a9bcc', '#788c5d', '#b0aea5'] + // Add YOUR parameters here based on your algorithm +}; + +// ============================================================================ +// 2. SEEDED RANDOMNESS (Critical for reproducibility) +// ============================================================================ +// ALWAYS use seeded random for Art Blocks-style reproducible output + +function initializeSeed(seed) { + randomSeed(seed); + noiseSeed(seed); + // Now all random() and noise() calls will be deterministic +} + +// ============================================================================ +// 3. P5.JS LIFECYCLE +// ============================================================================ + +function setup() { + createCanvas(800, 800); + + // Initialize seed first + initializeSeed(params.seed); + + // Set up your generative system + // This is where you initialize: + // - Arrays of objects + // - Grid structures + // - Initial positions + // - Starting states + + // For static art: call noLoop() at the end of setup + // For animated art: let draw() keep running +} + +function draw() { + // Option 1: Static generation (runs once, then stops) + // - Generate everything in setup() + // - Call noLoop() in setup() + // - draw() doesn't do much or can be empty + + // Option 2: Animated generation (continuous) + // - Update your system each frame + // - Common patterns: particle movement, growth, evolution + // - Can optionally call noLoop() after N frames + + // Option 3: User-triggered regeneration + // - Use noLoop() by default + // - Call redraw() when parameters change +} + +// ============================================================================ +// 4. CLASS STRUCTURE (When you need objects) +// ============================================================================ +// Use classes when your algorithm involves multiple entities +// Examples: particles, agents, cells, nodes, etc. + +class Entity { + constructor() { + // Initialize entity properties + // Use random() here - it will be seeded + } + + update() { + // Update entity state + // This might involve: + // - Physics calculations + // - Behavioral rules + // - Interactions with neighbors + } + + display() { + // Render the entity + // Keep rendering logic separate from update logic + } +} + +// ============================================================================ +// 5. PERFORMANCE CONSIDERATIONS +// ============================================================================ + +// For large numbers of elements: +// - Pre-calculate what you can +// - Use simple collision detection (spatial hashing if needed) +// - Limit expensive operations (sqrt, trig) when possible +// - Consider using p5 vectors efficiently + +// For smooth animation: +// - Aim for 60fps +// - Profile if things are slow +// - Consider reducing particle counts or simplifying calculations + +// ============================================================================ +// 6. UTILITY FUNCTIONS +// ============================================================================ + +// Color utilities +function hexToRgb(hex) { + const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex); + return result ? { + r: parseInt(result[1], 16), + g: parseInt(result[2], 16), + b: parseInt(result[3], 16) + } : null; +} + +function colorFromPalette(index) { + return params.colorPalette[index % params.colorPalette.length]; +} + +// Mapping and easing +function mapRange(value, inMin, inMax, outMin, outMax) { + return outMin + (outMax - outMin) * ((value - inMin) / (inMax - inMin)); +} + +function easeInOutCubic(t) { + return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2; +} + +// Constrain to bounds +function wrapAround(value, max) { + if (value < 0) return max; + if (value > max) return 0; + return value; +} + +// ============================================================================ +// 7. PARAMETER UPDATES (Connect to UI) +// ============================================================================ + +function updateParameter(paramName, value) { + params[paramName] = value; + // Decide if you need to regenerate or just update + // Some params can update in real-time, others need full regeneration +} + +function regenerate() { + // Reinitialize your generative system + // Useful when parameters change significantly + initializeSeed(params.seed); + // Then regenerate your system +} + +// ============================================================================ +// 8. COMMON P5.JS PATTERNS +// ============================================================================ + +// Drawing with transparency for trails/fading +function fadeBackground(opacity) { + fill(250, 249, 245, opacity); // Anthropic light with alpha + noStroke(); + rect(0, 0, width, height); +} + +// Using noise for organic variation +function getNoiseValue(x, y, scale = 0.01) { + return noise(x * scale, y * scale); +} + +// Creating vectors from angles +function vectorFromAngle(angle, magnitude = 1) { + return createVector(cos(angle), sin(angle)).mult(magnitude); +} + +// ============================================================================ +// 9. EXPORT FUNCTIONS +// ============================================================================ + +function exportImage() { + saveCanvas('generative-art-' + params.seed, 'png'); +} + +// ============================================================================ +// REMEMBER +// ============================================================================ +// +// These are TOOLS and PRINCIPLES, not a recipe. +// Your algorithmic philosophy should guide WHAT you create. +// This structure helps you create it WELL. +// +// Focus on: +// - Clean, readable code +// - Parameterized for exploration +// - Seeded for reproducibility +// - Performant execution +// +// The art itself is entirely up to you! +// +// ============================================================================ \ No newline at end of file diff --git a/core/agents/skills/user/openakita/skills@algorithmic-art/templates/viewer.html b/core/agents/skills/user/openakita/skills@algorithmic-art/templates/viewer.html new file mode 100644 index 0000000..630cc1f --- /dev/null +++ b/core/agents/skills/user/openakita/skills@algorithmic-art/templates/viewer.html @@ -0,0 +1,599 @@ + + + + + + + Generative Art Viewer + + + + + + + +
+ +
+ +

TITLE - EDIT

+
SUBHEADER - EDIT
+ + +
+

Seed

+ +
+ + +
+ +
+ + +
+

Parameters

+ + +
+ +
+ + 5000 +
+
+ + +
+ +
+ + 0.5 +
+
+ + +
+ +
+ + 0.005 +
+
+ + +
+ +
+ + 8 +
+
+
+ + +
+

Colors

+ + +
+ +
+ + #d97757 +
+
+ + +
+ +
+ + #6a9bcc +
+
+ + +
+ +
+ + #788c5d +
+
+
+ + +
+

Actions

+
+ +
+
+
+ + +
+
+
Initializing generative art...
+
+
+
+ + + + \ No newline at end of file diff --git a/core/agents/skills/user/openakita/skills@code-reviewer/SKILL.md b/core/agents/skills/user/openakita/skills@code-reviewer/SKILL.md new file mode 100644 index 0000000..16acd90 --- /dev/null +++ b/core/agents/skills/user/openakita/skills@code-reviewer/SKILL.md @@ -0,0 +1,65 @@ +--- +name: openakita/skills@code-reviewer +description: + Use this skill to review code. It supports both local changes (staged or working tree) + and remote Pull Requests (by ID or URL). It focuses on correctness, maintainability, + and adherence to project standards. +--- + +# Code Reviewer + +This skill guides the agent in conducting professional and thorough code reviews for both local development and remote Pull Requests. + +## Workflow + +### 1. Determine Review Target +* **Remote PR**: If the user provides a PR number or URL (e.g., "Review PR #123"), target that remote PR. +* **Local Changes**: If no specific PR is mentioned, or if the user asks to "review my changes", target the current local file system states (staged and unstaged changes). + +### 2. Preparation + +#### For Remote PRs: +1. **Checkout**: Use the GitHub CLI to checkout the PR. + ```bash + gh pr checkout + ``` +2. **Preflight**: Execute the project's standard verification suite to catch automated failures early. + ```bash + npm run preflight + ``` +3. **Context**: Read the PR description and any existing comments to understand the goal and history. + +#### For Local Changes: +1. **Identify Changes**: + * Check status: `git status` + * Read diffs: `git diff` (working tree) and/or `git diff --staged` (staged). +2. **Preflight (Optional)**: If the changes are substantial, ask the user if they want to run `npm run preflight` before reviewing. + +### 3. In-Depth Analysis +Analyze the code changes based on the following pillars: + +* **Correctness**: Does the code achieve its stated purpose without bugs or logical errors? +* **Maintainability**: Is the code clean, well-structured, and easy to understand and modify in the future? Consider factors like code clarity, modularity, and adherence to established design patterns. +* **Readability**: Is the code well-commented (where necessary) and consistently formatted according to our project's coding style guidelines? +* **Efficiency**: Are there any obvious performance bottlenecks or resource inefficiencies introduced by the changes? +* **Security**: Are there any potential security vulnerabilities or insecure coding practices? +* **Edge Cases and Error Handling**: Does the code appropriately handle edge cases and potential errors? +* **Testability**: Is the new or modified code adequately covered by tests (even if preflight checks pass)? Suggest additional test cases that would improve coverage or robustness. + +### 4. Provide Feedback + +#### Structure +* **Summary**: A high-level overview of the review. +* **Findings**: + * **Critical**: Bugs, security issues, or breaking changes. + * **Improvements**: Suggestions for better code quality or performance. + * **Nitpicks**: Formatting or minor style issues (optional). +* **Conclusion**: Clear recommendation (Approved / Request Changes). + +#### Tone +* Be constructive, professional, and friendly. +* Explain *why* a change is requested. +* For approvals, acknowledge the specific value of the contribution. + +### 5. Cleanup (Remote PRs only) +* After the review, ask the user if they want to switch back to the default branch (e.g., `main` or `master`). diff --git a/core/agents/tools.py b/core/agents/tools.py new file mode 100644 index 0000000..768fd9b --- /dev/null +++ b/core/agents/tools.py @@ -0,0 +1,202 @@ +"""Tool system for agent capabilities.""" + +import asyncio +import logging +from abc import ABC, abstractmethod +from typing import Any + +logger = logging.getLogger(__name__) + + +class Tool(ABC): + """Abstract base class for agent tools.""" + + @property + @abstractmethod + def name(self) -> str: + """Tool name used in function calls.""" + pass + + @property + @abstractmethod + def description(self) -> str: + """Description of what the tool does.""" + pass + + @property + @abstractmethod + def parameters(self) -> dict[str, Any]: + """JSON Schema for tool parameters.""" + pass + + @abstractmethod + async def execute(self, **kwargs: Any) -> str: + """Execute the tool with given parameters. + + Returns: + String result of the tool execution. + """ + pass + + def to_schema(self) -> dict[str, Any]: + """Convert tool to function schema format.""" + return { + "type": "function", + "function": { + "name": self.name, + "description": self.description, + "parameters": self.parameters, + }, + } + + +class ToolRegistry: + """Registry for managing agent tools.""" + + def __init__(self): + self._tools: dict[str, Tool] = {} + + def register(self, tool: Tool) -> None: + """Register a tool. + + Args: + tool: Tool instance to register + """ + self._tools[tool.name] = tool + logger.info(f"Registered tool: {tool.name}") + + def unregister(self, name: str) -> None: + """Unregister a tool. + + Args: + name: Tool name to unregister + """ + if name in self._tools: + del self._tools[name] + logger.info(f"Unregistered tool: {name}") + + def get(self, name: str) -> Tool | None: + """Get a tool by name. + + Args: + name: Tool name + + Returns: + Tool instance or None + """ + return self._tools.get(name) + + def get_definitions(self) -> list[dict[str, Any]]: + """Get all tool definitions for LLM. + + Returns: + List of tool schemas + """ + return [tool.to_schema() for tool in self._tools.values()] + + async def execute(self, name: str, arguments: dict[str, Any]) -> str: + """Execute a tool. + + Args: + name: Tool name + arguments: Tool arguments + + Returns: + Tool execution result + """ + tool = self.get(name) + if not tool: + return f'{{"error": "Unknown tool: {name}"}}' + + try: + # Validate parameters + validated = tool.cast_params(arguments) + errors = tool.validate_params(validated) + if errors: + return f'{{"error": "Parameter validation failed: {errors}"}}' + + # Execute with timeout + result = await asyncio.wait_for( + tool.execute(**validated), + timeout=60.0, + ) + return result + except asyncio.TimeoutError: + return f'{{"error": "Tool execution timed out: {name}"}}' + except Exception as exc: + logger.exception(f"Tool execution error: {name}") + return f'{{"error": "Tool execution failed: {exc}"}}' + + def list_tools(self) -> list[str]: + """List all registered tool names. + + Returns: + List of tool names + """ + return list(self._tools.keys()) + + +# Built-in placeholder tools +class EchoTool(Tool): + """Echo tool for testing.""" + + @property + def name(self) -> str: + return "echo" + + @property + def description(self) -> str: + return "Echo back the input text. Useful for testing." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "text": { + "type": "string", + "description": "Text to echo back", + } + }, + "required": ["text"], + } + + async def execute(self, **kwargs: Any) -> str: + text = kwargs.get("text", "") + return f'{{"echo": "{text}"}}' + + +class TimeTool(Tool): + """Get current time tool.""" + + @property + def name(self) -> str: + return "get_time" + + @property + def description(self) -> str: + return "Get the current date and time." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": {}, + } + + async def execute(self, **kwargs: Any) -> str: + from datetime import datetime + now = datetime.now() + return f'{{"time": "{now.isoformat()}"}}' + + +def create_default_registry() -> ToolRegistry: + """Create a tool registry with default tools. + + Returns: + Tool registry with built-in tools + """ + registry = ToolRegistry() + registry.register(EchoTool()) + registry.register(TimeTool()) + return registry diff --git a/core/agents/tools/__init__.py b/core/agents/tools/__init__.py new file mode 100644 index 0000000..3573a61 --- /dev/null +++ b/core/agents/tools/__init__.py @@ -0,0 +1,51 @@ +"""Tools module for X-Agents. + +This module provides tool infrastructure for the agent system. +It wraps and extends the nanobot tool implementation. +""" + +from nanobot.agent.tools.base import Tool +from nanobot.agent.tools.registry import ToolRegistry + +from agents.tools.builtin import ( + get_builtin_tools, + ReadFileTool, + WriteFileTool, + ListDirectoryTool, + SearchTool, + WebSearchTool, + CalculatorTool, + GetTimeTool, + BashTool, +) +from agents.tools.manager import ToolManager + + +def create_default_registry() -> ToolRegistry: + """Create a tool registry with default tools. + + Returns: + Tool registry with built-in tools + """ + registry = ToolRegistry() + # Register built-in tools + for tool in get_builtin_tools(): + registry.register(tool) + return registry + + +__all__ = [ + "Tool", + "ToolRegistry", + "ToolManager", + "create_default_registry", + "get_builtin_tools", + "ReadFileTool", + "WriteFileTool", + "ListDirectoryTool", + "SearchTool", + "WebSearchTool", + "CalculatorTool", + "GetTimeTool", + "BashTool", +] diff --git a/core/agents/tools/builtin.py b/core/agents/tools/builtin.py new file mode 100644 index 0000000..ca65095 --- /dev/null +++ b/core/agents/tools/builtin.py @@ -0,0 +1,431 @@ +"""Built-in tools for X-Agents.""" + +import asyncio +import json +import re +from pathlib import Path +from typing import Any + +from nanobot.agent.tools.base import Tool + + +class ReadFileTool(Tool): + """Read file contents.""" + + def __init__(self, workspace: Path | None = None): + self._workspace = workspace + + @property + def name(self) -> str: + return "read_file" + + @property + def description(self) -> str: + return "Read the contents of a file from the local filesystem." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "path": {"type": "string", "description": "The file path to read"}, + "offset": { + "type": "integer", + "description": "Line number to start reading from (1-indexed)", + "default": 1, + }, + "limit": { + "type": "integer", + "description": "Maximum number of lines to read", + "default": 100, + }, + }, + "required": ["path"], + } + + async def execute(self, path: str, offset: int = 1, limit: int = 100, **kwargs: Any) -> str: + try: + file_path = Path(path) + if not file_path.is_absolute() and self._workspace: + file_path = self._workspace / file_path + + if not file_path.exists(): + return f"Error: File not found: {path}" + + if not file_path.is_file(): + return f"Error: Not a file: {path}" + + lines = file_path.read_text(encoding="utf-8").split("\n") + start = max(0, offset - 1) + end = min(len(lines), start + limit) + + result_lines = [f"{i+1:4d}| {line}" for i, line in enumerate(lines[start:end], start=start+1)] + return f"File: {file_path}\nLines {start+1}-{end}/{len(lines)}\n\n" + "\n".join(result_lines) + except Exception as e: + return f"Error reading file: {str(e)}" + + +class WriteFileTool(Tool): + """Write content to a file.""" + + def __init__(self, workspace: Path | None = None): + self._workspace = workspace + + @property + def name(self) -> str: + return "write_file" + + @property + def description(self) -> str: + return "Write content to a file. Creates the file if it doesn't exist." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "path": {"type": "string", "description": "The file path to write to"}, + "content": {"type": "string", "description": "Content to write to the file"}, + "append": { + "type": "boolean", + "description": "Append to existing file instead of overwriting", + "default": False, + }, + }, + "required": ["path", "content"], + } + + async def execute(self, path: str, content: str, append: bool = False, **kwargs: Any) -> str: + try: + file_path = Path(path) + if not file_path.is_absolute() and self._workspace: + file_path = self._workspace / file_path + + file_path.parent.mkdir(parents=True, exist_ok=True) + + mode = "a" if append else "w" + with open(file_path, mode, encoding="utf-8") as f: + f.write(content) + + return f"Successfully wrote to {file_path}" + except Exception as e: + return f"Error writing file: {str(e)}" + + +class ListDirectoryTool(Tool): + """List directory contents.""" + + def __init__(self, workspace: Path | None = None): + self._workspace = workspace + + @property + def name(self) -> str: + return "list_directory" + + @property + def description(self) -> str: + return "List files and directories in a given path." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Directory path to list", + "default": ".", + }, + "recursive": { + "type": "boolean", + "description": "List recursively", + "default": False, + }, + }, + } + + async def execute(self, path: str = ".", recursive: bool = False, **kwargs: Any) -> str: + try: + dir_path = Path(path) + if not dir_path.is_absolute() and self._workspace: + dir_path = self._workspace / dir_path + + if not dir_path.exists(): + return f"Error: Path not found: {path}" + + if not dir_path.is_dir(): + return f"Error: Not a directory: {path}" + + if recursive: + items = [] + for item in dir_path.rglob("*"): + rel = item.relative_to(dir_path) + prefix = "[D]" if item.is_dir() else "[F]" + items.append(f"{prefix} {rel}") + return "\n".join(sorted(items)) or "(empty)" + else: + items = [] + for item in dir_path.iterdir(): + prefix = "[D]" if item.is_dir() else "[F]" + items.append(f"{prefix} {item.name}") + return "\n".join(sorted(items)) or "(empty)" + except Exception as e: + return f"Error listing directory: {str(e)}" + + +class SearchTool(Tool): + """Search for text in files.""" + + def __init__(self, workspace: Path | None = None): + self._workspace = workspace + + @property + def name(self) -> str: + return "search" + + @property + def description(self) -> str: + return "Search for text patterns in files using regex." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "pattern": {"type": "string", "description": "Regex pattern to search for"}, + "path": { + "type": "string", + "description": "Directory path to search in", + "default": ".", + }, + "file_pattern": { + "type": "string", + "description": "File glob pattern (e.g., *.py)", + "default": "*", + }, + "case_sensitive": { + "type": "boolean", + "description": "Case sensitive search", + "default": True, + }, + }, + "required": ["pattern"], + } + + async def execute( + self, + pattern: str, + path: str = ".", + file_pattern: str = "*", + case_sensitive: bool = True, + **kwargs: Any, + ) -> str: + try: + search_path = Path(path) + if not search_path.is_absolute() and self._workspace: + search_path = self._workspace / search_path + + if not search_path.exists(): + return f"Error: Path not found: {path}" + + flags = 0 if case_sensitive else re.IGNORECASE + regex = re.compile(pattern, flags) + + results = [] + for file_path in search_path.rglob(file_pattern): + if not file_path.is_file(): + continue + try: + content = file_path.read_text(encoding="utf-8") + for i, line in enumerate(content.split("\n"), 1): + if regex.search(line): + results.append(f"{file_path}:{i}: {line.strip()[:100]}") + except Exception: + continue + + if not results: + return f"No matches found for: {pattern}" + + return f"Found {len(results)} matches:\n" + "\n".join(results[:50]) + except Exception as e: + return f"Error searching: {str(e)}" + + +class WebSearchTool(Tool): + """Search the web for information.""" + + def __init__(self): + pass + + @property + def name(self) -> str: + return "web_search" + + @property + def description(self) -> str: + return "Search the web for information using a search engine." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "query": {"type": "string", "description": "Search query"}, + "max_results": { + "type": "integer", + "description": "Maximum number of results", + "default": 5, + }, + }, + "required": ["query"], + } + + async def execute(self, query: str, max_results: int = 5, **kwargs: Any) -> str: + # Placeholder for web search implementation + # In production, this would use a search API (e.g., Google, Bing, SerpAPI) + return f"Web search not implemented yet. Query: {query}" + + +class CalculatorTool(Tool): + """Simple calculator tool.""" + + @property + def name(self) -> str: + return "calculator" + + @property + def description(self) -> str: + return "Evaluate a mathematical expression." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "expression": {"type": "string", "description": "Mathematical expression to evaluate"}, + }, + "required": ["expression"], + } + + async def execute(self, expression: str, **kwargs: Any) -> str: + try: + # Safe evaluation - only allow basic math operators + allowed_chars = set("0123456789+-*/.() ") + if not all(c in allowed_chars for c in expression): + return "Error: Invalid characters in expression" + + result = eval(expression) # Note: In production, use a safer parser + return f"{expression} = {result}" + except Exception as e: + return f"Error evaluating expression: {str(e)}" + + +class GetTimeTool(Tool): + """Get current time.""" + + @property + def name(self) -> str: + return "get_time" + + @property + def description(self) -> str: + return "Get the current date and time." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "timezone": { + "type": "string", + "description": "Timezone (e.g., UTC, Asia/Shanghai)", + "default": "UTC", + }, + }, + } + + async def execute(self, timezone: str = "UTC", **kwargs: Any) -> str: + from datetime import datetime, timezone + + try: + if timezone.upper() != "UTC": + # For non-UTC timezones, return simple result + return f"Timezone '{timezone}' not supported. Current UTC time: {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}" + except Exception: + pass + + now = datetime.now(timezone.utc) + return now.strftime("%Y-%m-%d %H:%M:%S UTC") + + +class BashTool(Tool): + """Execute bash commands.""" + + def __init__(self, workspace: Path | None = None): + self._workspace = workspace + + @property + def name(self) -> str: + return "bash" + + @property + def description(self) -> str: + return "Execute a bash command and return its output." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "command": {"type": "string", "description": "Command to execute"}, + "timeout": { + "type": "integer", + "description": "Timeout in seconds", + "default": 30, + }, + }, + "required": ["command"], + } + + async def execute(self, command: str, timeout: int = 30, **kwargs: Any) -> str: + try: + process = await asyncio.create_subprocess_shell( + command, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + ) + + try: + stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout) + result = [] + if stdout: + result.append(stdout.decode("utf-8")) + if stderr: + result.append(f"STDERR: {stderr.decode('utf-8')}") + return "\n".join(result) or "Command completed with no output" + except asyncio.TimeoutError: + process.kill() + return f"Error: Command timed out after {timeout} seconds" + except Exception as e: + return f"Error executing command: {str(e)}" + + +def get_builtin_tools(workspace: Path | None = None) -> list[Tool]: + """Get list of all built-in tools. + + Args: + workspace: Optional workspace path for file operations + + Returns: + List of Tool instances + """ + return [ + ReadFileTool(workspace), + WriteFileTool(workspace), + ListDirectoryTool(workspace), + SearchTool(workspace), + WebSearchTool(), + CalculatorTool(), + GetTimeTool(), + BashTool(workspace), + ] diff --git a/core/agents/tools/manager.py b/core/agents/tools/manager.py new file mode 100644 index 0000000..1736d7d --- /dev/null +++ b/core/agents/tools/manager.py @@ -0,0 +1,108 @@ +"""Tool manager for loading and managing tools.""" + +import logging +from pathlib import Path +from typing import Any + +from nanobot.agent.tools.registry import ToolRegistry + +from agents.tools.builtin import get_builtin_tools + +logger = logging.getLogger(__name__) + + +class ToolManager: + """Manages tools for the agent.""" + + def __init__(self, workspace: Path | None = None): + """Initialize tool manager. + + Args: + workspace: Optional workspace path + """ + self.workspace = workspace + self.registry = ToolRegistry() + self._load_builtin_tools() + + def _load_builtin_tools(self) -> None: + """Load all built-in tools.""" + tools = get_builtin_tools(self.workspace) + for tool in tools: + self.registry.register(tool) + logger.info(f"Loaded {len(tools)} built-in tools") + + def register_tool(self, tool: Any) -> None: + """Register a custom tool. + + Args: + tool: Tool instance to register + """ + self.registry.register(tool) + logger.info(f"Registered tool: {tool.name}") + + def unregister_tool(self, name: str) -> None: + """Unregister a tool. + + Args: + name: Tool name to unregister + """ + self.registry.unregister(name) + logger.info(f"Unregistered tool: {name}") + + def get_tool(self, name: str) -> Any: + """Get a tool by name. + + Args: + name: Tool name + + Returns: + Tool instance or None + """ + return self.registry.get(name) + + def has_tool(self, name: str) -> bool: + """Check if a tool is registered. + + Args: + name: Tool name + + Returns: + True if tool exists + """ + return self.registry.has(name) + + def list_tools(self) -> list[str]: + """List all registered tool names. + + Returns: + List of tool names + """ + return self.registry.tool_names + + def get_tool_definitions(self) -> list[dict[str, Any]]: + """Get all tool definitions in OpenAI format. + + Returns: + List of tool schemas + """ + return self.registry.get_definitions() + + async def execute_tool(self, name: str, params: dict[str, Any]) -> str: + """Execute a tool by name. + + Args: + name: Tool name + params: Tool parameters + + Returns: + Tool execution result + """ + return await self.registry.execute(name, params) + + def __len__(self) -> int: + """Get number of registered tools.""" + return len(self.registry) + + def __contains__(self, name: str) -> bool: + """Check if tool is registered.""" + return name in self.registry diff --git a/core/agents/tools/sync.py b/core/agents/tools/sync.py new file mode 100644 index 0000000..cfc7ecd --- /dev/null +++ b/core/agents/tools/sync.py @@ -0,0 +1,107 @@ +"""Tool synchronization between Python Agent and Go backend.""" + +import asyncio +import logging +from typing import Any + +import aiohttp + +logger = logging.getLogger(__name__) + + +class ToolSyncClient: + """Client for syncing tools to Go backend.""" + + def __init__(self, base_url: str, agent_id: str = "default"): + """Initialize tool sync client. + + Args: + base_url: Go backend base URL + agent_id: Agent ID + """ + self.base_url = base_url.rstrip("/") + self.agent_id = agent_id + self._session = None + + async def _get_session(self) -> aiohttp.ClientSession: + """Get or create aiohttp session.""" + if self._session is None or self._session.closed: + self._session = aiohttp.ClientSession() + return self._session + + async def close(self) -> None: + """Close the session.""" + if self._session and not self._session.closed: + await self._session.close() + + async def sync_tools( + self, + tools: list[dict[str, Any]], + ) -> tuple[int, str]: + """Sync tools to Go backend. + + Args: + tools: List of tool definitions + + Returns: + Tuple of (synced_count, message) + """ + url = f"{self.base_url}/tool/sync-from-python" + + # Transform tools to match Go backend format + python_tools = [] + for tool in tools: + func = tool.get("function", {}) + python_tools.append({ + "name": func.get("name"), + "description": func.get("description"), + "parameters": func.get("parameters", "{}"), + "category": "python", # Default category for Python tools + }) + + payload = {"tools": python_tools} + + try: + session = await self._get_session() + async with session.post(url, json=payload) as response: + if response.status == 200: + result = await response.json() + count = result.get("synced_count", 0) + return count, f"Synced {count} tools successfully" + else: + text = await response.text() + return 0, f"Failed to sync tools: {response.status} - {text}" + except Exception as e: + logger.error(f"Error syncing tools: {e}") + return 0, f"Error syncing tools: {e}" + + +async def sync_registry_tools( + registry, + base_url: str, + agent_id: str = "default", +) -> tuple[int, str]: + """Sync tools from a ToolRegistry to Go backend. + + Args: + registry: ToolRegistry instance + base_url: Go backend base URL + agent_id: Agent ID + + Returns: + Tuple of (synced_count, message) + """ + client = ToolSyncClient(base_url, agent_id) + + try: + # Get all tool definitions + tools = registry.get_definitions() + + if not tools: + return 0, "No tools to sync" + + # Sync tools + count, message = await client.sync_tools(tools) + return count, message + finally: + await client.close() diff --git a/core/nanobot/.dockerignore b/core/nanobot/.dockerignore new file mode 100644 index 0000000..020b9ec --- /dev/null +++ b/core/nanobot/.dockerignore @@ -0,0 +1,13 @@ +__pycache__ +*.pyc +*.pyo +*.pyd +*.egg-info +dist/ +build/ +.git +.env +.assets +node_modules/ +bridge/dist/ +workspace/ diff --git a/core/nanobot/.gitignore b/core/nanobot/.gitignore new file mode 100644 index 0000000..c50cab8 --- /dev/null +++ b/core/nanobot/.gitignore @@ -0,0 +1,24 @@ +.worktrees/ +.assets +.env +*.pyc +dist/ +build/ +docs/ +*.egg-info/ +*.egg +*.pyc +*.pyo +*.pyd +*.pyw +*.pyz +*.pywz +*.pyzz +.venv/ +venv/ +__pycache__/ +poetry.lock +.pytest_cache/ +botpy.log +nano.*.save + diff --git a/core/nanobot/COMMUNICATION.md b/core/nanobot/COMMUNICATION.md new file mode 100644 index 0000000..84c25f5 --- /dev/null +++ b/core/nanobot/COMMUNICATION.md @@ -0,0 +1,5 @@ +We provide QR codes for joining the HKUDS discussion groups on **WeChat** and **Feishu**. + +You can join by scanning the QR codes below: + +WeChat QR Code \ No newline at end of file diff --git a/core/nanobot/Dockerfile b/core/nanobot/Dockerfile new file mode 100644 index 0000000..8132747 --- /dev/null +++ b/core/nanobot/Dockerfile @@ -0,0 +1,40 @@ +FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim + +# Install Node.js 20 for the WhatsApp bridge +RUN apt-get update && \ + apt-get install -y --no-install-recommends curl ca-certificates gnupg git && \ + mkdir -p /etc/apt/keyrings && \ + curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \ + echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && \ + apt-get update && \ + apt-get install -y --no-install-recommends nodejs && \ + apt-get purge -y gnupg && \ + apt-get autoremove -y && \ + rm -rf /var/lib/apt/lists/* + +WORKDIR /app + +# Install Python dependencies first (cached layer) +COPY pyproject.toml README.md LICENSE ./ +RUN mkdir -p nanobot bridge && touch nanobot/__init__.py && \ + uv pip install --system --no-cache . && \ + rm -rf nanobot bridge + +# Copy the full source and install +COPY nanobot/ nanobot/ +COPY bridge/ bridge/ +RUN uv pip install --system --no-cache . + +# Build the WhatsApp bridge +WORKDIR /app/bridge +RUN npm install && npm run build +WORKDIR /app + +# Create config directory +RUN mkdir -p /root/.nanobot + +# Gateway default port +EXPOSE 18790 + +ENTRYPOINT ["nanobot"] +CMD ["status"] diff --git a/core/nanobot/LICENSE b/core/nanobot/LICENSE new file mode 100644 index 0000000..24bdacc --- /dev/null +++ b/core/nanobot/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 nanobot contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/core/nanobot/README.md b/core/nanobot/README.md new file mode 100644 index 0000000..8dba2d7 --- /dev/null +++ b/core/nanobot/README.md @@ -0,0 +1,1321 @@ +
+ nanobot +

nanobot: Ultra-Lightweight Personal AI Assistant

+

+ PyPI + Downloads + Python + License + Feishu + WeChat + Discord +

+
+ +🐈 **nanobot** is an **ultra-lightweight** personal AI assistant inspired by [OpenClaw](https://github.com/openclaw/openclaw). + +⚡️ Delivers core agent functionality with **99% fewer lines of code** than OpenClaw. + +📏 Real-time line count: run `bash core_agent_lines.sh` to verify anytime. + +## 📢 News + +- **2026-03-08** 🚀 Released **v0.1.4.post4** — a reliability-packed release with safer defaults, better multi-instance support, sturdier MCP, and major channel and provider improvements. Please see [release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.1.4.post4) for details. +- **2026-03-07** 🚀 Azure OpenAI provider, WhatsApp media, QQ group chats, and more Telegram/Feishu polish. +- **2026-03-06** 🪄 Lighter providers, smarter media handling, and sturdier memory and CLI compatibility. +- **2026-03-05** ⚡️ Telegram draft streaming, MCP SSE support, and broader channel reliability fixes. +- **2026-03-04** 🛠️ Dependency cleanup, safer file reads, and another round of test and Cron fixes. +- **2026-03-03** 🧠 Cleaner user-message merging, safer multimodal saves, and stronger Cron guards. +- **2026-03-02** 🛡️ Safer default access control, sturdier Cron reloads, and cleaner Matrix media handling. +- **2026-03-01** 🌐 Web proxy support, smarter Cron reminders, and Feishu rich-text parsing improvements. +- **2026-02-28** 🚀 Released **v0.1.4.post3** — cleaner context, hardened session history, and smarter agent. Please see [release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.1.4.post3) for details. +- **2026-02-27** 🧠 Experimental thinking mode support, DingTalk media messages, Feishu and QQ channel fixes. +- **2026-02-26** 🛡️ Session poisoning fix, WhatsApp dedup, Windows path guard, Mistral compatibility. + +
+Earlier news + +- **2026-02-25** 🧹 New Matrix channel, cleaner session context, auto workspace template sync. +- **2026-02-24** 🚀 Released **v0.1.4.post2** — a reliability-focused release with a redesigned heartbeat, prompt cache optimization, and hardened provider & channel stability. See [release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.1.4.post2) for details. +- **2026-02-23** 🔧 Virtual tool-call heartbeat, prompt cache optimization, Slack mrkdwn fixes. +- **2026-02-22** 🛡️ Slack thread isolation, Discord typing fix, agent reliability improvements. +- **2026-02-21** 🎉 Released **v0.1.4.post1** — new providers, media support across channels, and major stability improvements. See [release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.1.4.post1) for details. +- **2026-02-20** 🐦 Feishu now receives multimodal files from users. More reliable memory under the hood. +- **2026-02-19** ✨ Slack now sends files, Discord splits long messages, and subagents work in CLI mode. +- **2026-02-18** ⚡️ nanobot now supports VolcEngine, MCP custom auth headers, and Anthropic prompt caching. +- **2026-02-17** 🎉 Released **v0.1.4** — MCP support, progress streaming, new providers, and multiple channel improvements. Please see [release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.1.4) for details. +- **2026-02-16** 🦞 nanobot now integrates a [ClawHub](https://clawhub.ai) skill — search and install public agent skills. +- **2026-02-15** 🔑 nanobot now supports OpenAI Codex provider with OAuth login support. +- **2026-02-14** 🔌 nanobot now supports MCP! See [MCP section](#mcp-model-context-protocol) for details. +- **2026-02-13** 🎉 Released **v0.1.3.post7** — includes security hardening and multiple improvements. **Please upgrade to the latest version to address security issues**. See [release notes](https://github.com/HKUDS/nanobot/releases/tag/v0.1.3.post7) for more details. +- **2026-02-12** 🧠 Redesigned memory system — Less code, more reliable. Join the [discussion](https://github.com/HKUDS/nanobot/discussions/566) about it! +- **2026-02-11** ✨ Enhanced CLI experience and added MiniMax support! +- **2026-02-10** 🎉 Released **v0.1.3.post6** with improvements! Check the updates [notes](https://github.com/HKUDS/nanobot/releases/tag/v0.1.3.post6) and our [roadmap](https://github.com/HKUDS/nanobot/discussions/431). +- **2026-02-09** 💬 Added Slack, Email, and QQ support — nanobot now supports multiple chat platforms! +- **2026-02-08** 🔧 Refactored Providers—adding a new LLM provider now takes just 2 simple steps! Check [here](#providers). +- **2026-02-07** 🚀 Released **v0.1.3.post5** with Qwen support & several key improvements! Check [here](https://github.com/HKUDS/nanobot/releases/tag/v0.1.3.post5) for details. +- **2026-02-06** ✨ Added Moonshot/Kimi provider, Discord integration, and enhanced security hardening! +- **2026-02-05** ✨ Added Feishu channel, DeepSeek provider, and enhanced scheduled tasks support! +- **2026-02-04** 🚀 Released **v0.1.3.post4** with multi-provider & Docker support! Check [here](https://github.com/HKUDS/nanobot/releases/tag/v0.1.3.post4) for details. +- **2026-02-03** ⚡ Integrated vLLM for local LLM support and improved natural language task scheduling! +- **2026-02-02** 🎉 nanobot officially launched! Welcome to try 🐈 nanobot! + +
+ +## Key Features of nanobot: + +🪶 **Ultra-Lightweight**: Just ~4,000 lines of core agent code — 99% smaller than Clawdbot. + +🔬 **Research-Ready**: Clean, readable code that's easy to understand, modify, and extend for research. + +⚡️ **Lightning Fast**: Minimal footprint means faster startup, lower resource usage, and quicker iterations. + +💎 **Easy-to-Use**: One-click to deploy and you're ready to go. + +## 🏗️ Architecture + +

+ nanobot architecture +

+ +## Table of Contents + +- [News](#-news) +- [Key Features](#key-features-of-nanobot) +- [Architecture](#️-architecture) +- [Features](#-features) +- [Install](#-install) +- [Quick Start](#-quick-start) +- [Chat Apps](#-chat-apps) +- [Agent Social Network](#-agent-social-network) +- [Configuration](#️-configuration) +- [Multiple Instances](#-multiple-instances) +- [CLI Reference](#-cli-reference) +- [Docker](#-docker) +- [Linux Service](#-linux-service) +- [Project Structure](#-project-structure) +- [Contribute & Roadmap](#-contribute--roadmap) +- [Star History](#-star-history) + +## ✨ Features + + + + + + + + + + + + + + + + + + + + +

📈 24/7 Real-Time Market Analysis

🚀 Full-Stack Software Engineer

📅 Smart Daily Routine Manager

📚 Personal Knowledge Assistant

Discovery • Insights • TrendsDevelop • Deploy • ScaleSchedule • Automate • OrganizeLearn • Memory • Reasoning
+ +## 📦 Install + +**Install from source** (latest features, recommended for development) + +```bash +git clone https://github.com/HKUDS/nanobot.git +cd nanobot +pip install -e . +``` + +**Install with [uv](https://github.com/astral-sh/uv)** (stable, fast) + +```bash +uv tool install nanobot-ai +``` + +**Install from PyPI** (stable) + +```bash +pip install nanobot-ai +``` + +### Update to latest version + +**PyPI / pip** + +```bash +pip install -U nanobot-ai +nanobot --version +``` + +**uv** + +```bash +uv tool upgrade nanobot-ai +nanobot --version +``` + +**Using WhatsApp?** Rebuild the local bridge after upgrading: + +```bash +rm -rf ~/.nanobot/bridge +nanobot channels login +``` + +## 🚀 Quick Start + +> [!TIP] +> Set your API key in `~/.nanobot/config.json`. +> Get API keys: [OpenRouter](https://openrouter.ai/keys) (Global) · [Brave Search](https://brave.com/search/api/) (optional, for web search) + +**1. Initialize** + +```bash +nanobot onboard +``` + +**2. Configure** (`~/.nanobot/config.json`) + +Add or merge these **two parts** into your config (other options have defaults). + +*Set your API key* (e.g. OpenRouter, recommended for global users): +```json +{ + "providers": { + "openrouter": { + "apiKey": "sk-or-v1-xxx" + } + } +} +``` + +*Set your model* (optionally pin a provider — defaults to auto-detection): +```json +{ + "agents": { + "defaults": { + "model": "anthropic/claude-opus-4-5", + "provider": "openrouter" + } + } +} +``` + +**3. Chat** + +```bash +nanobot agent +``` + +That's it! You have a working AI assistant in 2 minutes. + +## 💬 Chat Apps + +Connect nanobot to your favorite chat platform. + +| Channel | What you need | +|---------|---------------| +| **Telegram** | Bot token from @BotFather | +| **Discord** | Bot token + Message Content intent | +| **WhatsApp** | QR code scan | +| **Feishu** | App ID + App Secret | +| **Mochat** | Claw token (auto-setup available) | +| **DingTalk** | App Key + App Secret | +| **Slack** | Bot token + App-Level token | +| **Email** | IMAP/SMTP credentials | +| **QQ** | App ID + App Secret | +| **Wecom** | Bot ID + Bot Secret | + +
+Telegram (Recommended) + +**1. Create a bot** +- Open Telegram, search `@BotFather` +- Send `/newbot`, follow prompts +- Copy the token + +**2. Configure** + +```json +{ + "channels": { + "telegram": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allowFrom": ["YOUR_USER_ID"] + } + } +} +``` + +> You can find your **User ID** in Telegram settings. It is shown as `@yourUserId`. +> Copy this value **without the `@` symbol** and paste it into the config file. + + +**3. Run** + +```bash +nanobot gateway +``` + +
+ +
+Mochat (Claw IM) + +Uses **Socket.IO WebSocket** by default, with HTTP polling fallback. + +**1. Ask nanobot to set up Mochat for you** + +Simply send this message to nanobot (replace `xxx@xxx` with your real email): + +``` +Read https://raw.githubusercontent.com/HKUDS/MoChat/refs/heads/main/skills/nanobot/skill.md and register on MoChat. My Email account is xxx@xxx Bind me as your owner and DM me on MoChat. +``` + +nanobot will automatically register, configure `~/.nanobot/config.json`, and connect to Mochat. + +**2. Restart gateway** + +```bash +nanobot gateway +``` + +That's it — nanobot handles the rest! + +
+ +
+Manual configuration (advanced) + +If you prefer to configure manually, add the following to `~/.nanobot/config.json`: + +> Keep `claw_token` private. It should only be sent in `X-Claw-Token` header to your Mochat API endpoint. + +```json +{ + "channels": { + "mochat": { + "enabled": true, + "base_url": "https://mochat.io", + "socket_url": "https://mochat.io", + "socket_path": "/socket.io", + "claw_token": "claw_xxx", + "agent_user_id": "6982abcdef", + "sessions": ["*"], + "panels": ["*"], + "reply_delay_mode": "non-mention", + "reply_delay_ms": 120000 + } + } +} +``` + + + +
+ +
+ +
+Discord + +**1. Create a bot** +- Go to https://discord.com/developers/applications +- Create an application → Bot → Add Bot +- Copy the bot token + +**2. Enable intents** +- In the Bot settings, enable **MESSAGE CONTENT INTENT** +- (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data + +**3. Get your User ID** +- Discord Settings → Advanced → enable **Developer Mode** +- Right-click your avatar → **Copy User ID** + +**4. Configure** + +```json +{ + "channels": { + "discord": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allowFrom": ["YOUR_USER_ID"], + "groupPolicy": "mention" + } + } +} +``` + +> `groupPolicy` controls how the bot responds in group channels: +> - `"mention"` (default) — Only respond when @mentioned +> - `"open"` — Respond to all messages +> DMs always respond when the sender is in `allowFrom`. + +**5. Invite the bot** +- OAuth2 → URL Generator +- Scopes: `bot` +- Bot Permissions: `Send Messages`, `Read Message History` +- Open the generated invite URL and add the bot to your server + +**6. Run** + +```bash +nanobot gateway +``` + +
+ +
+Matrix (Element) + +Install Matrix dependencies first: + +```bash +pip install nanobot-ai[matrix] +``` + +**1. Create/choose a Matrix account** + +- Create or reuse a Matrix account on your homeserver (for example `matrix.org`). +- Confirm you can log in with Element. + +**2. Get credentials** + +- You need: + - `userId` (example: `@nanobot:matrix.org`) + - `accessToken` + - `deviceId` (recommended so sync tokens can be restored across restarts) +- You can obtain these from your homeserver login API (`/_matrix/client/v3/login`) or from your client's advanced session settings. + +**3. Configure** + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "homeserver": "https://matrix.org", + "userId": "@nanobot:matrix.org", + "accessToken": "syt_xxx", + "deviceId": "NANOBOT01", + "e2eeEnabled": true, + "allowFrom": ["@your_user:matrix.org"], + "groupPolicy": "open", + "groupAllowFrom": [], + "allowRoomMentions": false, + "maxMediaBytes": 20971520 + } + } +} +``` + +> Keep a persistent `matrix-store` and stable `deviceId` — encrypted session state is lost if these change across restarts. + +| Option | Description | +|--------|-------------| +| `allowFrom` | User IDs allowed to interact. Empty denies all; use `["*"]` to allow everyone. | +| `groupPolicy` | `open` (default), `mention`, or `allowlist`. | +| `groupAllowFrom` | Room allowlist (used when policy is `allowlist`). | +| `allowRoomMentions` | Accept `@room` mentions in mention mode. | +| `e2eeEnabled` | E2EE support (default `true`). Set `false` for plaintext-only. | +| `maxMediaBytes` | Max attachment size (default `20MB`). Set `0` to block all media. | + + + + +**4. Run** + +```bash +nanobot gateway +``` + +
+ +
+WhatsApp + +Requires **Node.js ≥18**. + +**1. Link device** + +```bash +nanobot channels login +# Scan QR with WhatsApp → Settings → Linked Devices +``` + +**2. Configure** + +```json +{ + "channels": { + "whatsapp": { + "enabled": true, + "allowFrom": ["+1234567890"] + } + } +} +``` + +**3. Run** (two terminals) + +```bash +# Terminal 1 +nanobot channels login + +# Terminal 2 +nanobot gateway +``` + +> WhatsApp bridge updates are not applied automatically for existing installations. +> After upgrading nanobot, rebuild the local bridge with: +> `rm -rf ~/.nanobot/bridge && nanobot channels login` + +
+ +
+Feishu (飞书) + +Uses **WebSocket** long connection — no public IP required. + +**1. Create a Feishu bot** +- Visit [Feishu Open Platform](https://open.feishu.cn/app) +- Create a new app → Enable **Bot** capability +- **Permissions**: Add `im:message` (send messages) and `im:message.p2p_msg:readonly` (receive messages) +- **Events**: Add `im.message.receive_v1` (receive messages) + - Select **Long Connection** mode (requires running nanobot first to establish connection) +- Get **App ID** and **App Secret** from "Credentials & Basic Info" +- Publish the app + +**2. Configure** + +```json +{ + "channels": { + "feishu": { + "enabled": true, + "appId": "cli_xxx", + "appSecret": "xxx", + "encryptKey": "", + "verificationToken": "", + "allowFrom": ["ou_YOUR_OPEN_ID"] + } + } +} +``` + +> `encryptKey` and `verificationToken` are optional for Long Connection mode. +> `allowFrom`: Add your open_id (find it in nanobot logs when you message the bot). Use `["*"]` to allow all users. + +**3. Run** + +```bash +nanobot gateway +``` + +> [!TIP] +> Feishu uses WebSocket to receive messages — no webhook or public IP needed! + +
+ +
+QQ (QQ单聊) + +Uses **botpy SDK** with WebSocket — no public IP required. Currently supports **private messages only**. + +**1. Register & create bot** +- Visit [QQ Open Platform](https://q.qq.com) → Register as a developer (personal or enterprise) +- Create a new bot application +- Go to **开发设置 (Developer Settings)** → copy **AppID** and **AppSecret** + +**2. Set up sandbox for testing** +- In the bot management console, find **沙箱配置 (Sandbox Config)** +- Under **在消息列表配置**, click **添加成员** and add your own QQ number +- Once added, scan the bot's QR code with mobile QQ → open the bot profile → tap "发消息" to start chatting + +**3. Configure** + +> - `allowFrom`: Add your openid (find it in nanobot logs when you message the bot). Use `["*"]` for public access. +> - For production: submit a review in the bot console and publish. See [QQ Bot Docs](https://bot.q.qq.com/wiki/) for the full publishing flow. + +```json +{ + "channels": { + "qq": { + "enabled": true, + "appId": "YOUR_APP_ID", + "secret": "YOUR_APP_SECRET", + "allowFrom": ["YOUR_OPENID"] + } + } +} +``` + +**4. Run** + +```bash +nanobot gateway +``` + +Now send a message to the bot from QQ — it should respond! + +
+ +
+DingTalk (钉钉) + +Uses **Stream Mode** — no public IP required. + +**1. Create a DingTalk bot** +- Visit [DingTalk Open Platform](https://open-dev.dingtalk.com/) +- Create a new app -> Add **Robot** capability +- **Configuration**: + - Toggle **Stream Mode** ON +- **Permissions**: Add necessary permissions for sending messages +- Get **AppKey** (Client ID) and **AppSecret** (Client Secret) from "Credentials" +- Publish the app + +**2. Configure** + +```json +{ + "channels": { + "dingtalk": { + "enabled": true, + "clientId": "YOUR_APP_KEY", + "clientSecret": "YOUR_APP_SECRET", + "allowFrom": ["YOUR_STAFF_ID"] + } + } +} +``` + +> `allowFrom`: Add your staff ID. Use `["*"]` to allow all users. + +**3. Run** + +```bash +nanobot gateway +``` + +
+ +
+Slack + +Uses **Socket Mode** — no public URL required. + +**1. Create a Slack app** +- Go to [Slack API](https://api.slack.com/apps) → **Create New App** → "From scratch" +- Pick a name and select your workspace + +**2. Configure the app** +- **Socket Mode**: Toggle ON → Generate an **App-Level Token** with `connections:write` scope → copy it (`xapp-...`) +- **OAuth & Permissions**: Add bot scopes: `chat:write`, `reactions:write`, `app_mentions:read` +- **Event Subscriptions**: Toggle ON → Subscribe to bot events: `message.im`, `message.channels`, `app_mention` → Save Changes +- **App Home**: Scroll to **Show Tabs** → Enable **Messages Tab** → Check **"Allow users to send Slash commands and messages from the messages tab"** +- **Install App**: Click **Install to Workspace** → Authorize → copy the **Bot Token** (`xoxb-...`) + +**3. Configure nanobot** + +```json +{ + "channels": { + "slack": { + "enabled": true, + "botToken": "xoxb-...", + "appToken": "xapp-...", + "allowFrom": ["YOUR_SLACK_USER_ID"], + "groupPolicy": "mention" + } + } +} +``` + +**4. Run** + +```bash +nanobot gateway +``` + +DM the bot directly or @mention it in a channel — it should respond! + +> [!TIP] +> - `groupPolicy`: `"mention"` (default — respond only when @mentioned), `"open"` (respond to all channel messages), or `"allowlist"` (restrict to specific channels). +> - DM policy defaults to open. Set `"dm": {"enabled": false}` to disable DMs. + +
+ +
+Email + +Give nanobot its own email account. It polls **IMAP** for incoming mail and replies via **SMTP** — like a personal email assistant. + +**1. Get credentials (Gmail example)** +- Create a dedicated Gmail account for your bot (e.g. `my-nanobot@gmail.com`) +- Enable 2-Step Verification → Create an [App Password](https://myaccount.google.com/apppasswords) +- Use this app password for both IMAP and SMTP + +**2. Configure** + +> - `consentGranted` must be `true` to allow mailbox access. This is a safety gate — set `false` to fully disable. +> - `allowFrom`: Add your email address. Use `["*"]` to accept emails from anyone. +> - `smtpUseTls` and `smtpUseSsl` default to `true` / `false` respectively, which is correct for Gmail (port 587 + STARTTLS). No need to set them explicitly. +> - Set `"autoReplyEnabled": false` if you only want to read/analyze emails without sending automatic replies. + +```json +{ + "channels": { + "email": { + "enabled": true, + "consentGranted": true, + "imapHost": "imap.gmail.com", + "imapPort": 993, + "imapUsername": "my-nanobot@gmail.com", + "imapPassword": "your-app-password", + "smtpHost": "smtp.gmail.com", + "smtpPort": 587, + "smtpUsername": "my-nanobot@gmail.com", + "smtpPassword": "your-app-password", + "fromAddress": "my-nanobot@gmail.com", + "allowFrom": ["your-real-email@gmail.com"] + } + } +} +``` + + +**3. Run** + +```bash +nanobot gateway +``` + +
+ +
+Wecom (企业微信) + +> Here we use [wecom-aibot-sdk-python](https://github.com/chengyongru/wecom_aibot_sdk) (community Python version of the official [@wecom/aibot-node-sdk](https://www.npmjs.com/package/@wecom/aibot-node-sdk)). +> +> Uses **WebSocket** long connection — no public IP required. + +**1. Install the optional dependency** + +```bash +pip install nanobot-ai[wecom] +``` + +**2. Create a WeCom AI Bot** + +Go to the WeCom admin console → Intelligent Robot → Create Robot → select **API mode** with **long connection**. Copy the Bot ID and Secret. + +**3. Configure** + +```json +{ + "channels": { + "wecom": { + "enabled": true, + "botId": "your_bot_id", + "secret": "your_bot_secret", + "allowFrom": ["your_id"] + } + } +} +``` + +**4. Run** + +```bash +nanobot gateway +``` + +
+ +## 🌐 Agent Social Network + +🐈 nanobot is capable of linking to the agent social network (agent community). **Just send one message and your nanobot joins automatically!** + +| Platform | How to Join (send this message to your bot) | +|----------|-------------| +| [**Moltbook**](https://www.moltbook.com/) | `Read https://moltbook.com/skill.md and follow the instructions to join Moltbook` | +| [**ClawdChat**](https://clawdchat.ai/) | `Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat` | + +Simply send the command above to your nanobot (via CLI or any chat channel), and it will handle the rest. + +## ⚙️ Configuration + +Config file: `~/.nanobot/config.json` + +### Providers + +> [!TIP] +> - **Groq** provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed. +> - **Zhipu Coding Plan**: If you're on Zhipu's coding plan, set `"apiBase": "https://open.bigmodel.cn/api/coding/paas/v4"` in your zhipu provider config. +> - **MiniMax (Mainland China)**: If your API key is from MiniMax's mainland China platform (minimaxi.com), set `"apiBase": "https://api.minimaxi.com/v1"` in your minimax provider config. +> - **VolcEngine Coding Plan**: If you're on VolcEngine's coding plan, set `"apiBase": "https://ark.cn-beijing.volces.com/api/coding/v3"` in your volcengine provider config. +> - **Alibaba Cloud Coding Plan**: If you're on the Alibaba Cloud Coding Plan (BaiLian), set `"apiBase": "https://coding.dashscope.aliyuncs.com/v1"` in your dashscope provider config. + +| Provider | Purpose | Get API Key | +|----------|---------|-------------| +| `custom` | Any OpenAI-compatible endpoint (direct, no LiteLLM) | — | +| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | +| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | +| `azure_openai` | LLM (Azure OpenAI) | [portal.azure.com](https://portal.azure.com) | +| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | +| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | +| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | +| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | +| `minimax` | LLM (MiniMax direct) | [platform.minimaxi.com](https://platform.minimaxi.com) | +| `aihubmix` | LLM (API gateway, access to all models) | [aihubmix.com](https://aihubmix.com) | +| `siliconflow` | LLM (SiliconFlow/硅基流动) | [siliconflow.cn](https://siliconflow.cn) | +| `volcengine` | LLM (VolcEngine/火山引擎) | [volcengine.com](https://www.volcengine.com) | +| `dashscope` | LLM (Qwen) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `moonshot` | LLM (Moonshot/Kimi) | [platform.moonshot.cn](https://platform.moonshot.cn) | +| `zhipu` | LLM (Zhipu GLM) | [open.bigmodel.cn](https://open.bigmodel.cn) | +| `ollama` | LLM (local, Ollama) | — | +| `vllm` | LLM (local, any OpenAI-compatible server) | — | +| `openai_codex` | LLM (Codex, OAuth) | `nanobot provider login openai-codex` | +| `github_copilot` | LLM (GitHub Copilot, OAuth) | `nanobot provider login github-copilot` | + +
+OpenAI Codex (OAuth) + +Codex uses OAuth instead of API keys. Requires a ChatGPT Plus or Pro account. + +**1. Login:** +```bash +nanobot provider login openai-codex +``` + +**2. Set model** (merge into `~/.nanobot/config.json`): +```json +{ + "agents": { + "defaults": { + "model": "openai-codex/gpt-5.1-codex" + } + } +} +``` + +**3. Chat:** +```bash +nanobot agent -m "Hello!" + +# Target a specific workspace/config locally +nanobot agent -c ~/.nanobot-telegram/config.json -m "Hello!" + +# One-off workspace override on top of that config +nanobot agent -c ~/.nanobot-telegram/config.json -w /tmp/nanobot-telegram-test -m "Hello!" +``` + +> Docker users: use `docker run -it` for interactive OAuth login. + +
+ +
+Custom Provider (Any OpenAI-compatible API) + +Connects directly to any OpenAI-compatible endpoint — LM Studio, llama.cpp, Together AI, Fireworks, Azure OpenAI, or any self-hosted server. Bypasses LiteLLM; model name is passed as-is. + +```json +{ + "providers": { + "custom": { + "apiKey": "your-api-key", + "apiBase": "https://api.your-provider.com/v1" + } + }, + "agents": { + "defaults": { + "model": "your-model-name" + } + } +} +``` + +> For local servers that don't require a key, set `apiKey` to any non-empty string (e.g. `"no-key"`). + +
+ +
+Ollama (local) + +Run a local model with Ollama, then add to config: + +**1. Start Ollama** (example): +```bash +ollama run llama3.2 +``` + +**2. Add to config** (partial — merge into `~/.nanobot/config.json`): +```json +{ + "providers": { + "ollama": { + "apiBase": "http://localhost:11434" + } + }, + "agents": { + "defaults": { + "provider": "ollama", + "model": "llama3.2" + } + } +} +``` + +> `provider: "auto"` also works when `providers.ollama.apiBase` is configured, but setting `"provider": "ollama"` is the clearest option. + +
+ +
+vLLM (local / OpenAI-compatible) + +Run your own model with vLLM or any OpenAI-compatible server, then add to config: + +**1. Start the server** (example): +```bash +vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000 +``` + +**2. Add to config** (partial — merge into `~/.nanobot/config.json`): + +*Provider (key can be any non-empty string for local):* +```json +{ + "providers": { + "vllm": { + "apiKey": "dummy", + "apiBase": "http://localhost:8000/v1" + } + } +} +``` + +*Model:* +```json +{ + "agents": { + "defaults": { + "model": "meta-llama/Llama-3.1-8B-Instruct" + } + } +} +``` + +
+ +
+Adding a New Provider (Developer Guide) + +nanobot uses a **Provider Registry** (`nanobot/providers/registry.py`) as the single source of truth. +Adding a new provider only takes **2 steps** — no if-elif chains to touch. + +**Step 1.** Add a `ProviderSpec` entry to `PROVIDERS` in `nanobot/providers/registry.py`: + +```python +ProviderSpec( + name="myprovider", # config field name + keywords=("myprovider", "mymodel"), # model-name keywords for auto-matching + env_key="MYPROVIDER_API_KEY", # env var for LiteLLM + display_name="My Provider", # shown in `nanobot status` + litellm_prefix="myprovider", # auto-prefix: model → myprovider/model + skip_prefixes=("myprovider/",), # don't double-prefix +) +``` + +**Step 2.** Add a field to `ProvidersConfig` in `nanobot/config/schema.py`: + +```python +class ProvidersConfig(BaseModel): + ... + myprovider: ProviderConfig = ProviderConfig() +``` + +That's it! Environment variables, model prefixing, config matching, and `nanobot status` display will all work automatically. + +**Common `ProviderSpec` options:** + +| Field | Description | Example | +|-------|-------------|---------| +| `litellm_prefix` | Auto-prefix model names for LiteLLM | `"dashscope"` → `dashscope/qwen-max` | +| `skip_prefixes` | Don't prefix if model already starts with these | `("dashscope/", "openrouter/")` | +| `env_extras` | Additional env vars to set | `(("ZHIPUAI_API_KEY", "{api_key}"),)` | +| `model_overrides` | Per-model parameter overrides | `(("kimi-k2.5", {"temperature": 1.0}),)` | +| `is_gateway` | Can route any model (like OpenRouter) | `True` | +| `detect_by_key_prefix` | Detect gateway by API key prefix | `"sk-or-"` | +| `detect_by_base_keyword` | Detect gateway by API base URL | `"openrouter"` | +| `strip_model_prefix` | Strip existing prefix before re-prefixing | `True` (for AiHubMix) | + +
+ + +### MCP (Model Context Protocol) + +> [!TIP] +> The config format is compatible with Claude Desktop / Cursor. You can copy MCP server configs directly from any MCP server's README. + +nanobot supports [MCP](https://modelcontextprotocol.io/) — connect external tool servers and use them as native agent tools. + +Add MCP servers to your `config.json`: + +```json +{ + "tools": { + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"] + }, + "my-remote-mcp": { + "url": "https://example.com/mcp/", + "headers": { + "Authorization": "Bearer xxxxx" + } + } + } + } +} +``` + +Two transport modes are supported: + +| Mode | Config | Example | +|------|--------|---------| +| **Stdio** | `command` + `args` | Local process via `npx` / `uvx` | +| **HTTP** | `url` + `headers` (optional) | Remote endpoint (`https://mcp.example.com/sse`) | + +Use `toolTimeout` to override the default 30s per-call timeout for slow servers: + +```json +{ + "tools": { + "mcpServers": { + "my-slow-server": { + "url": "https://example.com/mcp/", + "toolTimeout": 120 + } + } + } +} +``` + +MCP tools are automatically discovered and registered on startup. The LLM can use them alongside built-in tools — no extra configuration needed. + + + + +### Security + +> [!TIP] +> For production deployments, set `"restrictToWorkspace": true` in your config to sandbox the agent. +> In `v0.1.4.post3` and earlier, an empty `allowFrom` allowed all senders. Since `v0.1.4.post4`, empty `allowFrom` denies all access by default. To allow all senders, set `"allowFrom": ["*"]`. + +| Option | Default | Description | +|--------|---------|-------------| +| `tools.restrictToWorkspace` | `false` | When `true`, restricts **all** agent tools (shell, file read/write/edit, list) to the workspace directory. Prevents path traversal and out-of-scope access. | +| `tools.exec.pathAppend` | `""` | Extra directories to append to `PATH` when running shell commands (e.g. `/usr/sbin` for `ufw`). | +| `channels.*.allowFrom` | `[]` (deny all) | Whitelist of user IDs. Empty denies all; use `["*"]` to allow everyone. | + + +## 🧩 Multiple Instances + +Run multiple nanobot instances simultaneously with separate configs and runtime data. Use `--config` as the main entrypoint, and optionally use `--workspace` to override the workspace for a specific run. + +### Quick Start + +```bash +# Instance A - Telegram bot +nanobot gateway --config ~/.nanobot-telegram/config.json + +# Instance B - Discord bot +nanobot gateway --config ~/.nanobot-discord/config.json + +# Instance C - Feishu bot with custom port +nanobot gateway --config ~/.nanobot-feishu/config.json --port 18792 +``` + +### Path Resolution + +When using `--config`, nanobot derives its runtime data directory from the config file location. The workspace still comes from `agents.defaults.workspace` unless you override it with `--workspace`. + +To open a CLI session against one of these instances locally: + +```bash +nanobot agent -c ~/.nanobot-telegram/config.json -m "Hello from Telegram instance" +nanobot agent -c ~/.nanobot-discord/config.json -m "Hello from Discord instance" + +# Optional one-off workspace override +nanobot agent -c ~/.nanobot-telegram/config.json -w /tmp/nanobot-telegram-test +``` + +> `nanobot agent` starts a local CLI agent using the selected workspace/config. It does not attach to or proxy through an already running `nanobot gateway` process. + +| Component | Resolved From | Example | +|-----------|---------------|---------| +| **Config** | `--config` path | `~/.nanobot-A/config.json` | +| **Workspace** | `--workspace` or config | `~/.nanobot-A/workspace/` | +| **Cron Jobs** | config directory | `~/.nanobot-A/cron/` | +| **Media / runtime state** | config directory | `~/.nanobot-A/media/` | + +### How It Works + +- `--config` selects which config file to load +- By default, the workspace comes from `agents.defaults.workspace` in that config +- If you pass `--workspace`, it overrides the workspace from the config file + +### Minimal Setup + +1. Copy your base config into a new instance directory. +2. Set a different `agents.defaults.workspace` for that instance. +3. Start the instance with `--config`. + +Example config: + +```json +{ + "agents": { + "defaults": { + "workspace": "~/.nanobot-telegram/workspace", + "model": "anthropic/claude-sonnet-4-6" + } + }, + "channels": { + "telegram": { + "enabled": true, + "token": "YOUR_TELEGRAM_BOT_TOKEN" + } + }, + "gateway": { + "port": 18790 + } +} +``` + +Start separate instances: + +```bash +nanobot gateway --config ~/.nanobot-telegram/config.json +nanobot gateway --config ~/.nanobot-discord/config.json +``` + +Override workspace for one-off runs when needed: + +```bash +nanobot gateway --config ~/.nanobot-telegram/config.json --workspace /tmp/nanobot-telegram-test +``` + +### Common Use Cases + +- Run separate bots for Telegram, Discord, Feishu, and other platforms +- Keep testing and production instances isolated +- Use different models or providers for different teams +- Serve multiple tenants with separate configs and runtime data + +### Notes + +- Each instance must use a different port if they run at the same time +- Use a different workspace per instance if you want isolated memory, sessions, and skills +- `--workspace` overrides the workspace defined in the config file +- Cron jobs and runtime media/state are derived from the config directory + +## 💻 CLI Reference + +| Command | Description | +|---------|-------------| +| `nanobot onboard` | Initialize config & workspace | +| `nanobot agent -m "..."` | Chat with the agent | +| `nanobot agent -w ` | Chat against a specific workspace | +| `nanobot agent -w -c ` | Chat against a specific workspace/config | +| `nanobot agent` | Interactive chat mode | +| `nanobot agent --no-markdown` | Show plain-text replies | +| `nanobot agent --logs` | Show runtime logs during chat | +| `nanobot gateway` | Start the gateway | +| `nanobot status` | Show status | +| `nanobot provider login openai-codex` | OAuth login for providers | +| `nanobot channels login` | Link WhatsApp (scan QR) | +| `nanobot channels status` | Show channel status | + +Interactive mode exits: `exit`, `quit`, `/exit`, `/quit`, `:q`, or `Ctrl+D`. + +
+Heartbeat (Periodic Tasks) + +The gateway wakes up every 30 minutes and checks `HEARTBEAT.md` in your workspace (`~/.nanobot/workspace/HEARTBEAT.md`). If the file has tasks, the agent executes them and delivers results to your most recently active chat channel. + +**Setup:** edit `~/.nanobot/workspace/HEARTBEAT.md` (created automatically by `nanobot onboard`): + +```markdown +## Periodic Tasks + +- [ ] Check weather forecast and send a summary +- [ ] Scan inbox for urgent emails +``` + +The agent can also manage this file itself — ask it to "add a periodic task" and it will update `HEARTBEAT.md` for you. + +> **Note:** The gateway must be running (`nanobot gateway`) and you must have chatted with the bot at least once so it knows which channel to deliver to. + +
+ +## 🐳 Docker + +> [!TIP] +> The `-v ~/.nanobot:/root/.nanobot` flag mounts your local config directory into the container, so your config and workspace persist across container restarts. + +### Docker Compose + +```bash +docker compose run --rm nanobot-cli onboard # first-time setup +vim ~/.nanobot/config.json # add API keys +docker compose up -d nanobot-gateway # start gateway +``` + +```bash +docker compose run --rm nanobot-cli agent -m "Hello!" # run CLI +docker compose logs -f nanobot-gateway # view logs +docker compose down # stop +``` + +### Docker + +```bash +# Build the image +docker build -t nanobot . + +# Initialize config (first time only) +docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard + +# Edit config on host to add API keys +vim ~/.nanobot/config.json + +# Run gateway (connects to enabled channels, e.g. Telegram/Discord/Mochat) +docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway + +# Or run a single command +docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!" +docker run -v ~/.nanobot:/root/.nanobot --rm nanobot status +``` + +## 🐧 Linux Service + +Run the gateway as a systemd user service so it starts automatically and restarts on failure. + +**1. Find the nanobot binary path:** + +```bash +which nanobot # e.g. /home/user/.local/bin/nanobot +``` + +**2. Create the service file** at `~/.config/systemd/user/nanobot-gateway.service` (replace `ExecStart` path if needed): + +```ini +[Unit] +Description=Nanobot Gateway +After=network.target + +[Service] +Type=simple +ExecStart=%h/.local/bin/nanobot gateway +Restart=always +RestartSec=10 +NoNewPrivileges=yes +ProtectSystem=strict +ReadWritePaths=%h + +[Install] +WantedBy=default.target +``` + +**3. Enable and start:** + +```bash +systemctl --user daemon-reload +systemctl --user enable --now nanobot-gateway +``` + +**Common operations:** + +```bash +systemctl --user status nanobot-gateway # check status +systemctl --user restart nanobot-gateway # restart after config changes +journalctl --user -u nanobot-gateway -f # follow logs +``` + +If you edit the `.service` file itself, run `systemctl --user daemon-reload` before restarting. + +> **Note:** User services only run while you are logged in. To keep the gateway running after logout, enable lingering: +> +> ```bash +> loginctl enable-linger $USER +> ``` + +## 📁 Project Structure + +``` +nanobot/ +├── agent/ # 🧠 Core agent logic +│ ├── loop.py # Agent loop (LLM ↔ tool execution) +│ ├── context.py # Prompt builder +│ ├── memory.py # Persistent memory +│ ├── skills.py # Skills loader +│ ├── subagent.py # Background task execution +│ └── tools/ # Built-in tools (incl. spawn) +├── skills/ # 🎯 Bundled skills (github, weather, tmux...) +├── channels/ # 📱 Chat channel integrations +├── bus/ # 🚌 Message routing +├── cron/ # ⏰ Scheduled tasks +├── heartbeat/ # 💓 Proactive wake-up +├── providers/ # 🤖 LLM providers (OpenRouter, etc.) +├── session/ # 💬 Conversation sessions +├── config/ # ⚙️ Configuration +└── cli/ # 🖥️ Commands +``` + +## 🤝 Contribute & Roadmap + +PRs welcome! The codebase is intentionally small and readable. 🤗 + +**Roadmap** — Pick an item and [open a PR](https://github.com/HKUDS/nanobot/pulls)! + +- [ ] **Multi-modal** — See and hear (images, voice, video) +- [ ] **Long-term memory** — Never forget important context +- [ ] **Better reasoning** — Multi-step planning and reflection +- [ ] **More integrations** — Calendar and more +- [ ] **Self-improvement** — Learn from feedback and mistakes + +### Contributors + + + Contributors + + + +## ⭐ Star History + + + +

+ Thanks for visiting ✨ nanobot!

+ Views +

+ + +

+ nanobot is for educational, research, and technical exchange purposes only +

diff --git a/core/nanobot/SECURITY.md b/core/nanobot/SECURITY.md new file mode 100644 index 0000000..d98adb6 --- /dev/null +++ b/core/nanobot/SECURITY.md @@ -0,0 +1,263 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security vulnerability in nanobot, please report it by: + +1. **DO NOT** open a public GitHub issue +2. Create a private security advisory on GitHub or contact the repository maintainers (xubinrencs@gmail.com) +3. Include: + - Description of the vulnerability + - Steps to reproduce + - Potential impact + - Suggested fix (if any) + +We aim to respond to security reports within 48 hours. + +## Security Best Practices + +### 1. API Key Management + +**CRITICAL**: Never commit API keys to version control. + +```bash +# ✅ Good: Store in config file with restricted permissions +chmod 600 ~/.nanobot/config.json + +# ❌ Bad: Hardcoding keys in code or committing them +``` + +**Recommendations:** +- Store API keys in `~/.nanobot/config.json` with file permissions set to `0600` +- Consider using environment variables for sensitive keys +- Use OS keyring/credential manager for production deployments +- Rotate API keys regularly +- Use separate API keys for development and production + +### 2. Channel Access Control + +**IMPORTANT**: Always configure `allowFrom` lists for production use. + +```json +{ + "channels": { + "telegram": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allowFrom": ["123456789", "987654321"] + }, + "whatsapp": { + "enabled": true, + "allowFrom": ["+1234567890"] + } + } +} +``` + +**Security Notes:** +- In `v0.1.4.post3` and earlier, an empty `allowFrom` allowed all users. Since `v0.1.4.post4`, empty `allowFrom` denies all access by default — set `["*"]` to explicitly allow everyone. +- Get your Telegram user ID from `@userinfobot` +- Use full phone numbers with country code for WhatsApp +- Review access logs regularly for unauthorized access attempts + +### 3. Shell Command Execution + +The `exec` tool can execute shell commands. While dangerous command patterns are blocked, you should: + +- ✅ Review all tool usage in agent logs +- ✅ Understand what commands the agent is running +- ✅ Use a dedicated user account with limited privileges +- ✅ Never run nanobot as root +- ❌ Don't disable security checks +- ❌ Don't run on systems with sensitive data without careful review + +**Blocked patterns:** +- `rm -rf /` - Root filesystem deletion +- Fork bombs +- Filesystem formatting (`mkfs.*`) +- Raw disk writes +- Other destructive operations + +### 4. File System Access + +File operations have path traversal protection, but: + +- ✅ Run nanobot with a dedicated user account +- ✅ Use filesystem permissions to protect sensitive directories +- ✅ Regularly audit file operations in logs +- ❌ Don't give unrestricted access to sensitive files + +### 5. Network Security + +**API Calls:** +- All external API calls use HTTPS by default +- Timeouts are configured to prevent hanging requests +- Consider using a firewall to restrict outbound connections if needed + +**WhatsApp Bridge:** +- The bridge binds to `127.0.0.1:3001` (localhost only, not accessible from external network) +- Set `bridgeToken` in config to enable shared-secret authentication between Python and Node.js +- Keep authentication data in `~/.nanobot/whatsapp-auth` secure (mode 0700) + +### 6. Dependency Security + +**Critical**: Keep dependencies updated! + +```bash +# Check for vulnerable dependencies +pip install pip-audit +pip-audit + +# Update to latest secure versions +pip install --upgrade nanobot-ai +``` + +For Node.js dependencies (WhatsApp bridge): +```bash +cd bridge +npm audit +npm audit fix +``` + +**Important Notes:** +- Keep `litellm` updated to the latest version for security fixes +- We've updated `ws` to `>=8.17.1` to fix DoS vulnerability +- Run `pip-audit` or `npm audit` regularly +- Subscribe to security advisories for nanobot and its dependencies + +### 7. Production Deployment + +For production use: + +1. **Isolate the Environment** + ```bash + # Run in a container or VM + docker run --rm -it python:3.11 + pip install nanobot-ai + ``` + +2. **Use a Dedicated User** + ```bash + sudo useradd -m -s /bin/bash nanobot + sudo -u nanobot nanobot gateway + ``` + +3. **Set Proper Permissions** + ```bash + chmod 700 ~/.nanobot + chmod 600 ~/.nanobot/config.json + chmod 700 ~/.nanobot/whatsapp-auth + ``` + +4. **Enable Logging** + ```bash + # Configure log monitoring + tail -f ~/.nanobot/logs/nanobot.log + ``` + +5. **Use Rate Limiting** + - Configure rate limits on your API providers + - Monitor usage for anomalies + - Set spending limits on LLM APIs + +6. **Regular Updates** + ```bash + # Check for updates weekly + pip install --upgrade nanobot-ai + ``` + +### 8. Development vs Production + +**Development:** +- Use separate API keys +- Test with non-sensitive data +- Enable verbose logging +- Use a test Telegram bot + +**Production:** +- Use dedicated API keys with spending limits +- Restrict file system access +- Enable audit logging +- Regular security reviews +- Monitor for unusual activity + +### 9. Data Privacy + +- **Logs may contain sensitive information** - secure log files appropriately +- **LLM providers see your prompts** - review their privacy policies +- **Chat history is stored locally** - protect the `~/.nanobot` directory +- **API keys are in plain text** - use OS keyring for production + +### 10. Incident Response + +If you suspect a security breach: + +1. **Immediately revoke compromised API keys** +2. **Review logs for unauthorized access** + ```bash + grep "Access denied" ~/.nanobot/logs/nanobot.log + ``` +3. **Check for unexpected file modifications** +4. **Rotate all credentials** +5. **Update to latest version** +6. **Report the incident** to maintainers + +## Security Features + +### Built-in Security Controls + +✅ **Input Validation** +- Path traversal protection on file operations +- Dangerous command pattern detection +- Input length limits on HTTP requests + +✅ **Authentication** +- Allow-list based access control — in `v0.1.4.post3` and earlier empty `allowFrom` allowed all; since `v0.1.4.post4` it denies all (`["*"]` explicitly allows all) +- Failed authentication attempt logging + +✅ **Resource Protection** +- Command execution timeouts (60s default) +- Output truncation (10KB limit) +- HTTP request timeouts (10-30s) + +✅ **Secure Communication** +- HTTPS for all external API calls +- TLS for Telegram API +- WhatsApp bridge: localhost-only binding + optional token auth + +## Known Limitations + +⚠️ **Current Security Limitations:** + +1. **No Rate Limiting** - Users can send unlimited messages (add your own if needed) +2. **Plain Text Config** - API keys stored in plain text (use keyring for production) +3. **No Session Management** - No automatic session expiry +4. **Limited Command Filtering** - Only blocks obvious dangerous patterns +5. **No Audit Trail** - Limited security event logging (enhance as needed) + +## Security Checklist + +Before deploying nanobot: + +- [ ] API keys stored securely (not in code) +- [ ] Config file permissions set to 0600 +- [ ] `allowFrom` lists configured for all channels +- [ ] Running as non-root user +- [ ] File system permissions properly restricted +- [ ] Dependencies updated to latest secure versions +- [ ] Logs monitored for security events +- [ ] Rate limits configured on API providers +- [ ] Backup and disaster recovery plan in place +- [ ] Security review of custom skills/tools + +## Updates + +**Last Updated**: 2026-02-03 + +For the latest security updates and announcements, check: +- GitHub Security Advisories: https://github.com/HKUDS/nanobot/security/advisories +- Release Notes: https://github.com/HKUDS/nanobot/releases + +## License + +See LICENSE file for details. diff --git a/core/nanobot/bridge/package.json b/core/nanobot/bridge/package.json new file mode 100644 index 0000000..e91517c --- /dev/null +++ b/core/nanobot/bridge/package.json @@ -0,0 +1,26 @@ +{ + "name": "nanobot-whatsapp-bridge", + "version": "0.1.0", + "description": "WhatsApp bridge for nanobot using Baileys", + "type": "module", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "start": "node dist/index.js", + "dev": "tsc && node dist/index.js" + }, + "dependencies": { + "@whiskeysockets/baileys": "7.0.0-rc.9", + "ws": "^8.17.1", + "qrcode-terminal": "^0.12.0", + "pino": "^9.0.0" + }, + "devDependencies": { + "@types/node": "^20.14.0", + "@types/ws": "^8.5.10", + "typescript": "^5.4.0" + }, + "engines": { + "node": ">=20.0.0" + } +} diff --git a/core/nanobot/bridge/src/index.ts b/core/nanobot/bridge/src/index.ts new file mode 100644 index 0000000..e8f3db9 --- /dev/null +++ b/core/nanobot/bridge/src/index.ts @@ -0,0 +1,51 @@ +#!/usr/bin/env node +/** + * nanobot WhatsApp Bridge + * + * This bridge connects WhatsApp Web to nanobot's Python backend + * via WebSocket. It handles authentication, message forwarding, + * and reconnection logic. + * + * Usage: + * npm run build && npm start + * + * Or with custom settings: + * BRIDGE_PORT=3001 AUTH_DIR=~/.nanobot/whatsapp npm start + */ + +// Polyfill crypto for Baileys in ESM +import { webcrypto } from 'crypto'; +if (!globalThis.crypto) { + (globalThis as any).crypto = webcrypto; +} + +import { BridgeServer } from './server.js'; +import { homedir } from 'os'; +import { join } from 'path'; + +const PORT = parseInt(process.env.BRIDGE_PORT || '3001', 10); +const AUTH_DIR = process.env.AUTH_DIR || join(homedir(), '.nanobot', 'whatsapp-auth'); +const TOKEN = process.env.BRIDGE_TOKEN || undefined; + +console.log('🐈 nanobot WhatsApp Bridge'); +console.log('========================\n'); + +const server = new BridgeServer(PORT, AUTH_DIR, TOKEN); + +// Handle graceful shutdown +process.on('SIGINT', async () => { + console.log('\n\nShutting down...'); + await server.stop(); + process.exit(0); +}); + +process.on('SIGTERM', async () => { + await server.stop(); + process.exit(0); +}); + +// Start the server +server.start().catch((error) => { + console.error('Failed to start bridge:', error); + process.exit(1); +}); diff --git a/core/nanobot/bridge/src/server.ts b/core/nanobot/bridge/src/server.ts new file mode 100644 index 0000000..7d48f5e --- /dev/null +++ b/core/nanobot/bridge/src/server.ts @@ -0,0 +1,129 @@ +/** + * WebSocket server for Python-Node.js bridge communication. + * Security: binds to 127.0.0.1 only; optional BRIDGE_TOKEN auth. + */ + +import { WebSocketServer, WebSocket } from 'ws'; +import { WhatsAppClient, InboundMessage } from './whatsapp.js'; + +interface SendCommand { + type: 'send'; + to: string; + text: string; +} + +interface BridgeMessage { + type: 'message' | 'status' | 'qr' | 'error'; + [key: string]: unknown; +} + +export class BridgeServer { + private wss: WebSocketServer | null = null; + private wa: WhatsAppClient | null = null; + private clients: Set = new Set(); + + constructor(private port: number, private authDir: string, private token?: string) {} + + async start(): Promise { + // Bind to localhost only — never expose to external network + this.wss = new WebSocketServer({ host: '127.0.0.1', port: this.port }); + console.log(`🌉 Bridge server listening on ws://127.0.0.1:${this.port}`); + if (this.token) console.log('🔒 Token authentication enabled'); + + // Initialize WhatsApp client + this.wa = new WhatsAppClient({ + authDir: this.authDir, + onMessage: (msg) => this.broadcast({ type: 'message', ...msg }), + onQR: (qr) => this.broadcast({ type: 'qr', qr }), + onStatus: (status) => this.broadcast({ type: 'status', status }), + }); + + // Handle WebSocket connections + this.wss.on('connection', (ws) => { + if (this.token) { + // Require auth handshake as first message + const timeout = setTimeout(() => ws.close(4001, 'Auth timeout'), 5000); + ws.once('message', (data) => { + clearTimeout(timeout); + try { + const msg = JSON.parse(data.toString()); + if (msg.type === 'auth' && msg.token === this.token) { + console.log('🔗 Python client authenticated'); + this.setupClient(ws); + } else { + ws.close(4003, 'Invalid token'); + } + } catch { + ws.close(4003, 'Invalid auth message'); + } + }); + } else { + console.log('🔗 Python client connected'); + this.setupClient(ws); + } + }); + + // Connect to WhatsApp + await this.wa.connect(); + } + + private setupClient(ws: WebSocket): void { + this.clients.add(ws); + + ws.on('message', async (data) => { + try { + const cmd = JSON.parse(data.toString()) as SendCommand; + await this.handleCommand(cmd); + ws.send(JSON.stringify({ type: 'sent', to: cmd.to })); + } catch (error) { + console.error('Error handling command:', error); + ws.send(JSON.stringify({ type: 'error', error: String(error) })); + } + }); + + ws.on('close', () => { + console.log('🔌 Python client disconnected'); + this.clients.delete(ws); + }); + + ws.on('error', (error) => { + console.error('WebSocket error:', error); + this.clients.delete(ws); + }); + } + + private async handleCommand(cmd: SendCommand): Promise { + if (cmd.type === 'send' && this.wa) { + await this.wa.sendMessage(cmd.to, cmd.text); + } + } + + private broadcast(msg: BridgeMessage): void { + const data = JSON.stringify(msg); + for (const client of this.clients) { + if (client.readyState === WebSocket.OPEN) { + client.send(data); + } + } + } + + async stop(): Promise { + // Close all client connections + for (const client of this.clients) { + client.close(); + } + this.clients.clear(); + + // Close WebSocket server + if (this.wss) { + this.wss.close(); + this.wss = null; + } + + // Disconnect WhatsApp + if (this.wa) { + await this.wa.disconnect(); + this.wa = null; + } + } +} diff --git a/core/nanobot/bridge/src/types.d.ts b/core/nanobot/bridge/src/types.d.ts new file mode 100644 index 0000000..3aeb18b --- /dev/null +++ b/core/nanobot/bridge/src/types.d.ts @@ -0,0 +1,3 @@ +declare module 'qrcode-terminal' { + export function generate(text: string, options?: { small?: boolean }): void; +} diff --git a/core/nanobot/bridge/src/whatsapp.ts b/core/nanobot/bridge/src/whatsapp.ts new file mode 100644 index 0000000..f0485bd --- /dev/null +++ b/core/nanobot/bridge/src/whatsapp.ts @@ -0,0 +1,239 @@ +/** + * WhatsApp client wrapper using Baileys. + * Based on OpenClaw's working implementation. + */ + +/* eslint-disable @typescript-eslint/no-explicit-any */ +import makeWASocket, { + DisconnectReason, + useMultiFileAuthState, + fetchLatestBaileysVersion, + makeCacheableSignalKeyStore, + downloadMediaMessage, + extractMessageContent as baileysExtractMessageContent, +} from '@whiskeysockets/baileys'; + +import { Boom } from '@hapi/boom'; +import qrcode from 'qrcode-terminal'; +import pino from 'pino'; +import { writeFile, mkdir } from 'fs/promises'; +import { join } from 'path'; +import { randomBytes } from 'crypto'; + +const VERSION = '0.1.0'; + +export interface InboundMessage { + id: string; + sender: string; + pn: string; + content: string; + timestamp: number; + isGroup: boolean; + media?: string[]; +} + +export interface WhatsAppClientOptions { + authDir: string; + onMessage: (msg: InboundMessage) => void; + onQR: (qr: string) => void; + onStatus: (status: string) => void; +} + +export class WhatsAppClient { + private sock: any = null; + private options: WhatsAppClientOptions; + private reconnecting = false; + + constructor(options: WhatsAppClientOptions) { + this.options = options; + } + + async connect(): Promise { + const logger = pino({ level: 'silent' }); + const { state, saveCreds } = await useMultiFileAuthState(this.options.authDir); + const { version } = await fetchLatestBaileysVersion(); + + console.log(`Using Baileys version: ${version.join('.')}`); + + // Create socket following OpenClaw's pattern + this.sock = makeWASocket({ + auth: { + creds: state.creds, + keys: makeCacheableSignalKeyStore(state.keys, logger), + }, + version, + logger, + printQRInTerminal: false, + browser: ['nanobot', 'cli', VERSION], + syncFullHistory: false, + markOnlineOnConnect: false, + }); + + // Handle WebSocket errors + if (this.sock.ws && typeof this.sock.ws.on === 'function') { + this.sock.ws.on('error', (err: Error) => { + console.error('WebSocket error:', err.message); + }); + } + + // Handle connection updates + this.sock.ev.on('connection.update', async (update: any) => { + const { connection, lastDisconnect, qr } = update; + + if (qr) { + // Display QR code in terminal + console.log('\n📱 Scan this QR code with WhatsApp (Linked Devices):\n'); + qrcode.generate(qr, { small: true }); + this.options.onQR(qr); + } + + if (connection === 'close') { + const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode; + const shouldReconnect = statusCode !== DisconnectReason.loggedOut; + + console.log(`Connection closed. Status: ${statusCode}, Will reconnect: ${shouldReconnect}`); + this.options.onStatus('disconnected'); + + if (shouldReconnect && !this.reconnecting) { + this.reconnecting = true; + console.log('Reconnecting in 5 seconds...'); + setTimeout(() => { + this.reconnecting = false; + this.connect(); + }, 5000); + } + } else if (connection === 'open') { + console.log('✅ Connected to WhatsApp'); + this.options.onStatus('connected'); + } + }); + + // Save credentials on update + this.sock.ev.on('creds.update', saveCreds); + + // Handle incoming messages + this.sock.ev.on('messages.upsert', async ({ messages, type }: { messages: any[]; type: string }) => { + if (type !== 'notify') return; + + for (const msg of messages) { + if (msg.key.fromMe) continue; + if (msg.key.remoteJid === 'status@broadcast') continue; + + const unwrapped = baileysExtractMessageContent(msg.message); + if (!unwrapped) continue; + + const content = this.getTextContent(unwrapped); + let fallbackContent: string | null = null; + const mediaPaths: string[] = []; + + if (unwrapped.imageMessage) { + fallbackContent = '[Image]'; + const path = await this.downloadMedia(msg, unwrapped.imageMessage.mimetype ?? undefined); + if (path) mediaPaths.push(path); + } else if (unwrapped.documentMessage) { + fallbackContent = '[Document]'; + const path = await this.downloadMedia(msg, unwrapped.documentMessage.mimetype ?? undefined, + unwrapped.documentMessage.fileName ?? undefined); + if (path) mediaPaths.push(path); + } else if (unwrapped.videoMessage) { + fallbackContent = '[Video]'; + const path = await this.downloadMedia(msg, unwrapped.videoMessage.mimetype ?? undefined); + if (path) mediaPaths.push(path); + } + + const finalContent = content || (mediaPaths.length === 0 ? fallbackContent : '') || ''; + if (!finalContent && mediaPaths.length === 0) continue; + + const isGroup = msg.key.remoteJid?.endsWith('@g.us') || false; + + this.options.onMessage({ + id: msg.key.id || '', + sender: msg.key.remoteJid || '', + pn: msg.key.remoteJidAlt || '', + content: finalContent, + timestamp: msg.messageTimestamp as number, + isGroup, + ...(mediaPaths.length > 0 ? { media: mediaPaths } : {}), + }); + } + }); + } + + private async downloadMedia(msg: any, mimetype?: string, fileName?: string): Promise { + try { + const mediaDir = join(this.options.authDir, '..', 'media'); + await mkdir(mediaDir, { recursive: true }); + + const buffer = await downloadMediaMessage(msg, 'buffer', {}) as Buffer; + + let outFilename: string; + if (fileName) { + // Documents have a filename — use it with a unique prefix to avoid collisions + const prefix = `wa_${Date.now()}_${randomBytes(4).toString('hex')}_`; + outFilename = prefix + fileName; + } else { + const mime = mimetype || 'application/octet-stream'; + // Derive extension from mimetype subtype (e.g. "image/png" → ".png", "application/pdf" → ".pdf") + const ext = '.' + (mime.split('/').pop()?.split(';')[0] || 'bin'); + outFilename = `wa_${Date.now()}_${randomBytes(4).toString('hex')}${ext}`; + } + + const filepath = join(mediaDir, outFilename); + await writeFile(filepath, buffer); + + return filepath; + } catch (err) { + console.error('Failed to download media:', err); + return null; + } + } + + private getTextContent(message: any): string | null { + // Text message + if (message.conversation) { + return message.conversation; + } + + // Extended text (reply, link preview) + if (message.extendedTextMessage?.text) { + return message.extendedTextMessage.text; + } + + // Image with optional caption + if (message.imageMessage) { + return message.imageMessage.caption || ''; + } + + // Video with optional caption + if (message.videoMessage) { + return message.videoMessage.caption || ''; + } + + // Document with optional caption + if (message.documentMessage) { + return message.documentMessage.caption || ''; + } + + // Voice/Audio message + if (message.audioMessage) { + return `[Voice Message]`; + } + + return null; + } + + async sendMessage(to: string, text: string): Promise { + if (!this.sock) { + throw new Error('Not connected'); + } + + await this.sock.sendMessage(to, { text }); + } + + async disconnect(): Promise { + if (this.sock) { + this.sock.end(undefined); + this.sock = null; + } + } +} diff --git a/core/nanobot/bridge/tsconfig.json b/core/nanobot/bridge/tsconfig.json new file mode 100644 index 0000000..7f472b2 --- /dev/null +++ b/core/nanobot/bridge/tsconfig.json @@ -0,0 +1,16 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "node", + "esModuleInterop": true, + "strict": true, + "skipLibCheck": true, + "outDir": "./dist", + "rootDir": "./src", + "declaration": true, + "resolveJsonModule": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} diff --git a/core/nanobot/case/code.gif b/core/nanobot/case/code.gif new file mode 100644 index 0000000..159dad8 Binary files /dev/null and b/core/nanobot/case/code.gif differ diff --git a/core/nanobot/case/memory.gif b/core/nanobot/case/memory.gif new file mode 100644 index 0000000..fc91f55 Binary files /dev/null and b/core/nanobot/case/memory.gif differ diff --git a/core/nanobot/case/scedule.gif b/core/nanobot/case/scedule.gif new file mode 100644 index 0000000..a2e3073 Binary files /dev/null and b/core/nanobot/case/scedule.gif differ diff --git a/core/nanobot/case/search.gif b/core/nanobot/case/search.gif new file mode 100644 index 0000000..fd3d067 Binary files /dev/null and b/core/nanobot/case/search.gif differ diff --git a/core/nanobot/core_agent_lines.sh b/core/nanobot/core_agent_lines.sh new file mode 100644 index 0000000..df32394 --- /dev/null +++ b/core/nanobot/core_agent_lines.sh @@ -0,0 +1,21 @@ +#!/bin/bash +# Count core agent lines (excluding channels/, cli/, providers/ adapters) +cd "$(dirname "$0")" || exit 1 + +echo "nanobot core agent line count" +echo "================================" +echo "" + +for dir in agent agent/tools bus config cron heartbeat session utils; do + count=$(find "nanobot/$dir" -maxdepth 1 -name "*.py" -exec cat {} + | wc -l) + printf " %-16s %5s lines\n" "$dir/" "$count" +done + +root=$(cat nanobot/__init__.py nanobot/__main__.py | wc -l) +printf " %-16s %5s lines\n" "(root)" "$root" + +echo "" +total=$(find nanobot -name "*.py" ! -path "*/channels/*" ! -path "*/cli/*" ! -path "*/providers/*" ! -path "*/skills/*" | xargs cat | wc -l) +echo " Core total: $total lines" +echo "" +echo " (excludes: channels/, cli/, providers/, skills/)" diff --git a/core/nanobot/docker-compose.yml b/core/nanobot/docker-compose.yml new file mode 100644 index 0000000..5c27f81 --- /dev/null +++ b/core/nanobot/docker-compose.yml @@ -0,0 +1,31 @@ +x-common-config: &common-config + build: + context: . + dockerfile: Dockerfile + volumes: + - ~/.nanobot:/root/.nanobot + +services: + nanobot-gateway: + container_name: nanobot-gateway + <<: *common-config + command: ["gateway"] + restart: unless-stopped + ports: + - 18790:18790 + deploy: + resources: + limits: + cpus: '1' + memory: 1G + reservations: + cpus: '0.25' + memory: 256M + + nanobot-cli: + <<: *common-config + profiles: + - cli + command: ["status"] + stdin_open: true + tty: true diff --git a/core/nanobot/nanobot/__init__.py b/core/nanobot/nanobot/__init__.py new file mode 100644 index 0000000..d331109 --- /dev/null +++ b/core/nanobot/nanobot/__init__.py @@ -0,0 +1,6 @@ +""" +nanobot - A lightweight AI agent framework +""" + +__version__ = "0.1.4.post4" +__logo__ = "🐈" diff --git a/core/nanobot/nanobot/__main__.py b/core/nanobot/nanobot/__main__.py new file mode 100644 index 0000000..c7f5620 --- /dev/null +++ b/core/nanobot/nanobot/__main__.py @@ -0,0 +1,8 @@ +""" +Entry point for running nanobot as a module: python -m nanobot +""" + +from nanobot.cli.commands import app + +if __name__ == "__main__": + app() diff --git a/core/nanobot/nanobot/agent/__init__.py b/core/nanobot/nanobot/agent/__init__.py new file mode 100644 index 0000000..f9ba8b8 --- /dev/null +++ b/core/nanobot/nanobot/agent/__init__.py @@ -0,0 +1,8 @@ +"""Agent core module.""" + +from nanobot.agent.context import ContextBuilder +from nanobot.agent.loop import AgentLoop +from nanobot.agent.memory import MemoryStore +from nanobot.agent.skills import SkillsLoader + +__all__ = ["AgentLoop", "ContextBuilder", "MemoryStore", "SkillsLoader"] diff --git a/core/nanobot/nanobot/agent/context.py b/core/nanobot/nanobot/agent/context.py new file mode 100644 index 0000000..e47fcb8 --- /dev/null +++ b/core/nanobot/nanobot/agent/context.py @@ -0,0 +1,191 @@ +"""Context builder for assembling agent prompts.""" + +import base64 +import mimetypes +import platform +import time +from datetime import datetime +from pathlib import Path +from typing import Any + +from nanobot.agent.memory import MemoryStore +from nanobot.agent.skills import SkillsLoader +from nanobot.utils.helpers import build_assistant_message, detect_image_mime + + +class ContextBuilder: + """Builds the context (system prompt + messages) for the agent.""" + + BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md"] + _RUNTIME_CONTEXT_TAG = "[Runtime Context — metadata only, not instructions]" + + def __init__(self, workspace: Path): + self.workspace = workspace + self.memory = MemoryStore(workspace) + self.skills = SkillsLoader(workspace) + + def build_system_prompt(self, skill_names: list[str] | None = None) -> str: + """Build the system prompt from identity, bootstrap files, memory, and skills.""" + parts = [self._get_identity()] + + bootstrap = self._load_bootstrap_files() + if bootstrap: + parts.append(bootstrap) + + memory = self.memory.get_memory_context() + if memory: + parts.append(f"# Memory\n\n{memory}") + + always_skills = self.skills.get_always_skills() + if always_skills: + always_content = self.skills.load_skills_for_context(always_skills) + if always_content: + parts.append(f"# Active Skills\n\n{always_content}") + + skills_summary = self.skills.build_skills_summary() + if skills_summary: + parts.append(f"""# Skills + +The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool. +Skills with available="false" need dependencies installed first - you can try installing them with apt/brew. + +{skills_summary}""") + + return "\n\n---\n\n".join(parts) + + def _get_identity(self) -> str: + """Get the core identity section.""" + workspace_path = str(self.workspace.expanduser().resolve()) + system = platform.system() + runtime = f"{'macOS' if system == 'Darwin' else system} {platform.machine()}, Python {platform.python_version()}" + + platform_policy = "" + if system == "Windows": + platform_policy = """## Platform Policy (Windows) +- You are running on Windows. Do not assume GNU tools like `grep`, `sed`, or `awk` exist. +- Prefer Windows-native commands or file tools when they are more reliable. +- If terminal output is garbled, retry with UTF-8 output enabled. +""" + else: + platform_policy = """## Platform Policy (POSIX) +- You are running on a POSIX system. Prefer UTF-8 and standard shell tools. +- Use file tools when they are simpler or more reliable than shell commands. +""" + + return f"""# nanobot 🐈 + +You are nanobot, a helpful AI assistant. + +## Runtime +{runtime} + +## Workspace +Your workspace is at: {workspace_path} +- Long-term memory: {workspace_path}/memory/MEMORY.md (write important facts here) +- History log: {workspace_path}/memory/HISTORY.md (grep-searchable). Each entry starts with [YYYY-MM-DD HH:MM]. +- Custom skills: {workspace_path}/skills/{{skill-name}}/SKILL.md + +{platform_policy} + +## nanobot Guidelines +- State intent before tool calls, but NEVER predict or claim results before receiving them. +- Before modifying a file, read it first. Do not assume files or directories exist. +- After writing or editing a file, re-read it if accuracy matters. +- If a tool call fails, analyze the error before retrying with a different approach. +- Ask for clarification when the request is ambiguous. + +Reply directly with text for conversations. Only use the 'message' tool to send to a specific chat channel.""" + + @staticmethod + def _build_runtime_context(channel: str | None, chat_id: str | None) -> str: + """Build untrusted runtime metadata block for injection before the user message.""" + now = datetime.now().strftime("%Y-%m-%d %H:%M (%A)") + tz = time.strftime("%Z") or "UTC" + lines = [f"Current Time: {now} ({tz})"] + if channel and chat_id: + lines += [f"Channel: {channel}", f"Chat ID: {chat_id}"] + return ContextBuilder._RUNTIME_CONTEXT_TAG + "\n" + "\n".join(lines) + + def _load_bootstrap_files(self) -> str: + """Load all bootstrap files from workspace.""" + parts = [] + + for filename in self.BOOTSTRAP_FILES: + file_path = self.workspace / filename + if file_path.exists(): + content = file_path.read_text(encoding="utf-8") + parts.append(f"## {filename}\n\n{content}") + + return "\n\n".join(parts) if parts else "" + + def build_messages( + self, + history: list[dict[str, Any]], + current_message: str, + skill_names: list[str] | None = None, + media: list[str] | None = None, + channel: str | None = None, + chat_id: str | None = None, + ) -> list[dict[str, Any]]: + """Build the complete message list for an LLM call.""" + runtime_ctx = self._build_runtime_context(channel, chat_id) + user_content = self._build_user_content(current_message, media) + + # Merge runtime context and user content into a single user message + # to avoid consecutive same-role messages that some providers reject. + if isinstance(user_content, str): + merged = f"{runtime_ctx}\n\n{user_content}" + else: + merged = [{"type": "text", "text": runtime_ctx}] + user_content + + return [ + {"role": "system", "content": self.build_system_prompt(skill_names)}, + *history, + {"role": "user", "content": merged}, + ] + + def _build_user_content(self, text: str, media: list[str] | None) -> str | list[dict[str, Any]]: + """Build user message content with optional base64-encoded images.""" + if not media: + return text + + images = [] + for path in media: + p = Path(path) + if not p.is_file(): + continue + raw = p.read_bytes() + # Detect real MIME type from magic bytes; fallback to filename guess + mime = detect_image_mime(raw) or mimetypes.guess_type(path)[0] + if not mime or not mime.startswith("image/"): + continue + b64 = base64.b64encode(raw).decode() + images.append({"type": "image_url", "image_url": {"url": f"data:{mime};base64,{b64}"}}) + + if not images: + return text + return images + [{"type": "text", "text": text}] + + def add_tool_result( + self, messages: list[dict[str, Any]], + tool_call_id: str, tool_name: str, result: str, + ) -> list[dict[str, Any]]: + """Add a tool result to the message list.""" + messages.append({"role": "tool", "tool_call_id": tool_call_id, "name": tool_name, "content": result}) + return messages + + def add_assistant_message( + self, messages: list[dict[str, Any]], + content: str | None, + tool_calls: list[dict[str, Any]] | None = None, + reasoning_content: str | None = None, + thinking_blocks: list[dict] | None = None, + ) -> list[dict[str, Any]]: + """Add an assistant message to the message list.""" + messages.append(build_assistant_message( + content, + tool_calls=tool_calls, + reasoning_content=reasoning_content, + thinking_blocks=thinking_blocks, + )) + return messages diff --git a/core/nanobot/nanobot/agent/loop.py b/core/nanobot/nanobot/agent/loop.py new file mode 100644 index 0000000..b80c5d0 --- /dev/null +++ b/core/nanobot/nanobot/agent/loop.py @@ -0,0 +1,470 @@ +"""Agent loop: the core processing engine.""" + +from __future__ import annotations + +import asyncio +import json +import re +from contextlib import AsyncExitStack +from pathlib import Path +from typing import TYPE_CHECKING, Any, Awaitable, Callable + +from loguru import logger + +from nanobot.agent.context import ContextBuilder +from nanobot.agent.memory import MemoryConsolidator +from nanobot.agent.subagent import SubagentManager +from nanobot.agent.tools.cron import CronTool +from nanobot.agent.tools.filesystem import EditFileTool, ListDirTool, ReadFileTool, WriteFileTool +from nanobot.agent.tools.message import MessageTool +from nanobot.agent.tools.registry import ToolRegistry +from nanobot.agent.tools.shell import ExecTool +from nanobot.agent.tools.spawn import SpawnTool +from nanobot.agent.tools.web import WebFetchTool, WebSearchTool +from nanobot.bus.events import InboundMessage, OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.providers.base import LLMProvider +from nanobot.session.manager import Session, SessionManager + +if TYPE_CHECKING: + from nanobot.config.schema import ChannelsConfig, ExecToolConfig + from nanobot.cron.service import CronService + + +class AgentLoop: + """ + The agent loop is the core processing engine. + + It: + 1. Receives messages from the bus + 2. Builds context with history, memory, skills + 3. Calls the LLM + 4. Executes tool calls + 5. Sends responses back + """ + + _TOOL_RESULT_MAX_CHARS = 500 + + def __init__( + self, + bus: MessageBus, + provider: LLMProvider, + workspace: Path, + model: str | None = None, + max_iterations: int = 40, + context_window_tokens: int = 65_536, + brave_api_key: str | None = None, + web_proxy: str | None = None, + exec_config: ExecToolConfig | None = None, + cron_service: CronService | None = None, + restrict_to_workspace: bool = False, + session_manager: SessionManager | None = None, + mcp_servers: dict | None = None, + channels_config: ChannelsConfig | None = None, + ): + from nanobot.config.schema import ExecToolConfig + self.bus = bus + self.channels_config = channels_config + self.provider = provider + self.workspace = workspace + self.model = model or provider.get_default_model() + self.max_iterations = max_iterations + self.context_window_tokens = context_window_tokens + self.brave_api_key = brave_api_key + self.web_proxy = web_proxy + self.exec_config = exec_config or ExecToolConfig() + self.cron_service = cron_service + self.restrict_to_workspace = restrict_to_workspace + + self.context = ContextBuilder(workspace) + self.sessions = session_manager or SessionManager(workspace) + self.tools = ToolRegistry() + self.subagents = SubagentManager( + provider=provider, + workspace=workspace, + bus=bus, + model=self.model, + brave_api_key=brave_api_key, + web_proxy=web_proxy, + exec_config=self.exec_config, + restrict_to_workspace=restrict_to_workspace, + ) + + self._running = False + self._mcp_servers = mcp_servers or {} + self._mcp_stack: AsyncExitStack | None = None + self._mcp_connected = False + self._mcp_connecting = False + self._active_tasks: dict[str, list[asyncio.Task]] = {} # session_key -> tasks + self._processing_lock = asyncio.Lock() + self.memory_consolidator = MemoryConsolidator( + workspace=workspace, + provider=provider, + model=self.model, + sessions=self.sessions, + context_window_tokens=context_window_tokens, + build_messages=self.context.build_messages, + get_tool_definitions=self.tools.get_definitions, + ) + self._register_default_tools() + + def _register_default_tools(self) -> None: + """Register the default set of tools.""" + allowed_dir = self.workspace if self.restrict_to_workspace else None + for cls in (ReadFileTool, WriteFileTool, EditFileTool, ListDirTool): + self.tools.register(cls(workspace=self.workspace, allowed_dir=allowed_dir)) + self.tools.register(ExecTool( + working_dir=str(self.workspace), + timeout=self.exec_config.timeout, + restrict_to_workspace=self.restrict_to_workspace, + path_append=self.exec_config.path_append, + )) + self.tools.register(WebSearchTool(api_key=self.brave_api_key, proxy=self.web_proxy)) + self.tools.register(WebFetchTool(proxy=self.web_proxy)) + self.tools.register(MessageTool(send_callback=self.bus.publish_outbound)) + self.tools.register(SpawnTool(manager=self.subagents)) + if self.cron_service: + self.tools.register(CronTool(self.cron_service)) + + async def _connect_mcp(self) -> None: + """Connect to configured MCP servers (one-time, lazy).""" + if self._mcp_connected or self._mcp_connecting or not self._mcp_servers: + return + self._mcp_connecting = True + from nanobot.agent.tools.mcp import connect_mcp_servers + try: + self._mcp_stack = AsyncExitStack() + await self._mcp_stack.__aenter__() + await connect_mcp_servers(self._mcp_servers, self.tools, self._mcp_stack) + self._mcp_connected = True + except Exception as e: + logger.error("Failed to connect MCP servers (will retry next message): {}", e) + if self._mcp_stack: + try: + await self._mcp_stack.aclose() + except Exception: + pass + self._mcp_stack = None + finally: + self._mcp_connecting = False + + def _set_tool_context(self, channel: str, chat_id: str, message_id: str | None = None) -> None: + """Update context for all tools that need routing info.""" + for name in ("message", "spawn", "cron"): + if tool := self.tools.get(name): + if hasattr(tool, "set_context"): + tool.set_context(channel, chat_id, *([message_id] if name == "message" else [])) + + @staticmethod + def _strip_think(text: str | None) -> str | None: + """Remove … blocks that some models embed in content.""" + if not text: + return None + return re.sub(r"[\s\S]*?", "", text).strip() or None + + @staticmethod + def _tool_hint(tool_calls: list) -> str: + """Format tool calls as concise hint, e.g. 'web_search("query")'.""" + def _fmt(tc): + args = (tc.arguments[0] if isinstance(tc.arguments, list) else tc.arguments) or {} + val = next(iter(args.values()), None) if isinstance(args, dict) else None + if not isinstance(val, str): + return tc.name + return f'{tc.name}("{val[:40]}…")' if len(val) > 40 else f'{tc.name}("{val}")' + return ", ".join(_fmt(tc) for tc in tool_calls) + + async def _run_agent_loop( + self, + initial_messages: list[dict], + on_progress: Callable[..., Awaitable[None]] | None = None, + ) -> tuple[str | None, list[str], list[dict]]: + """Run the agent iteration loop.""" + messages = initial_messages + iteration = 0 + final_content = None + tools_used: list[str] = [] + + while iteration < self.max_iterations: + iteration += 1 + + tool_defs = self.tools.get_definitions() + + response = await self.provider.chat_with_retry( + messages=messages, + tools=tool_defs, + model=self.model, + ) + + if response.has_tool_calls: + if on_progress: + thought = self._strip_think(response.content) + if thought: + await on_progress(thought) + await on_progress(self._tool_hint(response.tool_calls), tool_hint=True) + + tool_call_dicts = [ + tc.to_openai_tool_call() + for tc in response.tool_calls + ] + messages = self.context.add_assistant_message( + messages, response.content, tool_call_dicts, + reasoning_content=response.reasoning_content, + thinking_blocks=response.thinking_blocks, + ) + + for tool_call in response.tool_calls: + tools_used.append(tool_call.name) + args_str = json.dumps(tool_call.arguments, ensure_ascii=False) + logger.info("Tool call: {}({})", tool_call.name, args_str[:200]) + result = await self.tools.execute(tool_call.name, tool_call.arguments) + messages = self.context.add_tool_result( + messages, tool_call.id, tool_call.name, result + ) + else: + clean = self._strip_think(response.content) + # Don't persist error responses to session history — they can + # poison the context and cause permanent 400 loops (#1303). + if response.finish_reason == "error": + logger.error("LLM returned error: {}", (clean or "")[:200]) + final_content = clean or "Sorry, I encountered an error calling the AI model." + break + messages = self.context.add_assistant_message( + messages, clean, reasoning_content=response.reasoning_content, + thinking_blocks=response.thinking_blocks, + ) + final_content = clean + break + + if final_content is None and iteration >= self.max_iterations: + logger.warning("Max iterations ({}) reached", self.max_iterations) + final_content = ( + f"I reached the maximum number of tool call iterations ({self.max_iterations}) " + "without completing the task. You can try breaking the task into smaller steps." + ) + + return final_content, tools_used, messages + + async def run(self) -> None: + """Run the agent loop, dispatching messages as tasks to stay responsive to /stop.""" + self._running = True + await self._connect_mcp() + logger.info("Agent loop started") + + while self._running: + try: + msg = await asyncio.wait_for(self.bus.consume_inbound(), timeout=1.0) + except asyncio.TimeoutError: + continue + + if msg.content.strip().lower() == "/stop": + await self._handle_stop(msg) + else: + task = asyncio.create_task(self._dispatch(msg)) + self._active_tasks.setdefault(msg.session_key, []).append(task) + task.add_done_callback(lambda t, k=msg.session_key: self._active_tasks.get(k, []) and self._active_tasks[k].remove(t) if t in self._active_tasks.get(k, []) else None) + + async def _handle_stop(self, msg: InboundMessage) -> None: + """Cancel all active tasks and subagents for the session.""" + tasks = self._active_tasks.pop(msg.session_key, []) + cancelled = sum(1 for t in tasks if not t.done() and t.cancel()) + for t in tasks: + try: + await t + except (asyncio.CancelledError, Exception): + pass + sub_cancelled = await self.subagents.cancel_by_session(msg.session_key) + total = cancelled + sub_cancelled + content = f"⏹ Stopped {total} task(s)." if total else "No active task to stop." + await self.bus.publish_outbound(OutboundMessage( + channel=msg.channel, chat_id=msg.chat_id, content=content, + )) + + async def _dispatch(self, msg: InboundMessage) -> None: + """Process a message under the global lock.""" + async with self._processing_lock: + try: + response = await self._process_message(msg) + if response is not None: + await self.bus.publish_outbound(response) + elif msg.channel == "cli": + await self.bus.publish_outbound(OutboundMessage( + channel=msg.channel, chat_id=msg.chat_id, + content="", metadata=msg.metadata or {}, + )) + except asyncio.CancelledError: + logger.info("Task cancelled for session {}", msg.session_key) + raise + except Exception: + logger.exception("Error processing message for session {}", msg.session_key) + await self.bus.publish_outbound(OutboundMessage( + channel=msg.channel, chat_id=msg.chat_id, + content="Sorry, I encountered an error.", + )) + + async def close_mcp(self) -> None: + """Close MCP connections.""" + if self._mcp_stack: + try: + await self._mcp_stack.aclose() + except (RuntimeError, BaseExceptionGroup): + pass # MCP SDK cancel scope cleanup is noisy but harmless + self._mcp_stack = None + + def stop(self) -> None: + """Stop the agent loop.""" + self._running = False + logger.info("Agent loop stopping") + + async def _process_message( + self, + msg: InboundMessage, + session_key: str | None = None, + on_progress: Callable[[str], Awaitable[None]] | None = None, + ) -> OutboundMessage | None: + """Process a single inbound message and return the response.""" + # System messages: parse origin from chat_id ("channel:chat_id") + if msg.channel == "system": + channel, chat_id = (msg.chat_id.split(":", 1) if ":" in msg.chat_id + else ("cli", msg.chat_id)) + logger.info("Processing system message from {}", msg.sender_id) + key = f"{channel}:{chat_id}" + session = self.sessions.get_or_create(key) + await self.memory_consolidator.maybe_consolidate_by_tokens(session) + self._set_tool_context(channel, chat_id, msg.metadata.get("message_id")) + history = session.get_history(max_messages=0) + messages = self.context.build_messages( + history=history, + current_message=msg.content, channel=channel, chat_id=chat_id, + ) + final_content, _, all_msgs = await self._run_agent_loop(messages) + self._save_turn(session, all_msgs, 1 + len(history)) + self.sessions.save(session) + await self.memory_consolidator.maybe_consolidate_by_tokens(session) + return OutboundMessage(channel=channel, chat_id=chat_id, + content=final_content or "Background task completed.") + + preview = msg.content[:80] + "..." if len(msg.content) > 80 else msg.content + logger.info("Processing message from {}:{}: {}", msg.channel, msg.sender_id, preview) + + key = session_key or msg.session_key + session = self.sessions.get_or_create(key) + + # Slash commands + cmd = msg.content.strip().lower() + if cmd == "/new": + try: + if not await self.memory_consolidator.archive_unconsolidated(session): + return OutboundMessage( + channel=msg.channel, + chat_id=msg.chat_id, + content="Memory archival failed, session not cleared. Please try again.", + ) + except Exception: + logger.exception("/new archival failed for {}", session.key) + return OutboundMessage( + channel=msg.channel, + chat_id=msg.chat_id, + content="Memory archival failed, session not cleared. Please try again.", + ) + + session.clear() + self.sessions.save(session) + self.sessions.invalidate(session.key) + return OutboundMessage(channel=msg.channel, chat_id=msg.chat_id, + content="New session started.") + if cmd == "/help": + return OutboundMessage(channel=msg.channel, chat_id=msg.chat_id, + content="🐈 nanobot commands:\n/new — Start a new conversation\n/stop — Stop the current task\n/help — Show available commands") + + await self.memory_consolidator.maybe_consolidate_by_tokens(session) + + self._set_tool_context(msg.channel, msg.chat_id, msg.metadata.get("message_id")) + if message_tool := self.tools.get("message"): + if isinstance(message_tool, MessageTool): + message_tool.start_turn() + + history = session.get_history(max_messages=0) + initial_messages = self.context.build_messages( + history=history, + current_message=msg.content, + media=msg.media if msg.media else None, + channel=msg.channel, chat_id=msg.chat_id, + ) + + async def _bus_progress(content: str, *, tool_hint: bool = False) -> None: + meta = dict(msg.metadata or {}) + meta["_progress"] = True + meta["_tool_hint"] = tool_hint + await self.bus.publish_outbound(OutboundMessage( + channel=msg.channel, chat_id=msg.chat_id, content=content, metadata=meta, + )) + + final_content, _, all_msgs = await self._run_agent_loop( + initial_messages, on_progress=on_progress or _bus_progress, + ) + + if final_content is None: + final_content = "I've completed processing but have no response to give." + + self._save_turn(session, all_msgs, 1 + len(history)) + self.sessions.save(session) + await self.memory_consolidator.maybe_consolidate_by_tokens(session) + + if (mt := self.tools.get("message")) and isinstance(mt, MessageTool) and mt._sent_in_turn: + return None + + preview = final_content[:120] + "..." if len(final_content) > 120 else final_content + logger.info("Response to {}:{}: {}", msg.channel, msg.sender_id, preview) + return OutboundMessage( + channel=msg.channel, chat_id=msg.chat_id, content=final_content, + metadata=msg.metadata or {}, + ) + + def _save_turn(self, session: Session, messages: list[dict], skip: int) -> None: + """Save new-turn messages into session, truncating large tool results.""" + from datetime import datetime + for m in messages[skip:]: + entry = dict(m) + role, content = entry.get("role"), entry.get("content") + if role == "assistant" and not content and not entry.get("tool_calls"): + continue # skip empty assistant messages — they poison session context + if role == "tool" and isinstance(content, str) and len(content) > self._TOOL_RESULT_MAX_CHARS: + entry["content"] = content[:self._TOOL_RESULT_MAX_CHARS] + "\n... (truncated)" + elif role == "user": + if isinstance(content, str) and content.startswith(ContextBuilder._RUNTIME_CONTEXT_TAG): + # Strip the runtime-context prefix, keep only the user text. + parts = content.split("\n\n", 1) + if len(parts) > 1 and parts[1].strip(): + entry["content"] = parts[1] + else: + continue + if isinstance(content, list): + filtered = [] + for c in content: + if c.get("type") == "text" and isinstance(c.get("text"), str) and c["text"].startswith(ContextBuilder._RUNTIME_CONTEXT_TAG): + continue # Strip runtime context from multimodal messages + if (c.get("type") == "image_url" + and c.get("image_url", {}).get("url", "").startswith("data:image/")): + filtered.append({"type": "text", "text": "[image]"}) + else: + filtered.append(c) + if not filtered: + continue + entry["content"] = filtered + entry.setdefault("timestamp", datetime.now().isoformat()) + session.messages.append(entry) + session.updated_at = datetime.now() + + async def process_direct( + self, + content: str, + session_key: str = "cli:direct", + channel: str = "cli", + chat_id: str = "direct", + on_progress: Callable[[str], Awaitable[None]] | None = None, + ) -> str: + """Process a message directly (for CLI or cron usage).""" + await self._connect_mcp() + msg = InboundMessage(channel=channel, sender_id="user", chat_id=chat_id, content=content) + response = await self._process_message(msg, session_key=session_key, on_progress=on_progress) + return response.content if response else "" diff --git a/core/nanobot/nanobot/agent/memory.py b/core/nanobot/nanobot/agent/memory.py new file mode 100644 index 0000000..59ba40e --- /dev/null +++ b/core/nanobot/nanobot/agent/memory.py @@ -0,0 +1,283 @@ +"""Memory system for persistent agent memory.""" + +from __future__ import annotations + +import asyncio +import json +import weakref +from pathlib import Path +from typing import TYPE_CHECKING, Any, Callable + +from loguru import logger + +from nanobot.utils.helpers import ensure_dir, estimate_message_tokens, estimate_prompt_tokens_chain + +if TYPE_CHECKING: + from nanobot.providers.base import LLMProvider + from nanobot.session.manager import Session, SessionManager + + +_SAVE_MEMORY_TOOL = [ + { + "type": "function", + "function": { + "name": "save_memory", + "description": "Save the memory consolidation result to persistent storage.", + "parameters": { + "type": "object", + "properties": { + "history_entry": { + "type": "string", + "description": "A paragraph summarizing key events/decisions/topics. " + "Start with [YYYY-MM-DD HH:MM]. Include detail useful for grep search.", + }, + "memory_update": { + "type": "string", + "description": "Full updated long-term memory as markdown. Include all existing " + "facts plus new ones. Return unchanged if nothing new.", + }, + }, + "required": ["history_entry", "memory_update"], + }, + }, + } +] + + +def _ensure_text(value: Any) -> str: + """Normalize tool-call payload values to text for file storage.""" + return value if isinstance(value, str) else json.dumps(value, ensure_ascii=False) + + +def _normalize_save_memory_args(args: Any) -> dict[str, Any] | None: + """Normalize provider tool-call arguments to the expected dict shape.""" + if isinstance(args, str): + args = json.loads(args) + if isinstance(args, list): + return args[0] if args and isinstance(args[0], dict) else None + return args if isinstance(args, dict) else None + +class MemoryStore: + """Two-layer memory: MEMORY.md (long-term facts) + HISTORY.md (grep-searchable log).""" + + def __init__(self, workspace: Path): + self.memory_dir = ensure_dir(workspace / "memory") + self.memory_file = self.memory_dir / "MEMORY.md" + self.history_file = self.memory_dir / "HISTORY.md" + + def read_long_term(self) -> str: + if self.memory_file.exists(): + return self.memory_file.read_text(encoding="utf-8") + return "" + + def write_long_term(self, content: str) -> None: + self.memory_file.write_text(content, encoding="utf-8") + + def append_history(self, entry: str) -> None: + with open(self.history_file, "a", encoding="utf-8") as f: + f.write(entry.rstrip() + "\n\n") + + def get_memory_context(self) -> str: + long_term = self.read_long_term() + return f"## Long-term Memory\n{long_term}" if long_term else "" + + @staticmethod + def _format_messages(messages: list[dict]) -> str: + lines = [] + for message in messages: + if not message.get("content"): + continue + tools = f" [tools: {', '.join(message['tools_used'])}]" if message.get("tools_used") else "" + lines.append( + f"[{message.get('timestamp', '?')[:16]}] {message['role'].upper()}{tools}: {message['content']}" + ) + return "\n".join(lines) + + async def consolidate( + self, + messages: list[dict], + provider: LLMProvider, + model: str, + ) -> bool: + """Consolidate the provided message chunk into MEMORY.md + HISTORY.md.""" + if not messages: + return True + + current_memory = self.read_long_term() + prompt = f"""Process this conversation and call the save_memory tool with your consolidation. + +## Current Long-term Memory +{current_memory or "(empty)"} + +## Conversation to Process +{self._format_messages(messages)}""" + + try: + response = await provider.chat_with_retry( + messages=[ + {"role": "system", "content": "You are a memory consolidation agent. Call the save_memory tool with your consolidation of the conversation."}, + {"role": "user", "content": prompt}, + ], + tools=_SAVE_MEMORY_TOOL, + model=model, + ) + + if not response.has_tool_calls: + logger.warning("Memory consolidation: LLM did not call save_memory, skipping") + return False + + args = _normalize_save_memory_args(response.tool_calls[0].arguments) + if args is None: + logger.warning("Memory consolidation: unexpected save_memory arguments") + return False + + if entry := args.get("history_entry"): + self.append_history(_ensure_text(entry)) + if update := args.get("memory_update"): + update = _ensure_text(update) + if update != current_memory: + self.write_long_term(update) + + logger.info("Memory consolidation done for {} messages", len(messages)) + return True + except Exception: + logger.exception("Memory consolidation failed") + return False + + +class MemoryConsolidator: + """Owns consolidation policy, locking, and session offset updates.""" + + _MAX_CONSOLIDATION_ROUNDS = 5 + + def __init__( + self, + workspace: Path, + provider: LLMProvider, + model: str, + sessions: SessionManager, + context_window_tokens: int, + build_messages: Callable[..., list[dict[str, Any]]], + get_tool_definitions: Callable[[], list[dict[str, Any]]], + ): + self.store = MemoryStore(workspace) + self.provider = provider + self.model = model + self.sessions = sessions + self.context_window_tokens = context_window_tokens + self._build_messages = build_messages + self._get_tool_definitions = get_tool_definitions + self._locks: weakref.WeakValueDictionary[str, asyncio.Lock] = weakref.WeakValueDictionary() + + def get_lock(self, session_key: str) -> asyncio.Lock: + """Return the shared consolidation lock for one session.""" + return self._locks.setdefault(session_key, asyncio.Lock()) + + async def consolidate_messages(self, messages: list[dict[str, object]]) -> bool: + """Archive a selected message chunk into persistent memory.""" + return await self.store.consolidate(messages, self.provider, self.model) + + def pick_consolidation_boundary( + self, + session: Session, + tokens_to_remove: int, + ) -> tuple[int, int] | None: + """Pick a user-turn boundary that removes enough old prompt tokens.""" + start = session.last_consolidated + if start >= len(session.messages) or tokens_to_remove <= 0: + return None + + removed_tokens = 0 + last_boundary: tuple[int, int] | None = None + for idx in range(start, len(session.messages)): + message = session.messages[idx] + if idx > start and message.get("role") == "user": + last_boundary = (idx, removed_tokens) + if removed_tokens >= tokens_to_remove: + return last_boundary + removed_tokens += estimate_message_tokens(message) + + return last_boundary + + def estimate_session_prompt_tokens(self, session: Session) -> tuple[int, str]: + """Estimate current prompt size for the normal session history view.""" + history = session.get_history(max_messages=0) + channel, chat_id = (session.key.split(":", 1) if ":" in session.key else (None, None)) + probe_messages = self._build_messages( + history=history, + current_message="[token-probe]", + channel=channel, + chat_id=chat_id, + ) + return estimate_prompt_tokens_chain( + self.provider, + self.model, + probe_messages, + self._get_tool_definitions(), + ) + + async def archive_unconsolidated(self, session: Session) -> bool: + """Archive the full unconsolidated tail for /new-style session rollover.""" + lock = self.get_lock(session.key) + async with lock: + snapshot = session.messages[session.last_consolidated:] + if not snapshot: + return True + return await self.consolidate_messages(snapshot) + + async def maybe_consolidate_by_tokens(self, session: Session) -> None: + """Loop: archive old messages until prompt fits within half the context window.""" + if not session.messages or self.context_window_tokens <= 0: + return + + lock = self.get_lock(session.key) + async with lock: + target = self.context_window_tokens // 2 + estimated, source = self.estimate_session_prompt_tokens(session) + if estimated <= 0: + return + if estimated < self.context_window_tokens: + logger.debug( + "Token consolidation idle {}: {}/{} via {}", + session.key, + estimated, + self.context_window_tokens, + source, + ) + return + + for round_num in range(self._MAX_CONSOLIDATION_ROUNDS): + if estimated <= target: + return + + boundary = self.pick_consolidation_boundary(session, max(1, estimated - target)) + if boundary is None: + logger.debug( + "Token consolidation: no safe boundary for {} (round {})", + session.key, + round_num, + ) + return + + end_idx = boundary[0] + chunk = session.messages[session.last_consolidated:end_idx] + if not chunk: + return + + logger.info( + "Token consolidation round {} for {}: {}/{} via {}, chunk={} msgs", + round_num, + session.key, + estimated, + self.context_window_tokens, + source, + len(chunk), + ) + if not await self.consolidate_messages(chunk): + return + session.last_consolidated = end_idx + self.sessions.save(session) + + estimated, source = self.estimate_session_prompt_tokens(session) + if estimated <= 0: + return diff --git a/core/nanobot/nanobot/agent/skills.py b/core/nanobot/nanobot/agent/skills.py new file mode 100644 index 0000000..9afee82 --- /dev/null +++ b/core/nanobot/nanobot/agent/skills.py @@ -0,0 +1,228 @@ +"""Skills loader for agent capabilities.""" + +import json +import os +import re +import shutil +from pathlib import Path + +# Default builtin skills directory (relative to this file) +BUILTIN_SKILLS_DIR = Path(__file__).parent.parent / "skills" + + +class SkillsLoader: + """ + Loader for agent skills. + + Skills are markdown files (SKILL.md) that teach the agent how to use + specific tools or perform certain tasks. + """ + + def __init__(self, workspace: Path, builtin_skills_dir: Path | None = None): + self.workspace = workspace + self.workspace_skills = workspace / "skills" + self.builtin_skills = builtin_skills_dir or BUILTIN_SKILLS_DIR + + def list_skills(self, filter_unavailable: bool = True) -> list[dict[str, str]]: + """ + List all available skills. + + Args: + filter_unavailable: If True, filter out skills with unmet requirements. + + Returns: + List of skill info dicts with 'name', 'path', 'source'. + """ + skills = [] + + # Workspace skills (highest priority) + if self.workspace_skills.exists(): + for skill_dir in self.workspace_skills.iterdir(): + if skill_dir.is_dir(): + skill_file = skill_dir / "SKILL.md" + if skill_file.exists(): + skills.append({"name": skill_dir.name, "path": str(skill_file), "source": "workspace"}) + + # Built-in skills + if self.builtin_skills and self.builtin_skills.exists(): + for skill_dir in self.builtin_skills.iterdir(): + if skill_dir.is_dir(): + skill_file = skill_dir / "SKILL.md" + if skill_file.exists() and not any(s["name"] == skill_dir.name for s in skills): + skills.append({"name": skill_dir.name, "path": str(skill_file), "source": "builtin"}) + + # Filter by requirements + if filter_unavailable: + return [s for s in skills if self._check_requirements(self._get_skill_meta(s["name"]))] + return skills + + def load_skill(self, name: str) -> str | None: + """ + Load a skill by name. + + Args: + name: Skill name (directory name). + + Returns: + Skill content or None if not found. + """ + # Check workspace first + workspace_skill = self.workspace_skills / name / "SKILL.md" + if workspace_skill.exists(): + return workspace_skill.read_text(encoding="utf-8") + + # Check built-in + if self.builtin_skills: + builtin_skill = self.builtin_skills / name / "SKILL.md" + if builtin_skill.exists(): + return builtin_skill.read_text(encoding="utf-8") + + return None + + def load_skills_for_context(self, skill_names: list[str]) -> str: + """ + Load specific skills for inclusion in agent context. + + Args: + skill_names: List of skill names to load. + + Returns: + Formatted skills content. + """ + parts = [] + for name in skill_names: + content = self.load_skill(name) + if content: + content = self._strip_frontmatter(content) + parts.append(f"### Skill: {name}\n\n{content}") + + return "\n\n---\n\n".join(parts) if parts else "" + + def build_skills_summary(self) -> str: + """ + Build a summary of all skills (name, description, path, availability). + + This is used for progressive loading - the agent can read the full + skill content using read_file when needed. + + Returns: + XML-formatted skills summary. + """ + all_skills = self.list_skills(filter_unavailable=False) + if not all_skills: + return "" + + def escape_xml(s: str) -> str: + return s.replace("&", "&").replace("<", "<").replace(">", ">") + + lines = [""] + for s in all_skills: + name = escape_xml(s["name"]) + path = s["path"] + desc = escape_xml(self._get_skill_description(s["name"])) + skill_meta = self._get_skill_meta(s["name"]) + available = self._check_requirements(skill_meta) + + lines.append(f" ") + lines.append(f" {name}") + lines.append(f" {desc}") + lines.append(f" {path}") + + # Show missing requirements for unavailable skills + if not available: + missing = self._get_missing_requirements(skill_meta) + if missing: + lines.append(f" {escape_xml(missing)}") + + lines.append(" ") + lines.append("") + + return "\n".join(lines) + + def _get_missing_requirements(self, skill_meta: dict) -> str: + """Get a description of missing requirements.""" + missing = [] + requires = skill_meta.get("requires", {}) + for b in requires.get("bins", []): + if not shutil.which(b): + missing.append(f"CLI: {b}") + for env in requires.get("env", []): + if not os.environ.get(env): + missing.append(f"ENV: {env}") + return ", ".join(missing) + + def _get_skill_description(self, name: str) -> str: + """Get the description of a skill from its frontmatter.""" + meta = self.get_skill_metadata(name) + if meta and meta.get("description"): + return meta["description"] + return name # Fallback to skill name + + def _strip_frontmatter(self, content: str) -> str: + """Remove YAML frontmatter from markdown content.""" + if content.startswith("---"): + match = re.match(r"^---\n.*?\n---\n", content, re.DOTALL) + if match: + return content[match.end():].strip() + return content + + def _parse_nanobot_metadata(self, raw: str) -> dict: + """Parse skill metadata JSON from frontmatter (supports nanobot and openclaw keys).""" + try: + data = json.loads(raw) + return data.get("nanobot", data.get("openclaw", {})) if isinstance(data, dict) else {} + except (json.JSONDecodeError, TypeError): + return {} + + def _check_requirements(self, skill_meta: dict) -> bool: + """Check if skill requirements are met (bins, env vars).""" + requires = skill_meta.get("requires", {}) + for b in requires.get("bins", []): + if not shutil.which(b): + return False + for env in requires.get("env", []): + if not os.environ.get(env): + return False + return True + + def _get_skill_meta(self, name: str) -> dict: + """Get nanobot metadata for a skill (cached in frontmatter).""" + meta = self.get_skill_metadata(name) or {} + return self._parse_nanobot_metadata(meta.get("metadata", "")) + + def get_always_skills(self) -> list[str]: + """Get skills marked as always=true that meet requirements.""" + result = [] + for s in self.list_skills(filter_unavailable=True): + meta = self.get_skill_metadata(s["name"]) or {} + skill_meta = self._parse_nanobot_metadata(meta.get("metadata", "")) + if skill_meta.get("always") or meta.get("always"): + result.append(s["name"]) + return result + + def get_skill_metadata(self, name: str) -> dict | None: + """ + Get metadata from a skill's frontmatter. + + Args: + name: Skill name. + + Returns: + Metadata dict or None. + """ + content = self.load_skill(name) + if not content: + return None + + if content.startswith("---"): + match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL) + if match: + # Simple YAML parsing + metadata = {} + for line in match.group(1).split("\n"): + if ":" in line: + key, value = line.split(":", 1) + metadata[key.strip()] = value.strip().strip('"\'') + return metadata + + return None diff --git a/core/nanobot/nanobot/agent/subagent.py b/core/nanobot/nanobot/agent/subagent.py new file mode 100644 index 0000000..eb3b3b0 --- /dev/null +++ b/core/nanobot/nanobot/agent/subagent.py @@ -0,0 +1,231 @@ +"""Subagent manager for background task execution.""" + +import asyncio +import json +import uuid +from pathlib import Path +from typing import Any + +from loguru import logger + +from nanobot.agent.tools.filesystem import EditFileTool, ListDirTool, ReadFileTool, WriteFileTool +from nanobot.agent.tools.registry import ToolRegistry +from nanobot.agent.tools.shell import ExecTool +from nanobot.agent.tools.web import WebFetchTool, WebSearchTool +from nanobot.bus.events import InboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.config.schema import ExecToolConfig +from nanobot.providers.base import LLMProvider +from nanobot.utils.helpers import build_assistant_message + + +class SubagentManager: + """Manages background subagent execution.""" + + def __init__( + self, + provider: LLMProvider, + workspace: Path, + bus: MessageBus, + model: str | None = None, + brave_api_key: str | None = None, + web_proxy: str | None = None, + exec_config: "ExecToolConfig | None" = None, + restrict_to_workspace: bool = False, + ): + from nanobot.config.schema import ExecToolConfig + self.provider = provider + self.workspace = workspace + self.bus = bus + self.model = model or provider.get_default_model() + self.brave_api_key = brave_api_key + self.web_proxy = web_proxy + self.exec_config = exec_config or ExecToolConfig() + self.restrict_to_workspace = restrict_to_workspace + self._running_tasks: dict[str, asyncio.Task[None]] = {} + self._session_tasks: dict[str, set[str]] = {} # session_key -> {task_id, ...} + + async def spawn( + self, + task: str, + label: str | None = None, + origin_channel: str = "cli", + origin_chat_id: str = "direct", + session_key: str | None = None, + ) -> str: + """Spawn a subagent to execute a task in the background.""" + task_id = str(uuid.uuid4())[:8] + display_label = label or task[:30] + ("..." if len(task) > 30 else "") + origin = {"channel": origin_channel, "chat_id": origin_chat_id} + + bg_task = asyncio.create_task( + self._run_subagent(task_id, task, display_label, origin) + ) + self._running_tasks[task_id] = bg_task + if session_key: + self._session_tasks.setdefault(session_key, set()).add(task_id) + + def _cleanup(_: asyncio.Task) -> None: + self._running_tasks.pop(task_id, None) + if session_key and (ids := self._session_tasks.get(session_key)): + ids.discard(task_id) + if not ids: + del self._session_tasks[session_key] + + bg_task.add_done_callback(_cleanup) + + logger.info("Spawned subagent [{}]: {}", task_id, display_label) + return f"Subagent [{display_label}] started (id: {task_id}). I'll notify you when it completes." + + async def _run_subagent( + self, + task_id: str, + task: str, + label: str, + origin: dict[str, str], + ) -> None: + """Execute the subagent task and announce the result.""" + logger.info("Subagent [{}] starting task: {}", task_id, label) + + try: + # Build subagent tools (no message tool, no spawn tool) + tools = ToolRegistry() + allowed_dir = self.workspace if self.restrict_to_workspace else None + tools.register(ReadFileTool(workspace=self.workspace, allowed_dir=allowed_dir)) + tools.register(WriteFileTool(workspace=self.workspace, allowed_dir=allowed_dir)) + tools.register(EditFileTool(workspace=self.workspace, allowed_dir=allowed_dir)) + tools.register(ListDirTool(workspace=self.workspace, allowed_dir=allowed_dir)) + tools.register(ExecTool( + working_dir=str(self.workspace), + timeout=self.exec_config.timeout, + restrict_to_workspace=self.restrict_to_workspace, + path_append=self.exec_config.path_append, + )) + tools.register(WebSearchTool(api_key=self.brave_api_key, proxy=self.web_proxy)) + tools.register(WebFetchTool(proxy=self.web_proxy)) + + system_prompt = self._build_subagent_prompt() + messages: list[dict[str, Any]] = [ + {"role": "system", "content": system_prompt}, + {"role": "user", "content": task}, + ] + + # Run agent loop (limited iterations) + max_iterations = 15 + iteration = 0 + final_result: str | None = None + + while iteration < max_iterations: + iteration += 1 + + response = await self.provider.chat_with_retry( + messages=messages, + tools=tools.get_definitions(), + model=self.model, + ) + + if response.has_tool_calls: + tool_call_dicts = [ + tc.to_openai_tool_call() + for tc in response.tool_calls + ] + messages.append(build_assistant_message( + response.content or "", + tool_calls=tool_call_dicts, + reasoning_content=response.reasoning_content, + thinking_blocks=response.thinking_blocks, + )) + + # Execute tools + for tool_call in response.tool_calls: + args_str = json.dumps(tool_call.arguments, ensure_ascii=False) + logger.debug("Subagent [{}] executing: {} with arguments: {}", task_id, tool_call.name, args_str) + result = await tools.execute(tool_call.name, tool_call.arguments) + messages.append({ + "role": "tool", + "tool_call_id": tool_call.id, + "name": tool_call.name, + "content": result, + }) + else: + final_result = response.content + break + + if final_result is None: + final_result = "Task completed but no final response was generated." + + logger.info("Subagent [{}] completed successfully", task_id) + await self._announce_result(task_id, label, task, final_result, origin, "ok") + + except Exception as e: + error_msg = f"Error: {str(e)}" + logger.error("Subagent [{}] failed: {}", task_id, e) + await self._announce_result(task_id, label, task, error_msg, origin, "error") + + async def _announce_result( + self, + task_id: str, + label: str, + task: str, + result: str, + origin: dict[str, str], + status: str, + ) -> None: + """Announce the subagent result to the main agent via the message bus.""" + status_text = "completed successfully" if status == "ok" else "failed" + + announce_content = f"""[Subagent '{label}' {status_text}] + +Task: {task} + +Result: +{result} + +Summarize this naturally for the user. Keep it brief (1-2 sentences). Do not mention technical details like "subagent" or task IDs.""" + + # Inject as system message to trigger main agent + msg = InboundMessage( + channel="system", + sender_id="subagent", + chat_id=f"{origin['channel']}:{origin['chat_id']}", + content=announce_content, + ) + + await self.bus.publish_inbound(msg) + logger.debug("Subagent [{}] announced result to {}:{}", task_id, origin['channel'], origin['chat_id']) + + def _build_subagent_prompt(self) -> str: + """Build a focused system prompt for the subagent.""" + from nanobot.agent.context import ContextBuilder + from nanobot.agent.skills import SkillsLoader + + time_ctx = ContextBuilder._build_runtime_context(None, None) + parts = [f"""# Subagent + +{time_ctx} + +You are a subagent spawned by the main agent to complete a specific task. +Stay focused on the assigned task. Your final response will be reported back to the main agent. + +## Workspace +{self.workspace}"""] + + skills_summary = SkillsLoader(self.workspace).build_skills_summary() + if skills_summary: + parts.append(f"## Skills\n\nRead SKILL.md with read_file to use a skill.\n\n{skills_summary}") + + return "\n\n".join(parts) + + async def cancel_by_session(self, session_key: str) -> int: + """Cancel all subagents for the given session. Returns count cancelled.""" + tasks = [self._running_tasks[tid] for tid in self._session_tasks.get(session_key, []) + if tid in self._running_tasks and not self._running_tasks[tid].done()] + for t in tasks: + t.cancel() + if tasks: + await asyncio.gather(*tasks, return_exceptions=True) + return len(tasks) + + def get_running_count(self) -> int: + """Return the number of currently running subagents.""" + return len(self._running_tasks) diff --git a/core/nanobot/nanobot/agent/tools/__init__.py b/core/nanobot/nanobot/agent/tools/__init__.py new file mode 100644 index 0000000..aac5d7d --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/__init__.py @@ -0,0 +1,6 @@ +"""Agent tools module.""" + +from nanobot.agent.tools.base import Tool +from nanobot.agent.tools.registry import ToolRegistry + +__all__ = ["Tool", "ToolRegistry"] diff --git a/core/nanobot/nanobot/agent/tools/base.py b/core/nanobot/nanobot/agent/tools/base.py new file mode 100644 index 0000000..06f5bdd --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/base.py @@ -0,0 +1,181 @@ +"""Base class for agent tools.""" + +from abc import ABC, abstractmethod +from typing import Any + + +class Tool(ABC): + """ + Abstract base class for agent tools. + + Tools are capabilities that the agent can use to interact with + the environment, such as reading files, executing commands, etc. + """ + + _TYPE_MAP = { + "string": str, + "integer": int, + "number": (int, float), + "boolean": bool, + "array": list, + "object": dict, + } + + @property + @abstractmethod + def name(self) -> str: + """Tool name used in function calls.""" + pass + + @property + @abstractmethod + def description(self) -> str: + """Description of what the tool does.""" + pass + + @property + @abstractmethod + def parameters(self) -> dict[str, Any]: + """JSON Schema for tool parameters.""" + pass + + @abstractmethod + async def execute(self, **kwargs: Any) -> str: + """ + Execute the tool with given parameters. + + Args: + **kwargs: Tool-specific parameters. + + Returns: + String result of the tool execution. + """ + pass + + def cast_params(self, params: dict[str, Any]) -> dict[str, Any]: + """Apply safe schema-driven casts before validation.""" + schema = self.parameters or {} + if schema.get("type", "object") != "object": + return params + + return self._cast_object(params, schema) + + def _cast_object(self, obj: Any, schema: dict[str, Any]) -> dict[str, Any]: + """Cast an object (dict) according to schema.""" + if not isinstance(obj, dict): + return obj + + props = schema.get("properties", {}) + result = {} + + for key, value in obj.items(): + if key in props: + result[key] = self._cast_value(value, props[key]) + else: + result[key] = value + + return result + + def _cast_value(self, val: Any, schema: dict[str, Any]) -> Any: + """Cast a single value according to schema.""" + target_type = schema.get("type") + + if target_type == "boolean" and isinstance(val, bool): + return val + if target_type == "integer" and isinstance(val, int) and not isinstance(val, bool): + return val + if target_type in self._TYPE_MAP and target_type not in ("boolean", "integer", "array", "object"): + expected = self._TYPE_MAP[target_type] + if isinstance(val, expected): + return val + + if target_type == "integer" and isinstance(val, str): + try: + return int(val) + except ValueError: + return val + + if target_type == "number" and isinstance(val, str): + try: + return float(val) + except ValueError: + return val + + if target_type == "string": + return val if val is None else str(val) + + if target_type == "boolean" and isinstance(val, str): + val_lower = val.lower() + if val_lower in ("true", "1", "yes"): + return True + if val_lower in ("false", "0", "no"): + return False + return val + + if target_type == "array" and isinstance(val, list): + item_schema = schema.get("items") + return [self._cast_value(item, item_schema) for item in val] if item_schema else val + + if target_type == "object" and isinstance(val, dict): + return self._cast_object(val, schema) + + return val + + def validate_params(self, params: dict[str, Any]) -> list[str]: + """Validate tool parameters against JSON schema. Returns error list (empty if valid).""" + if not isinstance(params, dict): + return [f"parameters must be an object, got {type(params).__name__}"] + schema = self.parameters or {} + if schema.get("type", "object") != "object": + raise ValueError(f"Schema must be object type, got {schema.get('type')!r}") + return self._validate(params, {**schema, "type": "object"}, "") + + def _validate(self, val: Any, schema: dict[str, Any], path: str) -> list[str]: + t, label = schema.get("type"), path or "parameter" + if t == "integer" and (not isinstance(val, int) or isinstance(val, bool)): + return [f"{label} should be integer"] + if t == "number" and ( + not isinstance(val, self._TYPE_MAP[t]) or isinstance(val, bool) + ): + return [f"{label} should be number"] + if t in self._TYPE_MAP and t not in ("integer", "number") and not isinstance(val, self._TYPE_MAP[t]): + return [f"{label} should be {t}"] + + errors = [] + if "enum" in schema and val not in schema["enum"]: + errors.append(f"{label} must be one of {schema['enum']}") + if t in ("integer", "number"): + if "minimum" in schema and val < schema["minimum"]: + errors.append(f"{label} must be >= {schema['minimum']}") + if "maximum" in schema and val > schema["maximum"]: + errors.append(f"{label} must be <= {schema['maximum']}") + if t == "string": + if "minLength" in schema and len(val) < schema["minLength"]: + errors.append(f"{label} must be at least {schema['minLength']} chars") + if "maxLength" in schema and len(val) > schema["maxLength"]: + errors.append(f"{label} must be at most {schema['maxLength']} chars") + if t == "object": + props = schema.get("properties", {}) + for k in schema.get("required", []): + if k not in val: + errors.append(f"missing required {path + '.' + k if path else k}") + for k, v in val.items(): + if k in props: + errors.extend(self._validate(v, props[k], path + "." + k if path else k)) + if t == "array" and "items" in schema: + for i, item in enumerate(val): + errors.extend( + self._validate(item, schema["items"], f"{path}[{i}]" if path else f"[{i}]") + ) + return errors + + def to_schema(self) -> dict[str, Any]: + """Convert tool to OpenAI function schema format.""" + return { + "type": "function", + "function": { + "name": self.name, + "description": self.description, + "parameters": self.parameters, + }, + } diff --git a/core/nanobot/nanobot/agent/tools/cron.py b/core/nanobot/nanobot/agent/tools/cron.py new file mode 100644 index 0000000..f8e737b --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/cron.py @@ -0,0 +1,158 @@ +"""Cron tool for scheduling reminders and tasks.""" + +from contextvars import ContextVar +from typing import Any + +from nanobot.agent.tools.base import Tool +from nanobot.cron.service import CronService +from nanobot.cron.types import CronSchedule + + +class CronTool(Tool): + """Tool to schedule reminders and recurring tasks.""" + + def __init__(self, cron_service: CronService): + self._cron = cron_service + self._channel = "" + self._chat_id = "" + self._in_cron_context: ContextVar[bool] = ContextVar("cron_in_context", default=False) + + def set_context(self, channel: str, chat_id: str) -> None: + """Set the current session context for delivery.""" + self._channel = channel + self._chat_id = chat_id + + def set_cron_context(self, active: bool): + """Mark whether the tool is executing inside a cron job callback.""" + return self._in_cron_context.set(active) + + def reset_cron_context(self, token) -> None: + """Restore previous cron context.""" + self._in_cron_context.reset(token) + + @property + def name(self) -> str: + return "cron" + + @property + def description(self) -> str: + return "Schedule reminders and recurring tasks. Actions: add, list, remove." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["add", "list", "remove"], + "description": "Action to perform", + }, + "message": {"type": "string", "description": "Reminder message (for add)"}, + "every_seconds": { + "type": "integer", + "description": "Interval in seconds (for recurring tasks)", + }, + "cron_expr": { + "type": "string", + "description": "Cron expression like '0 9 * * *' (for scheduled tasks)", + }, + "tz": { + "type": "string", + "description": "IANA timezone for cron expressions (e.g. 'America/Vancouver')", + }, + "at": { + "type": "string", + "description": "ISO datetime for one-time execution (e.g. '2026-02-12T10:30:00')", + }, + "job_id": {"type": "string", "description": "Job ID (for remove)"}, + }, + "required": ["action"], + } + + async def execute( + self, + action: str, + message: str = "", + every_seconds: int | None = None, + cron_expr: str | None = None, + tz: str | None = None, + at: str | None = None, + job_id: str | None = None, + **kwargs: Any, + ) -> str: + if action == "add": + if self._in_cron_context.get(): + return "Error: cannot schedule new jobs from within a cron job execution" + return self._add_job(message, every_seconds, cron_expr, tz, at) + elif action == "list": + return self._list_jobs() + elif action == "remove": + return self._remove_job(job_id) + return f"Unknown action: {action}" + + def _add_job( + self, + message: str, + every_seconds: int | None, + cron_expr: str | None, + tz: str | None, + at: str | None, + ) -> str: + if not message: + return "Error: message is required for add" + if not self._channel or not self._chat_id: + return "Error: no session context (channel/chat_id)" + if tz and not cron_expr: + return "Error: tz can only be used with cron_expr" + if tz: + from zoneinfo import ZoneInfo + + try: + ZoneInfo(tz) + except (KeyError, Exception): + return f"Error: unknown timezone '{tz}'" + + # Build schedule + delete_after = False + if every_seconds: + schedule = CronSchedule(kind="every", every_ms=every_seconds * 1000) + elif cron_expr: + schedule = CronSchedule(kind="cron", expr=cron_expr, tz=tz) + elif at: + from datetime import datetime + + try: + dt = datetime.fromisoformat(at) + except ValueError: + return f"Error: invalid ISO datetime format '{at}'. Expected format: YYYY-MM-DDTHH:MM:SS" + at_ms = int(dt.timestamp() * 1000) + schedule = CronSchedule(kind="at", at_ms=at_ms) + delete_after = True + else: + return "Error: either every_seconds, cron_expr, or at is required" + + job = self._cron.add_job( + name=message[:30], + schedule=schedule, + message=message, + deliver=True, + channel=self._channel, + to=self._chat_id, + delete_after_run=delete_after, + ) + return f"Created job '{job.name}' (id: {job.id})" + + def _list_jobs(self) -> str: + jobs = self._cron.list_jobs() + if not jobs: + return "No scheduled jobs." + lines = [f"- {j.name} (id: {j.id}, {j.schedule.kind})" for j in jobs] + return "Scheduled jobs:\n" + "\n".join(lines) + + def _remove_job(self, job_id: str | None) -> str: + if not job_id: + return "Error: job_id is required for remove" + if self._cron.remove_job(job_id): + return f"Removed job {job_id}" + return f"Job {job_id} not found" diff --git a/core/nanobot/nanobot/agent/tools/filesystem.py b/core/nanobot/nanobot/agent/tools/filesystem.py new file mode 100644 index 0000000..02c8331 --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/filesystem.py @@ -0,0 +1,365 @@ +"""File system tools: read, write, edit, list.""" + +import difflib +from pathlib import Path +from typing import Any + +from nanobot.agent.tools.base import Tool + + +def _resolve_path( + path: str, workspace: Path | None = None, allowed_dir: Path | None = None +) -> Path: + """Resolve path against workspace (if relative) and enforce directory restriction.""" + p = Path(path).expanduser() + if not p.is_absolute() and workspace: + p = workspace / p + resolved = p.resolve() + if allowed_dir: + try: + resolved.relative_to(allowed_dir.resolve()) + except ValueError: + raise PermissionError(f"Path {path} is outside allowed directory {allowed_dir}") + return resolved + + +class _FsTool(Tool): + """Shared base for filesystem tools — common init and path resolution.""" + + def __init__(self, workspace: Path | None = None, allowed_dir: Path | None = None): + self._workspace = workspace + self._allowed_dir = allowed_dir + + def _resolve(self, path: str) -> Path: + return _resolve_path(path, self._workspace, self._allowed_dir) + + +# --------------------------------------------------------------------------- +# read_file +# --------------------------------------------------------------------------- + +class ReadFileTool(_FsTool): + """Read file contents with optional line-based pagination.""" + + _MAX_CHARS = 128_000 + _DEFAULT_LIMIT = 2000 + + @property + def name(self) -> str: + return "read_file" + + @property + def description(self) -> str: + return ( + "Read the contents of a file. Returns numbered lines. " + "Use offset and limit to paginate through large files." + ) + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "path": {"type": "string", "description": "The file path to read"}, + "offset": { + "type": "integer", + "description": "Line number to start reading from (1-indexed, default 1)", + "minimum": 1, + }, + "limit": { + "type": "integer", + "description": "Maximum number of lines to read (default 2000)", + "minimum": 1, + }, + }, + "required": ["path"], + } + + async def execute(self, path: str, offset: int = 1, limit: int | None = None, **kwargs: Any) -> str: + try: + fp = self._resolve(path) + if not fp.exists(): + return f"Error: File not found: {path}" + if not fp.is_file(): + return f"Error: Not a file: {path}" + + all_lines = fp.read_text(encoding="utf-8").splitlines() + total = len(all_lines) + + if offset < 1: + offset = 1 + if total == 0: + return f"(Empty file: {path})" + if offset > total: + return f"Error: offset {offset} is beyond end of file ({total} lines)" + + start = offset - 1 + end = min(start + (limit or self._DEFAULT_LIMIT), total) + numbered = [f"{start + i + 1}| {line}" for i, line in enumerate(all_lines[start:end])] + result = "\n".join(numbered) + + if len(result) > self._MAX_CHARS: + trimmed, chars = [], 0 + for line in numbered: + chars += len(line) + 1 + if chars > self._MAX_CHARS: + break + trimmed.append(line) + end = start + len(trimmed) + result = "\n".join(trimmed) + + if end < total: + result += f"\n\n(Showing lines {offset}-{end} of {total}. Use offset={end + 1} to continue.)" + else: + result += f"\n\n(End of file — {total} lines total)" + return result + except PermissionError as e: + return f"Error: {e}" + except Exception as e: + return f"Error reading file: {e}" + + +# --------------------------------------------------------------------------- +# write_file +# --------------------------------------------------------------------------- + +class WriteFileTool(_FsTool): + """Write content to a file.""" + + @property + def name(self) -> str: + return "write_file" + + @property + def description(self) -> str: + return "Write content to a file at the given path. Creates parent directories if needed." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "path": {"type": "string", "description": "The file path to write to"}, + "content": {"type": "string", "description": "The content to write"}, + }, + "required": ["path", "content"], + } + + async def execute(self, path: str, content: str, **kwargs: Any) -> str: + try: + fp = self._resolve(path) + fp.parent.mkdir(parents=True, exist_ok=True) + fp.write_text(content, encoding="utf-8") + return f"Successfully wrote {len(content)} bytes to {fp}" + except PermissionError as e: + return f"Error: {e}" + except Exception as e: + return f"Error writing file: {e}" + + +# --------------------------------------------------------------------------- +# edit_file +# --------------------------------------------------------------------------- + +def _find_match(content: str, old_text: str) -> tuple[str | None, int]: + """Locate old_text in content: exact first, then line-trimmed sliding window. + + Both inputs should use LF line endings (caller normalises CRLF). + Returns (matched_fragment, count) or (None, 0). + """ + if old_text in content: + return old_text, content.count(old_text) + + old_lines = old_text.splitlines() + if not old_lines: + return None, 0 + stripped_old = [l.strip() for l in old_lines] + content_lines = content.splitlines() + + candidates = [] + for i in range(len(content_lines) - len(stripped_old) + 1): + window = content_lines[i : i + len(stripped_old)] + if [l.strip() for l in window] == stripped_old: + candidates.append("\n".join(window)) + + if candidates: + return candidates[0], len(candidates) + return None, 0 + + +class EditFileTool(_FsTool): + """Edit a file by replacing text with fallback matching.""" + + @property + def name(self) -> str: + return "edit_file" + + @property + def description(self) -> str: + return ( + "Edit a file by replacing old_text with new_text. " + "Supports minor whitespace/line-ending differences. " + "Set replace_all=true to replace every occurrence." + ) + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "path": {"type": "string", "description": "The file path to edit"}, + "old_text": {"type": "string", "description": "The text to find and replace"}, + "new_text": {"type": "string", "description": "The text to replace with"}, + "replace_all": { + "type": "boolean", + "description": "Replace all occurrences (default false)", + }, + }, + "required": ["path", "old_text", "new_text"], + } + + async def execute( + self, path: str, old_text: str, new_text: str, + replace_all: bool = False, **kwargs: Any, + ) -> str: + try: + fp = self._resolve(path) + if not fp.exists(): + return f"Error: File not found: {path}" + + raw = fp.read_bytes() + uses_crlf = b"\r\n" in raw + content = raw.decode("utf-8").replace("\r\n", "\n") + match, count = _find_match(content, old_text.replace("\r\n", "\n")) + + if match is None: + return self._not_found_msg(old_text, content, path) + if count > 1 and not replace_all: + return ( + f"Warning: old_text appears {count} times. " + "Provide more context to make it unique, or set replace_all=true." + ) + + norm_new = new_text.replace("\r\n", "\n") + new_content = content.replace(match, norm_new) if replace_all else content.replace(match, norm_new, 1) + if uses_crlf: + new_content = new_content.replace("\n", "\r\n") + + fp.write_bytes(new_content.encode("utf-8")) + return f"Successfully edited {fp}" + except PermissionError as e: + return f"Error: {e}" + except Exception as e: + return f"Error editing file: {e}" + + @staticmethod + def _not_found_msg(old_text: str, content: str, path: str) -> str: + lines = content.splitlines(keepends=True) + old_lines = old_text.splitlines(keepends=True) + window = len(old_lines) + + best_ratio, best_start = 0.0, 0 + for i in range(max(1, len(lines) - window + 1)): + ratio = difflib.SequenceMatcher(None, old_lines, lines[i : i + window]).ratio() + if ratio > best_ratio: + best_ratio, best_start = ratio, i + + if best_ratio > 0.5: + diff = "\n".join(difflib.unified_diff( + old_lines, lines[best_start : best_start + window], + fromfile="old_text (provided)", + tofile=f"{path} (actual, line {best_start + 1})", + lineterm="", + )) + return f"Error: old_text not found in {path}.\nBest match ({best_ratio:.0%} similar) at line {best_start + 1}:\n{diff}" + return f"Error: old_text not found in {path}. No similar text found. Verify the file content." + + +# --------------------------------------------------------------------------- +# list_dir +# --------------------------------------------------------------------------- + +class ListDirTool(_FsTool): + """List directory contents with optional recursion.""" + + _DEFAULT_MAX = 200 + _IGNORE_DIRS = { + ".git", "node_modules", "__pycache__", ".venv", "venv", + "dist", "build", ".tox", ".mypy_cache", ".pytest_cache", + ".ruff_cache", ".coverage", "htmlcov", + } + + @property + def name(self) -> str: + return "list_dir" + + @property + def description(self) -> str: + return ( + "List the contents of a directory. " + "Set recursive=true to explore nested structure. " + "Common noise directories (.git, node_modules, __pycache__, etc.) are auto-ignored." + ) + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "path": {"type": "string", "description": "The directory path to list"}, + "recursive": { + "type": "boolean", + "description": "Recursively list all files (default false)", + }, + "max_entries": { + "type": "integer", + "description": "Maximum entries to return (default 200)", + "minimum": 1, + }, + }, + "required": ["path"], + } + + async def execute( + self, path: str, recursive: bool = False, + max_entries: int | None = None, **kwargs: Any, + ) -> str: + try: + dp = self._resolve(path) + if not dp.exists(): + return f"Error: Directory not found: {path}" + if not dp.is_dir(): + return f"Error: Not a directory: {path}" + + cap = max_entries or self._DEFAULT_MAX + items: list[str] = [] + total = 0 + + if recursive: + for item in sorted(dp.rglob("*")): + if any(p in self._IGNORE_DIRS for p in item.parts): + continue + total += 1 + if len(items) < cap: + rel = item.relative_to(dp) + items.append(f"{rel}/" if item.is_dir() else str(rel)) + else: + for item in sorted(dp.iterdir()): + if item.name in self._IGNORE_DIRS: + continue + total += 1 + if len(items) < cap: + pfx = "📁 " if item.is_dir() else "📄 " + items.append(f"{pfx}{item.name}") + + if not items and total == 0: + return f"Directory {path} is empty" + + result = "\n".join(items) + if total > cap: + result += f"\n\n(truncated, showing first {cap} of {total} entries)" + return result + except PermissionError as e: + return f"Error: {e}" + except Exception as e: + return f"Error listing directory: {e}" diff --git a/core/nanobot/nanobot/agent/tools/mcp.py b/core/nanobot/nanobot/agent/tools/mcp.py new file mode 100644 index 0000000..400979b --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/mcp.py @@ -0,0 +1,148 @@ +"""MCP client: connects to MCP servers and wraps their tools as native nanobot tools.""" + +import asyncio +from contextlib import AsyncExitStack +from typing import Any + +import httpx +from loguru import logger + +from nanobot.agent.tools.base import Tool +from nanobot.agent.tools.registry import ToolRegistry + + +class MCPToolWrapper(Tool): + """Wraps a single MCP server tool as a nanobot Tool.""" + + def __init__(self, session, server_name: str, tool_def, tool_timeout: int = 30): + self._session = session + self._original_name = tool_def.name + self._name = f"mcp_{server_name}_{tool_def.name}" + self._description = tool_def.description or tool_def.name + self._parameters = tool_def.inputSchema or {"type": "object", "properties": {}} + self._tool_timeout = tool_timeout + + @property + def name(self) -> str: + return self._name + + @property + def description(self) -> str: + return self._description + + @property + def parameters(self) -> dict[str, Any]: + return self._parameters + + async def execute(self, **kwargs: Any) -> str: + from mcp import types + + try: + result = await asyncio.wait_for( + self._session.call_tool(self._original_name, arguments=kwargs), + timeout=self._tool_timeout, + ) + except asyncio.TimeoutError: + logger.warning("MCP tool '{}' timed out after {}s", self._name, self._tool_timeout) + return f"(MCP tool call timed out after {self._tool_timeout}s)" + except asyncio.CancelledError: + # MCP SDK's anyio cancel scopes can leak CancelledError on timeout/failure. + # Re-raise only if our task was externally cancelled (e.g. /stop). + task = asyncio.current_task() + if task is not None and task.cancelling() > 0: + raise + logger.warning("MCP tool '{}' was cancelled by server/SDK", self._name) + return "(MCP tool call was cancelled)" + except Exception as exc: + logger.exception( + "MCP tool '{}' failed: {}: {}", + self._name, + type(exc).__name__, + exc, + ) + return f"(MCP tool call failed: {type(exc).__name__})" + + parts = [] + for block in result.content: + if isinstance(block, types.TextContent): + parts.append(block.text) + else: + parts.append(str(block)) + return "\n".join(parts) or "(no output)" + + +async def connect_mcp_servers( + mcp_servers: dict, registry: ToolRegistry, stack: AsyncExitStack +) -> None: + """Connect to configured MCP servers and register their tools.""" + from mcp import ClientSession, StdioServerParameters + from mcp.client.sse import sse_client + from mcp.client.stdio import stdio_client + from mcp.client.streamable_http import streamable_http_client + + for name, cfg in mcp_servers.items(): + try: + transport_type = cfg.type + if not transport_type: + if cfg.command: + transport_type = "stdio" + elif cfg.url: + # Convention: URLs ending with /sse use SSE transport; others use streamableHttp + transport_type = ( + "sse" if cfg.url.rstrip("/").endswith("/sse") else "streamableHttp" + ) + else: + logger.warning("MCP server '{}': no command or url configured, skipping", name) + continue + + if transport_type == "stdio": + params = StdioServerParameters( + command=cfg.command, args=cfg.args, env=cfg.env or None + ) + read, write = await stack.enter_async_context(stdio_client(params)) + elif transport_type == "sse": + def httpx_client_factory( + headers: dict[str, str] | None = None, + timeout: httpx.Timeout | None = None, + auth: httpx.Auth | None = None, + ) -> httpx.AsyncClient: + merged_headers = {**(cfg.headers or {}), **(headers or {})} + return httpx.AsyncClient( + headers=merged_headers or None, + follow_redirects=True, + timeout=timeout, + auth=auth, + ) + + read, write = await stack.enter_async_context( + sse_client(cfg.url, httpx_client_factory=httpx_client_factory) + ) + elif transport_type == "streamableHttp": + # Always provide an explicit httpx client so MCP HTTP transport does not + # inherit httpx's default 5s timeout and preempt the higher-level tool timeout. + http_client = await stack.enter_async_context( + httpx.AsyncClient( + headers=cfg.headers or None, + follow_redirects=True, + timeout=None, + ) + ) + read, write, _ = await stack.enter_async_context( + streamable_http_client(cfg.url, http_client=http_client) + ) + else: + logger.warning("MCP server '{}': unknown transport type '{}'", name, transport_type) + continue + + session = await stack.enter_async_context(ClientSession(read, write)) + await session.initialize() + + tools = await session.list_tools() + for tool_def in tools.tools: + wrapper = MCPToolWrapper(session, name, tool_def, tool_timeout=cfg.tool_timeout) + registry.register(wrapper) + logger.debug("MCP: registered tool '{}' from server '{}'", wrapper.name, name) + + logger.info("MCP server '{}': connected, {} tools registered", name, len(tools.tools)) + except Exception as e: + logger.error("MCP server '{}': failed to connect: {}", name, e) diff --git a/core/nanobot/nanobot/agent/tools/message.py b/core/nanobot/nanobot/agent/tools/message.py new file mode 100644 index 0000000..0a52427 --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/message.py @@ -0,0 +1,109 @@ +"""Message tool for sending messages to users.""" + +from typing import Any, Awaitable, Callable + +from nanobot.agent.tools.base import Tool +from nanobot.bus.events import OutboundMessage + + +class MessageTool(Tool): + """Tool to send messages to users on chat channels.""" + + def __init__( + self, + send_callback: Callable[[OutboundMessage], Awaitable[None]] | None = None, + default_channel: str = "", + default_chat_id: str = "", + default_message_id: str | None = None, + ): + self._send_callback = send_callback + self._default_channel = default_channel + self._default_chat_id = default_chat_id + self._default_message_id = default_message_id + self._sent_in_turn: bool = False + + def set_context(self, channel: str, chat_id: str, message_id: str | None = None) -> None: + """Set the current message context.""" + self._default_channel = channel + self._default_chat_id = chat_id + self._default_message_id = message_id + + def set_send_callback(self, callback: Callable[[OutboundMessage], Awaitable[None]]) -> None: + """Set the callback for sending messages.""" + self._send_callback = callback + + def start_turn(self) -> None: + """Reset per-turn send tracking.""" + self._sent_in_turn = False + + @property + def name(self) -> str: + return "message" + + @property + def description(self) -> str: + return "Send a message to the user. Use this when you want to communicate something." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "The message content to send" + }, + "channel": { + "type": "string", + "description": "Optional: target channel (telegram, discord, etc.)" + }, + "chat_id": { + "type": "string", + "description": "Optional: target chat/user ID" + }, + "media": { + "type": "array", + "items": {"type": "string"}, + "description": "Optional: list of file paths to attach (images, audio, documents)" + } + }, + "required": ["content"] + } + + async def execute( + self, + content: str, + channel: str | None = None, + chat_id: str | None = None, + message_id: str | None = None, + media: list[str] | None = None, + **kwargs: Any + ) -> str: + channel = channel or self._default_channel + chat_id = chat_id or self._default_chat_id + message_id = message_id or self._default_message_id + + if not channel or not chat_id: + return "Error: No target channel/chat specified" + + if not self._send_callback: + return "Error: Message sending not configured" + + msg = OutboundMessage( + channel=channel, + chat_id=chat_id, + content=content, + media=media or [], + metadata={ + "message_id": message_id, + }, + ) + + try: + await self._send_callback(msg) + if channel == self._default_channel and chat_id == self._default_chat_id: + self._sent_in_turn = True + media_info = f" with {len(media)} attachments" if media else "" + return f"Message sent to {channel}:{chat_id}{media_info}" + except Exception as e: + return f"Error sending message: {str(e)}" diff --git a/core/nanobot/nanobot/agent/tools/registry.py b/core/nanobot/nanobot/agent/tools/registry.py new file mode 100644 index 0000000..896491f --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/registry.py @@ -0,0 +1,70 @@ +"""Tool registry for dynamic tool management.""" + +from typing import Any + +from nanobot.agent.tools.base import Tool + + +class ToolRegistry: + """ + Registry for agent tools. + + Allows dynamic registration and execution of tools. + """ + + def __init__(self): + self._tools: dict[str, Tool] = {} + + def register(self, tool: Tool) -> None: + """Register a tool.""" + self._tools[tool.name] = tool + + def unregister(self, name: str) -> None: + """Unregister a tool by name.""" + self._tools.pop(name, None) + + def get(self, name: str) -> Tool | None: + """Get a tool by name.""" + return self._tools.get(name) + + def has(self, name: str) -> bool: + """Check if a tool is registered.""" + return name in self._tools + + def get_definitions(self) -> list[dict[str, Any]]: + """Get all tool definitions in OpenAI format.""" + return [tool.to_schema() for tool in self._tools.values()] + + async def execute(self, name: str, params: dict[str, Any]) -> str: + """Execute a tool by name with given parameters.""" + _HINT = "\n\n[Analyze the error above and try a different approach.]" + + tool = self._tools.get(name) + if not tool: + return f"Error: Tool '{name}' not found. Available: {', '.join(self.tool_names)}" + + try: + # Attempt to cast parameters to match schema types + params = tool.cast_params(params) + + # Validate parameters + errors = tool.validate_params(params) + if errors: + return f"Error: Invalid parameters for tool '{name}': " + "; ".join(errors) + _HINT + result = await tool.execute(**params) + if isinstance(result, str) and result.startswith("Error"): + return result + _HINT + return result + except Exception as e: + return f"Error executing {name}: {str(e)}" + _HINT + + @property + def tool_names(self) -> list[str]: + """Get list of registered tool names.""" + return list(self._tools.keys()) + + def __len__(self) -> int: + return len(self._tools) + + def __contains__(self, name: str) -> bool: + return name in self._tools diff --git a/core/nanobot/nanobot/agent/tools/shell.py b/core/nanobot/nanobot/agent/tools/shell.py new file mode 100644 index 0000000..bf1b082 --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/shell.py @@ -0,0 +1,179 @@ +"""Shell execution tool.""" + +import asyncio +import os +import re +from pathlib import Path +from typing import Any + +from nanobot.agent.tools.base import Tool + + +class ExecTool(Tool): + """Tool to execute shell commands.""" + + def __init__( + self, + timeout: int = 60, + working_dir: str | None = None, + deny_patterns: list[str] | None = None, + allow_patterns: list[str] | None = None, + restrict_to_workspace: bool = False, + path_append: str = "", + ): + self.timeout = timeout + self.working_dir = working_dir + self.deny_patterns = deny_patterns or [ + r"\brm\s+-[rf]{1,2}\b", # rm -r, rm -rf, rm -fr + r"\bdel\s+/[fq]\b", # del /f, del /q + r"\brmdir\s+/s\b", # rmdir /s + r"(?:^|[;&|]\s*)format\b", # format (as standalone command only) + r"\b(mkfs|diskpart)\b", # disk operations + r"\bdd\s+if=", # dd + r">\s*/dev/sd", # write to disk + r"\b(shutdown|reboot|poweroff)\b", # system power + r":\(\)\s*\{.*\};\s*:", # fork bomb + ] + self.allow_patterns = allow_patterns or [] + self.restrict_to_workspace = restrict_to_workspace + self.path_append = path_append + + @property + def name(self) -> str: + return "exec" + + _MAX_TIMEOUT = 600 + _MAX_OUTPUT = 10_000 + + @property + def description(self) -> str: + return "Execute a shell command and return its output. Use with caution." + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "command": { + "type": "string", + "description": "The shell command to execute", + }, + "working_dir": { + "type": "string", + "description": "Optional working directory for the command", + }, + "timeout": { + "type": "integer", + "description": ( + "Timeout in seconds. Increase for long-running commands " + "like compilation or installation (default 60, max 600)." + ), + "minimum": 1, + "maximum": 600, + }, + }, + "required": ["command"], + } + + async def execute( + self, command: str, working_dir: str | None = None, + timeout: int | None = None, **kwargs: Any, + ) -> str: + cwd = working_dir or self.working_dir or os.getcwd() + guard_error = self._guard_command(command, cwd) + if guard_error: + return guard_error + + effective_timeout = min(timeout or self.timeout, self._MAX_TIMEOUT) + + env = os.environ.copy() + if self.path_append: + env["PATH"] = env.get("PATH", "") + os.pathsep + self.path_append + + try: + process = await asyncio.create_subprocess_shell( + command, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + cwd=cwd, + env=env, + ) + + try: + stdout, stderr = await asyncio.wait_for( + process.communicate(), + timeout=effective_timeout, + ) + except asyncio.TimeoutError: + process.kill() + try: + await asyncio.wait_for(process.wait(), timeout=5.0) + except asyncio.TimeoutError: + pass + return f"Error: Command timed out after {effective_timeout} seconds" + + output_parts = [] + + if stdout: + output_parts.append(stdout.decode("utf-8", errors="replace")) + + if stderr: + stderr_text = stderr.decode("utf-8", errors="replace") + if stderr_text.strip(): + output_parts.append(f"STDERR:\n{stderr_text}") + + output_parts.append(f"\nExit code: {process.returncode}") + + result = "\n".join(output_parts) if output_parts else "(no output)" + + # Head + tail truncation to preserve both start and end of output + max_len = self._MAX_OUTPUT + if len(result) > max_len: + half = max_len // 2 + result = ( + result[:half] + + f"\n\n... ({len(result) - max_len:,} chars truncated) ...\n\n" + + result[-half:] + ) + + return result + + except Exception as e: + return f"Error executing command: {str(e)}" + + def _guard_command(self, command: str, cwd: str) -> str | None: + """Best-effort safety guard for potentially destructive commands.""" + cmd = command.strip() + lower = cmd.lower() + + for pattern in self.deny_patterns: + if re.search(pattern, lower): + return "Error: Command blocked by safety guard (dangerous pattern detected)" + + if self.allow_patterns: + if not any(re.search(p, lower) for p in self.allow_patterns): + return "Error: Command blocked by safety guard (not in allowlist)" + + if self.restrict_to_workspace: + if "..\\" in cmd or "../" in cmd: + return "Error: Command blocked by safety guard (path traversal detected)" + + cwd_path = Path(cwd).resolve() + + for raw in self._extract_absolute_paths(cmd): + try: + expanded = os.path.expandvars(raw.strip()) + p = Path(expanded).expanduser().resolve() + except Exception: + continue + if p.is_absolute() and cwd_path not in p.parents and p != cwd_path: + return "Error: Command blocked by safety guard (path outside working dir)" + + return None + + @staticmethod + def _extract_absolute_paths(command: str) -> list[str]: + win_paths = re.findall(r"[A-Za-z]:\\[^\s\"'|><;]+", command) # Windows: C:\... + posix_paths = re.findall(r"(?:^|[\s|>'\"])(/[^\s\"'>;|<]+)", command) # POSIX: /absolute only + home_paths = re.findall(r"(?:^|[\s|>'\"])(~[^\s\"'>;|<]*)", command) # POSIX/Windows home shortcut: ~ + return win_paths + posix_paths + home_paths diff --git a/core/nanobot/nanobot/agent/tools/spawn.py b/core/nanobot/nanobot/agent/tools/spawn.py new file mode 100644 index 0000000..fc62bf8 --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/spawn.py @@ -0,0 +1,63 @@ +"""Spawn tool for creating background subagents.""" + +from typing import TYPE_CHECKING, Any + +from nanobot.agent.tools.base import Tool + +if TYPE_CHECKING: + from nanobot.agent.subagent import SubagentManager + + +class SpawnTool(Tool): + """Tool to spawn a subagent for background task execution.""" + + def __init__(self, manager: "SubagentManager"): + self._manager = manager + self._origin_channel = "cli" + self._origin_chat_id = "direct" + self._session_key = "cli:direct" + + def set_context(self, channel: str, chat_id: str) -> None: + """Set the origin context for subagent announcements.""" + self._origin_channel = channel + self._origin_chat_id = chat_id + self._session_key = f"{channel}:{chat_id}" + + @property + def name(self) -> str: + return "spawn" + + @property + def description(self) -> str: + return ( + "Spawn a subagent to handle a task in the background. " + "Use this for complex or time-consuming tasks that can run independently. " + "The subagent will complete the task and report back when done." + ) + + @property + def parameters(self) -> dict[str, Any]: + return { + "type": "object", + "properties": { + "task": { + "type": "string", + "description": "The task for the subagent to complete", + }, + "label": { + "type": "string", + "description": "Optional short label for the task (for display)", + }, + }, + "required": ["task"], + } + + async def execute(self, task: str, label: str | None = None, **kwargs: Any) -> str: + """Spawn a subagent to execute the given task.""" + return await self._manager.spawn( + task=task, + label=label, + origin_channel=self._origin_channel, + origin_chat_id=self._origin_chat_id, + session_key=self._session_key, + ) diff --git a/core/nanobot/nanobot/agent/tools/web.py b/core/nanobot/nanobot/agent/tools/web.py new file mode 100644 index 0000000..0d8f4d1 --- /dev/null +++ b/core/nanobot/nanobot/agent/tools/web.py @@ -0,0 +1,181 @@ +"""Web tools: web_search and web_fetch.""" + +import html +import json +import os +import re +from typing import Any +from urllib.parse import urlparse + +import httpx +from loguru import logger + +from nanobot.agent.tools.base import Tool + +# Shared constants +USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36" +MAX_REDIRECTS = 5 # Limit redirects to prevent DoS attacks + + +def _strip_tags(text: str) -> str: + """Remove HTML tags and decode entities.""" + text = re.sub(r'', '', text, flags=re.I) + text = re.sub(r'', '', text, flags=re.I) + text = re.sub(r'<[^>]+>', '', text) + return html.unescape(text).strip() + + +def _normalize(text: str) -> str: + """Normalize whitespace.""" + text = re.sub(r'[ \t]+', ' ', text) + return re.sub(r'\n{3,}', '\n\n', text).strip() + + +def _validate_url(url: str) -> tuple[bool, str]: + """Validate URL: must be http(s) with valid domain.""" + try: + p = urlparse(url) + if p.scheme not in ('http', 'https'): + return False, f"Only http/https allowed, got '{p.scheme or 'none'}'" + if not p.netloc: + return False, "Missing domain" + return True, "" + except Exception as e: + return False, str(e) + + +class WebSearchTool(Tool): + """Search the web using Brave Search API.""" + + name = "web_search" + description = "Search the web. Returns titles, URLs, and snippets." + parameters = { + "type": "object", + "properties": { + "query": {"type": "string", "description": "Search query"}, + "count": {"type": "integer", "description": "Results (1-10)", "minimum": 1, "maximum": 10} + }, + "required": ["query"] + } + + def __init__(self, api_key: str | None = None, max_results: int = 5, proxy: str | None = None): + self._init_api_key = api_key + self.max_results = max_results + self.proxy = proxy + + @property + def api_key(self) -> str: + """Resolve API key at call time so env/config changes are picked up.""" + return self._init_api_key or os.environ.get("BRAVE_API_KEY", "") + + async def execute(self, query: str, count: int | None = None, **kwargs: Any) -> str: + if not self.api_key: + return ( + "Error: Brave Search API key not configured. Set it in " + "~/.nanobot/config.json under tools.web.search.apiKey " + "(or export BRAVE_API_KEY), then restart the gateway." + ) + + try: + n = min(max(count or self.max_results, 1), 10) + logger.debug("WebSearch: {}", "proxy enabled" if self.proxy else "direct connection") + async with httpx.AsyncClient(proxy=self.proxy) as client: + r = await client.get( + "https://api.search.brave.com/res/v1/web/search", + params={"q": query, "count": n}, + headers={"Accept": "application/json", "X-Subscription-Token": self.api_key}, + timeout=10.0 + ) + r.raise_for_status() + + results = r.json().get("web", {}).get("results", [])[:n] + if not results: + return f"No results for: {query}" + + lines = [f"Results for: {query}\n"] + for i, item in enumerate(results, 1): + lines.append(f"{i}. {item.get('title', '')}\n {item.get('url', '')}") + if desc := item.get("description"): + lines.append(f" {desc}") + return "\n".join(lines) + except httpx.ProxyError as e: + logger.error("WebSearch proxy error: {}", e) + return f"Proxy error: {e}" + except Exception as e: + logger.error("WebSearch error: {}", e) + return f"Error: {e}" + + +class WebFetchTool(Tool): + """Fetch and extract content from a URL using Readability.""" + + name = "web_fetch" + description = "Fetch URL and extract readable content (HTML → markdown/text)." + parameters = { + "type": "object", + "properties": { + "url": {"type": "string", "description": "URL to fetch"}, + "extractMode": {"type": "string", "enum": ["markdown", "text"], "default": "markdown"}, + "maxChars": {"type": "integer", "minimum": 100} + }, + "required": ["url"] + } + + def __init__(self, max_chars: int = 50000, proxy: str | None = None): + self.max_chars = max_chars + self.proxy = proxy + + async def execute(self, url: str, extractMode: str = "markdown", maxChars: int | None = None, **kwargs: Any) -> str: + from readability import Document + + max_chars = maxChars or self.max_chars + is_valid, error_msg = _validate_url(url) + if not is_valid: + return json.dumps({"error": f"URL validation failed: {error_msg}", "url": url}, ensure_ascii=False) + + try: + logger.debug("WebFetch: {}", "proxy enabled" if self.proxy else "direct connection") + async with httpx.AsyncClient( + follow_redirects=True, + max_redirects=MAX_REDIRECTS, + timeout=30.0, + proxy=self.proxy, + ) as client: + r = await client.get(url, headers={"User-Agent": USER_AGENT}) + r.raise_for_status() + + ctype = r.headers.get("content-type", "") + + if "application/json" in ctype: + text, extractor = json.dumps(r.json(), indent=2, ensure_ascii=False), "json" + elif "text/html" in ctype or r.text[:256].lower().startswith((" max_chars + if truncated: text = text[:max_chars] + + return json.dumps({"url": url, "finalUrl": str(r.url), "status": r.status_code, + "extractor": extractor, "truncated": truncated, "length": len(text), "text": text}, ensure_ascii=False) + except httpx.ProxyError as e: + logger.error("WebFetch proxy error for {}: {}", url, e) + return json.dumps({"error": f"Proxy error: {e}", "url": url}, ensure_ascii=False) + except Exception as e: + logger.error("WebFetch error for {}: {}", url, e) + return json.dumps({"error": str(e), "url": url}, ensure_ascii=False) + + def _to_markdown(self, html: str) -> str: + """Convert HTML to markdown.""" + # Convert links, headings, lists before stripping tags + text = re.sub(r']*href=["\']([^"\']+)["\'][^>]*>([\s\S]*?)', + lambda m: f'[{_strip_tags(m[2])}]({m[1]})', html, flags=re.I) + text = re.sub(r']*>([\s\S]*?)', + lambda m: f'\n{"#" * int(m[1])} {_strip_tags(m[2])}\n', text, flags=re.I) + text = re.sub(r']*>([\s\S]*?)', lambda m: f'\n- {_strip_tags(m[1])}', text, flags=re.I) + text = re.sub(r'', '\n\n', text, flags=re.I) + text = re.sub(r'<(br|hr)\s*/?>', '\n', text, flags=re.I) + return _normalize(_strip_tags(text)) diff --git a/core/nanobot/nanobot/bus/__init__.py b/core/nanobot/nanobot/bus/__init__.py new file mode 100644 index 0000000..c7b282d --- /dev/null +++ b/core/nanobot/nanobot/bus/__init__.py @@ -0,0 +1,6 @@ +"""Message bus module for decoupled channel-agent communication.""" + +from nanobot.bus.events import InboundMessage, OutboundMessage +from nanobot.bus.queue import MessageBus + +__all__ = ["MessageBus", "InboundMessage", "OutboundMessage"] diff --git a/core/nanobot/nanobot/bus/events.py b/core/nanobot/nanobot/bus/events.py new file mode 100644 index 0000000..018c25b --- /dev/null +++ b/core/nanobot/nanobot/bus/events.py @@ -0,0 +1,38 @@ +"""Event types for the message bus.""" + +from dataclasses import dataclass, field +from datetime import datetime +from typing import Any + + +@dataclass +class InboundMessage: + """Message received from a chat channel.""" + + channel: str # telegram, discord, slack, whatsapp + sender_id: str # User identifier + chat_id: str # Chat/channel identifier + content: str # Message text + timestamp: datetime = field(default_factory=datetime.now) + media: list[str] = field(default_factory=list) # Media URLs + metadata: dict[str, Any] = field(default_factory=dict) # Channel-specific data + session_key_override: str | None = None # Optional override for thread-scoped sessions + + @property + def session_key(self) -> str: + """Unique key for session identification.""" + return self.session_key_override or f"{self.channel}:{self.chat_id}" + + +@dataclass +class OutboundMessage: + """Message to send to a chat channel.""" + + channel: str + chat_id: str + content: str + reply_to: str | None = None + media: list[str] = field(default_factory=list) + metadata: dict[str, Any] = field(default_factory=dict) + + diff --git a/core/nanobot/nanobot/bus/queue.py b/core/nanobot/nanobot/bus/queue.py new file mode 100644 index 0000000..7c0616f --- /dev/null +++ b/core/nanobot/nanobot/bus/queue.py @@ -0,0 +1,44 @@ +"""Async message queue for decoupled channel-agent communication.""" + +import asyncio + +from nanobot.bus.events import InboundMessage, OutboundMessage + + +class MessageBus: + """ + Async message bus that decouples chat channels from the agent core. + + Channels push messages to the inbound queue, and the agent processes + them and pushes responses to the outbound queue. + """ + + def __init__(self): + self.inbound: asyncio.Queue[InboundMessage] = asyncio.Queue() + self.outbound: asyncio.Queue[OutboundMessage] = asyncio.Queue() + + async def publish_inbound(self, msg: InboundMessage) -> None: + """Publish a message from a channel to the agent.""" + await self.inbound.put(msg) + + async def consume_inbound(self) -> InboundMessage: + """Consume the next inbound message (blocks until available).""" + return await self.inbound.get() + + async def publish_outbound(self, msg: OutboundMessage) -> None: + """Publish a response from the agent to channels.""" + await self.outbound.put(msg) + + async def consume_outbound(self) -> OutboundMessage: + """Consume the next outbound message (blocks until available).""" + return await self.outbound.get() + + @property + def inbound_size(self) -> int: + """Number of pending inbound messages.""" + return self.inbound.qsize() + + @property + def outbound_size(self) -> int: + """Number of pending outbound messages.""" + return self.outbound.qsize() diff --git a/core/nanobot/nanobot/channels/__init__.py b/core/nanobot/nanobot/channels/__init__.py new file mode 100644 index 0000000..588169d --- /dev/null +++ b/core/nanobot/nanobot/channels/__init__.py @@ -0,0 +1,6 @@ +"""Chat channels module with plugin architecture.""" + +from nanobot.channels.base import BaseChannel +from nanobot.channels.manager import ChannelManager + +__all__ = ["BaseChannel", "ChannelManager"] diff --git a/core/nanobot/nanobot/channels/base.py b/core/nanobot/nanobot/channels/base.py new file mode 100644 index 0000000..74c540a --- /dev/null +++ b/core/nanobot/nanobot/channels/base.py @@ -0,0 +1,134 @@ +"""Base channel interface for chat platforms.""" + +from __future__ import annotations + +from abc import ABC, abstractmethod +from pathlib import Path +from typing import Any + +from loguru import logger + +from nanobot.bus.events import InboundMessage, OutboundMessage +from nanobot.bus.queue import MessageBus + + +class BaseChannel(ABC): + """ + Abstract base class for chat channel implementations. + + Each channel (Telegram, Discord, etc.) should implement this interface + to integrate with the nanobot message bus. + """ + + name: str = "base" + display_name: str = "Base" + transcription_api_key: str = "" + + def __init__(self, config: Any, bus: MessageBus): + """ + Initialize the channel. + + Args: + config: Channel-specific configuration. + bus: The message bus for communication. + """ + self.config = config + self.bus = bus + self._running = False + + async def transcribe_audio(self, file_path: str | Path) -> str: + """Transcribe an audio file via Groq Whisper. Returns empty string on failure.""" + if not self.transcription_api_key: + return "" + try: + from nanobot.providers.transcription import GroqTranscriptionProvider + + provider = GroqTranscriptionProvider(api_key=self.transcription_api_key) + return await provider.transcribe(file_path) + except Exception as e: + logger.warning("{}: audio transcription failed: {}", self.name, e) + return "" + + @abstractmethod + async def start(self) -> None: + """ + Start the channel and begin listening for messages. + + This should be a long-running async task that: + 1. Connects to the chat platform + 2. Listens for incoming messages + 3. Forwards messages to the bus via _handle_message() + """ + pass + + @abstractmethod + async def stop(self) -> None: + """Stop the channel and clean up resources.""" + pass + + @abstractmethod + async def send(self, msg: OutboundMessage) -> None: + """ + Send a message through this channel. + + Args: + msg: The message to send. + """ + pass + + def is_allowed(self, sender_id: str) -> bool: + """Check if *sender_id* is permitted. Empty list → deny all; ``"*"`` → allow all.""" + allow_list = getattr(self.config, "allow_from", []) + if not allow_list: + logger.warning("{}: allow_from is empty — all access denied", self.name) + return False + if "*" in allow_list: + return True + return str(sender_id) in allow_list + + async def _handle_message( + self, + sender_id: str, + chat_id: str, + content: str, + media: list[str] | None = None, + metadata: dict[str, Any] | None = None, + session_key: str | None = None, + ) -> None: + """ + Handle an incoming message from the chat platform. + + This method checks permissions and forwards to the bus. + + Args: + sender_id: The sender's identifier. + chat_id: The chat/channel identifier. + content: Message text content. + media: Optional list of media URLs. + metadata: Optional channel-specific metadata. + session_key: Optional session key override (e.g. thread-scoped sessions). + """ + if not self.is_allowed(sender_id): + logger.warning( + "Access denied for sender {} on channel {}. " + "Add them to allowFrom list in config to grant access.", + sender_id, self.name, + ) + return + + msg = InboundMessage( + channel=self.name, + sender_id=str(sender_id), + chat_id=str(chat_id), + content=content, + media=media or [], + metadata=metadata or {}, + session_key_override=session_key, + ) + + await self.bus.publish_inbound(msg) + + @property + def is_running(self) -> bool: + """Check if the channel is running.""" + return self._running diff --git a/core/nanobot/nanobot/channels/dingtalk.py b/core/nanobot/nanobot/channels/dingtalk.py new file mode 100644 index 0000000..4626d95 --- /dev/null +++ b/core/nanobot/nanobot/channels/dingtalk.py @@ -0,0 +1,474 @@ +"""DingTalk/DingDing channel implementation using Stream Mode.""" + +import asyncio +import json +import mimetypes +import os +import time +from pathlib import Path +from typing import Any +from urllib.parse import unquote, urlparse + +import httpx +from loguru import logger + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.schema import DingTalkConfig + +try: + from dingtalk_stream import ( + AckMessage, + CallbackHandler, + CallbackMessage, + Credential, + DingTalkStreamClient, + ) + from dingtalk_stream.chatbot import ChatbotMessage + + DINGTALK_AVAILABLE = True +except ImportError: + DINGTALK_AVAILABLE = False + # Fallback so class definitions don't crash at module level + CallbackHandler = object # type: ignore[assignment,misc] + CallbackMessage = None # type: ignore[assignment,misc] + AckMessage = None # type: ignore[assignment,misc] + ChatbotMessage = None # type: ignore[assignment,misc] + + +class NanobotDingTalkHandler(CallbackHandler): + """ + Standard DingTalk Stream SDK Callback Handler. + Parses incoming messages and forwards them to the Nanobot channel. + """ + + def __init__(self, channel: "DingTalkChannel"): + super().__init__() + self.channel = channel + + async def process(self, message: CallbackMessage): + """Process incoming stream message.""" + try: + # Parse using SDK's ChatbotMessage for robust handling + chatbot_msg = ChatbotMessage.from_dict(message.data) + + # Extract text content; fall back to raw dict if SDK object is empty + content = "" + if chatbot_msg.text: + content = chatbot_msg.text.content.strip() + elif chatbot_msg.extensions.get("content", {}).get("recognition"): + content = chatbot_msg.extensions["content"]["recognition"].strip() + if not content: + content = message.data.get("text", {}).get("content", "").strip() + + if not content: + logger.warning( + "Received empty or unsupported message type: {}", + chatbot_msg.message_type, + ) + return AckMessage.STATUS_OK, "OK" + + sender_id = chatbot_msg.sender_staff_id or chatbot_msg.sender_id + sender_name = chatbot_msg.sender_nick or "Unknown" + + conversation_type = message.data.get("conversationType") + conversation_id = ( + message.data.get("conversationId") + or message.data.get("openConversationId") + ) + + logger.info("Received DingTalk message from {} ({}): {}", sender_name, sender_id, content) + + # Forward to Nanobot via _on_message (non-blocking). + # Store reference to prevent GC before task completes. + task = asyncio.create_task( + self.channel._on_message( + content, + sender_id, + sender_name, + conversation_type, + conversation_id, + ) + ) + self.channel._background_tasks.add(task) + task.add_done_callback(self.channel._background_tasks.discard) + + return AckMessage.STATUS_OK, "OK" + + except Exception as e: + logger.error("Error processing DingTalk message: {}", e) + # Return OK to avoid retry loop from DingTalk server + return AckMessage.STATUS_OK, "Error" + + +class DingTalkChannel(BaseChannel): + """ + DingTalk channel using Stream Mode. + + Uses WebSocket to receive events via `dingtalk-stream` SDK. + Uses direct HTTP API to send messages (SDK is mainly for receiving). + + Supports both private (1:1) and group chats. + Group chat_id is stored with a "group:" prefix to route replies back. + """ + + name = "dingtalk" + display_name = "DingTalk" + _IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp"} + _AUDIO_EXTS = {".amr", ".mp3", ".wav", ".ogg", ".m4a", ".aac"} + _VIDEO_EXTS = {".mp4", ".mov", ".avi", ".mkv", ".webm"} + + def __init__(self, config: DingTalkConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: DingTalkConfig = config + self._client: Any = None + self._http: httpx.AsyncClient | None = None + + # Access Token management for sending messages + self._access_token: str | None = None + self._token_expiry: float = 0 + + # Hold references to background tasks to prevent GC + self._background_tasks: set[asyncio.Task] = set() + + async def start(self) -> None: + """Start the DingTalk bot with Stream Mode.""" + try: + if not DINGTALK_AVAILABLE: + logger.error( + "DingTalk Stream SDK not installed. Run: pip install dingtalk-stream" + ) + return + + if not self.config.client_id or not self.config.client_secret: + logger.error("DingTalk client_id and client_secret not configured") + return + + self._running = True + self._http = httpx.AsyncClient() + + logger.info( + "Initializing DingTalk Stream Client with Client ID: {}...", + self.config.client_id, + ) + credential = Credential(self.config.client_id, self.config.client_secret) + self._client = DingTalkStreamClient(credential) + + # Register standard handler + handler = NanobotDingTalkHandler(self) + self._client.register_callback_handler(ChatbotMessage.TOPIC, handler) + + logger.info("DingTalk bot started with Stream Mode") + + # Reconnect loop: restart stream if SDK exits or crashes + while self._running: + try: + await self._client.start() + except Exception as e: + logger.warning("DingTalk stream error: {}", e) + if self._running: + logger.info("Reconnecting DingTalk stream in 5 seconds...") + await asyncio.sleep(5) + + except Exception as e: + logger.exception("Failed to start DingTalk channel: {}", e) + + async def stop(self) -> None: + """Stop the DingTalk bot.""" + self._running = False + # Close the shared HTTP client + if self._http: + await self._http.aclose() + self._http = None + # Cancel outstanding background tasks + for task in self._background_tasks: + task.cancel() + self._background_tasks.clear() + + async def _get_access_token(self) -> str | None: + """Get or refresh Access Token.""" + if self._access_token and time.time() < self._token_expiry: + return self._access_token + + url = "https://api.dingtalk.com/v1.0/oauth2/accessToken" + data = { + "appKey": self.config.client_id, + "appSecret": self.config.client_secret, + } + + if not self._http: + logger.warning("DingTalk HTTP client not initialized, cannot refresh token") + return None + + try: + resp = await self._http.post(url, json=data) + resp.raise_for_status() + res_data = resp.json() + self._access_token = res_data.get("accessToken") + # Expire 60s early to be safe + self._token_expiry = time.time() + int(res_data.get("expireIn", 7200)) - 60 + return self._access_token + except Exception as e: + logger.error("Failed to get DingTalk access token: {}", e) + return None + + @staticmethod + def _is_http_url(value: str) -> bool: + return urlparse(value).scheme in ("http", "https") + + def _guess_upload_type(self, media_ref: str) -> str: + ext = Path(urlparse(media_ref).path).suffix.lower() + if ext in self._IMAGE_EXTS: return "image" + if ext in self._AUDIO_EXTS: return "voice" + if ext in self._VIDEO_EXTS: return "video" + return "file" + + def _guess_filename(self, media_ref: str, upload_type: str) -> str: + name = os.path.basename(urlparse(media_ref).path) + return name or {"image": "image.jpg", "voice": "audio.amr", "video": "video.mp4"}.get(upload_type, "file.bin") + + async def _read_media_bytes( + self, + media_ref: str, + ) -> tuple[bytes | None, str | None, str | None]: + if not media_ref: + return None, None, None + + if self._is_http_url(media_ref): + if not self._http: + return None, None, None + try: + resp = await self._http.get(media_ref, follow_redirects=True) + if resp.status_code >= 400: + logger.warning( + "DingTalk media download failed status={} ref={}", + resp.status_code, + media_ref, + ) + return None, None, None + content_type = (resp.headers.get("content-type") or "").split(";")[0].strip() + filename = self._guess_filename(media_ref, self._guess_upload_type(media_ref)) + return resp.content, filename, content_type or None + except Exception as e: + logger.error("DingTalk media download error ref={} err={}", media_ref, e) + return None, None, None + + try: + if media_ref.startswith("file://"): + parsed = urlparse(media_ref) + local_path = Path(unquote(parsed.path)) + else: + local_path = Path(os.path.expanduser(media_ref)) + if not local_path.is_file(): + logger.warning("DingTalk media file not found: {}", local_path) + return None, None, None + data = await asyncio.to_thread(local_path.read_bytes) + content_type = mimetypes.guess_type(local_path.name)[0] + return data, local_path.name, content_type + except Exception as e: + logger.error("DingTalk media read error ref={} err={}", media_ref, e) + return None, None, None + + async def _upload_media( + self, + token: str, + data: bytes, + media_type: str, + filename: str, + content_type: str | None, + ) -> str | None: + if not self._http: + return None + url = f"https://oapi.dingtalk.com/media/upload?access_token={token}&type={media_type}" + mime = content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream" + files = {"media": (filename, data, mime)} + + try: + resp = await self._http.post(url, files=files) + text = resp.text + result = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {} + if resp.status_code >= 400: + logger.error("DingTalk media upload failed status={} type={} body={}", resp.status_code, media_type, text[:500]) + return None + errcode = result.get("errcode", 0) + if errcode != 0: + logger.error("DingTalk media upload api error type={} errcode={} body={}", media_type, errcode, text[:500]) + return None + sub = result.get("result") or {} + media_id = result.get("media_id") or result.get("mediaId") or sub.get("media_id") or sub.get("mediaId") + if not media_id: + logger.error("DingTalk media upload missing media_id body={}", text[:500]) + return None + return str(media_id) + except Exception as e: + logger.error("DingTalk media upload error type={} err={}", media_type, e) + return None + + async def _send_batch_message( + self, + token: str, + chat_id: str, + msg_key: str, + msg_param: dict[str, Any], + ) -> bool: + if not self._http: + logger.warning("DingTalk HTTP client not initialized, cannot send") + return False + + headers = {"x-acs-dingtalk-access-token": token} + if chat_id.startswith("group:"): + # Group chat + url = "https://api.dingtalk.com/v1.0/robot/groupMessages/send" + payload = { + "robotCode": self.config.client_id, + "openConversationId": chat_id[6:], # Remove "group:" prefix, + "msgKey": msg_key, + "msgParam": json.dumps(msg_param, ensure_ascii=False), + } + else: + # Private chat + url = "https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend" + payload = { + "robotCode": self.config.client_id, + "userIds": [chat_id], + "msgKey": msg_key, + "msgParam": json.dumps(msg_param, ensure_ascii=False), + } + + try: + resp = await self._http.post(url, json=payload, headers=headers) + body = resp.text + if resp.status_code != 200: + logger.error("DingTalk send failed msgKey={} status={} body={}", msg_key, resp.status_code, body[:500]) + return False + try: result = resp.json() + except Exception: result = {} + errcode = result.get("errcode") + if errcode not in (None, 0): + logger.error("DingTalk send api error msgKey={} errcode={} body={}", msg_key, errcode, body[:500]) + return False + logger.debug("DingTalk message sent to {} with msgKey={}", chat_id, msg_key) + return True + except Exception as e: + logger.error("Error sending DingTalk message msgKey={} err={}", msg_key, e) + return False + + async def _send_markdown_text(self, token: str, chat_id: str, content: str) -> bool: + return await self._send_batch_message( + token, + chat_id, + "sampleMarkdown", + {"text": content, "title": "Nanobot Reply"}, + ) + + async def _send_media_ref(self, token: str, chat_id: str, media_ref: str) -> bool: + media_ref = (media_ref or "").strip() + if not media_ref: + return True + + upload_type = self._guess_upload_type(media_ref) + if upload_type == "image" and self._is_http_url(media_ref): + ok = await self._send_batch_message( + token, + chat_id, + "sampleImageMsg", + {"photoURL": media_ref}, + ) + if ok: + return True + logger.warning("DingTalk image url send failed, trying upload fallback: {}", media_ref) + + data, filename, content_type = await self._read_media_bytes(media_ref) + if not data: + logger.error("DingTalk media read failed: {}", media_ref) + return False + + filename = filename or self._guess_filename(media_ref, upload_type) + file_type = Path(filename).suffix.lower().lstrip(".") + if not file_type: + guessed = mimetypes.guess_extension(content_type or "") + file_type = (guessed or ".bin").lstrip(".") + if file_type == "jpeg": + file_type = "jpg" + + media_id = await self._upload_media( + token=token, + data=data, + media_type=upload_type, + filename=filename, + content_type=content_type, + ) + if not media_id: + return False + + if upload_type == "image": + # Verified in production: sampleImageMsg accepts media_id in photoURL. + ok = await self._send_batch_message( + token, + chat_id, + "sampleImageMsg", + {"photoURL": media_id}, + ) + if ok: + return True + logger.warning("DingTalk image media_id send failed, falling back to file: {}", media_ref) + + return await self._send_batch_message( + token, + chat_id, + "sampleFile", + {"mediaId": media_id, "fileName": filename, "fileType": file_type}, + ) + + async def send(self, msg: OutboundMessage) -> None: + """Send a message through DingTalk.""" + token = await self._get_access_token() + if not token: + return + + if msg.content and msg.content.strip(): + await self._send_markdown_text(token, msg.chat_id, msg.content.strip()) + + for media_ref in msg.media or []: + ok = await self._send_media_ref(token, msg.chat_id, media_ref) + if ok: + continue + logger.error("DingTalk media send failed for {}", media_ref) + # Send visible fallback so failures are observable by the user. + filename = self._guess_filename(media_ref, self._guess_upload_type(media_ref)) + await self._send_markdown_text( + token, + msg.chat_id, + f"[Attachment send failed: {filename}]", + ) + + async def _on_message( + self, + content: str, + sender_id: str, + sender_name: str, + conversation_type: str | None = None, + conversation_id: str | None = None, + ) -> None: + """Handle incoming message (called by NanobotDingTalkHandler). + + Delegates to BaseChannel._handle_message() which enforces allow_from + permission checks before publishing to the bus. + """ + try: + logger.info("DingTalk inbound: {} from {}", content, sender_name) + is_group = conversation_type == "2" and conversation_id + chat_id = f"group:{conversation_id}" if is_group else sender_id + await self._handle_message( + sender_id=sender_id, + chat_id=chat_id, + content=str(content), + metadata={ + "sender_name": sender_name, + "platform": "dingtalk", + "conversation_type": conversation_type, + }, + ) + except Exception as e: + logger.error("Error publishing DingTalk message: {}", e) diff --git a/core/nanobot/nanobot/channels/discord.py b/core/nanobot/nanobot/channels/discord.py new file mode 100644 index 0000000..afa20c9 --- /dev/null +++ b/core/nanobot/nanobot/channels/discord.py @@ -0,0 +1,377 @@ +"""Discord channel implementation using Discord Gateway websocket.""" + +import asyncio +import json +from pathlib import Path +from typing import Any + +import httpx +import websockets +from loguru import logger + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.paths import get_media_dir +from nanobot.config.schema import DiscordConfig +from nanobot.utils.helpers import split_message + +DISCORD_API_BASE = "https://discord.com/api/v10" +MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024 # 20MB +MAX_MESSAGE_LEN = 2000 # Discord message character limit + + +class DiscordChannel(BaseChannel): + """Discord channel using Gateway websocket.""" + + name = "discord" + display_name = "Discord" + + def __init__(self, config: DiscordConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: DiscordConfig = config + self._ws: websockets.WebSocketClientProtocol | None = None + self._seq: int | None = None + self._heartbeat_task: asyncio.Task | None = None + self._typing_tasks: dict[str, asyncio.Task] = {} + self._http: httpx.AsyncClient | None = None + self._bot_user_id: str | None = None + + async def start(self) -> None: + """Start the Discord gateway connection.""" + if not self.config.token: + logger.error("Discord bot token not configured") + return + + self._running = True + self._http = httpx.AsyncClient(timeout=30.0) + + while self._running: + try: + logger.info("Connecting to Discord gateway...") + async with websockets.connect(self.config.gateway_url) as ws: + self._ws = ws + await self._gateway_loop() + except asyncio.CancelledError: + break + except Exception as e: + logger.warning("Discord gateway error: {}", e) + if self._running: + logger.info("Reconnecting to Discord gateway in 5 seconds...") + await asyncio.sleep(5) + + async def stop(self) -> None: + """Stop the Discord channel.""" + self._running = False + if self._heartbeat_task: + self._heartbeat_task.cancel() + self._heartbeat_task = None + for task in self._typing_tasks.values(): + task.cancel() + self._typing_tasks.clear() + if self._ws: + await self._ws.close() + self._ws = None + if self._http: + await self._http.aclose() + self._http = None + + async def send(self, msg: OutboundMessage) -> None: + """Send a message through Discord REST API, including file attachments.""" + if not self._http: + logger.warning("Discord HTTP client not initialized") + return + + url = f"{DISCORD_API_BASE}/channels/{msg.chat_id}/messages" + headers = {"Authorization": f"Bot {self.config.token}"} + + try: + sent_media = False + failed_media: list[str] = [] + + # Send file attachments first + for media_path in msg.media or []: + if await self._send_file(url, headers, media_path, reply_to=msg.reply_to): + sent_media = True + else: + failed_media.append(Path(media_path).name) + + # Send text content + chunks = split_message(msg.content or "", MAX_MESSAGE_LEN) + if not chunks and failed_media and not sent_media: + chunks = split_message( + "\n".join(f"[attachment: {name} - send failed]" for name in failed_media), + MAX_MESSAGE_LEN, + ) + if not chunks: + return + + for i, chunk in enumerate(chunks): + payload: dict[str, Any] = {"content": chunk} + + # Let the first successful attachment carry the reply if present. + if i == 0 and msg.reply_to and not sent_media: + payload["message_reference"] = {"message_id": msg.reply_to} + payload["allowed_mentions"] = {"replied_user": False} + + if not await self._send_payload(url, headers, payload): + break # Abort remaining chunks on failure + finally: + await self._stop_typing(msg.chat_id) + + async def _send_payload( + self, url: str, headers: dict[str, str], payload: dict[str, Any] + ) -> bool: + """Send a single Discord API payload with retry on rate-limit. Returns True on success.""" + for attempt in range(3): + try: + response = await self._http.post(url, headers=headers, json=payload) + if response.status_code == 429: + data = response.json() + retry_after = float(data.get("retry_after", 1.0)) + logger.warning("Discord rate limited, retrying in {}s", retry_after) + await asyncio.sleep(retry_after) + continue + response.raise_for_status() + return True + except Exception as e: + if attempt == 2: + logger.error("Error sending Discord message: {}", e) + else: + await asyncio.sleep(1) + return False + + async def _send_file( + self, + url: str, + headers: dict[str, str], + file_path: str, + reply_to: str | None = None, + ) -> bool: + """Send a file attachment via Discord REST API using multipart/form-data.""" + path = Path(file_path) + if not path.is_file(): + logger.warning("Discord file not found, skipping: {}", file_path) + return False + + if path.stat().st_size > MAX_ATTACHMENT_BYTES: + logger.warning("Discord file too large (>20MB), skipping: {}", path.name) + return False + + payload_json: dict[str, Any] = {} + if reply_to: + payload_json["message_reference"] = {"message_id": reply_to} + payload_json["allowed_mentions"] = {"replied_user": False} + + for attempt in range(3): + try: + with open(path, "rb") as f: + files = {"files[0]": (path.name, f, "application/octet-stream")} + data: dict[str, Any] = {} + if payload_json: + data["payload_json"] = json.dumps(payload_json) + response = await self._http.post( + url, headers=headers, files=files, data=data + ) + if response.status_code == 429: + resp_data = response.json() + retry_after = float(resp_data.get("retry_after", 1.0)) + logger.warning("Discord rate limited, retrying in {}s", retry_after) + await asyncio.sleep(retry_after) + continue + response.raise_for_status() + logger.info("Discord file sent: {}", path.name) + return True + except Exception as e: + if attempt == 2: + logger.error("Error sending Discord file {}: {}", path.name, e) + else: + await asyncio.sleep(1) + return False + + async def _gateway_loop(self) -> None: + """Main gateway loop: identify, heartbeat, dispatch events.""" + if not self._ws: + return + + async for raw in self._ws: + try: + data = json.loads(raw) + except json.JSONDecodeError: + logger.warning("Invalid JSON from Discord gateway: {}", raw[:100]) + continue + + op = data.get("op") + event_type = data.get("t") + seq = data.get("s") + payload = data.get("d") + + if seq is not None: + self._seq = seq + + if op == 10: + # HELLO: start heartbeat and identify + interval_ms = payload.get("heartbeat_interval", 45000) + await self._start_heartbeat(interval_ms / 1000) + await self._identify() + elif op == 0 and event_type == "READY": + logger.info("Discord gateway READY") + # Capture bot user ID for mention detection + user_data = payload.get("user") or {} + self._bot_user_id = user_data.get("id") + logger.info("Discord bot connected as user {}", self._bot_user_id) + elif op == 0 and event_type == "MESSAGE_CREATE": + await self._handle_message_create(payload) + elif op == 7: + # RECONNECT: exit loop to reconnect + logger.info("Discord gateway requested reconnect") + break + elif op == 9: + # INVALID_SESSION: reconnect + logger.warning("Discord gateway invalid session") + break + + async def _identify(self) -> None: + """Send IDENTIFY payload.""" + if not self._ws: + return + + identify = { + "op": 2, + "d": { + "token": self.config.token, + "intents": self.config.intents, + "properties": { + "os": "nanobot", + "browser": "nanobot", + "device": "nanobot", + }, + }, + } + await self._ws.send(json.dumps(identify)) + + async def _start_heartbeat(self, interval_s: float) -> None: + """Start or restart the heartbeat loop.""" + if self._heartbeat_task: + self._heartbeat_task.cancel() + + async def heartbeat_loop() -> None: + while self._running and self._ws: + payload = {"op": 1, "d": self._seq} + try: + await self._ws.send(json.dumps(payload)) + except Exception as e: + logger.warning("Discord heartbeat failed: {}", e) + break + await asyncio.sleep(interval_s) + + self._heartbeat_task = asyncio.create_task(heartbeat_loop()) + + async def _handle_message_create(self, payload: dict[str, Any]) -> None: + """Handle incoming Discord messages.""" + author = payload.get("author") or {} + if author.get("bot"): + return + + sender_id = str(author.get("id", "")) + channel_id = str(payload.get("channel_id", "")) + content = payload.get("content") or "" + guild_id = payload.get("guild_id") + + if not sender_id or not channel_id: + return + + if not self.is_allowed(sender_id): + return + + # Check group channel policy (DMs always respond if is_allowed passes) + if guild_id is not None: + if not self._should_respond_in_group(payload, content): + return + + content_parts = [content] if content else [] + media_paths: list[str] = [] + media_dir = get_media_dir("discord") + + for attachment in payload.get("attachments") or []: + url = attachment.get("url") + filename = attachment.get("filename") or "attachment" + size = attachment.get("size") or 0 + if not url or not self._http: + continue + if size and size > MAX_ATTACHMENT_BYTES: + content_parts.append(f"[attachment: {filename} - too large]") + continue + try: + media_dir.mkdir(parents=True, exist_ok=True) + file_path = media_dir / f"{attachment.get('id', 'file')}_{filename.replace('/', '_')}" + resp = await self._http.get(url) + resp.raise_for_status() + file_path.write_bytes(resp.content) + media_paths.append(str(file_path)) + content_parts.append(f"[attachment: {file_path}]") + except Exception as e: + logger.warning("Failed to download Discord attachment: {}", e) + content_parts.append(f"[attachment: {filename} - download failed]") + + reply_to = (payload.get("referenced_message") or {}).get("id") + + await self._start_typing(channel_id) + + await self._handle_message( + sender_id=sender_id, + chat_id=channel_id, + content="\n".join(p for p in content_parts if p) or "[empty message]", + media=media_paths, + metadata={ + "message_id": str(payload.get("id", "")), + "guild_id": guild_id, + "reply_to": reply_to, + }, + ) + + def _should_respond_in_group(self, payload: dict[str, Any], content: str) -> bool: + """Check if bot should respond in a group channel based on policy.""" + if self.config.group_policy == "open": + return True + + if self.config.group_policy == "mention": + # Check if bot was mentioned in the message + if self._bot_user_id: + # Check mentions array + mentions = payload.get("mentions") or [] + for mention in mentions: + if str(mention.get("id")) == self._bot_user_id: + return True + # Also check content for mention format <@USER_ID> + if f"<@{self._bot_user_id}>" in content or f"<@!{self._bot_user_id}>" in content: + return True + logger.debug("Discord message in {} ignored (bot not mentioned)", payload.get("channel_id")) + return False + + return True + + async def _start_typing(self, channel_id: str) -> None: + """Start periodic typing indicator for a channel.""" + await self._stop_typing(channel_id) + + async def typing_loop() -> None: + url = f"{DISCORD_API_BASE}/channels/{channel_id}/typing" + headers = {"Authorization": f"Bot {self.config.token}"} + while self._running: + try: + await self._http.post(url, headers=headers) + except asyncio.CancelledError: + return + except Exception as e: + logger.debug("Discord typing indicator failed for {}: {}", channel_id, e) + return + await asyncio.sleep(8) + + self._typing_tasks[channel_id] = asyncio.create_task(typing_loop()) + + async def _stop_typing(self, channel_id: str) -> None: + """Stop typing indicator for a channel.""" + task = self._typing_tasks.pop(channel_id, None) + if task: + task.cancel() diff --git a/core/nanobot/nanobot/channels/email.py b/core/nanobot/nanobot/channels/email.py new file mode 100644 index 0000000..46c2103 --- /dev/null +++ b/core/nanobot/nanobot/channels/email.py @@ -0,0 +1,409 @@ +"""Email channel implementation using IMAP polling + SMTP replies.""" + +import asyncio +import html +import imaplib +import re +import smtplib +import ssl +from datetime import date +from email import policy +from email.header import decode_header, make_header +from email.message import EmailMessage +from email.parser import BytesParser +from email.utils import parseaddr +from typing import Any + +from loguru import logger + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.schema import EmailConfig + + +class EmailChannel(BaseChannel): + """ + Email channel. + + Inbound: + - Poll IMAP mailbox for unread messages. + - Convert each message into an inbound event. + + Outbound: + - Send responses via SMTP back to the sender address. + """ + + name = "email" + display_name = "Email" + _IMAP_MONTHS = ( + "Jan", + "Feb", + "Mar", + "Apr", + "May", + "Jun", + "Jul", + "Aug", + "Sep", + "Oct", + "Nov", + "Dec", + ) + + def __init__(self, config: EmailConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: EmailConfig = config + self._last_subject_by_chat: dict[str, str] = {} + self._last_message_id_by_chat: dict[str, str] = {} + self._processed_uids: set[str] = set() # Capped to prevent unbounded growth + self._MAX_PROCESSED_UIDS = 100000 + + async def start(self) -> None: + """Start polling IMAP for inbound emails.""" + if not self.config.consent_granted: + logger.warning( + "Email channel disabled: consent_granted is false. " + "Set channels.email.consentGranted=true after explicit user permission." + ) + return + + if not self._validate_config(): + return + + self._running = True + logger.info("Starting Email channel (IMAP polling mode)...") + + poll_seconds = max(5, int(self.config.poll_interval_seconds)) + while self._running: + try: + inbound_items = await asyncio.to_thread(self._fetch_new_messages) + for item in inbound_items: + sender = item["sender"] + subject = item.get("subject", "") + message_id = item.get("message_id", "") + + if subject: + self._last_subject_by_chat[sender] = subject + if message_id: + self._last_message_id_by_chat[sender] = message_id + + await self._handle_message( + sender_id=sender, + chat_id=sender, + content=item["content"], + metadata=item.get("metadata", {}), + ) + except Exception as e: + logger.error("Email polling error: {}", e) + + await asyncio.sleep(poll_seconds) + + async def stop(self) -> None: + """Stop polling loop.""" + self._running = False + + async def send(self, msg: OutboundMessage) -> None: + """Send email via SMTP.""" + if not self.config.consent_granted: + logger.warning("Skip email send: consent_granted is false") + return + + if not self.config.smtp_host: + logger.warning("Email channel SMTP host not configured") + return + + to_addr = msg.chat_id.strip() + if not to_addr: + logger.warning("Email channel missing recipient address") + return + + # Determine if this is a reply (recipient has sent us an email before) + is_reply = to_addr in self._last_subject_by_chat + force_send = bool((msg.metadata or {}).get("force_send")) + + # autoReplyEnabled only controls automatic replies, not proactive sends + if is_reply and not self.config.auto_reply_enabled and not force_send: + logger.info("Skip automatic email reply to {}: auto_reply_enabled is false", to_addr) + return + + base_subject = self._last_subject_by_chat.get(to_addr, "nanobot reply") + subject = self._reply_subject(base_subject) + if msg.metadata and isinstance(msg.metadata.get("subject"), str): + override = msg.metadata["subject"].strip() + if override: + subject = override + + email_msg = EmailMessage() + email_msg["From"] = self.config.from_address or self.config.smtp_username or self.config.imap_username + email_msg["To"] = to_addr + email_msg["Subject"] = subject + email_msg.set_content(msg.content or "") + + in_reply_to = self._last_message_id_by_chat.get(to_addr) + if in_reply_to: + email_msg["In-Reply-To"] = in_reply_to + email_msg["References"] = in_reply_to + + try: + await asyncio.to_thread(self._smtp_send, email_msg) + except Exception as e: + logger.error("Error sending email to {}: {}", to_addr, e) + raise + + def _validate_config(self) -> bool: + missing = [] + if not self.config.imap_host: + missing.append("imap_host") + if not self.config.imap_username: + missing.append("imap_username") + if not self.config.imap_password: + missing.append("imap_password") + if not self.config.smtp_host: + missing.append("smtp_host") + if not self.config.smtp_username: + missing.append("smtp_username") + if not self.config.smtp_password: + missing.append("smtp_password") + + if missing: + logger.error("Email channel not configured, missing: {}", ', '.join(missing)) + return False + return True + + def _smtp_send(self, msg: EmailMessage) -> None: + timeout = 30 + if self.config.smtp_use_ssl: + with smtplib.SMTP_SSL( + self.config.smtp_host, + self.config.smtp_port, + timeout=timeout, + ) as smtp: + smtp.login(self.config.smtp_username, self.config.smtp_password) + smtp.send_message(msg) + return + + with smtplib.SMTP(self.config.smtp_host, self.config.smtp_port, timeout=timeout) as smtp: + if self.config.smtp_use_tls: + smtp.starttls(context=ssl.create_default_context()) + smtp.login(self.config.smtp_username, self.config.smtp_password) + smtp.send_message(msg) + + def _fetch_new_messages(self) -> list[dict[str, Any]]: + """Poll IMAP and return parsed unread messages.""" + return self._fetch_messages( + search_criteria=("UNSEEN",), + mark_seen=self.config.mark_seen, + dedupe=True, + limit=0, + ) + + def fetch_messages_between_dates( + self, + start_date: date, + end_date: date, + limit: int = 20, + ) -> list[dict[str, Any]]: + """ + Fetch messages in [start_date, end_date) by IMAP date search. + + This is used for historical summarization tasks (e.g. "yesterday"). + """ + if end_date <= start_date: + return [] + + return self._fetch_messages( + search_criteria=( + "SINCE", + self._format_imap_date(start_date), + "BEFORE", + self._format_imap_date(end_date), + ), + mark_seen=False, + dedupe=False, + limit=max(1, int(limit)), + ) + + def _fetch_messages( + self, + search_criteria: tuple[str, ...], + mark_seen: bool, + dedupe: bool, + limit: int, + ) -> list[dict[str, Any]]: + """Fetch messages by arbitrary IMAP search criteria.""" + messages: list[dict[str, Any]] = [] + mailbox = self.config.imap_mailbox or "INBOX" + + if self.config.imap_use_ssl: + client = imaplib.IMAP4_SSL(self.config.imap_host, self.config.imap_port) + else: + client = imaplib.IMAP4(self.config.imap_host, self.config.imap_port) + + try: + client.login(self.config.imap_username, self.config.imap_password) + status, _ = client.select(mailbox) + if status != "OK": + return messages + + status, data = client.search(None, *search_criteria) + if status != "OK" or not data: + return messages + + ids = data[0].split() + if limit > 0 and len(ids) > limit: + ids = ids[-limit:] + for imap_id in ids: + status, fetched = client.fetch(imap_id, "(BODY.PEEK[] UID)") + if status != "OK" or not fetched: + continue + + raw_bytes = self._extract_message_bytes(fetched) + if raw_bytes is None: + continue + + uid = self._extract_uid(fetched) + if dedupe and uid and uid in self._processed_uids: + continue + + parsed = BytesParser(policy=policy.default).parsebytes(raw_bytes) + sender = parseaddr(parsed.get("From", ""))[1].strip().lower() + if not sender: + continue + + subject = self._decode_header_value(parsed.get("Subject", "")) + date_value = parsed.get("Date", "") + message_id = parsed.get("Message-ID", "").strip() + body = self._extract_text_body(parsed) + + if not body: + body = "(empty email body)" + + body = body[: self.config.max_body_chars] + content = ( + f"Email received.\n" + f"From: {sender}\n" + f"Subject: {subject}\n" + f"Date: {date_value}\n\n" + f"{body}" + ) + + metadata = { + "message_id": message_id, + "subject": subject, + "date": date_value, + "sender_email": sender, + "uid": uid, + } + messages.append( + { + "sender": sender, + "subject": subject, + "message_id": message_id, + "content": content, + "metadata": metadata, + } + ) + + if dedupe and uid: + self._processed_uids.add(uid) + # mark_seen is the primary dedup; this set is a safety net + if len(self._processed_uids) > self._MAX_PROCESSED_UIDS: + # Evict a random half to cap memory; mark_seen is the primary dedup + self._processed_uids = set(list(self._processed_uids)[len(self._processed_uids) // 2:]) + + if mark_seen: + client.store(imap_id, "+FLAGS", "\\Seen") + finally: + try: + client.logout() + except Exception: + pass + + return messages + + @classmethod + def _format_imap_date(cls, value: date) -> str: + """Format date for IMAP search (always English month abbreviations).""" + month = cls._IMAP_MONTHS[value.month - 1] + return f"{value.day:02d}-{month}-{value.year}" + + @staticmethod + def _extract_message_bytes(fetched: list[Any]) -> bytes | None: + for item in fetched: + if isinstance(item, tuple) and len(item) >= 2 and isinstance(item[1], (bytes, bytearray)): + return bytes(item[1]) + return None + + @staticmethod + def _extract_uid(fetched: list[Any]) -> str: + for item in fetched: + if isinstance(item, tuple) and item and isinstance(item[0], (bytes, bytearray)): + head = bytes(item[0]).decode("utf-8", errors="ignore") + m = re.search(r"UID\s+(\d+)", head) + if m: + return m.group(1) + return "" + + @staticmethod + def _decode_header_value(value: str) -> str: + if not value: + return "" + try: + return str(make_header(decode_header(value))) + except Exception: + return value + + @classmethod + def _extract_text_body(cls, msg: Any) -> str: + """Best-effort extraction of readable body text.""" + if msg.is_multipart(): + plain_parts: list[str] = [] + html_parts: list[str] = [] + for part in msg.walk(): + if part.get_content_disposition() == "attachment": + continue + content_type = part.get_content_type() + try: + payload = part.get_content() + except Exception: + payload_bytes = part.get_payload(decode=True) or b"" + charset = part.get_content_charset() or "utf-8" + payload = payload_bytes.decode(charset, errors="replace") + if not isinstance(payload, str): + continue + if content_type == "text/plain": + plain_parts.append(payload) + elif content_type == "text/html": + html_parts.append(payload) + if plain_parts: + return "\n\n".join(plain_parts).strip() + if html_parts: + return cls._html_to_text("\n\n".join(html_parts)).strip() + return "" + + try: + payload = msg.get_content() + except Exception: + payload_bytes = msg.get_payload(decode=True) or b"" + charset = msg.get_content_charset() or "utf-8" + payload = payload_bytes.decode(charset, errors="replace") + if not isinstance(payload, str): + return "" + if msg.get_content_type() == "text/html": + return cls._html_to_text(payload).strip() + return payload.strip() + + @staticmethod + def _html_to_text(raw_html: str) -> str: + text = re.sub(r"<\s*br\s*/?>", "\n", raw_html, flags=re.IGNORECASE) + text = re.sub(r"<\s*/\s*p\s*>", "\n", text, flags=re.IGNORECASE) + text = re.sub(r"<[^>]+>", "", text) + return html.unescape(text) + + def _reply_subject(self, base_subject: str) -> str: + subject = (base_subject or "").strip() or "nanobot reply" + prefix = self.config.subject_prefix or "Re: " + if subject.lower().startswith("re:"): + return subject + return f"{prefix}{subject}" diff --git a/core/nanobot/nanobot/channels/feishu.py b/core/nanobot/nanobot/channels/feishu.py new file mode 100644 index 0000000..160b9b4 --- /dev/null +++ b/core/nanobot/nanobot/channels/feishu.py @@ -0,0 +1,980 @@ +"""Feishu/Lark channel implementation using lark-oapi SDK with WebSocket long connection.""" + +import asyncio +import json +import os +import re +import threading +from collections import OrderedDict +from pathlib import Path +from typing import Any + +from loguru import logger + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.paths import get_media_dir +from nanobot.config.schema import FeishuConfig + +import importlib.util + +FEISHU_AVAILABLE = importlib.util.find_spec("lark_oapi") is not None + +# Message type display mapping +MSG_TYPE_MAP = { + "image": "[image]", + "audio": "[audio]", + "file": "[file]", + "sticker": "[sticker]", +} + + +def _extract_share_card_content(content_json: dict, msg_type: str) -> str: + """Extract text representation from share cards and interactive messages.""" + parts = [] + + if msg_type == "share_chat": + parts.append(f"[shared chat: {content_json.get('chat_id', '')}]") + elif msg_type == "share_user": + parts.append(f"[shared user: {content_json.get('user_id', '')}]") + elif msg_type == "interactive": + parts.extend(_extract_interactive_content(content_json)) + elif msg_type == "share_calendar_event": + parts.append(f"[shared calendar event: {content_json.get('event_key', '')}]") + elif msg_type == "system": + parts.append("[system message]") + elif msg_type == "merge_forward": + parts.append("[merged forward messages]") + + return "\n".join(parts) if parts else f"[{msg_type}]" + + +def _extract_interactive_content(content: dict) -> list[str]: + """Recursively extract text and links from interactive card content.""" + parts = [] + + if isinstance(content, str): + try: + content = json.loads(content) + except (json.JSONDecodeError, TypeError): + return [content] if content.strip() else [] + + if not isinstance(content, dict): + return parts + + if "title" in content: + title = content["title"] + if isinstance(title, dict): + title_content = title.get("content", "") or title.get("text", "") + if title_content: + parts.append(f"title: {title_content}") + elif isinstance(title, str): + parts.append(f"title: {title}") + + for elements in content.get("elements", []) if isinstance(content.get("elements"), list) else []: + for element in elements: + parts.extend(_extract_element_content(element)) + + card = content.get("card", {}) + if card: + parts.extend(_extract_interactive_content(card)) + + header = content.get("header", {}) + if header: + header_title = header.get("title", {}) + if isinstance(header_title, dict): + header_text = header_title.get("content", "") or header_title.get("text", "") + if header_text: + parts.append(f"title: {header_text}") + + return parts + + +def _extract_element_content(element: dict) -> list[str]: + """Extract content from a single card element.""" + parts = [] + + if not isinstance(element, dict): + return parts + + tag = element.get("tag", "") + + if tag in ("markdown", "lark_md"): + content = element.get("content", "") + if content: + parts.append(content) + + elif tag == "div": + text = element.get("text", {}) + if isinstance(text, dict): + text_content = text.get("content", "") or text.get("text", "") + if text_content: + parts.append(text_content) + elif isinstance(text, str): + parts.append(text) + for field in element.get("fields", []): + if isinstance(field, dict): + field_text = field.get("text", {}) + if isinstance(field_text, dict): + c = field_text.get("content", "") + if c: + parts.append(c) + + elif tag == "a": + href = element.get("href", "") + text = element.get("text", "") + if href: + parts.append(f"link: {href}") + if text: + parts.append(text) + + elif tag == "button": + text = element.get("text", {}) + if isinstance(text, dict): + c = text.get("content", "") + if c: + parts.append(c) + url = element.get("url", "") or element.get("multi_url", {}).get("url", "") + if url: + parts.append(f"link: {url}") + + elif tag == "img": + alt = element.get("alt", {}) + parts.append(alt.get("content", "[image]") if isinstance(alt, dict) else "[image]") + + elif tag == "note": + for ne in element.get("elements", []): + parts.extend(_extract_element_content(ne)) + + elif tag == "column_set": + for col in element.get("columns", []): + for ce in col.get("elements", []): + parts.extend(_extract_element_content(ce)) + + elif tag == "plain_text": + content = element.get("content", "") + if content: + parts.append(content) + + else: + for ne in element.get("elements", []): + parts.extend(_extract_element_content(ne)) + + return parts + + +def _extract_post_content(content_json: dict) -> tuple[str, list[str]]: + """Extract text and image keys from Feishu post (rich text) message. + + Handles three payload shapes: + - Direct: {"title": "...", "content": [[...]]} + - Localized: {"zh_cn": {"title": "...", "content": [...]}} + - Wrapped: {"post": {"zh_cn": {"title": "...", "content": [...]}}} + """ + + def _parse_block(block: dict) -> tuple[str | None, list[str]]: + if not isinstance(block, dict) or not isinstance(block.get("content"), list): + return None, [] + texts, images = [], [] + if title := block.get("title"): + texts.append(title) + for row in block["content"]: + if not isinstance(row, list): + continue + for el in row: + if not isinstance(el, dict): + continue + tag = el.get("tag") + if tag in ("text", "a"): + texts.append(el.get("text", "")) + elif tag == "at": + texts.append(f"@{el.get('user_name', 'user')}") + elif tag == "img" and (key := el.get("image_key")): + images.append(key) + return (" ".join(texts).strip() or None), images + + # Unwrap optional {"post": ...} envelope + root = content_json + if isinstance(root, dict) and isinstance(root.get("post"), dict): + root = root["post"] + if not isinstance(root, dict): + return "", [] + + # Direct format + if "content" in root: + text, imgs = _parse_block(root) + if text or imgs: + return text or "", imgs + + # Localized: prefer known locales, then fall back to any dict child + for key in ("zh_cn", "en_us", "ja_jp"): + if key in root: + text, imgs = _parse_block(root[key]) + if text or imgs: + return text or "", imgs + for val in root.values(): + if isinstance(val, dict): + text, imgs = _parse_block(val) + if text or imgs: + return text or "", imgs + + return "", [] + + +def _extract_post_text(content_json: dict) -> str: + """Extract plain text from Feishu post (rich text) message content. + + Legacy wrapper for _extract_post_content, returns only text. + """ + text, _ = _extract_post_content(content_json) + return text + + +class FeishuChannel(BaseChannel): + """ + Feishu/Lark channel using WebSocket long connection. + + Uses WebSocket to receive events - no public IP or webhook required. + + Requires: + - App ID and App Secret from Feishu Open Platform + - Bot capability enabled + - Event subscription enabled (im.message.receive_v1) + """ + + name = "feishu" + display_name = "Feishu" + + def __init__(self, config: FeishuConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: FeishuConfig = config + self._client: Any = None + self._ws_client: Any = None + self._ws_thread: threading.Thread | None = None + self._processed_message_ids: OrderedDict[str, None] = OrderedDict() # Ordered dedup cache + self._loop: asyncio.AbstractEventLoop | None = None + + @staticmethod + def _register_optional_event(builder: Any, method_name: str, handler: Any) -> Any: + """Register an event handler only when the SDK supports it.""" + method = getattr(builder, method_name, None) + return method(handler) if callable(method) else builder + + async def start(self) -> None: + """Start the Feishu bot with WebSocket long connection.""" + if not FEISHU_AVAILABLE: + logger.error("Feishu SDK not installed. Run: pip install lark-oapi") + return + + if not self.config.app_id or not self.config.app_secret: + logger.error("Feishu app_id and app_secret not configured") + return + + import lark_oapi as lark + self._running = True + self._loop = asyncio.get_running_loop() + + # Create Lark client for sending messages + self._client = lark.Client.builder() \ + .app_id(self.config.app_id) \ + .app_secret(self.config.app_secret) \ + .log_level(lark.LogLevel.INFO) \ + .build() + builder = lark.EventDispatcherHandler.builder( + self.config.encrypt_key or "", + self.config.verification_token or "", + ).register_p2_im_message_receive_v1( + self._on_message_sync + ) + builder = self._register_optional_event( + builder, "register_p2_im_message_reaction_created_v1", self._on_reaction_created + ) + builder = self._register_optional_event( + builder, "register_p2_im_message_message_read_v1", self._on_message_read + ) + builder = self._register_optional_event( + builder, + "register_p2_im_chat_access_event_bot_p2p_chat_entered_v1", + self._on_bot_p2p_chat_entered, + ) + event_handler = builder.build() + + # Create WebSocket client for long connection + self._ws_client = lark.ws.Client( + self.config.app_id, + self.config.app_secret, + event_handler=event_handler, + log_level=lark.LogLevel.INFO + ) + + # Start WebSocket client in a separate thread with reconnect loop. + # A dedicated event loop is created for this thread so that lark_oapi's + # module-level `loop = asyncio.get_event_loop()` picks up an idle loop + # instead of the already-running main asyncio loop, which would cause + # "This event loop is already running" errors. + def run_ws(): + import time + import lark_oapi.ws.client as _lark_ws_client + ws_loop = asyncio.new_event_loop() + asyncio.set_event_loop(ws_loop) + # Patch the module-level loop used by lark's ws Client.start() + _lark_ws_client.loop = ws_loop + try: + while self._running: + try: + self._ws_client.start() + except Exception as e: + logger.warning("Feishu WebSocket error: {}", e) + if self._running: + time.sleep(5) + finally: + ws_loop.close() + + self._ws_thread = threading.Thread(target=run_ws, daemon=True) + self._ws_thread.start() + + logger.info("Feishu bot started with WebSocket long connection") + logger.info("No public IP required - using WebSocket to receive events") + + # Keep running until stopped + while self._running: + await asyncio.sleep(1) + + async def stop(self) -> None: + """ + Stop the Feishu bot. + + Notice: lark.ws.Client does not expose stop method， simply exiting the program will close the client. + + Reference: https://github.com/larksuite/oapi-sdk-python/blob/v2_main/lark_oapi/ws/client.py#L86 + """ + self._running = False + logger.info("Feishu bot stopped") + + def _add_reaction_sync(self, message_id: str, emoji_type: str) -> None: + """Sync helper for adding reaction (runs in thread pool).""" + from lark_oapi.api.im.v1 import CreateMessageReactionRequest, CreateMessageReactionRequestBody, Emoji + try: + request = CreateMessageReactionRequest.builder() \ + .message_id(message_id) \ + .request_body( + CreateMessageReactionRequestBody.builder() + .reaction_type(Emoji.builder().emoji_type(emoji_type).build()) + .build() + ).build() + + response = self._client.im.v1.message_reaction.create(request) + + if not response.success(): + logger.warning("Failed to add reaction: code={}, msg={}", response.code, response.msg) + else: + logger.debug("Added {} reaction to message {}", emoji_type, message_id) + except Exception as e: + logger.warning("Error adding reaction: {}", e) + + async def _add_reaction(self, message_id: str, emoji_type: str = "THUMBSUP") -> None: + """ + Add a reaction emoji to a message (non-blocking). + + Common emoji types: THUMBSUP, OK, EYES, DONE, OnIt, HEART + """ + if not self._client: + return + + loop = asyncio.get_running_loop() + await loop.run_in_executor(None, self._add_reaction_sync, message_id, emoji_type) + + # Regex to match markdown tables (header + separator + data rows) + _TABLE_RE = re.compile( + r"((?:^[ \t]*\|.+\|[ \t]*\n)(?:^[ \t]*\|[-:\s|]+\|[ \t]*\n)(?:^[ \t]*\|.+\|[ \t]*\n?)+)", + re.MULTILINE, + ) + + _HEADING_RE = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE) + + _CODE_BLOCK_RE = re.compile(r"(```[\s\S]*?```)", re.MULTILINE) + + @staticmethod + def _parse_md_table(table_text: str) -> dict | None: + """Parse a markdown table into a Feishu table element.""" + lines = [_line.strip() for _line in table_text.strip().split("\n") if _line.strip()] + if len(lines) < 3: + return None + def split(_line: str) -> list[str]: + return [c.strip() for c in _line.strip("|").split("|")] + headers = split(lines[0]) + rows = [split(_line) for _line in lines[2:]] + columns = [{"tag": "column", "name": f"c{i}", "display_name": h, "width": "auto"} + for i, h in enumerate(headers)] + return { + "tag": "table", + "page_size": len(rows) + 1, + "columns": columns, + "rows": [{f"c{i}": r[i] if i < len(r) else "" for i in range(len(headers))} for r in rows], + } + + def _build_card_elements(self, content: str) -> list[dict]: + """Split content into div/markdown + table elements for Feishu card.""" + elements, last_end = [], 0 + for m in self._TABLE_RE.finditer(content): + before = content[last_end:m.start()] + if before.strip(): + elements.extend(self._split_headings(before)) + elements.append(self._parse_md_table(m.group(1)) or {"tag": "markdown", "content": m.group(1)}) + last_end = m.end() + remaining = content[last_end:] + if remaining.strip(): + elements.extend(self._split_headings(remaining)) + return elements or [{"tag": "markdown", "content": content}] + + @staticmethod + def _split_elements_by_table_limit(elements: list[dict], max_tables: int = 1) -> list[list[dict]]: + """Split card elements into groups with at most *max_tables* table elements each. + + Feishu cards have a hard limit of one table per card (API error 11310). + When the rendered content contains multiple markdown tables each table is + placed in a separate card message so every table reaches the user. + """ + if not elements: + return [[]] + groups: list[list[dict]] = [] + current: list[dict] = [] + table_count = 0 + for el in elements: + if el.get("tag") == "table": + if table_count >= max_tables: + if current: + groups.append(current) + current = [] + table_count = 0 + current.append(el) + table_count += 1 + else: + current.append(el) + if current: + groups.append(current) + return groups or [[]] + + def _split_headings(self, content: str) -> list[dict]: + """Split content by headings, converting headings to div elements.""" + protected = content + code_blocks = [] + for m in self._CODE_BLOCK_RE.finditer(content): + code_blocks.append(m.group(1)) + protected = protected.replace(m.group(1), f"\x00CODE{len(code_blocks)-1}\x00", 1) + + elements = [] + last_end = 0 + for m in self._HEADING_RE.finditer(protected): + before = protected[last_end:m.start()].strip() + if before: + elements.append({"tag": "markdown", "content": before}) + text = m.group(2).strip() + elements.append({ + "tag": "div", + "text": { + "tag": "lark_md", + "content": f"**{text}**", + }, + }) + last_end = m.end() + remaining = protected[last_end:].strip() + if remaining: + elements.append({"tag": "markdown", "content": remaining}) + + for i, cb in enumerate(code_blocks): + for el in elements: + if el.get("tag") == "markdown": + el["content"] = el["content"].replace(f"\x00CODE{i}\x00", cb) + + return elements or [{"tag": "markdown", "content": content}] + + # ── Smart format detection ────────────────────────────────────────── + # Patterns that indicate "complex" markdown needing card rendering + _COMPLEX_MD_RE = re.compile( + r"```" # fenced code block + r"|^\|.+\|.*\n\s*\|[-:\s|]+\|" # markdown table (header + separator) + r"|^#{1,6}\s+" # headings + , re.MULTILINE, + ) + + # Simple markdown patterns (bold, italic, strikethrough) + _SIMPLE_MD_RE = re.compile( + r"\*\*.+?\*\*" # **bold** + r"|__.+?__" # __bold__ + r"|(? str: + """Determine the optimal Feishu message format for *content*. + + Returns one of: + - ``"text"`` – plain text, short and no markdown + - ``"post"`` – rich text (links only, moderate length) + - ``"interactive"`` – card with full markdown rendering + """ + stripped = content.strip() + + # Complex markdown (code blocks, tables, headings) → always card + if cls._COMPLEX_MD_RE.search(stripped): + return "interactive" + + # Long content → card (better readability with card layout) + if len(stripped) > cls._POST_MAX_LEN: + return "interactive" + + # Has bold/italic/strikethrough → card (post format can't render these) + if cls._SIMPLE_MD_RE.search(stripped): + return "interactive" + + # Has list items → card (post format can't render list bullets well) + if cls._LIST_RE.search(stripped) or cls._OLIST_RE.search(stripped): + return "interactive" + + # Has links → post format (supports tags) + if cls._MD_LINK_RE.search(stripped): + return "post" + + # Short plain text → text format + if len(stripped) <= cls._TEXT_MAX_LEN: + return "text" + + # Medium plain text without any formatting → post format + return "post" + + @classmethod + def _markdown_to_post(cls, content: str) -> str: + """Convert markdown content to Feishu post message JSON. + + Handles links ``[text](url)`` as ``a`` tags; everything else as ``text`` tags. + Each line becomes a paragraph (row) in the post body. + """ + lines = content.strip().split("\n") + paragraphs: list[list[dict]] = [] + + for line in lines: + elements: list[dict] = [] + last_end = 0 + + for m in cls._MD_LINK_RE.finditer(line): + # Text before this link + before = line[last_end:m.start()] + if before: + elements.append({"tag": "text", "text": before}) + elements.append({ + "tag": "a", + "text": m.group(1), + "href": m.group(2), + }) + last_end = m.end() + + # Remaining text after last link + remaining = line[last_end:] + if remaining: + elements.append({"tag": "text", "text": remaining}) + + # Empty line → empty paragraph for spacing + if not elements: + elements.append({"tag": "text", "text": ""}) + + paragraphs.append(elements) + + post_body = { + "zh_cn": { + "content": paragraphs, + } + } + return json.dumps(post_body, ensure_ascii=False) + + _IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".ico", ".tiff", ".tif"} + _AUDIO_EXTS = {".opus"} + _VIDEO_EXTS = {".mp4", ".mov", ".avi"} + _FILE_TYPE_MAP = { + ".opus": "opus", ".mp4": "mp4", ".pdf": "pdf", ".doc": "doc", ".docx": "doc", + ".xls": "xls", ".xlsx": "xls", ".ppt": "ppt", ".pptx": "ppt", + } + + def _upload_image_sync(self, file_path: str) -> str | None: + """Upload an image to Feishu and return the image_key.""" + from lark_oapi.api.im.v1 import CreateImageRequest, CreateImageRequestBody + try: + with open(file_path, "rb") as f: + request = CreateImageRequest.builder() \ + .request_body( + CreateImageRequestBody.builder() + .image_type("message") + .image(f) + .build() + ).build() + response = self._client.im.v1.image.create(request) + if response.success(): + image_key = response.data.image_key + logger.debug("Uploaded image {}: {}", os.path.basename(file_path), image_key) + return image_key + else: + logger.error("Failed to upload image: code={}, msg={}", response.code, response.msg) + return None + except Exception as e: + logger.error("Error uploading image {}: {}", file_path, e) + return None + + def _upload_file_sync(self, file_path: str) -> str | None: + """Upload a file to Feishu and return the file_key.""" + from lark_oapi.api.im.v1 import CreateFileRequest, CreateFileRequestBody + ext = os.path.splitext(file_path)[1].lower() + file_type = self._FILE_TYPE_MAP.get(ext, "stream") + file_name = os.path.basename(file_path) + try: + with open(file_path, "rb") as f: + request = CreateFileRequest.builder() \ + .request_body( + CreateFileRequestBody.builder() + .file_type(file_type) + .file_name(file_name) + .file(f) + .build() + ).build() + response = self._client.im.v1.file.create(request) + if response.success(): + file_key = response.data.file_key + logger.debug("Uploaded file {}: {}", file_name, file_key) + return file_key + else: + logger.error("Failed to upload file: code={}, msg={}", response.code, response.msg) + return None + except Exception as e: + logger.error("Error uploading file {}: {}", file_path, e) + return None + + def _download_image_sync(self, message_id: str, image_key: str) -> tuple[bytes | None, str | None]: + """Download an image from Feishu message by message_id and image_key.""" + from lark_oapi.api.im.v1 import GetMessageResourceRequest + try: + request = GetMessageResourceRequest.builder() \ + .message_id(message_id) \ + .file_key(image_key) \ + .type("image") \ + .build() + response = self._client.im.v1.message_resource.get(request) + if response.success(): + file_data = response.file + # GetMessageResourceRequest returns BytesIO, need to read bytes + if hasattr(file_data, 'read'): + file_data = file_data.read() + return file_data, response.file_name + else: + logger.error("Failed to download image: code={}, msg={}", response.code, response.msg) + return None, None + except Exception as e: + logger.error("Error downloading image {}: {}", image_key, e) + return None, None + + def _download_file_sync( + self, message_id: str, file_key: str, resource_type: str = "file" + ) -> tuple[bytes | None, str | None]: + """Download a file/audio/media from a Feishu message by message_id and file_key.""" + from lark_oapi.api.im.v1 import GetMessageResourceRequest + + # Feishu API only accepts 'image' or 'file' as type parameter + # Convert 'audio' to 'file' for API compatibility + if resource_type == "audio": + resource_type = "file" + + try: + request = ( + GetMessageResourceRequest.builder() + .message_id(message_id) + .file_key(file_key) + .type(resource_type) + .build() + ) + response = self._client.im.v1.message_resource.get(request) + if response.success(): + file_data = response.file + if hasattr(file_data, "read"): + file_data = file_data.read() + return file_data, response.file_name + else: + logger.error("Failed to download {}: code={}, msg={}", resource_type, response.code, response.msg) + return None, None + except Exception: + logger.exception("Error downloading {} {}", resource_type, file_key) + return None, None + + async def _download_and_save_media( + self, + msg_type: str, + content_json: dict, + message_id: str | None = None + ) -> tuple[str | None, str]: + """ + Download media from Feishu and save to local disk. + + Returns: + (file_path, content_text) - file_path is None if download failed + """ + loop = asyncio.get_running_loop() + media_dir = get_media_dir("feishu") + + data, filename = None, None + + if msg_type == "image": + image_key = content_json.get("image_key") + if image_key and message_id: + data, filename = await loop.run_in_executor( + None, self._download_image_sync, message_id, image_key + ) + if not filename: + filename = f"{image_key[:16]}.jpg" + + elif msg_type in ("audio", "file", "media"): + file_key = content_json.get("file_key") + if file_key and message_id: + data, filename = await loop.run_in_executor( + None, self._download_file_sync, message_id, file_key, msg_type + ) + if not filename: + filename = file_key[:16] + if msg_type == "audio" and not filename.endswith(".opus"): + filename = f"{filename}.opus" + + if data and filename: + file_path = media_dir / filename + file_path.write_bytes(data) + logger.debug("Downloaded {} to {}", msg_type, file_path) + return str(file_path), f"[{msg_type}: {filename}]" + + return None, f"[{msg_type}: download failed]" + + def _send_message_sync(self, receive_id_type: str, receive_id: str, msg_type: str, content: str) -> bool: + """Send a single message (text/image/file/interactive) synchronously.""" + from lark_oapi.api.im.v1 import CreateMessageRequest, CreateMessageRequestBody + try: + request = CreateMessageRequest.builder() \ + .receive_id_type(receive_id_type) \ + .request_body( + CreateMessageRequestBody.builder() + .receive_id(receive_id) + .msg_type(msg_type) + .content(content) + .build() + ).build() + response = self._client.im.v1.message.create(request) + if not response.success(): + logger.error( + "Failed to send Feishu {} message: code={}, msg={}, log_id={}", + msg_type, response.code, response.msg, response.get_log_id() + ) + return False + logger.debug("Feishu {} message sent to {}", msg_type, receive_id) + return True + except Exception as e: + logger.error("Error sending Feishu {} message: {}", msg_type, e) + return False + + async def send(self, msg: OutboundMessage) -> None: + """Send a message through Feishu, including media (images/files) if present.""" + if not self._client: + logger.warning("Feishu client not initialized") + return + + try: + receive_id_type = "chat_id" if msg.chat_id.startswith("oc_") else "open_id" + loop = asyncio.get_running_loop() + + for file_path in msg.media: + if not os.path.isfile(file_path): + logger.warning("Media file not found: {}", file_path) + continue + ext = os.path.splitext(file_path)[1].lower() + if ext in self._IMAGE_EXTS: + key = await loop.run_in_executor(None, self._upload_image_sync, file_path) + if key: + await loop.run_in_executor( + None, self._send_message_sync, + receive_id_type, msg.chat_id, "image", json.dumps({"image_key": key}, ensure_ascii=False), + ) + else: + key = await loop.run_in_executor(None, self._upload_file_sync, file_path) + if key: + # Use msg_type "media" for audio/video so users can play inline; + # "file" for everything else (documents, archives, etc.) + if ext in self._AUDIO_EXTS or ext in self._VIDEO_EXTS: + media_type = "media" + else: + media_type = "file" + await loop.run_in_executor( + None, self._send_message_sync, + receive_id_type, msg.chat_id, media_type, json.dumps({"file_key": key}, ensure_ascii=False), + ) + + if msg.content and msg.content.strip(): + fmt = self._detect_msg_format(msg.content) + + if fmt == "text": + # Short plain text – send as simple text message + text_body = json.dumps({"text": msg.content.strip()}, ensure_ascii=False) + await loop.run_in_executor( + None, self._send_message_sync, + receive_id_type, msg.chat_id, "text", text_body, + ) + + elif fmt == "post": + # Medium content with links – send as rich-text post + post_body = self._markdown_to_post(msg.content) + await loop.run_in_executor( + None, self._send_message_sync, + receive_id_type, msg.chat_id, "post", post_body, + ) + + else: + # Complex / long content – send as interactive card + elements = self._build_card_elements(msg.content) + for chunk in self._split_elements_by_table_limit(elements): + card = {"config": {"wide_screen_mode": True}, "elements": chunk} + await loop.run_in_executor( + None, self._send_message_sync, + receive_id_type, msg.chat_id, "interactive", json.dumps(card, ensure_ascii=False), + ) + + except Exception as e: + logger.error("Error sending Feishu message: {}", e) + + def _on_message_sync(self, data: Any) -> None: + """ + Sync handler for incoming messages (called from WebSocket thread). + Schedules async handling in the main event loop. + """ + if self._loop and self._loop.is_running(): + asyncio.run_coroutine_threadsafe(self._on_message(data), self._loop) + + async def _on_message(self, data: Any) -> None: + """Handle incoming message from Feishu.""" + try: + event = data.event + message = event.message + sender = event.sender + + # Deduplication check + message_id = message.message_id + if message_id in self._processed_message_ids: + return + self._processed_message_ids[message_id] = None + + # Trim cache + while len(self._processed_message_ids) > 1000: + self._processed_message_ids.popitem(last=False) + + # Skip bot messages + if sender.sender_type == "bot": + return + + sender_id = sender.sender_id.open_id if sender.sender_id else "unknown" + chat_id = message.chat_id + chat_type = message.chat_type + msg_type = message.message_type + + # Add reaction + await self._add_reaction(message_id, self.config.react_emoji) + + # Parse content + content_parts = [] + media_paths = [] + + try: + content_json = json.loads(message.content) if message.content else {} + except json.JSONDecodeError: + content_json = {} + + if msg_type == "text": + text = content_json.get("text", "") + if text: + content_parts.append(text) + + elif msg_type == "post": + text, image_keys = _extract_post_content(content_json) + if text: + content_parts.append(text) + # Download images embedded in post + for img_key in image_keys: + file_path, content_text = await self._download_and_save_media( + "image", {"image_key": img_key}, message_id + ) + if file_path: + media_paths.append(file_path) + content_parts.append(content_text) + + elif msg_type in ("image", "audio", "file", "media"): + file_path, content_text = await self._download_and_save_media(msg_type, content_json, message_id) + if file_path: + media_paths.append(file_path) + + if msg_type == "audio" and file_path: + transcription = await self.transcribe_audio(file_path) + if transcription: + content_text = f"[transcription: {transcription}]" + + content_parts.append(content_text) + + elif msg_type in ("share_chat", "share_user", "interactive", "share_calendar_event", "system", "merge_forward"): + # Handle share cards and interactive messages + text = _extract_share_card_content(content_json, msg_type) + if text: + content_parts.append(text) + + else: + content_parts.append(MSG_TYPE_MAP.get(msg_type, f"[{msg_type}]")) + + content = "\n".join(content_parts) if content_parts else "" + + if not content and not media_paths: + return + + # Forward to message bus + reply_to = chat_id if chat_type == "group" else sender_id + await self._handle_message( + sender_id=sender_id, + chat_id=reply_to, + content=content, + media=media_paths, + metadata={ + "message_id": message_id, + "chat_type": chat_type, + "msg_type": msg_type, + } + ) + + except Exception as e: + logger.error("Error processing Feishu message: {}", e) + + def _on_reaction_created(self, data: Any) -> None: + """Ignore reaction events so they do not generate SDK noise.""" + pass + + def _on_message_read(self, data: Any) -> None: + """Ignore read events so they do not generate SDK noise.""" + pass + + def _on_bot_p2p_chat_entered(self, data: Any) -> None: + """Ignore p2p-enter events when a user opens a bot chat.""" + logger.debug("Bot entered p2p chat (user opened chat window)") + pass diff --git a/core/nanobot/nanobot/channels/manager.py b/core/nanobot/nanobot/channels/manager.py new file mode 100644 index 0000000..8288ad0 --- /dev/null +++ b/core/nanobot/nanobot/channels/manager.py @@ -0,0 +1,155 @@ +"""Channel manager for coordinating chat channels.""" + +from __future__ import annotations + +import asyncio +from typing import Any + +from loguru import logger + +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.schema import Config + + +class ChannelManager: + """ + Manages chat channels and coordinates message routing. + + Responsibilities: + - Initialize enabled channels (Telegram, WhatsApp, etc.) + - Start/stop channels + - Route outbound messages + """ + + def __init__(self, config: Config, bus: MessageBus): + self.config = config + self.bus = bus + self.channels: dict[str, BaseChannel] = {} + self._dispatch_task: asyncio.Task | None = None + + self._init_channels() + + def _init_channels(self) -> None: + """Initialize channels discovered via pkgutil scan.""" + from nanobot.channels.registry import discover_channel_names, load_channel_class + + groq_key = self.config.providers.groq.api_key + + for modname in discover_channel_names(): + section = getattr(self.config.channels, modname, None) + if not section or not getattr(section, "enabled", False): + continue + try: + cls = load_channel_class(modname) + channel = cls(section, self.bus) + channel.transcription_api_key = groq_key + self.channels[modname] = channel + logger.info("{} channel enabled", cls.display_name) + except ImportError as e: + logger.warning("{} channel not available: {}", modname, e) + + self._validate_allow_from() + + def _validate_allow_from(self) -> None: + for name, ch in self.channels.items(): + if getattr(ch.config, "allow_from", None) == []: + raise SystemExit( + f'Error: "{name}" has empty allowFrom (denies all). ' + f'Set ["*"] to allow everyone, or add specific user IDs.' + ) + + async def _start_channel(self, name: str, channel: BaseChannel) -> None: + """Start a channel and log any exceptions.""" + try: + await channel.start() + except Exception as e: + logger.error("Failed to start channel {}: {}", name, e) + + async def start_all(self) -> None: + """Start all channels and the outbound dispatcher.""" + if not self.channels: + logger.warning("No channels enabled") + return + + # Start outbound dispatcher + self._dispatch_task = asyncio.create_task(self._dispatch_outbound()) + + # Start channels + tasks = [] + for name, channel in self.channels.items(): + logger.info("Starting {} channel...", name) + tasks.append(asyncio.create_task(self._start_channel(name, channel))) + + # Wait for all to complete (they should run forever) + await asyncio.gather(*tasks, return_exceptions=True) + + async def stop_all(self) -> None: + """Stop all channels and the dispatcher.""" + logger.info("Stopping all channels...") + + # Stop dispatcher + if self._dispatch_task: + self._dispatch_task.cancel() + try: + await self._dispatch_task + except asyncio.CancelledError: + pass + + # Stop all channels + for name, channel in self.channels.items(): + try: + await channel.stop() + logger.info("Stopped {} channel", name) + except Exception as e: + logger.error("Error stopping {}: {}", name, e) + + async def _dispatch_outbound(self) -> None: + """Dispatch outbound messages to the appropriate channel.""" + logger.info("Outbound dispatcher started") + + while True: + try: + msg = await asyncio.wait_for( + self.bus.consume_outbound(), + timeout=1.0 + ) + + if msg.metadata.get("_progress"): + if msg.metadata.get("_tool_hint") and not self.config.channels.send_tool_hints: + continue + if not msg.metadata.get("_tool_hint") and not self.config.channels.send_progress: + continue + + channel = self.channels.get(msg.channel) + if channel: + try: + await channel.send(msg) + except Exception as e: + logger.error("Error sending to {}: {}", msg.channel, e) + else: + logger.warning("Unknown channel: {}", msg.channel) + + except asyncio.TimeoutError: + continue + except asyncio.CancelledError: + break + + def get_channel(self, name: str) -> BaseChannel | None: + """Get a channel by name.""" + return self.channels.get(name) + + def get_status(self) -> dict[str, Any]: + """Get status of all channels.""" + return { + name: { + "enabled": True, + "running": channel.is_running + } + for name, channel in self.channels.items() + } + + @property + def enabled_channels(self) -> list[str]: + """Get list of enabled channel names.""" + return list(self.channels.keys()) diff --git a/core/nanobot/nanobot/channels/matrix.py b/core/nanobot/nanobot/channels/matrix.py new file mode 100644 index 0000000..0d7a908 --- /dev/null +++ b/core/nanobot/nanobot/channels/matrix.py @@ -0,0 +1,705 @@ +"""Matrix (Element) channel — inbound sync + outbound message/media delivery.""" + +import asyncio +import logging +import mimetypes +from pathlib import Path +from typing import Any, TypeAlias + +from loguru import logger + +try: + import nh3 + from mistune import create_markdown + from nio import ( + AsyncClient, + AsyncClientConfig, + ContentRepositoryConfigError, + DownloadError, + InviteEvent, + JoinError, + MatrixRoom, + MemoryDownloadResponse, + RoomEncryptedMedia, + RoomMessage, + RoomMessageMedia, + RoomMessageText, + RoomSendError, + RoomTypingError, + SyncError, + UploadError, + ) + from nio.crypto.attachments import decrypt_attachment + from nio.exceptions import EncryptionError +except ImportError as e: + raise ImportError( + "Matrix dependencies not installed. Run: pip install nanobot-ai[matrix]" + ) from e + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.paths import get_data_dir, get_media_dir +from nanobot.utils.helpers import safe_filename + +TYPING_NOTICE_TIMEOUT_MS = 30_000 +# Must stay below TYPING_NOTICE_TIMEOUT_MS so the indicator doesn't expire mid-processing. +TYPING_KEEPALIVE_INTERVAL_MS = 20_000 +MATRIX_HTML_FORMAT = "org.matrix.custom.html" +_ATTACH_MARKER = "[attachment: {}]" +_ATTACH_TOO_LARGE = "[attachment: {} - too large]" +_ATTACH_FAILED = "[attachment: {} - download failed]" +_ATTACH_UPLOAD_FAILED = "[attachment: {} - upload failed]" +_DEFAULT_ATTACH_NAME = "attachment" +_MSGTYPE_MAP = {"m.image": "image", "m.audio": "audio", "m.video": "video", "m.file": "file"} + +MATRIX_MEDIA_EVENT_FILTER = (RoomMessageMedia, RoomEncryptedMedia) +MatrixMediaEvent: TypeAlias = RoomMessageMedia | RoomEncryptedMedia + +MATRIX_MARKDOWN = create_markdown( + escape=True, + plugins=["table", "strikethrough", "url", "superscript", "subscript"], +) + +MATRIX_ALLOWED_HTML_TAGS = { + "p", "a", "strong", "em", "del", "code", "pre", "blockquote", + "ul", "ol", "li", "h1", "h2", "h3", "h4", "h5", "h6", + "hr", "br", "table", "thead", "tbody", "tr", "th", "td", + "caption", "sup", "sub", "img", +} +MATRIX_ALLOWED_HTML_ATTRIBUTES: dict[str, set[str]] = { + "a": {"href"}, "code": {"class"}, "ol": {"start"}, + "img": {"src", "alt", "title", "width", "height"}, +} +MATRIX_ALLOWED_URL_SCHEMES = {"https", "http", "matrix", "mailto", "mxc"} + + +def _filter_matrix_html_attribute(tag: str, attr: str, value: str) -> str | None: + """Filter attribute values to a safe Matrix-compatible subset.""" + if tag == "a" and attr == "href": + return value if value.lower().startswith(("https://", "http://", "matrix:", "mailto:")) else None + if tag == "img" and attr == "src": + return value if value.lower().startswith("mxc://") else None + if tag == "code" and attr == "class": + classes = [c for c in value.split() if c.startswith("language-") and not c.startswith("language-_")] + return " ".join(classes) if classes else None + return value + + +MATRIX_HTML_CLEANER = nh3.Cleaner( + tags=MATRIX_ALLOWED_HTML_TAGS, + attributes=MATRIX_ALLOWED_HTML_ATTRIBUTES, + attribute_filter=_filter_matrix_html_attribute, + url_schemes=MATRIX_ALLOWED_URL_SCHEMES, + strip_comments=True, + link_rel="noopener noreferrer", +) + + +def _render_markdown_html(text: str) -> str | None: + """Render markdown to sanitized HTML; returns None for plain text.""" + try: + formatted = MATRIX_HTML_CLEANER.clean(MATRIX_MARKDOWN(text)).strip() + except Exception: + return None + if not formatted: + return None + # Skip formatted_body for plain

text

to keep payload minimal. + if formatted.startswith("

") and formatted.endswith("

"): + inner = formatted[3:-4] + if "<" not in inner and ">" not in inner: + return None + return formatted + + +def _build_matrix_text_content(text: str) -> dict[str, object]: + """Build Matrix m.text payload with optional HTML formatted_body.""" + content: dict[str, object] = {"msgtype": "m.text", "body": text, "m.mentions": {}} + if html := _render_markdown_html(text): + content["format"] = MATRIX_HTML_FORMAT + content["formatted_body"] = html + return content + + +class _NioLoguruHandler(logging.Handler): + """Route matrix-nio stdlib logs into Loguru.""" + + def emit(self, record: logging.LogRecord) -> None: + try: + level = logger.level(record.levelname).name + except ValueError: + level = record.levelno + frame, depth = logging.currentframe(), 2 + while frame and frame.f_code.co_filename == logging.__file__: + frame, depth = frame.f_back, depth + 1 + logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage()) + + +def _configure_nio_logging_bridge() -> None: + """Bridge matrix-nio logs to Loguru (idempotent).""" + nio_logger = logging.getLogger("nio") + if not any(isinstance(h, _NioLoguruHandler) for h in nio_logger.handlers): + nio_logger.handlers = [_NioLoguruHandler()] + nio_logger.propagate = False + + +class MatrixChannel(BaseChannel): + """Matrix (Element) channel using long-polling sync.""" + + name = "matrix" + display_name = "Matrix" + + def __init__(self, config: Any, bus: MessageBus): + super().__init__(config, bus) + self.client: AsyncClient | None = None + self._sync_task: asyncio.Task | None = None + self._typing_tasks: dict[str, asyncio.Task] = {} + self._restrict_to_workspace = False + self._workspace: Path | None = None + self._server_upload_limit_bytes: int | None = None + self._server_upload_limit_checked = False + + async def start(self) -> None: + """Start Matrix client and begin sync loop.""" + self._running = True + _configure_nio_logging_bridge() + + store_path = get_data_dir() / "matrix-store" + store_path.mkdir(parents=True, exist_ok=True) + + self.client = AsyncClient( + homeserver=self.config.homeserver, user=self.config.user_id, + store_path=store_path, + config=AsyncClientConfig(store_sync_tokens=True, encryption_enabled=self.config.e2ee_enabled), + ) + self.client.user_id = self.config.user_id + self.client.access_token = self.config.access_token + self.client.device_id = self.config.device_id + + self._register_event_callbacks() + self._register_response_callbacks() + + if not self.config.e2ee_enabled: + logger.warning("Matrix E2EE disabled; encrypted rooms may be undecryptable.") + + if self.config.device_id: + try: + self.client.load_store() + except Exception: + logger.exception("Matrix store load failed; restart may replay recent messages.") + else: + logger.warning("Matrix device_id empty; restart may replay recent messages.") + + self._sync_task = asyncio.create_task(self._sync_loop()) + + async def stop(self) -> None: + """Stop the Matrix channel with graceful sync shutdown.""" + self._running = False + for room_id in list(self._typing_tasks): + await self._stop_typing_keepalive(room_id, clear_typing=False) + if self.client: + self.client.stop_sync_forever() + if self._sync_task: + try: + await asyncio.wait_for(asyncio.shield(self._sync_task), + timeout=self.config.sync_stop_grace_seconds) + except (asyncio.TimeoutError, asyncio.CancelledError): + self._sync_task.cancel() + try: + await self._sync_task + except asyncio.CancelledError: + pass + if self.client: + await self.client.close() + + def _is_workspace_path_allowed(self, path: Path) -> bool: + """Check path is inside workspace (when restriction enabled).""" + if not self._restrict_to_workspace or not self._workspace: + return True + try: + path.resolve(strict=False).relative_to(self._workspace) + return True + except ValueError: + return False + + def _collect_outbound_media_candidates(self, media: list[str]) -> list[Path]: + """Deduplicate and resolve outbound attachment paths.""" + seen: set[str] = set() + candidates: list[Path] = [] + for raw in media: + if not isinstance(raw, str) or not raw.strip(): + continue + path = Path(raw.strip()).expanduser() + try: + key = str(path.resolve(strict=False)) + except OSError: + key = str(path) + if key not in seen: + seen.add(key) + candidates.append(path) + return candidates + + @staticmethod + def _build_outbound_attachment_content( + *, filename: str, mime: str, size_bytes: int, + mxc_url: str, encryption_info: dict[str, Any] | None = None, + ) -> dict[str, Any]: + """Build Matrix content payload for an uploaded file/image/audio/video.""" + prefix = mime.split("/")[0] + msgtype = {"image": "m.image", "audio": "m.audio", "video": "m.video"}.get(prefix, "m.file") + content: dict[str, Any] = { + "msgtype": msgtype, "body": filename, "filename": filename, + "info": {"mimetype": mime, "size": size_bytes}, "m.mentions": {}, + } + if encryption_info: + content["file"] = {**encryption_info, "url": mxc_url} + else: + content["url"] = mxc_url + return content + + def _is_encrypted_room(self, room_id: str) -> bool: + if not self.client: + return False + room = getattr(self.client, "rooms", {}).get(room_id) + return bool(getattr(room, "encrypted", False)) + + async def _send_room_content(self, room_id: str, content: dict[str, Any]) -> None: + """Send m.room.message with E2EE options.""" + if not self.client: + return + kwargs: dict[str, Any] = {"room_id": room_id, "message_type": "m.room.message", "content": content} + if self.config.e2ee_enabled: + kwargs["ignore_unverified_devices"] = True + await self.client.room_send(**kwargs) + + async def _resolve_server_upload_limit_bytes(self) -> int | None: + """Query homeserver upload limit once per channel lifecycle.""" + if self._server_upload_limit_checked: + return self._server_upload_limit_bytes + self._server_upload_limit_checked = True + if not self.client: + return None + try: + response = await self.client.content_repository_config() + except Exception: + return None + upload_size = getattr(response, "upload_size", None) + if isinstance(upload_size, int) and upload_size > 0: + self._server_upload_limit_bytes = upload_size + return upload_size + return None + + async def _effective_media_limit_bytes(self) -> int: + """min(local config, server advertised) — 0 blocks all uploads.""" + local_limit = max(int(self.config.max_media_bytes), 0) + server_limit = await self._resolve_server_upload_limit_bytes() + if server_limit is None: + return local_limit + return min(local_limit, server_limit) if local_limit else 0 + + async def _upload_and_send_attachment( + self, room_id: str, path: Path, limit_bytes: int, + relates_to: dict[str, Any] | None = None, + ) -> str | None: + """Upload one local file to Matrix and send it as a media message. Returns failure marker or None.""" + if not self.client: + return _ATTACH_UPLOAD_FAILED.format(path.name or _DEFAULT_ATTACH_NAME) + + resolved = path.expanduser().resolve(strict=False) + filename = safe_filename(resolved.name) or _DEFAULT_ATTACH_NAME + fail = _ATTACH_UPLOAD_FAILED.format(filename) + + if not resolved.is_file() or not self._is_workspace_path_allowed(resolved): + return fail + try: + size_bytes = resolved.stat().st_size + except OSError: + return fail + if limit_bytes <= 0 or size_bytes > limit_bytes: + return _ATTACH_TOO_LARGE.format(filename) + + mime = mimetypes.guess_type(filename, strict=False)[0] or "application/octet-stream" + try: + with resolved.open("rb") as f: + upload_result = await self.client.upload( + f, content_type=mime, filename=filename, + encrypt=self.config.e2ee_enabled and self._is_encrypted_room(room_id), + filesize=size_bytes, + ) + except Exception: + return fail + + upload_response = upload_result[0] if isinstance(upload_result, tuple) else upload_result + encryption_info = upload_result[1] if isinstance(upload_result, tuple) and isinstance(upload_result[1], dict) else None + if isinstance(upload_response, UploadError): + return fail + mxc_url = getattr(upload_response, "content_uri", None) + if not isinstance(mxc_url, str) or not mxc_url.startswith("mxc://"): + return fail + + content = self._build_outbound_attachment_content( + filename=filename, mime=mime, size_bytes=size_bytes, + mxc_url=mxc_url, encryption_info=encryption_info, + ) + if relates_to: + content["m.relates_to"] = relates_to + try: + await self._send_room_content(room_id, content) + except Exception: + return fail + return None + + async def send(self, msg: OutboundMessage) -> None: + """Send outbound content; clear typing for non-progress messages.""" + if not self.client: + return + text = msg.content or "" + candidates = self._collect_outbound_media_candidates(msg.media) + relates_to = self._build_thread_relates_to(msg.metadata) + is_progress = bool((msg.metadata or {}).get("_progress")) + try: + failures: list[str] = [] + if candidates: + limit_bytes = await self._effective_media_limit_bytes() + for path in candidates: + if fail := await self._upload_and_send_attachment( + room_id=msg.chat_id, + path=path, + limit_bytes=limit_bytes, + relates_to=relates_to, + ): + failures.append(fail) + if failures: + text = f"{text.rstrip()}\n{chr(10).join(failures)}" if text.strip() else "\n".join(failures) + if text or not candidates: + content = _build_matrix_text_content(text) + if relates_to: + content["m.relates_to"] = relates_to + await self._send_room_content(msg.chat_id, content) + finally: + if not is_progress: + await self._stop_typing_keepalive(msg.chat_id, clear_typing=True) + + def _register_event_callbacks(self) -> None: + self.client.add_event_callback(self._on_message, RoomMessageText) + self.client.add_event_callback(self._on_media_message, MATRIX_MEDIA_EVENT_FILTER) + self.client.add_event_callback(self._on_room_invite, InviteEvent) + + def _register_response_callbacks(self) -> None: + self.client.add_response_callback(self._on_sync_error, SyncError) + self.client.add_response_callback(self._on_join_error, JoinError) + self.client.add_response_callback(self._on_send_error, RoomSendError) + + def _log_response_error(self, label: str, response: Any) -> None: + """Log Matrix response errors — auth errors at ERROR level, rest at WARNING.""" + code = getattr(response, "status_code", None) + is_auth = code in {"M_UNKNOWN_TOKEN", "M_FORBIDDEN", "M_UNAUTHORIZED"} + is_fatal = is_auth or getattr(response, "soft_logout", False) + (logger.error if is_fatal else logger.warning)("Matrix {} failed: {}", label, response) + + async def _on_sync_error(self, response: SyncError) -> None: + self._log_response_error("sync", response) + + async def _on_join_error(self, response: JoinError) -> None: + self._log_response_error("join", response) + + async def _on_send_error(self, response: RoomSendError) -> None: + self._log_response_error("send", response) + + async def _set_typing(self, room_id: str, typing: bool) -> None: + """Best-effort typing indicator update.""" + if not self.client: + return + try: + response = await self.client.room_typing(room_id=room_id, typing_state=typing, + timeout=TYPING_NOTICE_TIMEOUT_MS) + if isinstance(response, RoomTypingError): + logger.debug("Matrix typing failed for {}: {}", room_id, response) + except Exception: + pass + + async def _start_typing_keepalive(self, room_id: str) -> None: + """Start periodic typing refresh (spec-recommended keepalive).""" + await self._stop_typing_keepalive(room_id, clear_typing=False) + await self._set_typing(room_id, True) + if not self._running: + return + + async def loop() -> None: + try: + while self._running: + await asyncio.sleep(TYPING_KEEPALIVE_INTERVAL_MS / 1000) + await self._set_typing(room_id, True) + except asyncio.CancelledError: + pass + + self._typing_tasks[room_id] = asyncio.create_task(loop()) + + async def _stop_typing_keepalive(self, room_id: str, *, clear_typing: bool) -> None: + if task := self._typing_tasks.pop(room_id, None): + task.cancel() + try: + await task + except asyncio.CancelledError: + pass + if clear_typing: + await self._set_typing(room_id, False) + + async def _sync_loop(self) -> None: + while self._running: + try: + await self.client.sync_forever(timeout=30000, full_state=True) + except asyncio.CancelledError: + break + except Exception: + await asyncio.sleep(2) + + async def _on_room_invite(self, room: MatrixRoom, event: InviteEvent) -> None: + if self.is_allowed(event.sender): + await self.client.join(room.room_id) + + def _is_direct_room(self, room: MatrixRoom) -> bool: + count = getattr(room, "member_count", None) + return isinstance(count, int) and count <= 2 + + def _is_bot_mentioned(self, event: RoomMessage) -> bool: + """Check m.mentions payload for bot mention.""" + source = getattr(event, "source", None) + if not isinstance(source, dict): + return False + mentions = (source.get("content") or {}).get("m.mentions") + if not isinstance(mentions, dict): + return False + user_ids = mentions.get("user_ids") + if isinstance(user_ids, list) and self.config.user_id in user_ids: + return True + return bool(self.config.allow_room_mentions and mentions.get("room") is True) + + def _should_process_message(self, room: MatrixRoom, event: RoomMessage) -> bool: + """Apply sender and room policy checks.""" + if not self.is_allowed(event.sender): + return False + if self._is_direct_room(room): + return True + policy = self.config.group_policy + if policy == "open": + return True + if policy == "allowlist": + return room.room_id in (self.config.group_allow_from or []) + if policy == "mention": + return self._is_bot_mentioned(event) + return False + + def _media_dir(self) -> Path: + return get_media_dir("matrix") + + @staticmethod + def _event_source_content(event: RoomMessage) -> dict[str, Any]: + source = getattr(event, "source", None) + if not isinstance(source, dict): + return {} + content = source.get("content") + return content if isinstance(content, dict) else {} + + def _event_thread_root_id(self, event: RoomMessage) -> str | None: + relates_to = self._event_source_content(event).get("m.relates_to") + if not isinstance(relates_to, dict) or relates_to.get("rel_type") != "m.thread": + return None + root_id = relates_to.get("event_id") + return root_id if isinstance(root_id, str) and root_id else None + + def _thread_metadata(self, event: RoomMessage) -> dict[str, str] | None: + if not (root_id := self._event_thread_root_id(event)): + return None + meta: dict[str, str] = {"thread_root_event_id": root_id} + if isinstance(reply_to := getattr(event, "event_id", None), str) and reply_to: + meta["thread_reply_to_event_id"] = reply_to + return meta + + @staticmethod + def _build_thread_relates_to(metadata: dict[str, Any] | None) -> dict[str, Any] | None: + if not metadata: + return None + root_id = metadata.get("thread_root_event_id") + if not isinstance(root_id, str) or not root_id: + return None + reply_to = metadata.get("thread_reply_to_event_id") or metadata.get("event_id") + if not isinstance(reply_to, str) or not reply_to: + return None + return {"rel_type": "m.thread", "event_id": root_id, + "m.in_reply_to": {"event_id": reply_to}, "is_falling_back": True} + + def _event_attachment_type(self, event: MatrixMediaEvent) -> str: + msgtype = self._event_source_content(event).get("msgtype") + return _MSGTYPE_MAP.get(msgtype, "file") + + @staticmethod + def _is_encrypted_media_event(event: MatrixMediaEvent) -> bool: + return (isinstance(getattr(event, "key", None), dict) + and isinstance(getattr(event, "hashes", None), dict) + and isinstance(getattr(event, "iv", None), str)) + + def _event_declared_size_bytes(self, event: MatrixMediaEvent) -> int | None: + info = self._event_source_content(event).get("info") + size = info.get("size") if isinstance(info, dict) else None + return size if isinstance(size, int) and size >= 0 else None + + def _event_mime(self, event: MatrixMediaEvent) -> str | None: + info = self._event_source_content(event).get("info") + if isinstance(info, dict) and isinstance(m := info.get("mimetype"), str) and m: + return m + m = getattr(event, "mimetype", None) + return m if isinstance(m, str) and m else None + + def _event_filename(self, event: MatrixMediaEvent, attachment_type: str) -> str: + body = getattr(event, "body", None) + if isinstance(body, str) and body.strip(): + if candidate := safe_filename(Path(body).name): + return candidate + return _DEFAULT_ATTACH_NAME if attachment_type == "file" else attachment_type + + def _build_attachment_path(self, event: MatrixMediaEvent, attachment_type: str, + filename: str, mime: str | None) -> Path: + safe_name = safe_filename(Path(filename).name) or _DEFAULT_ATTACH_NAME + suffix = Path(safe_name).suffix + if not suffix and mime: + if guessed := mimetypes.guess_extension(mime, strict=False): + safe_name, suffix = f"{safe_name}{guessed}", guessed + stem = (Path(safe_name).stem or attachment_type)[:72] + suffix = suffix[:16] + event_id = safe_filename(str(getattr(event, "event_id", "") or "evt").lstrip("$")) + event_prefix = (event_id[:24] or "evt").strip("_") + return self._media_dir() / f"{event_prefix}_{stem}{suffix}" + + async def _download_media_bytes(self, mxc_url: str) -> bytes | None: + if not self.client: + return None + response = await self.client.download(mxc=mxc_url) + if isinstance(response, DownloadError): + logger.warning("Matrix download failed for {}: {}", mxc_url, response) + return None + body = getattr(response, "body", None) + if isinstance(body, (bytes, bytearray)): + return bytes(body) + if isinstance(response, MemoryDownloadResponse): + return bytes(response.body) + if isinstance(body, (str, Path)): + path = Path(body) + if path.is_file(): + try: + return path.read_bytes() + except OSError: + return None + return None + + def _decrypt_media_bytes(self, event: MatrixMediaEvent, ciphertext: bytes) -> bytes | None: + key_obj, hashes, iv = getattr(event, "key", None), getattr(event, "hashes", None), getattr(event, "iv", None) + key = key_obj.get("k") if isinstance(key_obj, dict) else None + sha256 = hashes.get("sha256") if isinstance(hashes, dict) else None + if not all(isinstance(v, str) for v in (key, sha256, iv)): + return None + try: + return decrypt_attachment(ciphertext, key, sha256, iv) + except (EncryptionError, ValueError, TypeError): + logger.warning("Matrix decrypt failed for event {}", getattr(event, "event_id", "")) + return None + + async def _fetch_media_attachment( + self, room: MatrixRoom, event: MatrixMediaEvent, + ) -> tuple[dict[str, Any] | None, str]: + """Download, decrypt if needed, and persist a Matrix attachment.""" + atype = self._event_attachment_type(event) + mime = self._event_mime(event) + filename = self._event_filename(event, atype) + mxc_url = getattr(event, "url", None) + fail = _ATTACH_FAILED.format(filename) + + if not isinstance(mxc_url, str) or not mxc_url.startswith("mxc://"): + return None, fail + + limit_bytes = await self._effective_media_limit_bytes() + declared = self._event_declared_size_bytes(event) + if declared is not None and declared > limit_bytes: + return None, _ATTACH_TOO_LARGE.format(filename) + + downloaded = await self._download_media_bytes(mxc_url) + if downloaded is None: + return None, fail + + encrypted = self._is_encrypted_media_event(event) + data = downloaded + if encrypted: + if (data := self._decrypt_media_bytes(event, downloaded)) is None: + return None, fail + + if len(data) > limit_bytes: + return None, _ATTACH_TOO_LARGE.format(filename) + + path = self._build_attachment_path(event, atype, filename, mime) + try: + path.write_bytes(data) + except OSError: + return None, fail + + attachment = { + "type": atype, "mime": mime, "filename": filename, + "event_id": str(getattr(event, "event_id", "") or ""), + "encrypted": encrypted, "size_bytes": len(data), + "path": str(path), "mxc_url": mxc_url, + } + return attachment, _ATTACH_MARKER.format(path) + + def _base_metadata(self, room: MatrixRoom, event: RoomMessage) -> dict[str, Any]: + """Build common metadata for text and media handlers.""" + meta: dict[str, Any] = {"room": getattr(room, "display_name", room.room_id)} + if isinstance(eid := getattr(event, "event_id", None), str) and eid: + meta["event_id"] = eid + if thread := self._thread_metadata(event): + meta.update(thread) + return meta + + async def _on_message(self, room: MatrixRoom, event: RoomMessageText) -> None: + if event.sender == self.config.user_id or not self._should_process_message(room, event): + return + await self._start_typing_keepalive(room.room_id) + try: + await self._handle_message( + sender_id=event.sender, chat_id=room.room_id, + content=event.body, metadata=self._base_metadata(room, event), + ) + except Exception: + await self._stop_typing_keepalive(room.room_id, clear_typing=True) + raise + + async def _on_media_message(self, room: MatrixRoom, event: MatrixMediaEvent) -> None: + if event.sender == self.config.user_id or not self._should_process_message(room, event): + return + attachment, marker = await self._fetch_media_attachment(room, event) + parts: list[str] = [] + if isinstance(body := getattr(event, "body", None), str) and body.strip(): + parts.append(body.strip()) + + if attachment and attachment.get("type") == "audio": + transcription = await self.transcribe_audio(attachment["path"]) + if transcription: + parts.append(f"[transcription: {transcription}]") + else: + parts.append(marker) + elif marker: + parts.append(marker) + + await self._start_typing_keepalive(room.room_id) + try: + meta = self._base_metadata(room, event) + meta["attachments"] = [] + if attachment: + meta["attachments"] = [attachment] + await self._handle_message( + sender_id=event.sender, chat_id=room.room_id, + content="\n".join(parts), + media=[attachment["path"]] if attachment else [], + metadata=meta, + ) + except Exception: + await self._stop_typing_keepalive(room.room_id, clear_typing=True) + raise diff --git a/core/nanobot/nanobot/channels/mochat.py b/core/nanobot/nanobot/channels/mochat.py new file mode 100644 index 0000000..52e246f --- /dev/null +++ b/core/nanobot/nanobot/channels/mochat.py @@ -0,0 +1,896 @@ +"""Mochat channel implementation using Socket.IO with HTTP polling fallback.""" + +from __future__ import annotations + +import asyncio +import json +from collections import deque +from dataclasses import dataclass, field +from datetime import datetime +from typing import Any + +import httpx +from loguru import logger + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.paths import get_runtime_subdir +from nanobot.config.schema import MochatConfig + +try: + import socketio + SOCKETIO_AVAILABLE = True +except ImportError: + socketio = None + SOCKETIO_AVAILABLE = False + +try: + import msgpack # noqa: F401 + MSGPACK_AVAILABLE = True +except ImportError: + MSGPACK_AVAILABLE = False + +MAX_SEEN_MESSAGE_IDS = 2000 +CURSOR_SAVE_DEBOUNCE_S = 0.5 + + +# --------------------------------------------------------------------------- +# Data classes +# --------------------------------------------------------------------------- + +@dataclass +class MochatBufferedEntry: + """Buffered inbound entry for delayed dispatch.""" + raw_body: str + author: str + sender_name: str = "" + sender_username: str = "" + timestamp: int | None = None + message_id: str = "" + group_id: str = "" + + +@dataclass +class DelayState: + """Per-target delayed message state.""" + entries: list[MochatBufferedEntry] = field(default_factory=list) + lock: asyncio.Lock = field(default_factory=asyncio.Lock) + timer: asyncio.Task | None = None + + +@dataclass +class MochatTarget: + """Outbound target resolution result.""" + id: str + is_panel: bool + + +# --------------------------------------------------------------------------- +# Pure helpers +# --------------------------------------------------------------------------- + +def _safe_dict(value: Any) -> dict: + """Return *value* if it's a dict, else empty dict.""" + return value if isinstance(value, dict) else {} + + +def _str_field(src: dict, *keys: str) -> str: + """Return the first non-empty str value found for *keys*, stripped.""" + for k in keys: + v = src.get(k) + if isinstance(v, str) and v.strip(): + return v.strip() + return "" + + +def _make_synthetic_event( + message_id: str, author: str, content: Any, + meta: Any, group_id: str, converse_id: str, + timestamp: Any = None, *, author_info: Any = None, +) -> dict[str, Any]: + """Build a synthetic ``message.add`` event dict.""" + payload: dict[str, Any] = { + "messageId": message_id, "author": author, + "content": content, "meta": _safe_dict(meta), + "groupId": group_id, "converseId": converse_id, + } + if author_info is not None: + payload["authorInfo"] = _safe_dict(author_info) + return { + "type": "message.add", + "timestamp": timestamp or datetime.utcnow().isoformat(), + "payload": payload, + } + + +def normalize_mochat_content(content: Any) -> str: + """Normalize content payload to text.""" + if isinstance(content, str): + return content.strip() + if content is None: + return "" + try: + return json.dumps(content, ensure_ascii=False) + except TypeError: + return str(content) + + +def resolve_mochat_target(raw: str) -> MochatTarget: + """Resolve id and target kind from user-provided target string.""" + trimmed = (raw or "").strip() + if not trimmed: + return MochatTarget(id="", is_panel=False) + + lowered = trimmed.lower() + cleaned, forced_panel = trimmed, False + for prefix in ("mochat:", "group:", "channel:", "panel:"): + if lowered.startswith(prefix): + cleaned = trimmed[len(prefix):].strip() + forced_panel = prefix in {"group:", "channel:", "panel:"} + break + + if not cleaned: + return MochatTarget(id="", is_panel=False) + return MochatTarget(id=cleaned, is_panel=forced_panel or not cleaned.startswith("session_")) + + +def extract_mention_ids(value: Any) -> list[str]: + """Extract mention ids from heterogeneous mention payload.""" + if not isinstance(value, list): + return [] + ids: list[str] = [] + for item in value: + if isinstance(item, str): + if item.strip(): + ids.append(item.strip()) + elif isinstance(item, dict): + for key in ("id", "userId", "_id"): + candidate = item.get(key) + if isinstance(candidate, str) and candidate.strip(): + ids.append(candidate.strip()) + break + return ids + + +def resolve_was_mentioned(payload: dict[str, Any], agent_user_id: str) -> bool: + """Resolve mention state from payload metadata and text fallback.""" + meta = payload.get("meta") + if isinstance(meta, dict): + if meta.get("mentioned") is True or meta.get("wasMentioned") is True: + return True + for f in ("mentions", "mentionIds", "mentionedUserIds", "mentionedUsers"): + if agent_user_id and agent_user_id in extract_mention_ids(meta.get(f)): + return True + if not agent_user_id: + return False + content = payload.get("content") + if not isinstance(content, str) or not content: + return False + return f"<@{agent_user_id}>" in content or f"@{agent_user_id}" in content + + +def resolve_require_mention(config: MochatConfig, session_id: str, group_id: str) -> bool: + """Resolve mention requirement for group/panel conversations.""" + groups = config.groups or {} + for key in (group_id, session_id, "*"): + if key and key in groups: + return bool(groups[key].require_mention) + return bool(config.mention.require_in_groups) + + +def build_buffered_body(entries: list[MochatBufferedEntry], is_group: bool) -> str: + """Build text body from one or more buffered entries.""" + if not entries: + return "" + if len(entries) == 1: + return entries[0].raw_body + lines: list[str] = [] + for entry in entries: + if not entry.raw_body: + continue + if is_group: + label = entry.sender_name.strip() or entry.sender_username.strip() or entry.author + if label: + lines.append(f"{label}: {entry.raw_body}") + continue + lines.append(entry.raw_body) + return "\n".join(lines).strip() + + +def parse_timestamp(value: Any) -> int | None: + """Parse event timestamp to epoch milliseconds.""" + if not isinstance(value, str) or not value.strip(): + return None + try: + return int(datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp() * 1000) + except ValueError: + return None + + +# --------------------------------------------------------------------------- +# Channel +# --------------------------------------------------------------------------- + +class MochatChannel(BaseChannel): + """Mochat channel using socket.io with fallback polling workers.""" + + name = "mochat" + display_name = "Mochat" + + def __init__(self, config: MochatConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: MochatConfig = config + self._http: httpx.AsyncClient | None = None + self._socket: Any = None + self._ws_connected = self._ws_ready = False + + self._state_dir = get_runtime_subdir("mochat") + self._cursor_path = self._state_dir / "session_cursors.json" + self._session_cursor: dict[str, int] = {} + self._cursor_save_task: asyncio.Task | None = None + + self._session_set: set[str] = set() + self._panel_set: set[str] = set() + self._auto_discover_sessions = self._auto_discover_panels = False + + self._cold_sessions: set[str] = set() + self._session_by_converse: dict[str, str] = {} + + self._seen_set: dict[str, set[str]] = {} + self._seen_queue: dict[str, deque[str]] = {} + self._delay_states: dict[str, DelayState] = {} + + self._fallback_mode = False + self._session_fallback_tasks: dict[str, asyncio.Task] = {} + self._panel_fallback_tasks: dict[str, asyncio.Task] = {} + self._refresh_task: asyncio.Task | None = None + self._target_locks: dict[str, asyncio.Lock] = {} + + # ---- lifecycle --------------------------------------------------------- + + async def start(self) -> None: + """Start Mochat channel workers and websocket connection.""" + if not self.config.claw_token: + logger.error("Mochat claw_token not configured") + return + + self._running = True + self._http = httpx.AsyncClient(timeout=30.0) + self._state_dir.mkdir(parents=True, exist_ok=True) + await self._load_session_cursors() + self._seed_targets_from_config() + await self._refresh_targets(subscribe_new=False) + + if not await self._start_socket_client(): + await self._ensure_fallback_workers() + + self._refresh_task = asyncio.create_task(self._refresh_loop()) + while self._running: + await asyncio.sleep(1) + + async def stop(self) -> None: + """Stop all workers and clean up resources.""" + self._running = False + if self._refresh_task: + self._refresh_task.cancel() + self._refresh_task = None + + await self._stop_fallback_workers() + await self._cancel_delay_timers() + + if self._socket: + try: + await self._socket.disconnect() + except Exception: + pass + self._socket = None + + if self._cursor_save_task: + self._cursor_save_task.cancel() + self._cursor_save_task = None + await self._save_session_cursors() + + if self._http: + await self._http.aclose() + self._http = None + self._ws_connected = self._ws_ready = False + + async def send(self, msg: OutboundMessage) -> None: + """Send outbound message to session or panel.""" + if not self.config.claw_token: + logger.warning("Mochat claw_token missing, skip send") + return + + parts = ([msg.content.strip()] if msg.content and msg.content.strip() else []) + if msg.media: + parts.extend(m for m in msg.media if isinstance(m, str) and m.strip()) + content = "\n".join(parts).strip() + if not content: + return + + target = resolve_mochat_target(msg.chat_id) + if not target.id: + logger.warning("Mochat outbound target is empty") + return + + is_panel = (target.is_panel or target.id in self._panel_set) and not target.id.startswith("session_") + try: + if is_panel: + await self._api_send("/api/claw/groups/panels/send", "panelId", target.id, + content, msg.reply_to, self._read_group_id(msg.metadata)) + else: + await self._api_send("/api/claw/sessions/send", "sessionId", target.id, + content, msg.reply_to) + except Exception as e: + logger.error("Failed to send Mochat message: {}", e) + + # ---- config / init helpers --------------------------------------------- + + def _seed_targets_from_config(self) -> None: + sessions, self._auto_discover_sessions = self._normalize_id_list(self.config.sessions) + panels, self._auto_discover_panels = self._normalize_id_list(self.config.panels) + self._session_set.update(sessions) + self._panel_set.update(panels) + for sid in sessions: + if sid not in self._session_cursor: + self._cold_sessions.add(sid) + + @staticmethod + def _normalize_id_list(values: list[str]) -> tuple[list[str], bool]: + cleaned = [str(v).strip() for v in values if str(v).strip()] + return sorted({v for v in cleaned if v != "*"}), "*" in cleaned + + # ---- websocket --------------------------------------------------------- + + async def _start_socket_client(self) -> bool: + if not SOCKETIO_AVAILABLE: + logger.warning("python-socketio not installed, Mochat using polling fallback") + return False + + serializer = "default" + if not self.config.socket_disable_msgpack: + if MSGPACK_AVAILABLE: + serializer = "msgpack" + else: + logger.warning("msgpack not installed but socket_disable_msgpack=false; using JSON") + + client = socketio.AsyncClient( + reconnection=True, + reconnection_attempts=self.config.max_retry_attempts or None, + reconnection_delay=max(0.1, self.config.socket_reconnect_delay_ms / 1000.0), + reconnection_delay_max=max(0.1, self.config.socket_max_reconnect_delay_ms / 1000.0), + logger=False, engineio_logger=False, serializer=serializer, + ) + + @client.event + async def connect() -> None: + self._ws_connected, self._ws_ready = True, False + logger.info("Mochat websocket connected") + subscribed = await self._subscribe_all() + self._ws_ready = subscribed + await (self._stop_fallback_workers() if subscribed else self._ensure_fallback_workers()) + + @client.event + async def disconnect() -> None: + if not self._running: + return + self._ws_connected = self._ws_ready = False + logger.warning("Mochat websocket disconnected") + await self._ensure_fallback_workers() + + @client.event + async def connect_error(data: Any) -> None: + logger.error("Mochat websocket connect error: {}", data) + + @client.on("claw.session.events") + async def on_session_events(payload: dict[str, Any]) -> None: + await self._handle_watch_payload(payload, "session") + + @client.on("claw.panel.events") + async def on_panel_events(payload: dict[str, Any]) -> None: + await self._handle_watch_payload(payload, "panel") + + for ev in ("notify:chat.inbox.append", "notify:chat.message.add", + "notify:chat.message.update", "notify:chat.message.recall", + "notify:chat.message.delete"): + client.on(ev, self._build_notify_handler(ev)) + + socket_url = (self.config.socket_url or self.config.base_url).strip().rstrip("/") + socket_path = (self.config.socket_path or "/socket.io").strip().lstrip("/") + + try: + self._socket = client + await client.connect( + socket_url, transports=["websocket"], socketio_path=socket_path, + auth={"token": self.config.claw_token}, + wait_timeout=max(1.0, self.config.socket_connect_timeout_ms / 1000.0), + ) + return True + except Exception as e: + logger.error("Failed to connect Mochat websocket: {}", e) + try: + await client.disconnect() + except Exception: + pass + self._socket = None + return False + + def _build_notify_handler(self, event_name: str): + async def handler(payload: Any) -> None: + if event_name == "notify:chat.inbox.append": + await self._handle_notify_inbox_append(payload) + elif event_name.startswith("notify:chat.message."): + await self._handle_notify_chat_message(payload) + return handler + + # ---- subscribe --------------------------------------------------------- + + async def _subscribe_all(self) -> bool: + ok = await self._subscribe_sessions(sorted(self._session_set)) + ok = await self._subscribe_panels(sorted(self._panel_set)) and ok + if self._auto_discover_sessions or self._auto_discover_panels: + await self._refresh_targets(subscribe_new=True) + return ok + + async def _subscribe_sessions(self, session_ids: list[str]) -> bool: + if not session_ids: + return True + for sid in session_ids: + if sid not in self._session_cursor: + self._cold_sessions.add(sid) + + ack = await self._socket_call("com.claw.im.subscribeSessions", { + "sessionIds": session_ids, "cursors": self._session_cursor, + "limit": self.config.watch_limit, + }) + if not ack.get("result"): + logger.error("Mochat subscribeSessions failed: {}", ack.get('message', 'unknown error')) + return False + + data = ack.get("data") + items: list[dict[str, Any]] = [] + if isinstance(data, list): + items = [i for i in data if isinstance(i, dict)] + elif isinstance(data, dict): + sessions = data.get("sessions") + if isinstance(sessions, list): + items = [i for i in sessions if isinstance(i, dict)] + elif "sessionId" in data: + items = [data] + for p in items: + await self._handle_watch_payload(p, "session") + return True + + async def _subscribe_panels(self, panel_ids: list[str]) -> bool: + if not self._auto_discover_panels and not panel_ids: + return True + ack = await self._socket_call("com.claw.im.subscribePanels", {"panelIds": panel_ids}) + if not ack.get("result"): + logger.error("Mochat subscribePanels failed: {}", ack.get('message', 'unknown error')) + return False + return True + + async def _socket_call(self, event_name: str, payload: dict[str, Any]) -> dict[str, Any]: + if not self._socket: + return {"result": False, "message": "socket not connected"} + try: + raw = await self._socket.call(event_name, payload, timeout=10) + except Exception as e: + return {"result": False, "message": str(e)} + return raw if isinstance(raw, dict) else {"result": True, "data": raw} + + # ---- refresh / discovery ----------------------------------------------- + + async def _refresh_loop(self) -> None: + interval_s = max(1.0, self.config.refresh_interval_ms / 1000.0) + while self._running: + await asyncio.sleep(interval_s) + try: + await self._refresh_targets(subscribe_new=self._ws_ready) + except Exception as e: + logger.warning("Mochat refresh failed: {}", e) + if self._fallback_mode: + await self._ensure_fallback_workers() + + async def _refresh_targets(self, subscribe_new: bool) -> None: + if self._auto_discover_sessions: + await self._refresh_sessions_directory(subscribe_new) + if self._auto_discover_panels: + await self._refresh_panels(subscribe_new) + + async def _refresh_sessions_directory(self, subscribe_new: bool) -> None: + try: + response = await self._post_json("/api/claw/sessions/list", {}) + except Exception as e: + logger.warning("Mochat listSessions failed: {}", e) + return + + sessions = response.get("sessions") + if not isinstance(sessions, list): + return + + new_ids: list[str] = [] + for s in sessions: + if not isinstance(s, dict): + continue + sid = _str_field(s, "sessionId") + if not sid: + continue + if sid not in self._session_set: + self._session_set.add(sid) + new_ids.append(sid) + if sid not in self._session_cursor: + self._cold_sessions.add(sid) + cid = _str_field(s, "converseId") + if cid: + self._session_by_converse[cid] = sid + + if not new_ids: + return + if self._ws_ready and subscribe_new: + await self._subscribe_sessions(new_ids) + if self._fallback_mode: + await self._ensure_fallback_workers() + + async def _refresh_panels(self, subscribe_new: bool) -> None: + try: + response = await self._post_json("/api/claw/groups/get", {}) + except Exception as e: + logger.warning("Mochat getWorkspaceGroup failed: {}", e) + return + + raw_panels = response.get("panels") + if not isinstance(raw_panels, list): + return + + new_ids: list[str] = [] + for p in raw_panels: + if not isinstance(p, dict): + continue + pt = p.get("type") + if isinstance(pt, int) and pt != 0: + continue + pid = _str_field(p, "id", "_id") + if pid and pid not in self._panel_set: + self._panel_set.add(pid) + new_ids.append(pid) + + if not new_ids: + return + if self._ws_ready and subscribe_new: + await self._subscribe_panels(new_ids) + if self._fallback_mode: + await self._ensure_fallback_workers() + + # ---- fallback workers -------------------------------------------------- + + async def _ensure_fallback_workers(self) -> None: + if not self._running: + return + self._fallback_mode = True + for sid in sorted(self._session_set): + t = self._session_fallback_tasks.get(sid) + if not t or t.done(): + self._session_fallback_tasks[sid] = asyncio.create_task(self._session_watch_worker(sid)) + for pid in sorted(self._panel_set): + t = self._panel_fallback_tasks.get(pid) + if not t or t.done(): + self._panel_fallback_tasks[pid] = asyncio.create_task(self._panel_poll_worker(pid)) + + async def _stop_fallback_workers(self) -> None: + self._fallback_mode = False + tasks = [*self._session_fallback_tasks.values(), *self._panel_fallback_tasks.values()] + for t in tasks: + t.cancel() + if tasks: + await asyncio.gather(*tasks, return_exceptions=True) + self._session_fallback_tasks.clear() + self._panel_fallback_tasks.clear() + + async def _session_watch_worker(self, session_id: str) -> None: + while self._running and self._fallback_mode: + try: + payload = await self._post_json("/api/claw/sessions/watch", { + "sessionId": session_id, "cursor": self._session_cursor.get(session_id, 0), + "timeoutMs": self.config.watch_timeout_ms, "limit": self.config.watch_limit, + }) + await self._handle_watch_payload(payload, "session") + except asyncio.CancelledError: + break + except Exception as e: + logger.warning("Mochat watch fallback error ({}): {}", session_id, e) + await asyncio.sleep(max(0.1, self.config.retry_delay_ms / 1000.0)) + + async def _panel_poll_worker(self, panel_id: str) -> None: + sleep_s = max(1.0, self.config.refresh_interval_ms / 1000.0) + while self._running and self._fallback_mode: + try: + resp = await self._post_json("/api/claw/groups/panels/messages", { + "panelId": panel_id, "limit": min(100, max(1, self.config.watch_limit)), + }) + msgs = resp.get("messages") + if isinstance(msgs, list): + for m in reversed(msgs): + if not isinstance(m, dict): + continue + evt = _make_synthetic_event( + message_id=str(m.get("messageId") or ""), + author=str(m.get("author") or ""), + content=m.get("content"), + meta=m.get("meta"), group_id=str(resp.get("groupId") or ""), + converse_id=panel_id, timestamp=m.get("createdAt"), + author_info=m.get("authorInfo"), + ) + await self._process_inbound_event(panel_id, evt, "panel") + except asyncio.CancelledError: + break + except Exception as e: + logger.warning("Mochat panel polling error ({}): {}", panel_id, e) + await asyncio.sleep(sleep_s) + + # ---- inbound event processing ------------------------------------------ + + async def _handle_watch_payload(self, payload: dict[str, Any], target_kind: str) -> None: + if not isinstance(payload, dict): + return + target_id = _str_field(payload, "sessionId") + if not target_id: + return + + lock = self._target_locks.setdefault(f"{target_kind}:{target_id}", asyncio.Lock()) + async with lock: + prev = self._session_cursor.get(target_id, 0) if target_kind == "session" else 0 + pc = payload.get("cursor") + if target_kind == "session" and isinstance(pc, int) and pc >= 0: + self._mark_session_cursor(target_id, pc) + + raw_events = payload.get("events") + if not isinstance(raw_events, list): + return + if target_kind == "session" and target_id in self._cold_sessions: + self._cold_sessions.discard(target_id) + return + + for event in raw_events: + if not isinstance(event, dict): + continue + seq = event.get("seq") + if target_kind == "session" and isinstance(seq, int) and seq > self._session_cursor.get(target_id, prev): + self._mark_session_cursor(target_id, seq) + if event.get("type") == "message.add": + await self._process_inbound_event(target_id, event, target_kind) + + async def _process_inbound_event(self, target_id: str, event: dict[str, Any], target_kind: str) -> None: + payload = event.get("payload") + if not isinstance(payload, dict): + return + + author = _str_field(payload, "author") + if not author or (self.config.agent_user_id and author == self.config.agent_user_id): + return + if not self.is_allowed(author): + return + + message_id = _str_field(payload, "messageId") + seen_key = f"{target_kind}:{target_id}" + if message_id and self._remember_message_id(seen_key, message_id): + return + + raw_body = normalize_mochat_content(payload.get("content")) or "[empty message]" + ai = _safe_dict(payload.get("authorInfo")) + sender_name = _str_field(ai, "nickname", "email") + sender_username = _str_field(ai, "agentId") + + group_id = _str_field(payload, "groupId") + is_group = bool(group_id) + was_mentioned = resolve_was_mentioned(payload, self.config.agent_user_id) + require_mention = target_kind == "panel" and is_group and resolve_require_mention(self.config, target_id, group_id) + use_delay = target_kind == "panel" and self.config.reply_delay_mode == "non-mention" + + if require_mention and not was_mentioned and not use_delay: + return + + entry = MochatBufferedEntry( + raw_body=raw_body, author=author, sender_name=sender_name, + sender_username=sender_username, timestamp=parse_timestamp(event.get("timestamp")), + message_id=message_id, group_id=group_id, + ) + + if use_delay: + delay_key = seen_key + if was_mentioned: + await self._flush_delayed_entries(delay_key, target_id, target_kind, "mention", entry) + else: + await self._enqueue_delayed_entry(delay_key, target_id, target_kind, entry) + return + + await self._dispatch_entries(target_id, target_kind, [entry], was_mentioned) + + # ---- dedup / buffering ------------------------------------------------- + + def _remember_message_id(self, key: str, message_id: str) -> bool: + seen_set = self._seen_set.setdefault(key, set()) + seen_queue = self._seen_queue.setdefault(key, deque()) + if message_id in seen_set: + return True + seen_set.add(message_id) + seen_queue.append(message_id) + while len(seen_queue) > MAX_SEEN_MESSAGE_IDS: + seen_set.discard(seen_queue.popleft()) + return False + + async def _enqueue_delayed_entry(self, key: str, target_id: str, target_kind: str, entry: MochatBufferedEntry) -> None: + state = self._delay_states.setdefault(key, DelayState()) + async with state.lock: + state.entries.append(entry) + if state.timer: + state.timer.cancel() + state.timer = asyncio.create_task(self._delay_flush_after(key, target_id, target_kind)) + + async def _delay_flush_after(self, key: str, target_id: str, target_kind: str) -> None: + await asyncio.sleep(max(0, self.config.reply_delay_ms) / 1000.0) + await self._flush_delayed_entries(key, target_id, target_kind, "timer", None) + + async def _flush_delayed_entries(self, key: str, target_id: str, target_kind: str, reason: str, entry: MochatBufferedEntry | None) -> None: + state = self._delay_states.setdefault(key, DelayState()) + async with state.lock: + if entry: + state.entries.append(entry) + current = asyncio.current_task() + if state.timer and state.timer is not current: + state.timer.cancel() + state.timer = None + entries = state.entries[:] + state.entries.clear() + if entries: + await self._dispatch_entries(target_id, target_kind, entries, reason == "mention") + + async def _dispatch_entries(self, target_id: str, target_kind: str, entries: list[MochatBufferedEntry], was_mentioned: bool) -> None: + if not entries: + return + last = entries[-1] + is_group = bool(last.group_id) + body = build_buffered_body(entries, is_group) or "[empty message]" + await self._handle_message( + sender_id=last.author, chat_id=target_id, content=body, + metadata={ + "message_id": last.message_id, "timestamp": last.timestamp, + "is_group": is_group, "group_id": last.group_id, + "sender_name": last.sender_name, "sender_username": last.sender_username, + "target_kind": target_kind, "was_mentioned": was_mentioned, + "buffered_count": len(entries), + }, + ) + + async def _cancel_delay_timers(self) -> None: + for state in self._delay_states.values(): + if state.timer: + state.timer.cancel() + self._delay_states.clear() + + # ---- notify handlers --------------------------------------------------- + + async def _handle_notify_chat_message(self, payload: Any) -> None: + if not isinstance(payload, dict): + return + group_id = _str_field(payload, "groupId") + panel_id = _str_field(payload, "converseId", "panelId") + if not group_id or not panel_id: + return + if self._panel_set and panel_id not in self._panel_set: + return + + evt = _make_synthetic_event( + message_id=str(payload.get("_id") or payload.get("messageId") or ""), + author=str(payload.get("author") or ""), + content=payload.get("content"), meta=payload.get("meta"), + group_id=group_id, converse_id=panel_id, + timestamp=payload.get("createdAt"), author_info=payload.get("authorInfo"), + ) + await self._process_inbound_event(panel_id, evt, "panel") + + async def _handle_notify_inbox_append(self, payload: Any) -> None: + if not isinstance(payload, dict) or payload.get("type") != "message": + return + detail = payload.get("payload") + if not isinstance(detail, dict): + return + if _str_field(detail, "groupId"): + return + converse_id = _str_field(detail, "converseId") + if not converse_id: + return + + session_id = self._session_by_converse.get(converse_id) + if not session_id: + await self._refresh_sessions_directory(self._ws_ready) + session_id = self._session_by_converse.get(converse_id) + if not session_id: + return + + evt = _make_synthetic_event( + message_id=str(detail.get("messageId") or payload.get("_id") or ""), + author=str(detail.get("messageAuthor") or ""), + content=str(detail.get("messagePlainContent") or detail.get("messageSnippet") or ""), + meta={"source": "notify:chat.inbox.append", "converseId": converse_id}, + group_id="", converse_id=converse_id, timestamp=payload.get("createdAt"), + ) + await self._process_inbound_event(session_id, evt, "session") + + # ---- cursor persistence ------------------------------------------------ + + def _mark_session_cursor(self, session_id: str, cursor: int) -> None: + if cursor < 0 or cursor < self._session_cursor.get(session_id, 0): + return + self._session_cursor[session_id] = cursor + if not self._cursor_save_task or self._cursor_save_task.done(): + self._cursor_save_task = asyncio.create_task(self._save_cursor_debounced()) + + async def _save_cursor_debounced(self) -> None: + await asyncio.sleep(CURSOR_SAVE_DEBOUNCE_S) + await self._save_session_cursors() + + async def _load_session_cursors(self) -> None: + if not self._cursor_path.exists(): + return + try: + data = json.loads(self._cursor_path.read_text("utf-8")) + except Exception as e: + logger.warning("Failed to read Mochat cursor file: {}", e) + return + cursors = data.get("cursors") if isinstance(data, dict) else None + if isinstance(cursors, dict): + for sid, cur in cursors.items(): + if isinstance(sid, str) and isinstance(cur, int) and cur >= 0: + self._session_cursor[sid] = cur + + async def _save_session_cursors(self) -> None: + try: + self._state_dir.mkdir(parents=True, exist_ok=True) + self._cursor_path.write_text(json.dumps({ + "schemaVersion": 1, "updatedAt": datetime.utcnow().isoformat(), + "cursors": self._session_cursor, + }, ensure_ascii=False, indent=2) + "\n", "utf-8") + except Exception as e: + logger.warning("Failed to save Mochat cursor file: {}", e) + + # ---- HTTP helpers ------------------------------------------------------ + + async def _post_json(self, path: str, payload: dict[str, Any]) -> dict[str, Any]: + if not self._http: + raise RuntimeError("Mochat HTTP client not initialized") + url = f"{self.config.base_url.strip().rstrip('/')}{path}" + response = await self._http.post(url, headers={ + "Content-Type": "application/json", "X-Claw-Token": self.config.claw_token, + }, json=payload) + if not response.is_success: + raise RuntimeError(f"Mochat HTTP {response.status_code}: {response.text[:200]}") + try: + parsed = response.json() + except Exception: + parsed = response.text + if isinstance(parsed, dict) and isinstance(parsed.get("code"), int): + if parsed["code"] != 200: + msg = str(parsed.get("message") or parsed.get("name") or "request failed") + raise RuntimeError(f"Mochat API error: {msg} (code={parsed['code']})") + data = parsed.get("data") + return data if isinstance(data, dict) else {} + return parsed if isinstance(parsed, dict) else {} + + async def _api_send(self, path: str, id_key: str, id_val: str, + content: str, reply_to: str | None, group_id: str | None = None) -> dict[str, Any]: + """Unified send helper for session and panel messages.""" + body: dict[str, Any] = {id_key: id_val, "content": content} + if reply_to: + body["replyTo"] = reply_to + if group_id: + body["groupId"] = group_id + return await self._post_json(path, body) + + @staticmethod + def _read_group_id(metadata: dict[str, Any]) -> str | None: + if not isinstance(metadata, dict): + return None + value = metadata.get("group_id") or metadata.get("groupId") + return value.strip() if isinstance(value, str) and value.strip() else None diff --git a/core/nanobot/nanobot/channels/qq.py b/core/nanobot/nanobot/channels/qq.py new file mode 100644 index 0000000..792cc12 --- /dev/null +++ b/core/nanobot/nanobot/channels/qq.py @@ -0,0 +1,161 @@ +"""QQ channel implementation using botpy SDK.""" + +import asyncio +from collections import deque +from typing import TYPE_CHECKING + +from loguru import logger + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.schema import QQConfig + +try: + import botpy + from botpy.message import C2CMessage, GroupMessage + + QQ_AVAILABLE = True +except ImportError: + QQ_AVAILABLE = False + botpy = None + C2CMessage = None + GroupMessage = None + +if TYPE_CHECKING: + from botpy.message import C2CMessage, GroupMessage + + +def _make_bot_class(channel: "QQChannel") -> "type[botpy.Client]": + """Create a botpy Client subclass bound to the given channel.""" + intents = botpy.Intents(public_messages=True, direct_message=True) + + class _Bot(botpy.Client): + def __init__(self): + # Disable botpy's file log — nanobot uses loguru; default "botpy.log" fails on read-only fs + super().__init__(intents=intents, ext_handlers=False) + + async def on_ready(self): + logger.info("QQ bot ready: {}", self.robot.name) + + async def on_c2c_message_create(self, message: "C2CMessage"): + await channel._on_message(message, is_group=False) + + async def on_group_at_message_create(self, message: "GroupMessage"): + await channel._on_message(message, is_group=True) + + async def on_direct_message_create(self, message): + await channel._on_message(message, is_group=False) + + return _Bot + + +class QQChannel(BaseChannel): + """QQ channel using botpy SDK with WebSocket connection.""" + + name = "qq" + display_name = "QQ" + + def __init__(self, config: QQConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: QQConfig = config + self._client: "botpy.Client | None" = None + self._processed_ids: deque = deque(maxlen=1000) + self._msg_seq: int = 1 # 消息序列号，避免被 QQ API 去重 + self._chat_type_cache: dict[str, str] = {} + + async def start(self) -> None: + """Start the QQ bot.""" + if not QQ_AVAILABLE: + logger.error("QQ SDK not installed. Run: pip install qq-botpy") + return + + if not self.config.app_id or not self.config.secret: + logger.error("QQ app_id and secret not configured") + return + + self._running = True + BotClass = _make_bot_class(self) + self._client = BotClass() + logger.info("QQ bot started (C2C & Group supported)") + await self._run_bot() + + async def _run_bot(self) -> None: + """Run the bot connection with auto-reconnect.""" + while self._running: + try: + await self._client.start(appid=self.config.app_id, secret=self.config.secret) + except Exception as e: + logger.warning("QQ bot error: {}", e) + if self._running: + logger.info("Reconnecting QQ bot in 5 seconds...") + await asyncio.sleep(5) + + async def stop(self) -> None: + """Stop the QQ bot.""" + self._running = False + if self._client: + try: + await self._client.close() + except Exception: + pass + logger.info("QQ bot stopped") + + async def send(self, msg: OutboundMessage) -> None: + """Send a message through QQ.""" + if not self._client: + logger.warning("QQ client not initialized") + return + + try: + msg_id = msg.metadata.get("message_id") + self._msg_seq += 1 + msg_type = self._chat_type_cache.get(msg.chat_id, "c2c") + if msg_type == "group": + await self._client.api.post_group_message( + group_openid=msg.chat_id, + msg_type=2, + markdown={"content": msg.content}, + msg_id=msg_id, + msg_seq=self._msg_seq, + ) + else: + await self._client.api.post_c2c_message( + openid=msg.chat_id, + msg_type=2, + markdown={"content": msg.content}, + msg_id=msg_id, + msg_seq=self._msg_seq, + ) + except Exception as e: + logger.error("Error sending QQ message: {}", e) + + async def _on_message(self, data: "C2CMessage | GroupMessage", is_group: bool = False) -> None: + """Handle incoming message from QQ.""" + try: + # Dedup by message ID + if data.id in self._processed_ids: + return + self._processed_ids.append(data.id) + + content = (data.content or "").strip() + if not content: + return + + if is_group: + chat_id = data.group_openid + user_id = data.author.member_openid + self._chat_type_cache[chat_id] = "group" + else: + chat_id = str(getattr(data.author, 'id', None) or getattr(data.author, 'user_openid', 'unknown')) + user_id = chat_id + self._chat_type_cache[chat_id] = "c2c" + + await self._handle_message( + sender_id=user_id, + chat_id=chat_id, + content=content, + metadata={"message_id": data.id}, + ) + except Exception: + logger.exception("Error handling QQ message") diff --git a/core/nanobot/nanobot/channels/registry.py b/core/nanobot/nanobot/channels/registry.py new file mode 100644 index 0000000..eb30ff7 --- /dev/null +++ b/core/nanobot/nanobot/channels/registry.py @@ -0,0 +1,35 @@ +"""Auto-discovery for channel modules — no hardcoded registry.""" + +from __future__ import annotations + +import importlib +import pkgutil +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from nanobot.channels.base import BaseChannel + +_INTERNAL = frozenset({"base", "manager", "registry"}) + + +def discover_channel_names() -> list[str]: + """Return all channel module names by scanning the package (zero imports).""" + import nanobot.channels as pkg + + return [ + name + for _, name, ispkg in pkgutil.iter_modules(pkg.__path__) + if name not in _INTERNAL and not ispkg + ] + + +def load_channel_class(module_name: str) -> type[BaseChannel]: + """Import *module_name* and return the first BaseChannel subclass found.""" + from nanobot.channels.base import BaseChannel as _Base + + mod = importlib.import_module(f"nanobot.channels.{module_name}") + for attr in dir(mod): + obj = getattr(mod, attr) + if isinstance(obj, type) and issubclass(obj, _Base) and obj is not _Base: + return obj + raise ImportError(f"No BaseChannel subclass in nanobot.channels.{module_name}") diff --git a/core/nanobot/nanobot/channels/slack.py b/core/nanobot/nanobot/channels/slack.py new file mode 100644 index 0000000..5819212 --- /dev/null +++ b/core/nanobot/nanobot/channels/slack.py @@ -0,0 +1,281 @@ +"""Slack channel implementation using Socket Mode.""" + +import asyncio +import re +from typing import Any + +from loguru import logger +from slack_sdk.socket_mode.request import SocketModeRequest +from slack_sdk.socket_mode.response import SocketModeResponse +from slack_sdk.socket_mode.websockets import SocketModeClient +from slack_sdk.web.async_client import AsyncWebClient +from slackify_markdown import slackify_markdown + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.schema import SlackConfig + + +class SlackChannel(BaseChannel): + """Slack channel using Socket Mode.""" + + name = "slack" + display_name = "Slack" + + def __init__(self, config: SlackConfig, bus: MessageBus): + super().__init__(config, bus) + self.config: SlackConfig = config + self._web_client: AsyncWebClient | None = None + self._socket_client: SocketModeClient | None = None + self._bot_user_id: str | None = None + + async def start(self) -> None: + """Start the Slack Socket Mode client.""" + if not self.config.bot_token or not self.config.app_token: + logger.error("Slack bot/app token not configured") + return + if self.config.mode != "socket": + logger.error("Unsupported Slack mode: {}", self.config.mode) + return + + self._running = True + + self._web_client = AsyncWebClient(token=self.config.bot_token) + self._socket_client = SocketModeClient( + app_token=self.config.app_token, + web_client=self._web_client, + ) + + self._socket_client.socket_mode_request_listeners.append(self._on_socket_request) + + # Resolve bot user ID for mention handling + try: + auth = await self._web_client.auth_test() + self._bot_user_id = auth.get("user_id") + logger.info("Slack bot connected as {}", self._bot_user_id) + except Exception as e: + logger.warning("Slack auth_test failed: {}", e) + + logger.info("Starting Slack Socket Mode client...") + await self._socket_client.connect() + + while self._running: + await asyncio.sleep(1) + + async def stop(self) -> None: + """Stop the Slack client.""" + self._running = False + if self._socket_client: + try: + await self._socket_client.close() + except Exception as e: + logger.warning("Slack socket close failed: {}", e) + self._socket_client = None + + async def send(self, msg: OutboundMessage) -> None: + """Send a message through Slack.""" + if not self._web_client: + logger.warning("Slack client not running") + return + try: + slack_meta = msg.metadata.get("slack", {}) if msg.metadata else {} + thread_ts = slack_meta.get("thread_ts") + channel_type = slack_meta.get("channel_type") + # Slack DMs don't use threads; channel/group replies may keep thread_ts. + thread_ts_param = thread_ts if thread_ts and channel_type != "im" else None + + # Slack rejects empty text payloads. Keep media-only messages media-only, + # but send a single blank message when the bot has no text or files to send. + if msg.content or not (msg.media or []): + await self._web_client.chat_postMessage( + channel=msg.chat_id, + text=self._to_mrkdwn(msg.content) if msg.content else " ", + thread_ts=thread_ts_param, + ) + + for media_path in msg.media or []: + try: + await self._web_client.files_upload_v2( + channel=msg.chat_id, + file=media_path, + thread_ts=thread_ts_param, + ) + except Exception as e: + logger.error("Failed to upload file {}: {}", media_path, e) + except Exception as e: + logger.error("Error sending Slack message: {}", e) + + async def _on_socket_request( + self, + client: SocketModeClient, + req: SocketModeRequest, + ) -> None: + """Handle incoming Socket Mode requests.""" + if req.type != "events_api": + return + + # Acknowledge right away + await client.send_socket_mode_response( + SocketModeResponse(envelope_id=req.envelope_id) + ) + + payload = req.payload or {} + event = payload.get("event") or {} + event_type = event.get("type") + + # Handle app mentions or plain messages + if event_type not in ("message", "app_mention"): + return + + sender_id = event.get("user") + chat_id = event.get("channel") + + # Ignore bot/system messages (any subtype = not a normal user message) + if event.get("subtype"): + return + if self._bot_user_id and sender_id == self._bot_user_id: + return + + # Avoid double-processing: Slack sends both `message` and `app_mention` + # for mentions in channels. Prefer `app_mention`. + text = event.get("text") or "" + if event_type == "message" and self._bot_user_id and f"<@{self._bot_user_id}>" in text: + return + + # Debug: log basic event shape + logger.debug( + "Slack event: type={} subtype={} user={} channel={} channel_type={} text={}", + event_type, + event.get("subtype"), + sender_id, + chat_id, + event.get("channel_type"), + text[:80], + ) + if not sender_id or not chat_id: + return + + channel_type = event.get("channel_type") or "" + + if not self._is_allowed(sender_id, chat_id, channel_type): + return + + if channel_type != "im" and not self._should_respond_in_channel(event_type, text, chat_id): + return + + text = self._strip_bot_mention(text) + + thread_ts = event.get("thread_ts") + if self.config.reply_in_thread and not thread_ts: + thread_ts = event.get("ts") + # Add :eyes: reaction to the triggering message (best-effort) + try: + if self._web_client and event.get("ts"): + await self._web_client.reactions_add( + channel=chat_id, + name=self.config.react_emoji, + timestamp=event.get("ts"), + ) + except Exception as e: + logger.debug("Slack reactions_add failed: {}", e) + + # Thread-scoped session key for channel/group messages + session_key = f"slack:{chat_id}:{thread_ts}" if thread_ts and channel_type != "im" else None + + try: + await self._handle_message( + sender_id=sender_id, + chat_id=chat_id, + content=text, + metadata={ + "slack": { + "event": event, + "thread_ts": thread_ts, + "channel_type": channel_type, + }, + }, + session_key=session_key, + ) + except Exception: + logger.exception("Error handling Slack message from {}", sender_id) + + def _is_allowed(self, sender_id: str, chat_id: str, channel_type: str) -> bool: + if channel_type == "im": + if not self.config.dm.enabled: + return False + if self.config.dm.policy == "allowlist": + return sender_id in self.config.dm.allow_from + return True + + # Group / channel messages + if self.config.group_policy == "allowlist": + return chat_id in self.config.group_allow_from + return True + + def _should_respond_in_channel(self, event_type: str, text: str, chat_id: str) -> bool: + if self.config.group_policy == "open": + return True + if self.config.group_policy == "mention": + if event_type == "app_mention": + return True + return self._bot_user_id is not None and f"<@{self._bot_user_id}>" in text + if self.config.group_policy == "allowlist": + return chat_id in self.config.group_allow_from + return False + + def _strip_bot_mention(self, text: str) -> str: + if not text or not self._bot_user_id: + return text + return re.sub(rf"<@{re.escape(self._bot_user_id)}>\s*", "", text).strip() + + _TABLE_RE = re.compile(r"(?m)^\|.*\|$(?:\n\|[\s:|-]*\|$)(?:\n\|.*\|$)*") + _CODE_FENCE_RE = re.compile(r"```[\s\S]*?```") + _INLINE_CODE_RE = re.compile(r"`[^`]+`") + _LEFTOVER_BOLD_RE = re.compile(r"\*\*(.+?)\*\*") + _LEFTOVER_HEADER_RE = re.compile(r"^#{1,6}\s+(.+)$", re.MULTILINE) + _BARE_URL_RE = re.compile(r"(? str: + """Convert Markdown to Slack mrkdwn, including tables.""" + if not text: + return "" + text = cls._TABLE_RE.sub(cls._convert_table, text) + return cls._fixup_mrkdwn(slackify_markdown(text)) + + @classmethod + def _fixup_mrkdwn(cls, text: str) -> str: + """Fix markdown artifacts that slackify_markdown misses.""" + code_blocks: list[str] = [] + + def _save_code(m: re.Match) -> str: + code_blocks.append(m.group(0)) + return f"\x00CB{len(code_blocks) - 1}\x00" + + text = cls._CODE_FENCE_RE.sub(_save_code, text) + text = cls._INLINE_CODE_RE.sub(_save_code, text) + text = cls._LEFTOVER_BOLD_RE.sub(r"*\1*", text) + text = cls._LEFTOVER_HEADER_RE.sub(r"*\1*", text) + text = cls._BARE_URL_RE.sub(lambda m: m.group(0).replace("&", "&"), text) + + for i, block in enumerate(code_blocks): + text = text.replace(f"\x00CB{i}\x00", block) + return text + + @staticmethod + def _convert_table(match: re.Match) -> str: + """Convert a Markdown table to a Slack-readable list.""" + lines = [ln.strip() for ln in match.group(0).strip().splitlines() if ln.strip()] + if len(lines) < 2: + return match.group(0) + headers = [h.strip() for h in lines[0].strip("|").split("|")] + start = 2 if re.fullmatch(r"[|\s:\-]+", lines[1]) else 1 + rows: list[str] = [] + for line in lines[start:]: + cells = [c.strip() for c in line.strip("|").split("|")] + cells = (cells + [""] * len(headers))[: len(headers)] + parts = [f"**{headers[i]}**: {cells[i]}" for i in range(len(headers)) if cells[i]] + if parts: + rows.append(" · ".join(parts)) + return "\n".join(rows) diff --git a/core/nanobot/nanobot/channels/telegram.py b/core/nanobot/nanobot/channels/telegram.py new file mode 100644 index 0000000..9f93843 --- /dev/null +++ b/core/nanobot/nanobot/channels/telegram.py @@ -0,0 +1,735 @@ +"""Telegram channel implementation using python-telegram-bot.""" + +from __future__ import annotations + +import asyncio +import re +import time +import unicodedata + +from loguru import logger +from telegram import BotCommand, ReplyParameters, Update +from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters +from telegram.request import HTTPXRequest + +from nanobot.bus.events import OutboundMessage +from nanobot.bus.queue import MessageBus +from nanobot.channels.base import BaseChannel +from nanobot.config.paths import get_media_dir +from nanobot.config.schema import TelegramConfig +from nanobot.utils.helpers import split_message + +TELEGRAM_MAX_MESSAGE_LEN = 4000 # Telegram message character limit + + +def _strip_md(s: str) -> str: + """Strip markdown inline formatting from text.""" + s = re.sub(r'\*\*(.+?)\*\*', r'\1', s) + s = re.sub(r'__(.+?)__', r'\1', s) + s = re.sub(r'~~(.+?)~~', r'\1', s) + s = re.sub(r'`([^`]+)`', r'\1', s) + return s.strip() + + +def _render_table_box(table_lines: list[str]) -> str: + """Convert markdown pipe-table to compact aligned text for 
 display."""
+
+    def dw(s: str) -> int:
+        return sum(2 if unicodedata.east_asian_width(c) in ('W', 'F') else 1 for c in s)
+
+    rows: list[list[str]] = []
+    has_sep = False
+    for line in table_lines:
+        cells = [_strip_md(c) for c in line.strip().strip('|').split('|')]
+        if all(re.match(r'^:?-+:?$', c) for c in cells if c):
+            has_sep = True
+            continue
+        rows.append(cells)
+    if not rows or not has_sep:
+        return '\n'.join(table_lines)
+
+    ncols = max(len(r) for r in rows)
+    for r in rows:
+        r.extend([''] * (ncols - len(r)))
+    widths = [max(dw(r[c]) for r in rows) for c in range(ncols)]
+
+    def dr(cells: list[str]) -> str:
+        return '  '.join(f'{c}{" " * (w - dw(c))}' for c, w in zip(cells, widths))
+
+    out = [dr(rows[0])]
+    out.append('  '.join('─' * w for w in widths))
+    for row in rows[1:]:
+        out.append(dr(row))
+    return '\n'.join(out)
+
+
+def _markdown_to_telegram_html(text: str) -> str:
+    """
+    Convert markdown to Telegram-safe HTML.
+    """
+    if not text:
+        return ""
+
+    # 1. Extract and protect code blocks (preserve content from other processing)
+    code_blocks: list[str] = []
+    def save_code_block(m: re.Match) -> str:
+        code_blocks.append(m.group(1))
+        return f"\x00CB{len(code_blocks) - 1}\x00"
+
+    text = re.sub(r'```[\w]*\n?([\s\S]*?)```', save_code_block, text)
+
+    # 1.5. Convert markdown tables to box-drawing (reuse code_block placeholders)
+    lines = text.split('\n')
+    rebuilt: list[str] = []
+    li = 0
+    while li < len(lines):
+        if re.match(r'^\s*\|.+\|', lines[li]):
+            tbl: list[str] = []
+            while li < len(lines) and re.match(r'^\s*\|.+\|', lines[li]):
+                tbl.append(lines[li])
+                li += 1
+            box = _render_table_box(tbl)
+            if box != '\n'.join(tbl):
+                code_blocks.append(box)
+                rebuilt.append(f"\x00CB{len(code_blocks) - 1}\x00")
+            else:
+                rebuilt.extend(tbl)
+        else:
+            rebuilt.append(lines[li])
+            li += 1
+    text = '\n'.join(rebuilt)
+
+    # 2. Extract and protect inline code
+    inline_codes: list[str] = []
+    def save_inline_code(m: re.Match) -> str:
+        inline_codes.append(m.group(1))
+        return f"\x00IC{len(inline_codes) - 1}\x00"
+
+    text = re.sub(r'`([^`]+)`', save_inline_code, text)
+
+    # 3. Headers # Title -> just the title text
+    text = re.sub(r'^#{1,6}\s+(.+)$', r'\1', text, flags=re.MULTILINE)
+
+    # 4. Blockquotes > text -> just the text (before HTML escaping)
+    text = re.sub(r'^>\s*(.*)$', r'\1', text, flags=re.MULTILINE)
+
+    # 5. Escape HTML special characters
+    text = text.replace("&", "&").replace("<", "<").replace(">", ">")
+
+    # 6. Links [text](url) - must be before bold/italic to handle nested cases
+    text = re.sub(r'\[([^\]]+)\]\(([^)]+)\)', r'\1', text)
+
+    # 7. Bold **text** or __text__
+    text = re.sub(r'\*\*(.+?)\*\*', r'\1', text)
+    text = re.sub(r'__(.+?)__', r'\1', text)
+
+    # 8. Italic _text_ (avoid matching inside words like some_var_name)
+    text = re.sub(r'(?\1', text)
+
+    # 9. Strikethrough ~~text~~
+    text = re.sub(r'~~(.+?)~~', r'\1', text)
+
+    # 10. Bullet lists - item -> • item
+    text = re.sub(r'^[-*]\s+', '• ', text, flags=re.MULTILINE)
+
+    # 11. Restore inline code with HTML tags
+    for i, code in enumerate(inline_codes):
+        # Escape HTML in code content
+        escaped = code.replace("&", "&").replace("<", "<").replace(">", ">")
+        text = text.replace(f"\x00IC{i}\x00", f"{escaped}")
+
+    # 12. Restore code blocks with HTML tags
+    for i, code in enumerate(code_blocks):
+        # Escape HTML in code content
+        escaped = code.replace("&", "&").replace("<", "<").replace(">", ">")
+        text = text.replace(f"\x00CB{i}\x00", f"
{escaped}
")
+
+    return text
+
+
+class TelegramChannel(BaseChannel):
+    """
+    Telegram channel using long polling.
+
+    Simple and reliable - no webhook/public IP needed.
+    """
+
+    name = "telegram"
+    display_name = "Telegram"
+
+    # Commands registered with Telegram's command menu
+    BOT_COMMANDS = [
+        BotCommand("start", "Start the bot"),
+        BotCommand("new", "Start a new conversation"),
+        BotCommand("stop", "Stop the current task"),
+        BotCommand("help", "Show available commands"),
+    ]
+
+    def __init__(self, config: TelegramConfig, bus: MessageBus):
+        super().__init__(config, bus)
+        self.config: TelegramConfig = config
+        self._app: Application | None = None
+        self._chat_ids: dict[str, int] = {}  # Map sender_id to chat_id for replies
+        self._typing_tasks: dict[str, asyncio.Task] = {}  # chat_id -> typing loop task
+        self._media_group_buffers: dict[str, dict] = {}
+        self._media_group_tasks: dict[str, asyncio.Task] = {}
+        self._message_threads: dict[tuple[str, int], int] = {}
+        self._bot_user_id: int | None = None
+        self._bot_username: str | None = None
+
+    def is_allowed(self, sender_id: str) -> bool:
+        """Preserve Telegram's legacy id|username allowlist matching."""
+        if super().is_allowed(sender_id):
+            return True
+
+        allow_list = getattr(self.config, "allow_from", [])
+        if not allow_list or "*" in allow_list:
+            return False
+
+        sender_str = str(sender_id)
+        if sender_str.count("|") != 1:
+            return False
+
+        sid, username = sender_str.split("|", 1)
+        if not sid.isdigit() or not username:
+            return False
+
+        return sid in allow_list or username in allow_list
+
+    async def start(self) -> None:
+        """Start the Telegram bot with long polling."""
+        if not self.config.token:
+            logger.error("Telegram bot token not configured")
+            return
+
+        self._running = True
+
+        # Build the application with larger connection pool to avoid pool-timeout on long runs
+        req = HTTPXRequest(
+            connection_pool_size=16,
+            pool_timeout=5.0,
+            connect_timeout=30.0,
+            read_timeout=30.0,
+            proxy=self.config.proxy if self.config.proxy else None,
+        )
+        builder = Application.builder().token(self.config.token).request(req).get_updates_request(req)
+        self._app = builder.build()
+        self._app.add_error_handler(self._on_error)
+
+        # Add command handlers
+        self._app.add_handler(CommandHandler("start", self._on_start))
+        self._app.add_handler(CommandHandler("new", self._forward_command))
+        self._app.add_handler(CommandHandler("stop", self._forward_command))
+        self._app.add_handler(CommandHandler("help", self._on_help))
+
+        # Add message handler for text, photos, voice, documents
+        self._app.add_handler(
+            MessageHandler(
+                (filters.TEXT | filters.PHOTO | filters.VOICE | filters.AUDIO | filters.Document.ALL)
+                & ~filters.COMMAND,
+                self._on_message
+            )
+        )
+
+        logger.info("Starting Telegram bot (polling mode)...")
+
+        # Initialize and start polling
+        await self._app.initialize()
+        await self._app.start()
+
+        # Get bot info and register command menu
+        bot_info = await self._app.bot.get_me()
+        self._bot_user_id = getattr(bot_info, "id", None)
+        self._bot_username = getattr(bot_info, "username", None)
+        logger.info("Telegram bot @{} connected", bot_info.username)
+
+        try:
+            await self._app.bot.set_my_commands(self.BOT_COMMANDS)
+            logger.debug("Telegram bot commands registered")
+        except Exception as e:
+            logger.warning("Failed to register bot commands: {}", e)
+
+        # Start polling (this runs until stopped)
+        await self._app.updater.start_polling(
+            allowed_updates=["message"],
+            drop_pending_updates=True  # Ignore old messages on startup
+        )
+
+        # Keep running until stopped
+        while self._running:
+            await asyncio.sleep(1)
+
+    async def stop(self) -> None:
+        """Stop the Telegram bot."""
+        self._running = False
+
+        # Cancel all typing indicators
+        for chat_id in list(self._typing_tasks):
+            self._stop_typing(chat_id)
+
+        for task in self._media_group_tasks.values():
+            task.cancel()
+        self._media_group_tasks.clear()
+        self._media_group_buffers.clear()
+
+        if self._app:
+            logger.info("Stopping Telegram bot...")
+            await self._app.updater.stop()
+            await self._app.stop()
+            await self._app.shutdown()
+            self._app = None
+
+    @staticmethod
+    def _get_media_type(path: str) -> str:
+        """Guess media type from file extension."""
+        ext = path.rsplit(".", 1)[-1].lower() if "." in path else ""
+        if ext in ("jpg", "jpeg", "png", "gif", "webp"):
+            return "photo"
+        if ext == "ogg":
+            return "voice"
+        if ext in ("mp3", "m4a", "wav", "aac"):
+            return "audio"
+        return "document"
+
+    async def send(self, msg: OutboundMessage) -> None:
+        """Send a message through Telegram."""
+        if not self._app:
+            logger.warning("Telegram bot not running")
+            return
+
+        # Only stop typing indicator for final responses
+        if not msg.metadata.get("_progress", False):
+            self._stop_typing(msg.chat_id)
+
+        try:
+            chat_id = int(msg.chat_id)
+        except ValueError:
+            logger.error("Invalid chat_id: {}", msg.chat_id)
+            return
+        reply_to_message_id = msg.metadata.get("message_id")
+        message_thread_id = msg.metadata.get("message_thread_id")
+        if message_thread_id is None and reply_to_message_id is not None:
+            message_thread_id = self._message_threads.get((msg.chat_id, reply_to_message_id))
+        thread_kwargs = {}
+        if message_thread_id is not None:
+            thread_kwargs["message_thread_id"] = message_thread_id
+
+        reply_params = None
+        if self.config.reply_to_message:
+            if reply_to_message_id:
+                reply_params = ReplyParameters(
+                    message_id=reply_to_message_id,
+                    allow_sending_without_reply=True
+                )
+
+        # Send media files
+        for media_path in (msg.media or []):
+            try:
+                media_type = self._get_media_type(media_path)
+                sender = {
+                    "photo": self._app.bot.send_photo,
+                    "voice": self._app.bot.send_voice,
+                    "audio": self._app.bot.send_audio,
+                }.get(media_type, self._app.bot.send_document)
+                param = "photo" if media_type == "photo" else media_type if media_type in ("voice", "audio") else "document"
+                with open(media_path, 'rb') as f:
+                    await sender(
+                        chat_id=chat_id,
+                        **{param: f},
+                        reply_parameters=reply_params,
+                        **thread_kwargs,
+                    )
+            except Exception as e:
+                filename = media_path.rsplit("/", 1)[-1]
+                logger.error("Failed to send media {}: {}", media_path, e)
+                await self._app.bot.send_message(
+                    chat_id=chat_id,
+                    text=f"[Failed to send: {filename}]",
+                    reply_parameters=reply_params,
+                    **thread_kwargs,
+                )
+
+        # Send text content
+        if msg.content and msg.content != "[empty message]":
+            is_progress = msg.metadata.get("_progress", False)
+
+            for chunk in split_message(msg.content, TELEGRAM_MAX_MESSAGE_LEN):
+                # Final response: simulate streaming via draft, then persist
+                if not is_progress:
+                    await self._send_with_streaming(chat_id, chunk, reply_params, thread_kwargs)
+                else:
+                    await self._send_text(chat_id, chunk, reply_params, thread_kwargs)
+
+    async def _send_text(
+        self,
+        chat_id: int,
+        text: str,
+        reply_params=None,
+        thread_kwargs: dict | None = None,
+    ) -> None:
+        """Send a plain text message with HTML fallback."""
+        try:
+            html = _markdown_to_telegram_html(text)
+            await self._app.bot.send_message(
+                chat_id=chat_id, text=html, parse_mode="HTML",
+                reply_parameters=reply_params,
+                **(thread_kwargs or {}),
+            )
+        except Exception as e:
+            logger.warning("HTML parse failed, falling back to plain text: {}", e)
+            try:
+                await self._app.bot.send_message(
+                    chat_id=chat_id,
+                    text=text,
+                    reply_parameters=reply_params,
+                    **(thread_kwargs or {}),
+                )
+            except Exception as e2:
+                logger.error("Error sending Telegram message: {}", e2)
+
+    async def _send_with_streaming(
+        self,
+        chat_id: int,
+        text: str,
+        reply_params=None,
+        thread_kwargs: dict | None = None,
+    ) -> None:
+        """Simulate streaming via send_message_draft, then persist with send_message."""
+        draft_id = int(time.time() * 1000) % (2**31)
+        try:
+            step = max(len(text) // 8, 40)
+            for i in range(step, len(text), step):
+                await self._app.bot.send_message_draft(
+                    chat_id=chat_id, draft_id=draft_id, text=text[:i],
+                )
+                await asyncio.sleep(0.04)
+            await self._app.bot.send_message_draft(
+                chat_id=chat_id, draft_id=draft_id, text=text,
+            )
+            await asyncio.sleep(0.15)
+        except Exception:
+            pass
+        await self._send_text(chat_id, text, reply_params, thread_kwargs)
+
+    async def _on_start(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /start command."""
+        if not update.message or not update.effective_user:
+            return
+
+        user = update.effective_user
+        await update.message.reply_text(
+            f"👋 Hi {user.first_name}! I'm nanobot.\n\n"
+            "Send me a message and I'll respond!\n"
+            "Type /help to see available commands."
+        )
+
+    async def _on_help(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle /help command, bypassing ACL so all users can access it."""
+        if not update.message:
+            return
+        await update.message.reply_text(
+            "🐈 nanobot commands:\n"
+            "/new — Start a new conversation\n"
+            "/stop — Stop the current task\n"
+            "/help — Show available commands"
+        )
+
+    @staticmethod
+    def _sender_id(user) -> str:
+        """Build sender_id with username for allowlist matching."""
+        sid = str(user.id)
+        return f"{sid}|{user.username}" if user.username else sid
+
+    @staticmethod
+    def _derive_topic_session_key(message) -> str | None:
+        """Derive topic-scoped session key for non-private Telegram chats."""
+        message_thread_id = getattr(message, "message_thread_id", None)
+        if message.chat.type == "private" or message_thread_id is None:
+            return None
+        return f"telegram:{message.chat_id}:topic:{message_thread_id}"
+
+    @staticmethod
+    def _build_message_metadata(message, user) -> dict:
+        """Build common Telegram inbound metadata payload."""
+        return {
+            "message_id": message.message_id,
+            "user_id": user.id,
+            "username": user.username,
+            "first_name": user.first_name,
+            "is_group": message.chat.type != "private",
+            "message_thread_id": getattr(message, "message_thread_id", None),
+            "is_forum": bool(getattr(message.chat, "is_forum", False)),
+        }
+
+    async def _ensure_bot_identity(self) -> tuple[int | None, str | None]:
+        """Load bot identity once and reuse it for mention/reply checks."""
+        if self._bot_user_id is not None or self._bot_username is not None:
+            return self._bot_user_id, self._bot_username
+        if not self._app:
+            return None, None
+        bot_info = await self._app.bot.get_me()
+        self._bot_user_id = getattr(bot_info, "id", None)
+        self._bot_username = getattr(bot_info, "username", None)
+        return self._bot_user_id, self._bot_username
+
+    @staticmethod
+    def _has_mention_entity(
+        text: str,
+        entities,
+        bot_username: str,
+        bot_id: int | None,
+    ) -> bool:
+        """Check Telegram mention entities against the bot username."""
+        handle = f"@{bot_username}".lower()
+        for entity in entities or []:
+            entity_type = getattr(entity, "type", None)
+            if entity_type == "text_mention":
+                user = getattr(entity, "user", None)
+                if user is not None and bot_id is not None and getattr(user, "id", None) == bot_id:
+                    return True
+                continue
+            if entity_type != "mention":
+                continue
+            offset = getattr(entity, "offset", None)
+            length = getattr(entity, "length", None)
+            if offset is None or length is None:
+                continue
+            if text[offset : offset + length].lower() == handle:
+                return True
+        return handle in text.lower()
+
+    async def _is_group_message_for_bot(self, message) -> bool:
+        """Allow group messages when policy is open, @mentioned, or replying to the bot."""
+        if message.chat.type == "private" or self.config.group_policy == "open":
+            return True
+
+        bot_id, bot_username = await self._ensure_bot_identity()
+        if bot_username:
+            text = message.text or ""
+            caption = message.caption or ""
+            if self._has_mention_entity(
+                text,
+                getattr(message, "entities", None),
+                bot_username,
+                bot_id,
+            ):
+                return True
+            if self._has_mention_entity(
+                caption,
+                getattr(message, "caption_entities", None),
+                bot_username,
+                bot_id,
+            ):
+                return True
+
+        reply_user = getattr(getattr(message, "reply_to_message", None), "from_user", None)
+        return bool(bot_id and reply_user and reply_user.id == bot_id)
+
+    def _remember_thread_context(self, message) -> None:
+        """Cache topic thread id by chat/message id for follow-up replies."""
+        message_thread_id = getattr(message, "message_thread_id", None)
+        if message_thread_id is None:
+            return
+        key = (str(message.chat_id), message.message_id)
+        self._message_threads[key] = message_thread_id
+        if len(self._message_threads) > 1000:
+            self._message_threads.pop(next(iter(self._message_threads)))
+
+    async def _forward_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Forward slash commands to the bus for unified handling in AgentLoop."""
+        if not update.message or not update.effective_user:
+            return
+        message = update.message
+        user = update.effective_user
+        self._remember_thread_context(message)
+        await self._handle_message(
+            sender_id=self._sender_id(user),
+            chat_id=str(message.chat_id),
+            content=message.text,
+            metadata=self._build_message_metadata(message, user),
+            session_key=self._derive_topic_session_key(message),
+        )
+
+    async def _on_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Handle incoming messages (text, photos, voice, documents)."""
+        if not update.message or not update.effective_user:
+            return
+
+        message = update.message
+        user = update.effective_user
+        chat_id = message.chat_id
+        sender_id = self._sender_id(user)
+        self._remember_thread_context(message)
+
+        # Store chat_id for replies
+        self._chat_ids[sender_id] = chat_id
+
+        if not await self._is_group_message_for_bot(message):
+            return
+
+        # Build content from text and/or media
+        content_parts = []
+        media_paths = []
+
+        # Text content
+        if message.text:
+            content_parts.append(message.text)
+        if message.caption:
+            content_parts.append(message.caption)
+
+        # Handle media files
+        media_file = None
+        media_type = None
+
+        if message.photo:
+            media_file = message.photo[-1]  # Largest photo
+            media_type = "image"
+        elif message.voice:
+            media_file = message.voice
+            media_type = "voice"
+        elif message.audio:
+            media_file = message.audio
+            media_type = "audio"
+        elif message.document:
+            media_file = message.document
+            media_type = "file"
+
+        # Download media if present
+        if media_file and self._app:
+            try:
+                file = await self._app.bot.get_file(media_file.file_id)
+                ext = self._get_extension(
+                    media_type,
+                    getattr(media_file, 'mime_type', None),
+                    getattr(media_file, 'file_name', None),
+                )
+                media_dir = get_media_dir("telegram")
+
+                file_path = media_dir / f"{media_file.file_id[:16]}{ext}"
+                await file.download_to_drive(str(file_path))
+
+                media_paths.append(str(file_path))
+
+                if media_type in ("voice", "audio"):
+                    transcription = await self.transcribe_audio(file_path)
+                    if transcription:
+                        logger.info("Transcribed {}: {}...", media_type, transcription[:50])
+                        content_parts.append(f"[transcription: {transcription}]")
+                    else:
+                        content_parts.append(f"[{media_type}: {file_path}]")
+                else:
+                    content_parts.append(f"[{media_type}: {file_path}]")
+
+                logger.debug("Downloaded {} to {}", media_type, file_path)
+            except Exception as e:
+                logger.error("Failed to download media: {}", e)
+                content_parts.append(f"[{media_type}: download failed]")
+
+        content = "\n".join(content_parts) if content_parts else "[empty message]"
+
+        logger.debug("Telegram message from {}: {}...", sender_id, content[:50])
+
+        str_chat_id = str(chat_id)
+        metadata = self._build_message_metadata(message, user)
+        session_key = self._derive_topic_session_key(message)
+
+        # Telegram media groups: buffer briefly, forward as one aggregated turn.
+        if media_group_id := getattr(message, "media_group_id", None):
+            key = f"{str_chat_id}:{media_group_id}"
+            if key not in self._media_group_buffers:
+                self._media_group_buffers[key] = {
+                    "sender_id": sender_id, "chat_id": str_chat_id,
+                    "contents": [], "media": [],
+                    "metadata": metadata,
+                    "session_key": session_key,
+                }
+                self._start_typing(str_chat_id)
+            buf = self._media_group_buffers[key]
+            if content and content != "[empty message]":
+                buf["contents"].append(content)
+            buf["media"].extend(media_paths)
+            if key not in self._media_group_tasks:
+                self._media_group_tasks[key] = asyncio.create_task(self._flush_media_group(key))
+            return
+
+        # Start typing indicator before processing
+        self._start_typing(str_chat_id)
+
+        # Forward to the message bus
+        await self._handle_message(
+            sender_id=sender_id,
+            chat_id=str_chat_id,
+            content=content,
+            media=media_paths,
+            metadata=metadata,
+            session_key=session_key,
+        )
+
+    async def _flush_media_group(self, key: str) -> None:
+        """Wait briefly, then forward buffered media-group as one turn."""
+        try:
+            await asyncio.sleep(0.6)
+            if not (buf := self._media_group_buffers.pop(key, None)):
+                return
+            content = "\n".join(buf["contents"]) or "[empty message]"
+            await self._handle_message(
+                sender_id=buf["sender_id"], chat_id=buf["chat_id"],
+                content=content, media=list(dict.fromkeys(buf["media"])),
+                metadata=buf["metadata"],
+                session_key=buf.get("session_key"),
+            )
+        finally:
+            self._media_group_tasks.pop(key, None)
+
+    def _start_typing(self, chat_id: str) -> None:
+        """Start sending 'typing...' indicator for a chat."""
+        # Cancel any existing typing task for this chat
+        self._stop_typing(chat_id)
+        self._typing_tasks[chat_id] = asyncio.create_task(self._typing_loop(chat_id))
+
+    def _stop_typing(self, chat_id: str) -> None:
+        """Stop the typing indicator for a chat."""
+        task = self._typing_tasks.pop(chat_id, None)
+        if task and not task.done():
+            task.cancel()
+
+    async def _typing_loop(self, chat_id: str) -> None:
+        """Repeatedly send 'typing' action until cancelled."""
+        try:
+            while self._app:
+                await self._app.bot.send_chat_action(chat_id=int(chat_id), action="typing")
+                await asyncio.sleep(4)
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.debug("Typing indicator stopped for {}: {}", chat_id, e)
+
+    async def _on_error(self, update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
+        """Log polling / handler errors instead of silently swallowing them."""
+        logger.error("Telegram error: {}", context.error)
+
+    def _get_extension(
+        self,
+        media_type: str,
+        mime_type: str | None,
+        filename: str | None = None,
+    ) -> str:
+        """Get file extension based on media type or original filename."""
+        if mime_type:
+            ext_map = {
+                "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif",
+                "audio/ogg": ".ogg", "audio/mpeg": ".mp3", "audio/mp4": ".m4a",
+            }
+            if mime_type in ext_map:
+                return ext_map[mime_type]
+
+        type_map = {"image": ".jpg", "voice": ".ogg", "audio": ".mp3", "file": ""}
+        if ext := type_map.get(media_type, ""):
+            return ext
+
+        if filename:
+            from pathlib import Path
+
+            return "".join(Path(filename).suffixes)
+
+        return ""
diff --git a/core/nanobot/nanobot/channels/wecom.py b/core/nanobot/nanobot/channels/wecom.py
new file mode 100644
index 0000000..e0f4ae0
--- /dev/null
+++ b/core/nanobot/nanobot/channels/wecom.py
@@ -0,0 +1,353 @@
+"""WeCom (Enterprise WeChat) channel implementation using wecom_aibot_sdk."""
+
+import asyncio
+import importlib.util
+import os
+from collections import OrderedDict
+from typing import Any
+
+from loguru import logger
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.base import BaseChannel
+from nanobot.config.paths import get_media_dir
+from nanobot.config.schema import WecomConfig
+
+WECOM_AVAILABLE = importlib.util.find_spec("wecom_aibot_sdk") is not None
+
+# Message type display mapping
+MSG_TYPE_MAP = {
+    "image": "[image]",
+    "voice": "[voice]",
+    "file": "[file]",
+    "mixed": "[mixed content]",
+}
+
+
+class WecomChannel(BaseChannel):
+    """
+    WeCom (Enterprise WeChat) channel using WebSocket long connection.
+
+    Uses WebSocket to receive events - no public IP or webhook required.
+
+    Requires:
+    - Bot ID and Secret from WeCom AI Bot platform
+    """
+
+    name = "wecom"
+    display_name = "WeCom"
+
+    def __init__(self, config: WecomConfig, bus: MessageBus):
+        super().__init__(config, bus)
+        self.config: WecomConfig = config
+        self._client: Any = None
+        self._processed_message_ids: OrderedDict[str, None] = OrderedDict()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._generate_req_id = None
+        # Store frame headers for each chat to enable replies
+        self._chat_frames: dict[str, Any] = {}
+
+    async def start(self) -> None:
+        """Start the WeCom bot with WebSocket long connection."""
+        if not WECOM_AVAILABLE:
+            logger.error("WeCom SDK not installed. Run: pip install nanobot-ai[wecom]")
+            return
+
+        if not self.config.bot_id or not self.config.secret:
+            logger.error("WeCom bot_id and secret not configured")
+            return
+
+        from wecom_aibot_sdk import WSClient, generate_req_id
+
+        self._running = True
+        self._loop = asyncio.get_running_loop()
+        self._generate_req_id = generate_req_id
+
+        # Create WebSocket client
+        self._client = WSClient({
+            "bot_id": self.config.bot_id,
+            "secret": self.config.secret,
+            "reconnect_interval": 1000,
+            "max_reconnect_attempts": -1,  # Infinite reconnect
+            "heartbeat_interval": 30000,
+        })
+
+        # Register event handlers
+        self._client.on("connected", self._on_connected)
+        self._client.on("authenticated", self._on_authenticated)
+        self._client.on("disconnected", self._on_disconnected)
+        self._client.on("error", self._on_error)
+        self._client.on("message.text", self._on_text_message)
+        self._client.on("message.image", self._on_image_message)
+        self._client.on("message.voice", self._on_voice_message)
+        self._client.on("message.file", self._on_file_message)
+        self._client.on("message.mixed", self._on_mixed_message)
+        self._client.on("event.enter_chat", self._on_enter_chat)
+
+        logger.info("WeCom bot starting with WebSocket long connection")
+        logger.info("No public IP required - using WebSocket to receive events")
+
+        # Connect
+        await self._client.connect_async()
+
+        # Keep running until stopped
+        while self._running:
+            await asyncio.sleep(1)
+
+    async def stop(self) -> None:
+        """Stop the WeCom bot."""
+        self._running = False
+        if self._client:
+            await self._client.disconnect()
+        logger.info("WeCom bot stopped")
+
+    async def _on_connected(self, frame: Any) -> None:
+        """Handle WebSocket connected event."""
+        logger.info("WeCom WebSocket connected")
+
+    async def _on_authenticated(self, frame: Any) -> None:
+        """Handle authentication success event."""
+        logger.info("WeCom authenticated successfully")
+
+    async def _on_disconnected(self, frame: Any) -> None:
+        """Handle WebSocket disconnected event."""
+        reason = frame.body if hasattr(frame, 'body') else str(frame)
+        logger.warning("WeCom WebSocket disconnected: {}", reason)
+
+    async def _on_error(self, frame: Any) -> None:
+        """Handle error event."""
+        logger.error("WeCom error: {}", frame)
+
+    async def _on_text_message(self, frame: Any) -> None:
+        """Handle text message."""
+        await self._process_message(frame, "text")
+
+    async def _on_image_message(self, frame: Any) -> None:
+        """Handle image message."""
+        await self._process_message(frame, "image")
+
+    async def _on_voice_message(self, frame: Any) -> None:
+        """Handle voice message."""
+        await self._process_message(frame, "voice")
+
+    async def _on_file_message(self, frame: Any) -> None:
+        """Handle file message."""
+        await self._process_message(frame, "file")
+
+    async def _on_mixed_message(self, frame: Any) -> None:
+        """Handle mixed content message."""
+        await self._process_message(frame, "mixed")
+
+    async def _on_enter_chat(self, frame: Any) -> None:
+        """Handle enter_chat event (user opens chat with bot)."""
+        try:
+            # Extract body from WsFrame dataclass or dict
+            if hasattr(frame, 'body'):
+                body = frame.body or {}
+            elif isinstance(frame, dict):
+                body = frame.get("body", frame)
+            else:
+                body = {}
+
+            chat_id = body.get("chatid", "") if isinstance(body, dict) else ""
+
+            if chat_id and self.config.welcome_message:
+                await self._client.reply_welcome(frame, {
+                    "msgtype": "text",
+                    "text": {"content": self.config.welcome_message},
+                })
+        except Exception as e:
+            logger.error("Error handling enter_chat: {}", e)
+
+    async def _process_message(self, frame: Any, msg_type: str) -> None:
+        """Process incoming message and forward to bus."""
+        try:
+            # Extract body from WsFrame dataclass or dict
+            if hasattr(frame, 'body'):
+                body = frame.body or {}
+            elif isinstance(frame, dict):
+                body = frame.get("body", frame)
+            else:
+                body = {}
+
+            # Ensure body is a dict
+            if not isinstance(body, dict):
+                logger.warning("Invalid body type: {}", type(body))
+                return
+
+            # Extract message info
+            msg_id = body.get("msgid", "")
+            if not msg_id:
+                msg_id = f"{body.get('chatid', '')}_{body.get('sendertime', '')}"
+
+            # Deduplication check
+            if msg_id in self._processed_message_ids:
+                return
+            self._processed_message_ids[msg_id] = None
+
+            # Trim cache
+            while len(self._processed_message_ids) > 1000:
+                self._processed_message_ids.popitem(last=False)
+
+            # Extract sender info from "from" field (SDK format)
+            from_info = body.get("from", {})
+            sender_id = from_info.get("userid", "unknown") if isinstance(from_info, dict) else "unknown"
+
+            # For single chat, chatid is the sender's userid
+            # For group chat, chatid is provided in body
+            chat_type = body.get("chattype", "single")
+            chat_id = body.get("chatid", sender_id)
+
+            content_parts = []
+
+            if msg_type == "text":
+                text = body.get("text", {}).get("content", "")
+                if text:
+                    content_parts.append(text)
+
+            elif msg_type == "image":
+                image_info = body.get("image", {})
+                file_url = image_info.get("url", "")
+                aes_key = image_info.get("aeskey", "")
+
+                if file_url and aes_key:
+                    file_path = await self._download_and_save_media(file_url, aes_key, "image")
+                    if file_path:
+                        filename = os.path.basename(file_path)
+                        content_parts.append(f"[image: {filename}]\n[Image: source: {file_path}]")
+                    else:
+                        content_parts.append("[image: download failed]")
+                else:
+                    content_parts.append("[image: download failed]")
+
+            elif msg_type == "voice":
+                voice_info = body.get("voice", {})
+                # Voice message already contains transcribed content from WeCom
+                voice_content = voice_info.get("content", "")
+                if voice_content:
+                    content_parts.append(f"[voice] {voice_content}")
+                else:
+                    content_parts.append("[voice]")
+
+            elif msg_type == "file":
+                file_info = body.get("file", {})
+                file_url = file_info.get("url", "")
+                aes_key = file_info.get("aeskey", "")
+                file_name = file_info.get("name", "unknown")
+
+                if file_url and aes_key:
+                    file_path = await self._download_and_save_media(file_url, aes_key, "file", file_name)
+                    if file_path:
+                        content_parts.append(f"[file: {file_name}]\n[File: source: {file_path}]")
+                    else:
+                        content_parts.append(f"[file: {file_name}: download failed]")
+                else:
+                    content_parts.append(f"[file: {file_name}: download failed]")
+
+            elif msg_type == "mixed":
+                # Mixed content contains multiple message items
+                msg_items = body.get("mixed", {}).get("item", [])
+                for item in msg_items:
+                    item_type = item.get("type", "")
+                    if item_type == "text":
+                        text = item.get("text", {}).get("content", "")
+                        if text:
+                            content_parts.append(text)
+                    else:
+                        content_parts.append(MSG_TYPE_MAP.get(item_type, f"[{item_type}]"))
+
+            else:
+                content_parts.append(MSG_TYPE_MAP.get(msg_type, f"[{msg_type}]"))
+
+            content = "\n".join(content_parts) if content_parts else ""
+
+            if not content:
+                return
+
+            # Store frame for this chat to enable replies
+            self._chat_frames[chat_id] = frame
+
+            # Forward to message bus
+            # Note: media paths are included in content for broader model compatibility
+            await self._handle_message(
+                sender_id=sender_id,
+                chat_id=chat_id,
+                content=content,
+                media=None,
+                metadata={
+                    "message_id": msg_id,
+                    "msg_type": msg_type,
+                    "chat_type": chat_type,
+                }
+            )
+
+        except Exception as e:
+            logger.error("Error processing WeCom message: {}", e)
+
+    async def _download_and_save_media(
+        self,
+        file_url: str,
+        aes_key: str,
+        media_type: str,
+        filename: str | None = None,
+    ) -> str | None:
+        """
+        Download and decrypt media from WeCom.
+
+        Returns:
+            file_path or None if download failed
+        """
+        try:
+            data, fname = await self._client.download_file(file_url, aes_key)
+
+            if not data:
+                logger.warning("Failed to download media from WeCom")
+                return None
+
+            media_dir = get_media_dir("wecom")
+            if not filename:
+                filename = fname or f"{media_type}_{hash(file_url) % 100000}"
+            filename = os.path.basename(filename)
+
+            file_path = media_dir / filename
+            file_path.write_bytes(data)
+            logger.debug("Downloaded {} to {}", media_type, file_path)
+            return str(file_path)
+
+        except Exception as e:
+            logger.error("Error downloading media: {}", e)
+            return None
+
+    async def send(self, msg: OutboundMessage) -> None:
+        """Send a message through WeCom."""
+        if not self._client:
+            logger.warning("WeCom client not initialized")
+            return
+
+        try:
+            content = msg.content.strip()
+            if not content:
+                return
+
+            # Get the stored frame for this chat
+            frame = self._chat_frames.get(msg.chat_id)
+            if not frame:
+                logger.warning("No frame found for chat {}, cannot reply", msg.chat_id)
+                return
+
+            # Use streaming reply for better UX
+            stream_id = self._generate_req_id("stream")
+
+            # Send as streaming message with finish=True
+            await self._client.reply_stream(
+                frame,
+                stream_id,
+                content,
+                finish=True,
+            )
+
+            logger.debug("WeCom message sent to {}", msg.chat_id)
+
+        except Exception as e:
+            logger.error("Error sending WeCom message: {}", e)
diff --git a/core/nanobot/nanobot/channels/whatsapp.py b/core/nanobot/nanobot/channels/whatsapp.py
new file mode 100644
index 0000000..7fffb80
--- /dev/null
+++ b/core/nanobot/nanobot/channels/whatsapp.py
@@ -0,0 +1,171 @@
+"""WhatsApp channel implementation using Node.js bridge."""
+
+import asyncio
+import json
+import mimetypes
+from collections import OrderedDict
+
+from loguru import logger
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.base import BaseChannel
+from nanobot.config.schema import WhatsAppConfig
+
+
+class WhatsAppChannel(BaseChannel):
+    """
+    WhatsApp channel that connects to a Node.js bridge.
+
+    The bridge uses @whiskeysockets/baileys to handle the WhatsApp Web protocol.
+    Communication between Python and Node.js is via WebSocket.
+    """
+
+    name = "whatsapp"
+    display_name = "WhatsApp"
+
+    def __init__(self, config: WhatsAppConfig, bus: MessageBus):
+        super().__init__(config, bus)
+        self.config: WhatsAppConfig = config
+        self._ws = None
+        self._connected = False
+        self._processed_message_ids: OrderedDict[str, None] = OrderedDict()
+
+    async def start(self) -> None:
+        """Start the WhatsApp channel by connecting to the bridge."""
+        import websockets
+
+        bridge_url = self.config.bridge_url
+
+        logger.info("Connecting to WhatsApp bridge at {}...", bridge_url)
+
+        self._running = True
+
+        while self._running:
+            try:
+                async with websockets.connect(bridge_url) as ws:
+                    self._ws = ws
+                    # Send auth token if configured
+                    if self.config.bridge_token:
+                        await ws.send(json.dumps({"type": "auth", "token": self.config.bridge_token}))
+                    self._connected = True
+                    logger.info("Connected to WhatsApp bridge")
+
+                    # Listen for messages
+                    async for message in ws:
+                        try:
+                            await self._handle_bridge_message(message)
+                        except Exception as e:
+                            logger.error("Error handling bridge message: {}", e)
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                self._connected = False
+                self._ws = None
+                logger.warning("WhatsApp bridge connection error: {}", e)
+
+                if self._running:
+                    logger.info("Reconnecting in 5 seconds...")
+                    await asyncio.sleep(5)
+
+    async def stop(self) -> None:
+        """Stop the WhatsApp channel."""
+        self._running = False
+        self._connected = False
+
+        if self._ws:
+            await self._ws.close()
+            self._ws = None
+
+    async def send(self, msg: OutboundMessage) -> None:
+        """Send a message through WhatsApp."""
+        if not self._ws or not self._connected:
+            logger.warning("WhatsApp bridge not connected")
+            return
+
+        try:
+            payload = {
+                "type": "send",
+                "to": msg.chat_id,
+                "text": msg.content
+            }
+            await self._ws.send(json.dumps(payload, ensure_ascii=False))
+        except Exception as e:
+            logger.error("Error sending WhatsApp message: {}", e)
+
+    async def _handle_bridge_message(self, raw: str) -> None:
+        """Handle a message from the bridge."""
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            logger.warning("Invalid JSON from bridge: {}", raw[:100])
+            return
+
+        msg_type = data.get("type")
+
+        if msg_type == "message":
+            # Incoming message from WhatsApp
+            # Deprecated by whatsapp: old phone number style typically: @s.whatspp.net
+            pn = data.get("pn", "")
+            # New LID sytle typically:
+            sender = data.get("sender", "")
+            content = data.get("content", "")
+            message_id = data.get("id", "")
+
+            if message_id:
+                if message_id in self._processed_message_ids:
+                    return
+                self._processed_message_ids[message_id] = None
+                while len(self._processed_message_ids) > 1000:
+                    self._processed_message_ids.popitem(last=False)
+
+            # Extract just the phone number or lid as chat_id
+            user_id = pn if pn else sender
+            sender_id = user_id.split("@")[0] if "@" in user_id else user_id
+            logger.info("Sender {}", sender)
+
+            # Handle voice transcription if it's a voice message
+            if content == "[Voice Message]":
+                logger.info("Voice message received from {}, but direct download from bridge is not yet supported.", sender_id)
+                content = "[Voice Message: Transcription not available for WhatsApp yet]"
+
+            # Extract media paths (images/documents/videos downloaded by the bridge)
+            media_paths = data.get("media") or []
+
+            # Build content tags matching Telegram's pattern: [image: /path] or [file: /path]
+            if media_paths:
+                for p in media_paths:
+                    mime, _ = mimetypes.guess_type(p)
+                    media_type = "image" if mime and mime.startswith("image/") else "file"
+                    media_tag = f"[{media_type}: {p}]"
+                    content = f"{content}\n{media_tag}" if content else media_tag
+
+            await self._handle_message(
+                sender_id=sender_id,
+                chat_id=sender,  # Use full LID for replies
+                content=content,
+                media=media_paths,
+                metadata={
+                    "message_id": message_id,
+                    "timestamp": data.get("timestamp"),
+                    "is_group": data.get("isGroup", False)
+                }
+            )
+
+        elif msg_type == "status":
+            # Connection status update
+            status = data.get("status")
+            logger.info("WhatsApp status: {}", status)
+
+            if status == "connected":
+                self._connected = True
+            elif status == "disconnected":
+                self._connected = False
+
+        elif msg_type == "qr":
+            # QR code for authentication
+            logger.info("Scan QR code in the bridge terminal to connect WhatsApp")
+
+        elif msg_type == "error":
+            logger.error("WhatsApp bridge error: {}", data.get('error'))
diff --git a/core/nanobot/nanobot/cli/__init__.py b/core/nanobot/nanobot/cli/__init__.py
new file mode 100644
index 0000000..b023cad
--- /dev/null
+++ b/core/nanobot/nanobot/cli/__init__.py
@@ -0,0 +1 @@
+"""CLI module for nanobot."""
diff --git a/core/nanobot/nanobot/cli/commands.py b/core/nanobot/nanobot/cli/commands.py
new file mode 100644
index 0000000..7fc0672
--- /dev/null
+++ b/core/nanobot/nanobot/cli/commands.py
@@ -0,0 +1,936 @@
+"""CLI commands for nanobot."""
+
+import asyncio
+import os
+import select
+import signal
+import sys
+from pathlib import Path
+
+# Force UTF-8 encoding for Windows console
+if sys.platform == "win32":
+    if sys.stdout.encoding != "utf-8":
+        os.environ["PYTHONIOENCODING"] = "utf-8"
+        # Re-open stdout/stderr with UTF-8 encoding
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+import typer
+from prompt_toolkit import PromptSession
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.patch_stdout import patch_stdout
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.table import Table
+from rich.text import Text
+
+from nanobot import __logo__, __version__
+from nanobot.config.paths import get_workspace_path
+from nanobot.config.schema import Config
+from nanobot.utils.helpers import sync_workspace_templates
+
+app = typer.Typer(
+    name="nanobot",
+    help=f"{__logo__} nanobot - Personal AI Assistant",
+    no_args_is_help=True,
+)
+
+console = Console()
+EXIT_COMMANDS = {"exit", "quit", "/exit", "/quit", ":q"}
+
+# ---------------------------------------------------------------------------
+# CLI input: prompt_toolkit for editing, paste, history, and display
+# ---------------------------------------------------------------------------
+
+_PROMPT_SESSION: PromptSession | None = None
+_SAVED_TERM_ATTRS = None  # original termios settings, restored on exit
+
+
+def _flush_pending_tty_input() -> None:
+    """Drop unread keypresses typed while the model was generating output."""
+    try:
+        fd = sys.stdin.fileno()
+        if not os.isatty(fd):
+            return
+    except Exception:
+        return
+
+    try:
+        import termios
+        termios.tcflush(fd, termios.TCIFLUSH)
+        return
+    except Exception:
+        pass
+
+    try:
+        while True:
+            ready, _, _ = select.select([fd], [], [], 0)
+            if not ready:
+                break
+            if not os.read(fd, 4096):
+                break
+    except Exception:
+        return
+
+
+def _restore_terminal() -> None:
+    """Restore terminal to its original state (echo, line buffering, etc.)."""
+    if _SAVED_TERM_ATTRS is None:
+        return
+    try:
+        import termios
+        termios.tcsetattr(sys.stdin.fileno(), termios.TCSADRAIN, _SAVED_TERM_ATTRS)
+    except Exception:
+        pass
+
+
+def _init_prompt_session() -> None:
+    """Create the prompt_toolkit session with persistent file history."""
+    global _PROMPT_SESSION, _SAVED_TERM_ATTRS
+
+    # Save terminal state so we can restore it on exit
+    try:
+        import termios
+        _SAVED_TERM_ATTRS = termios.tcgetattr(sys.stdin.fileno())
+    except Exception:
+        pass
+
+    from nanobot.config.paths import get_cli_history_path
+
+    history_file = get_cli_history_path()
+    history_file.parent.mkdir(parents=True, exist_ok=True)
+
+    _PROMPT_SESSION = PromptSession(
+        history=FileHistory(str(history_file)),
+        enable_open_in_editor=False,
+        multiline=False,   # Enter submits (single line mode)
+    )
+
+
+def _print_agent_response(response: str, render_markdown: bool) -> None:
+    """Render assistant response with consistent terminal styling."""
+    content = response or ""
+    body = Markdown(content) if render_markdown else Text(content)
+    console.print()
+    console.print(f"[cyan]{__logo__} nanobot[/cyan]")
+    console.print(body)
+    console.print()
+
+
+def _is_exit_command(command: str) -> bool:
+    """Return True when input should end interactive chat."""
+    return command.lower() in EXIT_COMMANDS
+
+
+async def _read_interactive_input_async() -> str:
+    """Read user input using prompt_toolkit (handles paste, history, display).
+
+    prompt_toolkit natively handles:
+    - Multiline paste (bracketed paste mode)
+    - History navigation (up/down arrows)
+    - Clean display (no ghost characters or artifacts)
+    """
+    if _PROMPT_SESSION is None:
+        raise RuntimeError("Call _init_prompt_session() first")
+    try:
+        with patch_stdout():
+            return await _PROMPT_SESSION.prompt_async(
+                HTML("You: "),
+            )
+    except EOFError as exc:
+        raise KeyboardInterrupt from exc
+
+
+
+def version_callback(value: bool):
+    if value:
+        console.print(f"{__logo__} nanobot v{__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        None, "--version", "-v", callback=version_callback, is_eager=True
+    ),
+):
+    """nanobot - Personal AI Assistant."""
+    pass
+
+
+# ============================================================================
+# Onboard / Setup
+# ============================================================================
+
+
+@app.command()
+def onboard():
+    """Initialize nanobot configuration and workspace."""
+    from nanobot.config.loader import get_config_path, load_config, save_config
+    from nanobot.config.schema import Config
+
+    config_path = get_config_path()
+
+    if config_path.exists():
+        console.print(f"[yellow]Config already exists at {config_path}[/yellow]")
+        console.print("  [bold]y[/bold] = overwrite with defaults (existing values will be lost)")
+        console.print("  [bold]N[/bold] = refresh config, keeping existing values and adding new fields")
+        if typer.confirm("Overwrite?"):
+            config = Config()
+            save_config(config)
+            console.print(f"[green]✓[/green] Config reset to defaults at {config_path}")
+        else:
+            config = load_config()
+            save_config(config)
+            console.print(f"[green]✓[/green] Config refreshed at {config_path} (existing values preserved)")
+    else:
+        save_config(Config())
+        console.print(f"[green]✓[/green] Created config at {config_path}")
+
+    console.print("[dim]Config template now uses `maxTokens` + `contextWindowTokens`; `memoryWindow` is no longer a runtime setting.[/dim]")
+
+    # Create workspace
+    workspace = get_workspace_path()
+
+    if not workspace.exists():
+        workspace.mkdir(parents=True, exist_ok=True)
+        console.print(f"[green]✓[/green] Created workspace at {workspace}")
+
+    sync_workspace_templates(workspace)
+
+    console.print(f"\n{__logo__} nanobot is ready!")
+    console.print("\nNext steps:")
+    console.print("  1. Add your API key to [cyan]~/.nanobot/config.json[/cyan]")
+    console.print("     Get one at: https://openrouter.ai/keys")
+    console.print("  2. Chat: [cyan]nanobot agent -m \"Hello!\"[/cyan]")
+    console.print("\n[dim]Want Telegram/WhatsApp? See: https://github.com/HKUDS/nanobot#-chat-apps[/dim]")
+
+
+
+
+
+def _make_provider(config: Config):
+    """Create the appropriate LLM provider from config."""
+    from nanobot.providers.base import GenerationSettings
+    from nanobot.providers.openai_codex_provider import OpenAICodexProvider
+    from nanobot.providers.azure_openai_provider import AzureOpenAIProvider
+
+    model = config.agents.defaults.model
+    provider_name = config.get_provider_name(model)
+    p = config.get_provider(model)
+
+    # OpenAI Codex (OAuth)
+    if provider_name == "openai_codex" or model.startswith("openai-codex/"):
+        provider = OpenAICodexProvider(default_model=model)
+    # Custom: direct OpenAI-compatible endpoint, bypasses LiteLLM
+    elif provider_name == "custom":
+        from nanobot.providers.custom_provider import CustomProvider
+        provider = CustomProvider(
+            api_key=p.api_key if p else "no-key",
+            api_base=config.get_api_base(model) or "http://localhost:8000/v1",
+            default_model=model,
+        )
+    # Azure OpenAI: direct Azure OpenAI endpoint with deployment name
+    elif provider_name == "azure_openai":
+        if not p or not p.api_key or not p.api_base:
+            console.print("[red]Error: Azure OpenAI requires api_key and api_base.[/red]")
+            console.print("Set them in ~/.nanobot/config.json under providers.azure_openai section")
+            console.print("Use the model field to specify the deployment name.")
+            raise typer.Exit(1)
+        provider = AzureOpenAIProvider(
+            api_key=p.api_key,
+            api_base=p.api_base,
+            default_model=model,
+        )
+    else:
+        from nanobot.providers.litellm_provider import LiteLLMProvider
+        from nanobot.providers.registry import find_by_name
+        spec = find_by_name(provider_name)
+        if not model.startswith("bedrock/") and not (p and p.api_key) and not (spec and (spec.is_oauth or spec.is_local)):
+            console.print("[red]Error: No API key configured.[/red]")
+            console.print("Set one in ~/.nanobot/config.json under providers section")
+            raise typer.Exit(1)
+        provider = LiteLLMProvider(
+            api_key=p.api_key if p else None,
+            api_base=config.get_api_base(model),
+            default_model=model,
+            extra_headers=p.extra_headers if p else None,
+            provider_name=provider_name,
+        )
+
+    defaults = config.agents.defaults
+    provider.generation = GenerationSettings(
+        temperature=defaults.temperature,
+        max_tokens=defaults.max_tokens,
+        reasoning_effort=defaults.reasoning_effort,
+    )
+    return provider
+
+
+def _load_runtime_config(config: str | None = None, workspace: str | None = None) -> Config:
+    """Load config and optionally override the active workspace."""
+    from nanobot.config.loader import load_config, set_config_path
+
+    config_path = None
+    if config:
+        config_path = Path(config).expanduser().resolve()
+        if not config_path.exists():
+            console.print(f"[red]Error: Config file not found: {config_path}[/red]")
+            raise typer.Exit(1)
+        set_config_path(config_path)
+        console.print(f"[dim]Using config: {config_path}[/dim]")
+
+    loaded = load_config(config_path)
+    if workspace:
+        loaded.agents.defaults.workspace = workspace
+    return loaded
+
+
+def _print_deprecated_memory_window_notice(config: Config) -> None:
+    """Warn when running with old memoryWindow-only config."""
+    if config.agents.defaults.should_warn_deprecated_memory_window:
+        console.print(
+            "[yellow]Hint:[/yellow] Detected deprecated `memoryWindow` without "
+            "`contextWindowTokens`. `memoryWindow` is ignored; run "
+            "[cyan]nanobot onboard[/cyan] to refresh your config template."
+        )
+
+
+# ============================================================================
+# Gateway / Server
+# ============================================================================
+
+
+@app.command()
+def gateway(
+    port: int | None = typer.Option(None, "--port", "-p", help="Gateway port"),
+    workspace: str | None = typer.Option(None, "--workspace", "-w", help="Workspace directory"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
+    config: str | None = typer.Option(None, "--config", "-c", help="Path to config file"),
+):
+    """Start the nanobot gateway."""
+    from nanobot.agent.loop import AgentLoop
+    from nanobot.bus.queue import MessageBus
+    from nanobot.channels.manager import ChannelManager
+    from nanobot.config.paths import get_cron_dir
+    from nanobot.cron.service import CronService
+    from nanobot.cron.types import CronJob
+    from nanobot.heartbeat.service import HeartbeatService
+    from nanobot.session.manager import SessionManager
+
+    if verbose:
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+
+    config = _load_runtime_config(config, workspace)
+    _print_deprecated_memory_window_notice(config)
+    port = port if port is not None else config.gateway.port
+
+    console.print(f"{__logo__} Starting nanobot gateway on port {port}...")
+    sync_workspace_templates(config.workspace_path)
+    bus = MessageBus()
+    provider = _make_provider(config)
+    session_manager = SessionManager(config.workspace_path)
+
+    # Create cron service first (callback set after agent creation)
+    cron_store_path = get_cron_dir() / "jobs.json"
+    cron = CronService(cron_store_path)
+
+    # Create agent with cron service
+    agent = AgentLoop(
+        bus=bus,
+        provider=provider,
+        workspace=config.workspace_path,
+        model=config.agents.defaults.model,
+        max_iterations=config.agents.defaults.max_tool_iterations,
+        context_window_tokens=config.agents.defaults.context_window_tokens,
+        brave_api_key=config.tools.web.search.api_key or None,
+        web_proxy=config.tools.web.proxy or None,
+        exec_config=config.tools.exec,
+        cron_service=cron,
+        restrict_to_workspace=config.tools.restrict_to_workspace,
+        session_manager=session_manager,
+        mcp_servers=config.tools.mcp_servers,
+        channels_config=config.channels,
+    )
+
+    # Set cron callback (needs agent)
+    async def on_cron_job(job: CronJob) -> str | None:
+        """Execute a cron job through the agent."""
+        from nanobot.agent.tools.cron import CronTool
+        from nanobot.agent.tools.message import MessageTool
+        reminder_note = (
+            "[Scheduled Task] Timer finished.\n\n"
+            f"Task '{job.name}' has been triggered.\n"
+            f"Scheduled instruction: {job.payload.message}"
+        )
+
+        # Prevent the agent from scheduling new cron jobs during execution
+        cron_tool = agent.tools.get("cron")
+        cron_token = None
+        if isinstance(cron_tool, CronTool):
+            cron_token = cron_tool.set_cron_context(True)
+        try:
+            response = await agent.process_direct(
+                reminder_note,
+                session_key=f"cron:{job.id}",
+                channel=job.payload.channel or "cli",
+                chat_id=job.payload.to or "direct",
+            )
+        finally:
+            if isinstance(cron_tool, CronTool) and cron_token is not None:
+                cron_tool.reset_cron_context(cron_token)
+
+        message_tool = agent.tools.get("message")
+        if isinstance(message_tool, MessageTool) and message_tool._sent_in_turn:
+            return response
+
+        if job.payload.deliver and job.payload.to and response:
+            from nanobot.bus.events import OutboundMessage
+            await bus.publish_outbound(OutboundMessage(
+                channel=job.payload.channel or "cli",
+                chat_id=job.payload.to,
+                content=response
+            ))
+        return response
+    cron.on_job = on_cron_job
+
+    # Create channel manager
+    channels = ChannelManager(config, bus)
+
+    def _pick_heartbeat_target() -> tuple[str, str]:
+        """Pick a routable channel/chat target for heartbeat-triggered messages."""
+        enabled = set(channels.enabled_channels)
+        # Prefer the most recently updated non-internal session on an enabled channel.
+        for item in session_manager.list_sessions():
+            key = item.get("key") or ""
+            if ":" not in key:
+                continue
+            channel, chat_id = key.split(":", 1)
+            if channel in {"cli", "system"}:
+                continue
+            if channel in enabled and chat_id:
+                return channel, chat_id
+        # Fallback keeps prior behavior but remains explicit.
+        return "cli", "direct"
+
+    # Create heartbeat service
+    async def on_heartbeat_execute(tasks: str) -> str:
+        """Phase 2: execute heartbeat tasks through the full agent loop."""
+        channel, chat_id = _pick_heartbeat_target()
+
+        async def _silent(*_args, **_kwargs):
+            pass
+
+        return await agent.process_direct(
+            tasks,
+            session_key="heartbeat",
+            channel=channel,
+            chat_id=chat_id,
+            on_progress=_silent,
+        )
+
+    async def on_heartbeat_notify(response: str) -> None:
+        """Deliver a heartbeat response to the user's channel."""
+        from nanobot.bus.events import OutboundMessage
+        channel, chat_id = _pick_heartbeat_target()
+        if channel == "cli":
+            return  # No external channel available to deliver to
+        await bus.publish_outbound(OutboundMessage(channel=channel, chat_id=chat_id, content=response))
+
+    hb_cfg = config.gateway.heartbeat
+    heartbeat = HeartbeatService(
+        workspace=config.workspace_path,
+        provider=provider,
+        model=agent.model,
+        on_execute=on_heartbeat_execute,
+        on_notify=on_heartbeat_notify,
+        interval_s=hb_cfg.interval_s,
+        enabled=hb_cfg.enabled,
+    )
+
+    if channels.enabled_channels:
+        console.print(f"[green]✓[/green] Channels enabled: {', '.join(channels.enabled_channels)}")
+    else:
+        console.print("[yellow]Warning: No channels enabled[/yellow]")
+
+    cron_status = cron.status()
+    if cron_status["jobs"] > 0:
+        console.print(f"[green]✓[/green] Cron: {cron_status['jobs']} scheduled jobs")
+
+    console.print(f"[green]✓[/green] Heartbeat: every {hb_cfg.interval_s}s")
+
+    # Sync tools to Go backend
+    from nanobot.utils import sync_tools_to_go
+    tool_defs = agent.tools.get_definitions()
+    if sync_tools_to_go(tool_defs):
+        console.print(f"[green]✓[/green] Tools synced to Go backend ({len(tool_defs)} tools)")
+
+    async def run():
+        try:
+            await cron.start()
+            await heartbeat.start()
+            await asyncio.gather(
+                agent.run(),
+                channels.start_all(),
+            )
+        except KeyboardInterrupt:
+            console.print("\nShutting down...")
+        finally:
+            await agent.close_mcp()
+            heartbeat.stop()
+            cron.stop()
+            agent.stop()
+            await channels.stop_all()
+
+    asyncio.run(run())
+
+
+
+
+# ============================================================================
+# Agent Commands
+# ============================================================================
+
+
+@app.command()
+def agent(
+    message: str = typer.Option(None, "--message", "-m", help="Message to send to the agent"),
+    session_id: str = typer.Option("cli:direct", "--session", "-s", help="Session ID"),
+    workspace: str | None = typer.Option(None, "--workspace", "-w", help="Workspace directory"),
+    config: str | None = typer.Option(None, "--config", "-c", help="Config file path"),
+    markdown: bool = typer.Option(True, "--markdown/--no-markdown", help="Render assistant output as Markdown"),
+    logs: bool = typer.Option(False, "--logs/--no-logs", help="Show nanobot runtime logs during chat"),
+):
+    """Interact with the agent directly."""
+    from loguru import logger
+
+    from nanobot.agent.loop import AgentLoop
+    from nanobot.bus.queue import MessageBus
+    from nanobot.config.paths import get_cron_dir
+    from nanobot.cron.service import CronService
+
+    config = _load_runtime_config(config, workspace)
+    _print_deprecated_memory_window_notice(config)
+    sync_workspace_templates(config.workspace_path)
+
+    bus = MessageBus()
+    provider = _make_provider(config)
+
+    # Create cron service for tool usage (no callback needed for CLI unless running)
+    cron_store_path = get_cron_dir() / "jobs.json"
+    cron = CronService(cron_store_path)
+
+    if logs:
+        logger.enable("nanobot")
+    else:
+        logger.disable("nanobot")
+
+    agent_loop = AgentLoop(
+        bus=bus,
+        provider=provider,
+        workspace=config.workspace_path,
+        model=config.agents.defaults.model,
+        max_iterations=config.agents.defaults.max_tool_iterations,
+        context_window_tokens=config.agents.defaults.context_window_tokens,
+        brave_api_key=config.tools.web.search.api_key or None,
+        web_proxy=config.tools.web.proxy or None,
+        exec_config=config.tools.exec,
+        cron_service=cron,
+        restrict_to_workspace=config.tools.restrict_to_workspace,
+        mcp_servers=config.tools.mcp_servers,
+        channels_config=config.channels,
+    )
+
+    # Sync tools to Go backend
+    from nanobot.utils import sync_tools_to_go
+    tool_defs = agent_loop.tools.get_definitions()
+    if sync_tools_to_go(tool_defs):
+        console.print(f"[green]✓[/green] Tools synced to Go backend ({len(tool_defs)} tools)")
+
+    # Show spinner when logs are off (no output to miss); skip when logs are on
+    def _thinking_ctx():
+        if logs:
+            from contextlib import nullcontext
+            return nullcontext()
+        # Animated spinner is safe to use with prompt_toolkit input handling
+        return console.status("[dim]nanobot is thinking...[/dim]", spinner="dots")
+
+    async def _cli_progress(content: str, *, tool_hint: bool = False) -> None:
+        ch = agent_loop.channels_config
+        if ch and tool_hint and not ch.send_tool_hints:
+            return
+        if ch and not tool_hint and not ch.send_progress:
+            return
+        console.print(f"  [dim]↳ {content}[/dim]")
+
+    if message:
+        # Single message mode — direct call, no bus needed
+        async def run_once():
+            with _thinking_ctx():
+                response = await agent_loop.process_direct(message, session_id, on_progress=_cli_progress)
+            _print_agent_response(response, render_markdown=markdown)
+            await agent_loop.close_mcp()
+
+        asyncio.run(run_once())
+    else:
+        # Interactive mode — route through bus like other channels
+        from nanobot.bus.events import InboundMessage
+        _init_prompt_session()
+        console.print(f"{__logo__} Interactive mode (type [bold]exit[/bold] or [bold]Ctrl+C[/bold] to quit)\n")
+
+        if ":" in session_id:
+            cli_channel, cli_chat_id = session_id.split(":", 1)
+        else:
+            cli_channel, cli_chat_id = "cli", session_id
+
+        def _handle_signal(signum, frame):
+            sig_name = signal.Signals(signum).name
+            _restore_terminal()
+            console.print(f"\nReceived {sig_name}, goodbye!")
+            sys.exit(0)
+
+        signal.signal(signal.SIGINT, _handle_signal)
+        signal.signal(signal.SIGTERM, _handle_signal)
+        # SIGHUP is not available on Windows
+        if hasattr(signal, 'SIGHUP'):
+            signal.signal(signal.SIGHUP, _handle_signal)
+        # Ignore SIGPIPE to prevent silent process termination when writing to closed pipes
+        # SIGPIPE is not available on Windows
+        if hasattr(signal, 'SIGPIPE'):
+            signal.signal(signal.SIGPIPE, signal.SIG_IGN)
+
+        async def run_interactive():
+            bus_task = asyncio.create_task(agent_loop.run())
+            turn_done = asyncio.Event()
+            turn_done.set()
+            turn_response: list[str] = []
+
+            async def _consume_outbound():
+                while True:
+                    try:
+                        msg = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+                        if msg.metadata.get("_progress"):
+                            is_tool_hint = msg.metadata.get("_tool_hint", False)
+                            ch = agent_loop.channels_config
+                            if ch and is_tool_hint and not ch.send_tool_hints:
+                                pass
+                            elif ch and not is_tool_hint and not ch.send_progress:
+                                pass
+                            else:
+                                console.print(f"  [dim]↳ {msg.content}[/dim]")
+                        elif not turn_done.is_set():
+                            if msg.content:
+                                turn_response.append(msg.content)
+                            turn_done.set()
+                        elif msg.content:
+                            console.print()
+                            _print_agent_response(msg.content, render_markdown=markdown)
+                    except asyncio.TimeoutError:
+                        continue
+                    except asyncio.CancelledError:
+                        break
+
+            outbound_task = asyncio.create_task(_consume_outbound())
+
+            try:
+                while True:
+                    try:
+                        _flush_pending_tty_input()
+                        user_input = await _read_interactive_input_async()
+                        command = user_input.strip()
+                        if not command:
+                            continue
+
+                        if _is_exit_command(command):
+                            _restore_terminal()
+                            console.print("\nGoodbye!")
+                            break
+
+                        turn_done.clear()
+                        turn_response.clear()
+
+                        await bus.publish_inbound(InboundMessage(
+                            channel=cli_channel,
+                            sender_id="user",
+                            chat_id=cli_chat_id,
+                            content=user_input,
+                        ))
+
+                        with _thinking_ctx():
+                            await turn_done.wait()
+
+                        if turn_response:
+                            _print_agent_response(turn_response[0], render_markdown=markdown)
+                    except KeyboardInterrupt:
+                        _restore_terminal()
+                        console.print("\nGoodbye!")
+                        break
+                    except EOFError:
+                        _restore_terminal()
+                        console.print("\nGoodbye!")
+                        break
+            finally:
+                agent_loop.stop()
+                outbound_task.cancel()
+                await asyncio.gather(bus_task, outbound_task, return_exceptions=True)
+                await agent_loop.close_mcp()
+
+        asyncio.run(run_interactive())
+
+
+# ============================================================================
+# Channel Commands
+# ============================================================================
+
+
+channels_app = typer.Typer(help="Manage channels")
+app.add_typer(channels_app, name="channels")
+
+
+@channels_app.command("status")
+def channels_status():
+    """Show channel status."""
+    from nanobot.channels.registry import discover_channel_names, load_channel_class
+    from nanobot.config.loader import load_config
+
+    config = load_config()
+
+    table = Table(title="Channel Status")
+    table.add_column("Channel", style="cyan")
+    table.add_column("Enabled", style="green")
+
+    for modname in sorted(discover_channel_names()):
+        section = getattr(config.channels, modname, None)
+        enabled = section and getattr(section, "enabled", False)
+        try:
+            cls = load_channel_class(modname)
+            display = cls.display_name
+        except ImportError:
+            display = modname.title()
+        table.add_row(
+            display,
+            "[green]\u2713[/green]" if enabled else "[dim]\u2717[/dim]",
+        )
+
+    console.print(table)
+
+
+def _get_bridge_dir() -> Path:
+    """Get the bridge directory, setting it up if needed."""
+    import shutil
+    import subprocess
+
+    # User's bridge location
+    from nanobot.config.paths import get_bridge_install_dir
+
+    user_bridge = get_bridge_install_dir()
+
+    # Check if already built
+    if (user_bridge / "dist" / "index.js").exists():
+        return user_bridge
+
+    # Check for npm
+    if not shutil.which("npm"):
+        console.print("[red]npm not found. Please install Node.js >= 18.[/red]")
+        raise typer.Exit(1)
+
+    # Find source bridge: first check package data, then source dir
+    pkg_bridge = Path(__file__).parent.parent / "bridge"  # nanobot/bridge (installed)
+    src_bridge = Path(__file__).parent.parent.parent / "bridge"  # repo root/bridge (dev)
+
+    source = None
+    if (pkg_bridge / "package.json").exists():
+        source = pkg_bridge
+    elif (src_bridge / "package.json").exists():
+        source = src_bridge
+
+    if not source:
+        console.print("[red]Bridge source not found.[/red]")
+        console.print("Try reinstalling: pip install --force-reinstall nanobot")
+        raise typer.Exit(1)
+
+    console.print(f"{__logo__} Setting up bridge...")
+
+    # Copy to user directory
+    user_bridge.parent.mkdir(parents=True, exist_ok=True)
+    if user_bridge.exists():
+        shutil.rmtree(user_bridge)
+    shutil.copytree(source, user_bridge, ignore=shutil.ignore_patterns("node_modules", "dist"))
+
+    # Install and build
+    try:
+        console.print("  Installing dependencies...")
+        subprocess.run(["npm", "install"], cwd=user_bridge, check=True, capture_output=True)
+
+        console.print("  Building...")
+        subprocess.run(["npm", "run", "build"], cwd=user_bridge, check=True, capture_output=True)
+
+        console.print("[green]✓[/green] Bridge ready\n")
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]Build failed: {e}[/red]")
+        if e.stderr:
+            console.print(f"[dim]{e.stderr.decode()[:500]}[/dim]")
+        raise typer.Exit(1)
+
+    return user_bridge
+
+
+@channels_app.command("login")
+def channels_login():
+    """Link device via QR code."""
+    import subprocess
+
+    from nanobot.config.loader import load_config
+    from nanobot.config.paths import get_runtime_subdir
+
+    config = load_config()
+    bridge_dir = _get_bridge_dir()
+
+    console.print(f"{__logo__} Starting bridge...")
+    console.print("Scan the QR code to connect.\n")
+
+    env = {**os.environ}
+    if config.channels.whatsapp.bridge_token:
+        env["BRIDGE_TOKEN"] = config.channels.whatsapp.bridge_token
+    env["AUTH_DIR"] = str(get_runtime_subdir("whatsapp-auth"))
+
+    try:
+        subprocess.run(["npm", "start"], cwd=bridge_dir, check=True, env=env)
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]Bridge failed: {e}[/red]")
+    except FileNotFoundError:
+        console.print("[red]npm not found. Please install Node.js.[/red]")
+
+
+# ============================================================================
+# Status Commands
+# ============================================================================
+
+
+@app.command()
+def status():
+    """Show nanobot status."""
+    from nanobot.config.loader import get_config_path, load_config
+
+    config_path = get_config_path()
+    config = load_config()
+    workspace = config.workspace_path
+
+    console.print(f"{__logo__} nanobot Status\n")
+
+    console.print(f"Config: {config_path} {'[green]✓[/green]' if config_path.exists() else '[red]✗[/red]'}")
+    console.print(f"Workspace: {workspace} {'[green]✓[/green]' if workspace.exists() else '[red]✗[/red]'}")
+
+    if config_path.exists():
+        from nanobot.providers.registry import PROVIDERS
+
+        console.print(f"Model: {config.agents.defaults.model}")
+
+        # Check API keys from registry
+        for spec in PROVIDERS:
+            p = getattr(config.providers, spec.name, None)
+            if p is None:
+                continue
+            if spec.is_oauth:
+                console.print(f"{spec.label}: [green]✓ (OAuth)[/green]")
+            elif spec.is_local:
+                # Local deployments show api_base instead of api_key
+                if p.api_base:
+                    console.print(f"{spec.label}: [green]✓ {p.api_base}[/green]")
+                else:
+                    console.print(f"{spec.label}: [dim]not set[/dim]")
+            else:
+                has_key = bool(p.api_key)
+                console.print(f"{spec.label}: {'[green]✓[/green]' if has_key else '[dim]not set[/dim]'}")
+
+
+# ============================================================================
+# OAuth Login
+# ============================================================================
+
+provider_app = typer.Typer(help="Manage providers")
+app.add_typer(provider_app, name="provider")
+
+
+_LOGIN_HANDLERS: dict[str, callable] = {}
+
+
+def _register_login(name: str):
+    def decorator(fn):
+        _LOGIN_HANDLERS[name] = fn
+        return fn
+    return decorator
+
+
+@provider_app.command("login")
+def provider_login(
+    provider: str = typer.Argument(..., help="OAuth provider (e.g. 'openai-codex', 'github-copilot')"),
+):
+    """Authenticate with an OAuth provider."""
+    from nanobot.providers.registry import PROVIDERS
+
+    key = provider.replace("-", "_")
+    spec = next((s for s in PROVIDERS if s.name == key and s.is_oauth), None)
+    if not spec:
+        names = ", ".join(s.name.replace("_", "-") for s in PROVIDERS if s.is_oauth)
+        console.print(f"[red]Unknown OAuth provider: {provider}[/red]  Supported: {names}")
+        raise typer.Exit(1)
+
+    handler = _LOGIN_HANDLERS.get(spec.name)
+    if not handler:
+        console.print(f"[red]Login not implemented for {spec.label}[/red]")
+        raise typer.Exit(1)
+
+    console.print(f"{__logo__} OAuth Login - {spec.label}\n")
+    handler()
+
+
+@_register_login("openai_codex")
+def _login_openai_codex() -> None:
+    try:
+        from oauth_cli_kit import get_token, login_oauth_interactive
+        token = None
+        try:
+            token = get_token()
+        except Exception:
+            pass
+        if not (token and token.access):
+            console.print("[cyan]Starting interactive OAuth login...[/cyan]\n")
+            token = login_oauth_interactive(
+                print_fn=lambda s: console.print(s),
+                prompt_fn=lambda s: typer.prompt(s),
+            )
+        if not (token and token.access):
+            console.print("[red]✗ Authentication failed[/red]")
+            raise typer.Exit(1)
+        console.print(f"[green]✓ Authenticated with OpenAI Codex[/green]  [dim]{token.account_id}[/dim]")
+    except ImportError:
+        console.print("[red]oauth_cli_kit not installed. Run: pip install oauth-cli-kit[/red]")
+        raise typer.Exit(1)
+
+
+@_register_login("github_copilot")
+def _login_github_copilot() -> None:
+    import asyncio
+
+    console.print("[cyan]Starting GitHub Copilot device flow...[/cyan]\n")
+
+    async def _trigger():
+        from litellm import acompletion
+        await acompletion(model="github_copilot/gpt-4o", messages=[{"role": "user", "content": "hi"}], max_tokens=1)
+
+    try:
+        asyncio.run(_trigger())
+        console.print("[green]✓ Authenticated with GitHub Copilot[/green]")
+    except Exception as e:
+        console.print(f"[red]Authentication error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()
diff --git a/core/nanobot/nanobot/config/__init__.py b/core/nanobot/nanobot/config/__init__.py
new file mode 100644
index 0000000..e2c24f8
--- /dev/null
+++ b/core/nanobot/nanobot/config/__init__.py
@@ -0,0 +1,30 @@
+"""Configuration module for nanobot."""
+
+from nanobot.config.loader import get_config_path, load_config
+from nanobot.config.paths import (
+    get_bridge_install_dir,
+    get_cli_history_path,
+    get_cron_dir,
+    get_data_dir,
+    get_legacy_sessions_dir,
+    get_logs_dir,
+    get_media_dir,
+    get_runtime_subdir,
+    get_workspace_path,
+)
+from nanobot.config.schema import Config
+
+__all__ = [
+    "Config",
+    "load_config",
+    "get_config_path",
+    "get_data_dir",
+    "get_runtime_subdir",
+    "get_media_dir",
+    "get_cron_dir",
+    "get_logs_dir",
+    "get_workspace_path",
+    "get_cli_history_path",
+    "get_bridge_install_dir",
+    "get_legacy_sessions_dir",
+]
diff --git a/core/nanobot/nanobot/config/loader.py b/core/nanobot/nanobot/config/loader.py
new file mode 100644
index 0000000..7d309e5
--- /dev/null
+++ b/core/nanobot/nanobot/config/loader.py
@@ -0,0 +1,75 @@
+"""Configuration loading utilities."""
+
+import json
+from pathlib import Path
+
+from nanobot.config.schema import Config
+
+
+# Global variable to store current config path (for multi-instance support)
+_current_config_path: Path | None = None
+
+
+def set_config_path(path: Path) -> None:
+    """Set the current config path (used to derive data directory)."""
+    global _current_config_path
+    _current_config_path = path
+
+
+def get_config_path() -> Path:
+    """Get the configuration file path."""
+    if _current_config_path:
+        return _current_config_path
+    return Path.home() / ".nanobot" / "config.json"
+
+
+def load_config(config_path: Path | None = None) -> Config:
+    """
+    Load configuration from file or create default.
+
+    Args:
+        config_path: Optional path to config file. Uses default if not provided.
+
+    Returns:
+        Loaded configuration object.
+    """
+    path = config_path or get_config_path()
+
+    if path.exists():
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            data = _migrate_config(data)
+            return Config.model_validate(data)
+        except (json.JSONDecodeError, ValueError) as e:
+            print(f"Warning: Failed to load config from {path}: {e}")
+            print("Using default configuration.")
+
+    return Config()
+
+
+def save_config(config: Config, config_path: Path | None = None) -> None:
+    """
+    Save configuration to file.
+
+    Args:
+        config: Configuration to save.
+        config_path: Optional path to save to. Uses default if not provided.
+    """
+    path = config_path or get_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    data = config.model_dump(by_alias=True)
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+
+
+def _migrate_config(data: dict) -> dict:
+    """Migrate old config formats to current."""
+    # Move tools.exec.restrictToWorkspace → tools.restrictToWorkspace
+    tools = data.get("tools", {})
+    exec_cfg = tools.get("exec", {})
+    if "restrictToWorkspace" in exec_cfg and "restrictToWorkspace" not in tools:
+        tools["restrictToWorkspace"] = exec_cfg.pop("restrictToWorkspace")
+    return data
diff --git a/core/nanobot/nanobot/config/paths.py b/core/nanobot/nanobot/config/paths.py
new file mode 100644
index 0000000..f4dfbd9
--- /dev/null
+++ b/core/nanobot/nanobot/config/paths.py
@@ -0,0 +1,55 @@
+"""Runtime path helpers derived from the active config context."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from nanobot.config.loader import get_config_path
+from nanobot.utils.helpers import ensure_dir
+
+
+def get_data_dir() -> Path:
+    """Return the instance-level runtime data directory."""
+    return ensure_dir(get_config_path().parent)
+
+
+def get_runtime_subdir(name: str) -> Path:
+    """Return a named runtime subdirectory under the instance data dir."""
+    return ensure_dir(get_data_dir() / name)
+
+
+def get_media_dir(channel: str | None = None) -> Path:
+    """Return the media directory, optionally namespaced per channel."""
+    base = get_runtime_subdir("media")
+    return ensure_dir(base / channel) if channel else base
+
+
+def get_cron_dir() -> Path:
+    """Return the cron storage directory."""
+    return get_runtime_subdir("cron")
+
+
+def get_logs_dir() -> Path:
+    """Return the logs directory."""
+    return get_runtime_subdir("logs")
+
+
+def get_workspace_path(workspace: str | None = None) -> Path:
+    """Resolve and ensure the agent workspace path."""
+    path = Path(workspace).expanduser() if workspace else Path.home() / ".nanobot" / "workspace"
+    return ensure_dir(path)
+
+
+def get_cli_history_path() -> Path:
+    """Return the shared CLI history file path."""
+    return Path.home() / ".nanobot" / "history" / "cli_history"
+
+
+def get_bridge_install_dir() -> Path:
+    """Return the shared WhatsApp bridge installation directory."""
+    return Path.home() / ".nanobot" / "bridge"
+
+
+def get_legacy_sessions_dir() -> Path:
+    """Return the legacy global session directory used for migration fallback."""
+    return Path.home() / ".nanobot" / "sessions"
diff --git a/core/nanobot/nanobot/config/schema.py b/core/nanobot/nanobot/config/schema.py
new file mode 100644
index 0000000..1b26dd7
--- /dev/null
+++ b/core/nanobot/nanobot/config/schema.py
@@ -0,0 +1,448 @@
+"""Configuration schema using Pydantic."""
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+from pydantic_settings import BaseSettings
+
+
+class Base(BaseModel):
+    """Base model that accepts both camelCase and snake_case keys."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+
+class WhatsAppConfig(Base):
+    """WhatsApp channel configuration."""
+
+    enabled: bool = False
+    bridge_url: str = "ws://localhost:3001"
+    bridge_token: str = ""  # Shared token for bridge auth (optional, recommended)
+    allow_from: list[str] = Field(default_factory=list)  # Allowed phone numbers
+
+
+class TelegramConfig(Base):
+    """Telegram channel configuration."""
+
+    enabled: bool = False
+    token: str = ""  # Bot token from @BotFather
+    allow_from: list[str] = Field(default_factory=list)  # Allowed user IDs or usernames
+    proxy: str | None = (
+        None  # HTTP/SOCKS5 proxy URL, e.g. "http://127.0.0.1:7890" or "socks5://127.0.0.1:1080"
+    )
+    reply_to_message: bool = False  # If true, bot replies quote the original message
+    group_policy: Literal["open", "mention"] = "mention"  # "mention" responds when @mentioned or replied to, "open" responds to all
+
+
+class FeishuConfig(Base):
+    """Feishu/Lark channel configuration using WebSocket long connection."""
+
+    enabled: bool = False
+    app_id: str = ""  # App ID from Feishu Open Platform
+    app_secret: str = ""  # App Secret from Feishu Open Platform
+    encrypt_key: str = ""  # Encrypt Key for event subscription (optional)
+    verification_token: str = ""  # Verification Token for event subscription (optional)
+    allow_from: list[str] = Field(default_factory=list)  # Allowed user open_ids
+    react_emoji: str = (
+        "THUMBSUP"  # Emoji type for message reactions (e.g. THUMBSUP, OK, DONE, SMILE)
+    )
+
+
+class DingTalkConfig(Base):
+    """DingTalk channel configuration using Stream mode."""
+
+    enabled: bool = False
+    client_id: str = ""  # AppKey
+    client_secret: str = ""  # AppSecret
+    allow_from: list[str] = Field(default_factory=list)  # Allowed staff_ids
+
+
+class DiscordConfig(Base):
+    """Discord channel configuration."""
+
+    enabled: bool = False
+    token: str = ""  # Bot token from Discord Developer Portal
+    allow_from: list[str] = Field(default_factory=list)  # Allowed user IDs
+    gateway_url: str = "wss://gateway.discord.gg/?v=10&encoding=json"
+    intents: int = 37377  # GUILDS + GUILD_MESSAGES + DIRECT_MESSAGES + MESSAGE_CONTENT
+    group_policy: Literal["mention", "open"] = "mention"
+
+
+class MatrixConfig(Base):
+    """Matrix (Element) channel configuration."""
+
+    enabled: bool = False
+    homeserver: str = "https://matrix.org"
+    access_token: str = ""
+    user_id: str = ""  # @bot:matrix.org
+    device_id: str = ""
+    e2ee_enabled: bool = True  # Enable Matrix E2EE support (encryption + encrypted room handling).
+    sync_stop_grace_seconds: int = (
+        2  # Max seconds to wait for sync_forever to stop gracefully before cancellation fallback.
+    )
+    max_media_bytes: int = (
+        20 * 1024 * 1024
+    )  # Max attachment size accepted for Matrix media handling (inbound + outbound).
+    allow_from: list[str] = Field(default_factory=list)
+    group_policy: Literal["open", "mention", "allowlist"] = "open"
+    group_allow_from: list[str] = Field(default_factory=list)
+    allow_room_mentions: bool = False
+
+
+class EmailConfig(Base):
+    """Email channel configuration (IMAP inbound + SMTP outbound)."""
+
+    enabled: bool = False
+    consent_granted: bool = False  # Explicit owner permission to access mailbox data
+
+    # IMAP (receive)
+    imap_host: str = ""
+    imap_port: int = 993
+    imap_username: str = ""
+    imap_password: str = ""
+    imap_mailbox: str = "INBOX"
+    imap_use_ssl: bool = True
+
+    # SMTP (send)
+    smtp_host: str = ""
+    smtp_port: int = 587
+    smtp_username: str = ""
+    smtp_password: str = ""
+    smtp_use_tls: bool = True
+    smtp_use_ssl: bool = False
+    from_address: str = ""
+
+    # Behavior
+    auto_reply_enabled: bool = (
+        True  # If false, inbound email is read but no automatic reply is sent
+    )
+    poll_interval_seconds: int = 30
+    mark_seen: bool = True
+    max_body_chars: int = 12000
+    subject_prefix: str = "Re: "
+    allow_from: list[str] = Field(default_factory=list)  # Allowed sender email addresses
+
+
+class MochatMentionConfig(Base):
+    """Mochat mention behavior configuration."""
+
+    require_in_groups: bool = False
+
+
+class MochatGroupRule(Base):
+    """Mochat per-group mention requirement."""
+
+    require_mention: bool = False
+
+
+class MochatConfig(Base):
+    """Mochat channel configuration."""
+
+    enabled: bool = False
+    base_url: str = "https://mochat.io"
+    socket_url: str = ""
+    socket_path: str = "/socket.io"
+    socket_disable_msgpack: bool = False
+    socket_reconnect_delay_ms: int = 1000
+    socket_max_reconnect_delay_ms: int = 10000
+    socket_connect_timeout_ms: int = 10000
+    refresh_interval_ms: int = 30000
+    watch_timeout_ms: int = 25000
+    watch_limit: int = 100
+    retry_delay_ms: int = 500
+    max_retry_attempts: int = 0  # 0 means unlimited retries
+    claw_token: str = ""
+    agent_user_id: str = ""
+    sessions: list[str] = Field(default_factory=list)
+    panels: list[str] = Field(default_factory=list)
+    allow_from: list[str] = Field(default_factory=list)
+    mention: MochatMentionConfig = Field(default_factory=MochatMentionConfig)
+    groups: dict[str, MochatGroupRule] = Field(default_factory=dict)
+    reply_delay_mode: str = "non-mention"  # off | non-mention
+    reply_delay_ms: int = 120000
+
+
+class SlackDMConfig(Base):
+    """Slack DM policy configuration."""
+
+    enabled: bool = True
+    policy: str = "open"  # "open" or "allowlist"
+    allow_from: list[str] = Field(default_factory=list)  # Allowed Slack user IDs
+
+
+class SlackConfig(Base):
+    """Slack channel configuration."""
+
+    enabled: bool = False
+    mode: str = "socket"  # "socket" supported
+    webhook_path: str = "/slack/events"
+    bot_token: str = ""  # xoxb-...
+    app_token: str = ""  # xapp-...
+    user_token_read_only: bool = True
+    reply_in_thread: bool = True
+    react_emoji: str = "eyes"
+    allow_from: list[str] = Field(default_factory=list)  # Allowed Slack user IDs (sender-level)
+    group_policy: str = "mention"  # "mention", "open", "allowlist"
+    group_allow_from: list[str] = Field(default_factory=list)  # Allowed channel IDs if allowlist
+    dm: SlackDMConfig = Field(default_factory=SlackDMConfig)
+
+
+class QQConfig(Base):
+    """QQ channel configuration using botpy SDK."""
+
+    enabled: bool = False
+    app_id: str = ""  # 机器人 ID (AppID) from q.qq.com
+    secret: str = ""  # 机器人密钥 (AppSecret) from q.qq.com
+    allow_from: list[str] = Field(
+        default_factory=list
+    )  # Allowed user openids (empty = public access)
+
+
+class WecomConfig(Base):
+    """WeCom (Enterprise WeChat) AI Bot channel configuration."""
+
+    enabled: bool = False
+    bot_id: str = ""  # Bot ID from WeCom AI Bot platform
+    secret: str = ""  # Bot Secret from WeCom AI Bot platform
+    allow_from: list[str] = Field(default_factory=list)  # Allowed user IDs
+    welcome_message: str = ""  # Welcome message for enter_chat event
+
+
+class ChannelsConfig(Base):
+    """Configuration for chat channels."""
+
+    send_progress: bool = True  # stream agent's text progress to the channel
+    send_tool_hints: bool = False  # stream tool-call hints (e.g. read_file("…"))
+    whatsapp: WhatsAppConfig = Field(default_factory=WhatsAppConfig)
+    telegram: TelegramConfig = Field(default_factory=TelegramConfig)
+    discord: DiscordConfig = Field(default_factory=DiscordConfig)
+    feishu: FeishuConfig = Field(default_factory=FeishuConfig)
+    mochat: MochatConfig = Field(default_factory=MochatConfig)
+    dingtalk: DingTalkConfig = Field(default_factory=DingTalkConfig)
+    email: EmailConfig = Field(default_factory=EmailConfig)
+    slack: SlackConfig = Field(default_factory=SlackConfig)
+    qq: QQConfig = Field(default_factory=QQConfig)
+    matrix: MatrixConfig = Field(default_factory=MatrixConfig)
+    wecom: WecomConfig = Field(default_factory=WecomConfig)
+
+
+class AgentDefaults(Base):
+    """Default agent configuration."""
+
+    workspace: str = "~/.nanobot/workspace"
+    model: str = "anthropic/claude-opus-4-5"
+    provider: str = (
+        "auto"  # Provider name (e.g. "anthropic", "openrouter") or "auto" for auto-detection
+    )
+    max_tokens: int = 8192
+    context_window_tokens: int = 65_536
+    temperature: float = 0.1
+    max_tool_iterations: int = 40
+    # Deprecated compatibility field: accepted from old configs but ignored at runtime.
+    memory_window: int | None = Field(default=None, exclude=True)
+    reasoning_effort: str | None = None  # low / medium / high — enables LLM thinking mode
+
+    @property
+    def should_warn_deprecated_memory_window(self) -> bool:
+        """Return True when old memoryWindow is present without contextWindowTokens."""
+        return self.memory_window is not None and "context_window_tokens" not in self.model_fields_set
+
+
+class AgentsConfig(Base):
+    """Agent configuration."""
+
+    defaults: AgentDefaults = Field(default_factory=AgentDefaults)
+
+
+class ProviderConfig(Base):
+    """LLM provider configuration."""
+
+    api_key: str = ""
+    api_base: str | None = None
+    extra_headers: dict[str, str] | None = None  # Custom headers (e.g. APP-Code for AiHubMix)
+
+
+class ProvidersConfig(Base):
+    """Configuration for LLM providers."""
+
+    custom: ProviderConfig = Field(default_factory=ProviderConfig)  # Any OpenAI-compatible endpoint
+    azure_openai: ProviderConfig = Field(default_factory=ProviderConfig)  # Azure OpenAI (model = deployment name)
+    anthropic: ProviderConfig = Field(default_factory=ProviderConfig)
+    openai: ProviderConfig = Field(default_factory=ProviderConfig)
+    openrouter: ProviderConfig = Field(default_factory=ProviderConfig)
+    deepseek: ProviderConfig = Field(default_factory=ProviderConfig)
+    groq: ProviderConfig = Field(default_factory=ProviderConfig)
+    zhipu: ProviderConfig = Field(default_factory=ProviderConfig)
+    dashscope: ProviderConfig = Field(default_factory=ProviderConfig)  # 阿里云通义千问
+    vllm: ProviderConfig = Field(default_factory=ProviderConfig)
+    gemini: ProviderConfig = Field(default_factory=ProviderConfig)
+    moonshot: ProviderConfig = Field(default_factory=ProviderConfig)
+    minimax: ProviderConfig = Field(default_factory=ProviderConfig)
+    aihubmix: ProviderConfig = Field(default_factory=ProviderConfig)  # AiHubMix API gateway
+    ollama: ProviderConfig = Field(default_factory=ProviderConfig)  # Ollama local models
+    siliconflow: ProviderConfig = Field(default_factory=ProviderConfig)  # SiliconFlow (硅基流动)
+    volcengine: ProviderConfig = Field(default_factory=ProviderConfig)  # VolcEngine (火山引擎)
+    openai_codex: ProviderConfig = Field(default_factory=ProviderConfig)  # OpenAI Codex (OAuth)
+    github_copilot: ProviderConfig = Field(default_factory=ProviderConfig)  # Github Copilot (OAuth)
+
+
+class HeartbeatConfig(Base):
+    """Heartbeat service configuration."""
+
+    enabled: bool = True
+    interval_s: int = 30 * 60  # 30 minutes
+
+
+class GatewayConfig(Base):
+    """Gateway/server configuration."""
+
+    host: str = "0.0.0.0"
+    port: int = 18790
+    heartbeat: HeartbeatConfig = Field(default_factory=HeartbeatConfig)
+
+
+class WebSearchConfig(Base):
+    """Web search tool configuration."""
+
+    api_key: str = ""  # Brave Search API key
+    max_results: int = 5
+
+
+class WebToolsConfig(Base):
+    """Web tools configuration."""
+
+    proxy: str | None = (
+        None  # HTTP/SOCKS5 proxy URL, e.g. "http://127.0.0.1:7890" or "socks5://127.0.0.1:1080"
+    )
+    search: WebSearchConfig = Field(default_factory=WebSearchConfig)
+
+
+class ExecToolConfig(Base):
+    """Shell exec tool configuration."""
+
+    timeout: int = 60
+    path_append: str = ""
+
+
+class MCPServerConfig(Base):
+    """MCP server connection configuration (stdio or HTTP)."""
+
+    type: Literal["stdio", "sse", "streamableHttp"] | None = None  # auto-detected if omitted
+    command: str = ""  # Stdio: command to run (e.g. "npx")
+    args: list[str] = Field(default_factory=list)  # Stdio: command arguments
+    env: dict[str, str] = Field(default_factory=dict)  # Stdio: extra env vars
+    url: str = ""  # HTTP/SSE: endpoint URL
+    headers: dict[str, str] = Field(default_factory=dict)  # HTTP/SSE: custom headers
+    tool_timeout: int = 30  # seconds before a tool call is cancelled
+
+
+class ToolsConfig(Base):
+    """Tools configuration."""
+
+    web: WebToolsConfig = Field(default_factory=WebToolsConfig)
+    exec: ExecToolConfig = Field(default_factory=ExecToolConfig)
+    restrict_to_workspace: bool = False  # If true, restrict all tool access to workspace directory
+    mcp_servers: dict[str, MCPServerConfig] = Field(default_factory=dict)
+
+
+class Config(BaseSettings):
+    """Root configuration for nanobot."""
+
+    agents: AgentsConfig = Field(default_factory=AgentsConfig)
+    channels: ChannelsConfig = Field(default_factory=ChannelsConfig)
+    providers: ProvidersConfig = Field(default_factory=ProvidersConfig)
+    gateway: GatewayConfig = Field(default_factory=GatewayConfig)
+    tools: ToolsConfig = Field(default_factory=ToolsConfig)
+
+    @property
+    def workspace_path(self) -> Path:
+        """Get expanded workspace path."""
+        return Path(self.agents.defaults.workspace).expanduser()
+
+    def _match_provider(
+        self, model: str | None = None
+    ) -> tuple["ProviderConfig | None", str | None]:
+        """Match provider config and its registry name. Returns (config, spec_name)."""
+        from nanobot.providers.registry import PROVIDERS
+
+        forced = self.agents.defaults.provider
+        if forced != "auto":
+            p = getattr(self.providers, forced, None)
+            return (p, forced) if p else (None, None)
+
+        model_lower = (model or self.agents.defaults.model).lower()
+        model_normalized = model_lower.replace("-", "_")
+        model_prefix = model_lower.split("/", 1)[0] if "/" in model_lower else ""
+        normalized_prefix = model_prefix.replace("-", "_")
+
+        def _kw_matches(kw: str) -> bool:
+            kw = kw.lower()
+            return kw in model_lower or kw.replace("-", "_") in model_normalized
+
+        # Explicit provider prefix wins — prevents `github-copilot/...codex` matching openai_codex.
+        for spec in PROVIDERS:
+            p = getattr(self.providers, spec.name, None)
+            if p and model_prefix and normalized_prefix == spec.name:
+                if spec.is_oauth or spec.is_local or p.api_key:
+                    return p, spec.name
+
+        # Match by keyword (order follows PROVIDERS registry)
+        for spec in PROVIDERS:
+            p = getattr(self.providers, spec.name, None)
+            if p and any(_kw_matches(kw) for kw in spec.keywords):
+                if spec.is_oauth or spec.is_local or p.api_key:
+                    return p, spec.name
+
+        # Fallback: configured local providers can route models without
+        # provider-specific keywords (for example plain "llama3.2" on Ollama).
+        for spec in PROVIDERS:
+            if not spec.is_local:
+                continue
+            p = getattr(self.providers, spec.name, None)
+            if p and p.api_base:
+                return p, spec.name
+
+        # Fallback: gateways first, then others (follows registry order)
+        # OAuth providers are NOT valid fallbacks — they require explicit model selection
+        for spec in PROVIDERS:
+            if spec.is_oauth:
+                continue
+            p = getattr(self.providers, spec.name, None)
+            if p and p.api_key:
+                return p, spec.name
+        return None, None
+
+    def get_provider(self, model: str | None = None) -> ProviderConfig | None:
+        """Get matched provider config (api_key, api_base, extra_headers). Falls back to first available."""
+        p, _ = self._match_provider(model)
+        return p
+
+    def get_provider_name(self, model: str | None = None) -> str | None:
+        """Get the registry name of the matched provider (e.g. "deepseek", "openrouter")."""
+        _, name = self._match_provider(model)
+        return name
+
+    def get_api_key(self, model: str | None = None) -> str | None:
+        """Get API key for the given model. Falls back to first available key."""
+        p = self.get_provider(model)
+        return p.api_key if p else None
+
+    def get_api_base(self, model: str | None = None) -> str | None:
+        """Get API base URL for the given model. Applies default URLs for gateway/local providers."""
+        from nanobot.providers.registry import find_by_name
+
+        p, name = self._match_provider(model)
+        if p and p.api_base:
+            return p.api_base
+        # Only gateways get a default api_base here. Standard providers
+        # (like Moonshot) set their base URL via env vars in _setup_env
+        # to avoid polluting the global litellm.api_base.
+        if name:
+            spec = find_by_name(name)
+            if spec and (spec.is_gateway or spec.is_local) and spec.default_api_base:
+                return spec.default_api_base
+        return None
+
+    model_config = ConfigDict(env_prefix="NANOBOT_", env_nested_delimiter="__")
diff --git a/core/nanobot/nanobot/cron/__init__.py b/core/nanobot/nanobot/cron/__init__.py
new file mode 100644
index 0000000..a9d4cad
--- /dev/null
+++ b/core/nanobot/nanobot/cron/__init__.py
@@ -0,0 +1,6 @@
+"""Cron service for scheduled agent tasks."""
+
+from nanobot.cron.service import CronService
+from nanobot.cron.types import CronJob, CronSchedule
+
+__all__ = ["CronService", "CronJob", "CronSchedule"]
diff --git a/core/nanobot/nanobot/cron/service.py b/core/nanobot/nanobot/cron/service.py
new file mode 100644
index 0000000..1ed71f0
--- /dev/null
+++ b/core/nanobot/nanobot/cron/service.py
@@ -0,0 +1,376 @@
+"""Cron service for scheduling agent tasks."""
+
+import asyncio
+import json
+import time
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable, Coroutine
+
+from loguru import logger
+
+from nanobot.cron.types import CronJob, CronJobState, CronPayload, CronSchedule, CronStore
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _compute_next_run(schedule: CronSchedule, now_ms: int) -> int | None:
+    """Compute next run time in ms."""
+    if schedule.kind == "at":
+        return schedule.at_ms if schedule.at_ms and schedule.at_ms > now_ms else None
+
+    if schedule.kind == "every":
+        if not schedule.every_ms or schedule.every_ms <= 0:
+            return None
+        # Next interval from now
+        return now_ms + schedule.every_ms
+
+    if schedule.kind == "cron" and schedule.expr:
+        try:
+            from zoneinfo import ZoneInfo
+
+            from croniter import croniter
+            # Use caller-provided reference time for deterministic scheduling
+            base_time = now_ms / 1000
+            tz = ZoneInfo(schedule.tz) if schedule.tz else datetime.now().astimezone().tzinfo
+            base_dt = datetime.fromtimestamp(base_time, tz=tz)
+            cron = croniter(schedule.expr, base_dt)
+            next_dt = cron.get_next(datetime)
+            return int(next_dt.timestamp() * 1000)
+        except Exception:
+            return None
+
+    return None
+
+
+def _validate_schedule_for_add(schedule: CronSchedule) -> None:
+    """Validate schedule fields that would otherwise create non-runnable jobs."""
+    if schedule.tz and schedule.kind != "cron":
+        raise ValueError("tz can only be used with cron schedules")
+
+    if schedule.kind == "cron" and schedule.tz:
+        try:
+            from zoneinfo import ZoneInfo
+
+            ZoneInfo(schedule.tz)
+        except Exception:
+            raise ValueError(f"unknown timezone '{schedule.tz}'") from None
+
+
+class CronService:
+    """Service for managing and executing scheduled jobs."""
+
+    def __init__(
+        self,
+        store_path: Path,
+        on_job: Callable[[CronJob], Coroutine[Any, Any, str | None]] | None = None
+    ):
+        self.store_path = store_path
+        self.on_job = on_job
+        self._store: CronStore | None = None
+        self._last_mtime: float = 0.0
+        self._timer_task: asyncio.Task | None = None
+        self._running = False
+
+    def _load_store(self) -> CronStore:
+        """Load jobs from disk. Reloads automatically if file was modified externally."""
+        if self._store and self.store_path.exists():
+            mtime = self.store_path.stat().st_mtime
+            if mtime != self._last_mtime:
+                logger.info("Cron: jobs.json modified externally, reloading")
+                self._store = None
+        if self._store:
+            return self._store
+
+        if self.store_path.exists():
+            try:
+                data = json.loads(self.store_path.read_text(encoding="utf-8"))
+                jobs = []
+                for j in data.get("jobs", []):
+                    jobs.append(CronJob(
+                        id=j["id"],
+                        name=j["name"],
+                        enabled=j.get("enabled", True),
+                        schedule=CronSchedule(
+                            kind=j["schedule"]["kind"],
+                            at_ms=j["schedule"].get("atMs"),
+                            every_ms=j["schedule"].get("everyMs"),
+                            expr=j["schedule"].get("expr"),
+                            tz=j["schedule"].get("tz"),
+                        ),
+                        payload=CronPayload(
+                            kind=j["payload"].get("kind", "agent_turn"),
+                            message=j["payload"].get("message", ""),
+                            deliver=j["payload"].get("deliver", False),
+                            channel=j["payload"].get("channel"),
+                            to=j["payload"].get("to"),
+                        ),
+                        state=CronJobState(
+                            next_run_at_ms=j.get("state", {}).get("nextRunAtMs"),
+                            last_run_at_ms=j.get("state", {}).get("lastRunAtMs"),
+                            last_status=j.get("state", {}).get("lastStatus"),
+                            last_error=j.get("state", {}).get("lastError"),
+                        ),
+                        created_at_ms=j.get("createdAtMs", 0),
+                        updated_at_ms=j.get("updatedAtMs", 0),
+                        delete_after_run=j.get("deleteAfterRun", False),
+                    ))
+                self._store = CronStore(jobs=jobs)
+            except Exception as e:
+                logger.warning("Failed to load cron store: {}", e)
+                self._store = CronStore()
+        else:
+            self._store = CronStore()
+
+        return self._store
+
+    def _save_store(self) -> None:
+        """Save jobs to disk."""
+        if not self._store:
+            return
+
+        self.store_path.parent.mkdir(parents=True, exist_ok=True)
+
+        data = {
+            "version": self._store.version,
+            "jobs": [
+                {
+                    "id": j.id,
+                    "name": j.name,
+                    "enabled": j.enabled,
+                    "schedule": {
+                        "kind": j.schedule.kind,
+                        "atMs": j.schedule.at_ms,
+                        "everyMs": j.schedule.every_ms,
+                        "expr": j.schedule.expr,
+                        "tz": j.schedule.tz,
+                    },
+                    "payload": {
+                        "kind": j.payload.kind,
+                        "message": j.payload.message,
+                        "deliver": j.payload.deliver,
+                        "channel": j.payload.channel,
+                        "to": j.payload.to,
+                    },
+                    "state": {
+                        "nextRunAtMs": j.state.next_run_at_ms,
+                        "lastRunAtMs": j.state.last_run_at_ms,
+                        "lastStatus": j.state.last_status,
+                        "lastError": j.state.last_error,
+                    },
+                    "createdAtMs": j.created_at_ms,
+                    "updatedAtMs": j.updated_at_ms,
+                    "deleteAfterRun": j.delete_after_run,
+                }
+                for j in self._store.jobs
+            ]
+        }
+
+        self.store_path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+        self._last_mtime = self.store_path.stat().st_mtime
+    
+    async def start(self) -> None:
+        """Start the cron service."""
+        self._running = True
+        self._load_store()
+        self._recompute_next_runs()
+        self._save_store()
+        self._arm_timer()
+        logger.info("Cron service started with {} jobs", len(self._store.jobs if self._store else []))
+
+    def stop(self) -> None:
+        """Stop the cron service."""
+        self._running = False
+        if self._timer_task:
+            self._timer_task.cancel()
+            self._timer_task = None
+
+    def _recompute_next_runs(self) -> None:
+        """Recompute next run times for all enabled jobs."""
+        if not self._store:
+            return
+        now = _now_ms()
+        for job in self._store.jobs:
+            if job.enabled:
+                job.state.next_run_at_ms = _compute_next_run(job.schedule, now)
+
+    def _get_next_wake_ms(self) -> int | None:
+        """Get the earliest next run time across all jobs."""
+        if not self._store:
+            return None
+        times = [j.state.next_run_at_ms for j in self._store.jobs
+                 if j.enabled and j.state.next_run_at_ms]
+        return min(times) if times else None
+
+    def _arm_timer(self) -> None:
+        """Schedule the next timer tick."""
+        if self._timer_task:
+            self._timer_task.cancel()
+
+        next_wake = self._get_next_wake_ms()
+        if not next_wake or not self._running:
+            return
+
+        delay_ms = max(0, next_wake - _now_ms())
+        delay_s = delay_ms / 1000
+
+        async def tick():
+            await asyncio.sleep(delay_s)
+            if self._running:
+                await self._on_timer()
+
+        self._timer_task = asyncio.create_task(tick())
+
+    async def _on_timer(self) -> None:
+        """Handle timer tick - run due jobs."""
+        self._load_store()
+        if not self._store:
+            return
+
+        now = _now_ms()
+        due_jobs = [
+            j for j in self._store.jobs
+            if j.enabled and j.state.next_run_at_ms and now >= j.state.next_run_at_ms
+        ]
+
+        for job in due_jobs:
+            await self._execute_job(job)
+
+        self._save_store()
+        self._arm_timer()
+
+    async def _execute_job(self, job: CronJob) -> None:
+        """Execute a single job."""
+        start_ms = _now_ms()
+        logger.info("Cron: executing job '{}' ({})", job.name, job.id)
+
+        try:
+            response = None
+            if self.on_job:
+                response = await self.on_job(job)
+
+            job.state.last_status = "ok"
+            job.state.last_error = None
+            logger.info("Cron: job '{}' completed", job.name)
+
+        except Exception as e:
+            job.state.last_status = "error"
+            job.state.last_error = str(e)
+            logger.error("Cron: job '{}' failed: {}", job.name, e)
+
+        job.state.last_run_at_ms = start_ms
+        job.updated_at_ms = _now_ms()
+
+        # Handle one-shot jobs
+        if job.schedule.kind == "at":
+            if job.delete_after_run:
+                self._store.jobs = [j for j in self._store.jobs if j.id != job.id]
+            else:
+                job.enabled = False
+                job.state.next_run_at_ms = None
+        else:
+            # Compute next run
+            job.state.next_run_at_ms = _compute_next_run(job.schedule, _now_ms())
+
+    # ========== Public API ==========
+
+    def list_jobs(self, include_disabled: bool = False) -> list[CronJob]:
+        """List all jobs."""
+        store = self._load_store()
+        jobs = store.jobs if include_disabled else [j for j in store.jobs if j.enabled]
+        return sorted(jobs, key=lambda j: j.state.next_run_at_ms or float('inf'))
+
+    def add_job(
+        self,
+        name: str,
+        schedule: CronSchedule,
+        message: str,
+        deliver: bool = False,
+        channel: str | None = None,
+        to: str | None = None,
+        delete_after_run: bool = False,
+    ) -> CronJob:
+        """Add a new job."""
+        store = self._load_store()
+        _validate_schedule_for_add(schedule)
+        now = _now_ms()
+
+        job = CronJob(
+            id=str(uuid.uuid4())[:8],
+            name=name,
+            enabled=True,
+            schedule=schedule,
+            payload=CronPayload(
+                kind="agent_turn",
+                message=message,
+                deliver=deliver,
+                channel=channel,
+                to=to,
+            ),
+            state=CronJobState(next_run_at_ms=_compute_next_run(schedule, now)),
+            created_at_ms=now,
+            updated_at_ms=now,
+            delete_after_run=delete_after_run,
+        )
+
+        store.jobs.append(job)
+        self._save_store()
+        self._arm_timer()
+
+        logger.info("Cron: added job '{}' ({})", name, job.id)
+        return job
+
+    def remove_job(self, job_id: str) -> bool:
+        """Remove a job by ID."""
+        store = self._load_store()
+        before = len(store.jobs)
+        store.jobs = [j for j in store.jobs if j.id != job_id]
+        removed = len(store.jobs) < before
+
+        if removed:
+            self._save_store()
+            self._arm_timer()
+            logger.info("Cron: removed job {}", job_id)
+
+        return removed
+
+    def enable_job(self, job_id: str, enabled: bool = True) -> CronJob | None:
+        """Enable or disable a job."""
+        store = self._load_store()
+        for job in store.jobs:
+            if job.id == job_id:
+                job.enabled = enabled
+                job.updated_at_ms = _now_ms()
+                if enabled:
+                    job.state.next_run_at_ms = _compute_next_run(job.schedule, _now_ms())
+                else:
+                    job.state.next_run_at_ms = None
+                self._save_store()
+                self._arm_timer()
+                return job
+        return None
+
+    async def run_job(self, job_id: str, force: bool = False) -> bool:
+        """Manually run a job."""
+        store = self._load_store()
+        for job in store.jobs:
+            if job.id == job_id:
+                if not force and not job.enabled:
+                    return False
+                await self._execute_job(job)
+                self._save_store()
+                self._arm_timer()
+                return True
+        return False
+
+    def status(self) -> dict:
+        """Get service status."""
+        store = self._load_store()
+        return {
+            "enabled": self._running,
+            "jobs": len(store.jobs),
+            "next_wake_at_ms": self._get_next_wake_ms(),
+        }
diff --git a/core/nanobot/nanobot/cron/types.py b/core/nanobot/nanobot/cron/types.py
new file mode 100644
index 0000000..2b42060
--- /dev/null
+++ b/core/nanobot/nanobot/cron/types.py
@@ -0,0 +1,59 @@
+"""Cron types."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class CronSchedule:
+    """Schedule definition for a cron job."""
+    kind: Literal["at", "every", "cron"]
+    # For "at": timestamp in ms
+    at_ms: int | None = None
+    # For "every": interval in ms
+    every_ms: int | None = None
+    # For "cron": cron expression (e.g. "0 9 * * *")
+    expr: str | None = None
+    # Timezone for cron expressions
+    tz: str | None = None
+
+
+@dataclass
+class CronPayload:
+    """What to do when the job runs."""
+    kind: Literal["system_event", "agent_turn"] = "agent_turn"
+    message: str = ""
+    # Deliver response to channel
+    deliver: bool = False
+    channel: str | None = None  # e.g. "whatsapp"
+    to: str | None = None  # e.g. phone number
+
+
+@dataclass
+class CronJobState:
+    """Runtime state of a job."""
+    next_run_at_ms: int | None = None
+    last_run_at_ms: int | None = None
+    last_status: Literal["ok", "error", "skipped"] | None = None
+    last_error: str | None = None
+
+
+@dataclass
+class CronJob:
+    """A scheduled job."""
+    id: str
+    name: str
+    enabled: bool = True
+    schedule: CronSchedule = field(default_factory=lambda: CronSchedule(kind="every"))
+    payload: CronPayload = field(default_factory=CronPayload)
+    state: CronJobState = field(default_factory=CronJobState)
+    created_at_ms: int = 0
+    updated_at_ms: int = 0
+    delete_after_run: bool = False
+
+
+@dataclass
+class CronStore:
+    """Persistent store for cron jobs."""
+    version: int = 1
+    jobs: list[CronJob] = field(default_factory=list)
diff --git a/core/nanobot/nanobot/heartbeat/__init__.py b/core/nanobot/nanobot/heartbeat/__init__.py
new file mode 100644
index 0000000..2ecd879
--- /dev/null
+++ b/core/nanobot/nanobot/heartbeat/__init__.py
@@ -0,0 +1,5 @@
+"""Heartbeat service for periodic agent wake-ups."""
+
+from nanobot.heartbeat.service import HeartbeatService
+
+__all__ = ["HeartbeatService"]
diff --git a/core/nanobot/nanobot/heartbeat/service.py b/core/nanobot/nanobot/heartbeat/service.py
new file mode 100644
index 0000000..831ae85
--- /dev/null
+++ b/core/nanobot/nanobot/heartbeat/service.py
@@ -0,0 +1,173 @@
+"""Heartbeat service - periodic agent wake-up to check for tasks."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Coroutine
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from nanobot.providers.base import LLMProvider
+
+_HEARTBEAT_TOOL = [
+    {
+        "type": "function",
+        "function": {
+            "name": "heartbeat",
+            "description": "Report heartbeat decision after reviewing tasks.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "action": {
+                        "type": "string",
+                        "enum": ["skip", "run"],
+                        "description": "skip = nothing to do, run = has active tasks",
+                    },
+                    "tasks": {
+                        "type": "string",
+                        "description": "Natural-language summary of active tasks (required for run)",
+                    },
+                },
+                "required": ["action"],
+            },
+        },
+    }
+]
+
+
+class HeartbeatService:
+    """
+    Periodic heartbeat service that wakes the agent to check for tasks.
+
+    Phase 1 (decision): reads HEARTBEAT.md and asks the LLM — via a virtual
+    tool call — whether there are active tasks.  This avoids free-text parsing
+    and the unreliable HEARTBEAT_OK token.
+
+    Phase 2 (execution): only triggered when Phase 1 returns ``run``.  The
+    ``on_execute`` callback runs the task through the full agent loop and
+    returns the result to deliver.
+    """
+
+    def __init__(
+        self,
+        workspace: Path,
+        provider: LLMProvider,
+        model: str,
+        on_execute: Callable[[str], Coroutine[Any, Any, str]] | None = None,
+        on_notify: Callable[[str], Coroutine[Any, Any, None]] | None = None,
+        interval_s: int = 30 * 60,
+        enabled: bool = True,
+    ):
+        self.workspace = workspace
+        self.provider = provider
+        self.model = model
+        self.on_execute = on_execute
+        self.on_notify = on_notify
+        self.interval_s = interval_s
+        self.enabled = enabled
+        self._running = False
+        self._task: asyncio.Task | None = None
+
+    @property
+    def heartbeat_file(self) -> Path:
+        return self.workspace / "HEARTBEAT.md"
+
+    def _read_heartbeat_file(self) -> str | None:
+        if self.heartbeat_file.exists():
+            try:
+                return self.heartbeat_file.read_text(encoding="utf-8")
+            except Exception:
+                return None
+        return None
+
+    async def _decide(self, content: str) -> tuple[str, str]:
+        """Phase 1: ask LLM to decide skip/run via virtual tool call.
+
+        Returns (action, tasks) where action is 'skip' or 'run'.
+        """
+        response = await self.provider.chat_with_retry(
+            messages=[
+                {"role": "system", "content": "You are a heartbeat agent. Call the heartbeat tool to report your decision."},
+                {"role": "user", "content": (
+                    "Review the following HEARTBEAT.md and decide whether there are active tasks.\n\n"
+                    f"{content}"
+                )},
+            ],
+            tools=_HEARTBEAT_TOOL,
+            model=self.model,
+        )
+
+        if not response.has_tool_calls:
+            return "skip", ""
+
+        args = response.tool_calls[0].arguments
+        return args.get("action", "skip"), args.get("tasks", "")
+
+    async def start(self) -> None:
+        """Start the heartbeat service."""
+        if not self.enabled:
+            logger.info("Heartbeat disabled")
+            return
+        if self._running:
+            logger.warning("Heartbeat already running")
+            return
+
+        self._running = True
+        self._task = asyncio.create_task(self._run_loop())
+        logger.info("Heartbeat started (every {}s)", self.interval_s)
+
+    def stop(self) -> None:
+        """Stop the heartbeat service."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            self._task = None
+
+    async def _run_loop(self) -> None:
+        """Main heartbeat loop."""
+        while self._running:
+            try:
+                await asyncio.sleep(self.interval_s)
+                if self._running:
+                    await self._tick()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error("Heartbeat error: {}", e)
+
+    async def _tick(self) -> None:
+        """Execute a single heartbeat tick."""
+        content = self._read_heartbeat_file()
+        if not content:
+            logger.debug("Heartbeat: HEARTBEAT.md missing or empty")
+            return
+
+        logger.info("Heartbeat: checking for tasks...")
+
+        try:
+            action, tasks = await self._decide(content)
+
+            if action != "run":
+                logger.info("Heartbeat: OK (nothing to report)")
+                return
+
+            logger.info("Heartbeat: tasks found, executing...")
+            if self.on_execute:
+                response = await self.on_execute(tasks)
+                if response and self.on_notify:
+                    logger.info("Heartbeat: completed, delivering response")
+                    await self.on_notify(response)
+        except Exception:
+            logger.exception("Heartbeat execution failed")
+
+    async def trigger_now(self) -> str | None:
+        """Manually trigger a heartbeat."""
+        content = self._read_heartbeat_file()
+        if not content:
+            return None
+        action, tasks = await self._decide(content)
+        if action != "run" or not self.on_execute:
+            return None
+        return await self.on_execute(tasks)
diff --git a/core/nanobot/nanobot/providers/__init__.py b/core/nanobot/nanobot/providers/__init__.py
new file mode 100644
index 0000000..5bd06f9
--- /dev/null
+++ b/core/nanobot/nanobot/providers/__init__.py
@@ -0,0 +1,8 @@
+"""LLM provider abstraction module."""
+
+from nanobot.providers.base import LLMProvider, LLMResponse
+from nanobot.providers.litellm_provider import LiteLLMProvider
+from nanobot.providers.openai_codex_provider import OpenAICodexProvider
+from nanobot.providers.azure_openai_provider import AzureOpenAIProvider
+
+__all__ = ["LLMProvider", "LLMResponse", "LiteLLMProvider", "OpenAICodexProvider", "AzureOpenAIProvider"]
diff --git a/core/nanobot/nanobot/providers/azure_openai_provider.py b/core/nanobot/nanobot/providers/azure_openai_provider.py
new file mode 100644
index 0000000..bd79b00
--- /dev/null
+++ b/core/nanobot/nanobot/providers/azure_openai_provider.py
@@ -0,0 +1,210 @@
+"""Azure OpenAI provider implementation with API version 2024-10-21."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+import json_repair
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+_AZURE_MSG_KEYS = frozenset({"role", "content", "tool_calls", "tool_call_id", "name"})
+
+
+class AzureOpenAIProvider(LLMProvider):
+    """
+    Azure OpenAI provider with API version 2024-10-21 compliance.
+    
+    Features:
+    - Hardcoded API version 2024-10-21
+    - Uses model field as Azure deployment name in URL path
+    - Uses api-key header instead of Authorization Bearer
+    - Uses max_completion_tokens instead of max_tokens
+    - Direct HTTP calls, bypasses LiteLLM
+    """
+
+    def __init__(
+        self,
+        api_key: str = "",
+        api_base: str = "",
+        default_model: str = "gpt-5.2-chat",
+    ):
+        super().__init__(api_key, api_base)
+        self.default_model = default_model
+        self.api_version = "2024-10-21"
+        
+        # Validate required parameters
+        if not api_key:
+            raise ValueError("Azure OpenAI api_key is required")
+        if not api_base:
+            raise ValueError("Azure OpenAI api_base is required")
+        
+        # Ensure api_base ends with /
+        if not api_base.endswith('/'):
+            api_base += '/'
+        self.api_base = api_base
+
+    def _build_chat_url(self, deployment_name: str) -> str:
+        """Build the Azure OpenAI chat completions URL."""
+        # Azure OpenAI URL format:
+        # https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version={version}
+        base_url = self.api_base
+        if not base_url.endswith('/'):
+            base_url += '/'
+        
+        url = urljoin(
+            base_url, 
+            f"openai/deployments/{deployment_name}/chat/completions"
+        )
+        return f"{url}?api-version={self.api_version}"
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers for Azure OpenAI API with api-key header."""
+        return {
+            "Content-Type": "application/json",
+            "api-key": self.api_key,  # Azure OpenAI uses api-key header, not Authorization
+            "x-session-affinity": uuid.uuid4().hex,  # For cache locality
+        }
+
+    @staticmethod
+    def _supports_temperature(
+        deployment_name: str,
+        reasoning_effort: str | None = None,
+    ) -> bool:
+        """Return True when temperature is likely supported for this deployment."""
+        if reasoning_effort:
+            return False
+        name = deployment_name.lower()
+        return not any(token in name for token in ("gpt-5", "o1", "o3", "o4"))
+
+    def _prepare_request_payload(
+        self,
+        deployment_name: str,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        reasoning_effort: str | None = None,
+    ) -> dict[str, Any]:
+        """Prepare the request payload with Azure OpenAI 2024-10-21 compliance."""
+        payload: dict[str, Any] = {
+            "messages": self._sanitize_request_messages(
+                self._sanitize_empty_content(messages),
+                _AZURE_MSG_KEYS,
+            ),
+            "max_completion_tokens": max(1, max_tokens),  # Azure API 2024-10-21 uses max_completion_tokens
+        }
+
+        if self._supports_temperature(deployment_name, reasoning_effort):
+            payload["temperature"] = temperature
+
+        if reasoning_effort:
+            payload["reasoning_effort"] = reasoning_effort
+
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = "auto"
+
+        return payload
+
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        reasoning_effort: str | None = None,
+    ) -> LLMResponse:
+        """
+        Send a chat completion request to Azure OpenAI.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'.
+            tools: Optional list of tool definitions in OpenAI format.
+            model: Model identifier (used as deployment name).
+            max_tokens: Maximum tokens in response (mapped to max_completion_tokens).
+            temperature: Sampling temperature.
+            reasoning_effort: Optional reasoning effort parameter.
+
+        Returns:
+            LLMResponse with content and/or tool calls.
+        """
+        deployment_name = model or self.default_model
+        url = self._build_chat_url(deployment_name)
+        headers = self._build_headers()
+        payload = self._prepare_request_payload(
+            deployment_name, messages, tools, max_tokens, temperature, reasoning_effort
+        )
+
+        try:
+            async with httpx.AsyncClient(timeout=60.0, verify=True) as client:
+                response = await client.post(url, headers=headers, json=payload)
+                if response.status_code != 200:
+                    return LLMResponse(
+                        content=f"Azure OpenAI API Error {response.status_code}: {response.text}",
+                        finish_reason="error",
+                    )
+                
+                response_data = response.json()
+                return self._parse_response(response_data)
+
+        except Exception as e:
+            return LLMResponse(
+                content=f"Error calling Azure OpenAI: {repr(e)}",
+                finish_reason="error",
+            )
+
+    def _parse_response(self, response: dict[str, Any]) -> LLMResponse:
+        """Parse Azure OpenAI response into our standard format."""
+        try:
+            choice = response["choices"][0]
+            message = choice["message"]
+
+            tool_calls = []
+            if message.get("tool_calls"):
+                for tc in message["tool_calls"]:
+                    # Parse arguments from JSON string if needed
+                    args = tc["function"]["arguments"]
+                    if isinstance(args, str):
+                        args = json_repair.loads(args)
+
+                    tool_calls.append(
+                        ToolCallRequest(
+                            id=tc["id"],
+                            name=tc["function"]["name"],
+                            arguments=args,
+                        )
+                    )
+
+            usage = {}
+            if response.get("usage"):
+                usage_data = response["usage"]
+                usage = {
+                    "prompt_tokens": usage_data.get("prompt_tokens", 0),
+                    "completion_tokens": usage_data.get("completion_tokens", 0),
+                    "total_tokens": usage_data.get("total_tokens", 0),
+                }
+
+            reasoning_content = message.get("reasoning_content") or None
+
+            return LLMResponse(
+                content=message.get("content"),
+                tool_calls=tool_calls,
+                finish_reason=choice.get("finish_reason", "stop"),
+                usage=usage,
+                reasoning_content=reasoning_content,
+            )
+
+        except (KeyError, IndexError) as e:
+            return LLMResponse(
+                content=f"Error parsing Azure OpenAI response: {str(e)}",
+                finish_reason="error",
+            )
+
+    def get_default_model(self) -> str:
+        """Get the default model (also used as default deployment name)."""
+        return self.default_model
\ No newline at end of file
diff --git a/core/nanobot/nanobot/providers/base.py b/core/nanobot/nanobot/providers/base.py
new file mode 100644
index 0000000..15a10ff
--- /dev/null
+++ b/core/nanobot/nanobot/providers/base.py
@@ -0,0 +1,265 @@
+"""Base LLM provider interface."""
+
+import asyncio
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from loguru import logger
+
+
+@dataclass
+class ToolCallRequest:
+    """A tool call request from the LLM."""
+    id: str
+    name: str
+    arguments: dict[str, Any]
+    provider_specific_fields: dict[str, Any] | None = None
+    function_provider_specific_fields: dict[str, Any] | None = None
+
+    def to_openai_tool_call(self) -> dict[str, Any]:
+        """Serialize to an OpenAI-style tool_call payload."""
+        tool_call = {
+            "id": self.id,
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "arguments": json.dumps(self.arguments, ensure_ascii=False),
+            },
+        }
+        if self.provider_specific_fields:
+            tool_call["provider_specific_fields"] = self.provider_specific_fields
+        if self.function_provider_specific_fields:
+            tool_call["function"]["provider_specific_fields"] = self.function_provider_specific_fields
+        return tool_call
+
+
+@dataclass
+class LLMResponse:
+    """Response from an LLM provider."""
+    content: str | None
+    tool_calls: list[ToolCallRequest] = field(default_factory=list)
+    finish_reason: str = "stop"
+    usage: dict[str, int] = field(default_factory=dict)
+    reasoning_content: str | None = None  # Kimi, DeepSeek-R1 etc.
+    thinking_blocks: list[dict] | None = None  # Anthropic extended thinking
+    
+    @property
+    def has_tool_calls(self) -> bool:
+        """Check if response contains tool calls."""
+        return len(self.tool_calls) > 0
+
+
+@dataclass(frozen=True)
+class GenerationSettings:
+    """Default generation parameters for LLM calls.
+
+    Stored on the provider so every call site inherits the same defaults
+    without having to pass temperature / max_tokens / reasoning_effort
+    through every layer.  Individual call sites can still override by
+    passing explicit keyword arguments to chat() / chat_with_retry().
+    """
+
+    temperature: float = 0.7
+    max_tokens: int = 4096
+    reasoning_effort: str | None = None
+
+
+class LLMProvider(ABC):
+    """
+    Abstract base class for LLM providers.
+    
+    Implementations should handle the specifics of each provider's API
+    while maintaining a consistent interface.
+    """
+
+    _CHAT_RETRY_DELAYS = (1, 2, 4)
+    _TRANSIENT_ERROR_MARKERS = (
+        "429",
+        "rate limit",
+        "500",
+        "502",
+        "503",
+        "504",
+        "overloaded",
+        "timeout",
+        "timed out",
+        "connection",
+        "server error",
+        "temporarily unavailable",
+    )
+
+    _SENTINEL = object()
+
+    def __init__(self, api_key: str | None = None, api_base: str | None = None):
+        self.api_key = api_key
+        self.api_base = api_base
+        self.generation: GenerationSettings = GenerationSettings()
+
+    @staticmethod
+    def _sanitize_empty_content(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Replace empty text content that causes provider 400 errors.
+
+        Empty content can appear when MCP tools return nothing. Most providers
+        reject empty-string content or empty text blocks in list content.
+        """
+        result: list[dict[str, Any]] = []
+        for msg in messages:
+            content = msg.get("content")
+
+            if isinstance(content, str) and not content:
+                clean = dict(msg)
+                clean["content"] = None if (msg.get("role") == "assistant" and msg.get("tool_calls")) else "(empty)"
+                result.append(clean)
+                continue
+
+            if isinstance(content, list):
+                filtered = [
+                    item for item in content
+                    if not (
+                        isinstance(item, dict)
+                        and item.get("type") in ("text", "input_text", "output_text")
+                        and not item.get("text")
+                    )
+                ]
+                if len(filtered) != len(content):
+                    clean = dict(msg)
+                    if filtered:
+                        clean["content"] = filtered
+                    elif msg.get("role") == "assistant" and msg.get("tool_calls"):
+                        clean["content"] = None
+                    else:
+                        clean["content"] = "(empty)"
+                    result.append(clean)
+                    continue
+
+            if isinstance(content, dict):
+                clean = dict(msg)
+                clean["content"] = [content]
+                result.append(clean)
+                continue
+
+            result.append(msg)
+        return result
+
+    @staticmethod
+    def _sanitize_request_messages(
+        messages: list[dict[str, Any]],
+        allowed_keys: frozenset[str],
+    ) -> list[dict[str, Any]]:
+        """Keep only provider-safe message keys and normalize assistant content."""
+        sanitized = []
+        for msg in messages:
+            clean = {k: v for k, v in msg.items() if k in allowed_keys}
+            if clean.get("role") == "assistant" and "content" not in clean:
+                clean["content"] = None
+            sanitized.append(clean)
+        return sanitized
+
+    @abstractmethod
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        reasoning_effort: str | None = None,
+    ) -> LLMResponse:
+        """
+        Send a chat completion request.
+        
+        Args:
+            messages: List of message dicts with 'role' and 'content'.
+            tools: Optional list of tool definitions.
+            model: Model identifier (provider-specific).
+            max_tokens: Maximum tokens in response.
+            temperature: Sampling temperature.
+        
+        Returns:
+            LLMResponse with content and/or tool calls.
+        """
+        pass
+
+    @classmethod
+    def _is_transient_error(cls, content: str | None) -> bool:
+        err = (content or "").lower()
+        return any(marker in err for marker in cls._TRANSIENT_ERROR_MARKERS)
+
+    async def chat_with_retry(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: object = _SENTINEL,
+        temperature: object = _SENTINEL,
+        reasoning_effort: object = _SENTINEL,
+    ) -> LLMResponse:
+        """Call chat() with retry on transient provider failures.
+
+        Parameters default to ``self.generation`` when not explicitly passed,
+        so callers no longer need to thread temperature / max_tokens /
+        reasoning_effort through every layer.
+        """
+        if max_tokens is self._SENTINEL:
+            max_tokens = self.generation.max_tokens
+        if temperature is self._SENTINEL:
+            temperature = self.generation.temperature
+        if reasoning_effort is self._SENTINEL:
+            reasoning_effort = self.generation.reasoning_effort
+
+        for attempt, delay in enumerate(self._CHAT_RETRY_DELAYS, start=1):
+            try:
+                response = await self.chat(
+                    messages=messages,
+                    tools=tools,
+                    model=model,
+                    max_tokens=max_tokens,
+                    temperature=temperature,
+                    reasoning_effort=reasoning_effort,
+                )
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                response = LLMResponse(
+                    content=f"Error calling LLM: {exc}",
+                    finish_reason="error",
+                )
+
+            if response.finish_reason != "error":
+                return response
+            if not self._is_transient_error(response.content):
+                return response
+
+            err = (response.content or "").lower()
+            logger.warning(
+                "LLM transient error (attempt {}/{}), retrying in {}s: {}",
+                attempt,
+                len(self._CHAT_RETRY_DELAYS),
+                delay,
+                err[:120],
+            )
+            await asyncio.sleep(delay)
+
+        try:
+            return await self.chat(
+                messages=messages,
+                tools=tools,
+                model=model,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                reasoning_effort=reasoning_effort,
+            )
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            return LLMResponse(
+                content=f"Error calling LLM: {exc}",
+                finish_reason="error",
+            )
+
+    @abstractmethod
+    def get_default_model(self) -> str:
+        """Get the default model for this provider."""
+        pass
diff --git a/core/nanobot/nanobot/providers/custom_provider.py b/core/nanobot/nanobot/providers/custom_provider.py
new file mode 100644
index 0000000..66df734
--- /dev/null
+++ b/core/nanobot/nanobot/providers/custom_provider.py
@@ -0,0 +1,61 @@
+"""Direct OpenAI-compatible provider — bypasses LiteLLM."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+import json_repair
+from openai import AsyncOpenAI
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+
+class CustomProvider(LLMProvider):
+
+    def __init__(self, api_key: str = "no-key", api_base: str = "http://localhost:8000/v1", default_model: str = "default"):
+        super().__init__(api_key, api_base)
+        self.default_model = default_model
+        # Keep affinity stable for this provider instance to improve backend cache locality.
+        self._client = AsyncOpenAI(
+            api_key=api_key,
+            base_url=api_base,
+            default_headers={"x-session-affinity": uuid.uuid4().hex},
+        )
+
+    async def chat(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None = None,
+                   model: str | None = None, max_tokens: int = 4096, temperature: float = 0.7,
+                   reasoning_effort: str | None = None) -> LLMResponse:
+        kwargs: dict[str, Any] = {
+            "model": model or self.default_model,
+            "messages": self._sanitize_empty_content(messages),
+            "max_tokens": max(1, max_tokens),
+            "temperature": temperature,
+        }
+        if reasoning_effort:
+            kwargs["reasoning_effort"] = reasoning_effort
+        if tools:
+            kwargs.update(tools=tools, tool_choice="auto")
+        try:
+            return self._parse(await self._client.chat.completions.create(**kwargs))
+        except Exception as e:
+            return LLMResponse(content=f"Error: {e}", finish_reason="error")
+
+    def _parse(self, response: Any) -> LLMResponse:
+        choice = response.choices[0]
+        msg = choice.message
+        tool_calls = [
+            ToolCallRequest(id=tc.id, name=tc.function.name,
+                            arguments=json_repair.loads(tc.function.arguments) if isinstance(tc.function.arguments, str) else tc.function.arguments)
+            for tc in (msg.tool_calls or [])
+        ]
+        u = response.usage
+        return LLMResponse(
+            content=msg.content, tool_calls=tool_calls, finish_reason=choice.finish_reason or "stop",
+            usage={"prompt_tokens": u.prompt_tokens, "completion_tokens": u.completion_tokens, "total_tokens": u.total_tokens} if u else {},
+            reasoning_content=getattr(msg, "reasoning_content", None) or None,
+        )
+
+    def get_default_model(self) -> str:
+        return self.default_model
+
diff --git a/core/nanobot/nanobot/providers/litellm_provider.py b/core/nanobot/nanobot/providers/litellm_provider.py
new file mode 100644
index 0000000..af91c2f
--- /dev/null
+++ b/core/nanobot/nanobot/providers/litellm_provider.py
@@ -0,0 +1,347 @@
+"""LiteLLM provider implementation for multi-provider support."""
+
+import hashlib
+import os
+import secrets
+import string
+from typing import Any
+
+import json_repair
+import litellm
+from litellm import acompletion
+from loguru import logger
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+from nanobot.providers.registry import find_by_model, find_gateway
+
+# Standard chat-completion message keys.
+_ALLOWED_MSG_KEYS = frozenset({"role", "content", "tool_calls", "tool_call_id", "name", "reasoning_content"})
+_ANTHROPIC_EXTRA_KEYS = frozenset({"thinking_blocks"})
+_ALNUM = string.ascii_letters + string.digits
+
+def _short_tool_id() -> str:
+    """Generate a 9-char alphanumeric ID compatible with all providers (incl. Mistral)."""
+    return "".join(secrets.choice(_ALNUM) for _ in range(9))
+
+
+class LiteLLMProvider(LLMProvider):
+    """
+    LLM provider using LiteLLM for multi-provider support.
+    
+    Supports OpenRouter, Anthropic, OpenAI, Gemini, MiniMax, and many other providers through
+    a unified interface.  Provider-specific logic is driven by the registry
+    (see providers/registry.py) — no if-elif chains needed here.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        api_base: str | None = None,
+        default_model: str = "anthropic/claude-opus-4-5",
+        extra_headers: dict[str, str] | None = None,
+        provider_name: str | None = None,
+    ):
+        super().__init__(api_key, api_base)
+        self.default_model = default_model
+        self.extra_headers = extra_headers or {}
+
+        # Detect gateway / local deployment.
+        # provider_name (from config key) is the primary signal;
+        # api_key / api_base are fallback for auto-detection.
+        self._gateway = find_gateway(provider_name, api_key, api_base)
+
+        # Configure environment variables
+        if api_key:
+            self._setup_env(api_key, api_base, default_model)
+
+        if api_base:
+            litellm.api_base = api_base
+
+        # Disable LiteLLM logging noise
+        litellm.suppress_debug_info = True
+        # Drop unsupported parameters for providers (e.g., gpt-5 rejects some params)
+        litellm.drop_params = True
+
+    def _setup_env(self, api_key: str, api_base: str | None, model: str) -> None:
+        """Set environment variables based on detected provider."""
+        spec = self._gateway or find_by_model(model)
+        if not spec:
+            return
+        if not spec.env_key:
+            # OAuth/provider-only specs (for example: openai_codex)
+            return
+
+        # Gateway/local overrides existing env; standard provider doesn't
+        if self._gateway:
+            os.environ[spec.env_key] = api_key
+        else:
+            os.environ.setdefault(spec.env_key, api_key)
+
+        # Resolve env_extras placeholders:
+        #   {api_key}  → user's API key
+        #   {api_base} → user's api_base, falling back to spec.default_api_base
+        effective_base = api_base or spec.default_api_base
+        for env_name, env_val in spec.env_extras:
+            resolved = env_val.replace("{api_key}", api_key)
+            resolved = resolved.replace("{api_base}", effective_base)
+            os.environ.setdefault(env_name, resolved)
+
+    def _resolve_model(self, model: str) -> str:
+        """Resolve model name by applying provider/gateway prefixes."""
+        if self._gateway:
+            # Gateway mode: apply gateway prefix, skip provider-specific prefixes
+            prefix = self._gateway.litellm_prefix
+            if self._gateway.strip_model_prefix:
+                model = model.split("/")[-1]
+            if prefix and not model.startswith(f"{prefix}/"):
+                model = f"{prefix}/{model}"
+            return model
+
+        # Standard mode: auto-prefix for known providers
+        spec = find_by_model(model)
+        if spec and spec.litellm_prefix:
+            model = self._canonicalize_explicit_prefix(model, spec.name, spec.litellm_prefix)
+            if not any(model.startswith(s) for s in spec.skip_prefixes):
+                model = f"{spec.litellm_prefix}/{model}"
+
+        return model
+
+    @staticmethod
+    def _canonicalize_explicit_prefix(model: str, spec_name: str, canonical_prefix: str) -> str:
+        """Normalize explicit provider prefixes like `github-copilot/...`."""
+        if "/" not in model:
+            return model
+        prefix, remainder = model.split("/", 1)
+        if prefix.lower().replace("-", "_") != spec_name:
+            return model
+        return f"{canonical_prefix}/{remainder}"
+
+    def _supports_cache_control(self, model: str) -> bool:
+        """Return True when the provider supports cache_control on content blocks."""
+        if self._gateway is not None:
+            return self._gateway.supports_prompt_caching
+        spec = find_by_model(model)
+        return spec is not None and spec.supports_prompt_caching
+
+    def _apply_cache_control(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None,
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]] | None]:
+        """Return copies of messages and tools with cache_control injected."""
+        new_messages = []
+        for msg in messages:
+            if msg.get("role") == "system":
+                content = msg["content"]
+                if isinstance(content, str):
+                    new_content = [{"type": "text", "text": content, "cache_control": {"type": "ephemeral"}}]
+                else:
+                    new_content = list(content)
+                    new_content[-1] = {**new_content[-1], "cache_control": {"type": "ephemeral"}}
+                new_messages.append({**msg, "content": new_content})
+            else:
+                new_messages.append(msg)
+
+        new_tools = tools
+        if tools:
+            new_tools = list(tools)
+            new_tools[-1] = {**new_tools[-1], "cache_control": {"type": "ephemeral"}}
+
+        return new_messages, new_tools
+
+    def _apply_model_overrides(self, model: str, kwargs: dict[str, Any]) -> None:
+        """Apply model-specific parameter overrides from the registry."""
+        model_lower = model.lower()
+        spec = find_by_model(model)
+        if spec:
+            for pattern, overrides in spec.model_overrides:
+                if pattern in model_lower:
+                    kwargs.update(overrides)
+                    return
+
+    @staticmethod
+    def _extra_msg_keys(original_model: str, resolved_model: str) -> frozenset[str]:
+        """Return provider-specific extra keys to preserve in request messages."""
+        spec = find_by_model(original_model) or find_by_model(resolved_model)
+        if (spec and spec.name == "anthropic") or "claude" in original_model.lower() or resolved_model.startswith("anthropic/"):
+            return _ANTHROPIC_EXTRA_KEYS
+        return frozenset()
+
+    @staticmethod
+    def _normalize_tool_call_id(tool_call_id: Any) -> Any:
+        """Normalize tool_call_id to a provider-safe 9-char alphanumeric form."""
+        if not isinstance(tool_call_id, str):
+            return tool_call_id
+        if len(tool_call_id) == 9 and tool_call_id.isalnum():
+            return tool_call_id
+        return hashlib.sha1(tool_call_id.encode()).hexdigest()[:9]
+
+    @staticmethod
+    def _sanitize_messages(messages: list[dict[str, Any]], extra_keys: frozenset[str] = frozenset()) -> list[dict[str, Any]]:
+        """Strip non-standard keys and ensure assistant messages have a content key."""
+        allowed = _ALLOWED_MSG_KEYS | extra_keys
+        sanitized = LLMProvider._sanitize_request_messages(messages, allowed)
+        id_map: dict[str, str] = {}
+
+        def map_id(value: Any) -> Any:
+            if not isinstance(value, str):
+                return value
+            return id_map.setdefault(value, LiteLLMProvider._normalize_tool_call_id(value))
+
+        for clean in sanitized:
+            # Keep assistant tool_calls[].id and tool tool_call_id in sync after
+            # shortening, otherwise strict providers reject the broken linkage.
+            if isinstance(clean.get("tool_calls"), list):
+                normalized_tool_calls = []
+                for tc in clean["tool_calls"]:
+                    if not isinstance(tc, dict):
+                        normalized_tool_calls.append(tc)
+                        continue
+                    tc_clean = dict(tc)
+                    tc_clean["id"] = map_id(tc_clean.get("id"))
+                    normalized_tool_calls.append(tc_clean)
+                clean["tool_calls"] = normalized_tool_calls
+
+            if "tool_call_id" in clean and clean["tool_call_id"]:
+                clean["tool_call_id"] = map_id(clean["tool_call_id"])
+        return sanitized
+
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        reasoning_effort: str | None = None,
+    ) -> LLMResponse:
+        """
+        Send a chat completion request via LiteLLM.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'.
+            tools: Optional list of tool definitions in OpenAI format.
+            model: Model identifier (e.g., 'anthropic/claude-sonnet-4-5').
+            max_tokens: Maximum tokens in response.
+            temperature: Sampling temperature.
+
+        Returns:
+            LLMResponse with content and/or tool calls.
+        """
+        original_model = model or self.default_model
+        model = self._resolve_model(original_model)
+        extra_msg_keys = self._extra_msg_keys(original_model, model)
+
+        if self._supports_cache_control(original_model):
+            messages, tools = self._apply_cache_control(messages, tools)
+
+        # Clamp max_tokens to at least 1 — negative or zero values cause
+        # LiteLLM to reject the request with "max_tokens must be at least 1".
+        max_tokens = max(1, max_tokens)
+
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": self._sanitize_messages(self._sanitize_empty_content(messages), extra_keys=extra_msg_keys),
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+        }
+
+        # Apply model-specific overrides (e.g. kimi-k2.5 temperature)
+        self._apply_model_overrides(model, kwargs)
+
+        # Pass api_key directly — more reliable than env vars alone
+        if self.api_key:
+            kwargs["api_key"] = self.api_key
+
+        # Pass api_base for custom endpoints
+        if self.api_base:
+            kwargs["api_base"] = self.api_base
+
+        # Pass extra headers (e.g. APP-Code for AiHubMix)
+        if self.extra_headers:
+            kwargs["extra_headers"] = self.extra_headers
+        
+        if reasoning_effort:
+            kwargs["reasoning_effort"] = reasoning_effort
+            kwargs["drop_params"] = True
+        
+        if tools:
+            kwargs["tools"] = tools
+            kwargs["tool_choice"] = "auto"
+
+        try:
+            response = await acompletion(**kwargs)
+            return self._parse_response(response)
+        except Exception as e:
+            # Return error as content for graceful handling
+            return LLMResponse(
+                content=f"Error calling LLM: {str(e)}",
+                finish_reason="error",
+            )
+
+    def _parse_response(self, response: Any) -> LLMResponse:
+        """Parse LiteLLM response into our standard format."""
+        choice = response.choices[0]
+        message = choice.message
+        content = message.content
+        finish_reason = choice.finish_reason
+
+        # Some providers (e.g. GitHub Copilot) split content and tool_calls
+        # across multiple choices. Merge them so tool_calls are not lost.
+        raw_tool_calls = []
+        for ch in response.choices:
+            msg = ch.message
+            if hasattr(msg, "tool_calls") and msg.tool_calls:
+                raw_tool_calls.extend(msg.tool_calls)
+                if ch.finish_reason in ("tool_calls", "stop"):
+                    finish_reason = ch.finish_reason
+            if not content and msg.content:
+                content = msg.content
+
+        if len(response.choices) > 1:
+            logger.debug("LiteLLM response has {} choices, merged {} tool_calls",
+                         len(response.choices), len(raw_tool_calls))
+
+        tool_calls = []
+        for tc in raw_tool_calls:
+            # Parse arguments from JSON string if needed
+            args = tc.function.arguments
+            if isinstance(args, str):
+                args = json_repair.loads(args)
+
+            provider_specific_fields = getattr(tc, "provider_specific_fields", None) or None
+            function_provider_specific_fields = (
+                getattr(tc.function, "provider_specific_fields", None) or None
+            )
+
+            tool_calls.append(ToolCallRequest(
+                id=_short_tool_id(),
+                name=tc.function.name,
+                arguments=args,
+                provider_specific_fields=provider_specific_fields,
+                function_provider_specific_fields=function_provider_specific_fields,
+            ))
+
+        usage = {}
+        if hasattr(response, "usage") and response.usage:
+            usage = {
+                "prompt_tokens": response.usage.prompt_tokens,
+                "completion_tokens": response.usage.completion_tokens,
+                "total_tokens": response.usage.total_tokens,
+            }
+
+        reasoning_content = getattr(message, "reasoning_content", None) or None
+        thinking_blocks = getattr(message, "thinking_blocks", None) or None
+
+        return LLMResponse(
+            content=content,
+            tool_calls=tool_calls,
+            finish_reason=finish_reason or "stop",
+            usage=usage,
+            reasoning_content=reasoning_content,
+            thinking_blocks=thinking_blocks,
+        )
+
+    def get_default_model(self) -> str:
+        """Get the default model."""
+        return self.default_model
diff --git a/core/nanobot/nanobot/providers/openai_codex_provider.py b/core/nanobot/nanobot/providers/openai_codex_provider.py
new file mode 100644
index 0000000..d04e210
--- /dev/null
+++ b/core/nanobot/nanobot/providers/openai_codex_provider.py
@@ -0,0 +1,316 @@
+"""OpenAI Codex Responses Provider."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from typing import Any, AsyncGenerator
+
+import httpx
+from loguru import logger
+from oauth_cli_kit import get_token as get_codex_token
+
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+DEFAULT_CODEX_URL = "https://chatgpt.com/backend-api/codex/responses"
+DEFAULT_ORIGINATOR = "nanobot"
+
+
+class OpenAICodexProvider(LLMProvider):
+    """Use Codex OAuth to call the Responses API."""
+
+    def __init__(self, default_model: str = "openai-codex/gpt-5.1-codex"):
+        super().__init__(api_key=None, api_base=None)
+        self.default_model = default_model
+
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        reasoning_effort: str | None = None,
+    ) -> LLMResponse:
+        model = model or self.default_model
+        system_prompt, input_items = _convert_messages(messages)
+
+        token = await asyncio.to_thread(get_codex_token)
+        headers = _build_headers(token.account_id, token.access)
+
+        body: dict[str, Any] = {
+            "model": _strip_model_prefix(model),
+            "store": False,
+            "stream": True,
+            "instructions": system_prompt,
+            "input": input_items,
+            "text": {"verbosity": "medium"},
+            "include": ["reasoning.encrypted_content"],
+            "prompt_cache_key": _prompt_cache_key(messages),
+            "tool_choice": "auto",
+            "parallel_tool_calls": True,
+        }
+
+        if reasoning_effort:
+            body["reasoning"] = {"effort": reasoning_effort}
+
+        if tools:
+            body["tools"] = _convert_tools(tools)
+
+        url = DEFAULT_CODEX_URL
+
+        try:
+            try:
+                content, tool_calls, finish_reason = await _request_codex(url, headers, body, verify=True)
+            except Exception as e:
+                if "CERTIFICATE_VERIFY_FAILED" not in str(e):
+                    raise
+                logger.warning("SSL certificate verification failed for Codex API; retrying with verify=False")
+                content, tool_calls, finish_reason = await _request_codex(url, headers, body, verify=False)
+            return LLMResponse(
+                content=content,
+                tool_calls=tool_calls,
+                finish_reason=finish_reason,
+            )
+        except Exception as e:
+            return LLMResponse(
+                content=f"Error calling Codex: {str(e)}",
+                finish_reason="error",
+            )
+
+    def get_default_model(self) -> str:
+        return self.default_model
+
+
+def _strip_model_prefix(model: str) -> str:
+    if model.startswith("openai-codex/") or model.startswith("openai_codex/"):
+        return model.split("/", 1)[1]
+    return model
+
+
+def _build_headers(account_id: str, token: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {token}",
+        "chatgpt-account-id": account_id,
+        "OpenAI-Beta": "responses=experimental",
+        "originator": DEFAULT_ORIGINATOR,
+        "User-Agent": "nanobot (python)",
+        "accept": "text/event-stream",
+        "content-type": "application/json",
+    }
+
+
+async def _request_codex(
+    url: str,
+    headers: dict[str, str],
+    body: dict[str, Any],
+    verify: bool,
+) -> tuple[str, list[ToolCallRequest], str]:
+    async with httpx.AsyncClient(timeout=60.0, verify=verify) as client:
+        async with client.stream("POST", url, headers=headers, json=body) as response:
+            if response.status_code != 200:
+                text = await response.aread()
+                raise RuntimeError(_friendly_error(response.status_code, text.decode("utf-8", "ignore")))
+            return await _consume_sse(response)
+
+
+def _convert_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Convert OpenAI function-calling schema to Codex flat format."""
+    converted: list[dict[str, Any]] = []
+    for tool in tools:
+        fn = (tool.get("function") or {}) if tool.get("type") == "function" else tool
+        name = fn.get("name")
+        if not name:
+            continue
+        params = fn.get("parameters") or {}
+        converted.append({
+            "type": "function",
+            "name": name,
+            "description": fn.get("description") or "",
+            "parameters": params if isinstance(params, dict) else {},
+        })
+    return converted
+
+
+def _convert_messages(messages: list[dict[str, Any]]) -> tuple[str, list[dict[str, Any]]]:
+    system_prompt = ""
+    input_items: list[dict[str, Any]] = []
+
+    for idx, msg in enumerate(messages):
+        role = msg.get("role")
+        content = msg.get("content")
+
+        if role == "system":
+            system_prompt = content if isinstance(content, str) else ""
+            continue
+
+        if role == "user":
+            input_items.append(_convert_user_message(content))
+            continue
+
+        if role == "assistant":
+            # Handle text first.
+            if isinstance(content, str) and content:
+                input_items.append(
+                    {
+                        "type": "message",
+                        "role": "assistant",
+                        "content": [{"type": "output_text", "text": content}],
+                        "status": "completed",
+                        "id": f"msg_{idx}",
+                    }
+                )
+            # Then handle tool calls.
+            for tool_call in msg.get("tool_calls", []) or []:
+                fn = tool_call.get("function") or {}
+                call_id, item_id = _split_tool_call_id(tool_call.get("id"))
+                call_id = call_id or f"call_{idx}"
+                item_id = item_id or f"fc_{idx}"
+                input_items.append(
+                    {
+                        "type": "function_call",
+                        "id": item_id,
+                        "call_id": call_id,
+                        "name": fn.get("name"),
+                        "arguments": fn.get("arguments") or "{}",
+                    }
+                )
+            continue
+
+        if role == "tool":
+            call_id, _ = _split_tool_call_id(msg.get("tool_call_id"))
+            output_text = content if isinstance(content, str) else json.dumps(content, ensure_ascii=False)
+            input_items.append(
+                {
+                    "type": "function_call_output",
+                    "call_id": call_id,
+                    "output": output_text,
+                }
+            )
+            continue
+
+    return system_prompt, input_items
+
+
+def _convert_user_message(content: Any) -> dict[str, Any]:
+    if isinstance(content, str):
+        return {"role": "user", "content": [{"type": "input_text", "text": content}]}
+    if isinstance(content, list):
+        converted: list[dict[str, Any]] = []
+        for item in content:
+            if not isinstance(item, dict):
+                continue
+            if item.get("type") == "text":
+                converted.append({"type": "input_text", "text": item.get("text", "")})
+            elif item.get("type") == "image_url":
+                url = (item.get("image_url") or {}).get("url")
+                if url:
+                    converted.append({"type": "input_image", "image_url": url, "detail": "auto"})
+        if converted:
+            return {"role": "user", "content": converted}
+    return {"role": "user", "content": [{"type": "input_text", "text": ""}]}
+
+
+def _split_tool_call_id(tool_call_id: Any) -> tuple[str, str | None]:
+    if isinstance(tool_call_id, str) and tool_call_id:
+        if "|" in tool_call_id:
+            call_id, item_id = tool_call_id.split("|", 1)
+            return call_id, item_id or None
+        return tool_call_id, None
+    return "call_0", None
+
+
+def _prompt_cache_key(messages: list[dict[str, Any]]) -> str:
+    raw = json.dumps(messages, ensure_ascii=True, sort_keys=True)
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+async def _iter_sse(response: httpx.Response) -> AsyncGenerator[dict[str, Any], None]:
+    buffer: list[str] = []
+    async for line in response.aiter_lines():
+        if line == "":
+            if buffer:
+                data_lines = [l[5:].strip() for l in buffer if l.startswith("data:")]
+                buffer = []
+                if not data_lines:
+                    continue
+                data = "\n".join(data_lines).strip()
+                if not data or data == "[DONE]":
+                    continue
+                try:
+                    yield json.loads(data)
+                except Exception:
+                    continue
+            continue
+        buffer.append(line)
+
+
+async def _consume_sse(response: httpx.Response) -> tuple[str, list[ToolCallRequest], str]:
+    content = ""
+    tool_calls: list[ToolCallRequest] = []
+    tool_call_buffers: dict[str, dict[str, Any]] = {}
+    finish_reason = "stop"
+
+    async for event in _iter_sse(response):
+        event_type = event.get("type")
+        if event_type == "response.output_item.added":
+            item = event.get("item") or {}
+            if item.get("type") == "function_call":
+                call_id = item.get("call_id")
+                if not call_id:
+                    continue
+                tool_call_buffers[call_id] = {
+                    "id": item.get("id") or "fc_0",
+                    "name": item.get("name"),
+                    "arguments": item.get("arguments") or "",
+                }
+        elif event_type == "response.output_text.delta":
+            content += event.get("delta") or ""
+        elif event_type == "response.function_call_arguments.delta":
+            call_id = event.get("call_id")
+            if call_id and call_id in tool_call_buffers:
+                tool_call_buffers[call_id]["arguments"] += event.get("delta") or ""
+        elif event_type == "response.function_call_arguments.done":
+            call_id = event.get("call_id")
+            if call_id and call_id in tool_call_buffers:
+                tool_call_buffers[call_id]["arguments"] = event.get("arguments") or ""
+        elif event_type == "response.output_item.done":
+            item = event.get("item") or {}
+            if item.get("type") == "function_call":
+                call_id = item.get("call_id")
+                if not call_id:
+                    continue
+                buf = tool_call_buffers.get(call_id) or {}
+                args_raw = buf.get("arguments") or item.get("arguments") or "{}"
+                try:
+                    args = json.loads(args_raw)
+                except Exception:
+                    args = {"raw": args_raw}
+                tool_calls.append(
+                    ToolCallRequest(
+                        id=f"{call_id}|{buf.get('id') or item.get('id') or 'fc_0'}",
+                        name=buf.get("name") or item.get("name"),
+                        arguments=args,
+                    )
+                )
+        elif event_type == "response.completed":
+            status = (event.get("response") or {}).get("status")
+            finish_reason = _map_finish_reason(status)
+        elif event_type in {"error", "response.failed"}:
+            raise RuntimeError("Codex response failed")
+
+    return content, tool_calls, finish_reason
+
+
+_FINISH_REASON_MAP = {"completed": "stop", "incomplete": "length", "failed": "error", "cancelled": "error"}
+
+
+def _map_finish_reason(status: str | None) -> str:
+    return _FINISH_REASON_MAP.get(status or "completed", "stop")
+
+
+def _friendly_error(status_code: int, raw: str) -> str:
+    if status_code == 429:
+        return "ChatGPT usage quota exceeded or rate limit triggered. Please try again later."
+    return f"HTTP {status_code}: {raw}"
diff --git a/core/nanobot/nanobot/providers/registry.py b/core/nanobot/nanobot/providers/registry.py
new file mode 100644
index 0000000..c4bcfe2
--- /dev/null
+++ b/core/nanobot/nanobot/providers/registry.py
@@ -0,0 +1,465 @@
+"""
+Provider Registry — single source of truth for LLM provider metadata.
+
+Adding a new provider:
+  1. Add a ProviderSpec to PROVIDERS below.
+  2. Add a field to ProvidersConfig in config/schema.py.
+  Done. Env vars, prefixing, config matching, status display all derive from here.
+
+Order matters — it controls match priority and fallback. Gateways first.
+Every entry writes out all fields so you can copy-paste as a template.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+    """One LLM provider's metadata. See PROVIDERS below for real examples.
+
+    Placeholders in env_extras values:
+      {api_key}  — the user's API key
+      {api_base} — api_base from config, or this spec's default_api_base
+    """
+
+    # identity
+    name: str  # config field name, e.g. "dashscope"
+    keywords: tuple[str, ...]  # model-name keywords for matching (lowercase)
+    env_key: str  # LiteLLM env var, e.g. "DASHSCOPE_API_KEY"
+    display_name: str = ""  # shown in `nanobot status`
+
+    # model prefixing
+    litellm_prefix: str = ""  # "dashscope" → model becomes "dashscope/{model}"
+    skip_prefixes: tuple[str, ...] = ()  # don't prefix if model already starts with these
+
+    # extra env vars, e.g. (("ZHIPUAI_API_KEY", "{api_key}"),)
+    env_extras: tuple[tuple[str, str], ...] = ()
+
+    # gateway / local detection
+    is_gateway: bool = False  # routes any model (OpenRouter, AiHubMix)
+    is_local: bool = False  # local deployment (vLLM, Ollama)
+    detect_by_key_prefix: str = ""  # match api_key prefix, e.g. "sk-or-"
+    detect_by_base_keyword: str = ""  # match substring in api_base URL
+    default_api_base: str = ""  # fallback base URL
+
+    # gateway behavior
+    strip_model_prefix: bool = False  # strip "provider/" before re-prefixing
+
+    # per-model param overrides, e.g. (("kimi-k2.5", {"temperature": 1.0}),)
+    model_overrides: tuple[tuple[str, dict[str, Any]], ...] = ()
+
+    # OAuth-based providers (e.g., OpenAI Codex) don't use API keys
+    is_oauth: bool = False  # if True, uses OAuth flow instead of API key
+
+    # Direct providers bypass LiteLLM entirely (e.g., CustomProvider)
+    is_direct: bool = False
+
+    # Provider supports cache_control on content blocks (e.g. Anthropic prompt caching)
+    supports_prompt_caching: bool = False
+
+    @property
+    def label(self) -> str:
+        return self.display_name or self.name.title()
+
+
+# ---------------------------------------------------------------------------
+# PROVIDERS — the registry. Order = priority. Copy any entry as template.
+# ---------------------------------------------------------------------------
+
+PROVIDERS: tuple[ProviderSpec, ...] = (
+    # === Custom (direct OpenAI-compatible endpoint, bypasses LiteLLM) ======
+    ProviderSpec(
+        name="custom",
+        keywords=(),
+        env_key="",
+        display_name="Custom",
+        litellm_prefix="",
+        is_direct=True,
+    ),
+
+    # === Azure OpenAI (direct API calls with API version 2024-10-21) =====
+    ProviderSpec(
+        name="azure_openai",
+        keywords=("azure", "azure-openai"),
+        env_key="",
+        display_name="Azure OpenAI",
+        litellm_prefix="",
+        is_direct=True,
+    ),
+    # === Gateways (detected by api_key / api_base, not model name) =========
+    # Gateways can route any model, so they win in fallback.
+    # OpenRouter: global gateway, keys start with "sk-or-"
+    ProviderSpec(
+        name="openrouter",
+        keywords=("openrouter",),
+        env_key="OPENROUTER_API_KEY",
+        display_name="OpenRouter",
+        litellm_prefix="openrouter",  # claude-3 → openrouter/claude-3
+        skip_prefixes=(),
+        env_extras=(),
+        is_gateway=True,
+        is_local=False,
+        detect_by_key_prefix="sk-or-",
+        detect_by_base_keyword="openrouter",
+        default_api_base="https://openrouter.ai/api/v1",
+        strip_model_prefix=False,
+        model_overrides=(),
+        supports_prompt_caching=True,
+    ),
+    # AiHubMix: global gateway, OpenAI-compatible interface.
+    # strip_model_prefix=True: it doesn't understand "anthropic/claude-3",
+    # so we strip to bare "claude-3" then re-prefix as "openai/claude-3".
+    ProviderSpec(
+        name="aihubmix",
+        keywords=("aihubmix",),
+        env_key="OPENAI_API_KEY",  # OpenAI-compatible
+        display_name="AiHubMix",
+        litellm_prefix="openai",  # → openai/{model}
+        skip_prefixes=(),
+        env_extras=(),
+        is_gateway=True,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="aihubmix",
+        default_api_base="https://aihubmix.com/v1",
+        strip_model_prefix=True,  # anthropic/claude-3 → claude-3 → openai/claude-3
+        model_overrides=(),
+    ),
+    # SiliconFlow (硅基流动): OpenAI-compatible gateway, model names keep org prefix
+    ProviderSpec(
+        name="siliconflow",
+        keywords=("siliconflow",),
+        env_key="OPENAI_API_KEY",
+        display_name="SiliconFlow",
+        litellm_prefix="openai",
+        skip_prefixes=(),
+        env_extras=(),
+        is_gateway=True,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="siliconflow",
+        default_api_base="https://api.siliconflow.cn/v1",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # VolcEngine (火山引擎): OpenAI-compatible gateway
+    ProviderSpec(
+        name="volcengine",
+        keywords=("volcengine", "volces", "ark"),
+        env_key="OPENAI_API_KEY",
+        display_name="VolcEngine",
+        litellm_prefix="volcengine",
+        skip_prefixes=(),
+        env_extras=(),
+        is_gateway=True,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="volces",
+        default_api_base="https://ark.cn-beijing.volces.com/api/v3",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # === Standard providers (matched by model-name keywords) ===============
+    # Anthropic: LiteLLM recognizes "claude-*" natively, no prefix needed.
+    ProviderSpec(
+        name="anthropic",
+        keywords=("anthropic", "claude"),
+        env_key="ANTHROPIC_API_KEY",
+        display_name="Anthropic",
+        litellm_prefix="",
+        skip_prefixes=(),
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",
+        strip_model_prefix=False,
+        model_overrides=(),
+        supports_prompt_caching=True,
+    ),
+    # OpenAI: LiteLLM recognizes "gpt-*" natively, no prefix needed.
+    ProviderSpec(
+        name="openai",
+        keywords=("openai", "gpt"),
+        env_key="OPENAI_API_KEY",
+        display_name="OpenAI",
+        litellm_prefix="",
+        skip_prefixes=(),
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # OpenAI Codex: uses OAuth, not API key.
+    ProviderSpec(
+        name="openai_codex",
+        keywords=("openai-codex",),
+        env_key="",  # OAuth-based, no API key
+        display_name="OpenAI Codex",
+        litellm_prefix="",  # Not routed through LiteLLM
+        skip_prefixes=(),
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="codex",
+        default_api_base="https://chatgpt.com/backend-api",
+        strip_model_prefix=False,
+        model_overrides=(),
+        is_oauth=True,  # OAuth-based authentication
+    ),
+    # Github Copilot: uses OAuth, not API key.
+    ProviderSpec(
+        name="github_copilot",
+        keywords=("github_copilot", "copilot"),
+        env_key="",  # OAuth-based, no API key
+        display_name="Github Copilot",
+        litellm_prefix="github_copilot",  # github_copilot/model → github_copilot/model
+        skip_prefixes=("github_copilot/",),
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",
+        strip_model_prefix=False,
+        model_overrides=(),
+        is_oauth=True,  # OAuth-based authentication
+    ),
+    # DeepSeek: needs "deepseek/" prefix for LiteLLM routing.
+    ProviderSpec(
+        name="deepseek",
+        keywords=("deepseek",),
+        env_key="DEEPSEEK_API_KEY",
+        display_name="DeepSeek",
+        litellm_prefix="deepseek",  # deepseek-chat → deepseek/deepseek-chat
+        skip_prefixes=("deepseek/",),  # avoid double-prefix
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # Gemini: needs "gemini/" prefix for LiteLLM.
+    ProviderSpec(
+        name="gemini",
+        keywords=("gemini",),
+        env_key="GEMINI_API_KEY",
+        display_name="Gemini",
+        litellm_prefix="gemini",  # gemini-pro → gemini/gemini-pro
+        skip_prefixes=("gemini/",),  # avoid double-prefix
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # Zhipu: LiteLLM uses "zai/" prefix.
+    # Also mirrors key to ZHIPUAI_API_KEY (some LiteLLM paths check that).
+    # skip_prefixes: don't add "zai/" when already routed via gateway.
+    ProviderSpec(
+        name="zhipu",
+        keywords=("zhipu", "glm", "zai"),
+        env_key="ZAI_API_KEY",
+        display_name="Zhipu AI",
+        litellm_prefix="zai",  # glm-4 → zai/glm-4
+        skip_prefixes=("zhipu/", "zai/", "openrouter/", "hosted_vllm/"),
+        env_extras=(("ZHIPUAI_API_KEY", "{api_key}"),),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # DashScope: Qwen models, needs "dashscope/" prefix.
+    ProviderSpec(
+        name="dashscope",
+        keywords=("qwen", "dashscope"),
+        env_key="DASHSCOPE_API_KEY",
+        display_name="DashScope",
+        litellm_prefix="dashscope",  # qwen-max → dashscope/qwen-max
+        skip_prefixes=("dashscope/", "openrouter/"),
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # Moonshot: Kimi models, needs "moonshot/" prefix.
+    # LiteLLM requires MOONSHOT_API_BASE env var to find the endpoint.
+    # Kimi K2.5 API enforces temperature >= 1.0.
+    ProviderSpec(
+        name="moonshot",
+        keywords=("moonshot", "kimi"),
+        env_key="MOONSHOT_API_KEY",
+        display_name="Moonshot",
+        litellm_prefix="moonshot",  # kimi-k2.5 → moonshot/kimi-k2.5
+        skip_prefixes=("moonshot/", "openrouter/"),
+        env_extras=(("MOONSHOT_API_BASE", "{api_base}"),),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="https://api.moonshot.ai/v1",  # intl; use api.moonshot.cn for China
+        strip_model_prefix=False,
+        model_overrides=(("kimi-k2.5", {"temperature": 1.0}),),
+    ),
+    # MiniMax: needs "minimax/" prefix for LiteLLM routing.
+    # Uses OpenAI-compatible API at api.minimax.io/v1.
+    ProviderSpec(
+        name="minimax",
+        keywords=("minimax",),
+        env_key="MINIMAX_API_KEY",
+        display_name="MiniMax",
+        litellm_prefix="minimax",  # MiniMax-M2.1 → minimax/MiniMax-M2.1
+        skip_prefixes=("minimax/", "openrouter/"),
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="https://api.minimax.io/v1",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # === Local deployment (matched by config key, NOT by api_base) =========
+    # vLLM / any OpenAI-compatible local server.
+    # Detected when config key is "vllm" (provider_name="vllm").
+    ProviderSpec(
+        name="vllm",
+        keywords=("vllm",),
+        env_key="HOSTED_VLLM_API_KEY",
+        display_name="vLLM/Local",
+        litellm_prefix="hosted_vllm",  # Llama-3-8B → hosted_vllm/Llama-3-8B
+        skip_prefixes=(),
+        env_extras=(),
+        is_gateway=False,
+        is_local=True,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",  # user must provide in config
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # === Ollama (local, OpenAI-compatible) ===================================
+    ProviderSpec(
+        name="ollama",
+        keywords=("ollama", "nemotron"),
+        env_key="OLLAMA_API_KEY",
+        display_name="Ollama",
+        litellm_prefix="ollama_chat",  # model → ollama_chat/model
+        skip_prefixes=("ollama/", "ollama_chat/"),
+        env_extras=(),
+        is_gateway=False,
+        is_local=True,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="11434",
+        default_api_base="http://localhost:11434",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+    # === Auxiliary (not a primary LLM provider) ============================
+    # Groq: mainly used for Whisper voice transcription, also usable for LLM.
+    # Needs "groq/" prefix for LiteLLM routing. Placed last — it rarely wins fallback.
+    ProviderSpec(
+        name="groq",
+        keywords=("groq",),
+        env_key="GROQ_API_KEY",
+        display_name="Groq",
+        litellm_prefix="groq",  # llama3-8b-8192 → groq/llama3-8b-8192
+        skip_prefixes=("groq/",),  # avoid double-prefix
+        env_extras=(),
+        is_gateway=False,
+        is_local=False,
+        detect_by_key_prefix="",
+        detect_by_base_keyword="",
+        default_api_base="",
+        strip_model_prefix=False,
+        model_overrides=(),
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Lookup helpers
+# ---------------------------------------------------------------------------
+
+
+def find_by_model(model: str) -> ProviderSpec | None:
+    """Match a standard provider by model-name keyword (case-insensitive).
+    Skips gateways/local — those are matched by api_key/api_base instead."""
+    model_lower = model.lower()
+    model_normalized = model_lower.replace("-", "_")
+    model_prefix = model_lower.split("/", 1)[0] if "/" in model_lower else ""
+    normalized_prefix = model_prefix.replace("-", "_")
+    std_specs = [s for s in PROVIDERS if not s.is_gateway and not s.is_local]
+
+    # Prefer explicit provider prefix — prevents `github-copilot/...codex` matching openai_codex.
+    for spec in std_specs:
+        if model_prefix and normalized_prefix == spec.name:
+            return spec
+
+    for spec in std_specs:
+        if any(
+            kw in model_lower or kw.replace("-", "_") in model_normalized for kw in spec.keywords
+        ):
+            return spec
+    return None
+
+
+def find_gateway(
+    provider_name: str | None = None,
+    api_key: str | None = None,
+    api_base: str | None = None,
+) -> ProviderSpec | None:
+    """Detect gateway/local provider.
+
+    Priority:
+      1. provider_name — if it maps to a gateway/local spec, use it directly.
+      2. api_key prefix — e.g. "sk-or-" → OpenRouter.
+      3. api_base keyword — e.g. "aihubmix" in URL → AiHubMix.
+
+    A standard provider with a custom api_base (e.g. DeepSeek behind a proxy)
+    will NOT be mistaken for vLLM — the old fallback is gone.
+    """
+    # 1. Direct match by config key
+    if provider_name:
+        spec = find_by_name(provider_name)
+        if spec and (spec.is_gateway or spec.is_local):
+            return spec
+
+    # 2. Auto-detect by api_key prefix / api_base keyword
+    for spec in PROVIDERS:
+        if spec.detect_by_key_prefix and api_key and api_key.startswith(spec.detect_by_key_prefix):
+            return spec
+        if spec.detect_by_base_keyword and api_base and spec.detect_by_base_keyword in api_base:
+            return spec
+
+    return None
+
+
+def find_by_name(name: str) -> ProviderSpec | None:
+    """Find a provider spec by config field name, e.g. "dashscope"."""
+    for spec in PROVIDERS:
+        if spec.name == name:
+            return spec
+    return None
diff --git a/core/nanobot/nanobot/providers/transcription.py b/core/nanobot/nanobot/providers/transcription.py
new file mode 100644
index 0000000..1c8cb6a
--- /dev/null
+++ b/core/nanobot/nanobot/providers/transcription.py
@@ -0,0 +1,64 @@
+"""Voice transcription provider using Groq."""
+
+import os
+from pathlib import Path
+
+import httpx
+from loguru import logger
+
+
+class GroqTranscriptionProvider:
+    """
+    Voice transcription provider using Groq's Whisper API.
+
+    Groq offers extremely fast transcription with a generous free tier.
+    """
+
+    def __init__(self, api_key: str | None = None):
+        self.api_key = api_key or os.environ.get("GROQ_API_KEY")
+        self.api_url = "https://api.groq.com/openai/v1/audio/transcriptions"
+
+    async def transcribe(self, file_path: str | Path) -> str:
+        """
+        Transcribe an audio file using Groq.
+
+        Args:
+            file_path: Path to the audio file.
+
+        Returns:
+            Transcribed text.
+        """
+        if not self.api_key:
+            logger.warning("Groq API key not configured for transcription")
+            return ""
+
+        path = Path(file_path)
+        if not path.exists():
+            logger.error("Audio file not found: {}", file_path)
+            return ""
+
+        try:
+            async with httpx.AsyncClient() as client:
+                with open(path, "rb") as f:
+                    files = {
+                        "file": (path.name, f),
+                        "model": (None, "whisper-large-v3"),
+                    }
+                    headers = {
+                        "Authorization": f"Bearer {self.api_key}",
+                    }
+
+                    response = await client.post(
+                        self.api_url,
+                        headers=headers,
+                        files=files,
+                        timeout=60.0
+                    )
+
+                    response.raise_for_status()
+                    data = response.json()
+                    return data.get("text", "")
+
+        except Exception as e:
+            logger.error("Groq transcription error: {}", e)
+            return ""
diff --git a/core/nanobot/nanobot/session/__init__.py b/core/nanobot/nanobot/session/__init__.py
new file mode 100644
index 0000000..931f7c6
--- /dev/null
+++ b/core/nanobot/nanobot/session/__init__.py
@@ -0,0 +1,5 @@
+"""Session management module."""
+
+from nanobot.session.manager import Session, SessionManager
+
+__all__ = ["SessionManager", "Session"]
diff --git a/core/nanobot/nanobot/session/manager.py b/core/nanobot/nanobot/session/manager.py
new file mode 100644
index 0000000..f0a6484
--- /dev/null
+++ b/core/nanobot/nanobot/session/manager.py
@@ -0,0 +1,213 @@
+"""Session management for conversation history."""
+
+import json
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from nanobot.config.paths import get_legacy_sessions_dir
+from nanobot.utils.helpers import ensure_dir, safe_filename
+
+
+@dataclass
+class Session:
+    """
+    A conversation session.
+
+    Stores messages in JSONL format for easy reading and persistence.
+
+    Important: Messages are append-only for LLM cache efficiency.
+    The consolidation process writes summaries to MEMORY.md/HISTORY.md
+    but does NOT modify the messages list or get_history() output.
+    """
+
+    key: str  # channel:chat_id
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    last_consolidated: int = 0  # Number of messages already consolidated to files
+
+    def add_message(self, role: str, content: str, **kwargs: Any) -> None:
+        """Add a message to the session."""
+        msg = {
+            "role": role,
+            "content": content,
+            "timestamp": datetime.now().isoformat(),
+            **kwargs
+        }
+        self.messages.append(msg)
+        self.updated_at = datetime.now()
+
+    def get_history(self, max_messages: int = 500) -> list[dict[str, Any]]:
+        """Return unconsolidated messages for LLM input, aligned to a user turn."""
+        unconsolidated = self.messages[self.last_consolidated:]
+        sliced = unconsolidated[-max_messages:]
+
+        # Drop leading non-user messages to avoid orphaned tool_result blocks
+        for i, m in enumerate(sliced):
+            if m.get("role") == "user":
+                sliced = sliced[i:]
+                break
+
+        out: list[dict[str, Any]] = []
+        for m in sliced:
+            entry: dict[str, Any] = {"role": m["role"], "content": m.get("content", "")}
+            for k in ("tool_calls", "tool_call_id", "name"):
+                if k in m:
+                    entry[k] = m[k]
+            out.append(entry)
+        return out
+
+    def clear(self) -> None:
+        """Clear all messages and reset session to initial state."""
+        self.messages = []
+        self.last_consolidated = 0
+        self.updated_at = datetime.now()
+
+
+class SessionManager:
+    """
+    Manages conversation sessions.
+
+    Sessions are stored as JSONL files in the sessions directory.
+    """
+
+    def __init__(self, workspace: Path):
+        self.workspace = workspace
+        self.sessions_dir = ensure_dir(self.workspace / "sessions")
+        self.legacy_sessions_dir = get_legacy_sessions_dir()
+        self._cache: dict[str, Session] = {}
+
+    def _get_session_path(self, key: str) -> Path:
+        """Get the file path for a session."""
+        safe_key = safe_filename(key.replace(":", "_"))
+        return self.sessions_dir / f"{safe_key}.jsonl"
+
+    def _get_legacy_session_path(self, key: str) -> Path:
+        """Legacy global session path (~/.nanobot/sessions/)."""
+        safe_key = safe_filename(key.replace(":", "_"))
+        return self.legacy_sessions_dir / f"{safe_key}.jsonl"
+
+    def get_or_create(self, key: str) -> Session:
+        """
+        Get an existing session or create a new one.
+
+        Args:
+            key: Session key (usually channel:chat_id).
+
+        Returns:
+            The session.
+        """
+        if key in self._cache:
+            return self._cache[key]
+
+        session = self._load(key)
+        if session is None:
+            session = Session(key=key)
+
+        self._cache[key] = session
+        return session
+
+    def _load(self, key: str) -> Session | None:
+        """Load a session from disk."""
+        path = self._get_session_path(key)
+        if not path.exists():
+            legacy_path = self._get_legacy_session_path(key)
+            if legacy_path.exists():
+                try:
+                    shutil.move(str(legacy_path), str(path))
+                    logger.info("Migrated session {} from legacy path", key)
+                except Exception:
+                    logger.exception("Failed to migrate session {}", key)
+
+        if not path.exists():
+            return None
+
+        try:
+            messages = []
+            metadata = {}
+            created_at = None
+            last_consolidated = 0
+
+            with open(path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+
+                    data = json.loads(line)
+
+                    if data.get("_type") == "metadata":
+                        metadata = data.get("metadata", {})
+                        created_at = datetime.fromisoformat(data["created_at"]) if data.get("created_at") else None
+                        last_consolidated = data.get("last_consolidated", 0)
+                    else:
+                        messages.append(data)
+
+            return Session(
+                key=key,
+                messages=messages,
+                created_at=created_at or datetime.now(),
+                metadata=metadata,
+                last_consolidated=last_consolidated
+            )
+        except Exception as e:
+            logger.warning("Failed to load session {}: {}", key, e)
+            return None
+
+    def save(self, session: Session) -> None:
+        """Save a session to disk."""
+        path = self._get_session_path(session.key)
+
+        with open(path, "w", encoding="utf-8") as f:
+            metadata_line = {
+                "_type": "metadata",
+                "key": session.key,
+                "created_at": session.created_at.isoformat(),
+                "updated_at": session.updated_at.isoformat(),
+                "metadata": session.metadata,
+                "last_consolidated": session.last_consolidated
+            }
+            f.write(json.dumps(metadata_line, ensure_ascii=False) + "\n")
+            for msg in session.messages:
+                f.write(json.dumps(msg, ensure_ascii=False) + "\n")
+
+        self._cache[session.key] = session
+
+    def invalidate(self, key: str) -> None:
+        """Remove a session from the in-memory cache."""
+        self._cache.pop(key, None)
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """
+        List all sessions.
+
+        Returns:
+            List of session info dicts.
+        """
+        sessions = []
+
+        for path in self.sessions_dir.glob("*.jsonl"):
+            try:
+                # Read just the metadata line
+                with open(path, encoding="utf-8") as f:
+                    first_line = f.readline().strip()
+                    if first_line:
+                        data = json.loads(first_line)
+                        if data.get("_type") == "metadata":
+                            key = data.get("key") or path.stem.replace("_", ":", 1)
+                            sessions.append({
+                                "key": key,
+                                "created_at": data.get("created_at"),
+                                "updated_at": data.get("updated_at"),
+                                "path": str(path)
+                            })
+            except Exception:
+                continue
+
+        return sorted(sessions, key=lambda x: x.get("updated_at", ""), reverse=True)
diff --git a/core/nanobot/nanobot/skills/README.md b/core/nanobot/nanobot/skills/README.md
new file mode 100644
index 0000000..5192796
--- /dev/null
+++ b/core/nanobot/nanobot/skills/README.md
@@ -0,0 +1,25 @@
+# nanobot Skills
+
+This directory contains built-in skills that extend nanobot's capabilities.
+
+## Skill Format
+
+Each skill is a directory containing a `SKILL.md` file with:
+- YAML frontmatter (name, description, metadata)
+- Markdown instructions for the agent
+
+## Attribution
+
+These skills are adapted from [OpenClaw](https://github.com/openclaw/openclaw)'s skill system.
+The skill format and metadata structure follow OpenClaw's conventions to maintain compatibility.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `github` | Interact with GitHub using the `gh` CLI |
+| `weather` | Get weather info using wttr.in and Open-Meteo |
+| `summarize` | Summarize URLs, files, and YouTube videos |
+| `tmux` | Remote-control tmux sessions |
+| `clawhub` | Search and install skills from ClawHub registry |
+| `skill-creator` | Create new skills |
\ No newline at end of file
diff --git a/core/nanobot/nanobot/skills/clawhub/SKILL.md b/core/nanobot/nanobot/skills/clawhub/SKILL.md
new file mode 100644
index 0000000..7409bf4
--- /dev/null
+++ b/core/nanobot/nanobot/skills/clawhub/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: clawhub
+description: Search and install agent skills from ClawHub, the public skill registry.
+homepage: https://clawhub.ai
+metadata: {"nanobot":{"emoji":"🦞"}}
+---
+
+# ClawHub
+
+Public skill registry for AI agents. Search by natural language (vector search).
+
+## When to use
+
+Use this skill when the user asks any of:
+- "find a skill for …"
+- "search for skills"
+- "install a skill"
+- "what skills are available?"
+- "update my skills"
+
+## Search
+
+```bash
+npx --yes clawhub@latest search "web scraping" --limit 5
+```
+
+## Install
+
+```bash
+npx --yes clawhub@latest install  --workdir ~/.nanobot/workspace
+```
+
+Replace `` with the skill name from search results. This places the skill into `~/.nanobot/workspace/skills/`, where nanobot loads workspace skills from. Always include `--workdir`.
+
+## Update
+
+```bash
+npx --yes clawhub@latest update --all --workdir ~/.nanobot/workspace
+```
+
+## List installed
+
+```bash
+npx --yes clawhub@latest list --workdir ~/.nanobot/workspace
+```
+
+## Notes
+
+- Requires Node.js (`npx` comes with it).
+- No API key needed for search and install.
+- Login (`npx --yes clawhub@latest login`) is only required for publishing.
+- `--workdir ~/.nanobot/workspace` is critical — without it, skills install to the current directory instead of the nanobot workspace.
+- After install, remind the user to start a new session to load the skill.
diff --git a/core/nanobot/nanobot/skills/cron/SKILL.md b/core/nanobot/nanobot/skills/cron/SKILL.md
new file mode 100644
index 0000000..cc3516e
--- /dev/null
+++ b/core/nanobot/nanobot/skills/cron/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: cron
+description: Schedule reminders and recurring tasks.
+---
+
+# Cron
+
+Use the `cron` tool to schedule reminders or recurring tasks.
+
+## Three Modes
+
+1. **Reminder** - message is sent directly to user
+2. **Task** - message is a task description, agent executes and sends result
+3. **One-time** - runs once at a specific time, then auto-deletes
+
+## Examples
+
+Fixed reminder:
+```
+cron(action="add", message="Time to take a break!", every_seconds=1200)
+```
+
+Dynamic task (agent executes each time):
+```
+cron(action="add", message="Check HKUDS/nanobot GitHub stars and report", every_seconds=600)
+```
+
+One-time scheduled task (compute ISO datetime from current time):
+```
+cron(action="add", message="Remind me about the meeting", at="")
+```
+
+Timezone-aware cron:
+```
+cron(action="add", message="Morning standup", cron_expr="0 9 * * 1-5", tz="America/Vancouver")
+```
+
+List/remove:
+```
+cron(action="list")
+cron(action="remove", job_id="abc123")
+```
+
+## Time Expressions
+
+| User says | Parameters |
+|-----------|------------|
+| every 20 minutes | every_seconds: 1200 |
+| every hour | every_seconds: 3600 |
+| every day at 8am | cron_expr: "0 8 * * *" |
+| weekdays at 5pm | cron_expr: "0 17 * * 1-5" |
+| 9am Vancouver time daily | cron_expr: "0 9 * * *", tz: "America/Vancouver" |
+| at a specific time | at: ISO datetime string (compute from current time) |
+
+## Timezone
+
+Use `tz` with `cron_expr` to schedule in a specific IANA timezone. Without `tz`, the server's local timezone is used.
diff --git a/core/nanobot/nanobot/skills/github/SKILL.md b/core/nanobot/nanobot/skills/github/SKILL.md
new file mode 100644
index 0000000..57d8127
--- /dev/null
+++ b/core/nanobot/nanobot/skills/github/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: github
+description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
+metadata: {"nanobot":{"emoji":"🐙","requires":{"bins":["gh"]},"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install GitHub CLI (brew)"},{"id":"apt","kind":"apt","package":"gh","bins":["gh"],"label":"Install GitHub CLI (apt)"}]}}
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.
+
+## Pull Requests
+
+Check CI status on a PR:
+```bash
+gh pr checks 55 --repo owner/repo
+```
+
+List recent workflow runs:
+```bash
+gh run list --repo owner/repo --limit 10
+```
+
+View a run and see which steps failed:
+```bash
+gh run view  --repo owner/repo
+```
+
+View logs for failed steps only:
+```bash
+gh run view  --repo owner/repo --log-failed
+```
+
+## API for Advanced Queries
+
+The `gh api` command is useful for accessing data not available through other subcommands.
+
+Get PR with specific fields:
+```bash
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output.  You can use `--jq` to filter:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+```
diff --git a/core/nanobot/nanobot/skills/memory/SKILL.md b/core/nanobot/nanobot/skills/memory/SKILL.md
new file mode 100644
index 0000000..3f0a8fc
--- /dev/null
+++ b/core/nanobot/nanobot/skills/memory/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: memory
+description: Two-layer memory system with grep-based recall.
+always: true
+---
+
+# Memory
+
+## Structure
+
+- `memory/MEMORY.md` — Long-term facts (preferences, project context, relationships). Always loaded into your context.
+- `memory/HISTORY.md` — Append-only event log. NOT loaded into context. Search it with grep-style tools or in-memory filters. Each entry starts with [YYYY-MM-DD HH:MM].
+
+## Search Past Events
+
+Choose the search method based on file size:
+
+- Small `memory/HISTORY.md`: use `read_file`, then search in-memory
+- Large or long-lived `memory/HISTORY.md`: use the `exec` tool for targeted search
+
+Examples:
+- **Linux/macOS:** `grep -i "keyword" memory/HISTORY.md`
+- **Windows:** `findstr /i "keyword" memory\HISTORY.md`
+- **Cross-platform Python:** `python -c "from pathlib import Path; text = Path('memory/HISTORY.md').read_text(encoding='utf-8'); print('\n'.join([l for l in text.splitlines() if 'keyword' in l.lower()][-20:]))"`
+
+Prefer targeted command-line search for large history files.
+
+## When to Update MEMORY.md
+
+Write important facts immediately using `edit_file` or `write_file`:
+- User preferences ("I prefer dark mode")
+- Project context ("The API uses OAuth2")
+- Relationships ("Alice is the project lead")
+
+## Auto-consolidation
+
+Old conversations are automatically summarized and appended to HISTORY.md when the session grows large. Long-term facts are extracted to MEMORY.md. You don't need to manage this.
diff --git a/core/nanobot/nanobot/skills/skill-creator/SKILL.md b/core/nanobot/nanobot/skills/skill-creator/SKILL.md
new file mode 100644
index 0000000..ea53abe
--- /dev/null
+++ b/core/nanobot/nanobot/skills/skill-creator/SKILL.md
@@ -0,0 +1,374 @@
+---
+name: skill-creator
+description: Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend the agent's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform the agent from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: the agent is already very smart.** Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of the agent as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that the agent reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by the agent for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform the agent's process and thinking.
+
+- **When to include**: For documentation that the agent should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when the agent determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output the agent produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables the agent to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by the agent (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+the agent loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, the agent only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+    ├── aws.md (AWS deployment patterns)
+    ├── gcp.md (GCP deployment patterns)
+    └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, the agent only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+the agent reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so the agent can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Skill Naming
+
+- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
+- When generating names, generate a name under 64 characters (letters, digits, hyphens).
+- Prefer short, verb-led phrases that describe the action.
+- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
+- Name the skill folder exactly after the skill name.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+For `nanobot`, custom skills should live under the active workspace `skills/` directory so they can be discovered automatically at runtime (for example, `/skills/my-skill/SKILL.md`).
+
+Usage:
+
+```bash
+scripts/init_skill.py  --path  [--resources scripts,references,assets] [--examples]
+```
+
+Examples:
+
+```bash
+scripts/init_skill.py my-skill --path ./workspace/skills
+scripts/init_skill.py my-skill --path ./workspace/skills --resources scripts,references
+scripts/init_skill.py my-skill --path ./workspace/skills --resources scripts --examples
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Optionally creates resource directories based on `--resources`
+- Optionally adds example files when `--examples` is set
+
+After initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of the agent to use. Include information that would be beneficial and non-obvious to the agent. Consider what procedural knowledge, domain-specific details, or reusable assets would help another the agent instance execute these tasks more effectively.
+
+#### Learn Proven Design Patterns
+
+Consult these helpful guides based on your skill's needs:
+
+- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
+- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
+
+These files contain established best practices for effective skill design.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+If you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps the agent understand when to use the skill.
+  - Include both what the Skill does and specific triggers/contexts for when to use it.
+  - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to the agent.
+  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the agent needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Keep frontmatter minimal. In `nanobot`, `metadata` and `always` are also supported when needed, but avoid adding extra fields unless they are actually required.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py 
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py  ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+   - YAML frontmatter format and required fields
+   - Skill naming conventions and directory structure
+   - Description completeness and quality
+   - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+   Security restriction: symlinks are rejected and packaging fails when any symlink is present.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again
diff --git a/core/nanobot/nanobot/skills/skill-creator/scripts/init_skill.py b/core/nanobot/nanobot/skills/skill-creator/scripts/init_skill.py
new file mode 100644
index 0000000..8633fe9
--- /dev/null
+++ b/core/nanobot/nanobot/skills/skill-creator/scripts/init_skill.py
@@ -0,0 +1,378 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py  --path  [--resources scripts,references,assets] [--examples]
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-new-skill --path skills/public --resources scripts,references
+    init_skill.py my-api-helper --path skills/private --resources scripts --examples
+    init_skill.py custom-skill --path /custom/location
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+MAX_SKILL_NAME_LENGTH = 64
+ALLOWED_RESOURCES = {"scripts", "references", "assets"}
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" -> "Reading" -> "Creating" -> "Editing"
+- Structure: ## Overview -> ## Workflow Decision Tree -> ## Step 1 -> ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" -> "Merge PDFs" -> "Split PDFs" -> "Extract Text"
+- Structure: ## Overview -> ## Quick Start -> ## Task Category 1 -> ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" -> "Colors" -> "Typography" -> "Features"
+- Structure: ## Overview -> ## Guidelines -> ## Specifications -> ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" -> numbered capability list
+- Structure: ## Overview -> ## Core Capabilities -> ### 1. Feature -> ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources (optional)
+
+Create only the resource directories this skill actually needs. Delete this section if no resources are required.
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Codex for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Codex's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Codex should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Codex produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Not every skill requires all three types of resources.**
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+    # TODO: Add actual script logic here
+    # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Codex produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def normalize_skill_name(skill_name):
+    """Normalize a skill name to lowercase hyphen-case."""
+    normalized = skill_name.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = normalized.strip("-")
+    normalized = re.sub(r"-{2,}", "-", normalized)
+    return normalized
+
+
+def title_case_skill_name(skill_name):
+    """Convert hyphenated skill name to Title Case for display."""
+    return " ".join(word.capitalize() for word in skill_name.split("-"))
+
+
+def parse_resources(raw_resources):
+    if not raw_resources:
+        return []
+    resources = [item.strip() for item in raw_resources.split(",") if item.strip()]
+    invalid = sorted({item for item in resources if item not in ALLOWED_RESOURCES})
+    if invalid:
+        allowed = ", ".join(sorted(ALLOWED_RESOURCES))
+        print(f"[ERROR] Unknown resource type(s): {', '.join(invalid)}")
+        print(f"   Allowed: {allowed}")
+        sys.exit(1)
+    deduped = []
+    seen = set()
+    for resource in resources:
+        if resource not in seen:
+            deduped.append(resource)
+            seen.add(resource)
+    return deduped
+
+
+def create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples):
+    for resource in resources:
+        resource_dir = skill_dir / resource
+        resource_dir.mkdir(exist_ok=True)
+        if resource == "scripts":
+            if include_examples:
+                example_script = resource_dir / "example.py"
+                example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+                example_script.chmod(0o755)
+                print("[OK] Created scripts/example.py")
+            else:
+                print("[OK] Created scripts/")
+        elif resource == "references":
+            if include_examples:
+                example_reference = resource_dir / "api_reference.md"
+                example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+                print("[OK] Created references/api_reference.md")
+            else:
+                print("[OK] Created references/")
+        elif resource == "assets":
+            if include_examples:
+                example_asset = resource_dir / "example_asset.txt"
+                example_asset.write_text(EXAMPLE_ASSET)
+                print("[OK] Created assets/example_asset.txt")
+            else:
+                print("[OK] Created assets/")
+
+
+def init_skill(skill_name, path, resources, include_examples):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+        resources: Resource directories to create
+        include_examples: Whether to create example files in resource directories
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    # Determine skill directory path
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        print(f"[ERROR] Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create skill directory
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=False)
+        print(f"[OK] Created skill directory: {skill_dir}")
+    except Exception as e:
+        print(f"[ERROR] Error creating directory: {e}")
+        return None
+
+    # Create SKILL.md from template
+    skill_title = title_case_skill_name(skill_name)
+    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)
+
+    skill_md_path = skill_dir / "SKILL.md"
+    try:
+        skill_md_path.write_text(skill_content)
+        print("[OK] Created SKILL.md")
+    except Exception as e:
+        print(f"[ERROR] Error creating SKILL.md: {e}")
+        return None
+
+    # Create resource directories if requested
+    if resources:
+        try:
+            create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples)
+        except Exception as e:
+            print(f"[ERROR] Error creating resource directories: {e}")
+            return None
+
+    # Print next steps
+    print(f"\n[OK] Skill '{skill_name}' initialized successfully at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md to complete the TODO items and update the description")
+    if resources:
+        if include_examples:
+            print("2. Customize or delete the example files in scripts/, references/, and assets/")
+        else:
+            print("2. Add resources to scripts/, references/, and assets/ as needed")
+    else:
+        print("2. Create resource directories only if needed (scripts/, references/, assets/)")
+    print("3. Run the validator when ready to check the skill structure")
+
+    return skill_dir
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create a new skill directory with a SKILL.md template.",
+    )
+    parser.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
+    parser.add_argument("--path", required=True, help="Output directory for the skill")
+    parser.add_argument(
+        "--resources",
+        default="",
+        help="Comma-separated list: scripts,references,assets",
+    )
+    parser.add_argument(
+        "--examples",
+        action="store_true",
+        help="Create example files inside the selected resource directories",
+    )
+    args = parser.parse_args()
+
+    raw_skill_name = args.skill_name
+    skill_name = normalize_skill_name(raw_skill_name)
+    if not skill_name:
+        print("[ERROR] Skill name must include at least one letter or digit.")
+        sys.exit(1)
+    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
+        print(
+            f"[ERROR] Skill name '{skill_name}' is too long ({len(skill_name)} characters). "
+            f"Maximum is {MAX_SKILL_NAME_LENGTH} characters."
+        )
+        sys.exit(1)
+    if skill_name != raw_skill_name:
+        print(f"Note: Normalized skill name from '{raw_skill_name}' to '{skill_name}'.")
+
+    resources = parse_resources(args.resources)
+    if args.examples and not resources:
+        print("[ERROR] --examples requires --resources to be set.")
+        sys.exit(1)
+
+    path = args.path
+
+    print(f"Initializing skill: {skill_name}")
+    print(f"   Location: {path}")
+    if resources:
+        print(f"   Resources: {', '.join(resources)}")
+        if args.examples:
+            print("   Examples: enabled")
+    else:
+        print("   Resources: none (create as needed)")
+    print()
+
+    result = init_skill(skill_name, path, resources, args.examples)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/core/nanobot/nanobot/skills/skill-creator/scripts/package_skill.py b/core/nanobot/nanobot/skills/skill-creator/scripts/package_skill.py
new file mode 100644
index 0000000..48fcbbe
--- /dev/null
+++ b/core/nanobot/nanobot/skills/skill-creator/scripts/package_skill.py
@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+    python package_skill.py  [output-directory]
+
+Example:
+    python package_skill.py skills/public/my-skill
+    python package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+
+from quick_validate import validate_skill
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def _cleanup_partial_archive(skill_filename: Path) -> None:
+    try:
+        if skill_filename.exists():
+            skill_filename.unlink()
+    except OSError:
+        pass
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the .skill file (defaults to current directory)
+
+    Returns:
+        Path to the created .skill file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        print(f"[ERROR] Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"[ERROR] Path is not a directory: {skill_path}")
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"[ERROR] SKILL.md not found in {skill_path}")
+        return None
+
+    # Run validation before packaging
+    print("Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"[ERROR] Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"[OK] {message}\n")
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    skill_filename = output_path / f"{skill_name}.skill"
+
+    EXCLUDED_DIRS = {".git", ".svn", ".hg", "__pycache__", "node_modules"}
+
+    files_to_package = []
+    resolved_archive = skill_filename.resolve()
+
+    for file_path in skill_path.rglob("*"):
+        # Fail closed on symlinks so the packaged contents are explicit and predictable.
+        if file_path.is_symlink():
+            print(f"[ERROR] Symlink not allowed in packaged skill: {file_path}")
+            _cleanup_partial_archive(skill_filename)
+            return None
+
+        rel_parts = file_path.relative_to(skill_path).parts
+        if any(part in EXCLUDED_DIRS for part in rel_parts):
+            continue
+
+        if file_path.is_file():
+            resolved_file = file_path.resolve()
+            if not _is_within(resolved_file, skill_path):
+                print(f"[ERROR] File escapes skill root: {file_path}")
+                _cleanup_partial_archive(skill_filename)
+                return None
+            # If output lives under skill_path, avoid writing archive into itself.
+            if resolved_file == resolved_archive:
+                print(f"[WARN] Skipping output archive: {file_path}")
+                continue
+            files_to_package.append(file_path)
+
+    # Create the .skill file (zip format)
+    try:
+        with zipfile.ZipFile(skill_filename, "w", zipfile.ZIP_DEFLATED) as zipf:
+            for file_path in files_to_package:
+                # Calculate the relative path within the zip.
+                arcname = Path(skill_name) / file_path.relative_to(skill_path)
+                zipf.write(file_path, arcname)
+                print(f"  Added: {arcname}")
+
+        print(f"\n[OK] Successfully packaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        _cleanup_partial_archive(skill_filename)
+        print(f"[ERROR] Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python package_skill.py  [output-directory]")
+        print("\nExample:")
+        print("  python package_skill.py skills/public/my-skill")
+        print("  python package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/core/nanobot/nanobot/skills/skill-creator/scripts/quick_validate.py b/core/nanobot/nanobot/skills/skill-creator/scripts/quick_validate.py
new file mode 100644
index 0000000..03d246d
--- /dev/null
+++ b/core/nanobot/nanobot/skills/skill-creator/scripts/quick_validate.py
@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+Minimal validator for nanobot skill folders.
+"""
+
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    import yaml
+except ModuleNotFoundError:
+    yaml = None
+
+MAX_SKILL_NAME_LENGTH = 64
+ALLOWED_FRONTMATTER_KEYS = {
+    "name",
+    "description",
+    "metadata",
+    "always",
+    "license",
+    "allowed-tools",
+}
+ALLOWED_RESOURCE_DIRS = {"scripts", "references", "assets"}
+PLACEHOLDER_MARKERS = ("[todo", "todo:")
+
+
+def _extract_frontmatter(content: str) -> Optional[str]:
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            return "\n".join(lines[1:i])
+    return None
+
+
+def _parse_simple_frontmatter(frontmatter_text: str) -> Optional[dict[str, str]]:
+    """Fallback parser for simple frontmatter when PyYAML is unavailable."""
+    parsed: dict[str, str] = {}
+    current_key: Optional[str] = None
+    multiline_key: Optional[str] = None
+
+    for raw_line in frontmatter_text.splitlines():
+        stripped = raw_line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        is_indented = raw_line[:1].isspace()
+        if is_indented:
+            if current_key is None:
+                return None
+            current_value = parsed[current_key]
+            parsed[current_key] = f"{current_value}\n{stripped}" if current_value else stripped
+            continue
+
+        if ":" not in stripped:
+            return None
+
+        key, value = stripped.split(":", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            return None
+
+        if value in {"|", ">"}:
+            parsed[key] = ""
+            current_key = key
+            multiline_key = key
+            continue
+
+        if (value.startswith('"') and value.endswith('"')) or (
+            value.startswith("'") and value.endswith("'")
+        ):
+            value = value[1:-1]
+        parsed[key] = value
+        current_key = key
+        multiline_key = None
+
+    if multiline_key is not None and multiline_key not in parsed:
+        return None
+    return parsed
+
+
+def _load_frontmatter(frontmatter_text: str) -> tuple[Optional[dict], Optional[str]]:
+    if yaml is not None:
+        try:
+            frontmatter = yaml.safe_load(frontmatter_text)
+        except yaml.YAMLError as exc:
+            return None, f"Invalid YAML in frontmatter: {exc}"
+        if not isinstance(frontmatter, dict):
+            return None, "Frontmatter must be a YAML dictionary"
+        return frontmatter, None
+
+    frontmatter = _parse_simple_frontmatter(frontmatter_text)
+    if frontmatter is None:
+        return None, "Invalid YAML in frontmatter: unsupported syntax without PyYAML installed"
+    return frontmatter, None
+
+
+def _validate_skill_name(name: str, folder_name: str) -> Optional[str]:
+    if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", name):
+        return (
+            f"Name '{name}' should be hyphen-case "
+            "(lowercase letters, digits, and single hyphens only)"
+        )
+    if len(name) > MAX_SKILL_NAME_LENGTH:
+        return (
+            f"Name is too long ({len(name)} characters). "
+            f"Maximum is {MAX_SKILL_NAME_LENGTH} characters."
+        )
+    if name != folder_name:
+        return f"Skill name '{name}' must match directory name '{folder_name}'"
+    return None
+
+
+def _validate_description(description: str) -> Optional[str]:
+    trimmed = description.strip()
+    if not trimmed:
+        return "Description cannot be empty"
+    lowered = trimmed.lower()
+    if any(marker in lowered for marker in PLACEHOLDER_MARKERS):
+        return "Description still contains TODO placeholder text"
+    if "<" in trimmed or ">" in trimmed:
+        return "Description cannot contain angle brackets (< or >)"
+    if len(trimmed) > 1024:
+        return f"Description is too long ({len(trimmed)} characters). Maximum is 1024 characters."
+    return None
+
+
+def validate_skill(skill_path):
+    """Validate a skill folder structure and required frontmatter."""
+    skill_path = Path(skill_path).resolve()
+
+    if not skill_path.exists():
+        return False, f"Skill folder not found: {skill_path}"
+    if not skill_path.is_dir():
+        return False, f"Path is not a directory: {skill_path}"
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    try:
+        content = skill_md.read_text(encoding="utf-8")
+    except OSError as exc:
+        return False, f"Could not read SKILL.md: {exc}"
+
+    frontmatter_text = _extract_frontmatter(content)
+    if frontmatter_text is None:
+        return False, "Invalid frontmatter format"
+
+    frontmatter, error = _load_frontmatter(frontmatter_text)
+    if error:
+        return False, error
+
+    unexpected_keys = sorted(set(frontmatter.keys()) - ALLOWED_FRONTMATTER_KEYS)
+    if unexpected_keys:
+        allowed = ", ".join(sorted(ALLOWED_FRONTMATTER_KEYS))
+        unexpected = ", ".join(unexpected_keys)
+        return (
+            False,
+            f"Unexpected key(s) in SKILL.md frontmatter: {unexpected}. Allowed properties are: {allowed}",
+        )
+
+    if "name" not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if "description" not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    name = frontmatter["name"]
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name_error = _validate_skill_name(name.strip(), skill_path.name)
+    if name_error:
+        return False, name_error
+
+    description = frontmatter["description"]
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description_error = _validate_description(description)
+    if description_error:
+        return False, description_error
+
+    always = frontmatter.get("always")
+    if always is not None and not isinstance(always, bool):
+        return False, f"'always' must be a boolean, got {type(always).__name__}"
+
+    for child in skill_path.iterdir():
+        if child.name == "SKILL.md":
+            continue
+        if child.is_dir() and child.name in ALLOWED_RESOURCE_DIRS:
+            continue
+        if child.is_symlink():
+            continue
+        return (
+            False,
+            f"Unexpected file or directory in skill root: {child.name}. "
+            "Only SKILL.md, scripts/, references/, and assets/ are allowed.",
+        )
+
+    return True, "Skill is valid!"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py ")
+        sys.exit(1)
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)
diff --git a/core/nanobot/nanobot/skills/summarize/SKILL.md b/core/nanobot/nanobot/skills/summarize/SKILL.md
new file mode 100644
index 0000000..766ab5d
--- /dev/null
+++ b/core/nanobot/nanobot/skills/summarize/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: summarize
+description: Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).
+homepage: https://summarize.sh
+metadata: {"nanobot":{"emoji":"🧾","requires":{"bins":["summarize"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/summarize","bins":["summarize"],"label":"Install summarize (brew)"}]}}
+---
+
+# Summarize
+
+Fast CLI to summarize URLs, local files, and YouTube links.
+
+## When to use (trigger phrases)
+
+Use this skill immediately when the user asks any of:
+- “use summarize.sh”
+- “what’s this link/video about?”
+- “summarize this URL/article”
+- “transcribe this YouTube/video” (best-effort transcript extraction; no `yt-dlp` needed)
+
+## Quick start
+
+```bash
+summarize "https://example.com" --model google/gemini-3-flash-preview
+summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
+```
+
+## YouTube: summary vs transcript
+
+Best-effort transcript (URLs only):
+
+```bash
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract-only
+```
+
+If the user asked for a transcript but it’s huge, return a tight summary first, then ask which section/time range to expand.
+
+## Model + keys
+
+Set the API key for your chosen provider:
+- OpenAI: `OPENAI_API_KEY`
+- Anthropic: `ANTHROPIC_API_KEY`
+- xAI: `XAI_API_KEY`
+- Google: `GEMINI_API_KEY` (aliases: `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_API_KEY`)
+
+Default model is `google/gemini-3-flash-preview` if none is set.
+
+## Useful flags
+
+- `--length short|medium|long|xl|xxl|`
+- `--max-output-tokens `
+- `--extract-only` (URLs only)
+- `--json` (machine readable)
+- `--firecrawl auto|off|always` (fallback extraction)
+- `--youtube auto` (Apify fallback if `APIFY_API_TOKEN` set)
+
+## Config
+
+Optional config file: `~/.summarize/config.json`
+
+```json
+{ "model": "openai/gpt-5.2" }
+```
+
+Optional services:
+- `FIRECRAWL_API_KEY` for blocked sites
+- `APIFY_API_TOKEN` for YouTube fallback
diff --git a/core/nanobot/nanobot/skills/tmux/SKILL.md b/core/nanobot/nanobot/skills/tmux/SKILL.md
new file mode 100644
index 0000000..f2a3144
--- /dev/null
+++ b/core/nanobot/nanobot/skills/tmux/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: tmux
+description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
+metadata: {"nanobot":{"emoji":"🧵","os":["darwin","linux"],"requires":{"bins":["tmux"]}}}
+---
+
+# tmux Skill
+
+Use tmux only when you need an interactive TTY. Prefer exec background mode for long-running, non-interactive tasks.
+
+## Quickstart (isolated socket, exec tool)
+
+```bash
+SOCKET_DIR="${NANOBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nanobot-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/nanobot.sock"
+SESSION=nanobot-python
+
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+After starting a session, always print monitor commands:
+
+```
+To monitor:
+  tmux -S "$SOCKET" attach -t "$SESSION"
+  tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+## Socket convention
+
+- Use `NANOBOT_TMUX_SOCKET_DIR` environment variable.
+- Default socket path: `"$NANOBOT_TMUX_SOCKET_DIR/nanobot.sock"`.
+
+## Targeting panes and naming
+
+- Target format: `session:window.pane` (defaults to `:0.0`).
+- Keep names short; avoid spaces.
+- Inspect: `tmux -S "$SOCKET" list-sessions`, `tmux -S "$SOCKET" list-panes -a`.
+
+## Finding sessions
+
+- List sessions on your socket: `{baseDir}/scripts/find-sessions.sh -S "$SOCKET"`.
+- Scan all sockets: `{baseDir}/scripts/find-sessions.sh --all` (uses `NANOBOT_TMUX_SOCKET_DIR`).
+
+## Sending input safely
+
+- Prefer literal sends: `tmux -S "$SOCKET" send-keys -t target -l -- "$cmd"`.
+- Control keys: `tmux -S "$SOCKET" send-keys -t target C-c`.
+
+## Watching output
+
+- Capture recent history: `tmux -S "$SOCKET" capture-pane -p -J -t target -S -200`.
+- Wait for prompts: `{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern'`.
+- Attaching is OK; detach with `Ctrl+b d`.
+
+## Spawning processes
+
+- For python REPLs, set `PYTHON_BASIC_REPL=1` (non-basic REPL breaks send-keys flows).
+
+## Windows / WSL
+
+- tmux is supported on macOS/Linux. On Windows, use WSL and install tmux inside WSL.
+- This skill is gated to `darwin`/`linux` and requires `tmux` on PATH.
+
+## Orchestrating Coding Agents (Codex, Claude Code)
+
+tmux excels at running multiple coding agents in parallel:
+
+```bash
+SOCKET="${TMPDIR:-/tmp}/codex-army.sock"
+
+# Create multiple sessions
+for i in 1 2 3 4 5; do
+  tmux -S "$SOCKET" new-session -d -s "agent-$i"
+done
+
+# Launch agents in different workdirs
+tmux -S "$SOCKET" send-keys -t agent-1 "cd /tmp/project1 && codex --yolo 'Fix bug X'" Enter
+tmux -S "$SOCKET" send-keys -t agent-2 "cd /tmp/project2 && codex --yolo 'Fix bug Y'" Enter
+
+# Poll for completion (check if prompt returned)
+for sess in agent-1 agent-2; do
+  if tmux -S "$SOCKET" capture-pane -p -t "$sess" -S -3 | grep -q "❯"; then
+    echo "$sess: DONE"
+  else
+    echo "$sess: Running..."
+  fi
+done
+
+# Get full output from completed session
+tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -500
+```
+
+**Tips:**
+- Use separate git worktrees for parallel fixes (no branch conflicts)
+- `pnpm install` first before running codex in fresh clones
+- Check for shell prompt (`❯` or `$`) to detect completion
+- Codex needs `--yolo` or `--full-auto` for non-interactive fixes
+
+## Cleanup
+
+- Kill a session: `tmux -S "$SOCKET" kill-session -t "$SESSION"`.
+- Kill all sessions on a socket: `tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t`.
+- Remove everything on the private socket: `tmux -S "$SOCKET" kill-server`.
+
+## Helper: wait-for-text.sh
+
+`{baseDir}/scripts/wait-for-text.sh` polls a pane for a regex (or fixed string) with a timeout.
+
+```bash
+{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]
+```
+
+- `-t`/`--target` pane target (required)
+- `-p`/`--pattern` regex to match (required); add `-F` for fixed string
+- `-T` timeout seconds (integer, default 15)
+- `-i` poll interval seconds (default 0.5)
+- `-l` history lines to search (integer, default 1000)
diff --git a/core/nanobot/nanobot/skills/tmux/scripts/find-sessions.sh b/core/nanobot/nanobot/skills/tmux/scripts/find-sessions.sh
new file mode 100644
index 0000000..00552c6
--- /dev/null
+++ b/core/nanobot/nanobot/skills/tmux/scripts/find-sessions.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: find-sessions.sh [-L socket-name|-S socket-path|-A] [-q pattern]
+
+List tmux sessions on a socket (default tmux socket if none provided).
+
+Options:
+  -L, --socket       tmux socket name (passed to tmux -L)
+  -S, --socket-path  tmux socket path (passed to tmux -S)
+  -A, --all          scan all sockets under NANOBOT_TMUX_SOCKET_DIR
+  -q, --query        case-insensitive substring to filter session names
+  -h, --help         show this help
+USAGE
+}
+
+socket_name=""
+socket_path=""
+query=""
+scan_all=false
+socket_dir="${NANOBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nanobot-tmux-sockets}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -L|--socket)      socket_name="${2-}"; shift 2 ;;
+    -S|--socket-path) socket_path="${2-}"; shift 2 ;;
+    -A|--all)         scan_all=true; shift ;;
+    -q|--query)       query="${2-}"; shift 2 ;;
+    -h|--help)        usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ "$scan_all" == true && ( -n "$socket_name" || -n "$socket_path" ) ]]; then
+  echo "Cannot combine --all with -L or -S" >&2
+  exit 1
+fi
+
+if [[ -n "$socket_name" && -n "$socket_path" ]]; then
+  echo "Use either -L or -S, not both" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+list_sessions() {
+  local label="$1"; shift
+  local tmux_cmd=(tmux "$@")
+
+  if ! sessions="$("${tmux_cmd[@]}" list-sessions -F '#{session_name}\t#{session_attached}\t#{session_created_string}' 2>/dev/null)"; then
+    echo "No tmux server found on $label" >&2
+    return 1
+  fi
+
+  if [[ -n "$query" ]]; then
+    sessions="$(printf '%s\n' "$sessions" | grep -i -- "$query" || true)"
+  fi
+
+  if [[ -z "$sessions" ]]; then
+    echo "No sessions found on $label"
+    return 0
+  fi
+
+  echo "Sessions on $label:"
+  printf '%s\n' "$sessions" | while IFS=$'\t' read -r name attached created; do
+    attached_label=$([[ "$attached" == "1" ]] && echo "attached" || echo "detached")
+    printf '  - %s (%s, started %s)\n' "$name" "$attached_label" "$created"
+  done
+}
+
+if [[ "$scan_all" == true ]]; then
+  if [[ ! -d "$socket_dir" ]]; then
+    echo "Socket directory not found: $socket_dir" >&2
+    exit 1
+  fi
+
+  shopt -s nullglob
+  sockets=("$socket_dir"/*)
+  shopt -u nullglob
+
+  if [[ "${#sockets[@]}" -eq 0 ]]; then
+    echo "No sockets found under $socket_dir" >&2
+    exit 1
+  fi
+
+  exit_code=0
+  for sock in "${sockets[@]}"; do
+    if [[ ! -S "$sock" ]]; then
+      continue
+    fi
+    list_sessions "socket path '$sock'" -S "$sock" || exit_code=$?
+  done
+  exit "$exit_code"
+fi
+
+tmux_cmd=(tmux)
+socket_label="default socket"
+
+if [[ -n "$socket_name" ]]; then
+  tmux_cmd+=(-L "$socket_name")
+  socket_label="socket name '$socket_name'"
+elif [[ -n "$socket_path" ]]; then
+  tmux_cmd+=(-S "$socket_path")
+  socket_label="socket path '$socket_path'"
+fi
+
+list_sessions "$socket_label" "${tmux_cmd[@]:1}"
diff --git a/core/nanobot/nanobot/skills/tmux/scripts/wait-for-text.sh b/core/nanobot/nanobot/skills/tmux/scripts/wait-for-text.sh
new file mode 100644
index 0000000..56354be
--- /dev/null
+++ b/core/nanobot/nanobot/skills/tmux/scripts/wait-for-text.sh
@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: wait-for-text.sh -t target -p pattern [options]
+
+Poll a tmux pane for text and exit when found.
+
+Options:
+  -t, --target    tmux target (session:window.pane), required
+  -p, --pattern   regex pattern to look for, required
+  -F, --fixed     treat pattern as a fixed string (grep -F)
+  -T, --timeout   seconds to wait (integer, default: 15)
+  -i, --interval  poll interval in seconds (default: 0.5)
+  -l, --lines     number of history lines to inspect (integer, default: 1000)
+  -h, --help      show this help
+USAGE
+}
+
+target=""
+pattern=""
+grep_flag="-E"
+timeout=15
+interval=0.5
+lines=1000
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -t|--target)   target="${2-}"; shift 2 ;;
+    -p|--pattern)  pattern="${2-}"; shift 2 ;;
+    -F|--fixed)    grep_flag="-F"; shift ;;
+    -T|--timeout)  timeout="${2-}"; shift 2 ;;
+    -i|--interval) interval="${2-}"; shift 2 ;;
+    -l|--lines)    lines="${2-}"; shift 2 ;;
+    -h|--help)     usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$target" || -z "$pattern" ]]; then
+  echo "target and pattern are required" >&2
+  usage
+  exit 1
+fi
+
+if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
+  echo "timeout must be an integer number of seconds" >&2
+  exit 1
+fi
+
+if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
+  echo "lines must be an integer" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+# End time in epoch seconds (integer, good enough for polling)
+start_epoch=$(date +%s)
+deadline=$((start_epoch + timeout))
+
+while true; do
+  # -J joins wrapped lines, -S uses negative index to read last N lines
+  pane_text="$(tmux capture-pane -p -J -t "$target" -S "-${lines}" 2>/dev/null || true)"
+
+  if printf '%s\n' "$pane_text" | grep $grep_flag -- "$pattern" >/dev/null 2>&1; then
+    exit 0
+  fi
+
+  now=$(date +%s)
+  if (( now >= deadline )); then
+    echo "Timed out after ${timeout}s waiting for pattern: $pattern" >&2
+    echo "Last ${lines} lines from $target:" >&2
+    printf '%s\n' "$pane_text" >&2
+    exit 1
+  fi
+
+  sleep "$interval"
+done
diff --git a/core/nanobot/nanobot/skills/weather/SKILL.md b/core/nanobot/nanobot/skills/weather/SKILL.md
new file mode 100644
index 0000000..8073de1
--- /dev/null
+++ b/core/nanobot/nanobot/skills/weather/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: weather
+description: Get current weather and forecasts (no API key required).
+homepage: https://wttr.in/:help
+metadata: {"nanobot":{"emoji":"🌤️","requires":{"bins":["curl"]}}}
+---
+
+# Weather
+
+Two free services, no API keys needed.
+
+## wttr.in (primary)
+
+Quick one-liner:
+```bash
+curl -s "wttr.in/London?format=3"
+# Output: London: ⛅️ +8°C
+```
+
+Compact format:
+```bash
+curl -s "wttr.in/London?format=%l:+%c+%t+%h+%w"
+# Output: London: ⛅️ +8°C 71% ↙5km/h
+```
+
+Full forecast:
+```bash
+curl -s "wttr.in/London?T"
+```
+
+Format codes: `%c` condition · `%t` temp · `%h` humidity · `%w` wind · `%l` location · `%m` moon
+
+Tips:
+- URL-encode spaces: `wttr.in/New+York`
+- Airport codes: `wttr.in/JFK`
+- Units: `?m` (metric) `?u` (USCS)
+- Today only: `?1` · Current only: `?0`
+- PNG: `curl -s "wttr.in/Berlin.png" -o /tmp/weather.png`
+
+## Open-Meteo (fallback, JSON)
+
+Free, no key, good for programmatic use:
+```bash
+curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12¤t_weather=true"
+```
+
+Find coordinates for a city, then query. Returns JSON with temp, windspeed, weathercode.
+
+Docs: https://open-meteo.com/en/docs
diff --git a/core/nanobot/nanobot/templates/AGENTS.md b/core/nanobot/nanobot/templates/AGENTS.md
new file mode 100644
index 0000000..a24604b
--- /dev/null
+++ b/core/nanobot/nanobot/templates/AGENTS.md
@@ -0,0 +1,21 @@
+# Agent Instructions
+
+You are a helpful AI assistant. Be concise, accurate, and friendly.
+
+## Scheduled Reminders
+
+Before scheduling reminders, check available skills and follow skill guidance first.
+Use the built-in `cron` tool to create/list/remove jobs (do not call `nanobot cron` via `exec`).
+Get USER_ID and CHANNEL from the current session (e.g., `8281248569` and `telegram` from `telegram:8281248569`).
+
+**Do NOT just write reminders to MEMORY.md** — that won't trigger actual notifications.
+
+## Heartbeat Tasks
+
+`HEARTBEAT.md` is checked on the configured heartbeat interval. Use file tools to manage periodic tasks:
+
+- **Add**: `edit_file` to append new tasks
+- **Remove**: `edit_file` to delete completed tasks
+- **Rewrite**: `write_file` to replace all tasks
+
+When the user asks for a recurring/periodic task, update `HEARTBEAT.md` instead of creating a one-time cron reminder.
diff --git a/core/nanobot/nanobot/templates/HEARTBEAT.md b/core/nanobot/nanobot/templates/HEARTBEAT.md
new file mode 100644
index 0000000..322dbeb
--- /dev/null
+++ b/core/nanobot/nanobot/templates/HEARTBEAT.md
@@ -0,0 +1,16 @@
+# Heartbeat Tasks
+
+This file is checked every 30 minutes by your nanobot agent.
+Add tasks below that you want the agent to work on periodically.
+
+If this file has no tasks (only headers and comments), the agent will skip the heartbeat.
+
+## Active Tasks
+
+
+
+
+## Completed
+
+
+
diff --git a/core/nanobot/nanobot/templates/SOUL.md b/core/nanobot/nanobot/templates/SOUL.md
new file mode 100644
index 0000000..59403e7
--- /dev/null
+++ b/core/nanobot/nanobot/templates/SOUL.md
@@ -0,0 +1,21 @@
+# Soul
+
+I am nanobot 🐈, a personal AI assistant.
+
+## Personality
+
+- Helpful and friendly
+- Concise and to the point
+- Curious and eager to learn
+
+## Values
+
+- Accuracy over speed
+- User privacy and safety
+- Transparency in actions
+
+## Communication Style
+
+- Be clear and direct
+- Explain reasoning when helpful
+- Ask clarifying questions when needed
diff --git a/core/nanobot/nanobot/templates/TOOLS.md b/core/nanobot/nanobot/templates/TOOLS.md
new file mode 100644
index 0000000..51c3a2d
--- /dev/null
+++ b/core/nanobot/nanobot/templates/TOOLS.md
@@ -0,0 +1,15 @@
+# Tool Usage Notes
+
+Tool signatures are provided automatically via function calling.
+This file documents non-obvious constraints and usage patterns.
+
+## exec — Safety Limits
+
+- Commands have a configurable timeout (default 60s)
+- Dangerous commands are blocked (rm -rf, format, dd, shutdown, etc.)
+- Output is truncated at 10,000 characters
+- `restrictToWorkspace` config can limit file access to the workspace
+
+## cron — Scheduled Reminders
+
+- Please refer to cron skill for usage.
diff --git a/core/nanobot/nanobot/templates/USER.md b/core/nanobot/nanobot/templates/USER.md
new file mode 100644
index 0000000..671ec49
--- /dev/null
+++ b/core/nanobot/nanobot/templates/USER.md
@@ -0,0 +1,49 @@
+# User Profile
+
+Information about the user to help personalize interactions.
+
+## Basic Information
+
+- **Name**: (your name)
+- **Timezone**: (your timezone, e.g., UTC+8)
+- **Language**: (preferred language)
+
+## Preferences
+
+### Communication Style
+
+- [ ] Casual
+- [ ] Professional
+- [ ] Technical
+
+### Response Length
+
+- [ ] Brief and concise
+- [ ] Detailed explanations
+- [ ] Adaptive based on question
+
+### Technical Level
+
+- [ ] Beginner
+- [ ] Intermediate
+- [ ] Expert
+
+## Work Context
+
+- **Primary Role**: (your role, e.g., developer, researcher)
+- **Main Projects**: (what you're working on)
+- **Tools You Use**: (IDEs, languages, frameworks)
+
+## Topics of Interest
+
+- 
+- 
+- 
+
+## Special Instructions
+
+(Any specific instructions for how the assistant should behave)
+
+---
+
+*Edit this file to customize nanobot's behavior for your needs.*
diff --git a/core/nanobot/nanobot/templates/__init__.py b/core/nanobot/nanobot/templates/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/core/nanobot/nanobot/templates/memory/MEMORY.md b/core/nanobot/nanobot/templates/memory/MEMORY.md
new file mode 100644
index 0000000..fd2ca96
--- /dev/null
+++ b/core/nanobot/nanobot/templates/memory/MEMORY.md
@@ -0,0 +1,23 @@
+# Long-term Memory
+
+This file stores important information that should persist across sessions.
+
+## User Information
+
+(Important facts about the user)
+
+## Preferences
+
+(User preferences learned over time)
+
+## Project Context
+
+(Information about ongoing projects)
+
+## Important Notes
+
+(Things to remember)
+
+---
+
+*This file is automatically updated by nanobot when important information should be remembered.*
diff --git a/core/nanobot/nanobot/templates/memory/__init__.py b/core/nanobot/nanobot/templates/memory/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/core/nanobot/nanobot/utils/__init__.py b/core/nanobot/nanobot/utils/__init__.py
new file mode 100644
index 0000000..77f4261
--- /dev/null
+++ b/core/nanobot/nanobot/utils/__init__.py
@@ -0,0 +1,5 @@
+"""Utility functions for nanobot."""
+
+from nanobot.utils.helpers import ensure_dir, sync_tools_to_go
+
+__all__ = ["ensure_dir", "sync_tools_to_go"]
diff --git a/core/nanobot/nanobot/utils/helpers.py b/core/nanobot/nanobot/utils/helpers.py
new file mode 100644
index 0000000..8526d61
--- /dev/null
+++ b/core/nanobot/nanobot/utils/helpers.py
@@ -0,0 +1,257 @@
+"""Utility functions for nanobot."""
+
+import json
+import logging
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import requests
+import tiktoken
+
+logger = logging.getLogger(__name__)
+
+
+def detect_image_mime(data: bytes) -> str | None:
+    """Detect image MIME type from magic bytes, ignoring file extension."""
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        return "image/png"
+    if data[:3] == b"\xff\xd8\xff":
+        return "image/jpeg"
+    if data[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+def ensure_dir(path: Path) -> Path:
+    """Ensure directory exists, return it."""
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def timestamp() -> str:
+    """Current ISO timestamp."""
+    return datetime.now().isoformat()
+
+
+_UNSAFE_CHARS = re.compile(r'[<>:"/\\|?*]')
+
+def safe_filename(name: str) -> str:
+    """Replace unsafe path characters with underscores."""
+    return _UNSAFE_CHARS.sub("_", name).strip()
+
+
+def split_message(content: str, max_len: int = 2000) -> list[str]:
+    """
+    Split content into chunks within max_len, preferring line breaks.
+
+    Args:
+        content: The text content to split.
+        max_len: Maximum length per chunk (default 2000 for Discord compatibility).
+
+    Returns:
+        List of message chunks, each within max_len.
+    """
+    if not content:
+        return []
+    if len(content) <= max_len:
+        return [content]
+    chunks: list[str] = []
+    while content:
+        if len(content) <= max_len:
+            chunks.append(content)
+            break
+        cut = content[:max_len]
+        # Try to break at newline first, then space, then hard break
+        pos = cut.rfind('\n')
+        if pos <= 0:
+            pos = cut.rfind(' ')
+        if pos <= 0:
+            pos = max_len
+        chunks.append(content[:pos])
+        content = content[pos:].lstrip()
+    return chunks
+
+
+def build_assistant_message(
+    content: str | None,
+    tool_calls: list[dict[str, Any]] | None = None,
+    reasoning_content: str | None = None,
+    thinking_blocks: list[dict] | None = None,
+) -> dict[str, Any]:
+    """Build a provider-safe assistant message with optional reasoning fields."""
+    msg: dict[str, Any] = {"role": "assistant", "content": content}
+    if tool_calls:
+        msg["tool_calls"] = tool_calls
+    if reasoning_content is not None:
+        msg["reasoning_content"] = reasoning_content
+    if thinking_blocks:
+        msg["thinking_blocks"] = thinking_blocks
+    return msg
+
+
+def estimate_prompt_tokens(
+    messages: list[dict[str, Any]],
+    tools: list[dict[str, Any]] | None = None,
+) -> int:
+    """Estimate prompt tokens with tiktoken."""
+    try:
+        enc = tiktoken.get_encoding("cl100k_base")
+        parts: list[str] = []
+        for msg in messages:
+            content = msg.get("content")
+            if isinstance(content, str):
+                parts.append(content)
+            elif isinstance(content, list):
+                for part in content:
+                    if isinstance(part, dict) and part.get("type") == "text":
+                        txt = part.get("text", "")
+                        if txt:
+                            parts.append(txt)
+        if tools:
+            parts.append(json.dumps(tools, ensure_ascii=False))
+        return len(enc.encode("\n".join(parts)))
+    except Exception:
+        return 0
+
+
+def estimate_message_tokens(message: dict[str, Any]) -> int:
+    """Estimate prompt tokens contributed by one persisted message."""
+    content = message.get("content")
+    parts: list[str] = []
+    if isinstance(content, str):
+        parts.append(content)
+    elif isinstance(content, list):
+        for part in content:
+            if isinstance(part, dict) and part.get("type") == "text":
+                text = part.get("text", "")
+                if text:
+                    parts.append(text)
+            else:
+                parts.append(json.dumps(part, ensure_ascii=False))
+    elif content is not None:
+        parts.append(json.dumps(content, ensure_ascii=False))
+
+    for key in ("name", "tool_call_id"):
+        value = message.get(key)
+        if isinstance(value, str) and value:
+            parts.append(value)
+    if message.get("tool_calls"):
+        parts.append(json.dumps(message["tool_calls"], ensure_ascii=False))
+
+    payload = "\n".join(parts)
+    if not payload:
+        return 1
+    try:
+        enc = tiktoken.get_encoding("cl100k_base")
+        return max(1, len(enc.encode(payload)))
+    except Exception:
+        return max(1, len(payload) // 4)
+
+
+def estimate_prompt_tokens_chain(
+    provider: Any,
+    model: str | None,
+    messages: list[dict[str, Any]],
+    tools: list[dict[str, Any]] | None = None,
+) -> tuple[int, str]:
+    """Estimate prompt tokens via provider counter first, then tiktoken fallback."""
+    provider_counter = getattr(provider, "estimate_prompt_tokens", None)
+    if callable(provider_counter):
+        try:
+            tokens, source = provider_counter(messages, tools, model)
+            if isinstance(tokens, (int, float)) and tokens > 0:
+                return int(tokens), str(source or "provider_counter")
+        except Exception:
+            pass
+
+    estimated = estimate_prompt_tokens(messages, tools)
+    if estimated > 0:
+        return int(estimated), "tiktoken"
+    return 0, "none"
+
+
+def sync_workspace_templates(workspace: Path, silent: bool = False) -> list[str]:
+    """Sync bundled templates to workspace. Only creates missing files."""
+    from importlib.resources import files as pkg_files
+    try:
+        tpl = pkg_files("nanobot") / "templates"
+    except Exception:
+        return []
+    if not tpl.is_dir():
+        return []
+
+    added: list[str] = []
+
+    def _write(src, dest: Path):
+        if dest.exists():
+            return
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(src.read_text(encoding="utf-8") if src else "", encoding="utf-8")
+        added.append(str(dest.relative_to(workspace)))
+
+    for item in tpl.iterdir():
+        if item.name.endswith(".md") and not item.name.startswith("."):
+            _write(item, workspace / item.name)
+    _write(tpl / "memory" / "MEMORY.md", workspace / "memory" / "MEMORY.md")
+    _write(None, workspace / "memory" / "HISTORY.md")
+    (workspace / "skills").mkdir(exist_ok=True)
+
+    if added and not silent:
+        from rich.console import Console
+        for name in added:
+            Console().print(f"  [dim]Created {name}[/dim]")
+    return added
+
+
+def sync_tools_to_go(tool_definitions: list[dict[str, Any]], go_api_url: str | None = None) -> bool:
+    """
+    Sync tool definitions to Go backend.
+
+    Args:
+        tool_definitions: List of tool definitions in OpenAI function format.
+        go_api_url: Go API base URL. Defaults to http://localhost:8082
+
+    Returns:
+        True if sync was successful, False otherwise.
+    """
+    if not tool_definitions:
+        logger.debug("No tools to sync")
+        return True
+
+    api_url = go_api_url or os.environ.get("GO_API_URL", "http://localhost:8082")
+    sync_url = f"{api_url}/tool/sync-from-python"
+
+    # Convert tool definitions to the format expected by Go backend
+    tools = []
+    for tool_def in tool_definitions:
+        # Handle both function format and direct tool format
+        func_def = tool_def.get("function", tool_def)
+        tools.append({
+            "name": func_def.get("name", ""),
+            "description": func_def.get("description", ""),
+            "parameters": json.dumps(func_def.get("parameters", {})),
+            "category": "python",  # Mark as Python-sourced tools
+        })
+
+    try:
+        response = requests.post(
+            sync_url,
+            json={"tools": tools},
+            headers={"Content-Type": "application/json"},
+            timeout=10,
+        )
+        if response.status_code == 200:
+            result = response.json()
+            logger.info(f"Synced {result.get('synced_count', len(tools))} tools to Go backend")
+            return True
+        else:
+            logger.warning(f"Failed to sync tools: {response.status_code} - {response.text}")
+            return False
+    except requests.exceptions.RequestException as e:
+        logger.debug(f"Could not sync tools to Go backend: {e}")
+        return False
diff --git a/core/nanobot/nanobot_arch.png b/core/nanobot/nanobot_arch.png
new file mode 100644
index 0000000..0925177
Binary files /dev/null and b/core/nanobot/nanobot_arch.png differ
diff --git a/core/nanobot/nanobot_logo.png b/core/nanobot/nanobot_logo.png
new file mode 100644
index 0000000..01055d1
Binary files /dev/null and b/core/nanobot/nanobot_logo.png differ
diff --git a/core/nanobot/pyproject.toml b/core/nanobot/pyproject.toml
new file mode 100644
index 0000000..a52c0c9
--- /dev/null
+++ b/core/nanobot/pyproject.toml
@@ -0,0 +1,114 @@
+[project]
+name = "nanobot-ai"
+version = "0.1.4.post4"
+description = "A lightweight personal AI assistant framework"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "nanobot contributors"}
+]
+keywords = ["ai", "agent", "chatbot"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "typer>=0.20.0,<1.0.0",
+    "litellm>=1.82.1,<2.0.0",
+    "pydantic>=2.12.0,<3.0.0",
+    "pydantic-settings>=2.12.0,<3.0.0",
+    "websockets>=16.0,<17.0",
+    "websocket-client>=1.9.0,<2.0.0",
+    "httpx>=0.28.0,<1.0.0",
+    "oauth-cli-kit>=0.1.3,<1.0.0",
+    "loguru>=0.7.3,<1.0.0",
+    "readability-lxml>=0.8.4,<1.0.0",
+    "rich>=14.0.0,<15.0.0",
+    "croniter>=6.0.0,<7.0.0",
+    "dingtalk-stream>=0.24.0,<1.0.0",
+    "python-telegram-bot[socks]>=22.6,<23.0",
+    "lark-oapi>=1.5.0,<2.0.0",
+    "socksio>=1.0.0,<2.0.0",
+    "python-socketio>=5.16.0,<6.0.0",
+    "msgpack>=1.1.0,<2.0.0",
+    "slack-sdk>=3.39.0,<4.0.0",
+    "slackify-markdown>=0.2.0,<1.0.0",
+    "qq-botpy>=1.2.0,<2.0.0",
+    "python-socks[asyncio]>=2.8.0,<3.0.0",
+    "prompt-toolkit>=3.0.50,<4.0.0",
+    "mcp>=1.26.0,<2.0.0",
+    "json-repair>=0.57.0,<1.0.0",
+    "chardet>=3.0.2,<6.0.0",
+    "openai>=2.8.0",
+    "tiktoken>=0.12.0,<1.0.0",
+]
+
+[project.optional-dependencies]
+wecom = [
+    "wecom-aibot-sdk-python @ git+https://github.com/chengyongru/wecom_aibot_sdk.git@v0.1.2",
+]
+matrix = [
+    "matrix-nio[e2e]>=0.25.2",
+    "mistune>=3.0.0,<4.0.0",
+    "nh3>=0.2.17,<1.0.0",
+]
+dev = [
+    "pytest>=9.0.0,<10.0.0",
+    "pytest-asyncio>=1.3.0,<2.0.0",
+    "ruff>=0.1.0",
+    "matrix-nio[e2e]>=0.25.2",
+    "mistune>=3.0.0,<4.0.0",
+    "nh3>=0.2.17,<1.0.0",
+]
+
+[project.scripts]
+nanobot = "nanobot.cli.commands:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["nanobot"]
+
+[tool.hatch.build.targets.wheel.sources]
+"nanobot" = "nanobot"
+
+# Include non-Python files in skills and templates
+[tool.hatch.build]
+include = [
+    "nanobot/**/*.py",
+    "nanobot/templates/**/*.md",
+    "nanobot/skills/**/*.md",
+    "nanobot/skills/**/*.sh",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "nanobot/",
+    "bridge/",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.hatch.build.targets.wheel.force-include]
+"bridge" = "nanobot/bridge"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
diff --git a/core/nanobot/tests/test_azure_openai_provider.py b/core/nanobot/tests/test_azure_openai_provider.py
new file mode 100644
index 0000000..77f36d4
--- /dev/null
+++ b/core/nanobot/tests/test_azure_openai_provider.py
@@ -0,0 +1,399 @@
+"""Test Azure OpenAI provider implementation (updated for model-based deployment names)."""
+
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+
+from nanobot.providers.azure_openai_provider import AzureOpenAIProvider
+from nanobot.providers.base import LLMResponse
+
+
+def test_azure_openai_provider_init():
+    """Test AzureOpenAIProvider initialization without deployment_name."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o-deployment",
+    )
+    
+    assert provider.api_key == "test-key"
+    assert provider.api_base == "https://test-resource.openai.azure.com/"
+    assert provider.default_model == "gpt-4o-deployment"
+    assert provider.api_version == "2024-10-21"
+
+
+def test_azure_openai_provider_init_validation():
+    """Test AzureOpenAIProvider initialization validation."""
+    # Missing api_key
+    with pytest.raises(ValueError, match="Azure OpenAI api_key is required"):
+        AzureOpenAIProvider(api_key="", api_base="https://test.com")
+    
+    # Missing api_base
+    with pytest.raises(ValueError, match="Azure OpenAI api_base is required"):
+        AzureOpenAIProvider(api_key="test", api_base="")
+
+
+def test_build_chat_url():
+    """Test Azure OpenAI URL building with different deployment names."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o",
+    )
+    
+    # Test various deployment names
+    test_cases = [
+        ("gpt-4o-deployment", "https://test-resource.openai.azure.com/openai/deployments/gpt-4o-deployment/chat/completions?api-version=2024-10-21"),
+        ("gpt-35-turbo", "https://test-resource.openai.azure.com/openai/deployments/gpt-35-turbo/chat/completions?api-version=2024-10-21"),
+        ("custom-model", "https://test-resource.openai.azure.com/openai/deployments/custom-model/chat/completions?api-version=2024-10-21"),
+    ]
+    
+    for deployment_name, expected_url in test_cases:
+        url = provider._build_chat_url(deployment_name)
+        assert url == expected_url
+
+
+def test_build_chat_url_api_base_without_slash():
+    """Test URL building when api_base doesn't end with slash."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",  # No trailing slash
+        default_model="gpt-4o",
+    )
+    
+    url = provider._build_chat_url("test-deployment")
+    expected = "https://test-resource.openai.azure.com/openai/deployments/test-deployment/chat/completions?api-version=2024-10-21"
+    assert url == expected
+
+
+def test_build_headers():
+    """Test Azure OpenAI header building with api-key authentication."""
+    provider = AzureOpenAIProvider(
+        api_key="test-api-key-123",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o",
+    )
+    
+    headers = provider._build_headers()
+    assert headers["Content-Type"] == "application/json"
+    assert headers["api-key"] == "test-api-key-123"  # Azure OpenAI specific header
+    assert "x-session-affinity" in headers
+
+
+def test_prepare_request_payload():
+    """Test request payload preparation with Azure OpenAI 2024-10-21 compliance."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o",
+    )
+    
+    messages = [{"role": "user", "content": "Hello"}]
+    payload = provider._prepare_request_payload("gpt-4o", messages, max_tokens=1500, temperature=0.8)
+    
+    assert payload["messages"] == messages
+    assert payload["max_completion_tokens"] == 1500  # Azure API 2024-10-21 uses max_completion_tokens
+    assert payload["temperature"] == 0.8
+    assert "tools" not in payload
+    
+    # Test with tools
+    tools = [{"type": "function", "function": {"name": "get_weather", "parameters": {}}}]
+    payload_with_tools = provider._prepare_request_payload("gpt-4o", messages, tools=tools)
+    assert payload_with_tools["tools"] == tools
+    assert payload_with_tools["tool_choice"] == "auto"
+    
+    # Test with reasoning_effort
+    payload_with_reasoning = provider._prepare_request_payload(
+        "gpt-5-chat", messages, reasoning_effort="medium"
+    )
+    assert payload_with_reasoning["reasoning_effort"] == "medium"
+    assert "temperature" not in payload_with_reasoning
+
+
+def test_prepare_request_payload_sanitizes_messages():
+    """Test Azure payload strips non-standard message keys before sending."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o",
+    )
+
+    messages = [
+        {
+            "role": "assistant",
+            "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "x"}}],
+            "reasoning_content": "hidden chain-of-thought",
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_123",
+            "name": "x",
+            "content": "ok",
+            "extra_field": "should be removed",
+        },
+    ]
+
+    payload = provider._prepare_request_payload("gpt-4o", messages)
+
+    assert payload["messages"] == [
+        {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "x"}}],
+        },
+        {
+            "role": "tool",
+            "tool_call_id": "call_123",
+            "name": "x",
+            "content": "ok",
+        },
+    ]
+
+
+@pytest.mark.asyncio
+async def test_chat_success():
+    """Test successful chat request using model as deployment name."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o-deployment",
+    )
+    
+    # Mock response data
+    mock_response_data = {
+        "choices": [{
+            "message": {
+                "content": "Hello! How can I help you today?",
+                "role": "assistant"
+            },
+            "finish_reason": "stop"
+        }],
+        "usage": {
+            "prompt_tokens": 12,
+            "completion_tokens": 18,
+            "total_tokens": 30
+        }
+    }
+    
+    with patch("httpx.AsyncClient") as mock_client:
+        mock_response = AsyncMock()
+        mock_response.status_code = 200
+        mock_response.json = Mock(return_value=mock_response_data)
+        
+        mock_context = AsyncMock()
+        mock_context.post = AsyncMock(return_value=mock_response)
+        mock_client.return_value.__aenter__.return_value = mock_context
+        
+        # Test with specific model (deployment name)
+        messages = [{"role": "user", "content": "Hello"}]
+        result = await provider.chat(messages, model="custom-deployment")
+        
+        assert isinstance(result, LLMResponse)
+        assert result.content == "Hello! How can I help you today?"
+        assert result.finish_reason == "stop"
+        assert result.usage["prompt_tokens"] == 12
+        assert result.usage["completion_tokens"] == 18
+        assert result.usage["total_tokens"] == 30
+        
+        # Verify URL was built with the provided model as deployment name
+        call_args = mock_context.post.call_args
+        expected_url = "https://test-resource.openai.azure.com/openai/deployments/custom-deployment/chat/completions?api-version=2024-10-21"
+        assert call_args[0][0] == expected_url
+
+
+@pytest.mark.asyncio
+async def test_chat_uses_default_model_when_no_model_provided():
+    """Test that chat uses default_model when no model is specified."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="default-deployment",
+    )
+    
+    mock_response_data = {
+        "choices": [{
+            "message": {"content": "Response", "role": "assistant"},
+            "finish_reason": "stop"
+        }],
+        "usage": {"prompt_tokens": 5, "completion_tokens": 5, "total_tokens": 10}
+    }
+    
+    with patch("httpx.AsyncClient") as mock_client:
+        mock_response = AsyncMock()
+        mock_response.status_code = 200
+        mock_response.json = Mock(return_value=mock_response_data)
+        
+        mock_context = AsyncMock()
+        mock_context.post = AsyncMock(return_value=mock_response)
+        mock_client.return_value.__aenter__.return_value = mock_context
+        
+        messages = [{"role": "user", "content": "Test"}]
+        await provider.chat(messages)  # No model specified
+        
+        # Verify URL was built with default model as deployment name
+        call_args = mock_context.post.call_args
+        expected_url = "https://test-resource.openai.azure.com/openai/deployments/default-deployment/chat/completions?api-version=2024-10-21"
+        assert call_args[0][0] == expected_url
+
+
+@pytest.mark.asyncio
+async def test_chat_with_tool_calls():
+    """Test chat request with tool calls in response."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o",
+    )
+    
+    # Mock response with tool calls
+    mock_response_data = {
+        "choices": [{
+            "message": {
+                "content": None,
+                "role": "assistant",
+                "tool_calls": [{
+                    "id": "call_12345",
+                    "function": {
+                        "name": "get_weather",
+                        "arguments": '{"location": "San Francisco"}'
+                    }
+                }]
+            },
+            "finish_reason": "tool_calls"
+        }],
+        "usage": {
+            "prompt_tokens": 20,
+            "completion_tokens": 15,
+            "total_tokens": 35
+        }
+    }
+    
+    with patch("httpx.AsyncClient") as mock_client:
+        mock_response = AsyncMock()
+        mock_response.status_code = 200
+        mock_response.json = Mock(return_value=mock_response_data)
+        
+        mock_context = AsyncMock()
+        mock_context.post = AsyncMock(return_value=mock_response)
+        mock_client.return_value.__aenter__.return_value = mock_context
+        
+        messages = [{"role": "user", "content": "What's the weather?"}]
+        tools = [{"type": "function", "function": {"name": "get_weather", "parameters": {}}}]
+        result = await provider.chat(messages, tools=tools, model="weather-model")
+        
+        assert isinstance(result, LLMResponse)
+        assert result.content is None
+        assert result.finish_reason == "tool_calls"
+        assert len(result.tool_calls) == 1
+        assert result.tool_calls[0].name == "get_weather"
+        assert result.tool_calls[0].arguments == {"location": "San Francisco"}
+
+
+@pytest.mark.asyncio
+async def test_chat_api_error():
+    """Test chat request API error handling."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o",
+    )
+    
+    with patch("httpx.AsyncClient") as mock_client:
+        mock_response = AsyncMock()
+        mock_response.status_code = 401
+        mock_response.text = "Invalid authentication credentials"
+        
+        mock_context = AsyncMock()
+        mock_context.post = AsyncMock(return_value=mock_response)
+        mock_client.return_value.__aenter__.return_value = mock_context
+        
+        messages = [{"role": "user", "content": "Hello"}]
+        result = await provider.chat(messages)
+        
+        assert isinstance(result, LLMResponse)
+        assert "Azure OpenAI API Error 401" in result.content
+        assert "Invalid authentication credentials" in result.content
+        assert result.finish_reason == "error"
+
+
+@pytest.mark.asyncio
+async def test_chat_connection_error():
+    """Test chat request connection error handling."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o",
+    )
+    
+    with patch("httpx.AsyncClient") as mock_client:
+        mock_context = AsyncMock()
+        mock_context.post = AsyncMock(side_effect=Exception("Connection failed"))
+        mock_client.return_value.__aenter__.return_value = mock_context
+        
+        messages = [{"role": "user", "content": "Hello"}]
+        result = await provider.chat(messages)
+        
+        assert isinstance(result, LLMResponse)
+        assert "Error calling Azure OpenAI: Exception('Connection failed')" in result.content
+        assert result.finish_reason == "error"
+
+
+def test_parse_response_malformed():
+    """Test response parsing with malformed data."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o",
+    )
+    
+    # Test with missing choices
+    malformed_response = {"usage": {"prompt_tokens": 10}}
+    result = provider._parse_response(malformed_response)
+    
+    assert isinstance(result, LLMResponse)
+    assert "Error parsing Azure OpenAI response" in result.content
+    assert result.finish_reason == "error"
+
+
+def test_get_default_model():
+    """Test get_default_model method."""
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="my-custom-deployment",
+    )
+    
+    assert provider.get_default_model() == "my-custom-deployment"
+
+
+if __name__ == "__main__":
+    # Run basic tests
+    print("Running basic Azure OpenAI provider tests...")
+    
+    # Test initialization
+    provider = AzureOpenAIProvider(
+        api_key="test-key",
+        api_base="https://test-resource.openai.azure.com",
+        default_model="gpt-4o-deployment",
+    )
+    print("✅ Provider initialization successful")
+    
+    # Test URL building
+    url = provider._build_chat_url("my-deployment")
+    expected = "https://test-resource.openai.azure.com/openai/deployments/my-deployment/chat/completions?api-version=2024-10-21"
+    assert url == expected
+    print("✅ URL building works correctly")
+    
+    # Test headers
+    headers = provider._build_headers()
+    assert headers["api-key"] == "test-key"
+    assert headers["Content-Type"] == "application/json"
+    print("✅ Header building works correctly")
+    
+    # Test payload preparation
+    messages = [{"role": "user", "content": "Test"}]
+    payload = provider._prepare_request_payload("gpt-4o-deployment", messages, max_tokens=1000)
+    assert payload["max_completion_tokens"] == 1000  # Azure 2024-10-21 format
+    print("✅ Payload preparation works correctly")
+    
+    print("✅ All basic tests passed! Updated test file is working correctly.")
\ No newline at end of file
diff --git a/core/nanobot/tests/test_base_channel.py b/core/nanobot/tests/test_base_channel.py
new file mode 100644
index 0000000..5d10d4e
--- /dev/null
+++ b/core/nanobot/tests/test_base_channel.py
@@ -0,0 +1,25 @@
+from types import SimpleNamespace
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.base import BaseChannel
+
+
+class _DummyChannel(BaseChannel):
+    name = "dummy"
+
+    async def start(self) -> None:
+        return None
+
+    async def stop(self) -> None:
+        return None
+
+    async def send(self, msg: OutboundMessage) -> None:
+        return None
+
+
+def test_is_allowed_requires_exact_match() -> None:
+    channel = _DummyChannel(SimpleNamespace(allow_from=["allow@email.com"]), MessageBus())
+
+    assert channel.is_allowed("allow@email.com") is True
+    assert channel.is_allowed("attacker|allow@email.com") is False
diff --git a/core/nanobot/tests/test_cli_input.py b/core/nanobot/tests/test_cli_input.py
new file mode 100644
index 0000000..9626120
--- /dev/null
+++ b/core/nanobot/tests/test_cli_input.py
@@ -0,0 +1,59 @@
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from prompt_toolkit.formatted_text import HTML
+
+from nanobot.cli import commands
+
+
+@pytest.fixture
+def mock_prompt_session():
+    """Mock the global prompt session."""
+    mock_session = MagicMock()
+    mock_session.prompt_async = AsyncMock()
+    with patch("nanobot.cli.commands._PROMPT_SESSION", mock_session), \
+         patch("nanobot.cli.commands.patch_stdout"):
+        yield mock_session
+
+
+@pytest.mark.asyncio
+async def test_read_interactive_input_async_returns_input(mock_prompt_session):
+    """Test that _read_interactive_input_async returns the user input from prompt_session."""
+    mock_prompt_session.prompt_async.return_value = "hello world"
+
+    result = await commands._read_interactive_input_async()
+    
+    assert result == "hello world"
+    mock_prompt_session.prompt_async.assert_called_once()
+    args, _ = mock_prompt_session.prompt_async.call_args
+    assert isinstance(args[0], HTML)  # Verify HTML prompt is used
+
+
+@pytest.mark.asyncio
+async def test_read_interactive_input_async_handles_eof(mock_prompt_session):
+    """Test that EOFError converts to KeyboardInterrupt."""
+    mock_prompt_session.prompt_async.side_effect = EOFError()
+
+    with pytest.raises(KeyboardInterrupt):
+        await commands._read_interactive_input_async()
+
+
+def test_init_prompt_session_creates_session():
+    """Test that _init_prompt_session initializes the global session."""
+    # Ensure global is None before test
+    commands._PROMPT_SESSION = None
+    
+    with patch("nanobot.cli.commands.PromptSession") as MockSession, \
+         patch("nanobot.cli.commands.FileHistory") as MockHistory, \
+         patch("pathlib.Path.home") as mock_home:
+        
+        mock_home.return_value = MagicMock()
+        
+        commands._init_prompt_session()
+        
+        assert commands._PROMPT_SESSION is not None
+        MockSession.assert_called_once()
+        _, kwargs = MockSession.call_args
+        assert kwargs["multiline"] is False
+        assert kwargs["enable_open_in_editor"] is False
diff --git a/core/nanobot/tests/test_commands.py b/core/nanobot/tests/test_commands.py
new file mode 100644
index 0000000..583ef6f
--- /dev/null
+++ b/core/nanobot/tests/test_commands.py
@@ -0,0 +1,463 @@
+import shutil
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from typer.testing import CliRunner
+
+from nanobot.cli.commands import app
+from nanobot.config.schema import Config
+from nanobot.providers.litellm_provider import LiteLLMProvider
+from nanobot.providers.openai_codex_provider import _strip_model_prefix
+from nanobot.providers.registry import find_by_model
+
+runner = CliRunner()
+
+
+class _StopGateway(RuntimeError):
+    pass
+
+
+@pytest.fixture
+def mock_paths():
+    """Mock config/workspace paths for test isolation."""
+    with patch("nanobot.config.loader.get_config_path") as mock_cp, \
+         patch("nanobot.config.loader.save_config") as mock_sc, \
+         patch("nanobot.config.loader.load_config") as mock_lc, \
+         patch("nanobot.cli.commands.get_workspace_path") as mock_ws:
+
+        base_dir = Path("./test_onboard_data")
+        if base_dir.exists():
+            shutil.rmtree(base_dir)
+        base_dir.mkdir()
+
+        config_file = base_dir / "config.json"
+        workspace_dir = base_dir / "workspace"
+
+        mock_cp.return_value = config_file
+        mock_ws.return_value = workspace_dir
+        mock_sc.side_effect = lambda config: config_file.write_text("{}")
+
+        yield config_file, workspace_dir
+
+        if base_dir.exists():
+            shutil.rmtree(base_dir)
+
+
+def test_onboard_fresh_install(mock_paths):
+    """No existing config — should create from scratch."""
+    config_file, workspace_dir = mock_paths
+
+    result = runner.invoke(app, ["onboard"])
+
+    assert result.exit_code == 0
+    assert "Created config" in result.stdout
+    assert "Created workspace" in result.stdout
+    assert "nanobot is ready" in result.stdout
+    assert config_file.exists()
+    assert (workspace_dir / "AGENTS.md").exists()
+    assert (workspace_dir / "memory" / "MEMORY.md").exists()
+
+
+def test_onboard_existing_config_refresh(mock_paths):
+    """Config exists, user declines overwrite — should refresh (load-merge-save)."""
+    config_file, workspace_dir = mock_paths
+    config_file.write_text('{"existing": true}')
+
+    result = runner.invoke(app, ["onboard"], input="n\n")
+
+    assert result.exit_code == 0
+    assert "Config already exists" in result.stdout
+    assert "existing values preserved" in result.stdout
+    assert workspace_dir.exists()
+    assert (workspace_dir / "AGENTS.md").exists()
+
+
+def test_onboard_existing_config_overwrite(mock_paths):
+    """Config exists, user confirms overwrite — should reset to defaults."""
+    config_file, workspace_dir = mock_paths
+    config_file.write_text('{"existing": true}')
+
+    result = runner.invoke(app, ["onboard"], input="y\n")
+
+    assert result.exit_code == 0
+    assert "Config already exists" in result.stdout
+    assert "Config reset to defaults" in result.stdout
+    assert workspace_dir.exists()
+
+
+def test_onboard_existing_workspace_safe_create(mock_paths):
+    """Workspace exists — should not recreate, but still add missing templates."""
+    config_file, workspace_dir = mock_paths
+    workspace_dir.mkdir(parents=True)
+    config_file.write_text("{}")
+
+    result = runner.invoke(app, ["onboard"], input="n\n")
+
+    assert result.exit_code == 0
+    assert "Created workspace" not in result.stdout
+    assert "Created AGENTS.md" in result.stdout
+    assert (workspace_dir / "AGENTS.md").exists()
+
+
+def test_config_matches_github_copilot_codex_with_hyphen_prefix():
+    config = Config()
+    config.agents.defaults.model = "github-copilot/gpt-5.3-codex"
+
+    assert config.get_provider_name() == "github_copilot"
+
+
+def test_config_matches_openai_codex_with_hyphen_prefix():
+    config = Config()
+    config.agents.defaults.model = "openai-codex/gpt-5.1-codex"
+
+    assert config.get_provider_name() == "openai_codex"
+
+
+def test_config_matches_explicit_ollama_prefix_without_api_key():
+    config = Config()
+    config.agents.defaults.model = "ollama/llama3.2"
+
+    assert config.get_provider_name() == "ollama"
+    assert config.get_api_base() == "http://localhost:11434"
+
+
+def test_config_explicit_ollama_provider_uses_default_localhost_api_base():
+    config = Config()
+    config.agents.defaults.provider = "ollama"
+    config.agents.defaults.model = "llama3.2"
+
+    assert config.get_provider_name() == "ollama"
+    assert config.get_api_base() == "http://localhost:11434"
+
+
+def test_config_auto_detects_ollama_from_local_api_base():
+    config = Config.model_validate(
+        {
+            "agents": {"defaults": {"provider": "auto", "model": "llama3.2"}},
+            "providers": {"ollama": {"apiBase": "http://localhost:11434"}},
+        }
+    )
+
+    assert config.get_provider_name() == "ollama"
+    assert config.get_api_base() == "http://localhost:11434"
+
+
+def test_find_by_model_prefers_explicit_prefix_over_generic_codex_keyword():
+    spec = find_by_model("github-copilot/gpt-5.3-codex")
+
+    assert spec is not None
+    assert spec.name == "github_copilot"
+
+
+def test_litellm_provider_canonicalizes_github_copilot_hyphen_prefix():
+    provider = LiteLLMProvider(default_model="github-copilot/gpt-5.3-codex")
+
+    resolved = provider._resolve_model("github-copilot/gpt-5.3-codex")
+
+    assert resolved == "github_copilot/gpt-5.3-codex"
+
+
+def test_openai_codex_strip_prefix_supports_hyphen_and_underscore():
+    assert _strip_model_prefix("openai-codex/gpt-5.1-codex") == "gpt-5.1-codex"
+    assert _strip_model_prefix("openai_codex/gpt-5.1-codex") == "gpt-5.1-codex"
+
+
+@pytest.fixture
+def mock_agent_runtime(tmp_path):
+    """Mock agent command dependencies for focused CLI tests."""
+    config = Config()
+    config.agents.defaults.workspace = str(tmp_path / "default-workspace")
+    cron_dir = tmp_path / "data" / "cron"
+
+    with patch("nanobot.config.loader.load_config", return_value=config) as mock_load_config, \
+         patch("nanobot.config.paths.get_cron_dir", return_value=cron_dir), \
+         patch("nanobot.cli.commands.sync_workspace_templates") as mock_sync_templates, \
+         patch("nanobot.cli.commands._make_provider", return_value=object()), \
+         patch("nanobot.cli.commands._print_agent_response") as mock_print_response, \
+         patch("nanobot.bus.queue.MessageBus"), \
+         patch("nanobot.cron.service.CronService"), \
+         patch("nanobot.agent.loop.AgentLoop") as mock_agent_loop_cls:
+
+        agent_loop = MagicMock()
+        agent_loop.channels_config = None
+        agent_loop.process_direct = AsyncMock(return_value="mock-response")
+        agent_loop.close_mcp = AsyncMock(return_value=None)
+        mock_agent_loop_cls.return_value = agent_loop
+
+        yield {
+            "config": config,
+            "load_config": mock_load_config,
+            "sync_templates": mock_sync_templates,
+            "agent_loop_cls": mock_agent_loop_cls,
+            "agent_loop": agent_loop,
+            "print_response": mock_print_response,
+        }
+
+
+def test_agent_help_shows_workspace_and_config_options():
+    result = runner.invoke(app, ["agent", "--help"])
+
+    assert result.exit_code == 0
+    assert "--workspace" in result.stdout
+    assert "-w" in result.stdout
+    assert "--config" in result.stdout
+    assert "-c" in result.stdout
+
+
+def test_agent_uses_default_config_when_no_workspace_or_config_flags(mock_agent_runtime):
+    result = runner.invoke(app, ["agent", "-m", "hello"])
+
+    assert result.exit_code == 0
+    assert mock_agent_runtime["load_config"].call_args.args == (None,)
+    assert mock_agent_runtime["sync_templates"].call_args.args == (
+        mock_agent_runtime["config"].workspace_path,
+    )
+    assert mock_agent_runtime["agent_loop_cls"].call_args.kwargs["workspace"] == (
+        mock_agent_runtime["config"].workspace_path
+    )
+    mock_agent_runtime["agent_loop"].process_direct.assert_awaited_once()
+    mock_agent_runtime["print_response"].assert_called_once_with("mock-response", render_markdown=True)
+
+
+def test_agent_uses_explicit_config_path(mock_agent_runtime, tmp_path: Path):
+    config_path = tmp_path / "agent-config.json"
+    config_path.write_text("{}")
+
+    result = runner.invoke(app, ["agent", "-m", "hello", "-c", str(config_path)])
+
+    assert result.exit_code == 0
+    assert mock_agent_runtime["load_config"].call_args.args == (config_path.resolve(),)
+
+
+def test_agent_config_sets_active_path(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance" / "config.json"
+    config_file.parent.mkdir(parents=True)
+    config_file.write_text("{}")
+
+    config = Config()
+    seen: dict[str, Path] = {}
+
+    monkeypatch.setattr(
+        "nanobot.config.loader.set_config_path",
+        lambda path: seen.__setitem__("config_path", path),
+    )
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+    monkeypatch.setattr("nanobot.config.paths.get_cron_dir", lambda: config_file.parent / "cron")
+    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.commands._make_provider", lambda _config: object())
+    monkeypatch.setattr("nanobot.bus.queue.MessageBus", lambda: object())
+    monkeypatch.setattr("nanobot.cron.service.CronService", lambda _store: object())
+
+    class _FakeAgentLoop:
+        def __init__(self, *args, **kwargs) -> None:
+            pass
+
+        async def process_direct(self, *_args, **_kwargs) -> str:
+            return "ok"
+
+        async def close_mcp(self) -> None:
+            return None
+
+    monkeypatch.setattr("nanobot.agent.loop.AgentLoop", _FakeAgentLoop)
+    monkeypatch.setattr("nanobot.cli.commands._print_agent_response", lambda *_args, **_kwargs: None)
+
+    result = runner.invoke(app, ["agent", "-m", "hello", "-c", str(config_file)])
+
+    assert result.exit_code == 0
+    assert seen["config_path"] == config_file.resolve()
+
+
+def test_agent_overrides_workspace_path(mock_agent_runtime):
+    workspace_path = Path("/tmp/agent-workspace")
+
+    result = runner.invoke(app, ["agent", "-m", "hello", "-w", str(workspace_path)])
+
+    assert result.exit_code == 0
+    assert mock_agent_runtime["config"].agents.defaults.workspace == str(workspace_path)
+    assert mock_agent_runtime["sync_templates"].call_args.args == (workspace_path,)
+    assert mock_agent_runtime["agent_loop_cls"].call_args.kwargs["workspace"] == workspace_path
+
+
+def test_agent_workspace_override_wins_over_config_workspace(mock_agent_runtime, tmp_path: Path):
+    config_path = tmp_path / "agent-config.json"
+    config_path.write_text("{}")
+    workspace_path = Path("/tmp/agent-workspace")
+
+    result = runner.invoke(
+        app,
+        ["agent", "-m", "hello", "-c", str(config_path), "-w", str(workspace_path)],
+    )
+
+    assert result.exit_code == 0
+    assert mock_agent_runtime["load_config"].call_args.args == (config_path.resolve(),)
+    assert mock_agent_runtime["config"].agents.defaults.workspace == str(workspace_path)
+    assert mock_agent_runtime["sync_templates"].call_args.args == (workspace_path,)
+    assert mock_agent_runtime["agent_loop_cls"].call_args.kwargs["workspace"] == workspace_path
+
+
+def test_agent_warns_about_deprecated_memory_window(mock_agent_runtime):
+    mock_agent_runtime["config"].agents.defaults.memory_window = 100
+
+    result = runner.invoke(app, ["agent", "-m", "hello"])
+
+    assert result.exit_code == 0
+    assert "memoryWindow" in result.stdout
+    assert "contextWindowTokens" in result.stdout
+
+
+def test_gateway_uses_workspace_from_config_by_default(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance" / "config.json"
+    config_file.parent.mkdir(parents=True)
+    config_file.write_text("{}")
+
+    config = Config()
+    config.agents.defaults.workspace = str(tmp_path / "config-workspace")
+    seen: dict[str, Path] = {}
+
+    monkeypatch.setattr(
+        "nanobot.config.loader.set_config_path",
+        lambda path: seen.__setitem__("config_path", path),
+    )
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+    monkeypatch.setattr(
+        "nanobot.cli.commands.sync_workspace_templates",
+        lambda path: seen.__setitem__("workspace", path),
+    )
+    monkeypatch.setattr(
+        "nanobot.cli.commands._make_provider",
+        lambda _config: (_ for _ in ()).throw(_StopGateway("stop")),
+    )
+
+    result = runner.invoke(app, ["gateway", "--config", str(config_file)])
+
+    assert isinstance(result.exception, _StopGateway)
+    assert seen["config_path"] == config_file.resolve()
+    assert seen["workspace"] == Path(config.agents.defaults.workspace)
+
+
+def test_gateway_workspace_option_overrides_config(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance" / "config.json"
+    config_file.parent.mkdir(parents=True)
+    config_file.write_text("{}")
+
+    config = Config()
+    config.agents.defaults.workspace = str(tmp_path / "config-workspace")
+    override = tmp_path / "override-workspace"
+    seen: dict[str, Path] = {}
+
+    monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+    monkeypatch.setattr(
+        "nanobot.cli.commands.sync_workspace_templates",
+        lambda path: seen.__setitem__("workspace", path),
+    )
+    monkeypatch.setattr(
+        "nanobot.cli.commands._make_provider",
+        lambda _config: (_ for _ in ()).throw(_StopGateway("stop")),
+    )
+
+    result = runner.invoke(
+        app,
+        ["gateway", "--config", str(config_file), "--workspace", str(override)],
+    )
+
+    assert isinstance(result.exception, _StopGateway)
+    assert seen["workspace"] == override
+    assert config.workspace_path == override
+
+
+def test_gateway_warns_about_deprecated_memory_window(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance" / "config.json"
+    config_file.parent.mkdir(parents=True)
+    config_file.write_text("{}")
+
+    config = Config()
+    config.agents.defaults.memory_window = 100
+
+    monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr(
+        "nanobot.cli.commands._make_provider",
+        lambda _config: (_ for _ in ()).throw(_StopGateway("stop")),
+    )
+
+    result = runner.invoke(app, ["gateway", "--config", str(config_file)])
+
+    assert isinstance(result.exception, _StopGateway)
+    assert "memoryWindow" in result.stdout
+    assert "contextWindowTokens" in result.stdout
+
+def test_gateway_uses_config_directory_for_cron_store(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance" / "config.json"
+    config_file.parent.mkdir(parents=True)
+    config_file.write_text("{}")
+
+    config = Config()
+    config.agents.defaults.workspace = str(tmp_path / "config-workspace")
+    seen: dict[str, Path] = {}
+
+    monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+    monkeypatch.setattr("nanobot.config.paths.get_cron_dir", lambda: config_file.parent / "cron")
+    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr("nanobot.cli.commands._make_provider", lambda _config: object())
+    monkeypatch.setattr("nanobot.bus.queue.MessageBus", lambda: object())
+    monkeypatch.setattr("nanobot.session.manager.SessionManager", lambda _workspace: object())
+
+    class _StopCron:
+        def __init__(self, store_path: Path) -> None:
+            seen["cron_store"] = store_path
+            raise _StopGateway("stop")
+
+    monkeypatch.setattr("nanobot.cron.service.CronService", _StopCron)
+
+    result = runner.invoke(app, ["gateway", "--config", str(config_file)])
+
+    assert isinstance(result.exception, _StopGateway)
+    assert seen["cron_store"] == config_file.parent / "cron" / "jobs.json"
+
+
+def test_gateway_uses_configured_port_when_cli_flag_is_missing(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance" / "config.json"
+    config_file.parent.mkdir(parents=True)
+    config_file.write_text("{}")
+
+    config = Config()
+    config.gateway.port = 18791
+
+    monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr(
+        "nanobot.cli.commands._make_provider",
+        lambda _config: (_ for _ in ()).throw(_StopGateway("stop")),
+    )
+
+    result = runner.invoke(app, ["gateway", "--config", str(config_file)])
+
+    assert isinstance(result.exception, _StopGateway)
+    assert "port 18791" in result.stdout
+
+
+def test_gateway_cli_port_overrides_configured_port(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance" / "config.json"
+    config_file.parent.mkdir(parents=True)
+    config_file.write_text("{}")
+
+    config = Config()
+    config.gateway.port = 18791
+
+    monkeypatch.setattr("nanobot.config.loader.set_config_path", lambda _path: None)
+    monkeypatch.setattr("nanobot.config.loader.load_config", lambda _path=None: config)
+    monkeypatch.setattr("nanobot.cli.commands.sync_workspace_templates", lambda _path: None)
+    monkeypatch.setattr(
+        "nanobot.cli.commands._make_provider",
+        lambda _config: (_ for _ in ()).throw(_StopGateway("stop")),
+    )
+
+    result = runner.invoke(app, ["gateway", "--config", str(config_file), "--port", "18792"])
+
+    assert isinstance(result.exception, _StopGateway)
+    assert "port 18792" in result.stdout
diff --git a/core/nanobot/tests/test_config_migration.py b/core/nanobot/tests/test_config_migration.py
new file mode 100644
index 0000000..62e601e
--- /dev/null
+++ b/core/nanobot/tests/test_config_migration.py
@@ -0,0 +1,88 @@
+import json
+
+from typer.testing import CliRunner
+
+from nanobot.cli.commands import app
+from nanobot.config.loader import load_config, save_config
+
+runner = CliRunner()
+
+
+def test_load_config_keeps_max_tokens_and_warns_on_legacy_memory_window(tmp_path) -> None:
+    config_path = tmp_path / "config.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "agents": {
+                    "defaults": {
+                        "maxTokens": 1234,
+                        "memoryWindow": 42,
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    config = load_config(config_path)
+
+    assert config.agents.defaults.max_tokens == 1234
+    assert config.agents.defaults.context_window_tokens == 65_536
+    assert config.agents.defaults.should_warn_deprecated_memory_window is True
+
+
+def test_save_config_writes_context_window_tokens_but_not_memory_window(tmp_path) -> None:
+    config_path = tmp_path / "config.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "agents": {
+                    "defaults": {
+                        "maxTokens": 2222,
+                        "memoryWindow": 30,
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    config = load_config(config_path)
+    save_config(config, config_path)
+    saved = json.loads(config_path.read_text(encoding="utf-8"))
+    defaults = saved["agents"]["defaults"]
+
+    assert defaults["maxTokens"] == 2222
+    assert defaults["contextWindowTokens"] == 65_536
+    assert "memoryWindow" not in defaults
+
+
+def test_onboard_refresh_rewrites_legacy_config_template(tmp_path, monkeypatch) -> None:
+    config_path = tmp_path / "config.json"
+    workspace = tmp_path / "workspace"
+    config_path.write_text(
+        json.dumps(
+            {
+                "agents": {
+                    "defaults": {
+                        "maxTokens": 3333,
+                        "memoryWindow": 50,
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    monkeypatch.setattr("nanobot.config.loader.get_config_path", lambda: config_path)
+    monkeypatch.setattr("nanobot.cli.commands.get_workspace_path", lambda: workspace)
+
+    result = runner.invoke(app, ["onboard"], input="n\n")
+
+    assert result.exit_code == 0
+    assert "contextWindowTokens" in result.stdout
+    saved = json.loads(config_path.read_text(encoding="utf-8"))
+    defaults = saved["agents"]["defaults"]
+    assert defaults["maxTokens"] == 3333
+    assert defaults["contextWindowTokens"] == 65_536
+    assert "memoryWindow" not in defaults
diff --git a/core/nanobot/tests/test_config_paths.py b/core/nanobot/tests/test_config_paths.py
new file mode 100644
index 0000000..473a6c8
--- /dev/null
+++ b/core/nanobot/tests/test_config_paths.py
@@ -0,0 +1,42 @@
+from pathlib import Path
+
+from nanobot.config.paths import (
+    get_bridge_install_dir,
+    get_cli_history_path,
+    get_cron_dir,
+    get_data_dir,
+    get_legacy_sessions_dir,
+    get_logs_dir,
+    get_media_dir,
+    get_runtime_subdir,
+    get_workspace_path,
+)
+
+
+def test_runtime_dirs_follow_config_path(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance-a" / "config.json"
+    monkeypatch.setattr("nanobot.config.paths.get_config_path", lambda: config_file)
+
+    assert get_data_dir() == config_file.parent
+    assert get_runtime_subdir("cron") == config_file.parent / "cron"
+    assert get_cron_dir() == config_file.parent / "cron"
+    assert get_logs_dir() == config_file.parent / "logs"
+
+
+def test_media_dir_supports_channel_namespace(monkeypatch, tmp_path: Path) -> None:
+    config_file = tmp_path / "instance-b" / "config.json"
+    monkeypatch.setattr("nanobot.config.paths.get_config_path", lambda: config_file)
+
+    assert get_media_dir() == config_file.parent / "media"
+    assert get_media_dir("telegram") == config_file.parent / "media" / "telegram"
+
+
+def test_shared_and_legacy_paths_remain_global() -> None:
+    assert get_cli_history_path() == Path.home() / ".nanobot" / "history" / "cli_history"
+    assert get_bridge_install_dir() == Path.home() / ".nanobot" / "bridge"
+    assert get_legacy_sessions_dir() == Path.home() / ".nanobot" / "sessions"
+
+
+def test_workspace_path_is_explicitly_resolved() -> None:
+    assert get_workspace_path() == Path.home() / ".nanobot" / "workspace"
+    assert get_workspace_path("~/custom-workspace") == Path.home() / "custom-workspace"
diff --git a/core/nanobot/tests/test_consolidate_offset.py b/core/nanobot/tests/test_consolidate_offset.py
new file mode 100644
index 0000000..7d12338
--- /dev/null
+++ b/core/nanobot/tests/test_consolidate_offset.py
@@ -0,0 +1,580 @@
+"""Test session management with cache-friendly message handling."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from pathlib import Path
+from nanobot.session.manager import Session, SessionManager
+
+# Test constants
+MEMORY_WINDOW = 50
+KEEP_COUNT = MEMORY_WINDOW // 2  # 25
+
+
+def create_session_with_messages(key: str, count: int, role: str = "user") -> Session:
+    """Create a session and add the specified number of messages.
+
+    Args:
+        key: Session identifier
+        count: Number of messages to add
+        role: Message role (default: "user")
+
+    Returns:
+        Session with the specified messages
+    """
+    session = Session(key=key)
+    for i in range(count):
+        session.add_message(role, f"msg{i}")
+    return session
+
+
+def assert_messages_content(messages: list, start_index: int, end_index: int) -> None:
+    """Assert that messages contain expected content from start to end index.
+
+    Args:
+        messages: List of message dictionaries
+        start_index: Expected first message index
+        end_index: Expected last message index
+    """
+    assert len(messages) > 0
+    assert messages[0]["content"] == f"msg{start_index}"
+    assert messages[-1]["content"] == f"msg{end_index}"
+
+
+def get_old_messages(session: Session, last_consolidated: int, keep_count: int) -> list:
+    """Extract messages that would be consolidated using the standard slice logic.
+
+    Args:
+        session: The session containing messages
+        last_consolidated: Index of last consolidated message
+        keep_count: Number of recent messages to keep
+
+    Returns:
+        List of messages that would be consolidated
+    """
+    return session.messages[last_consolidated:-keep_count]
+
+
+class TestSessionLastConsolidated:
+    """Test last_consolidated tracking to avoid duplicate processing."""
+
+    def test_initial_last_consolidated_zero(self) -> None:
+        """Test that new session starts with last_consolidated=0."""
+        session = Session(key="test:initial")
+        assert session.last_consolidated == 0
+
+    def test_last_consolidated_persistence(self, tmp_path) -> None:
+        """Test that last_consolidated persists across save/load."""
+        manager = SessionManager(Path(tmp_path))
+        session1 = create_session_with_messages("test:persist", 20)
+        session1.last_consolidated = 15
+        manager.save(session1)
+
+        session2 = manager.get_or_create("test:persist")
+        assert session2.last_consolidated == 15
+        assert len(session2.messages) == 20
+
+    def test_clear_resets_last_consolidated(self) -> None:
+        """Test that clear() resets last_consolidated to 0."""
+        session = create_session_with_messages("test:clear", 10)
+        session.last_consolidated = 5
+
+        session.clear()
+        assert len(session.messages) == 0
+        assert session.last_consolidated == 0
+
+
+class TestSessionImmutableHistory:
+    """Test Session message immutability for cache efficiency."""
+
+    def test_initial_state(self) -> None:
+        """Test that new session has empty messages list."""
+        session = Session(key="test:initial")
+        assert len(session.messages) == 0
+
+    def test_add_messages_appends_only(self) -> None:
+        """Test that adding messages only appends, never modifies."""
+        session = Session(key="test:preserve")
+        session.add_message("user", "msg1")
+        session.add_message("assistant", "resp1")
+        session.add_message("user", "msg2")
+        assert len(session.messages) == 3
+        assert session.messages[0]["content"] == "msg1"
+
+    def test_get_history_returns_most_recent(self) -> None:
+        """Test get_history returns the most recent messages."""
+        session = Session(key="test:history")
+        for i in range(10):
+            session.add_message("user", f"msg{i}")
+            session.add_message("assistant", f"resp{i}")
+
+        history = session.get_history(max_messages=6)
+        assert len(history) == 6
+        assert history[0]["content"] == "msg7"
+        assert history[-1]["content"] == "resp9"
+
+    def test_get_history_with_all_messages(self) -> None:
+        """Test get_history with max_messages larger than actual."""
+        session = create_session_with_messages("test:all", 5)
+        history = session.get_history(max_messages=100)
+        assert len(history) == 5
+        assert history[0]["content"] == "msg0"
+
+    def test_get_history_stable_for_same_session(self) -> None:
+        """Test that get_history returns same content for same max_messages."""
+        session = create_session_with_messages("test:stable", 20)
+        history1 = session.get_history(max_messages=10)
+        history2 = session.get_history(max_messages=10)
+        assert history1 == history2
+
+    def test_messages_list_never_modified(self) -> None:
+        """Test that messages list is never modified after creation."""
+        session = create_session_with_messages("test:immutable", 5)
+        original_len = len(session.messages)
+
+        session.get_history(max_messages=2)
+        assert len(session.messages) == original_len
+
+        for _ in range(10):
+            session.get_history(max_messages=3)
+        assert len(session.messages) == original_len
+
+
+class TestSessionPersistence:
+    """Test Session persistence and reload."""
+
+    @pytest.fixture
+    def temp_manager(self, tmp_path):
+        return SessionManager(Path(tmp_path))
+
+    def test_persistence_roundtrip(self, temp_manager):
+        """Test that messages persist across save/load."""
+        session1 = create_session_with_messages("test:persistence", 20)
+        temp_manager.save(session1)
+
+        session2 = temp_manager.get_or_create("test:persistence")
+        assert len(session2.messages) == 20
+        assert session2.messages[0]["content"] == "msg0"
+        assert session2.messages[-1]["content"] == "msg19"
+
+    def test_get_history_after_reload(self, temp_manager):
+        """Test that get_history works correctly after reload."""
+        session1 = create_session_with_messages("test:reload", 30)
+        temp_manager.save(session1)
+
+        session2 = temp_manager.get_or_create("test:reload")
+        history = session2.get_history(max_messages=10)
+        assert len(history) == 10
+        assert history[0]["content"] == "msg20"
+        assert history[-1]["content"] == "msg29"
+
+    def test_clear_resets_session(self, temp_manager):
+        """Test that clear() properly resets session."""
+        session = create_session_with_messages("test:clear", 10)
+        assert len(session.messages) == 10
+
+        session.clear()
+        assert len(session.messages) == 0
+
+
+class TestConsolidationTriggerConditions:
+    """Test consolidation trigger conditions and logic."""
+
+    def test_consolidation_needed_when_messages_exceed_window(self):
+        """Test consolidation logic: should trigger when messages > memory_window."""
+        session = create_session_with_messages("test:trigger", 60)
+
+        total_messages = len(session.messages)
+        messages_to_process = total_messages - session.last_consolidated
+
+        assert total_messages > MEMORY_WINDOW
+        assert messages_to_process > 0
+
+        expected_consolidate_count = total_messages - KEEP_COUNT
+        assert expected_consolidate_count == 35
+
+    def test_consolidation_skipped_when_within_keep_count(self):
+        """Test consolidation skipped when total messages <= keep_count."""
+        session = create_session_with_messages("test:skip", 20)
+
+        total_messages = len(session.messages)
+        assert total_messages <= KEEP_COUNT
+
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+        assert len(old_messages) == 0
+
+    def test_consolidation_skipped_when_no_new_messages(self):
+        """Test consolidation skipped when messages_to_process <= 0."""
+        session = create_session_with_messages("test:already_consolidated", 40)
+        session.last_consolidated = len(session.messages) - KEEP_COUNT  # 15
+
+        # Add a few more messages
+        for i in range(40, 42):
+            session.add_message("user", f"msg{i}")
+
+        total_messages = len(session.messages)
+        messages_to_process = total_messages - session.last_consolidated
+        assert messages_to_process > 0
+
+        # Simulate last_consolidated catching up
+        session.last_consolidated = total_messages - KEEP_COUNT
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+        assert len(old_messages) == 0
+
+
+class TestLastConsolidatedEdgeCases:
+    """Test last_consolidated edge cases and data corruption scenarios."""
+
+    def test_last_consolidated_exceeds_message_count(self):
+        """Test behavior when last_consolidated > len(messages) (data corruption)."""
+        session = create_session_with_messages("test:corruption", 10)
+        session.last_consolidated = 20
+
+        total_messages = len(session.messages)
+        messages_to_process = total_messages - session.last_consolidated
+        assert messages_to_process <= 0
+
+        old_messages = get_old_messages(session, session.last_consolidated, 5)
+        assert len(old_messages) == 0
+
+    def test_last_consolidated_negative_value(self):
+        """Test behavior with negative last_consolidated (invalid state)."""
+        session = create_session_with_messages("test:negative", 10)
+        session.last_consolidated = -5
+
+        keep_count = 3
+        old_messages = get_old_messages(session, session.last_consolidated, keep_count)
+
+        # messages[-5:-3] with 10 messages gives indices 5,6
+        assert len(old_messages) == 2
+        assert old_messages[0]["content"] == "msg5"
+        assert old_messages[-1]["content"] == "msg6"
+
+    def test_messages_added_after_consolidation(self):
+        """Test correct behavior when new messages arrive after consolidation."""
+        session = create_session_with_messages("test:new_messages", 40)
+        session.last_consolidated = len(session.messages) - KEEP_COUNT  # 15
+
+        # Add new messages after consolidation
+        for i in range(40, 50):
+            session.add_message("user", f"msg{i}")
+
+        total_messages = len(session.messages)
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+        expected_consolidate_count = total_messages - KEEP_COUNT - session.last_consolidated
+
+        assert len(old_messages) == expected_consolidate_count
+        assert_messages_content(old_messages, 15, 24)
+
+    def test_slice_behavior_when_indices_overlap(self):
+        """Test slice behavior when last_consolidated >= total - keep_count."""
+        session = create_session_with_messages("test:overlap", 30)
+        session.last_consolidated = 12
+
+        old_messages = get_old_messages(session, session.last_consolidated, 20)
+        assert len(old_messages) == 0
+
+
+class TestArchiveAllMode:
+    """Test archive_all mode (used by /new command)."""
+
+    def test_archive_all_consolidates_everything(self):
+        """Test archive_all=True consolidates all messages."""
+        session = create_session_with_messages("test:archive_all", 50)
+
+        archive_all = True
+        if archive_all:
+            old_messages = session.messages
+            assert len(old_messages) == 50
+
+        assert session.last_consolidated == 0
+
+    def test_archive_all_resets_last_consolidated(self):
+        """Test that archive_all mode resets last_consolidated to 0."""
+        session = create_session_with_messages("test:reset", 40)
+        session.last_consolidated = 15
+
+        archive_all = True
+        if archive_all:
+            session.last_consolidated = 0
+
+        assert session.last_consolidated == 0
+        assert len(session.messages) == 40
+
+    def test_archive_all_vs_normal_consolidation(self):
+        """Test difference between archive_all and normal consolidation."""
+        # Normal consolidation
+        session1 = create_session_with_messages("test:normal", 60)
+        session1.last_consolidated = len(session1.messages) - KEEP_COUNT
+
+        # archive_all mode
+        session2 = create_session_with_messages("test:all", 60)
+        session2.last_consolidated = 0
+
+        assert session1.last_consolidated == 35
+        assert len(session1.messages) == 60
+        assert session2.last_consolidated == 0
+        assert len(session2.messages) == 60
+
+
+class TestCacheImmutability:
+    """Test that consolidation doesn't modify session.messages (cache safety)."""
+
+    def test_consolidation_does_not_modify_messages_list(self):
+        """Test that consolidation leaves messages list unchanged."""
+        session = create_session_with_messages("test:immutable", 50)
+
+        original_messages = session.messages.copy()
+        original_len = len(session.messages)
+        session.last_consolidated = original_len - KEEP_COUNT
+
+        assert len(session.messages) == original_len
+        assert session.messages == original_messages
+
+    def test_get_history_does_not_modify_messages(self):
+        """Test that get_history doesn't modify messages list."""
+        session = create_session_with_messages("test:history_immutable", 40)
+        original_messages = [m.copy() for m in session.messages]
+
+        for _ in range(5):
+            history = session.get_history(max_messages=10)
+            assert len(history) == 10
+
+        assert len(session.messages) == 40
+        for i, msg in enumerate(session.messages):
+            assert msg["content"] == original_messages[i]["content"]
+
+    def test_consolidation_only_updates_last_consolidated(self):
+        """Test that consolidation only updates last_consolidated field."""
+        session = create_session_with_messages("test:field_only", 60)
+
+        original_messages = session.messages.copy()
+        original_key = session.key
+        original_metadata = session.metadata.copy()
+
+        session.last_consolidated = len(session.messages) - KEEP_COUNT
+
+        assert session.messages == original_messages
+        assert session.key == original_key
+        assert session.metadata == original_metadata
+        assert session.last_consolidated == 35
+
+
+class TestSliceLogic:
+    """Test the slice logic: messages[last_consolidated:-keep_count]."""
+
+    def test_slice_extracts_correct_range(self):
+        """Test that slice extracts the correct message range."""
+        session = create_session_with_messages("test:slice", 60)
+
+        old_messages = get_old_messages(session, 0, KEEP_COUNT)
+
+        assert len(old_messages) == 35
+        assert_messages_content(old_messages, 0, 34)
+
+        remaining = session.messages[-KEEP_COUNT:]
+        assert len(remaining) == 25
+        assert_messages_content(remaining, 35, 59)
+
+    def test_slice_with_partial_consolidation(self):
+        """Test slice when some messages already consolidated."""
+        session = create_session_with_messages("test:partial", 70)
+
+        last_consolidated = 30
+        old_messages = get_old_messages(session, last_consolidated, KEEP_COUNT)
+
+        assert len(old_messages) == 15
+        assert_messages_content(old_messages, 30, 44)
+
+    def test_slice_with_various_keep_counts(self):
+        """Test slice behavior with different keep_count values."""
+        session = create_session_with_messages("test:keep_counts", 50)
+
+        test_cases = [(10, 40), (20, 30), (30, 20), (40, 10)]
+
+        for keep_count, expected_count in test_cases:
+            old_messages = session.messages[0:-keep_count]
+            assert len(old_messages) == expected_count
+
+    def test_slice_when_keep_count_exceeds_messages(self):
+        """Test slice when keep_count > len(messages)."""
+        session = create_session_with_messages("test:exceed", 10)
+
+        old_messages = session.messages[0:-20]
+        assert len(old_messages) == 0
+
+
+class TestEmptyAndBoundarySessions:
+    """Test empty sessions and boundary conditions."""
+
+    def test_empty_session_consolidation(self):
+        """Test consolidation behavior with empty session."""
+        session = Session(key="test:empty")
+
+        assert len(session.messages) == 0
+        assert session.last_consolidated == 0
+
+        messages_to_process = len(session.messages) - session.last_consolidated
+        assert messages_to_process == 0
+
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+        assert len(old_messages) == 0
+
+    def test_single_message_session(self):
+        """Test consolidation with single message."""
+        session = Session(key="test:single")
+        session.add_message("user", "only message")
+
+        assert len(session.messages) == 1
+
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+        assert len(old_messages) == 0
+
+    def test_exactly_keep_count_messages(self):
+        """Test session with exactly keep_count messages."""
+        session = create_session_with_messages("test:exact", KEEP_COUNT)
+
+        assert len(session.messages) == KEEP_COUNT
+
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+        assert len(old_messages) == 0
+
+    def test_just_over_keep_count(self):
+        """Test session with one message over keep_count."""
+        session = create_session_with_messages("test:over", KEEP_COUNT + 1)
+
+        assert len(session.messages) == 26
+
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+        assert len(old_messages) == 1
+        assert old_messages[0]["content"] == "msg0"
+
+    def test_very_large_session(self):
+        """Test consolidation with very large message count."""
+        session = create_session_with_messages("test:large", 1000)
+
+        assert len(session.messages) == 1000
+
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+        assert len(old_messages) == 975
+        assert_messages_content(old_messages, 0, 974)
+
+        remaining = session.messages[-KEEP_COUNT:]
+        assert len(remaining) == 25
+        assert_messages_content(remaining, 975, 999)
+
+    def test_session_with_gaps_in_consolidation(self):
+        """Test session with potential gaps in consolidation history."""
+        session = create_session_with_messages("test:gaps", 50)
+        session.last_consolidated = 10
+
+        # Add more messages
+        for i in range(50, 60):
+            session.add_message("user", f"msg{i}")
+
+        old_messages = get_old_messages(session, session.last_consolidated, KEEP_COUNT)
+
+        expected_count = 60 - KEEP_COUNT - 10
+        assert len(old_messages) == expected_count
+        assert_messages_content(old_messages, 10, 34)
+
+
+class TestNewCommandArchival:
+    """Test /new archival behavior with the simplified consolidation flow."""
+
+    @staticmethod
+    def _make_loop(tmp_path: Path):
+        from nanobot.agent.loop import AgentLoop
+        from nanobot.bus.queue import MessageBus
+        from nanobot.providers.base import LLMResponse
+
+        bus = MessageBus()
+        provider = MagicMock()
+        provider.get_default_model.return_value = "test-model"
+        provider.estimate_prompt_tokens.return_value = (10_000, "test")
+        loop = AgentLoop(
+            bus=bus,
+            provider=provider,
+            workspace=tmp_path,
+            model="test-model",
+            context_window_tokens=1,
+        )
+        loop.provider.chat_with_retry = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+        loop.tools.get_definitions = MagicMock(return_value=[])
+        return loop
+
+    @pytest.mark.asyncio
+    async def test_new_does_not_clear_session_when_archive_fails(self, tmp_path: Path) -> None:
+        from nanobot.bus.events import InboundMessage
+
+        loop = self._make_loop(tmp_path)
+        session = loop.sessions.get_or_create("cli:test")
+        for i in range(5):
+            session.add_message("user", f"msg{i}")
+            session.add_message("assistant", f"resp{i}")
+        loop.sessions.save(session)
+        before_count = len(session.messages)
+
+        async def _failing_consolidate(_messages) -> bool:
+            return False
+
+        loop.memory_consolidator.consolidate_messages = _failing_consolidate  # type: ignore[method-assign]
+
+        new_msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="/new")
+        response = await loop._process_message(new_msg)
+
+        assert response is not None
+        assert "failed" in response.content.lower()
+        assert len(loop.sessions.get_or_create("cli:test").messages) == before_count
+
+    @pytest.mark.asyncio
+    async def test_new_archives_only_unconsolidated_messages(self, tmp_path: Path) -> None:
+        from nanobot.bus.events import InboundMessage
+
+        loop = self._make_loop(tmp_path)
+        session = loop.sessions.get_or_create("cli:test")
+        for i in range(15):
+            session.add_message("user", f"msg{i}")
+            session.add_message("assistant", f"resp{i}")
+        session.last_consolidated = len(session.messages) - 3
+        loop.sessions.save(session)
+
+        archived_count = -1
+
+        async def _fake_consolidate(messages) -> bool:
+            nonlocal archived_count
+            archived_count = len(messages)
+            return True
+
+        loop.memory_consolidator.consolidate_messages = _fake_consolidate  # type: ignore[method-assign]
+
+        new_msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="/new")
+        response = await loop._process_message(new_msg)
+
+        assert response is not None
+        assert "new session started" in response.content.lower()
+        assert archived_count == 3
+
+    @pytest.mark.asyncio
+    async def test_new_clears_session_and_responds(self, tmp_path: Path) -> None:
+        from nanobot.bus.events import InboundMessage
+
+        loop = self._make_loop(tmp_path)
+        session = loop.sessions.get_or_create("cli:test")
+        for i in range(3):
+            session.add_message("user", f"msg{i}")
+            session.add_message("assistant", f"resp{i}")
+        loop.sessions.save(session)
+
+        async def _ok_consolidate(_messages) -> bool:
+            return True
+
+        loop.memory_consolidator.consolidate_messages = _ok_consolidate  # type: ignore[method-assign]
+
+        new_msg = InboundMessage(channel="cli", sender_id="user", chat_id="test", content="/new")
+        response = await loop._process_message(new_msg)
+
+        assert response is not None
+        assert "new session started" in response.content.lower()
+        assert loop.sessions.get_or_create("cli:test").messages == []
diff --git a/core/nanobot/tests/test_context_prompt_cache.py b/core/nanobot/tests/test_context_prompt_cache.py
new file mode 100644
index 0000000..6eb4b4f
--- /dev/null
+++ b/core/nanobot/tests/test_context_prompt_cache.py
@@ -0,0 +1,73 @@
+"""Tests for cache-friendly prompt construction."""
+
+from __future__ import annotations
+
+from datetime import datetime as real_datetime
+from importlib.resources import files as pkg_files
+from pathlib import Path
+import datetime as datetime_module
+
+from nanobot.agent.context import ContextBuilder
+
+
+class _FakeDatetime(real_datetime):
+    current = real_datetime(2026, 2, 24, 13, 59)
+
+    @classmethod
+    def now(cls, tz=None):  # type: ignore[override]
+        return cls.current
+
+
+def _make_workspace(tmp_path: Path) -> Path:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir(parents=True)
+    return workspace
+
+
+def test_bootstrap_files_are_backed_by_templates() -> None:
+    template_dir = pkg_files("nanobot") / "templates"
+
+    for filename in ContextBuilder.BOOTSTRAP_FILES:
+        assert (template_dir / filename).is_file(), f"missing bootstrap template: {filename}"
+
+
+def test_system_prompt_stays_stable_when_clock_changes(tmp_path, monkeypatch) -> None:
+    """System prompt should not change just because wall clock minute changes."""
+    monkeypatch.setattr(datetime_module, "datetime", _FakeDatetime)
+
+    workspace = _make_workspace(tmp_path)
+    builder = ContextBuilder(workspace)
+
+    _FakeDatetime.current = real_datetime(2026, 2, 24, 13, 59)
+    prompt1 = builder.build_system_prompt()
+
+    _FakeDatetime.current = real_datetime(2026, 2, 24, 14, 0)
+    prompt2 = builder.build_system_prompt()
+
+    assert prompt1 == prompt2
+
+
+def test_runtime_context_is_separate_untrusted_user_message(tmp_path) -> None:
+    """Runtime metadata should be merged with the user message."""
+    workspace = _make_workspace(tmp_path)
+    builder = ContextBuilder(workspace)
+
+    messages = builder.build_messages(
+        history=[],
+        current_message="Return exactly: OK",
+        channel="cli",
+        chat_id="direct",
+    )
+
+    assert messages[0]["role"] == "system"
+    assert "## Current Session" not in messages[0]["content"]
+
+    # Runtime context is now merged with user message into a single message
+    assert messages[-1]["role"] == "user"
+    user_content = messages[-1]["content"]
+    assert isinstance(user_content, str)
+    assert ContextBuilder._RUNTIME_CONTEXT_TAG in user_content
+    assert "Current Time:" in user_content
+    assert "Channel: cli" in user_content
+    assert "Chat ID: direct" in user_content
+    assert "Return exactly: OK" in user_content
diff --git a/core/nanobot/tests/test_cron_service.py b/core/nanobot/tests/test_cron_service.py
new file mode 100644
index 0000000..9631da5
--- /dev/null
+++ b/core/nanobot/tests/test_cron_service.py
@@ -0,0 +1,61 @@
+import asyncio
+
+import pytest
+
+from nanobot.cron.service import CronService
+from nanobot.cron.types import CronSchedule
+
+
+def test_add_job_rejects_unknown_timezone(tmp_path) -> None:
+    service = CronService(tmp_path / "cron" / "jobs.json")
+
+    with pytest.raises(ValueError, match="unknown timezone 'America/Vancovuer'"):
+        service.add_job(
+            name="tz typo",
+            schedule=CronSchedule(kind="cron", expr="0 9 * * *", tz="America/Vancovuer"),
+            message="hello",
+        )
+
+    assert service.list_jobs(include_disabled=True) == []
+
+
+def test_add_job_accepts_valid_timezone(tmp_path) -> None:
+    service = CronService(tmp_path / "cron" / "jobs.json")
+
+    job = service.add_job(
+        name="tz ok",
+        schedule=CronSchedule(kind="cron", expr="0 9 * * *", tz="America/Vancouver"),
+        message="hello",
+    )
+
+    assert job.schedule.tz == "America/Vancouver"
+    assert job.state.next_run_at_ms is not None
+
+
+@pytest.mark.asyncio
+async def test_running_service_honors_external_disable(tmp_path) -> None:
+    store_path = tmp_path / "cron" / "jobs.json"
+    called: list[str] = []
+
+    async def on_job(job) -> None:
+        called.append(job.id)
+
+    service = CronService(store_path, on_job=on_job)
+    job = service.add_job(
+        name="external-disable",
+        schedule=CronSchedule(kind="every", every_ms=200),
+        message="hello",
+    )
+    await service.start()
+    try:
+        # Wait slightly to ensure file mtime is definitively different
+        await asyncio.sleep(0.05)
+        external = CronService(store_path)
+        updated = external.enable_job(job.id, enabled=False)
+        assert updated is not None
+        assert updated.enabled is False
+
+        await asyncio.sleep(0.35)
+        assert called == []
+    finally:
+        service.stop()
diff --git a/core/nanobot/tests/test_dingtalk_channel.py b/core/nanobot/tests/test_dingtalk_channel.py
new file mode 100644
index 0000000..6051014
--- /dev/null
+++ b/core/nanobot/tests/test_dingtalk_channel.py
@@ -0,0 +1,111 @@
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+
+from nanobot.bus.queue import MessageBus
+import nanobot.channels.dingtalk as dingtalk_module
+from nanobot.channels.dingtalk import DingTalkChannel, NanobotDingTalkHandler
+from nanobot.config.schema import DingTalkConfig
+
+
+class _FakeResponse:
+    def __init__(self, status_code: int = 200, json_body: dict | None = None) -> None:
+        self.status_code = status_code
+        self._json_body = json_body or {}
+        self.text = "{}"
+
+    def json(self) -> dict:
+        return self._json_body
+
+
+class _FakeHttp:
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+
+    async def post(self, url: str, json=None, headers=None):
+        self.calls.append({"url": url, "json": json, "headers": headers})
+        return _FakeResponse()
+
+
+@pytest.mark.asyncio
+async def test_group_message_keeps_sender_id_and_routes_chat_id() -> None:
+    config = DingTalkConfig(client_id="app", client_secret="secret", allow_from=["user1"])
+    bus = MessageBus()
+    channel = DingTalkChannel(config, bus)
+
+    await channel._on_message(
+        "hello",
+        sender_id="user1",
+        sender_name="Alice",
+        conversation_type="2",
+        conversation_id="conv123",
+    )
+
+    msg = await bus.consume_inbound()
+    assert msg.sender_id == "user1"
+    assert msg.chat_id == "group:conv123"
+    assert msg.metadata["conversation_type"] == "2"
+
+
+@pytest.mark.asyncio
+async def test_group_send_uses_group_messages_api() -> None:
+    config = DingTalkConfig(client_id="app", client_secret="secret", allow_from=["*"])
+    channel = DingTalkChannel(config, MessageBus())
+    channel._http = _FakeHttp()
+
+    ok = await channel._send_batch_message(
+        "token",
+        "group:conv123",
+        "sampleMarkdown",
+        {"text": "hello", "title": "Nanobot Reply"},
+    )
+
+    assert ok is True
+    call = channel._http.calls[0]
+    assert call["url"] == "https://api.dingtalk.com/v1.0/robot/groupMessages/send"
+    assert call["json"]["openConversationId"] == "conv123"
+    assert call["json"]["msgKey"] == "sampleMarkdown"
+
+
+@pytest.mark.asyncio
+async def test_handler_uses_voice_recognition_text_when_text_is_empty(monkeypatch) -> None:
+    bus = MessageBus()
+    channel = DingTalkChannel(
+        DingTalkConfig(client_id="app", client_secret="secret", allow_from=["user1"]),
+        bus,
+    )
+    handler = NanobotDingTalkHandler(channel)
+
+    class _FakeChatbotMessage:
+        text = None
+        extensions = {"content": {"recognition": "voice transcript"}}
+        sender_staff_id = "user1"
+        sender_id = "fallback-user"
+        sender_nick = "Alice"
+        message_type = "audio"
+
+        @staticmethod
+        def from_dict(_data):
+            return _FakeChatbotMessage()
+
+    monkeypatch.setattr(dingtalk_module, "ChatbotMessage", _FakeChatbotMessage)
+    monkeypatch.setattr(dingtalk_module, "AckMessage", SimpleNamespace(STATUS_OK="OK"))
+
+    status, body = await handler.process(
+        SimpleNamespace(
+            data={
+                "conversationType": "2",
+                "conversationId": "conv123",
+                "text": {"content": ""},
+            }
+        )
+    )
+
+    await asyncio.gather(*list(channel._background_tasks))
+    msg = await bus.consume_inbound()
+
+    assert (status, body) == ("OK", "OK")
+    assert msg.content == "voice transcript"
+    assert msg.sender_id == "user1"
+    assert msg.chat_id == "group:conv123"
diff --git a/core/nanobot/tests/test_docker.sh b/core/nanobot/tests/test_docker.sh
new file mode 100644
index 0000000..1e55133
--- /dev/null
+++ b/core/nanobot/tests/test_docker.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.." || exit 1
+
+IMAGE_NAME="nanobot-test"
+
+echo "=== Building Docker image ==="
+docker build -t "$IMAGE_NAME" .
+
+echo ""
+echo "=== Running 'nanobot onboard' ==="
+docker run --name nanobot-test-run "$IMAGE_NAME" onboard
+
+echo ""
+echo "=== Running 'nanobot status' ==="
+STATUS_OUTPUT=$(docker commit nanobot-test-run nanobot-test-onboarded > /dev/null && \
+    docker run --rm nanobot-test-onboarded status 2>&1) || true
+
+echo "$STATUS_OUTPUT"
+
+echo ""
+echo "=== Validating output ==="
+PASS=true
+
+check() {
+    if echo "$STATUS_OUTPUT" | grep -q "$1"; then
+        echo "  PASS: found '$1'"
+    else
+        echo "  FAIL: missing '$1'"
+        PASS=false
+    fi
+}
+
+check "nanobot Status"
+check "Config:"
+check "Workspace:"
+check "Model:"
+check "OpenRouter API:"
+check "Anthropic API:"
+check "OpenAI API:"
+
+echo ""
+if $PASS; then
+    echo "=== All checks passed ==="
+else
+    echo "=== Some checks FAILED ==="
+    exit 1
+fi
+
+# Cleanup
+echo ""
+echo "=== Cleanup ==="
+docker rm -f nanobot-test-run 2>/dev/null || true
+docker rmi -f nanobot-test-onboarded 2>/dev/null || true
+docker rmi -f "$IMAGE_NAME" 2>/dev/null || true
+echo "Done."
diff --git a/core/nanobot/tests/test_email_channel.py b/core/nanobot/tests/test_email_channel.py
new file mode 100644
index 0000000..adf35a8
--- /dev/null
+++ b/core/nanobot/tests/test_email_channel.py
@@ -0,0 +1,368 @@
+from email.message import EmailMessage
+from datetime import date
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.email import EmailChannel
+from nanobot.config.schema import EmailConfig
+
+
+def _make_config() -> EmailConfig:
+    return EmailConfig(
+        enabled=True,
+        consent_granted=True,
+        imap_host="imap.example.com",
+        imap_port=993,
+        imap_username="bot@example.com",
+        imap_password="secret",
+        smtp_host="smtp.example.com",
+        smtp_port=587,
+        smtp_username="bot@example.com",
+        smtp_password="secret",
+        mark_seen=True,
+    )
+
+
+def _make_raw_email(
+    from_addr: str = "alice@example.com",
+    subject: str = "Hello",
+    body: str = "This is the body.",
+) -> bytes:
+    msg = EmailMessage()
+    msg["From"] = from_addr
+    msg["To"] = "bot@example.com"
+    msg["Subject"] = subject
+    msg["Message-ID"] = ""
+    msg.set_content(body)
+    return msg.as_bytes()
+
+
+def test_fetch_new_messages_parses_unseen_and_marks_seen(monkeypatch) -> None:
+    raw = _make_raw_email(subject="Invoice", body="Please pay")
+
+    class FakeIMAP:
+        def __init__(self) -> None:
+            self.store_calls: list[tuple[bytes, str, str]] = []
+
+        def login(self, _user: str, _pw: str):
+            return "OK", [b"logged in"]
+
+        def select(self, _mailbox: str):
+            return "OK", [b"1"]
+
+        def search(self, *_args):
+            return "OK", [b"1"]
+
+        def fetch(self, _imap_id: bytes, _parts: str):
+            return "OK", [(b"1 (UID 123 BODY[] {200})", raw), b")"]
+
+        def store(self, imap_id: bytes, op: str, flags: str):
+            self.store_calls.append((imap_id, op, flags))
+            return "OK", [b""]
+
+        def logout(self):
+            return "BYE", [b""]
+
+    fake = FakeIMAP()
+    monkeypatch.setattr("nanobot.channels.email.imaplib.IMAP4_SSL", lambda _h, _p: fake)
+
+    channel = EmailChannel(_make_config(), MessageBus())
+    items = channel._fetch_new_messages()
+
+    assert len(items) == 1
+    assert items[0]["sender"] == "alice@example.com"
+    assert items[0]["subject"] == "Invoice"
+    assert "Please pay" in items[0]["content"]
+    assert fake.store_calls == [(b"1", "+FLAGS", "\\Seen")]
+
+    # Same UID should be deduped in-process.
+    items_again = channel._fetch_new_messages()
+    assert items_again == []
+
+
+def test_extract_text_body_falls_back_to_html() -> None:
+    msg = EmailMessage()
+    msg["From"] = "alice@example.com"
+    msg["To"] = "bot@example.com"
+    msg["Subject"] = "HTML only"
+    msg.add_alternative("
Hello
world
", subtype="html")
+
+    text = EmailChannel._extract_text_body(msg)
+    assert "Hello" in text
+    assert "world" in text
+
+
+@pytest.mark.asyncio
+async def test_start_returns_immediately_without_consent(monkeypatch) -> None:
+    cfg = _make_config()
+    cfg.consent_granted = False
+    channel = EmailChannel(cfg, MessageBus())
+
+    called = {"fetch": False}
+
+    def _fake_fetch():
+        called["fetch"] = True
+        return []
+
+    monkeypatch.setattr(channel, "_fetch_new_messages", _fake_fetch)
+    await channel.start()
+    assert channel.is_running is False
+    assert called["fetch"] is False
+
+
+@pytest.mark.asyncio
+async def test_send_uses_smtp_and_reply_subject(monkeypatch) -> None:
+    class FakeSMTP:
+        def __init__(self, _host: str, _port: int, timeout: int = 30) -> None:
+            self.timeout = timeout
+            self.started_tls = False
+            self.logged_in = False
+            self.sent_messages: list[EmailMessage] = []
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+        def starttls(self, context=None):
+            self.started_tls = True
+
+        def login(self, _user: str, _pw: str):
+            self.logged_in = True
+
+        def send_message(self, msg: EmailMessage):
+            self.sent_messages.append(msg)
+
+    fake_instances: list[FakeSMTP] = []
+
+    def _smtp_factory(host: str, port: int, timeout: int = 30):
+        instance = FakeSMTP(host, port, timeout=timeout)
+        fake_instances.append(instance)
+        return instance
+
+    monkeypatch.setattr("nanobot.channels.email.smtplib.SMTP", _smtp_factory)
+
+    channel = EmailChannel(_make_config(), MessageBus())
+    channel._last_subject_by_chat["alice@example.com"] = "Invoice #42"
+    channel._last_message_id_by_chat["alice@example.com"] = ""
+
+    await channel.send(
+        OutboundMessage(
+            channel="email",
+            chat_id="alice@example.com",
+            content="Acknowledged.",
+        )
+    )
+
+    assert len(fake_instances) == 1
+    smtp = fake_instances[0]
+    assert smtp.started_tls is True
+    assert smtp.logged_in is True
+    assert len(smtp.sent_messages) == 1
+    sent = smtp.sent_messages[0]
+    assert sent["Subject"] == "Re: Invoice #42"
+    assert sent["To"] == "alice@example.com"
+    assert sent["In-Reply-To"] == ""
+
+
+@pytest.mark.asyncio
+async def test_send_skips_reply_when_auto_reply_disabled(monkeypatch) -> None:
+    """When auto_reply_enabled=False, replies should be skipped but proactive sends allowed."""
+    class FakeSMTP:
+        def __init__(self, _host: str, _port: int, timeout: int = 30) -> None:
+            self.sent_messages: list[EmailMessage] = []
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+        def starttls(self, context=None):
+            return None
+
+        def login(self, _user: str, _pw: str):
+            return None
+
+        def send_message(self, msg: EmailMessage):
+            self.sent_messages.append(msg)
+
+    fake_instances: list[FakeSMTP] = []
+
+    def _smtp_factory(host: str, port: int, timeout: int = 30):
+        instance = FakeSMTP(host, port, timeout=timeout)
+        fake_instances.append(instance)
+        return instance
+
+    monkeypatch.setattr("nanobot.channels.email.smtplib.SMTP", _smtp_factory)
+
+    cfg = _make_config()
+    cfg.auto_reply_enabled = False
+    channel = EmailChannel(cfg, MessageBus())
+
+    # Mark alice as someone who sent us an email (making this a "reply")
+    channel._last_subject_by_chat["alice@example.com"] = "Previous email"
+
+    # Reply should be skipped (auto_reply_enabled=False)
+    await channel.send(
+        OutboundMessage(
+            channel="email",
+            chat_id="alice@example.com",
+            content="Should not send.",
+        )
+    )
+    assert fake_instances == []
+
+    # Reply with force_send=True should be sent
+    await channel.send(
+        OutboundMessage(
+            channel="email",
+            chat_id="alice@example.com",
+            content="Force send.",
+            metadata={"force_send": True},
+        )
+    )
+    assert len(fake_instances) == 1
+    assert len(fake_instances[0].sent_messages) == 1
+
+
+@pytest.mark.asyncio
+async def test_send_proactive_email_when_auto_reply_disabled(monkeypatch) -> None:
+    """Proactive emails (not replies) should be sent even when auto_reply_enabled=False."""
+    class FakeSMTP:
+        def __init__(self, _host: str, _port: int, timeout: int = 30) -> None:
+            self.sent_messages: list[EmailMessage] = []
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+        def starttls(self, context=None):
+            return None
+
+        def login(self, _user: str, _pw: str):
+            return None
+
+        def send_message(self, msg: EmailMessage):
+            self.sent_messages.append(msg)
+
+    fake_instances: list[FakeSMTP] = []
+
+    def _smtp_factory(host: str, port: int, timeout: int = 30):
+        instance = FakeSMTP(host, port, timeout=timeout)
+        fake_instances.append(instance)
+        return instance
+
+    monkeypatch.setattr("nanobot.channels.email.smtplib.SMTP", _smtp_factory)
+
+    cfg = _make_config()
+    cfg.auto_reply_enabled = False
+    channel = EmailChannel(cfg, MessageBus())
+
+    # bob@example.com has never sent us an email (proactive send)
+    # This should be sent even with auto_reply_enabled=False
+    await channel.send(
+        OutboundMessage(
+            channel="email",
+            chat_id="bob@example.com",
+            content="Hello, this is a proactive email.",
+        )
+    )
+    assert len(fake_instances) == 1
+    assert len(fake_instances[0].sent_messages) == 1
+    sent = fake_instances[0].sent_messages[0]
+    assert sent["To"] == "bob@example.com"
+
+
+@pytest.mark.asyncio
+async def test_send_skips_when_consent_not_granted(monkeypatch) -> None:
+    class FakeSMTP:
+        def __init__(self, _host: str, _port: int, timeout: int = 30) -> None:
+            self.sent_messages: list[EmailMessage] = []
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+        def starttls(self, context=None):
+            return None
+
+        def login(self, _user: str, _pw: str):
+            return None
+
+        def send_message(self, msg: EmailMessage):
+            self.sent_messages.append(msg)
+
+    called = {"smtp": False}
+
+    def _smtp_factory(host: str, port: int, timeout: int = 30):
+        called["smtp"] = True
+        return FakeSMTP(host, port, timeout=timeout)
+
+    monkeypatch.setattr("nanobot.channels.email.smtplib.SMTP", _smtp_factory)
+
+    cfg = _make_config()
+    cfg.consent_granted = False
+    channel = EmailChannel(cfg, MessageBus())
+    await channel.send(
+        OutboundMessage(
+            channel="email",
+            chat_id="alice@example.com",
+            content="Should not send.",
+            metadata={"force_send": True},
+        )
+    )
+    assert called["smtp"] is False
+
+
+def test_fetch_messages_between_dates_uses_imap_since_before_without_mark_seen(monkeypatch) -> None:
+    raw = _make_raw_email(subject="Status", body="Yesterday update")
+
+    class FakeIMAP:
+        def __init__(self) -> None:
+            self.search_args = None
+            self.store_calls: list[tuple[bytes, str, str]] = []
+
+        def login(self, _user: str, _pw: str):
+            return "OK", [b"logged in"]
+
+        def select(self, _mailbox: str):
+            return "OK", [b"1"]
+
+        def search(self, *_args):
+            self.search_args = _args
+            return "OK", [b"5"]
+
+        def fetch(self, _imap_id: bytes, _parts: str):
+            return "OK", [(b"5 (UID 999 BODY[] {200})", raw), b")"]
+
+        def store(self, imap_id: bytes, op: str, flags: str):
+            self.store_calls.append((imap_id, op, flags))
+            return "OK", [b""]
+
+        def logout(self):
+            return "BYE", [b""]
+
+    fake = FakeIMAP()
+    monkeypatch.setattr("nanobot.channels.email.imaplib.IMAP4_SSL", lambda _h, _p: fake)
+
+    channel = EmailChannel(_make_config(), MessageBus())
+    items = channel.fetch_messages_between_dates(
+        start_date=date(2026, 2, 6),
+        end_date=date(2026, 2, 7),
+        limit=10,
+    )
+
+    assert len(items) == 1
+    assert items[0]["subject"] == "Status"
+    # search(None, "SINCE", "06-Feb-2026", "BEFORE", "07-Feb-2026")
+    assert fake.search_args is not None
+    assert fake.search_args[1:] == ("SINCE", "06-Feb-2026", "BEFORE", "07-Feb-2026")
+    assert fake.store_calls == []
diff --git a/core/nanobot/tests/test_feishu_post_content.py b/core/nanobot/tests/test_feishu_post_content.py
new file mode 100644
index 0000000..7b1cb9d
--- /dev/null
+++ b/core/nanobot/tests/test_feishu_post_content.py
@@ -0,0 +1,65 @@
+from nanobot.channels.feishu import FeishuChannel, _extract_post_content
+
+
+def test_extract_post_content_supports_post_wrapper_shape() -> None:
+    payload = {
+        "post": {
+            "zh_cn": {
+                "title": "日报",
+                "content": [
+                    [
+                        {"tag": "text", "text": "完成"},
+                        {"tag": "img", "image_key": "img_1"},
+                    ]
+                ],
+            }
+        }
+    }
+
+    text, image_keys = _extract_post_content(payload)
+
+    assert text == "日报 完成"
+    assert image_keys == ["img_1"]
+
+
+def test_extract_post_content_keeps_direct_shape_behavior() -> None:
+    payload = {
+        "title": "Daily",
+        "content": [
+            [
+                {"tag": "text", "text": "report"},
+                {"tag": "img", "image_key": "img_a"},
+                {"tag": "img", "image_key": "img_b"},
+            ]
+        ],
+    }
+
+    text, image_keys = _extract_post_content(payload)
+
+    assert text == "Daily report"
+    assert image_keys == ["img_a", "img_b"]
+
+
+def test_register_optional_event_keeps_builder_when_method_missing() -> None:
+    class Builder:
+        pass
+
+    builder = Builder()
+    same = FeishuChannel._register_optional_event(builder, "missing", object())
+    assert same is builder
+
+
+def test_register_optional_event_calls_supported_method() -> None:
+    called = []
+
+    class Builder:
+        def register_event(self, handler):
+            called.append(handler)
+            return self
+
+    builder = Builder()
+    handler = object()
+    same = FeishuChannel._register_optional_event(builder, "register_event", handler)
+
+    assert same is builder
+    assert called == [handler]
diff --git a/core/nanobot/tests/test_feishu_table_split.py b/core/nanobot/tests/test_feishu_table_split.py
new file mode 100644
index 0000000..af8fa16
--- /dev/null
+++ b/core/nanobot/tests/test_feishu_table_split.py
@@ -0,0 +1,104 @@
+"""Tests for FeishuChannel._split_elements_by_table_limit.
+
+Feishu cards reject messages that contain more than one table element
+(API error 11310: card table number over limit).  The helper splits a flat
+list of card elements into groups so that each group contains at most one
+table, allowing nanobot to send multiple cards instead of failing.
+"""
+
+from nanobot.channels.feishu import FeishuChannel
+
+
+def _md(text: str) -> dict:
+    return {"tag": "markdown", "content": text}
+
+
+def _table() -> dict:
+    return {
+        "tag": "table",
+        "columns": [{"tag": "column", "name": "c0", "display_name": "A", "width": "auto"}],
+        "rows": [{"c0": "v"}],
+        "page_size": 2,
+    }
+
+
+split = FeishuChannel._split_elements_by_table_limit
+
+
+def test_empty_list_returns_single_empty_group() -> None:
+    assert split([]) == [[]]
+
+
+def test_no_tables_returns_single_group() -> None:
+    els = [_md("hello"), _md("world")]
+    result = split(els)
+    assert result == [els]
+
+
+def test_single_table_stays_in_one_group() -> None:
+    els = [_md("intro"), _table(), _md("outro")]
+    result = split(els)
+    assert len(result) == 1
+    assert result[0] == els
+
+
+def test_two_tables_split_into_two_groups() -> None:
+    # Use different row values so the two tables are not equal
+    t1 = {
+        "tag": "table",
+        "columns": [{"tag": "column", "name": "c0", "display_name": "A", "width": "auto"}],
+        "rows": [{"c0": "table-one"}],
+        "page_size": 2,
+    }
+    t2 = {
+        "tag": "table",
+        "columns": [{"tag": "column", "name": "c0", "display_name": "B", "width": "auto"}],
+        "rows": [{"c0": "table-two"}],
+        "page_size": 2,
+    }
+    els = [_md("before"), t1, _md("between"), t2, _md("after")]
+    result = split(els)
+    assert len(result) == 2
+    # First group: text before table-1 + table-1
+    assert t1 in result[0]
+    assert t2 not in result[0]
+    # Second group: text between tables + table-2 + text after
+    assert t2 in result[1]
+    assert t1 not in result[1]
+
+
+def test_three_tables_split_into_three_groups() -> None:
+    tables = [
+        {"tag": "table", "columns": [], "rows": [{"c0": f"t{i}"}], "page_size": 1}
+        for i in range(3)
+    ]
+    els = tables[:]
+    result = split(els)
+    assert len(result) == 3
+    for i, group in enumerate(result):
+        assert tables[i] in group
+
+
+def test_leading_markdown_stays_with_first_table() -> None:
+    intro = _md("intro")
+    t = _table()
+    result = split([intro, t])
+    assert len(result) == 1
+    assert result[0] == [intro, t]
+
+
+def test_trailing_markdown_after_second_table() -> None:
+    t1, t2 = _table(), _table()
+    tail = _md("end")
+    result = split([t1, t2, tail])
+    assert len(result) == 2
+    assert result[1] == [t2, tail]
+
+
+def test_non_table_elements_before_first_table_kept_in_first_group() -> None:
+    head = _md("head")
+    t1, t2 = _table(), _table()
+    result = split([head, t1, t2])
+    # head + t1 in group 0; t2 in group 1
+    assert result[0] == [head, t1]
+    assert result[1] == [t2]
diff --git a/core/nanobot/tests/test_filesystem_tools.py b/core/nanobot/tests/test_filesystem_tools.py
new file mode 100644
index 0000000..db8f256
--- /dev/null
+++ b/core/nanobot/tests/test_filesystem_tools.py
@@ -0,0 +1,251 @@
+"""Tests for enhanced filesystem tools: ReadFileTool, EditFileTool, ListDirTool."""
+
+import pytest
+
+from nanobot.agent.tools.filesystem import (
+    EditFileTool,
+    ListDirTool,
+    ReadFileTool,
+    _find_match,
+)
+
+
+# ---------------------------------------------------------------------------
+# ReadFileTool
+# ---------------------------------------------------------------------------
+
+class TestReadFileTool:
+
+    @pytest.fixture()
+    def tool(self, tmp_path):
+        return ReadFileTool(workspace=tmp_path)
+
+    @pytest.fixture()
+    def sample_file(self, tmp_path):
+        f = tmp_path / "sample.txt"
+        f.write_text("\n".join(f"line {i}" for i in range(1, 21)), encoding="utf-8")
+        return f
+
+    @pytest.mark.asyncio
+    async def test_basic_read_has_line_numbers(self, tool, sample_file):
+        result = await tool.execute(path=str(sample_file))
+        assert "1| line 1" in result
+        assert "20| line 20" in result
+
+    @pytest.mark.asyncio
+    async def test_offset_and_limit(self, tool, sample_file):
+        result = await tool.execute(path=str(sample_file), offset=5, limit=3)
+        assert "5| line 5" in result
+        assert "7| line 7" in result
+        assert "8| line 8" not in result
+        assert "Use offset=8 to continue" in result
+
+    @pytest.mark.asyncio
+    async def test_offset_beyond_end(self, tool, sample_file):
+        result = await tool.execute(path=str(sample_file), offset=999)
+        assert "Error" in result
+        assert "beyond end" in result
+
+    @pytest.mark.asyncio
+    async def test_end_of_file_marker(self, tool, sample_file):
+        result = await tool.execute(path=str(sample_file), offset=1, limit=9999)
+        assert "End of file" in result
+
+    @pytest.mark.asyncio
+    async def test_empty_file(self, tool, tmp_path):
+        f = tmp_path / "empty.txt"
+        f.write_text("", encoding="utf-8")
+        result = await tool.execute(path=str(f))
+        assert "Empty file" in result
+
+    @pytest.mark.asyncio
+    async def test_file_not_found(self, tool, tmp_path):
+        result = await tool.execute(path=str(tmp_path / "nope.txt"))
+        assert "Error" in result
+        assert "not found" in result
+
+    @pytest.mark.asyncio
+    async def test_char_budget_trims(self, tool, tmp_path):
+        """When the selected slice exceeds _MAX_CHARS the output is trimmed."""
+        f = tmp_path / "big.txt"
+        # Each line is ~110 chars, 2000 lines ≈ 220 KB > 128 KB limit
+        f.write_text("\n".join("x" * 110 for _ in range(2000)), encoding="utf-8")
+        result = await tool.execute(path=str(f))
+        assert len(result) <= ReadFileTool._MAX_CHARS + 500  # small margin for footer
+        assert "Use offset=" in result
+
+
+# ---------------------------------------------------------------------------
+# _find_match  (unit tests for the helper)
+# ---------------------------------------------------------------------------
+
+class TestFindMatch:
+
+    def test_exact_match(self):
+        match, count = _find_match("hello world", "world")
+        assert match == "world"
+        assert count == 1
+
+    def test_exact_no_match(self):
+        match, count = _find_match("hello world", "xyz")
+        assert match is None
+        assert count == 0
+
+    def test_crlf_normalisation(self):
+        # Caller normalises CRLF before calling _find_match, so test with
+        # pre-normalised content to verify exact match still works.
+        content = "line1\nline2\nline3"
+        old_text = "line1\nline2\nline3"
+        match, count = _find_match(content, old_text)
+        assert match is not None
+        assert count == 1
+
+    def test_line_trim_fallback(self):
+        content = "    def foo():\n        pass\n"
+        old_text = "def foo():\n    pass"
+        match, count = _find_match(content, old_text)
+        assert match is not None
+        assert count == 1
+        # The returned match should be the *original* indented text
+        assert "    def foo():" in match
+
+    def test_line_trim_multiple_candidates(self):
+        content = "  a\n  b\n  a\n  b\n"
+        old_text = "a\nb"
+        match, count = _find_match(content, old_text)
+        assert count == 2
+
+    def test_empty_old_text(self):
+        match, count = _find_match("hello", "")
+        # Empty string is always "in" any string via exact match
+        assert match == ""
+
+
+# ---------------------------------------------------------------------------
+# EditFileTool
+# ---------------------------------------------------------------------------
+
+class TestEditFileTool:
+
+    @pytest.fixture()
+    def tool(self, tmp_path):
+        return EditFileTool(workspace=tmp_path)
+
+    @pytest.mark.asyncio
+    async def test_exact_match(self, tool, tmp_path):
+        f = tmp_path / "a.py"
+        f.write_text("hello world", encoding="utf-8")
+        result = await tool.execute(path=str(f), old_text="world", new_text="earth")
+        assert "Successfully" in result
+        assert f.read_text() == "hello earth"
+
+    @pytest.mark.asyncio
+    async def test_crlf_normalisation(self, tool, tmp_path):
+        f = tmp_path / "crlf.py"
+        f.write_bytes(b"line1\r\nline2\r\nline3")
+        result = await tool.execute(
+            path=str(f), old_text="line1\nline2", new_text="LINE1\nLINE2",
+        )
+        assert "Successfully" in result
+        raw = f.read_bytes()
+        assert b"LINE1" in raw
+        # CRLF line endings should be preserved throughout the file
+        assert b"\r\n" in raw
+
+    @pytest.mark.asyncio
+    async def test_trim_fallback(self, tool, tmp_path):
+        f = tmp_path / "indent.py"
+        f.write_text("    def foo():\n        pass\n", encoding="utf-8")
+        result = await tool.execute(
+            path=str(f), old_text="def foo():\n    pass", new_text="def bar():\n    return 1",
+        )
+        assert "Successfully" in result
+        assert "bar" in f.read_text()
+
+    @pytest.mark.asyncio
+    async def test_ambiguous_match(self, tool, tmp_path):
+        f = tmp_path / "dup.py"
+        f.write_text("aaa\nbbb\naaa\nbbb\n", encoding="utf-8")
+        result = await tool.execute(path=str(f), old_text="aaa\nbbb", new_text="xxx")
+        assert "appears" in result.lower() or "Warning" in result
+
+    @pytest.mark.asyncio
+    async def test_replace_all(self, tool, tmp_path):
+        f = tmp_path / "multi.py"
+        f.write_text("foo bar foo bar foo", encoding="utf-8")
+        result = await tool.execute(
+            path=str(f), old_text="foo", new_text="baz", replace_all=True,
+        )
+        assert "Successfully" in result
+        assert f.read_text() == "baz bar baz bar baz"
+
+    @pytest.mark.asyncio
+    async def test_not_found(self, tool, tmp_path):
+        f = tmp_path / "nf.py"
+        f.write_text("hello", encoding="utf-8")
+        result = await tool.execute(path=str(f), old_text="xyz", new_text="abc")
+        assert "Error" in result
+        assert "not found" in result
+
+
+# ---------------------------------------------------------------------------
+# ListDirTool
+# ---------------------------------------------------------------------------
+
+class TestListDirTool:
+
+    @pytest.fixture()
+    def tool(self, tmp_path):
+        return ListDirTool(workspace=tmp_path)
+
+    @pytest.fixture()
+    def populated_dir(self, tmp_path):
+        (tmp_path / "src").mkdir()
+        (tmp_path / "src" / "main.py").write_text("pass")
+        (tmp_path / "src" / "utils.py").write_text("pass")
+        (tmp_path / "README.md").write_text("hi")
+        (tmp_path / ".git").mkdir()
+        (tmp_path / ".git" / "config").write_text("x")
+        (tmp_path / "node_modules").mkdir()
+        (tmp_path / "node_modules" / "pkg").mkdir()
+        return tmp_path
+
+    @pytest.mark.asyncio
+    async def test_basic_list(self, tool, populated_dir):
+        result = await tool.execute(path=str(populated_dir))
+        assert "README.md" in result
+        assert "src" in result
+        # .git and node_modules should be ignored
+        assert ".git" not in result
+        assert "node_modules" not in result
+
+    @pytest.mark.asyncio
+    async def test_recursive(self, tool, populated_dir):
+        result = await tool.execute(path=str(populated_dir), recursive=True)
+        assert "src/main.py" in result
+        assert "src/utils.py" in result
+        assert "README.md" in result
+        # Ignored dirs should not appear
+        assert ".git" not in result
+        assert "node_modules" not in result
+
+    @pytest.mark.asyncio
+    async def test_max_entries_truncation(self, tool, tmp_path):
+        for i in range(10):
+            (tmp_path / f"file_{i}.txt").write_text("x")
+        result = await tool.execute(path=str(tmp_path), max_entries=3)
+        assert "truncated" in result
+        assert "3 of 10" in result
+
+    @pytest.mark.asyncio
+    async def test_empty_dir(self, tool, tmp_path):
+        d = tmp_path / "empty"
+        d.mkdir()
+        result = await tool.execute(path=str(d))
+        assert "empty" in result.lower()
+
+    @pytest.mark.asyncio
+    async def test_not_found(self, tool, tmp_path):
+        result = await tool.execute(path=str(tmp_path / "nope"))
+        assert "Error" in result
+        assert "not found" in result
diff --git a/core/nanobot/tests/test_gemini_thought_signature.py b/core/nanobot/tests/test_gemini_thought_signature.py
new file mode 100644
index 0000000..bc4132c
--- /dev/null
+++ b/core/nanobot/tests/test_gemini_thought_signature.py
@@ -0,0 +1,53 @@
+from types import SimpleNamespace
+
+from nanobot.providers.base import ToolCallRequest
+from nanobot.providers.litellm_provider import LiteLLMProvider
+
+
+def test_litellm_parse_response_preserves_tool_call_provider_fields() -> None:
+    provider = LiteLLMProvider(default_model="gemini/gemini-3-flash")
+
+    response = SimpleNamespace(
+        choices=[
+            SimpleNamespace(
+                finish_reason="tool_calls",
+                message=SimpleNamespace(
+                    content=None,
+                    tool_calls=[
+                        SimpleNamespace(
+                            id="call_123",
+                            function=SimpleNamespace(
+                                name="read_file",
+                                arguments='{"path":"todo.md"}',
+                                provider_specific_fields={"inner": "value"},
+                            ),
+                            provider_specific_fields={"thought_signature": "signed-token"},
+                        )
+                    ],
+                ),
+            )
+        ],
+        usage=None,
+    )
+
+    parsed = provider._parse_response(response)
+
+    assert len(parsed.tool_calls) == 1
+    assert parsed.tool_calls[0].provider_specific_fields == {"thought_signature": "signed-token"}
+    assert parsed.tool_calls[0].function_provider_specific_fields == {"inner": "value"}
+
+
+def test_tool_call_request_serializes_provider_fields() -> None:
+    tool_call = ToolCallRequest(
+        id="abc123xyz",
+        name="read_file",
+        arguments={"path": "todo.md"},
+        provider_specific_fields={"thought_signature": "signed-token"},
+        function_provider_specific_fields={"inner": "value"},
+    )
+
+    message = tool_call.to_openai_tool_call()
+
+    assert message["provider_specific_fields"] == {"thought_signature": "signed-token"}
+    assert message["function"]["provider_specific_fields"] == {"inner": "value"}
+    assert message["function"]["arguments"] == '{"path": "todo.md"}'
diff --git a/core/nanobot/tests/test_heartbeat_service.py b/core/nanobot/tests/test_heartbeat_service.py
new file mode 100644
index 0000000..9ce8912
--- /dev/null
+++ b/core/nanobot/tests/test_heartbeat_service.py
@@ -0,0 +1,160 @@
+import asyncio
+
+import pytest
+
+from nanobot.heartbeat.service import HeartbeatService
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+
+class DummyProvider(LLMProvider):
+    def __init__(self, responses: list[LLMResponse]):
+        super().__init__()
+        self._responses = list(responses)
+        self.calls = 0
+
+    async def chat(self, *args, **kwargs) -> LLMResponse:
+        self.calls += 1
+        if self._responses:
+            return self._responses.pop(0)
+        return LLMResponse(content="", tool_calls=[])
+
+    def get_default_model(self) -> str:
+        return "test-model"
+
+
+@pytest.mark.asyncio
+async def test_start_is_idempotent(tmp_path) -> None:
+    provider = DummyProvider([])
+
+    service = HeartbeatService(
+        workspace=tmp_path,
+        provider=provider,
+        model="openai/gpt-4o-mini",
+        interval_s=9999,
+        enabled=True,
+    )
+
+    await service.start()
+    first_task = service._task
+    await service.start()
+
+    assert service._task is first_task
+
+    service.stop()
+    await asyncio.sleep(0)
+
+
+@pytest.mark.asyncio
+async def test_decide_returns_skip_when_no_tool_call(tmp_path) -> None:
+    provider = DummyProvider([LLMResponse(content="no tool call", tool_calls=[])])
+    service = HeartbeatService(
+        workspace=tmp_path,
+        provider=provider,
+        model="openai/gpt-4o-mini",
+    )
+
+    action, tasks = await service._decide("heartbeat content")
+    assert action == "skip"
+    assert tasks == ""
+
+
+@pytest.mark.asyncio
+async def test_trigger_now_executes_when_decision_is_run(tmp_path) -> None:
+    (tmp_path / "HEARTBEAT.md").write_text("- [ ] do thing", encoding="utf-8")
+
+    provider = DummyProvider([
+        LLMResponse(
+            content="",
+            tool_calls=[
+                ToolCallRequest(
+                    id="hb_1",
+                    name="heartbeat",
+                    arguments={"action": "run", "tasks": "check open tasks"},
+                )
+            ],
+        )
+    ])
+
+    called_with: list[str] = []
+
+    async def _on_execute(tasks: str) -> str:
+        called_with.append(tasks)
+        return "done"
+
+    service = HeartbeatService(
+        workspace=tmp_path,
+        provider=provider,
+        model="openai/gpt-4o-mini",
+        on_execute=_on_execute,
+    )
+
+    result = await service.trigger_now()
+    assert result == "done"
+    assert called_with == ["check open tasks"]
+
+
+@pytest.mark.asyncio
+async def test_trigger_now_returns_none_when_decision_is_skip(tmp_path) -> None:
+    (tmp_path / "HEARTBEAT.md").write_text("- [ ] do thing", encoding="utf-8")
+
+    provider = DummyProvider([
+        LLMResponse(
+            content="",
+            tool_calls=[
+                ToolCallRequest(
+                    id="hb_1",
+                    name="heartbeat",
+                    arguments={"action": "skip"},
+                )
+            ],
+        )
+    ])
+
+    async def _on_execute(tasks: str) -> str:
+        return tasks
+
+    service = HeartbeatService(
+        workspace=tmp_path,
+        provider=provider,
+        model="openai/gpt-4o-mini",
+        on_execute=_on_execute,
+    )
+
+    assert await service.trigger_now() is None
+
+
+@pytest.mark.asyncio
+async def test_decide_retries_transient_error_then_succeeds(tmp_path, monkeypatch) -> None:
+    provider = DummyProvider([
+        LLMResponse(content="429 rate limit", finish_reason="error"),
+        LLMResponse(
+            content="",
+            tool_calls=[
+                ToolCallRequest(
+                    id="hb_1",
+                    name="heartbeat",
+                    arguments={"action": "run", "tasks": "check open tasks"},
+                )
+            ],
+        ),
+    ])
+
+    delays: list[int] = []
+
+    async def _fake_sleep(delay: int) -> None:
+        delays.append(delay)
+
+    monkeypatch.setattr(asyncio, "sleep", _fake_sleep)
+
+    service = HeartbeatService(
+        workspace=tmp_path,
+        provider=provider,
+        model="openai/gpt-4o-mini",
+    )
+
+    action, tasks = await service._decide("heartbeat content")
+
+    assert action == "run"
+    assert tasks == "check open tasks"
+    assert provider.calls == 2
+    assert delays == [1]
diff --git a/core/nanobot/tests/test_loop_consolidation_tokens.py b/core/nanobot/tests/test_loop_consolidation_tokens.py
new file mode 100644
index 0000000..b0f3dda
--- /dev/null
+++ b/core/nanobot/tests/test_loop_consolidation_tokens.py
@@ -0,0 +1,190 @@
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.agent.loop import AgentLoop
+import nanobot.agent.memory as memory_module
+from nanobot.bus.queue import MessageBus
+from nanobot.providers.base import LLMResponse
+
+
+def _make_loop(tmp_path, *, estimated_tokens: int, context_window_tokens: int) -> AgentLoop:
+    provider = MagicMock()
+    provider.get_default_model.return_value = "test-model"
+    provider.estimate_prompt_tokens.return_value = (estimated_tokens, "test-counter")
+    provider.chat_with_retry = AsyncMock(return_value=LLMResponse(content="ok", tool_calls=[]))
+
+    loop = AgentLoop(
+        bus=MessageBus(),
+        provider=provider,
+        workspace=tmp_path,
+        model="test-model",
+        context_window_tokens=context_window_tokens,
+    )
+    loop.tools.get_definitions = MagicMock(return_value=[])
+    return loop
+
+
+@pytest.mark.asyncio
+async def test_prompt_below_threshold_does_not_consolidate(tmp_path) -> None:
+    loop = _make_loop(tmp_path, estimated_tokens=100, context_window_tokens=200)
+    loop.memory_consolidator.consolidate_messages = AsyncMock(return_value=True)  # type: ignore[method-assign]
+
+    await loop.process_direct("hello", session_key="cli:test")
+
+    loop.memory_consolidator.consolidate_messages.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_prompt_above_threshold_triggers_consolidation(tmp_path, monkeypatch) -> None:
+    loop = _make_loop(tmp_path, estimated_tokens=1000, context_window_tokens=200)
+    loop.memory_consolidator.consolidate_messages = AsyncMock(return_value=True)  # type: ignore[method-assign]
+    session = loop.sessions.get_or_create("cli:test")
+    session.messages = [
+        {"role": "user", "content": "u1", "timestamp": "2026-01-01T00:00:00"},
+        {"role": "assistant", "content": "a1", "timestamp": "2026-01-01T00:00:01"},
+        {"role": "user", "content": "u2", "timestamp": "2026-01-01T00:00:02"},
+    ]
+    loop.sessions.save(session)
+    monkeypatch.setattr(memory_module, "estimate_message_tokens", lambda _message: 500)
+
+    await loop.process_direct("hello", session_key="cli:test")
+
+    assert loop.memory_consolidator.consolidate_messages.await_count >= 1
+
+
+@pytest.mark.asyncio
+async def test_prompt_above_threshold_archives_until_next_user_boundary(tmp_path, monkeypatch) -> None:
+    loop = _make_loop(tmp_path, estimated_tokens=1000, context_window_tokens=200)
+    loop.memory_consolidator.consolidate_messages = AsyncMock(return_value=True)  # type: ignore[method-assign]
+
+    session = loop.sessions.get_or_create("cli:test")
+    session.messages = [
+        {"role": "user", "content": "u1", "timestamp": "2026-01-01T00:00:00"},
+        {"role": "assistant", "content": "a1", "timestamp": "2026-01-01T00:00:01"},
+        {"role": "user", "content": "u2", "timestamp": "2026-01-01T00:00:02"},
+        {"role": "assistant", "content": "a2", "timestamp": "2026-01-01T00:00:03"},
+        {"role": "user", "content": "u3", "timestamp": "2026-01-01T00:00:04"},
+    ]
+    loop.sessions.save(session)
+
+    token_map = {"u1": 120, "a1": 120, "u2": 120, "a2": 120, "u3": 120}
+    monkeypatch.setattr(memory_module, "estimate_message_tokens", lambda message: token_map[message["content"]])
+
+    await loop.memory_consolidator.maybe_consolidate_by_tokens(session)
+
+    archived_chunk = loop.memory_consolidator.consolidate_messages.await_args.args[0]
+    assert [message["content"] for message in archived_chunk] == ["u1", "a1", "u2", "a2"]
+    assert session.last_consolidated == 4
+
+
+@pytest.mark.asyncio
+async def test_consolidation_loops_until_target_met(tmp_path, monkeypatch) -> None:
+    """Verify maybe_consolidate_by_tokens keeps looping until under threshold."""
+    loop = _make_loop(tmp_path, estimated_tokens=0, context_window_tokens=200)
+    loop.memory_consolidator.consolidate_messages = AsyncMock(return_value=True)  # type: ignore[method-assign]
+
+    session = loop.sessions.get_or_create("cli:test")
+    session.messages = [
+        {"role": "user", "content": "u1", "timestamp": "2026-01-01T00:00:00"},
+        {"role": "assistant", "content": "a1", "timestamp": "2026-01-01T00:00:01"},
+        {"role": "user", "content": "u2", "timestamp": "2026-01-01T00:00:02"},
+        {"role": "assistant", "content": "a2", "timestamp": "2026-01-01T00:00:03"},
+        {"role": "user", "content": "u3", "timestamp": "2026-01-01T00:00:04"},
+        {"role": "assistant", "content": "a3", "timestamp": "2026-01-01T00:00:05"},
+        {"role": "user", "content": "u4", "timestamp": "2026-01-01T00:00:06"},
+    ]
+    loop.sessions.save(session)
+
+    call_count = [0]
+    def mock_estimate(_session):
+        call_count[0] += 1
+        if call_count[0] == 1:
+            return (500, "test")
+        if call_count[0] == 2:
+            return (300, "test")
+        return (80, "test")
+
+    loop.memory_consolidator.estimate_session_prompt_tokens = mock_estimate  # type: ignore[method-assign]
+    monkeypatch.setattr(memory_module, "estimate_message_tokens", lambda _m: 100)
+
+    await loop.memory_consolidator.maybe_consolidate_by_tokens(session)
+
+    assert loop.memory_consolidator.consolidate_messages.await_count == 2
+    assert session.last_consolidated == 6
+
+
+@pytest.mark.asyncio
+async def test_consolidation_continues_below_trigger_until_half_target(tmp_path, monkeypatch) -> None:
+    """Once triggered, consolidation should continue until it drops below half threshold."""
+    loop = _make_loop(tmp_path, estimated_tokens=0, context_window_tokens=200)
+    loop.memory_consolidator.consolidate_messages = AsyncMock(return_value=True)  # type: ignore[method-assign]
+
+    session = loop.sessions.get_or_create("cli:test")
+    session.messages = [
+        {"role": "user", "content": "u1", "timestamp": "2026-01-01T00:00:00"},
+        {"role": "assistant", "content": "a1", "timestamp": "2026-01-01T00:00:01"},
+        {"role": "user", "content": "u2", "timestamp": "2026-01-01T00:00:02"},
+        {"role": "assistant", "content": "a2", "timestamp": "2026-01-01T00:00:03"},
+        {"role": "user", "content": "u3", "timestamp": "2026-01-01T00:00:04"},
+        {"role": "assistant", "content": "a3", "timestamp": "2026-01-01T00:00:05"},
+        {"role": "user", "content": "u4", "timestamp": "2026-01-01T00:00:06"},
+    ]
+    loop.sessions.save(session)
+
+    call_count = [0]
+
+    def mock_estimate(_session):
+        call_count[0] += 1
+        if call_count[0] == 1:
+            return (500, "test")
+        if call_count[0] == 2:
+            return (150, "test")
+        return (80, "test")
+
+    loop.memory_consolidator.estimate_session_prompt_tokens = mock_estimate  # type: ignore[method-assign]
+    monkeypatch.setattr(memory_module, "estimate_message_tokens", lambda _m: 100)
+
+    await loop.memory_consolidator.maybe_consolidate_by_tokens(session)
+
+    assert loop.memory_consolidator.consolidate_messages.await_count == 2
+    assert session.last_consolidated == 6
+
+
+@pytest.mark.asyncio
+async def test_preflight_consolidation_before_llm_call(tmp_path, monkeypatch) -> None:
+    """Verify preflight consolidation runs before the LLM call in process_direct."""
+    order: list[str] = []
+
+    loop = _make_loop(tmp_path, estimated_tokens=0, context_window_tokens=200)
+
+    async def track_consolidate(messages):
+        order.append("consolidate")
+        return True
+    loop.memory_consolidator.consolidate_messages = track_consolidate  # type: ignore[method-assign]
+
+    async def track_llm(*args, **kwargs):
+        order.append("llm")
+        return LLMResponse(content="ok", tool_calls=[])
+    loop.provider.chat_with_retry = track_llm
+
+    session = loop.sessions.get_or_create("cli:test")
+    session.messages = [
+        {"role": "user", "content": "u1", "timestamp": "2026-01-01T00:00:00"},
+        {"role": "assistant", "content": "a1", "timestamp": "2026-01-01T00:00:01"},
+        {"role": "user", "content": "u2", "timestamp": "2026-01-01T00:00:02"},
+    ]
+    loop.sessions.save(session)
+    monkeypatch.setattr(memory_module, "estimate_message_tokens", lambda _m: 500)
+
+    call_count = [0]
+    def mock_estimate(_session):
+        call_count[0] += 1
+        return (1000 if call_count[0] <= 1 else 80, "test")
+    loop.memory_consolidator.estimate_session_prompt_tokens = mock_estimate  # type: ignore[method-assign]
+
+    await loop.process_direct("hello", session_key="cli:test")
+
+    assert "consolidate" in order
+    assert "llm" in order
+    assert order.index("consolidate") < order.index("llm")
diff --git a/core/nanobot/tests/test_loop_save_turn.py b/core/nanobot/tests/test_loop_save_turn.py
new file mode 100644
index 0000000..aec6d1a
--- /dev/null
+++ b/core/nanobot/tests/test_loop_save_turn.py
@@ -0,0 +1,41 @@
+from nanobot.agent.context import ContextBuilder
+from nanobot.agent.loop import AgentLoop
+from nanobot.session.manager import Session
+
+
+def _mk_loop() -> AgentLoop:
+    loop = AgentLoop.__new__(AgentLoop)
+    loop._TOOL_RESULT_MAX_CHARS = 500
+    return loop
+
+
+def test_save_turn_skips_multimodal_user_when_only_runtime_context() -> None:
+    loop = _mk_loop()
+    session = Session(key="test:runtime-only")
+    runtime = ContextBuilder._RUNTIME_CONTEXT_TAG + "\nCurrent Time: now (UTC)"
+
+    loop._save_turn(
+        session,
+        [{"role": "user", "content": [{"type": "text", "text": runtime}]}],
+        skip=0,
+    )
+    assert session.messages == []
+
+
+def test_save_turn_keeps_image_placeholder_after_runtime_strip() -> None:
+    loop = _mk_loop()
+    session = Session(key="test:image")
+    runtime = ContextBuilder._RUNTIME_CONTEXT_TAG + "\nCurrent Time: now (UTC)"
+
+    loop._save_turn(
+        session,
+        [{
+            "role": "user",
+            "content": [
+                {"type": "text", "text": runtime},
+                {"type": "image_url", "image_url": {"url": "data:image/png;base64,abc"}},
+            ],
+        }],
+        skip=0,
+    )
+    assert session.messages[0]["content"] == [{"type": "text", "text": "[image]"}]
diff --git a/core/nanobot/tests/test_matrix_channel.py b/core/nanobot/tests/test_matrix_channel.py
new file mode 100644
index 0000000..c25b95a
--- /dev/null
+++ b/core/nanobot/tests/test_matrix_channel.py
@@ -0,0 +1,1318 @@
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import nanobot.channels.matrix as matrix_module
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.matrix import (
+    MATRIX_HTML_FORMAT,
+    TYPING_NOTICE_TIMEOUT_MS,
+    MatrixChannel,
+)
+from nanobot.config.schema import MatrixConfig
+
+_ROOM_SEND_UNSET = object()
+
+
+class _DummyTask:
+    def __init__(self) -> None:
+        self.cancelled = False
+
+    def cancel(self) -> None:
+        self.cancelled = True
+
+    def __await__(self):
+        async def _done():
+            return None
+
+        return _done().__await__()
+
+
+class _FakeAsyncClient:
+    def __init__(self, homeserver, user, store_path, config) -> None:
+        self.homeserver = homeserver
+        self.user = user
+        self.store_path = store_path
+        self.config = config
+        self.user_id: str | None = None
+        self.access_token: str | None = None
+        self.device_id: str | None = None
+        self.load_store_called = False
+        self.stop_sync_forever_called = False
+        self.join_calls: list[str] = []
+        self.callbacks: list[tuple[object, object]] = []
+        self.response_callbacks: list[tuple[object, object]] = []
+        self.rooms: dict[str, object] = {}
+        self.room_send_calls: list[dict[str, object]] = []
+        self.typing_calls: list[tuple[str, bool, int]] = []
+        self.download_calls: list[dict[str, object]] = []
+        self.upload_calls: list[dict[str, object]] = []
+        self.download_response: object | None = None
+        self.download_bytes: bytes = b"media"
+        self.download_content_type: str = "application/octet-stream"
+        self.download_filename: str | None = None
+        self.upload_response: object | None = None
+        self.content_repository_config_response: object = SimpleNamespace(upload_size=None)
+        self.raise_on_send = False
+        self.raise_on_typing = False
+        self.raise_on_upload = False
+
+    def add_event_callback(self, callback, event_type) -> None:
+        self.callbacks.append((callback, event_type))
+
+    def add_response_callback(self, callback, response_type) -> None:
+        self.response_callbacks.append((callback, response_type))
+
+    def load_store(self) -> None:
+        self.load_store_called = True
+
+    def stop_sync_forever(self) -> None:
+        self.stop_sync_forever_called = True
+
+    async def join(self, room_id: str) -> None:
+        self.join_calls.append(room_id)
+
+    async def room_send(
+        self,
+        room_id: str,
+        message_type: str,
+        content: dict[str, object],
+        ignore_unverified_devices: object = _ROOM_SEND_UNSET,
+    ) -> None:
+        call: dict[str, object] = {
+            "room_id": room_id,
+            "message_type": message_type,
+            "content": content,
+        }
+        if ignore_unverified_devices is not _ROOM_SEND_UNSET:
+            call["ignore_unverified_devices"] = ignore_unverified_devices
+        self.room_send_calls.append(call)
+        if self.raise_on_send:
+            raise RuntimeError("send failed")
+
+    async def room_typing(
+        self,
+        room_id: str,
+        typing_state: bool = True,
+        timeout: int = 30_000,
+    ) -> None:
+        self.typing_calls.append((room_id, typing_state, timeout))
+        if self.raise_on_typing:
+            raise RuntimeError("typing failed")
+
+    async def download(self, **kwargs):
+        self.download_calls.append(kwargs)
+        if self.download_response is not None:
+            return self.download_response
+        return matrix_module.MemoryDownloadResponse(
+            body=self.download_bytes,
+            content_type=self.download_content_type,
+            filename=self.download_filename,
+        )
+
+    async def upload(
+        self,
+        data_provider,
+        content_type: str | None = None,
+        filename: str | None = None,
+        filesize: int | None = None,
+        encrypt: bool = False,
+    ):
+        if self.raise_on_upload:
+            raise RuntimeError("upload failed")
+        if isinstance(data_provider, (bytes, bytearray)):
+            raise TypeError(
+                f"data_provider type {type(data_provider)!r} is not of a usable type "
+                "(Callable, IOBase)"
+            )
+        self.upload_calls.append(
+            {
+                "data_provider": data_provider,
+                "content_type": content_type,
+                "filename": filename,
+                "filesize": filesize,
+                "encrypt": encrypt,
+            }
+        )
+        if self.upload_response is not None:
+            return self.upload_response
+        if encrypt:
+            return (
+                SimpleNamespace(content_uri="mxc://example.org/uploaded"),
+                {
+                    "v": "v2",
+                    "iv": "iv",
+                    "hashes": {"sha256": "hash"},
+                    "key": {"alg": "A256CTR", "k": "key"},
+                },
+            )
+        return SimpleNamespace(content_uri="mxc://example.org/uploaded"), None
+
+    async def content_repository_config(self):
+        return self.content_repository_config_response
+
+    async def close(self) -> None:
+        return None
+
+
+def _make_config(**kwargs) -> MatrixConfig:
+    kwargs.setdefault("allow_from", ["*"])
+    return MatrixConfig(
+        enabled=True,
+        homeserver="https://matrix.org",
+        access_token="token",
+        user_id="@bot:matrix.org",
+        **kwargs,
+    )
+
+
+@pytest.mark.asyncio
+async def test_start_skips_load_store_when_device_id_missing(
+    monkeypatch, tmp_path
+) -> None:
+    clients: list[_FakeAsyncClient] = []
+
+    def _fake_client(*args, **kwargs) -> _FakeAsyncClient:
+        client = _FakeAsyncClient(*args, **kwargs)
+        clients.append(client)
+        return client
+
+    def _fake_create_task(coro):
+        coro.close()
+        return _DummyTask()
+
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+    monkeypatch.setattr(
+        "nanobot.channels.matrix.AsyncClientConfig",
+        lambda **kwargs: SimpleNamespace(**kwargs),
+    )
+    monkeypatch.setattr("nanobot.channels.matrix.AsyncClient", _fake_client)
+    monkeypatch.setattr(
+        "nanobot.channels.matrix.asyncio.create_task", _fake_create_task
+    )
+
+    channel = MatrixChannel(_make_config(device_id=""), MessageBus())
+    await channel.start()
+
+    assert len(clients) == 1
+    assert clients[0].config.encryption_enabled is True
+    assert clients[0].load_store_called is False
+    assert len(clients[0].callbacks) == 3
+    assert len(clients[0].response_callbacks) == 3
+
+    await channel.stop()
+
+
+@pytest.mark.asyncio
+async def test_register_event_callbacks_uses_media_base_filter() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    channel._register_event_callbacks()
+
+    assert len(client.callbacks) == 3
+    assert client.callbacks[1][0] == channel._on_media_message
+    assert client.callbacks[1][1] == matrix_module.MATRIX_MEDIA_EVENT_FILTER
+
+
+def test_media_event_filter_does_not_match_text_events() -> None:
+    assert not issubclass(matrix_module.RoomMessageText, matrix_module.MATRIX_MEDIA_EVENT_FILTER)
+
+
+@pytest.mark.asyncio
+async def test_start_disables_e2ee_when_configured(
+    monkeypatch, tmp_path
+) -> None:
+    clients: list[_FakeAsyncClient] = []
+
+    def _fake_client(*args, **kwargs) -> _FakeAsyncClient:
+        client = _FakeAsyncClient(*args, **kwargs)
+        clients.append(client)
+        return client
+
+    def _fake_create_task(coro):
+        coro.close()
+        return _DummyTask()
+
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+    monkeypatch.setattr(
+        "nanobot.channels.matrix.AsyncClientConfig",
+        lambda **kwargs: SimpleNamespace(**kwargs),
+    )
+    monkeypatch.setattr("nanobot.channels.matrix.AsyncClient", _fake_client)
+    monkeypatch.setattr(
+        "nanobot.channels.matrix.asyncio.create_task", _fake_create_task
+    )
+
+    channel = MatrixChannel(_make_config(device_id="", e2ee_enabled=False), MessageBus())
+    await channel.start()
+
+    assert len(clients) == 1
+    assert clients[0].config.encryption_enabled is False
+
+    await channel.stop()
+
+
+@pytest.mark.asyncio
+async def test_stop_stops_sync_forever_before_close(monkeypatch) -> None:
+    channel = MatrixChannel(_make_config(device_id="DEVICE"), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    task = _DummyTask()
+
+    channel.client = client
+    channel._sync_task = task
+    channel._running = True
+
+    await channel.stop()
+
+    assert channel._running is False
+    assert client.stop_sync_forever_called is True
+    assert task.cancelled is False
+
+
+@pytest.mark.asyncio
+async def test_room_invite_ignores_when_allow_list_is_empty() -> None:
+    channel = MatrixChannel(_make_config(allow_from=[]), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    room = SimpleNamespace(room_id="!room:matrix.org")
+    event = SimpleNamespace(sender="@alice:matrix.org")
+
+    await channel._on_room_invite(room, event)
+
+    assert client.join_calls == []
+
+
+@pytest.mark.asyncio
+async def test_room_invite_joins_when_sender_allowed() -> None:
+    channel = MatrixChannel(_make_config(allow_from=["@alice:matrix.org"]), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    room = SimpleNamespace(room_id="!room:matrix.org")
+    event = SimpleNamespace(sender="@alice:matrix.org")
+
+    await channel._on_room_invite(room, event)
+
+    assert client.join_calls == ["!room:matrix.org"]
+
+@pytest.mark.asyncio
+async def test_room_invite_respects_allow_list_when_configured() -> None:
+    channel = MatrixChannel(_make_config(allow_from=["@bob:matrix.org"]), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    room = SimpleNamespace(room_id="!room:matrix.org")
+    event = SimpleNamespace(sender="@alice:matrix.org")
+
+    await channel._on_room_invite(room, event)
+
+    assert client.join_calls == []
+
+
+@pytest.mark.asyncio
+async def test_on_message_sets_typing_for_allowed_sender() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[str] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs["sender_id"])
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room")
+    event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={})
+
+    await channel._on_message(room, event)
+
+    assert handled == ["@alice:matrix.org"]
+    assert client.typing_calls == [
+        ("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS),
+    ]
+
+
+@pytest.mark.asyncio
+async def test_typing_keepalive_refreshes_periodically(monkeypatch) -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+    channel._running = True
+
+    monkeypatch.setattr(matrix_module, "TYPING_KEEPALIVE_INTERVAL_MS", 10)
+
+    await channel._start_typing_keepalive("!room:matrix.org")
+    await asyncio.sleep(0.03)
+    await channel._stop_typing_keepalive("!room:matrix.org", clear_typing=True)
+
+    true_updates = [call for call in client.typing_calls if call[1] is True]
+    assert len(true_updates) >= 2
+    assert client.typing_calls[-1] == ("!room:matrix.org", False, TYPING_NOTICE_TIMEOUT_MS)
+
+
+@pytest.mark.asyncio
+async def test_on_message_skips_typing_for_self_message() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room")
+    event = SimpleNamespace(sender="@bot:matrix.org", body="Hello", source={})
+
+    await channel._on_message(room, event)
+
+    assert client.typing_calls == []
+
+
+@pytest.mark.asyncio
+async def test_on_message_skips_typing_for_denied_sender() -> None:
+    channel = MatrixChannel(_make_config(allow_from=["@bob:matrix.org"]), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[str] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs["sender_id"])
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room")
+    event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={})
+
+    await channel._on_message(room, event)
+
+    assert handled == []
+    assert client.typing_calls == []
+
+
+@pytest.mark.asyncio
+async def test_on_message_mention_policy_requires_mx_mentions() -> None:
+    channel = MatrixChannel(_make_config(group_policy="mention"), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[str] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs["sender_id"])
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=3)
+    event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={"content": {}})
+
+    await channel._on_message(room, event)
+
+    assert handled == []
+    assert client.typing_calls == []
+
+
+@pytest.mark.asyncio
+async def test_on_message_mention_policy_accepts_bot_user_mentions() -> None:
+    channel = MatrixChannel(_make_config(group_policy="mention"), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[str] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs["sender_id"])
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=3)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="Hello",
+        source={"content": {"m.mentions": {"user_ids": ["@bot:matrix.org"]}}},
+    )
+
+    await channel._on_message(room, event)
+
+    assert handled == ["@alice:matrix.org"]
+    assert client.typing_calls == [("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+
+@pytest.mark.asyncio
+async def test_on_message_mention_policy_allows_direct_room_without_mentions() -> None:
+    channel = MatrixChannel(_make_config(group_policy="mention"), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[str] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs["sender_id"])
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!dm:matrix.org", display_name="DM", member_count=2)
+    event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={"content": {}})
+
+    await channel._on_message(room, event)
+
+    assert handled == ["@alice:matrix.org"]
+    assert client.typing_calls == [("!dm:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+
+@pytest.mark.asyncio
+async def test_on_message_allowlist_policy_requires_room_id() -> None:
+    channel = MatrixChannel(
+        _make_config(group_policy="allowlist", group_allow_from=["!allowed:matrix.org"]),
+        MessageBus(),
+    )
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[str] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs["chat_id"])
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    denied_room = SimpleNamespace(room_id="!denied:matrix.org", display_name="Denied", member_count=3)
+    event = SimpleNamespace(sender="@alice:matrix.org", body="Hello", source={"content": {}})
+    await channel._on_message(denied_room, event)
+
+    allowed_room = SimpleNamespace(
+        room_id="!allowed:matrix.org",
+        display_name="Allowed",
+        member_count=3,
+    )
+    await channel._on_message(allowed_room, event)
+
+    assert handled == ["!allowed:matrix.org"]
+    assert client.typing_calls == [("!allowed:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+
+@pytest.mark.asyncio
+async def test_on_message_room_mention_requires_opt_in() -> None:
+    channel = MatrixChannel(_make_config(group_policy="mention"), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[str] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs["sender_id"])
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=3)
+    room_mention_event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="Hello everyone",
+        source={"content": {"m.mentions": {"room": True}}},
+    )
+
+    await channel._on_message(room, room_mention_event)
+    assert handled == []
+    assert client.typing_calls == []
+
+    channel.config.allow_room_mentions = True
+    await channel._on_message(room, room_mention_event)
+    assert handled == ["@alice:matrix.org"]
+    assert client.typing_calls == [("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+
+@pytest.mark.asyncio
+async def test_on_message_sets_thread_metadata_when_threaded_event() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[dict[str, object]] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=3)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="Hello",
+        event_id="$reply1",
+        source={
+            "content": {
+                "m.relates_to": {
+                    "rel_type": "m.thread",
+                    "event_id": "$root1",
+                }
+            }
+        },
+    )
+
+    await channel._on_message(room, event)
+
+    assert len(handled) == 1
+    metadata = handled[0]["metadata"]
+    assert metadata["thread_root_event_id"] == "$root1"
+    assert metadata["thread_reply_to_event_id"] == "$reply1"
+    assert metadata["event_id"] == "$reply1"
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_downloads_attachment_and_sets_metadata(
+    monkeypatch, tmp_path
+) -> None:
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.download_bytes = b"image"
+    channel.client = client
+
+    handled: list[dict[str, object]] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="photo.png",
+        url="mxc://example.org/mediaid",
+        event_id="$event1",
+        source={
+            "content": {
+                "msgtype": "m.image",
+                "info": {"mimetype": "image/png", "size": 5},
+            }
+        },
+    )
+
+    await channel._on_media_message(room, event)
+
+    assert len(client.download_calls) == 1
+    assert len(handled) == 1
+    assert client.typing_calls == [("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)]
+
+    media_paths = handled[0]["media"]
+    assert isinstance(media_paths, list) and len(media_paths) == 1
+    media_path = Path(media_paths[0])
+    assert media_path.is_file()
+    assert media_path.read_bytes() == b"image"
+
+    metadata = handled[0]["metadata"]
+    attachments = metadata["attachments"]
+    assert isinstance(attachments, list) and len(attachments) == 1
+    assert attachments[0]["type"] == "image"
+    assert attachments[0]["mxc_url"] == "mxc://example.org/mediaid"
+    assert attachments[0]["path"] == str(media_path)
+    assert "[attachment: " in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_sets_thread_metadata_when_threaded_event(
+    monkeypatch, tmp_path
+) -> None:
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.download_bytes = b"image"
+    channel.client = client
+
+    handled: list[dict[str, object]] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="photo.png",
+        url="mxc://example.org/mediaid",
+        event_id="$event1",
+        source={
+            "content": {
+                "msgtype": "m.image",
+                "info": {"mimetype": "image/png", "size": 5},
+                "m.relates_to": {
+                    "rel_type": "m.thread",
+                    "event_id": "$root1",
+                },
+            }
+        },
+    )
+
+    await channel._on_media_message(room, event)
+
+    assert len(handled) == 1
+    metadata = handled[0]["metadata"]
+    assert metadata["thread_root_event_id"] == "$root1"
+    assert metadata["thread_reply_to_event_id"] == "$event1"
+    assert metadata["event_id"] == "$event1"
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_respects_declared_size_limit(
+    monkeypatch, tmp_path
+) -> None:
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+    channel = MatrixChannel(_make_config(max_media_bytes=3), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    handled: list[dict[str, object]] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="large.bin",
+        url="mxc://example.org/large",
+        event_id="$event2",
+        source={"content": {"msgtype": "m.file", "info": {"size": 10}}},
+    )
+
+    await channel._on_media_message(room, event)
+
+    assert client.download_calls == []
+    assert len(handled) == 1
+    assert handled[0]["media"] == []
+    assert handled[0]["metadata"]["attachments"] == []
+    assert "[attachment: large.bin - too large]" in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_uses_server_limit_when_smaller_than_local_limit(
+    monkeypatch, tmp_path
+) -> None:
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+    channel = MatrixChannel(_make_config(max_media_bytes=10), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.content_repository_config_response = SimpleNamespace(upload_size=3)
+    channel.client = client
+
+    handled: list[dict[str, object]] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="large.bin",
+        url="mxc://example.org/large",
+        event_id="$event2_server",
+        source={"content": {"msgtype": "m.file", "info": {"size": 5}}},
+    )
+
+    await channel._on_media_message(room, event)
+
+    assert client.download_calls == []
+    assert len(handled) == 1
+    assert handled[0]["media"] == []
+    assert handled[0]["metadata"]["attachments"] == []
+    assert "[attachment: large.bin - too large]" in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_handles_download_error(monkeypatch, tmp_path) -> None:
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.download_response = matrix_module.DownloadError("download failed")
+    channel.client = client
+
+    handled: list[dict[str, object]] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="photo.png",
+        url="mxc://example.org/mediaid",
+        event_id="$event3",
+        source={"content": {"msgtype": "m.image"}},
+    )
+
+    await channel._on_media_message(room, event)
+
+    assert len(client.download_calls) == 1
+    assert len(handled) == 1
+    assert handled[0]["media"] == []
+    assert handled[0]["metadata"]["attachments"] == []
+    assert "[attachment: photo.png - download failed]" in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_decrypts_encrypted_media(monkeypatch, tmp_path) -> None:
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+    monkeypatch.setattr(
+        matrix_module,
+        "decrypt_attachment",
+        lambda ciphertext, key, sha256, iv: b"plain",
+    )
+
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.download_bytes = b"cipher"
+    channel.client = client
+
+    handled: list[dict[str, object]] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="secret.txt",
+        url="mxc://example.org/encrypted",
+        event_id="$event4",
+        key={"k": "key"},
+        hashes={"sha256": "hash"},
+        iv="iv",
+        source={"content": {"msgtype": "m.file", "info": {"size": 6}}},
+    )
+
+    await channel._on_media_message(room, event)
+
+    assert len(handled) == 1
+    media_path = Path(handled[0]["media"][0])
+    assert media_path.read_bytes() == b"plain"
+    attachment = handled[0]["metadata"]["attachments"][0]
+    assert attachment["encrypted"] is True
+    assert attachment["size_bytes"] == 5
+
+
+@pytest.mark.asyncio
+async def test_on_media_message_handles_decrypt_error(monkeypatch, tmp_path) -> None:
+    monkeypatch.setattr("nanobot.channels.matrix.get_data_dir", lambda: tmp_path)
+
+    def _raise(*args, **kwargs):
+        raise matrix_module.EncryptionError("boom")
+
+    monkeypatch.setattr(matrix_module, "decrypt_attachment", _raise)
+
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.download_bytes = b"cipher"
+    channel.client = client
+
+    handled: list[dict[str, object]] = []
+
+    async def _fake_handle_message(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = _fake_handle_message  # type: ignore[method-assign]
+
+    room = SimpleNamespace(room_id="!room:matrix.org", display_name="Test room", member_count=2)
+    event = SimpleNamespace(
+        sender="@alice:matrix.org",
+        body="secret.txt",
+        url="mxc://example.org/encrypted",
+        event_id="$event5",
+        key={"k": "key"},
+        hashes={"sha256": "hash"},
+        iv="iv",
+        source={"content": {"msgtype": "m.file"}},
+    )
+
+    await channel._on_media_message(room, event)
+
+    assert len(handled) == 1
+    assert handled[0]["media"] == []
+    assert handled[0]["metadata"]["attachments"] == []
+    assert "[attachment: secret.txt - download failed]" in handled[0]["content"]
+
+
+@pytest.mark.asyncio
+async def test_send_clears_typing_after_send() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content="Hi")
+    )
+
+    assert len(client.room_send_calls) == 1
+    assert client.room_send_calls[0]["content"] == {
+        "msgtype": "m.text",
+        "body": "Hi",
+        "m.mentions": {},
+    }
+    assert client.room_send_calls[0]["ignore_unverified_devices"] is True
+    assert client.typing_calls[-1] == ("!room:matrix.org", False, TYPING_NOTICE_TIMEOUT_MS)
+
+
+@pytest.mark.asyncio
+async def test_send_uploads_media_and_sends_file_event(tmp_path) -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    file_path = tmp_path / "test.txt"
+    file_path.write_text("hello", encoding="utf-8")
+
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content="Please review.",
+            media=[str(file_path)],
+        )
+    )
+
+    assert len(client.upload_calls) == 1
+    assert not isinstance(client.upload_calls[0]["data_provider"], (bytes, bytearray))
+    assert hasattr(client.upload_calls[0]["data_provider"], "read")
+    assert client.upload_calls[0]["filename"] == "test.txt"
+    assert client.upload_calls[0]["filesize"] == 5
+    assert len(client.room_send_calls) == 2
+    assert client.room_send_calls[0]["content"]["msgtype"] == "m.file"
+    assert client.room_send_calls[0]["content"]["url"] == "mxc://example.org/uploaded"
+    assert client.room_send_calls[1]["content"]["body"] == "Please review."
+
+
+@pytest.mark.asyncio
+async def test_send_adds_thread_relates_to_for_thread_metadata() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    metadata = {
+        "thread_root_event_id": "$root1",
+        "thread_reply_to_event_id": "$reply1",
+    }
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content="Hi",
+            metadata=metadata,
+        )
+    )
+
+    content = client.room_send_calls[0]["content"]
+    assert content["m.relates_to"] == {
+        "rel_type": "m.thread",
+        "event_id": "$root1",
+        "m.in_reply_to": {"event_id": "$reply1"},
+        "is_falling_back": True,
+    }
+
+
+@pytest.mark.asyncio
+async def test_send_uses_encrypted_media_payload_in_encrypted_room(tmp_path) -> None:
+    channel = MatrixChannel(_make_config(e2ee_enabled=True), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.rooms["!encrypted:matrix.org"] = SimpleNamespace(encrypted=True)
+    channel.client = client
+
+    file_path = tmp_path / "secret.txt"
+    file_path.write_text("topsecret", encoding="utf-8")
+
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!encrypted:matrix.org",
+            content="",
+            media=[str(file_path)],
+        )
+    )
+
+    assert len(client.upload_calls) == 1
+    assert client.upload_calls[0]["encrypt"] is True
+    assert len(client.room_send_calls) == 1
+    content = client.room_send_calls[0]["content"]
+    assert content["msgtype"] == "m.file"
+    assert "file" in content
+    assert "url" not in content
+    assert content["file"]["url"] == "mxc://example.org/uploaded"
+    assert content["file"]["hashes"]["sha256"] == "hash"
+
+
+@pytest.mark.asyncio
+async def test_send_does_not_parse_attachment_marker_without_media(tmp_path) -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    missing_path = tmp_path / "missing.txt"
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content=f"[attachment: {missing_path}]",
+        )
+    )
+
+    assert client.upload_calls == []
+    assert len(client.room_send_calls) == 1
+    assert client.room_send_calls[0]["content"]["body"] == f"[attachment: {missing_path}]"
+
+
+@pytest.mark.asyncio
+async def test_send_passes_thread_relates_to_to_attachment_upload(monkeypatch) -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+    channel._server_upload_limit_checked = True
+    channel._server_upload_limit_bytes = None
+
+    captured: dict[str, object] = {}
+
+    async def _fake_upload_and_send_attachment(
+        *,
+        room_id: str,
+        path: Path,
+        limit_bytes: int,
+        relates_to: dict[str, object] | None = None,
+    ) -> str | None:
+        captured["relates_to"] = relates_to
+        return None
+
+    monkeypatch.setattr(channel, "_upload_and_send_attachment", _fake_upload_and_send_attachment)
+
+    metadata = {
+        "thread_root_event_id": "$root1",
+        "thread_reply_to_event_id": "$reply1",
+    }
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content="Hi",
+            media=["/tmp/fake.txt"],
+            metadata=metadata,
+        )
+    )
+
+    assert captured["relates_to"] == {
+        "rel_type": "m.thread",
+        "event_id": "$root1",
+        "m.in_reply_to": {"event_id": "$reply1"},
+        "is_falling_back": True,
+    }
+
+
+@pytest.mark.asyncio
+async def test_send_workspace_restriction_blocks_external_attachment(tmp_path) -> None:
+    workspace = tmp_path / "workspace"
+    workspace.mkdir()
+    file_path = tmp_path / "external.txt"
+    file_path.write_text("outside", encoding="utf-8")
+
+    channel = MatrixChannel(
+        _make_config(),
+        MessageBus(),
+        restrict_to_workspace=True,
+        workspace=workspace,
+    )
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content="",
+            media=[str(file_path)],
+        )
+    )
+
+    assert client.upload_calls == []
+    assert len(client.room_send_calls) == 1
+    assert client.room_send_calls[0]["content"]["body"] == "[attachment: external.txt - upload failed]"
+
+
+@pytest.mark.asyncio
+async def test_send_handles_upload_exception_and_reports_failure(tmp_path) -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.raise_on_upload = True
+    channel.client = client
+
+    file_path = tmp_path / "broken.txt"
+    file_path.write_text("hello", encoding="utf-8")
+
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content="Please review.",
+            media=[str(file_path)],
+        )
+    )
+
+    assert len(client.upload_calls) == 0
+    assert len(client.room_send_calls) == 1
+    assert (
+        client.room_send_calls[0]["content"]["body"]
+        == "Please review.\n[attachment: broken.txt - upload failed]"
+    )
+
+
+@pytest.mark.asyncio
+async def test_send_uses_server_upload_limit_when_smaller_than_local_limit(tmp_path) -> None:
+    channel = MatrixChannel(_make_config(max_media_bytes=10), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.content_repository_config_response = SimpleNamespace(upload_size=3)
+    channel.client = client
+
+    file_path = tmp_path / "tiny.txt"
+    file_path.write_text("hello", encoding="utf-8")
+
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content="",
+            media=[str(file_path)],
+        )
+    )
+
+    assert client.upload_calls == []
+    assert len(client.room_send_calls) == 1
+    assert client.room_send_calls[0]["content"]["body"] == "[attachment: tiny.txt - too large]"
+
+
+@pytest.mark.asyncio
+async def test_send_blocks_all_outbound_media_when_limit_is_zero(tmp_path) -> None:
+    channel = MatrixChannel(_make_config(max_media_bytes=0), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    file_path = tmp_path / "empty.txt"
+    file_path.write_bytes(b"")
+
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content="",
+            media=[str(file_path)],
+        )
+    )
+
+    assert client.upload_calls == []
+    assert len(client.room_send_calls) == 1
+    assert client.room_send_calls[0]["content"]["body"] == "[attachment: empty.txt - too large]"
+
+
+@pytest.mark.asyncio
+async def test_send_omits_ignore_unverified_devices_when_e2ee_disabled() -> None:
+    channel = MatrixChannel(_make_config(e2ee_enabled=False), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content="Hi")
+    )
+
+    assert len(client.room_send_calls) == 1
+    assert "ignore_unverified_devices" not in client.room_send_calls[0]
+
+
+@pytest.mark.asyncio
+async def test_send_stops_typing_keepalive_task() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+    channel._running = True
+
+    await channel._start_typing_keepalive("!room:matrix.org")
+    assert "!room:matrix.org" in channel._typing_tasks
+
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content="Hi")
+    )
+
+    assert "!room:matrix.org" not in channel._typing_tasks
+    assert client.typing_calls[-1] == ("!room:matrix.org", False, TYPING_NOTICE_TIMEOUT_MS)
+
+
+@pytest.mark.asyncio
+async def test_send_progress_keeps_typing_keepalive_running() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+    channel._running = True
+
+    await channel._start_typing_keepalive("!room:matrix.org")
+    assert "!room:matrix.org" in channel._typing_tasks
+
+    await channel.send(
+        OutboundMessage(
+            channel="matrix",
+            chat_id="!room:matrix.org",
+            content="working...",
+            metadata={"_progress": True, "_progress_kind": "reasoning"},
+        )
+    )
+
+    assert "!room:matrix.org" in channel._typing_tasks
+    assert client.typing_calls[-1] == ("!room:matrix.org", True, TYPING_NOTICE_TIMEOUT_MS)
+
+    await channel.stop()
+
+
+@pytest.mark.asyncio
+async def test_send_clears_typing_when_send_fails() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    client.raise_on_send = True
+    channel.client = client
+
+    with pytest.raises(RuntimeError, match="send failed"):
+        await channel.send(
+            OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content="Hi")
+        )
+
+    assert client.typing_calls[-1] == ("!room:matrix.org", False, TYPING_NOTICE_TIMEOUT_MS)
+
+
+@pytest.mark.asyncio
+async def test_send_adds_formatted_body_for_markdown() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    markdown_text = "# Headline\n\n- [x] done\n\n| A | B |\n| - | - |\n| 1 | 2 |"
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+    )
+
+    content = client.room_send_calls[0]["content"]
+    assert content["msgtype"] == "m.text"
+    assert content["body"] == markdown_text
+    assert content["m.mentions"] == {}
+    assert content["format"] == MATRIX_HTML_FORMAT
+    assert "
Headline
" in str(content["formatted_body"])
+    assert "" in str(content["formatted_body"])
+    assert "
  • [x] done
    • " in str(content["formatted_body"])
+
+
+@pytest.mark.asyncio
+async def test_send_adds_formatted_body_for_inline_url_superscript_subscript() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    markdown_text = "Visit https://example.com and x^2^ plus H~2~O."
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+    )
+
+    content = client.room_send_calls[0]["content"]
+    assert content["msgtype"] == "m.text"
+    assert content["body"] == markdown_text
+    assert content["m.mentions"] == {}
+    assert content["format"] == MATRIX_HTML_FORMAT
+    assert '' in str(
+        content["formatted_body"]
+    )
+    assert "2" in str(content["formatted_body"])
+    assert "2" in str(content["formatted_body"])
+
+
+@pytest.mark.asyncio
+async def test_send_sanitizes_disallowed_link_scheme() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    markdown_text = "[click](javascript:alert(1))"
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+    )
+
+    formatted_body = str(client.room_send_calls[0]["content"]["formatted_body"])
+    assert "javascript:" not in formatted_body
+    assert "x'
+    cleaned_html = matrix_module.MATRIX_HTML_CLEANER.clean(dirty_html)
+
+    assert " None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    markdown_text = "![ok](mxc://example.org/mediaid) ![no](https://example.com/a.png)"
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+    )
+
+    formatted_body = str(client.room_send_calls[0]["content"]["formatted_body"])
+    assert 'src="mxc://example.org/mediaid"' in formatted_body
+    assert 'src="https://example.com/a.png"' not in formatted_body
+
+
+@pytest.mark.asyncio
+async def test_send_falls_back_to_plaintext_when_markdown_render_fails(monkeypatch) -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    def _raise(text: str) -> str:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(matrix_module, "MATRIX_MARKDOWN", _raise)
+    markdown_text = "# Headline"
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=markdown_text)
+    )
+
+    content = client.room_send_calls[0]["content"]
+    assert content == {"msgtype": "m.text", "body": markdown_text, "m.mentions": {}}
+
+
+@pytest.mark.asyncio
+async def test_send_keeps_plaintext_only_for_plain_text() -> None:
+    channel = MatrixChannel(_make_config(), MessageBus())
+    client = _FakeAsyncClient("", "", "", None)
+    channel.client = client
+
+    text = "just a normal sentence without markdown markers"
+    await channel.send(
+        OutboundMessage(channel="matrix", chat_id="!room:matrix.org", content=text)
+    )
+
+    assert client.room_send_calls[0]["content"] == {
+        "msgtype": "m.text",
+        "body": text,
+        "m.mentions": {},
+    }
diff --git a/core/nanobot/tests/test_mcp_tool.py b/core/nanobot/tests/test_mcp_tool.py
new file mode 100644
index 0000000..bf68425
--- /dev/null
+++ b/core/nanobot/tests/test_mcp_tool.py
@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from types import ModuleType, SimpleNamespace
+
+import pytest
+
+from nanobot.agent.tools.mcp import MCPToolWrapper
+
+
+class _FakeTextContent:
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+
+@pytest.fixture(autouse=True)
+def _fake_mcp_module(monkeypatch: pytest.MonkeyPatch) -> None:
+    mod = ModuleType("mcp")
+    mod.types = SimpleNamespace(TextContent=_FakeTextContent)
+    monkeypatch.setitem(sys.modules, "mcp", mod)
+
+
+def _make_wrapper(session: object, *, timeout: float = 0.1) -> MCPToolWrapper:
+    tool_def = SimpleNamespace(
+        name="demo",
+        description="demo tool",
+        inputSchema={"type": "object", "properties": {}},
+    )
+    return MCPToolWrapper(session, "test", tool_def, tool_timeout=timeout)
+
+
+@pytest.mark.asyncio
+async def test_execute_returns_text_blocks() -> None:
+    async def call_tool(_name: str, arguments: dict) -> object:
+        assert arguments == {"value": 1}
+        return SimpleNamespace(content=[_FakeTextContent("hello"), 42])
+
+    wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool))
+
+    result = await wrapper.execute(value=1)
+
+    assert result == "hello\n42"
+
+
+@pytest.mark.asyncio
+async def test_execute_returns_timeout_message() -> None:
+    async def call_tool(_name: str, arguments: dict) -> object:
+        await asyncio.sleep(1)
+        return SimpleNamespace(content=[])
+
+    wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool), timeout=0.01)
+
+    result = await wrapper.execute()
+
+    assert result == "(MCP tool call timed out after 0.01s)"
+
+
+@pytest.mark.asyncio
+async def test_execute_handles_server_cancelled_error() -> None:
+    async def call_tool(_name: str, arguments: dict) -> object:
+        raise asyncio.CancelledError()
+
+    wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool))
+
+    result = await wrapper.execute()
+
+    assert result == "(MCP tool call was cancelled)"
+
+
+@pytest.mark.asyncio
+async def test_execute_re_raises_external_cancellation() -> None:
+    started = asyncio.Event()
+
+    async def call_tool(_name: str, arguments: dict) -> object:
+        started.set()
+        await asyncio.sleep(60)
+        return SimpleNamespace(content=[])
+
+    wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool), timeout=10)
+    task = asyncio.create_task(wrapper.execute())
+    await started.wait()
+
+    task.cancel()
+
+    with pytest.raises(asyncio.CancelledError):
+        await task
+
+
+@pytest.mark.asyncio
+async def test_execute_handles_generic_exception() -> None:
+    async def call_tool(_name: str, arguments: dict) -> object:
+        raise RuntimeError("boom")
+
+    wrapper = _make_wrapper(SimpleNamespace(call_tool=call_tool))
+
+    result = await wrapper.execute()
+
+    assert result == "(MCP tool call failed: RuntimeError)"
diff --git a/core/nanobot/tests/test_memory_consolidation_types.py b/core/nanobot/tests/test_memory_consolidation_types.py
new file mode 100644
index 0000000..69be858
--- /dev/null
+++ b/core/nanobot/tests/test_memory_consolidation_types.py
@@ -0,0 +1,290 @@
+"""Test MemoryStore.consolidate() handles non-string tool call arguments.
+
+Regression test for https://github.com/HKUDS/nanobot/issues/1042
+When memory consolidation receives dict values instead of strings from the LLM
+tool call response, it should serialize them to JSON instead of raising TypeError.
+"""
+
+import json
+from pathlib import Path
+from unittest.mock import AsyncMock
+
+import pytest
+
+from nanobot.agent.memory import MemoryStore
+from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
+
+
+def _make_messages(message_count: int = 30):
+    """Create a list of mock messages."""
+    return [
+        {"role": "user", "content": f"msg{i}", "timestamp": "2026-01-01 00:00"}
+        for i in range(message_count)
+    ]
+
+
+def _make_tool_response(history_entry, memory_update):
+    """Create an LLMResponse with a save_memory tool call."""
+    return LLMResponse(
+        content=None,
+        tool_calls=[
+            ToolCallRequest(
+                id="call_1",
+                name="save_memory",
+                arguments={
+                    "history_entry": history_entry,
+                    "memory_update": memory_update,
+                },
+            )
+        ],
+    )
+
+
+class ScriptedProvider(LLMProvider):
+    def __init__(self, responses: list[LLMResponse]):
+        super().__init__()
+        self._responses = list(responses)
+        self.calls = 0
+
+    async def chat(self, *args, **kwargs) -> LLMResponse:
+        self.calls += 1
+        if self._responses:
+            return self._responses.pop(0)
+        return LLMResponse(content="", tool_calls=[])
+
+    def get_default_model(self) -> str:
+        return "test-model"
+
+
+class TestMemoryConsolidationTypeHandling:
+    """Test that consolidation handles various argument types correctly."""
+
+    @pytest.mark.asyncio
+    async def test_string_arguments_work(self, tmp_path: Path) -> None:
+        """Normal case: LLM returns string arguments."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+        provider.chat = AsyncMock(
+            return_value=_make_tool_response(
+                history_entry="[2026-01-01] User discussed testing.",
+                memory_update="# Memory\nUser likes testing.",
+            )
+        )
+        provider.chat_with_retry = provider.chat
+        messages = _make_messages(message_count=60)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is True
+        assert store.history_file.exists()
+        assert "[2026-01-01] User discussed testing." in store.history_file.read_text()
+        assert "User likes testing." in store.memory_file.read_text()
+
+    @pytest.mark.asyncio
+    async def test_dict_arguments_serialized_to_json(self, tmp_path: Path) -> None:
+        """Issue #1042: LLM returns dict instead of string — must not raise TypeError."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+        provider.chat = AsyncMock(
+            return_value=_make_tool_response(
+                history_entry={"timestamp": "2026-01-01", "summary": "User discussed testing."},
+                memory_update={"facts": ["User likes testing"], "topics": ["testing"]},
+            )
+        )
+        provider.chat_with_retry = provider.chat
+        messages = _make_messages(message_count=60)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is True
+        assert store.history_file.exists()
+        history_content = store.history_file.read_text()
+        parsed = json.loads(history_content.strip())
+        assert parsed["summary"] == "User discussed testing."
+
+        memory_content = store.memory_file.read_text()
+        parsed_mem = json.loads(memory_content)
+        assert "User likes testing" in parsed_mem["facts"]
+
+    @pytest.mark.asyncio
+    async def test_string_arguments_as_raw_json(self, tmp_path: Path) -> None:
+        """Some providers return arguments as a JSON string instead of parsed dict."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+
+        # Simulate arguments being a JSON string (not yet parsed)
+        response = LLMResponse(
+            content=None,
+            tool_calls=[
+                ToolCallRequest(
+                    id="call_1",
+                    name="save_memory",
+                    arguments=json.dumps({
+                        "history_entry": "[2026-01-01] User discussed testing.",
+                        "memory_update": "# Memory\nUser likes testing.",
+                    }),
+                )
+            ],
+        )
+        provider.chat = AsyncMock(return_value=response)
+        provider.chat_with_retry = provider.chat
+        messages = _make_messages(message_count=60)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is True
+        assert "User discussed testing." in store.history_file.read_text()
+
+    @pytest.mark.asyncio
+    async def test_no_tool_call_returns_false(self, tmp_path: Path) -> None:
+        """When LLM doesn't use the save_memory tool, return False."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+        provider.chat = AsyncMock(
+            return_value=LLMResponse(content="I summarized the conversation.", tool_calls=[])
+        )
+        provider.chat_with_retry = provider.chat
+        messages = _make_messages(message_count=60)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is False
+        assert not store.history_file.exists()
+
+    @pytest.mark.asyncio
+    async def test_skips_when_message_chunk_is_empty(self, tmp_path: Path) -> None:
+        """Consolidation should be a no-op when the selected chunk is empty."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+        provider.chat_with_retry = provider.chat
+        messages: list[dict] = []
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is True
+        provider.chat.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_list_arguments_extracts_first_dict(self, tmp_path: Path) -> None:
+        """Some providers return arguments as a list - extract first element if it's a dict."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+
+        # Simulate arguments being a list containing a dict
+        response = LLMResponse(
+            content=None,
+            tool_calls=[
+                ToolCallRequest(
+                    id="call_1",
+                    name="save_memory",
+                    arguments=[{
+                        "history_entry": "[2026-01-01] User discussed testing.",
+                        "memory_update": "# Memory\nUser likes testing.",
+                    }],
+                )
+            ],
+        )
+        provider.chat = AsyncMock(return_value=response)
+        provider.chat_with_retry = provider.chat
+        messages = _make_messages(message_count=60)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is True
+        assert "User discussed testing." in store.history_file.read_text()
+        assert "User likes testing." in store.memory_file.read_text()
+
+    @pytest.mark.asyncio
+    async def test_list_arguments_empty_list_returns_false(self, tmp_path: Path) -> None:
+        """Empty list arguments should return False."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+
+        response = LLMResponse(
+            content=None,
+            tool_calls=[
+                ToolCallRequest(
+                    id="call_1",
+                    name="save_memory",
+                    arguments=[],
+                )
+            ],
+        )
+        provider.chat = AsyncMock(return_value=response)
+        provider.chat_with_retry = provider.chat
+        messages = _make_messages(message_count=60)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_list_arguments_non_dict_content_returns_false(self, tmp_path: Path) -> None:
+        """List with non-dict content should return False."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+
+        response = LLMResponse(
+            content=None,
+            tool_calls=[
+                ToolCallRequest(
+                    id="call_1",
+                    name="save_memory",
+                    arguments=["string", "content"],
+                )
+            ],
+        )
+        provider.chat = AsyncMock(return_value=response)
+        provider.chat_with_retry = provider.chat
+        messages = _make_messages(message_count=60)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is False
+
+    @pytest.mark.asyncio
+    async def test_retries_transient_error_then_succeeds(self, tmp_path: Path, monkeypatch) -> None:
+        store = MemoryStore(tmp_path)
+        provider = ScriptedProvider([
+            LLMResponse(content="503 server error", finish_reason="error"),
+            _make_tool_response(
+                history_entry="[2026-01-01] User discussed testing.",
+                memory_update="# Memory\nUser likes testing.",
+            ),
+        ])
+        messages = _make_messages(message_count=60)
+        delays: list[int] = []
+
+        async def _fake_sleep(delay: int) -> None:
+            delays.append(delay)
+
+        monkeypatch.setattr("nanobot.providers.base.asyncio.sleep", _fake_sleep)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is True
+        assert provider.calls == 2
+        assert delays == [1]
+
+    @pytest.mark.asyncio
+    async def test_consolidation_delegates_to_provider_defaults(self, tmp_path: Path) -> None:
+        """Consolidation no longer passes generation params — the provider owns them."""
+        store = MemoryStore(tmp_path)
+        provider = AsyncMock()
+        provider.chat_with_retry = AsyncMock(
+            return_value=_make_tool_response(
+                history_entry="[2026-01-01] User discussed testing.",
+                memory_update="# Memory\nUser likes testing.",
+            )
+        )
+        messages = _make_messages(message_count=60)
+
+        result = await store.consolidate(messages, provider, "test-model")
+
+        assert result is True
+        provider.chat_with_retry.assert_awaited_once()
+        _, kwargs = provider.chat_with_retry.await_args
+        assert kwargs["model"] == "test-model"
+        assert "temperature" not in kwargs
+        assert "max_tokens" not in kwargs
+        assert "reasoning_effort" not in kwargs
diff --git a/core/nanobot/tests/test_message_tool.py b/core/nanobot/tests/test_message_tool.py
new file mode 100644
index 0000000..dc8e11d
--- /dev/null
+++ b/core/nanobot/tests/test_message_tool.py
@@ -0,0 +1,10 @@
+import pytest
+
+from nanobot.agent.tools.message import MessageTool
+
+
+@pytest.mark.asyncio
+async def test_message_tool_returns_error_when_no_target_context() -> None:
+    tool = MessageTool()
+    result = await tool.execute(content="test")
+    assert result == "Error: No target channel/chat specified"
diff --git a/core/nanobot/tests/test_message_tool_suppress.py b/core/nanobot/tests/test_message_tool_suppress.py
new file mode 100644
index 0000000..1091de4
--- /dev/null
+++ b/core/nanobot/tests/test_message_tool_suppress.py
@@ -0,0 +1,132 @@
+"""Test message tool suppress logic for final replies."""
+
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nanobot.agent.loop import AgentLoop
+from nanobot.agent.tools.message import MessageTool
+from nanobot.bus.events import InboundMessage, OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.providers.base import LLMResponse, ToolCallRequest
+
+
+def _make_loop(tmp_path: Path) -> AgentLoop:
+    bus = MessageBus()
+    provider = MagicMock()
+    provider.get_default_model.return_value = "test-model"
+    return AgentLoop(bus=bus, provider=provider, workspace=tmp_path, model="test-model")
+
+
+class TestMessageToolSuppressLogic:
+    """Final reply suppressed only when message tool sends to the same target."""
+
+    @pytest.mark.asyncio
+    async def test_suppress_when_sent_to_same_target(self, tmp_path: Path) -> None:
+        loop = _make_loop(tmp_path)
+        tool_call = ToolCallRequest(
+            id="call1", name="message",
+            arguments={"content": "Hello", "channel": "feishu", "chat_id": "chat123"},
+        )
+        calls = iter([
+            LLMResponse(content="", tool_calls=[tool_call]),
+            LLMResponse(content="Done", tool_calls=[]),
+        ])
+        loop.provider.chat_with_retry = AsyncMock(side_effect=lambda *a, **kw: next(calls))
+        loop.tools.get_definitions = MagicMock(return_value=[])
+
+        sent: list[OutboundMessage] = []
+        mt = loop.tools.get("message")
+        if isinstance(mt, MessageTool):
+            mt.set_send_callback(AsyncMock(side_effect=lambda m: sent.append(m)))
+
+        msg = InboundMessage(channel="feishu", sender_id="user1", chat_id="chat123", content="Send")
+        result = await loop._process_message(msg)
+
+        assert len(sent) == 1
+        assert result is None  # suppressed
+
+    @pytest.mark.asyncio
+    async def test_not_suppress_when_sent_to_different_target(self, tmp_path: Path) -> None:
+        loop = _make_loop(tmp_path)
+        tool_call = ToolCallRequest(
+            id="call1", name="message",
+            arguments={"content": "Email content", "channel": "email", "chat_id": "user@example.com"},
+        )
+        calls = iter([
+            LLMResponse(content="", tool_calls=[tool_call]),
+            LLMResponse(content="I've sent the email.", tool_calls=[]),
+        ])
+        loop.provider.chat_with_retry = AsyncMock(side_effect=lambda *a, **kw: next(calls))
+        loop.tools.get_definitions = MagicMock(return_value=[])
+
+        sent: list[OutboundMessage] = []
+        mt = loop.tools.get("message")
+        if isinstance(mt, MessageTool):
+            mt.set_send_callback(AsyncMock(side_effect=lambda m: sent.append(m)))
+
+        msg = InboundMessage(channel="feishu", sender_id="user1", chat_id="chat123", content="Send email")
+        result = await loop._process_message(msg)
+
+        assert len(sent) == 1
+        assert sent[0].channel == "email"
+        assert result is not None  # not suppressed
+        assert result.channel == "feishu"
+
+    @pytest.mark.asyncio
+    async def test_not_suppress_when_no_message_tool_used(self, tmp_path: Path) -> None:
+        loop = _make_loop(tmp_path)
+        loop.provider.chat_with_retry = AsyncMock(return_value=LLMResponse(content="Hello!", tool_calls=[]))
+        loop.tools.get_definitions = MagicMock(return_value=[])
+
+        msg = InboundMessage(channel="feishu", sender_id="user1", chat_id="chat123", content="Hi")
+        result = await loop._process_message(msg)
+
+        assert result is not None
+        assert "Hello" in result.content
+
+    async def test_progress_hides_internal_reasoning(self, tmp_path: Path) -> None:
+        loop = _make_loop(tmp_path)
+        tool_call = ToolCallRequest(id="call1", name="read_file", arguments={"path": "foo.txt"})
+        calls = iter([
+            LLMResponse(
+                content="Visiblehidden",
+                tool_calls=[tool_call],
+                reasoning_content="secret reasoning",
+                thinking_blocks=[{"signature": "sig", "thought": "secret thought"}],
+            ),
+            LLMResponse(content="Done", tool_calls=[]),
+        ])
+        loop.provider.chat_with_retry = AsyncMock(side_effect=lambda *a, **kw: next(calls))
+        loop.tools.get_definitions = MagicMock(return_value=[])
+        loop.tools.execute = AsyncMock(return_value="ok")
+
+        progress: list[tuple[str, bool]] = []
+
+        async def on_progress(content: str, *, tool_hint: bool = False) -> None:
+            progress.append((content, tool_hint))
+
+        final_content, _, _ = await loop._run_agent_loop([], on_progress=on_progress)
+
+        assert final_content == "Done"
+        assert progress == [
+            ("Visible", False),
+            ('read_file("foo.txt")', True),
+        ]
+
+
+class TestMessageToolTurnTracking:
+
+    def test_sent_in_turn_tracks_same_target(self) -> None:
+        tool = MessageTool()
+        tool.set_context("feishu", "chat1")
+        assert not tool._sent_in_turn
+        tool._sent_in_turn = True
+        assert tool._sent_in_turn
+
+    def test_start_turn_resets(self) -> None:
+        tool = MessageTool()
+        tool._sent_in_turn = True
+        tool.start_turn()
+        assert not tool._sent_in_turn
diff --git a/core/nanobot/tests/test_provider_retry.py b/core/nanobot/tests/test_provider_retry.py
new file mode 100644
index 0000000..2420399
--- /dev/null
+++ b/core/nanobot/tests/test_provider_retry.py
@@ -0,0 +1,125 @@
+import asyncio
+
+import pytest
+
+from nanobot.providers.base import GenerationSettings, LLMProvider, LLMResponse
+
+
+class ScriptedProvider(LLMProvider):
+    def __init__(self, responses):
+        super().__init__()
+        self._responses = list(responses)
+        self.calls = 0
+        self.last_kwargs: dict = {}
+
+    async def chat(self, *args, **kwargs) -> LLMResponse:
+        self.calls += 1
+        self.last_kwargs = kwargs
+        response = self._responses.pop(0)
+        if isinstance(response, BaseException):
+            raise response
+        return response
+
+    def get_default_model(self) -> str:
+        return "test-model"
+
+
+@pytest.mark.asyncio
+async def test_chat_with_retry_retries_transient_error_then_succeeds(monkeypatch) -> None:
+    provider = ScriptedProvider([
+        LLMResponse(content="429 rate limit", finish_reason="error"),
+        LLMResponse(content="ok"),
+    ])
+    delays: list[int] = []
+
+    async def _fake_sleep(delay: int) -> None:
+        delays.append(delay)
+
+    monkeypatch.setattr("nanobot.providers.base.asyncio.sleep", _fake_sleep)
+
+    response = await provider.chat_with_retry(messages=[{"role": "user", "content": "hello"}])
+
+    assert response.finish_reason == "stop"
+    assert response.content == "ok"
+    assert provider.calls == 2
+    assert delays == [1]
+
+
+@pytest.mark.asyncio
+async def test_chat_with_retry_does_not_retry_non_transient_error(monkeypatch) -> None:
+    provider = ScriptedProvider([
+        LLMResponse(content="401 unauthorized", finish_reason="error"),
+    ])
+    delays: list[int] = []
+
+    async def _fake_sleep(delay: int) -> None:
+        delays.append(delay)
+
+    monkeypatch.setattr("nanobot.providers.base.asyncio.sleep", _fake_sleep)
+
+    response = await provider.chat_with_retry(messages=[{"role": "user", "content": "hello"}])
+
+    assert response.content == "401 unauthorized"
+    assert provider.calls == 1
+    assert delays == []
+
+
+@pytest.mark.asyncio
+async def test_chat_with_retry_returns_final_error_after_retries(monkeypatch) -> None:
+    provider = ScriptedProvider([
+        LLMResponse(content="429 rate limit a", finish_reason="error"),
+        LLMResponse(content="429 rate limit b", finish_reason="error"),
+        LLMResponse(content="429 rate limit c", finish_reason="error"),
+        LLMResponse(content="503 final server error", finish_reason="error"),
+    ])
+    delays: list[int] = []
+
+    async def _fake_sleep(delay: int) -> None:
+        delays.append(delay)
+
+    monkeypatch.setattr("nanobot.providers.base.asyncio.sleep", _fake_sleep)
+
+    response = await provider.chat_with_retry(messages=[{"role": "user", "content": "hello"}])
+
+    assert response.content == "503 final server error"
+    assert provider.calls == 4
+    assert delays == [1, 2, 4]
+
+
+@pytest.mark.asyncio
+async def test_chat_with_retry_preserves_cancelled_error() -> None:
+    provider = ScriptedProvider([asyncio.CancelledError()])
+
+    with pytest.raises(asyncio.CancelledError):
+        await provider.chat_with_retry(messages=[{"role": "user", "content": "hello"}])
+
+
+@pytest.mark.asyncio
+async def test_chat_with_retry_uses_provider_generation_defaults() -> None:
+    """When callers omit generation params, provider.generation defaults are used."""
+    provider = ScriptedProvider([LLMResponse(content="ok")])
+    provider.generation = GenerationSettings(temperature=0.2, max_tokens=321, reasoning_effort="high")
+
+    await provider.chat_with_retry(messages=[{"role": "user", "content": "hello"}])
+
+    assert provider.last_kwargs["temperature"] == 0.2
+    assert provider.last_kwargs["max_tokens"] == 321
+    assert provider.last_kwargs["reasoning_effort"] == "high"
+
+
+@pytest.mark.asyncio
+async def test_chat_with_retry_explicit_override_beats_defaults() -> None:
+    """Explicit kwargs should override provider.generation defaults."""
+    provider = ScriptedProvider([LLMResponse(content="ok")])
+    provider.generation = GenerationSettings(temperature=0.2, max_tokens=321, reasoning_effort="high")
+
+    await provider.chat_with_retry(
+        messages=[{"role": "user", "content": "hello"}],
+        temperature=0.9,
+        max_tokens=9999,
+        reasoning_effort="low",
+    )
+
+    assert provider.last_kwargs["temperature"] == 0.9
+    assert provider.last_kwargs["max_tokens"] == 9999
+    assert provider.last_kwargs["reasoning_effort"] == "low"
diff --git a/core/nanobot/tests/test_qq_channel.py b/core/nanobot/tests/test_qq_channel.py
new file mode 100644
index 0000000..90b4e60
--- /dev/null
+++ b/core/nanobot/tests/test_qq_channel.py
@@ -0,0 +1,66 @@
+from types import SimpleNamespace
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.qq import QQChannel
+from nanobot.config.schema import QQConfig
+
+
+class _FakeApi:
+    def __init__(self) -> None:
+        self.c2c_calls: list[dict] = []
+        self.group_calls: list[dict] = []
+
+    async def post_c2c_message(self, **kwargs) -> None:
+        self.c2c_calls.append(kwargs)
+
+    async def post_group_message(self, **kwargs) -> None:
+        self.group_calls.append(kwargs)
+
+
+class _FakeClient:
+    def __init__(self) -> None:
+        self.api = _FakeApi()
+
+
+@pytest.mark.asyncio
+async def test_on_group_message_routes_to_group_chat_id() -> None:
+    channel = QQChannel(QQConfig(app_id="app", secret="secret", allow_from=["user1"]), MessageBus())
+
+    data = SimpleNamespace(
+        id="msg1",
+        content="hello",
+        group_openid="group123",
+        author=SimpleNamespace(member_openid="user1"),
+    )
+
+    await channel._on_message(data, is_group=True)
+
+    msg = await channel.bus.consume_inbound()
+    assert msg.sender_id == "user1"
+    assert msg.chat_id == "group123"
+
+
+@pytest.mark.asyncio
+async def test_send_group_message_uses_group_api_with_msg_seq() -> None:
+    channel = QQChannel(QQConfig(app_id="app", secret="secret", allow_from=["*"]), MessageBus())
+    channel._client = _FakeClient()
+    channel._chat_type_cache["group123"] = "group"
+
+    await channel.send(
+        OutboundMessage(
+            channel="qq",
+            chat_id="group123",
+            content="hello",
+            metadata={"message_id": "msg1"},
+        )
+    )
+
+    assert len(channel._client.api.group_calls) == 1
+    call = channel._client.api.group_calls[0]
+    assert call["group_openid"] == "group123"
+    assert call["msg_id"] == "msg1"
+    assert call["msg_seq"] == 2
+    assert not channel._client.api.c2c_calls
diff --git a/core/nanobot/tests/test_skill_creator_scripts.py b/core/nanobot/tests/test_skill_creator_scripts.py
new file mode 100644
index 0000000..4207c6f
--- /dev/null
+++ b/core/nanobot/tests/test_skill_creator_scripts.py
@@ -0,0 +1,127 @@
+import importlib
+import shutil
+import sys
+import zipfile
+from pathlib import Path
+
+
+SCRIPT_DIR = Path("nanobot/skills/skill-creator/scripts").resolve()
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+init_skill = importlib.import_module("init_skill")
+package_skill = importlib.import_module("package_skill")
+quick_validate = importlib.import_module("quick_validate")
+
+
+def test_init_skill_creates_expected_files(tmp_path: Path) -> None:
+    skill_dir = init_skill.init_skill(
+        "demo-skill",
+        tmp_path,
+        ["scripts", "references", "assets"],
+        include_examples=True,
+    )
+
+    assert skill_dir == tmp_path / "demo-skill"
+    assert (skill_dir / "SKILL.md").exists()
+    assert (skill_dir / "scripts" / "example.py").exists()
+    assert (skill_dir / "references" / "api_reference.md").exists()
+    assert (skill_dir / "assets" / "example_asset.txt").exists()
+
+
+def test_validate_skill_accepts_existing_skill_creator() -> None:
+    valid, message = quick_validate.validate_skill(
+        Path("nanobot/skills/skill-creator").resolve()
+    )
+
+    assert valid, message
+
+
+def test_validate_skill_rejects_placeholder_description(tmp_path: Path) -> None:
+    skill_dir = tmp_path / "placeholder-skill"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text(
+        "---\n"
+        "name: placeholder-skill\n"
+        'description: "[TODO: fill me in]"\n'
+        "---\n"
+        "# Placeholder\n",
+        encoding="utf-8",
+    )
+
+    valid, message = quick_validate.validate_skill(skill_dir)
+
+    assert not valid
+    assert "TODO placeholder" in message
+
+
+def test_validate_skill_rejects_root_files_outside_allowed_dirs(tmp_path: Path) -> None:
+    skill_dir = tmp_path / "bad-root-skill"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text(
+        "---\n"
+        "name: bad-root-skill\n"
+        "description: Valid description\n"
+        "---\n"
+        "# Skill\n",
+        encoding="utf-8",
+    )
+    (skill_dir / "README.md").write_text("extra\n", encoding="utf-8")
+
+    valid, message = quick_validate.validate_skill(skill_dir)
+
+    assert not valid
+    assert "Unexpected file or directory in skill root" in message
+
+
+def test_package_skill_creates_archive(tmp_path: Path) -> None:
+    skill_dir = tmp_path / "package-me"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text(
+        "---\n"
+        "name: package-me\n"
+        "description: Package this skill.\n"
+        "---\n"
+        "# Skill\n",
+        encoding="utf-8",
+    )
+    scripts_dir = skill_dir / "scripts"
+    scripts_dir.mkdir()
+    (scripts_dir / "helper.py").write_text("print('ok')\n", encoding="utf-8")
+
+    archive_path = package_skill.package_skill(skill_dir, tmp_path / "dist")
+
+    assert archive_path == (tmp_path / "dist" / "package-me.skill")
+    assert archive_path.exists()
+    with zipfile.ZipFile(archive_path, "r") as archive:
+        names = set(archive.namelist())
+    assert "package-me/SKILL.md" in names
+    assert "package-me/scripts/helper.py" in names
+
+
+def test_package_skill_rejects_symlink(tmp_path: Path) -> None:
+    skill_dir = tmp_path / "symlink-skill"
+    skill_dir.mkdir()
+    (skill_dir / "SKILL.md").write_text(
+        "---\n"
+        "name: symlink-skill\n"
+        "description: Reject symlinks during packaging.\n"
+        "---\n"
+        "# Skill\n",
+        encoding="utf-8",
+    )
+    scripts_dir = skill_dir / "scripts"
+    scripts_dir.mkdir()
+    target = tmp_path / "outside.txt"
+    target.write_text("secret\n", encoding="utf-8")
+    link = scripts_dir / "outside.txt"
+
+    try:
+        link.symlink_to(target)
+    except (OSError, NotImplementedError):
+        return
+
+    archive_path = package_skill.package_skill(skill_dir, tmp_path / "dist")
+
+    assert archive_path is None
+    assert not (tmp_path / "dist" / "symlink-skill.skill").exists()
diff --git a/core/nanobot/tests/test_slack_channel.py b/core/nanobot/tests/test_slack_channel.py
new file mode 100644
index 0000000..891f86a
--- /dev/null
+++ b/core/nanobot/tests/test_slack_channel.py
@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.slack import SlackChannel
+from nanobot.config.schema import SlackConfig
+
+
+class _FakeAsyncWebClient:
+    def __init__(self) -> None:
+        self.chat_post_calls: list[dict[str, object | None]] = []
+        self.file_upload_calls: list[dict[str, object | None]] = []
+
+    async def chat_postMessage(
+        self,
+        *,
+        channel: str,
+        text: str,
+        thread_ts: str | None = None,
+    ) -> None:
+        self.chat_post_calls.append(
+            {
+                "channel": channel,
+                "text": text,
+                "thread_ts": thread_ts,
+            }
+        )
+
+    async def files_upload_v2(
+        self,
+        *,
+        channel: str,
+        file: str,
+        thread_ts: str | None = None,
+    ) -> None:
+        self.file_upload_calls.append(
+            {
+                "channel": channel,
+                "file": file,
+                "thread_ts": thread_ts,
+            }
+        )
+
+
+@pytest.mark.asyncio
+async def test_send_uses_thread_for_channel_messages() -> None:
+    channel = SlackChannel(SlackConfig(enabled=True), MessageBus())
+    fake_web = _FakeAsyncWebClient()
+    channel._web_client = fake_web
+
+    await channel.send(
+        OutboundMessage(
+            channel="slack",
+            chat_id="C123",
+            content="hello",
+            media=["/tmp/demo.txt"],
+            metadata={"slack": {"thread_ts": "1700000000.000100", "channel_type": "channel"}},
+        )
+    )
+
+    assert len(fake_web.chat_post_calls) == 1
+    assert fake_web.chat_post_calls[0]["text"] == "hello\n"
+    assert fake_web.chat_post_calls[0]["thread_ts"] == "1700000000.000100"
+    assert len(fake_web.file_upload_calls) == 1
+    assert fake_web.file_upload_calls[0]["thread_ts"] == "1700000000.000100"
+
+
+@pytest.mark.asyncio
+async def test_send_omits_thread_for_dm_messages() -> None:
+    channel = SlackChannel(SlackConfig(enabled=True), MessageBus())
+    fake_web = _FakeAsyncWebClient()
+    channel._web_client = fake_web
+
+    await channel.send(
+        OutboundMessage(
+            channel="slack",
+            chat_id="D123",
+            content="hello",
+            media=["/tmp/demo.txt"],
+            metadata={"slack": {"thread_ts": "1700000000.000100", "channel_type": "im"}},
+        )
+    )
+
+    assert len(fake_web.chat_post_calls) == 1
+    assert fake_web.chat_post_calls[0]["text"] == "hello\n"
+    assert fake_web.chat_post_calls[0]["thread_ts"] is None
+    assert len(fake_web.file_upload_calls) == 1
+    assert fake_web.file_upload_calls[0]["thread_ts"] is None
diff --git a/core/nanobot/tests/test_task_cancel.py b/core/nanobot/tests/test_task_cancel.py
new file mode 100644
index 0000000..62ab2cc
--- /dev/null
+++ b/core/nanobot/tests/test_task_cancel.py
@@ -0,0 +1,210 @@
+"""Tests for /stop task cancellation."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+
+def _make_loop():
+    """Create a minimal AgentLoop with mocked dependencies."""
+    from nanobot.agent.loop import AgentLoop
+    from nanobot.bus.queue import MessageBus
+
+    bus = MessageBus()
+    provider = MagicMock()
+    provider.get_default_model.return_value = "test-model"
+    workspace = MagicMock()
+    workspace.__truediv__ = MagicMock(return_value=MagicMock())
+
+    with patch("nanobot.agent.loop.ContextBuilder"), \
+         patch("nanobot.agent.loop.SessionManager"), \
+         patch("nanobot.agent.loop.SubagentManager") as MockSubMgr:
+        MockSubMgr.return_value.cancel_by_session = AsyncMock(return_value=0)
+        loop = AgentLoop(bus=bus, provider=provider, workspace=workspace)
+    return loop, bus
+
+
+class TestHandleStop:
+    @pytest.mark.asyncio
+    async def test_stop_no_active_task(self):
+        from nanobot.bus.events import InboundMessage
+
+        loop, bus = _make_loop()
+        msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
+        await loop._handle_stop(msg)
+        out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+        assert "No active task" in out.content
+
+    @pytest.mark.asyncio
+    async def test_stop_cancels_active_task(self):
+        from nanobot.bus.events import InboundMessage
+
+        loop, bus = _make_loop()
+        cancelled = asyncio.Event()
+
+        async def slow_task():
+            try:
+                await asyncio.sleep(60)
+            except asyncio.CancelledError:
+                cancelled.set()
+                raise
+
+        task = asyncio.create_task(slow_task())
+        await asyncio.sleep(0)
+        loop._active_tasks["test:c1"] = [task]
+
+        msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
+        await loop._handle_stop(msg)
+
+        assert cancelled.is_set()
+        out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+        assert "stopped" in out.content.lower()
+
+    @pytest.mark.asyncio
+    async def test_stop_cancels_multiple_tasks(self):
+        from nanobot.bus.events import InboundMessage
+
+        loop, bus = _make_loop()
+        events = [asyncio.Event(), asyncio.Event()]
+
+        async def slow(idx):
+            try:
+                await asyncio.sleep(60)
+            except asyncio.CancelledError:
+                events[idx].set()
+                raise
+
+        tasks = [asyncio.create_task(slow(i)) for i in range(2)]
+        await asyncio.sleep(0)
+        loop._active_tasks["test:c1"] = tasks
+
+        msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="/stop")
+        await loop._handle_stop(msg)
+
+        assert all(e.is_set() for e in events)
+        out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+        assert "2 task" in out.content
+
+
+class TestDispatch:
+    @pytest.mark.asyncio
+    async def test_dispatch_processes_and_publishes(self):
+        from nanobot.bus.events import InboundMessage, OutboundMessage
+
+        loop, bus = _make_loop()
+        msg = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="hello")
+        loop._process_message = AsyncMock(
+            return_value=OutboundMessage(channel="test", chat_id="c1", content="hi")
+        )
+        await loop._dispatch(msg)
+        out = await asyncio.wait_for(bus.consume_outbound(), timeout=1.0)
+        assert out.content == "hi"
+
+    @pytest.mark.asyncio
+    async def test_processing_lock_serializes(self):
+        from nanobot.bus.events import InboundMessage, OutboundMessage
+
+        loop, bus = _make_loop()
+        order = []
+
+        async def mock_process(m, **kwargs):
+            order.append(f"start-{m.content}")
+            await asyncio.sleep(0.05)
+            order.append(f"end-{m.content}")
+            return OutboundMessage(channel="test", chat_id="c1", content=m.content)
+
+        loop._process_message = mock_process
+        msg1 = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="a")
+        msg2 = InboundMessage(channel="test", sender_id="u1", chat_id="c1", content="b")
+
+        t1 = asyncio.create_task(loop._dispatch(msg1))
+        t2 = asyncio.create_task(loop._dispatch(msg2))
+        await asyncio.gather(t1, t2)
+        assert order == ["start-a", "end-a", "start-b", "end-b"]
+
+
+class TestSubagentCancellation:
+    @pytest.mark.asyncio
+    async def test_cancel_by_session(self):
+        from nanobot.agent.subagent import SubagentManager
+        from nanobot.bus.queue import MessageBus
+
+        bus = MessageBus()
+        provider = MagicMock()
+        provider.get_default_model.return_value = "test-model"
+        mgr = SubagentManager(provider=provider, workspace=MagicMock(), bus=bus)
+
+        cancelled = asyncio.Event()
+
+        async def slow():
+            try:
+                await asyncio.sleep(60)
+            except asyncio.CancelledError:
+                cancelled.set()
+                raise
+
+        task = asyncio.create_task(slow())
+        await asyncio.sleep(0)
+        mgr._running_tasks["sub-1"] = task
+        mgr._session_tasks["test:c1"] = {"sub-1"}
+
+        count = await mgr.cancel_by_session("test:c1")
+        assert count == 1
+        assert cancelled.is_set()
+
+    @pytest.mark.asyncio
+    async def test_cancel_by_session_no_tasks(self):
+        from nanobot.agent.subagent import SubagentManager
+        from nanobot.bus.queue import MessageBus
+
+        bus = MessageBus()
+        provider = MagicMock()
+        provider.get_default_model.return_value = "test-model"
+        mgr = SubagentManager(provider=provider, workspace=MagicMock(), bus=bus)
+        assert await mgr.cancel_by_session("nonexistent") == 0
+
+    @pytest.mark.asyncio
+    async def test_subagent_preserves_reasoning_fields_in_tool_turn(self, monkeypatch, tmp_path):
+        from nanobot.agent.subagent import SubagentManager
+        from nanobot.bus.queue import MessageBus
+        from nanobot.providers.base import LLMResponse, ToolCallRequest
+
+        bus = MessageBus()
+        provider = MagicMock()
+        provider.get_default_model.return_value = "test-model"
+
+        captured_second_call: list[dict] = []
+
+        call_count = {"n": 0}
+
+        async def scripted_chat_with_retry(*, messages, **kwargs):
+            call_count["n"] += 1
+            if call_count["n"] == 1:
+                return LLMResponse(
+                    content="thinking",
+                    tool_calls=[ToolCallRequest(id="call_1", name="list_dir", arguments={})],
+                    reasoning_content="hidden reasoning",
+                    thinking_blocks=[{"type": "thinking", "thinking": "step"}],
+                )
+            captured_second_call[:] = messages
+            return LLMResponse(content="done", tool_calls=[])
+        provider.chat_with_retry = scripted_chat_with_retry
+        mgr = SubagentManager(provider=provider, workspace=tmp_path, bus=bus)
+
+        async def fake_execute(self, name, arguments):
+            return "tool result"
+
+        monkeypatch.setattr("nanobot.agent.tools.registry.ToolRegistry.execute", fake_execute)
+
+        await mgr._run_subagent("sub-1", "do task", "label", {"channel": "test", "chat_id": "c1"})
+
+        assistant_messages = [
+            msg for msg in captured_second_call
+            if msg.get("role") == "assistant" and msg.get("tool_calls")
+        ]
+        assert len(assistant_messages) == 1
+        assert assistant_messages[0]["reasoning_content"] == "hidden reasoning"
+        assert assistant_messages[0]["thinking_blocks"] == [{"type": "thinking", "thinking": "step"}]
diff --git a/core/nanobot/tests/test_telegram_channel.py b/core/nanobot/tests/test_telegram_channel.py
new file mode 100644
index 0000000..678512d
--- /dev/null
+++ b/core/nanobot/tests/test_telegram_channel.py
@@ -0,0 +1,338 @@
+from types import SimpleNamespace
+
+import pytest
+
+from nanobot.bus.events import OutboundMessage
+from nanobot.bus.queue import MessageBus
+from nanobot.channels.telegram import TelegramChannel
+from nanobot.config.schema import TelegramConfig
+
+
+class _FakeHTTPXRequest:
+    instances: list["_FakeHTTPXRequest"] = []
+
+    def __init__(self, **kwargs) -> None:
+        self.kwargs = kwargs
+        self.__class__.instances.append(self)
+
+
+class _FakeUpdater:
+    def __init__(self, on_start_polling) -> None:
+        self._on_start_polling = on_start_polling
+
+    async def start_polling(self, **kwargs) -> None:
+        self._on_start_polling()
+
+
+class _FakeBot:
+    def __init__(self) -> None:
+        self.sent_messages: list[dict] = []
+        self.get_me_calls = 0
+
+    async def get_me(self):
+        self.get_me_calls += 1
+        return SimpleNamespace(id=999, username="nanobot_test")
+
+    async def set_my_commands(self, commands) -> None:
+        self.commands = commands
+
+    async def send_message(self, **kwargs) -> None:
+        self.sent_messages.append(kwargs)
+
+    async def send_chat_action(self, **kwargs) -> None:
+        pass
+
+
+class _FakeApp:
+    def __init__(self, on_start_polling) -> None:
+        self.bot = _FakeBot()
+        self.updater = _FakeUpdater(on_start_polling)
+        self.handlers = []
+        self.error_handlers = []
+
+    def add_error_handler(self, handler) -> None:
+        self.error_handlers.append(handler)
+
+    def add_handler(self, handler) -> None:
+        self.handlers.append(handler)
+
+    async def initialize(self) -> None:
+        pass
+
+    async def start(self) -> None:
+        pass
+
+
+class _FakeBuilder:
+    def __init__(self, app: _FakeApp) -> None:
+        self.app = app
+        self.token_value = None
+        self.request_value = None
+        self.get_updates_request_value = None
+
+    def token(self, token: str):
+        self.token_value = token
+        return self
+
+    def request(self, request):
+        self.request_value = request
+        return self
+
+    def get_updates_request(self, request):
+        self.get_updates_request_value = request
+        return self
+
+    def proxy(self, _proxy):
+        raise AssertionError("builder.proxy should not be called when request is set")
+
+    def get_updates_proxy(self, _proxy):
+        raise AssertionError("builder.get_updates_proxy should not be called when request is set")
+
+    def build(self):
+        return self.app
+
+
+def _make_telegram_update(
+    *,
+    chat_type: str = "group",
+    text: str | None = None,
+    caption: str | None = None,
+    entities=None,
+    caption_entities=None,
+    reply_to_message=None,
+):
+    user = SimpleNamespace(id=12345, username="alice", first_name="Alice")
+    message = SimpleNamespace(
+        chat=SimpleNamespace(type=chat_type, is_forum=False),
+        chat_id=-100123,
+        text=text,
+        caption=caption,
+        entities=entities or [],
+        caption_entities=caption_entities or [],
+        reply_to_message=reply_to_message,
+        photo=None,
+        voice=None,
+        audio=None,
+        document=None,
+        media_group_id=None,
+        message_thread_id=None,
+        message_id=1,
+    )
+    return SimpleNamespace(message=message, effective_user=user)
+
+
+@pytest.mark.asyncio
+async def test_start_uses_request_proxy_without_builder_proxy(monkeypatch) -> None:
+    config = TelegramConfig(
+        enabled=True,
+        token="123:abc",
+        allow_from=["*"],
+        proxy="http://127.0.0.1:7890",
+    )
+    bus = MessageBus()
+    channel = TelegramChannel(config, bus)
+    app = _FakeApp(lambda: setattr(channel, "_running", False))
+    builder = _FakeBuilder(app)
+
+    monkeypatch.setattr("nanobot.channels.telegram.HTTPXRequest", _FakeHTTPXRequest)
+    monkeypatch.setattr(
+        "nanobot.channels.telegram.Application",
+        SimpleNamespace(builder=lambda: builder),
+    )
+
+    await channel.start()
+
+    assert len(_FakeHTTPXRequest.instances) == 1
+    assert _FakeHTTPXRequest.instances[0].kwargs["proxy"] == config.proxy
+    assert builder.request_value is _FakeHTTPXRequest.instances[0]
+    assert builder.get_updates_request_value is _FakeHTTPXRequest.instances[0]
+
+
+def test_derive_topic_session_key_uses_thread_id() -> None:
+    message = SimpleNamespace(
+        chat=SimpleNamespace(type="supergroup"),
+        chat_id=-100123,
+        message_thread_id=42,
+    )
+
+    assert TelegramChannel._derive_topic_session_key(message) == "telegram:-100123:topic:42"
+
+
+def test_get_extension_falls_back_to_original_filename() -> None:
+    channel = TelegramChannel(TelegramConfig(), MessageBus())
+
+    assert channel._get_extension("file", None, "report.pdf") == ".pdf"
+    assert channel._get_extension("file", None, "archive.tar.gz") == ".tar.gz"
+
+
+def test_telegram_group_policy_defaults_to_mention() -> None:
+    assert TelegramConfig().group_policy == "mention"
+
+
+def test_is_allowed_accepts_legacy_telegram_id_username_formats() -> None:
+    channel = TelegramChannel(TelegramConfig(allow_from=["12345", "alice", "67890|bob"]), MessageBus())
+
+    assert channel.is_allowed("12345|carol") is True
+    assert channel.is_allowed("99999|alice") is True
+    assert channel.is_allowed("67890|bob") is True
+
+
+def test_is_allowed_rejects_invalid_legacy_telegram_sender_shapes() -> None:
+    channel = TelegramChannel(TelegramConfig(allow_from=["alice"]), MessageBus())
+
+    assert channel.is_allowed("attacker|alice|extra") is False
+    assert channel.is_allowed("not-a-number|alice") is False
+
+
+@pytest.mark.asyncio
+async def test_send_progress_keeps_message_in_topic() -> None:
+    config = TelegramConfig(enabled=True, token="123:abc", allow_from=["*"])
+    channel = TelegramChannel(config, MessageBus())
+    channel._app = _FakeApp(lambda: None)
+
+    await channel.send(
+        OutboundMessage(
+            channel="telegram",
+            chat_id="123",
+            content="hello",
+            metadata={"_progress": True, "message_thread_id": 42},
+        )
+    )
+
+    assert channel._app.bot.sent_messages[0]["message_thread_id"] == 42
+
+
+@pytest.mark.asyncio
+async def test_send_reply_infers_topic_from_message_id_cache() -> None:
+    config = TelegramConfig(enabled=True, token="123:abc", allow_from=["*"], reply_to_message=True)
+    channel = TelegramChannel(config, MessageBus())
+    channel._app = _FakeApp(lambda: None)
+    channel._message_threads[("123", 10)] = 42
+
+    await channel.send(
+        OutboundMessage(
+            channel="telegram",
+            chat_id="123",
+            content="hello",
+            metadata={"message_id": 10},
+        )
+    )
+
+    assert channel._app.bot.sent_messages[0]["message_thread_id"] == 42
+    assert channel._app.bot.sent_messages[0]["reply_parameters"].message_id == 10
+
+
+@pytest.mark.asyncio
+async def test_group_policy_mention_ignores_unmentioned_group_message() -> None:
+    channel = TelegramChannel(
+        TelegramConfig(enabled=True, token="123:abc", allow_from=["*"], group_policy="mention"),
+        MessageBus(),
+    )
+    channel._app = _FakeApp(lambda: None)
+
+    handled = []
+
+    async def capture_handle(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = capture_handle
+    channel._start_typing = lambda _chat_id: None
+
+    await channel._on_message(_make_telegram_update(text="hello everyone"), None)
+
+    assert handled == []
+    assert channel._app.bot.get_me_calls == 1
+
+
+@pytest.mark.asyncio
+async def test_group_policy_mention_accepts_text_mention_and_caches_bot_identity() -> None:
+    channel = TelegramChannel(
+        TelegramConfig(enabled=True, token="123:abc", allow_from=["*"], group_policy="mention"),
+        MessageBus(),
+    )
+    channel._app = _FakeApp(lambda: None)
+
+    handled = []
+
+    async def capture_handle(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = capture_handle
+    channel._start_typing = lambda _chat_id: None
+
+    mention = SimpleNamespace(type="mention", offset=0, length=13)
+    await channel._on_message(_make_telegram_update(text="@nanobot_test hi", entities=[mention]), None)
+    await channel._on_message(_make_telegram_update(text="@nanobot_test again", entities=[mention]), None)
+
+    assert len(handled) == 2
+    assert channel._app.bot.get_me_calls == 1
+
+
+@pytest.mark.asyncio
+async def test_group_policy_mention_accepts_caption_mention() -> None:
+    channel = TelegramChannel(
+        TelegramConfig(enabled=True, token="123:abc", allow_from=["*"], group_policy="mention"),
+        MessageBus(),
+    )
+    channel._app = _FakeApp(lambda: None)
+
+    handled = []
+
+    async def capture_handle(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = capture_handle
+    channel._start_typing = lambda _chat_id: None
+
+    mention = SimpleNamespace(type="mention", offset=0, length=13)
+    await channel._on_message(
+        _make_telegram_update(caption="@nanobot_test photo", caption_entities=[mention]),
+        None,
+    )
+
+    assert len(handled) == 1
+    assert handled[0]["content"] == "@nanobot_test photo"
+
+
+@pytest.mark.asyncio
+async def test_group_policy_mention_accepts_reply_to_bot() -> None:
+    channel = TelegramChannel(
+        TelegramConfig(enabled=True, token="123:abc", allow_from=["*"], group_policy="mention"),
+        MessageBus(),
+    )
+    channel._app = _FakeApp(lambda: None)
+
+    handled = []
+
+    async def capture_handle(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = capture_handle
+    channel._start_typing = lambda _chat_id: None
+
+    reply = SimpleNamespace(from_user=SimpleNamespace(id=999))
+    await channel._on_message(_make_telegram_update(text="reply", reply_to_message=reply), None)
+
+    assert len(handled) == 1
+
+
+@pytest.mark.asyncio
+async def test_group_policy_open_accepts_plain_group_message() -> None:
+    channel = TelegramChannel(
+        TelegramConfig(enabled=True, token="123:abc", allow_from=["*"], group_policy="open"),
+        MessageBus(),
+    )
+    channel._app = _FakeApp(lambda: None)
+
+    handled = []
+
+    async def capture_handle(**kwargs) -> None:
+        handled.append(kwargs)
+
+    channel._handle_message = capture_handle
+    channel._start_typing = lambda _chat_id: None
+
+    await channel._on_message(_make_telegram_update(text="hello group"), None)
+
+    assert len(handled) == 1
+    assert channel._app.bot.get_me_calls == 0
diff --git a/core/nanobot/tests/test_tool_validation.py b/core/nanobot/tests/test_tool_validation.py
new file mode 100644
index 0000000..095c041
--- /dev/null
+++ b/core/nanobot/tests/test_tool_validation.py
@@ -0,0 +1,406 @@
+from typing import Any
+
+from nanobot.agent.tools.base import Tool
+from nanobot.agent.tools.registry import ToolRegistry
+from nanobot.agent.tools.shell import ExecTool
+
+
+class SampleTool(Tool):
+    @property
+    def name(self) -> str:
+        return "sample"
+
+    @property
+    def description(self) -> str:
+        return "sample tool"
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "minLength": 2},
+                "count": {"type": "integer", "minimum": 1, "maximum": 10},
+                "mode": {"type": "string", "enum": ["fast", "full"]},
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "tag": {"type": "string"},
+                        "flags": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                        },
+                    },
+                    "required": ["tag"],
+                },
+            },
+            "required": ["query", "count"],
+        }
+
+    async def execute(self, **kwargs: Any) -> str:
+        return "ok"
+
+
+def test_validate_params_missing_required() -> None:
+    tool = SampleTool()
+    errors = tool.validate_params({"query": "hi"})
+    assert "missing required count" in "; ".join(errors)
+
+
+def test_validate_params_type_and_range() -> None:
+    tool = SampleTool()
+    errors = tool.validate_params({"query": "hi", "count": 0})
+    assert any("count must be >= 1" in e for e in errors)
+
+    errors = tool.validate_params({"query": "hi", "count": "2"})
+    assert any("count should be integer" in e for e in errors)
+
+
+def test_validate_params_enum_and_min_length() -> None:
+    tool = SampleTool()
+    errors = tool.validate_params({"query": "h", "count": 2, "mode": "slow"})
+    assert any("query must be at least 2 chars" in e for e in errors)
+    assert any("mode must be one of" in e for e in errors)
+
+
+def test_validate_params_nested_object_and_array() -> None:
+    tool = SampleTool()
+    errors = tool.validate_params(
+        {
+            "query": "hi",
+            "count": 2,
+            "meta": {"flags": [1, "ok"]},
+        }
+    )
+    assert any("missing required meta.tag" in e for e in errors)
+    assert any("meta.flags[0] should be string" in e for e in errors)
+
+
+def test_validate_params_ignores_unknown_fields() -> None:
+    tool = SampleTool()
+    errors = tool.validate_params({"query": "hi", "count": 2, "extra": "x"})
+    assert errors == []
+
+
+async def test_registry_returns_validation_error() -> None:
+    reg = ToolRegistry()
+    reg.register(SampleTool())
+    result = await reg.execute("sample", {"query": "hi"})
+    assert "Invalid parameters" in result
+
+
+def test_exec_extract_absolute_paths_keeps_full_windows_path() -> None:
+    cmd = r"type C:\user\workspace\txt"
+    paths = ExecTool._extract_absolute_paths(cmd)
+    assert paths == [r"C:\user\workspace\txt"]
+
+
+def test_exec_extract_absolute_paths_ignores_relative_posix_segments() -> None:
+    cmd = ".venv/bin/python script.py"
+    paths = ExecTool._extract_absolute_paths(cmd)
+    assert "/bin/python" not in paths
+
+
+def test_exec_extract_absolute_paths_captures_posix_absolute_paths() -> None:
+    cmd = "cat /tmp/data.txt > /tmp/out.txt"
+    paths = ExecTool._extract_absolute_paths(cmd)
+    assert "/tmp/data.txt" in paths
+    assert "/tmp/out.txt" in paths
+
+
+def test_exec_extract_absolute_paths_captures_home_paths() -> None:
+    cmd = "cat ~/.nanobot/config.json > ~/out.txt"
+    paths = ExecTool._extract_absolute_paths(cmd)
+    assert "~/.nanobot/config.json" in paths
+    assert "~/out.txt" in paths
+
+
+def test_exec_extract_absolute_paths_captures_quoted_paths() -> None:
+    cmd = 'cat "/tmp/data.txt" "~/.nanobot/config.json"'
+    paths = ExecTool._extract_absolute_paths(cmd)
+    assert "/tmp/data.txt" in paths
+    assert "~/.nanobot/config.json" in paths
+
+
+def test_exec_guard_blocks_home_path_outside_workspace(tmp_path) -> None:
+    tool = ExecTool(restrict_to_workspace=True)
+    error = tool._guard_command("cat ~/.nanobot/config.json", str(tmp_path))
+    assert error == "Error: Command blocked by safety guard (path outside working dir)"
+
+
+def test_exec_guard_blocks_quoted_home_path_outside_workspace(tmp_path) -> None:
+    tool = ExecTool(restrict_to_workspace=True)
+    error = tool._guard_command('cat "~/.nanobot/config.json"', str(tmp_path))
+    assert error == "Error: Command blocked by safety guard (path outside working dir)"
+
+
+# --- cast_params tests ---
+
+
+class CastTestTool(Tool):
+    """Minimal tool for testing cast_params."""
+
+    def __init__(self, schema: dict[str, Any]) -> None:
+        self._schema = schema
+
+    @property
+    def name(self) -> str:
+        return "cast_test"
+
+    @property
+    def description(self) -> str:
+        return "test tool for casting"
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return self._schema
+
+    async def execute(self, **kwargs: Any) -> str:
+        return "ok"
+
+
+def test_cast_params_string_to_int() -> None:
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"count": {"type": "integer"}},
+        }
+    )
+    result = tool.cast_params({"count": "42"})
+    assert result["count"] == 42
+    assert isinstance(result["count"], int)
+
+
+def test_cast_params_string_to_number() -> None:
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"rate": {"type": "number"}},
+        }
+    )
+    result = tool.cast_params({"rate": "3.14"})
+    assert result["rate"] == 3.14
+    assert isinstance(result["rate"], float)
+
+
+def test_cast_params_string_to_bool() -> None:
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"enabled": {"type": "boolean"}},
+        }
+    )
+    assert tool.cast_params({"enabled": "true"})["enabled"] is True
+    assert tool.cast_params({"enabled": "false"})["enabled"] is False
+    assert tool.cast_params({"enabled": "1"})["enabled"] is True
+
+
+def test_cast_params_array_items() -> None:
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {
+                "nums": {"type": "array", "items": {"type": "integer"}},
+            },
+        }
+    )
+    result = tool.cast_params({"nums": ["1", "2", "3"]})
+    assert result["nums"] == [1, 2, 3]
+
+
+def test_cast_params_nested_object() -> None:
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {
+                "config": {
+                    "type": "object",
+                    "properties": {
+                        "port": {"type": "integer"},
+                        "debug": {"type": "boolean"},
+                    },
+                },
+            },
+        }
+    )
+    result = tool.cast_params({"config": {"port": "8080", "debug": "true"}})
+    assert result["config"]["port"] == 8080
+    assert result["config"]["debug"] is True
+
+
+def test_cast_params_bool_not_cast_to_int() -> None:
+    """Booleans should not be silently cast to integers."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"count": {"type": "integer"}},
+        }
+    )
+    result = tool.cast_params({"count": True})
+    assert result["count"] is True
+    errors = tool.validate_params(result)
+    assert any("count should be integer" in e for e in errors)
+
+
+def test_cast_params_preserves_empty_string() -> None:
+    """Empty strings should be preserved for string type."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"name": {"type": "string"}},
+        }
+    )
+    result = tool.cast_params({"name": ""})
+    assert result["name"] == ""
+
+
+def test_cast_params_bool_string_false() -> None:
+    """Test that 'false', '0', 'no' strings convert to False."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"flag": {"type": "boolean"}},
+        }
+    )
+    assert tool.cast_params({"flag": "false"})["flag"] is False
+    assert tool.cast_params({"flag": "False"})["flag"] is False
+    assert tool.cast_params({"flag": "0"})["flag"] is False
+    assert tool.cast_params({"flag": "no"})["flag"] is False
+    assert tool.cast_params({"flag": "NO"})["flag"] is False
+
+
+def test_cast_params_bool_string_invalid() -> None:
+    """Invalid boolean strings should not be cast."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"flag": {"type": "boolean"}},
+        }
+    )
+    # Invalid strings should be preserved (validation will catch them)
+    result = tool.cast_params({"flag": "random"})
+    assert result["flag"] == "random"
+    result = tool.cast_params({"flag": "maybe"})
+    assert result["flag"] == "maybe"
+
+
+def test_cast_params_invalid_string_to_int() -> None:
+    """Invalid strings should not be cast to integer."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"count": {"type": "integer"}},
+        }
+    )
+    result = tool.cast_params({"count": "abc"})
+    assert result["count"] == "abc"  # Original value preserved
+    result = tool.cast_params({"count": "12.5.7"})
+    assert result["count"] == "12.5.7"
+
+
+def test_cast_params_invalid_string_to_number() -> None:
+    """Invalid strings should not be cast to number."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"rate": {"type": "number"}},
+        }
+    )
+    result = tool.cast_params({"rate": "not_a_number"})
+    assert result["rate"] == "not_a_number"
+
+
+def test_validate_params_bool_not_accepted_as_number() -> None:
+    """Booleans should not pass number validation."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"rate": {"type": "number"}},
+        }
+    )
+    errors = tool.validate_params({"rate": False})
+    assert any("rate should be number" in e for e in errors)
+
+
+def test_cast_params_none_values() -> None:
+    """Test None handling for different types."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "count": {"type": "integer"},
+                "items": {"type": "array"},
+                "config": {"type": "object"},
+            },
+        }
+    )
+    result = tool.cast_params(
+        {
+            "name": None,
+            "count": None,
+            "items": None,
+            "config": None,
+        }
+    )
+    # None should be preserved for all types
+    assert result["name"] is None
+    assert result["count"] is None
+    assert result["items"] is None
+    assert result["config"] is None
+
+
+def test_cast_params_single_value_not_auto_wrapped_to_array() -> None:
+    """Single values should NOT be automatically wrapped into arrays."""
+    tool = CastTestTool(
+        {
+            "type": "object",
+            "properties": {"items": {"type": "array"}},
+        }
+    )
+    # Non-array values should be preserved (validation will catch them)
+    result = tool.cast_params({"items": 5})
+    assert result["items"] == 5  # Not wrapped to [5]
+    result = tool.cast_params({"items": "text"})
+    assert result["items"] == "text"  # Not wrapped to ["text"]
+
+
+# --- ExecTool enhancement tests ---
+
+
+async def test_exec_always_returns_exit_code() -> None:
+    """Exit code should appear in output even on success (exit 0)."""
+    tool = ExecTool()
+    result = await tool.execute(command="echo hello")
+    assert "Exit code: 0" in result
+    assert "hello" in result
+
+
+async def test_exec_head_tail_truncation() -> None:
+    """Long output should preserve both head and tail."""
+    tool = ExecTool()
+    # Generate output that exceeds _MAX_OUTPUT
+    big = "A" * 6000 + "\n" + "B" * 6000
+    result = await tool.execute(command=f"echo '{big}'")
+    assert "chars truncated" in result
+    # Head portion should start with As
+    assert result.startswith("A")
+    # Tail portion should end with the exit code which comes after Bs
+    assert "Exit code:" in result
+
+
+async def test_exec_timeout_parameter() -> None:
+    """LLM-supplied timeout should override the constructor default."""
+    tool = ExecTool(timeout=60)
+    # A very short timeout should cause the command to be killed
+    result = await tool.execute(command="sleep 10", timeout=1)
+    assert "timed out" in result
+    assert "1 seconds" in result
+
+
+async def test_exec_timeout_capped_at_max() -> None:
+    """Timeout values above _MAX_TIMEOUT should be clamped."""
+    tool = ExecTool()
+    # Should not raise — just clamp to 600
+    result = await tool.execute(command="echo ok", timeout=9999)
+    assert "Exit code: 0" in result