bzzz/HAP_ACTION_PLAN.md

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.