# planck-claw Architecture planck-claw is a headless API library for building LLM-powered agents. It provides programmatic access to an agent loop, tool execution, memory, and session management — with no CLI, no built-in UI, and no bundled chat-platform adapters. All LLM traffic is routed through **OpenRouter**. ``` ┌─────────────────────────────────────────────────────────────────┐ │ planck-claw │ │ Headless AI Agent Library │ └─────────────────────────────────────────────────────────────────┘ ┌──────────────────┐ │ Your Application │ │ (imports library) │ └────────┬─────────┘ │ ┌──────────────┼──────────────┐ │ │ │ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ │ Context │ │ Agent Loop│ │ Gateway │ │ Builder │ │ (Core) │ │ Server │ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │ │ │ ┌─────────┼──────────────┼──────────────┼─────────┐ │ │ │ │ │ │ ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐ │ │ │ Memory │ │ Skills │ │ Message │ │ │ │ System │ │ Loader │ │ Bus │ │ │ └───────────┘ └───────────┘ └───────────┘ │ │ │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ OpenRouter │ │ Session Mgr │ │ │ │ Provider │ │ │ │ │ └───────┬───────┘ └───────────────┘ │ │ │ │ │ ┌───────▼───────┐ │ │ │ LLM APIs │ │ │ │ (via OpenRouter)│ │ │ └───────────────┘ │ │ │ │ ┌───────────────┐ │ │ │ Tool Registry │ │ │ └───────┬───────┘ │ │ │ │ │ ┌───────┼───────────────┐ │ │ │ │ │ │ │ ┌─▼─────┐ ┌─▼───────┐ ┌──▼────────┐ │ │ │ Shell │ │Read File│ │Write File │ │ │ │ Tool │ │ Tool │ │ Tool │ │ │ └───────┘ └─────────┘ └───────────┘ │ └─────────────────────────────────────────────┘ ┌─────────────────────────────┐ │ Channel Infrastructure │ │ (BaseChannel + Manager) │ └──────────┬──────────────────┘ │ ┌──────────▼──────────┐ │ ChannelManager │ └─────────┬───────────┘ │ ┌──────▼──────┐ │ Your Custom │ │ Channels │ └─────────────┘ ┌─────────────────────────────┐ │ Background Processing │ └──────────┬──────────────────┘ │ ┌─────────────┼─────────────┐ │ │ │ ┌─────▼──────┐ ┌───▼────────┐ ┌──▼───────┐ │ Subagent │ │ Heartbeat │ │ Cron │ │ Tasks │ │ Monitor │ │ Scheduler│ └────────────┘ └────────────┘ └──────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Configuration Layer │ ├─────────────────────────────────────────────────────────────────┤ │ Programmatic config object (Zod validated) │ │ │ │ ├── providers.openrouter ← OpenRouter API key & settings │ │ ├── agents.defaults ← Model, temperature, prompt │ │ ├── tools ← Tool restrictions │ │ ├── memory/ ← Conversation history │ │ ├── skills/ ← Custom skills (Markdown) │ │ └── sessions/ ← Session metadata │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Data Flow │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. Your code sends a message via the API │ │ ↓ │ │ 2. Agent Loop processes message │ │ ↓ │ │ 3. Context Builder creates prompt (system + history + skills) │ │ ↓ │ │ 4. Request sent to OpenRouter │ │ ↓ │ │ 5. LLM generates response │ │ ↓ │ │ 6. If tool calls → Execute tools │ │ ↓ │ │ 7. Loop back to LLM with tool results │ │ ↓ │ │ 8. Final response returned to caller │ │ ↓ │ │ 9. Memory system saves conversation │ │ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Extension Points │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ • Add new Tool: src/agent/tools/ │ │ • Add new Skill: provide Markdown skill content │ │ • Add new Channel: extend BaseChannel, register with manager │ │ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Technology Stack │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Runtime: Node.js >= 18 │ │ Language: TypeScript 5.x │ │ Build: tsc (TypeScript Compiler) │ │ Module: ESM (ES Modules) │ │ Validation: Zod │ │ HTTP: Axios │ │ Logging: Pino │ │ Linting: ESLint + Prettier │ │ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Key Design Patterns │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ • Registry Pattern: Tools │ │ • Builder Pattern: Context Builder │ │ • Repository Pattern: Memory Storage │ │ • Abstract Factory: BaseChannel for custom integrations │ │ • Pub/Sub: Message Bus │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ## Component Responsibilities ### Agent Loop - Orchestrates conversation flow - Manages tool execution cycle - Handles max iterations - Integrates all components ### Context Builder - Constructs system prompts - Adds skills documentation - Formats tool definitions - Truncates long contexts ### Memory System - Persists conversations - Loads historical messages - Manages message limits - Session isolation ### Skills Loader - Discovers skill files - Parses Markdown skills - Provides skill context - Dynamic reloading ### OpenRouter Provider - Single LLM provider — routes to any model available on OpenRouter - Handles API key authentication - Manages request/response formatting ### Tool Registry - Registers available tools - Executes tool functions - Validates tool calls - Returns structured results ### Configuration - Accepts programmatic config objects - Validates with Zod - Merges env variables - Provides defaults ## Security Layers 1. **Input Validation**: Zod schemas 2. **Command Whitelisting**: Tool restrictions 3. **Workspace Isolation**: Optional sandboxing 4. **Error Handling**: Comprehensive try-catch 5. **Secure IDs**: crypto.randomUUID() 6. **Type Safety**: TypeScript strict mode ## Gateway & Messaging Components ### Gateway Server - Central hub for channel integrations - Routes messages between channels and agent - Manages channel lifecycle - Coordinates with message bus - Handles graceful shutdown ### Message Bus - Event-driven message routing - Pub/sub pattern for scalability - Channel-specific and global handlers - Error isolation per handler - Supports async message processing ### Session Manager - Multi-user session management - Persists session metadata - Tracks user activity across channels - Session cleanup and garbage collection - Channel-aware session isolation ### Subagent Tasks - Background task execution - Configurable concurrency limits - Task queue management - Status tracking (pending/running/completed/failed) - Timeout and cancellation support ### Heartbeat Monitor - Proactive wake-up mechanism - Configurable interval beats - Custom beat handlers - Status monitoring - Can be enabled/disabled via config ### Channel Infrastructure - `BaseChannel` abstract class for building custom integrations - `ChannelManager` for registration and lifecycle - Message format standardization - Connection status tracking - No built-in platform adapters — bring your own ## Gateway Data Flow ``` Custom Channel → Message Bus → Gateway → Agent Loop → Response ↓ ↑ Subscribers Session Manager ``` 1. Your custom channel adapter receives a message 2. Message published to message bus 3. Gateway subscribes to messages 4. Gateway creates/retrieves session 5. Agent Loop processes message 6. Response sent back through the channel adapter ## Adding a Custom Channel 1. Create a channel adapter extending `BaseChannel` 2. Implement required methods: - `initialize()`: Setup channel connection - `start()`: Begin listening for messages - `stop()`: Cleanup and disconnect - `sendMessage()`: Send response to user - `isConnected()`: Check connection status 3. Register channel with `ChannelManager` 4. Channel automatically integrates with the gateway