Files
timmy-home/epics/EPIC-202-claw-agent.md

163 lines
4.5 KiB
Markdown
Raw Normal View History

# EPIC-202: Build Claw-Architecture Agent
**Status:** In Progress
**Priority:** P0
**Milestone:** M1: Core Architecture
**Created:** 2026-03-31
**Author:** Allegro
---
## Objective
Create a NEW autonomous agent using architectural patterns from [Claw Code](http://143.198.27.163:3000/Timmy/claw-code), integrated with Gitea for real work dispatch.
## Problem Statement
**Allegro-Primus is IDLE.**
- Gateway running (PID 367883) but zero meaningful output
- No Gitea issues created
- No PRs submitted
- No actual work completed
This agent will **replace** Allegro-Primus with real capabilities.
---
## Claw Patterns to Adopt
### 1. ToolPermissionContext
```python
@dataclass
class ToolPermissionContext:
deny_tools: set[str]
deny_prefixes: tuple[str, ...]
def blocks(self, tool_name: str) -> bool:
return tool_name in self.deny_tools or \
any(tool_name.startswith(p) for p in self.deny_prefixes)
```
**Why:** Fine-grained tool access control vs Hermes basic approval
### 2. ExecutionRegistry
```python
class ExecutionRegistry:
def command(self, name: str) -> CommandHandler
def tool(self, name: str) -> ToolHandler
def execute(self, context: PermissionContext) -> Result
```
**Why:** Clean routing vs Hermes model-decided routing
### 3. Session Persistence
```python
@dataclass
class RuntimeSession:
prompt: str
context: PortContext
history: HistoryLog
persisted_path: str
```
**Why:** JSON-based sessions vs SQLite - more portable, inspectable
### 4. Bootstrap Graph
```python
def build_bootstrap_graph() -> Graph:
# Setup phases
# Context building
# System init messages
```
**Why:** Structured initialization vs ad-hoc setup
---
## Implementation Plan
### Phase 1: Core Architecture (2 days)
- [ ] Create new Hermes profile: `claw-agent`
- [ ] Implement ToolPermissionContext
- [ ] Create ExecutionRegistry
- [ ] Build Session persistence layer
### Phase 2: Gitea Integration (2 days)
- [ ] Gitea client with issue querying
- [ ] Work scheduler for autonomous cycles
- [ ] PR creation and review assistance
### Phase 3: Deployment (1 day)
- [ ] Telegram bot integration
- [ ] Cron scheduling
- [ ] Health monitoring
---
## Success Criteria
| Criteria | How We'll Verify |
|----------|-----------------|
| Receives Telegram tasks | Send test message, agent responds |
| Queries Gitea issues | Agent lists open P0 issues |
| Permission checks work | Blocked tool returns error |
| Session persistence | Restart agent, history intact |
| Progress reports | Agent sends Telegram updates |
---
## Resource Requirements
| Resource | Status |
|----------|--------|
| Gitea API token | ✅ Have |
| Kimi API key | ✅ Have |
| Telegram bot | ⏳ Need @BotFather |
| New profile | ⏳ Will create |
---
## References
- [Claw Code Mirror](http://143.198.27.163:3000/Timmy/claw-code)
- [Claw Issue #1 - Architecture](http://143.198.27.163:3000/Timmy/claw-code/issues/1)
- [Hermes v0.6 Profiles](../docs/profiles.md)
---
## Tickets
- #203: Implement ToolPermissionContext
- #204: Create ExecutionRegistry
- #205: Build Session Persistence
- #206: Gitea Integration
- #207: Telegram Deployment
---
*This epic supersedes Allegro-Primus who has been idle.*
---
## Feedback — 2026-04-06 (Allegro Cross-Epic Review)
**Health:** 🟡 Yellow
**Blocker:** Gitea externally firewalled + no Allegro-Primus RCA
### Critical Issues
1. **Dependency blindness.** Every Claw Code reference points to `143.198.27.163:3000`, which is currently firewalled and unreachable from this VM. If the mirror is not locally cached, development is blocked on external infrastructure.
2. **Root cause vs. replacement.** The epic jumps to "replace Allegro-Primus" without proving he is unfixable. Primus being idle could be the same provider/auth outage that took down Ezra and Bezalel. A 5-line RCA should precede a 5-phase rewrite.
3. **Timeline fantasy.** "Phase 1: 2 days" assumes stable infrastructure. Current reality: Gitea externally firewalled, Bezalel VPS down, Ezra needs webhook switch. This epic needs a "Blocked Until" section.
4. **Resource stalemate.** "Telegram bot: Need @BotFather" — the fleet already operates multiple bots. Reuse an existing bot profile or document why a new one is required.
### Recommended Action
Add a **Pre-Flight Checklist** to the epic:
- [ ] Verify Gitea/Claw Code mirror is reachable from the build VM
- [ ] Publish 1-paragraph RCA on why Allegro-Primus is idle
- [ ] Confirm target repo for the new agent code
Do not start Phase 1 until all three are checked.