docs: add project documentation and architecture guides

Add comprehensive documentation including: - CLAUDE.md for build instructions and environment setup - project-map.md for directory structure and key file overview - docs/reference/tools-api.md for detailed tools API and architecture - session-log.md for tracking development decisions - updates to plugin tool injection documentation regarding security risks
2026-05-05 05:49:21 +03:00 · 2026-05-05 05:49:21 +03:00 · ab23be43a9
commit ab23be43a9
parent 07107384cb
5 changed files with 606 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,37 @@
+# PicoClaw
+
+## Build & Test Commands
+
+```bash
+make build          # Build for current platform (runs generate first)
+make build-all      # Cross-compile for all supported platforms
+make test           # Run Go tests + web tests
+make lint           # golangci-lint with goolm,stdjson tags
+make check          # deps + fmt + vet + test + lint-docs
+```
+
+## Environment Setup
+
+- Copy `.env.example` to `.env` and configure API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
+- Go 1.25.9+ required
+- Build tags: `goolm,stdjson` (set via GO_BUILD_TAGS or Makefile)
+- CGO_ENABLED=0 by default; CGO_ENABLED=1 only for macOS launcher builds
+
+## Critical Constraints
+
+- **Always run `make generate` before `make build`** — code generation creates required workspace symlinks
+- **Never edit `cmd/picoclaw/workspace/` directly** — it's regenerated by `go generate`
+- **MIPS builds require ELF e_flags patch** — handled automatically by Makefile
+- **loong64 needs manual ztypes_loong64.go** — handled automatically by Makefile
+- **WhatsApp native builds** add `whatsapp_native` tag but produce larger binaries
+- **Workspace location**: `~/.picoclaw/workspace` (skills, memory stored here at runtime)
+- **macOS launcher**: requires CGO_ENABLED=1 and minimal macOS 10.11 target
+- **No hardcoded API keys in CLI** — project is migrating to OAuth 2.0 flows
+- **Memory target**: core process <20MB for 64MB RAM boards; optimize data structures over storage
+
+## Architecture Notes
+- **Protocol-first**: Migrating from vendor-based to protocol-based provider classification (OpenAI-compat, Ollama-compat)
+- **Multi-architecture**: x86_64, ARM64, MIPS, RISC-V, LoongArch
+- **14+ chat channels** via adapter pattern in pkg/channels/
+- **MCP support**: Model Context Protocol server in pkg/mcp/
+- **Tools API**: See `docs/reference/tools-api.md` for complete tools documentation
--- a/docs/architecture/hooks/plugin-tool-injection.md
+++ b/docs/architecture/hooks/plugin-tool-injection.md
@ -556,6 +556,7 @@ This provides a flexible and elegant solution for plugin development.
 **Important**: The `respond` action bypasses `ApproveTool` approval checks.

 This means:
+
 - A `before_tool` hook can return `respond` for **any tool name**, including sensitive tools (like `bash`)
 - The tool won't go through the approval process, directly returning the hook-provided result
 - This is designed for plugin tools but introduces security risks
--- a/docs/reference/tools-api.md
+++ b/docs/reference/tools-api.md
@ -0,0 +1,453 @@
+# Tools API Documentation
+
+## Overview
+
+PicoClaw's tools system provides a extensible way for the AI agent to interact with the host system, web, hardware, and external services. Tools are registered in a centralized `ToolRegistry` and can be exposed to LLM providers via JSON Schema definitions.
+
+## Architecture
+
+### Tool Interface
+
+All tools implement the base `Tool` interface (`pkg/tools/registry.go`):
+
+```go
+type Tool interface {
+    Name() string
+    Description() string
+    Parameters() map[string]any  // JSON Schema
+    Execute(ctx context.Context, args map[string]any) *ToolResult
+}
+```
+
+Optional interfaces for enhanced behavior:
+
+- **`AsyncExecutor`** - Tools that support async execution with callback
+- **`mediaStoreAware`** - Tools that need access to media storage
+- **`PromptMetadataProvider`** - Tools that provide prompt layer/slot metadata
+
+### Tool Registry
+
+The `ToolRegistry` (`pkg/tools/registry.go`) manages all tools:
+
+- **Core Tools**: Registered with `Register(tool)` - always available, no TTL
+- **Hidden Tools**: Registered with `RegisterHidden(tool)` - have TTL (Time To Live), can be promoted
+- **Tool Definitions**: `GetDefinitions()` returns JSON Schema for LLM providers
+- **Provider Format**: `ToProviderDefs()` converts to provider-specific format (OpenAI, Anthropic, etc.)
+
+### Tool Execution Flow
+
+1. Tool called by agent with arguments
+2. Arguments validated against tool's JSON Schema
+3. Channel/ChatID context injected into `ctx`
+4. `Execute()` or `ExecuteAsync()` called
+5. Result normalized and returned as `ToolResult`
+6. Panics recovered to prevent agent crashes
+
+## Available Tools
+
+### Filesystem Tools
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `read_file` | Read file content from workspace or allowed paths | filesystem | `read_file` |
+| `write_file` | Create or overwrite files within workspace | filesystem | `write_file` |
+| `list_dir` | Inspect directories and enumerate files | filesystem | `list_dir` |
+| `edit_file` | Apply targeted edits to existing files | filesystem | `edit_file` |
+| `append_file` | Append content to end of existing file | filesystem | `append_file` |
+
+**Implementation**: `pkg/tools/fs/` package
+- Path validation against workspace restrictions
+- Symlink resolution to prevent escaping workspace
+- Configurable allow/deny path patterns
+- Max file size limit: 64KB (configurable via `MaxReadFileSize`)
+
+**Expected Arguments** (example for `read_file`):
+```json
+{
+  "path": "/path/to/file.txt",
+  "workspace": "/workspace"  // injected automatically
+}
+```
+
+### Shell/Exec Tool
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `exec` | Run shell commands in workspace sandbox | filesystem | `exec` |
+
+**Implementation**: `pkg/tools/shell.go`
+- **Security**: Deny patterns block dangerous commands:
+  - `rm -rf`, `dd`, `shutdown`, `reboot`, `chmod`, `chown`, `sudo`
+  - Command substitution: `$(...)`, backticks
+  - Pipe to shell: `\| sh`, `\| bash`
+- **Session Management**: Persistent shell sessions via `SessionManager`
+- **Timeout**: Configurable command timeout
+- **Working Directory**: Restricted to workspace by default
+
+**Expected Arguments**:
+```json
+{
+  "command": "ls -la",
+  "workdir": "/workspace",  // optional
+  "timeout": 30  // seconds, optional
+}
+```
+
+### Automation Tools
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `cron` | Schedule one-time or recurring tasks | automation | `cron` |
+
+**Implementation**: `pkg/tools/cron.go`
+- Schedule reminders, shell commands, and jobs
+- One-time or recurring (cron expression support)
+
+**Expected Arguments**:
+```json
+{
+  "action": "add",  // add, list, remove
+  "schedule": "0 9 * * *",  // cron format or "in 5m"
+  "command": "echo 'reminder'",  // optional
+  "message": "Daily reminder"  // optional
+}
+```
+
+### Web Tools
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `web_search` | Search the web using configured providers | web | `web` |
+| `web_fetch` | Fetch and summarize webpage contents | web | `web_fetch` |
+
+**Web Search Providers** (configured in `tools.web`):
+- **Sogou** - Chinese search engine
+- **DuckDuckGo** - Privacy-focused search
+- **Brave Search** - Independent search (requires API key)
+- **Tavily** - AI-optimized search (requires API key)
+- **Perplexity** - AI search engine (requires API key)
+- **SearXNG** - Metasearch engine (self-hosted)
+- **GLM Search** - Chinese AI search (requires API key)
+- **Baidu Search** - Chinese search engine (requires API key)
+
+**Web Search Expected Arguments**:
+```json
+{
+  "query": "latest AI news",
+  "max_results": 5,  // optional, default varies by provider
+  "provider": "brave"  // optional, uses default
+}
+```
+
+**Web Fetch Expected Arguments**:
+```json
+{
+  "url": "https://example.com",
+  "max_chars": 10000  // optional
+}
+```
+
+### Communication Tools
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `message` | Send follow-up message to active chat | communication | `message` |
+| `send_file` | Send file or media to active chat | communication | `send_file` |
+
+**Implementation**: `pkg/tools/integration_facade.go` → `pkg/tools/integration/`
+
+**Message Tool Expected Arguments**:
+```json
+{
+  "text": "Hello from the agent!",
+  "channel": "telegram",  // injected from context
+  "chat_id": "123456"  // injected from context
+}
+```
+
+**Send File Expected Arguments**:
+```json
+{
+  "path": "/workspace/report.pdf",
+  "caption": "Here's your file"  // optional
+}
+```
+
+### Skills Tools
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `find_skills` | Search external skill registries | skills | `find_skills` |
+| `install_skill` | Install skill from registry | skills | `install_skill` |
+
+**Dependencies**: Requires `skills` config to be enabled
+
+**Find Skills Expected Arguments**:
+```json
+{
+  "query": "pdf",
+  "limit": 10  // optional
+}
+```
+
+**Install Skill Expected Arguments**:
+```json
+{
+  "name": "pdf-tools",
+  "source": "registry-url"  // optional
+}
+```
+
+### Agent/Subagent Tools
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `spawn` | Launch background subagent for delegated work | agents | `spawn` |
+| `spawn_status` | Query status of spawned subagents | agents | `spawn_status` |
+
+**Dependencies**: Requires `subagent` config to be enabled
+
+**Spawn Tool Expected Arguments**:
+```json
+{
+  "task": "Research latest AI papers",
+  "model": "gpt-4",  // optional
+  "max_tokens": 2000,  // optional
+  "temperature": 0.7,  // optional
+  "async": true  // optional, run in background
+}
+```
+
+**Spawn Status Expected Arguments**:
+```json
+{
+  "task_id": "abc123"  // optional, returns specific task or all
+}
+```
+
+### Hardware Tools
+
+| Tool Name | Description | Category | Config Key | Platform |
+|-----------|-------------|----------|------------|----------|
+| `i2c` | Interact with I2C devices | hardware | `i2c` | Linux only |
+| `spi` | Interact with SPI devices | hardware | `spi` | Linux only |
+| `serial` | Interact with serial ports | hardware | `serial` | Linux/macOS/Windows |
+
+**Implementation**: `pkg/tools/hardware_facade.go` → `pkg/tools/hardware/`
+
+**I2C Expected Arguments**:
+```json
+{
+  "action": "read",  // read, write
+  "bus": "/dev/i2c-1",
+  "address": 0x48,
+  "register": 0x00,  // optional
+  "data": [0x01, 0x02]  // for write
+}
+```
+
+**Serial Expected Arguments**:
+```json
+{
+  "port": "/dev/ttyUSB0",
+  "baud": 9600,
+  "data": "hello"  // string or bytes
+}
+```
+
+### Discovery Tools (Hidden, TTL-based)
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `tool_search_tool_regex` | Discover hidden MCP tools by regex | discovery | `mcp.discovery.use_regex` |
+| `tool_search_tool_bm25` | Discover hidden MCP tools by semantics | discovery | `mcp.discovery.use_bm25` |
+
+**Dependencies**: Requires `mcp` and `mcp.discovery` to be enabled
+
+## Backend API Endpoints
+
+### Base URL
+```
+http://localhost:<port>/api
+```
+
+### Tool Management
+
+#### List All Tools
+```
+GET /api/tools
+```
+
+**Response**:
+```json
+{
+  "tools": [
+    {
+      "name": "read_file",
+      "description": "Read file content from the workspace",
+      "category": "filesystem",
+      "config_key": "read_file",
+      "status": "enabled",  // enabled, disabled, blocked
+      "reason_code": ""  // e.g., "requires_skills"
+    }
+  ]
+}
+```
+
+#### Enable/Disable Tool
+```
+PUT /api/tools/{name}/state
+```
+
+**Request Body**:
+```json
+{
+  "enabled": true
+}
+```
+
+**Response**:
+```json
+{
+  "status": "ok"
+}
+```
+
+### Web Search Configuration
+
+#### Get Web Search Config
+```
+GET /api/tools/web-search-config
+```
+
+**Response**:
+```json
+{
+  "provider": "auto",  // auto, sogou, duckduckgo, brave, tavily, etc.
+  "current_service": "brave",
+  "prefer_native": false,
+  "proxy": "",
+  "providers": [
+    {
+      "id": "brave",
+      "label": "Brave Search",
+      "configured": true,
+      "current": true,
+      "requires_auth": true
+    }
+  ],
+  "settings": {
+    "brave": {
+      "enabled": true,
+      "max_results": 10,
+      "api_key_set": true
+    }
+  }
+}
+```
+
+#### Update Web Search Config
+```
+PUT /api/tools/web-search-config
+```
+
+**Request Body**:
+```json
+{
+  "provider": "brave",
+  "prefer_native": false,
+  "proxy": "",
+  "settings": {
+    "brave": {
+      "enabled": true,
+      "max_results": 10,
+      "api_key": "BSA...",  // or "api_keys": ["key1", "key2"]
+      "base_url": ""  // optional for self-hosted
+    }
+  }
+}
+```
+
+## Tool Result Structure
+
+Tools return `*ToolResult` with the following fields:
+
+```go
+type ToolResult struct {
+    ForLLM      string        // Text returned to LLM for processing
+    ForUser     string        // Text shown to end user in chat
+    MediaURLs   []string      // Media attachment URLs (media:// or http://)
+    IsError     bool          // Whether execution failed
+    Async       bool          // True if running asynchronously
+    Err         error         // Underlying Go error (not serialized to JSON)
+}
+```
+
+## MCP (Model Context Protocol) Integration
+
+PicoClaw exposes tools via MCP server (`pkg/mcp/manager.go`):
+
+- External MCP servers can be integrated
+- Tools from MCP servers appear as hidden tools with TTL
+- Discovery tools (`tool_search_tool_regex`, `tool_search_tool_bm25`) make hidden tools available
+- MCP manager handles tool execution via isolated command transport
+
+**MCP Tool Discovery Flow**:
+1. MCP server registered with PicoClaw
+2. Tools exposed as hidden (TTL=0, not visible to LLM)
+3. Agent uses `tool_search_tool_regex` or `tool_search_tool_bm25`
+4. Matching tools promoted (TTL set >0)
+5. Promoted tools appear in next LLM context
+
+## Configuration
+
+Tools configured in `config.json` under `tools` section:
+
+```json
+{
+  "tools": {
+    "read_file": {"enabled": true},
+    "write_file": {"enabled": true},
+    "exec": {"enabled": true},
+    "web": {
+      "enabled": true,
+      "provider": "brave",
+      "brave": {
+        "enabled": true,
+        "max_results": 10,
+        "api_keys": ["BSA..."]
+      }
+    },
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "use_regex": true,
+        "use_bm25": false
+      }
+    }
+  }
+}
+```
+
+## Security Considerations
+
+1. **Path Restrictions**: Filesystem tools restrict access to workspace by default
+2. **Shell Command Filtering**: Dangerous commands blocked via regex patterns
+3. **Tool TTL**: Hidden tools auto-expire to prevent context bloat
+4. **Media Store**: File paths converted to `media://` URLs for safe transport
+5. **Panic Recovery**: Tool panics recovered to prevent agent crashes
+6. **Symlink Resolution**: Prevents escaping workspace via symlinks
+
+## Tool Registration Example
+
+```go
+// Register a core tool (always available)
+registry.Register(tools.NewReadFileTool(workspace, true, 64*1024))
+
+// Register a hidden tool (TTL-based)
+registry.RegisterHidden(tools.NewRegexSearchTool(registry, 5, 10))
+
+// Promote hidden tools (make them available to LLM)
+registry.PromoteTools([]string{"tool_search_tool_regex"}, 10)  // TTL=10 turns
+```
--- a/project-map.md
+++ b/project-map.md
@ -0,0 +1,92 @@
+# Project Map
+_Generated: 2026-05-05 | Git: 07107384_
+
+## Directory Structure
+cmd/ — CLI entry points (picoclaw main, membench, internal subcommands)
+pkg/ — Core library packages (agent, channels, providers, tools, etc.)
+web/frontend/ — Frontend UI (React/TypeScript with TanStack)
+web/backend/ — Backend API server (Go, dashboard auth, middleware)
+workspace/ — Runtime workspace (skills, memory)
+docs/ — Documentation (architecture, channels, guides, migration, reference)
+docs/reference/tools-api.md — Complete tools API documentation: available tools, data structures, backend API endpoints, MCP integration
+config/ — Configuration templates and examples
+build/ — Build scripts and artifacts
+docker/ — Docker containerization files
+scripts/ — Automation and utility scripts
+examples/ — Example projects (pico-echo-server)
+assets/ — Static assets (logo, images)
+
+## Key Files
+cmd/picoclaw/main.go — Main CLI entry point using Cobra; registers subcommands (agent, auth, gateway, mcp, migrate, model, skills, etc.)
+cmd/picoclaw/internal/ — Internal CLI command implementations (agent, auth, gateway, mcp, migrate, model, skills, status, version, onboard, cron, cliui)
+pkg/agent/ — Core agent logic: context management, pipelines (setup/llm/finalize), turn coordination, event handling, hooks, steering, thinking, prompt contributors
+pkg/agent/context_manager.go — Manages LLM context lifecycle, caching, and budget enforcement
+pkg/agent/pipeline.go — Orchestrates agent execution phases (setup → LLM → tools → finalize)
+pkg/channels/ — Multi-platform chat integrations: Discord, Telegram, Slack, WeChat, WeCom, Feishu, DingTalk, IRC, LINE, Matrix, VK, WhatsApp, OneBot, MaixCam, Pico
+pkg/providers/ — AI model provider integrations: Anthropic, OpenAI-compatible, Azure, AWS Bedrock, CLI, HTTP API; shared protocol types and OAuth
+pkg/config/ — Configuration loading, validation, and environment variable handling
+pkg/skills/ — Skills system for extending agent capabilities
+pkg/tools/ — Built-in tools: filesystem (fs), hardware interaction, shared utilities, integration tools
+pkg/mcp/ — Model Context Protocol (MCP) server implementation for tool/resource exposure
+pkg/memory/ — Agent memory management (short-term/long-term, persistence)
+pkg/gateway/ — Gateway for routing messages between channels and agents
+pkg/auth/ — Authentication and credential management (OAuth, API keys, encryption)
+pkg/identity/ — Identity and user/session management
+pkg/session/ — Session state management across channels
+pkg/state/ — Application state persistence
+pkg/credential/ — Secure credential storage (ChaCha20-Poly1305 encryption)
+pkg/routing/ — Message routing logic between channels, agents, and models
+pkg/bus/ — Internal event bus for decoupled communication
+pkg/events/ — Event definitions and handling (device events, system events)
+pkg/cron/ — Cron-based scheduling for periodic tasks
+pkg/logger/ — Logging infrastructure
+pkg/health/ — Health check endpoints and diagnostics
+pkg/heartbeat/ — Heartbeat/keepalive mechanism for long-running processes
+pkg/updater/ — Self-update functionality (minio/selfupdate)
+pkg/migrate/ — Database and config migration utilities
+pkg/media/ — Media processing (images, audio)
+pkg/audio/asr/ — Automatic Speech Recognition (ASR) providers
+pkg/audio/tts/ — Text-to-Speech (TTS) providers
+pkg/tokenizer/ — Token counting and management for LLM context budgets
+pkg/netbind/ — Network binding utilities for embedded/specific network configs
+pkg/fileutil/ — File utility functions
+pkg/devices/ — Device management (events, sources) for hardware integrations
+pkg/isolation/ — Sandboxing and isolation for security
+pkg/seahorse/ — Seahorse integration (encrypted storage)
+pkg/constants/ — Package-level constants
+web/backend/api/ — Backend API route definitions
+web/backend/middleware/ — HTTP middleware (auth, CORS, logging)
+web/backend/dashboardauth/ — Dashboard authentication logic
+web/backend/model/ — Backend data models
+web/backend/launcherconfig/ — Launcher configuration
+web/frontend/src/ — Frontend source (components, routes, store, features, hooks, lib, api, i18n)
+go.mod — Go 1.25.9 module definition; key deps: Cobra, DiscordGo, Telego, Anthropic SDK, AWS SDK v2, MCP SDK, gRPC, various channel SDKs
+go.sum — Dependency checksums
+Makefile — Build targets (build, test, lint, release)
+.goreleaser.yaml — GoReleaser config for cross-platform releases
+.golangci.yaml — GolangCI-Lint configuration
+README.md — Project overview: ultra-lightweight AI assistant for $10 hardware, <10MB RAM, inspired by NanoBot
+ROADMAP.md — Vision: lightweight, secure, autonomous AI Agent; core optimization, security hardening, protocol-first architecture
+CONTRIBUTING.md — Contribution guidelines
+LICENSE — MIT License
+.env.example — Example environment variables template
+.dockerignore / .gitignore — Ignore rules for Docker and Git
+
+## Critical Constraints
+- Target: Runs on $10 hardware (e.g., RISC-V SBCs) with <10MB RAM, core process <20MB for 64MB boards
+- Go 1.25.9 required (very recent version)
+- Self-bootstrapped: AI Agent drove architecture migration and optimization (not a fork)
+- Memory optimization takes precedence over storage size
+- Security: Prompt injection defense, tool abuse prevention, SSRF protection, filesystem sandbox, context isolation, privacy redaction
+- Crypto: Uses ChaCha20-Poly1305 for secret storage (upgrade from older algorithms)
+- OAuth 2.0 Flow: Deprecating hardcoded API keys in CLI
+- Architecture: Migrating from "Vendor-based" to "Protocol-based" classification (OpenAI-compatible, Ollama-compatible)
+- Multi-architecture: x86_64, ARM64, MIPS, RISC-V, LoongArch
+- Channel diversity: 14+ chat platforms supported with platform-specific adapters
+- Provider diversity: Anthropic, OpenAI-compat, Azure, Bedrock, local (Ollama, vLLM, LM Studio, Mistral)
+- Frontend: TypeScript/React with TanStack router/query
+- Build: Makefile + GoReleaser for cross-platform binaries
+- Workspace: Skills and memory stored in workspace/ directory at runtime
+
+## Hot Files
+pkg/agent/agent.go, pkg/agent/pipeline.go, pkg/agent/context_manager.go, pkg/agent/definition.go, pkg/channels/ (multiple files), pkg/providers/ (multiple files), cmd/picoclaw/main.go, pkg/config/, web/backend/api/, web/frontend/src/
--- a/session-log.md
+++ b/session-log.md
@ -0,0 +1,23 @@
+## 2026-05-05 00:00 [saved]
+
+Goal: Initial project setup - create memory files for PicoClaw project
+Decisions:
+
+- Initialized git repository for staleness tracking (enables precise project-map.md freshness checks)
+- Created project-map.md with directory structure, key files, critical constraints, and hot files
+- Created CLAUDE.md with build commands, environment setup, critical constraints, and architecture notes
+- Project is PicoClaw: ultra-lightweight AI assistant in Go targeting low end hardware with <50MB RAM
+Rejected: None (initial setup)
+## 2026-05-05 00:01 [saved]
+Goal: Document tools implementation and backend API interaction
+Decisions:
+- Created docs/tools-api.md with comprehensive tools documentation
+- Documented all 20+ tools across 8 categories (filesystem, automation, web, communication, skills, agents, hardware, discovery)
+- Documented backend API endpoints for tool management (GET/PUT /api/tools, web-search-config)
+- Documented tool data structures (Tool interface, ToolResult, SubTurnConfig)
+- Documented MCP integration and tool discovery flow
+- Documented security considerations and configuration examples
+Rejected: None
+Open: None
+
+Open: None