From ab23be43a98f0639ba7e0ae1910b01f115e4ea8b Mon Sep 17 00:00:00 2001 From: anthrodjear Date: Tue, 5 May 2026 05:49:21 +0300 Subject: [PATCH] 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 --- CLAUDE.md | 37 ++ .../hooks/plugin-tool-injection.md | 1 + docs/reference/tools-api.md | 453 ++++++++++++++++++ project-map.md | 92 ++++ session-log.md | 23 + 5 files changed, 606 insertions(+) create mode 100644 CLAUDE.md create mode 100644 docs/reference/tools-api.md create mode 100644 project-map.md create mode 100644 session-log.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..0492f7381 --- /dev/null +++ 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 diff --git a/docs/architecture/hooks/plugin-tool-injection.md b/docs/architecture/hooks/plugin-tool-injection.md index 9e699867b..7117eba03 100644 --- 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 diff --git a/docs/reference/tools-api.md b/docs/reference/tools-api.md new file mode 100644 index 000000000..165c33279 --- /dev/null +++ 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:/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 +``` diff --git a/project-map.md b/project-map.md new file mode 100644 index 000000000..35c3f0f2d --- /dev/null +++ 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/ diff --git a/session-log.md b/session-log.md new file mode 100644 index 000000000..9db18839f --- /dev/null +++ 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