docs: update CLAUDE.md for recently merged features (#183)

* docs: update CLAUDE.md for recently merged features Document skills system, sandbox network proxy, leak detector, Tinfoil private inference, setup wizard, and shell env scrubbing that were merged but not reflected in CLAUDE.md. Co-Authored-By: Claude Opus 4.6 <[email protected]> * docs: fix SKILL.md format example and scoring description Align SKILL.md frontmatter example with actual SkillManifest struct: activation block with patterns/keywords/max_context_tokens, requires nested under metadata.openclaw. Fix scoring pipeline description to mention keywords, tags, and regex patterns instead of triggers/intents. Co-Authored-By: Claude Opus 4.6 <[email protected]> * docs: optimize CLAUDE.md structure and reduce from 959 to 671 lines - Update llm/ directory tree (4 -> 12 files to match actual codebase) - Fix "NEAR AI (required)" -> "NEAR AI (when LLM_BACKEND=nearai)" - Remove 28-item Completed changelog list (no actionable value) - Deduplicate 3 config blocks with cross-references - Extract Workspace deep-dive to src/workspace/README.md - Extract Tool Architecture deep-dive to src/tools/README.md - Consolidate Code Style and Review Discipline under Key Patterns - Add workspace and tools to Module Specifications table Co-Authored-By: Claude Opus 4.6 <[email protected]> --------- Co-authored-by: Claude Opus 4.6 <[email protected]>
2026-08-25 14:53:34 +00:00 · 2026-02-20 01:04:39 +00:00
parent 17434d6499
commit 356f56f77c
3 changed files with 448 additions and 328 deletions
@@ -0,0 +1,136 @@
+# Tool System
+
+## Adding a New Tool
+
+### Built-in Tools (Rust)
+
+1. Create `src/tools/builtin/my_tool.rs`
+2. Implement the `Tool` trait
+3. Add `mod my_tool;` and `pub use` in `src/tools/builtin/mod.rs`
+4. Register in `ToolRegistry::register_builtin_tools()` in `registry.rs`
+5. Add tests
+
+### WASM Tools (Recommended)
+
+WASM tools are the preferred way to add new capabilities. They run in a sandboxed environment with explicit capabilities.
+
+1. Create a new crate in `tools-src/<name>/`
+2. Implement the WIT interface (`wit/tool.wit`)
+3. Create `<name>.capabilities.json` declaring required permissions
+4. Build with `cargo build --target wasm32-wasip2 --release`
+5. Install with `ironclaw tool install path/to/tool.wasm`
+
+See `tools-src/` for examples.
+
+## Tool Architecture Principles
+
+**CRITICAL: Keep tool-specific logic out of the main agent codebase.**
+
+The main agent provides generic infrastructure; tools are self-contained units that declare their requirements through capabilities files.
+
+### What Goes in Tools (capabilities.json)
+
+- API endpoints the tool needs (HTTP allowlist)
+- Credentials required (secret names, injection locations)
+- Rate limits and timeouts
+- Auth setup instructions (see below)
+- Workspace paths the tool can read
+
+### What Does NOT Go in Main Agent
+
+- Service-specific auth flows (OAuth for Notion, Slack, etc.)
+- Service-specific CLI commands (`auth notion`, `auth slack`)
+- Service-specific configuration handling
+- Hardcoded API URLs or token formats
+
+### Tool Authentication
+
+Tools declare their auth requirements in `<tool>.capabilities.json` under the `auth` section. Two methods are supported:
+
+#### OAuth (Browser-based login)
+
+For services that support OAuth, users just click through browser login:
+
+```json
+{
+  "auth": {
+    "secret_name": "notion_api_token",
+    "display_name": "Notion",
+    "oauth": {
+      "authorization_url": "https://api.notion.com/v1/oauth/authorize",
+      "token_url": "https://api.notion.com/v1/oauth/token",
+      "client_id_env": "NOTION_OAUTH_CLIENT_ID",
+      "client_secret_env": "NOTION_OAUTH_CLIENT_SECRET",
+      "scopes": [],
+      "use_pkce": false,
+      "extra_params": { "owner": "user" }
+    },
+    "env_var": "NOTION_TOKEN"
+  }
+}
+```
+
+To enable OAuth for a tool:
+1. Register a public OAuth app with the service (e.g., notion.so/my-integrations)
+2. Configure redirect URIs: `http://localhost:9876/callback` through `http://localhost:9886/callback`
+3. Set environment variables for client_id and client_secret
+
+#### Manual Token Entry (Fallback)
+
+For services without OAuth or when OAuth isn't configured:
+
+```json
+{
+  "auth": {
+    "secret_name": "openai_api_key",
+    "display_name": "OpenAI",
+    "instructions": "Get your API key from platform.openai.com/api-keys",
+    "setup_url": "https://platform.openai.com/api-keys",
+    "token_hint": "Starts with 'sk-'",
+    "env_var": "OPENAI_API_KEY"
+  }
+}
+```
+
+#### Auth Flow Priority
+
+When running `ironclaw tool auth <tool>`:
+
+1. Check `env_var` - if set in environment, use it directly
+2. Check `oauth` - if configured, open browser for OAuth flow
+3. Fall back to `instructions` + manual token entry
+
+The agent reads auth config from the tool's capabilities file and provides the appropriate flow. No service-specific code in the main agent.
+
+### WASM Tools vs MCP Servers: When to Use Which
+
+Both are first-class in the extension system (`ironclaw tool install` handles both), but they have different strengths.
+
+**WASM Tools (IronClaw native)**
+
+- Sandboxed: fuel metering, memory limits, no access except what's allowlisted
+- Credentials injected by host runtime, tool code never sees the actual token
+- Output scanned for secret leakage before returning to the LLM
+- Auth (OAuth/manual) declared in `capabilities.json`, agent handles the flow
+- Single binary, no process management, works offline
+- Cost: must build yourself in Rust, no ecosystem, synchronous only
+
+**MCP Servers (Model Context Protocol)**
+
+- Growing ecosystem of pre-built servers (GitHub, Notion, Postgres, etc.)
+- Any language (TypeScript/Python most common)
+- Can do websockets, streaming, background polling
+- Cost: external process with full system access (no sandbox), manages own credentials, IronClaw can't prevent leaks
+
+**Decision guide:**
+
+| Scenario | Use |
+|----------|-----|
+| Good MCP server already exists | **MCP** |
+| Handles sensitive credentials (email send, banking) | **WASM** |
+| Quick prototype or one-off integration | **MCP** |
+| Core capability you'll maintain long-term | **WASM** |
+| Needs background connections (websockets, polling) | **MCP** |
+| Multiple tools share one OAuth token (e.g., Google suite) | **WASM** |
+
+The LLM-facing interface is identical for both (tool name, schema, execute), so swapping between them is transparent to the agent.
@@ -0,0 +1,111 @@
+# Workspace & Memory System
+
+Inspired by [OpenClaw](https://github.com/openclaw/openclaw), the workspace provides persistent memory for agents with a flexible filesystem-like structure.
+
+## Key Principles
+
+1. **"Memory is database, not RAM"** - If you want to remember something, write it explicitly
+2. **Flexible structure** - Create any directory/file hierarchy you need
+3. **Self-documenting** - Use README.md files to describe directory structure
+4. **Hybrid search** - Combines FTS (keyword) + vector (semantic) via Reciprocal Rank Fusion
+
+## Filesystem Structure
+
+```
+workspace/
+├── README.md              <- Root runbook/index
+├── MEMORY.md              <- Long-term curated memory
+├── HEARTBEAT.md           <- Periodic checklist
+├── IDENTITY.md            <- Agent name, nature, vibe
+├── SOUL.md                <- Core values
+├── AGENTS.md              <- Behavior instructions
+├── USER.md                <- User context
+├── context/               <- Identity-related docs
+│   ├── vision.md
+│   └── priorities.md
+├── daily/                 <- Daily logs
+│   ├── 2024-01-15.md
+│   └── 2024-01-16.md
+├── projects/              <- Arbitrary structure
+│   └── alpha/
+│       ├── README.md
+│       └── notes.md
+└── ...
+```
+
+## Using the Workspace
+
+```rust
+use crate::workspace::{Workspace, OpenAiEmbeddings, paths};
+
+// Create workspace for a user
+let workspace = Workspace::new("user_123", pool)
+    .with_embeddings(Arc::new(OpenAiEmbeddings::new(api_key)));
+
+// Read/write any path
+let doc = workspace.read("projects/alpha/notes.md").await?;
+workspace.write("context/priorities.md", "# Priorities\n\n1. Feature X").await?;
+workspace.append("daily/2024-01-15.md", "Completed task X").await?;
+
+// Convenience methods for well-known files
+workspace.append_memory("User prefers dark mode").await?;
+workspace.append_daily_log("Session note").await?;
+
+// List directory contents
+let entries = workspace.list("projects/").await?;
+
+// Search (hybrid FTS + vector)
+let results = workspace.search("dark mode preference", 5).await?;
+
+// Get system prompt from identity files
+let prompt = workspace.system_prompt().await?;
+```
+
+## Memory Tools
+
+Four tools for LLM use:
+
+- **`memory_search`** - Hybrid search, MUST be called before answering questions about prior work
+- **`memory_write`** - Write to any path (memory, daily_log, or custom paths)
+- **`memory_read`** - Read any file by path
+- **`memory_tree`** - View workspace structure as a tree (depth parameter, default 1)
+
+## Hybrid Search (RRF)
+
+Combines full-text search and vector similarity using Reciprocal Rank Fusion:
+
+```
+score(d) = Σ 1/(k + rank(d)) for each method where d appears
+```
+
+Default k=60. Results from both methods are combined, with documents appearing in both getting boosted scores.
+
+**Backend differences:**
+- **PostgreSQL:** `ts_rank_cd` for FTS, pgvector cosine distance for vectors, full RRF
+- **libSQL:** FTS5 for keyword search only (vector search via `libsql_vector_idx` not yet wired)
+
+## Heartbeat System
+
+Proactive periodic execution (default: 30 minutes):
+
+1. Reads `HEARTBEAT.md` checklist
+2. Runs agent turn with checklist prompt
+3. If findings, notifies via channel
+4. If nothing, agent replies "HEARTBEAT_OK" (no notification)
+
+```rust
+use crate::agent::{HeartbeatConfig, spawn_heartbeat};
+
+let config = HeartbeatConfig::default()
+    .with_interval(Duration::from_secs(60 * 30))
+    .with_notify("user_123", "telegram");
+
+spawn_heartbeat(config, workspace, llm, response_tx);
+```
+
+## Chunking Strategy
+
+Documents are chunked for search indexing:
+- Default: 800 words per chunk (roughly 800 tokens for English)
+- 15% overlap between chunks for context preservation
+- Minimum chunk size: 50 words (tiny trailing chunks merge with previous)