ec81dc9ddc
- Archive all existing markdown documentation files - Create comprehensive HAP_ACTION_PLAN.md with: * Analysis of current BZZZ implementation vs HAP vision * 4-phase implementation strategy * Structural reorganization approach (multi-binary) * HAP interface implementation roadmap - Preserve existing functionality while adding human agent portal - Focus on incremental migration over rewrite 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
228 lines
8.4 KiB
Markdown
228 lines
8.4 KiB
Markdown
# BZZZ Human Agent Portal (HAP) — Implementation Action Plan
|
|
|
|
**Goal:**
|
|
Transform the existing BZZZ autonomous agent system into a dual-binary architecture supporting both autonomous agents and human agent portals using shared P2P infrastructure.
|
|
|
|
---
|
|
|
|
## 🔍 Current State Analysis
|
|
|
|
### ✅ What We Have
|
|
BZZZ currently implements a **comprehensive P2P autonomous agent system** with:
|
|
|
|
- **P2P Infrastructure**: libp2p mesh with mDNS discovery
|
|
- **Agent Identity**: Crypto-based agent records (`pkg/agentid/`)
|
|
- **Messaging**: HMMM collaborative reasoning integration
|
|
- **Storage**: DHT with role-based Age encryption
|
|
- **Addressing**: UCXL context resolution system (`pkg/ucxl/`)
|
|
- **Coordination**: SLURP task distribution (`pkg/slurp/`)
|
|
- **Configuration**: Role-based agent definitions
|
|
- **Web Interface**: Setup and configuration UI
|
|
|
|
### ⚠️ What's Missing
|
|
- **Multi-binary architecture** (currently single `main.go`)
|
|
- **Human interface layer** for message composition and interaction
|
|
- **HAP-specific workflows** (templated forms, prompts, context browsing)
|
|
|
|
---
|
|
|
|
## 📋 Implementation Phases
|
|
|
|
### Phase 1: Structural Reorganization (HIGH PRIORITY)
|
|
**Goal**: Split monolithic binary into shared runtime + dual binaries
|
|
|
|
#### Tasks:
|
|
- [ ] **1.1** Create `cmd/agent/main.go` (move existing `main.go`)
|
|
- [ ] **1.2** Create `cmd/hap/main.go` (new human portal entry point)
|
|
- [ ] **1.3** Extract shared initialization to `internal/common/runtime/`
|
|
- [ ] **1.4** Update `Makefile` to build both `bzzz-agent` and `bzzz-hap` binaries
|
|
- [ ] **1.5** Test autonomous agent functionality remains identical
|
|
|
|
**Key Changes:**
|
|
```
|
|
/cmd/
|
|
/agent/main.go # Existing autonomous agent logic
|
|
/hap/main.go # New human agent portal
|
|
/internal/common/
|
|
/runtime/ # Shared P2P, config, services initialization
|
|
agent.go
|
|
config.go
|
|
services.go
|
|
```
|
|
|
|
**Success Criteria:**
|
|
- Both binaries compile successfully
|
|
- `bzzz-agent` maintains all current functionality
|
|
- `bzzz-hap` can join P2P mesh as peer
|
|
|
|
### Phase 2: HAP Interface Implementation (MEDIUM PRIORITY)
|
|
**Goal**: Create human-friendly interaction layer
|
|
|
|
#### Tasks:
|
|
- [ ] **2.1** Implement basic terminal interface in `internal/hapui/terminal.go`
|
|
- [ ] **2.2** Create message composition templates for HMMM messages
|
|
- [ ] **2.3** Add context browsing interface for UCXL addresses
|
|
- [ ] **2.4** Implement justification prompts and metadata helpers
|
|
- [ ] **2.5** Test human agent can send/receive HMMM messages
|
|
|
|
**Key Components:**
|
|
```
|
|
/internal/hapui/
|
|
forms.go # Templated message composition
|
|
terminal.go # Terminal-based human interface
|
|
context.go # UCXL context browsing helpers
|
|
prompts.go # Justification and metadata prompts
|
|
```
|
|
|
|
**Success Criteria:**
|
|
- Human can compose and send HMMM messages via terminal
|
|
- Context browsing works for UCXL addresses
|
|
- HAP appears as valid agent to autonomous peers
|
|
|
|
### Phase 3: Enhanced Human Workflows (MEDIUM PRIORITY)
|
|
**Goal**: Add sophisticated human agent features
|
|
|
|
#### Tasks:
|
|
- [ ] **3.1** Implement patch creation and submission workflows
|
|
- [ ] **3.2** Add time-travel diff support (`~~`, `^^` operators)
|
|
- [ ] **3.3** Create collaborative editing interfaces
|
|
- [ ] **3.4** Add decision tracking and approval workflows
|
|
- [ ] **3.5** Implement web bridge for browser-based HAP interface
|
|
|
|
**Advanced Features:**
|
|
- Patch preview before submission to DHT
|
|
- Approval chains for architectural decisions
|
|
- Real-time collaboration on UCXL contexts
|
|
- WebSocket bridge to web UI for rich interface
|
|
|
|
**Success Criteria:**
|
|
- Humans can create and submit patches via HAP
|
|
- Approval workflows integrate with existing SLURP coordination
|
|
- Web interface provides richer interaction than terminal
|
|
|
|
### Phase 4: Integration & Optimization (LOW PRIORITY)
|
|
**Goal**: Polish and optimize the dual-agent system
|
|
|
|
#### Tasks:
|
|
- [ ] **4.1** Enhance `AgentID` structure to match HAP plan specification
|
|
- [ ] **4.2** Optimize resource usage for dual-binary deployment
|
|
- [ ] **4.3** Add comprehensive testing for human/machine agent interactions
|
|
- [ ] **4.4** Document HAP usage patterns and workflows
|
|
- [ ] **4.5** Create deployment guides for mixed agent teams
|
|
|
|
**Refinements:**
|
|
- Performance optimization for shared P2P layer
|
|
- Memory usage optimization when running both binaries
|
|
- Enhanced logging and monitoring for human activities
|
|
- Integration with existing health monitoring system
|
|
|
|
---
|
|
|
|
## 🧱 Architecture Alignment
|
|
|
|
### Current vs Planned Structure
|
|
|
|
| Component | Current Status | HAP Plan Status | Action Required |
|
|
|-----------|----------------|-----------------|-----------------|
|
|
| **Multi-binary** | ❌ Single `main.go` | Required | **Phase 1** restructure |
|
|
| **Agent Identity** | ✅ `pkg/agentid/` | ✅ Compatible | Minor enhancement |
|
|
| **HMMM Messages** | ✅ Integrated | ✅ Complete | None |
|
|
| **UCXL Context** | ✅ Full implementation | ✅ Complete | None |
|
|
| **DHT Storage** | ✅ Encrypted, distributed | ✅ Complete | None |
|
|
| **PubSub Comms** | ✅ Role-based topics | ✅ Complete | None |
|
|
| **HAP Interface** | ❌ Not implemented | Required | **Phase 2-3** |
|
|
|
|
### Shared Runtime Components
|
|
Both `bzzz-agent` and `bzzz-hap` will share:
|
|
|
|
- **P2P networking** and peer discovery
|
|
- **Agent identity** and cryptographic signing
|
|
- **HMMM message** validation and routing
|
|
- **UCXL address** resolution and context storage
|
|
- **DHT operations** for distributed state
|
|
- **Configuration system** and role definitions
|
|
|
|
**Only the execution loop and UI modality differ between binaries.**
|
|
|
|
---
|
|
|
|
## 🔧 Implementation Strategy
|
|
|
|
### Incremental Migration Approach
|
|
1. **Preserve existing functionality** - autonomous agents continue working
|
|
2. **Add HAP alongside** existing system rather than replacing
|
|
3. **Test continuously** - both binaries must interoperate correctly
|
|
4. **Gradual enhancement** - start with basic HAP, add features incrementally
|
|
|
|
### Key Principles
|
|
- **Backward compatibility**: Existing BZZZ deployments unaffected
|
|
- **Shared protocols**: Human and machine agents are indistinguishable on P2P mesh
|
|
- **Common codebase**: Maximum code reuse between binaries
|
|
- **Incremental delivery**: Each phase delivers working functionality
|
|
|
|
### Risk Mitigation
|
|
- **Comprehensive testing** after each phase
|
|
- **Feature flags** to enable/disable HAP features during development
|
|
- **Rollback capability** to single binary if needed
|
|
- **Documentation** of breaking changes and migration steps
|
|
|
|
---
|
|
|
|
## 📈 Success Metrics
|
|
|
|
### Phase 1 Success
|
|
- [ ] `make build` produces both `bzzz-agent` and `bzzz-hap` binaries
|
|
- [ ] Existing autonomous agent functionality unchanged
|
|
- [ ] Both binaries can join same P2P mesh
|
|
|
|
### Phase 2 Success
|
|
- [ ] Human can send HMMM messages via HAP terminal interface
|
|
- [ ] HAP appears as valid agent to autonomous peers
|
|
- [ ] Message composition templates functional
|
|
|
|
### Phase 3 Success
|
|
- [ ] Patch submission workflows complete
|
|
- [ ] Web interface provides rich HAP experience
|
|
- [ ] Human/machine agent collaboration demonstrated
|
|
|
|
### Overall Success
|
|
- [ ] Mixed teams of human and autonomous agents collaborate seamlessly
|
|
- [ ] HAP provides superior human experience compared to direct protocol interaction
|
|
- [ ] System maintains all existing performance and reliability characteristics
|
|
|
|
---
|
|
|
|
## 🎯 Next Steps
|
|
|
|
### Immediate Actions (This Sprint)
|
|
1. **Create cmd/ structure** and move main.go to cmd/agent/
|
|
2. **Stub cmd/hap/main.go** with basic P2P initialization
|
|
3. **Extract common runtime** to internal/common/
|
|
4. **Update Makefile** for dual binary builds
|
|
5. **Test agent binary** maintains existing functionality
|
|
|
|
### Short Term (Next 2-4 weeks)
|
|
1. **Implement basic HAP terminal interface**
|
|
2. **Add HMMM message composition**
|
|
3. **Test human agent P2P participation**
|
|
4. **Document HAP usage patterns**
|
|
|
|
### Medium Term (1-2 months)
|
|
1. **Add web bridge for browser interface**
|
|
2. **Implement patch workflows**
|
|
3. **Add collaborative features**
|
|
4. **Optimize performance**
|
|
|
|
---
|
|
|
|
## 📚 Resources & References
|
|
|
|
- **Original HAP Plan**: `archive/bzzz_hap_dev_plan.md`
|
|
- **Current Architecture**: `pkg/` directory structure
|
|
- **P2P Infrastructure**: `p2p/`, `pubsub/`, `pkg/dht/`
|
|
- **Agent Identity**: `pkg/agentid/`, `pkg/crypto/`
|
|
- **Messaging**: `pkg/hmmm_adapter/`, HMMM integration
|
|
- **Context System**: `pkg/ucxl/`, `pkg/ucxi/`
|
|
- **Configuration**: `pkg/config/`, role definitions
|
|
|
|
The current BZZZ implementation provides an excellent foundation for the HAP vision. The primary challenge is architectural restructuring rather than building new functionality from scratch. |