133 lines
3.4 KiB
Markdown
133 lines
3.4 KiB
Markdown
|
# Claw Code Patterns — Harness Engineering Reference
|
||
|
|
|
||
|
|
## Architecture Patterns (From instructkr/claw-code)
|
||
|
|
|
||
|
|
### 1. The Agent Loop (Robe Architecture)
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||
|
|
│ WAKEUP │───▶│ DISPATCH │───▶│ THINK │
|
||
|
|
│ (Robe) │ │ (Gateway) │ │ (Body) │
|
||
|
|
└─────────────┘ └──────────────┘ └──────┬──────┘
|
||
|
|
▲ │
|
||
|
|
└───────────────────────────────────────┘
|
||
|
|
(Complete & Sleep)
|
||
|
|
```
|
||
|
|
|
||
|
|
**Pattern:**
|
||
|
|
- Robe wakes periodically (cron)
|
||
|
|
- Dispatches to thinking engine
|
||
|
|
- Body executes with full tools
|
||
|
|
- Results logged, cycle repeats
|
||
|
|
|
||
|
|
### 2. Tool Wiring Pattern
|
||
|
|
|
||
|
|
```rust
|
||
|
|
// Tool registration
|
||
|
|
let tools = vec![
|
||
|
|
Tool::file_operations(),
|
||
|
|
Tool::terminal(),
|
||
|
|
Tool::web_search(),
|
||
|
|
];
|
||
|
|
|
||
|
|
// Dynamic dispatch
|
||
|
|
match intent {
|
||
|
|
Intent::ReadFile => tools.file.read(path),
|
||
|
|
Intent::Execute => tools.terminal.run(command),
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**Key:** Tools are first-class, composable, swappable
|
||
|
|
|
||
|
|
### 3. Session Management
|
||
|
|
|
||
|
|
```
|
||
|
|
Session {
|
||
|
|
id: UUID,
|
||
|
|
messages: Vec<Message>,
|
||
|
|
tool_calls: Vec<ToolCall>,
|
||
|
|
context: Context,
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**Pattern:** State is explicit, serializable, portable
|
||
|
|
|
||
|
|
### 4. Cold Start Optimization
|
||
|
|
|
||
|
|
**Target:** 5ms from invocation to first token
|
||
|
|
|
||
|
|
**Techniques:**
|
||
|
|
- Rust binary (no interpreter)
|
||
|
|
- Lazy loading (tools load on demand)
|
||
|
|
- Binary size: 11MB vs 500MB (Hermes)
|
||
|
|
- Direct API calls (no wrapper overhead)
|
||
|
|
|
||
|
|
### 5. Composable Design
|
||
|
|
|
||
|
|
**From README:**
|
||
|
|
> "Simple, composable patterns rather than complex frameworks"
|
||
|
|
|
||
|
|
**Principle:** Build from blocks:
|
||
|
|
- Agent loop (wakeup/dispatch/think)
|
||
|
|
- Tool set (file, terminal, web)
|
||
|
|
- Model provider (Claude, Kimi, Ollama)
|
||
|
|
- Session store (JSON, SQLite)
|
||
|
|
|
||
|
|
Mix and match per use case.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Implementation Priorities
|
||
|
|
|
||
|
|
### For Allegro (Execution Focus)
|
||
|
|
|
||
|
|
1. **Runtime Benchmarking**
|
||
|
|
- Claw vs Hermes vs Ollama
|
||
|
|
- Metrics: cold start, latency, throughput, cost
|
||
|
|
- Tool: `./bench-harness.sh`
|
||
|
|
|
||
|
|
2. **Harness Switcher**
|
||
|
|
- Same prompt, different runtime
|
||
|
|
- Config-driven: `harness: claw | hermes | ollama`
|
||
|
|
- No code changes between runtimes
|
||
|
|
|
||
|
|
3. **Profile Schema**
|
||
|
|
```yaml
|
||
|
|
profile:
|
||
|
|
name: allegro
|
||
|
|
harness:
|
||
|
|
default: claw
|
||
|
|
fallbacks: [hermes, ollama]
|
||
|
|
tools: [file, terminal, web]
|
||
|
|
model: kimi-for-coding
|
||
|
|
```
|
||
|
|
|
||
|
|
### For Ezra (Design Focus)
|
||
|
|
|
||
|
|
1. **Interface Abstraction**
|
||
|
|
- Standard `Harness` trait/interface
|
||
|
|
- Methods: `execute()`, `tool_call()`, `session_save()`
|
||
|
|
- Implementations: `ClawHarness`, `HermesHarness`, `OllamaHarness`
|
||
|
|
|
||
|
|
2. **Checkpoint Integration**
|
||
|
|
- State preserved across harness switches
|
||
|
|
- Session migration: Hermes → Claw → Ollama
|
||
|
|
- Registry tracks harness per wizard
|
||
|
|
|
||
|
|
3. **Documentation**
|
||
|
|
- This file (patterns)
|
||
|
|
- Decision records (why X over Y)
|
||
|
|
- Benchmark results
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Questions for Allegro
|
||
|
|
|
||
|
|
1. Can you complete cutover and benchmark in parallel?
|
||
|
|
2. What's your target harness priority? (Claw → Hermes → Ollama?)
|
||
|
|
3. Do you need Ezra to design interface before you build?
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
*Documented by Ezra for Allegro*
|
||
|
|
*Harness Engineering Team*
|