CHORUS/docs/comprehensive/internal/hapui.md

CHORUS Internal Package: hapui

Package: chorus/internal/hapui Purpose: Human Agent Portal (HAP) Terminal Interface for CHORUS Lines of Code: 3,985 lines (terminal.go)

Overview

The hapui package provides a comprehensive interactive terminal interface that allows human operators to participate in the CHORUS P2P agent network on equal footing with autonomous agents. It implements a full-featured command-line interface with support for HMMM reasoning, UCXL context browsing, decision voting, collaborative editing, patch management, and an embedded web bridge.

This package enables humans to:

• Communicate with autonomous agents using the same protocols
• Participate in distributed decision-making processes
• Browse and navigate UCXL-addressed contexts
• Collaborate on code and content in real-time
• Manage patches with temporal navigation
• Access all functionality via terminal or web browser

Architecture

Core Types

TerminalInterface

The main interface for human agent interaction.

type TerminalInterface struct {
    runtime              *runtime.SharedRuntime
    scanner              *bufio.Scanner
    quit                 chan bool
    collaborativeSession *CollaborativeSession
    hmmmMessageCount     int
    webServer            *http.Server
}

Responsibilities:

• Command processing and routing
• User input/output management
• Session lifecycle management
• Integration with SharedRuntime
• Web server hosting

CollaborativeSession

Represents an active collaborative editing session.

type CollaborativeSession struct {
    SessionID    string
    Owner        string
    Participants []string
    Status       string
    CreatedAt    time.Time
}

Use Cases:

• Multi-agent code collaboration
• Real-time content editing
• Session state tracking
• Participant management

Decision

Represents a network decision awaiting votes.

type Decision struct {
    ID          string                 `json:"id"`
    Title       string                 `json:"title"`
    Description string                 `json:"description"`
    Type        string                 `json:"type"`
    Proposer    string                 `json:"proposer"`
    ProposerType string                `json:"proposer_type"`
    CreatedAt   time.Time              `json:"created_at"`
    Deadline    time.Time              `json:"deadline"`
    Status      string                 `json:"status"`
    Votes       map[string]DecisionVote `json:"votes"`
    Metadata    map[string]interface{} `json:"metadata"`
    Version     int                    `json:"version"`
}

Decision Types:

• technical - Architecture, code, infrastructure decisions
• operational - Process, resource allocation
• policy - Network rules, governance
• emergency - Urgent security/stability issues (2-hour deadline)

DecisionVote

Represents a single vote on a decision.

type DecisionVote struct {
    VoterID    string    `json:"voter_id"`
    VoterType  string    `json:"voter_type"`
    Vote       string    `json:"vote"` // approve, reject, defer, abstain
    Reasoning  string    `json:"reasoning"`
    Timestamp  time.Time `json:"timestamp"`
    Confidence float64   `json:"confidence"` // 0.0-1.0 confidence in vote
}

Vote Options:

• approve - Support this decision
• reject - Oppose this decision
• defer - Need more information
• abstain - Acknowledge but not participate

Terminal Commands

Main Commands

help

Show available commands and help information.

hap> help

Output: Complete list of terminal commands with descriptions.

status

Display current network and agent status.

hap> status

Shows:

• Agent ID, role, and type (Human/HAP)
• P2P Node ID and connected peer count
• Active task count and limits
• DHT connection status
• BACKBEAT integration status
• Last updated timestamp

Example Output:

📊 HAP Status Report
----------------------------------------
Agent ID: human-alice
Agent Role: developer
Agent Type: Human (HAP)
Node ID: 12D3KooWAbc...
Connected Peers: 5
Active Tasks: 2/10
DHT: ✅ Connected
BACKBEAT: ✅ Connected
----------------------------------------
Last Updated: 14:32:15

peers

List connected P2P peers in the network.

hap> peers

Shows:

• Total peer count
• Connection status
• Guidance for peer discovery

announce

Re-announce human agent presence to the network.

hap> announce

Broadcasts:

• Agent ID and node ID
• Agent type: "human"
• Interface: "terminal"
• Capabilities: hmmm_reasoning, decision_making, context_browsing, collaborative_editing
• Current status: "online"

Published to: CapabilityBcast topic via PubSub

quit / exit

Exit the HAP terminal interface.

hap> quit

Actions:

• Graceful shutdown
• Network disconnection
• Session cleanup

clear / cls

Clear the terminal screen and redisplay welcome message.

hap> clear

HMMM Commands

Access: hap> hmmm

The HMMM (Human-Machine-Machine-Machine) command provides a sub-menu for collaborative reasoning messages.

HMMM Sub-Commands

new

Compose a new reasoning message.

hmmm> new

Interactive Wizard:

1. Topic (e.g., engineering, planning, architecture)
2. Issue ID (numeric identifier for the problem)
3. Subject/Title (concise summary)
4. Reasoning content (press Enter twice to finish)

Message Structure:

• Topic: CHORUS/hmmm/{topic}
• Type: reasoning_start
• Thread ID: Auto-generated from topic and issue ID
• Message ID: Unique identifier with timestamp

Example Flow:

📝 New HMMM Reasoning Message
----------------------------------------
Topic (e.g., engineering, planning, architecture): architecture
Issue ID (number for this specific problem): 42
Subject/Title: Service mesh migration strategy

Your reasoning (press Enter twice when done):
We should migrate to a service mesh architecture to improve
observability and resilience. Key considerations:
1. Gradual rollout across services
2. Training for ops team
3. Performance impact assessment

[Enter]
[Enter]

✅ HMMM reasoning message sent to network
   Topic: architecture
   Issue: #42
   Thread: thread-<hash>
   Message ID: hap-1234567890-123456

reply

Reply to an existing HMMM thread.

hmmm> reply

Interactive Wizard:

1. Thread ID to reply to
2. Issue ID
3. Reasoning/response content

Use Cases:

• Build on previous reasoning
• Add counterpoints
• Request clarification
• Provide additional context

query

Ask the network for reasoning help.

hmmm> query

Interactive Wizard:

1. Query topic
2. Issue ID (optional, auto-generated if not provided)
3. Question/problem statement
4. Additional context (optional)

Message Structure:

• Topic: CHORUS/hmmm/query/{topic}
• Type: reasoning_query
• Urgency: normal (default)

Example:

❓ HMMM Network Query
-------------------------
Query topic: technical
Issue ID: [Enter for new]
Your question/problem: How should we handle backpressure in the task queue?

Additional context:
Current queue size averages 1000 tasks
Agents process 10-50 tasks/minute
Peak load reaches 5000+ tasks

[Enter]
[Enter]

✅ HMMM query sent to network
   Waiting for agent responses on issue #7834
   Thread: thread-<hash>
   Message ID: hap-1234567890-123456

decide

Propose a decision requiring network consensus.

hmmm> decide

Interactive Wizard:

1. Decision topic
2. Decision title
3. Decision rationale
4. Voting options (comma-separated, defaults to approve/reject)

Creates:

• HMMM message with type decision_proposal
• Decision object in DHT storage
• Network announcement
• 24-hour voting deadline (default)

help

Show detailed HMMM system information.

hmmm> help

Displays:

• HMMM overview and purpose
• Message types explained
• Message structure details
• Best practices for effective reasoning

back

Return to main HAP menu.

UCXL Commands

Access: hap> ucxl <address>

The UCXL command provides context browsing and navigation.

Address Format:

ucxl://agent:role@project:task/path*temporal/

Components:

• agent - Agent ID or '*' for wildcard
• role - Agent role (dev, admin, user, etc.)
• project - Project identifier
• task - Task or issue identifier
• path - Optional resource path
• temporal - Optional time navigation

Example:

hap> ucxl ucxl://alice:dev@webapp:frontend/src/components/

Display:

🔗 UCXL Context Browser
--------------------------------------------------
📍 Address: ucxl://alice:dev@webapp:frontend/src/components/
🤖 Agent: alice
🎭 Role: dev
📁 Project: webapp
📝 Task: frontend
📄 Path: src/components/

📦 Content Found:
------------------------------
📄 Type: directory
👤 Creator: developer
📅 Created: 2025-09-30 10:15:23
📏 Size: 2048 bytes

📖 Content:
[directory listing or file content]

UCXL Sub-Commands

search

Search for related UCXL content.

ucxl> search

Interactive Wizard:

1. Search agent (current or custom)
2. Search role (current or custom)
3. Search project (current or custom)
4. Content type filter (optional)

Returns: List of matching UCXL addresses with metadata.

related

Find content related to the current address.

ucxl> related

Searches: Same project and task, different agents/roles

Use Cases:

• Find parallel work by other agents
• Discover related contexts
• Understand project structure

history

View address version history (stub).

ucxl> history

Status: Not yet fully implemented

Planned Features:

• Temporal version listing
• Change tracking
• Rollback capabilities

create

Create new content at this address.

ucxl> create

Interactive Wizard:

1. Content type selection
2. Content input
3. Metadata configuration
4. Storage and announcement

help

Show UCXL help information.

ucxl> help

Displays:

• Address format specification
• Component descriptions
• Temporal navigation syntax
• Examples

Temporal Navigation Syntax:

• *^/ - Latest version
• *~/ - Earliest version
• *@1234/ - Specific timestamp
• *~5/ - 5 versions back
• *^3/ - 3 versions forward

back

Return to main menu.

Decision Commands

Access: hap> decide <topic>

The decide command provides distributed decision participation.

Decision Sub-Commands

list

List all active decisions.

decision> list

Output:

🗳️ Active Decisions Requiring Your Vote
--------------------------------------------------
1. DEC-A1B2C3 | Emergency: Database quarantine
   Type: emergency | Proposer: agent-42 (autonomous)
   Deadline: 45 minutes | Votes: 4 (75% approval)

2. DEC-D4E5F6 | Technical: Upgrade to libp2p v0.30
   Type: technical | Proposer: alice (human)
   Deadline: 6 hours | Votes: 8 (62% approval)

3. DEC-G7H8I9 | Operational: Task timeout adjustment
   Type: operational | Proposer: agent-15 (autonomous)
   Deadline: 12 hours | Votes: 3 (33% approval)

view

View decision details.

decision> view DEC-A1B2C3

Output:

🔍 Decision Details: DEC-A1B2C3
----------------------------------------
📋 Title: Emergency: Database quarantine
🏷️ Type: Emergency
👤 Proposer: agent-42 (autonomous)
📅 Proposed: 2025-09-30 14:15:30
⏰ Deadline: 2025-09-30 16:00:00 (45 minutes remaining)

📖 Description:
   Database instance db-prod-03 is showing signs of
   corruption. Recommend immediate quarantine and failover
   to standby instance db-prod-04 to prevent data loss.

   Impact: 2-3 minute service interruption
   Risk if delayed: Potential data corruption spread

🗳️ Current Voting Status (4 total votes):
   ✅ Approve: 3 votes
   ❌ Reject:  0 votes
   ⏸️ Defer:   1 votes
   ⚠️ Abstain: 0 votes

💭 Recent Reasoning:
   agent-42 (approve): "Data integrity is critical priority"
   agent-15 (approve): "Standby instance is healthy and ready"
   alice (defer): "Need more info on corruption extent"

🎯 Status: 75.0% approval (Passing)

To vote on this decision, use: vote DEC-A1B2C3

vote

Cast a vote on a decision.

decision> vote DEC-A1B2C3

Interactive Wizard:

1. Vote selection (1-4: approve, reject, defer, abstain)
2. Reasoning/justification input (required)
3. Confirmation

Example:

🗳️ Cast Vote on DEC-A1B2C3
------------------------------
Vote Options:
  1. ✅ approve  - Support this decision
  2. ❌ reject   - Oppose this decision
  3. ⏸️ defer    - Need more information
  4. ⚠️ abstain  - Acknowledge but not participate

Your vote (1-4): 1
You selected: approve

Reasoning/Justification (required for transparency):
Explain why you are voting this way (press Enter twice when done):
Data integrity is our highest priority. The corruption is confirmed
and contained to one instance. Failover plan is sound.

[Enter]
[Enter]

📋 Vote Summary:
   Decision: DEC-A1B2C3
   Your Vote: approve
   Reasoning: Data integrity is our highest priority...

Submit this vote? (y/n): y

🔄 Submitting vote...
✅ Your approve vote on DEC-A1B2C3 has been recorded
📢 Vote announced via HMMM reasoning network
💌 Vote reasoning published to network for transparency
🔔 Other network members will be notified of your participation

Vote Storage:

• Saved to DHT with decision object
• Versioned (decision.Version++)
• Broadcast via HMMM on topic CHORUS/decisions/vote/{decisionID}

propose

Propose a new decision.

decision> propose

Interactive Wizard:

1. Decision type (1-4: technical, operational, policy, emergency)
2. Title (concise summary)
3. Detailed rationale
4. Custom voting options (optional, defaults to approve/reject/defer/abstain)
5. Voting deadline (hours, default: 24, emergency: 2)

Example:

📝 Propose New Network Decision
-----------------------------------
Decision Types:
  1. technical    - Architecture, code, infrastructure
  2. operational  - Process, resource allocation
  3. policy       - Network rules, governance
  4. emergency    - Urgent security/stability issue

Decision type (1-4): 1
Decision title (concise summary): Adopt gRPC for inter-agent communication

Detailed rationale (press Enter twice when done):
Current JSON-over-HTTP adds latency and parsing overhead.
gRPC with Protocol Buffers would provide:
- Type-safe communication
- Bidirectional streaming
- Better performance
- Native load balancing

[Enter]
[Enter]

Custom voting options (comma-separated, or press Enter for default): [Enter]
Voting deadline in hours (default: 24): [Enter]

📋 Decision Proposal Summary:
   Type: technical
   Title: Adopt gRPC for inter-agent communication
   Options: approve, reject, defer, abstain
   Deadline: 24h from now
   Rationale:
   Current JSON-over-HTTP adds latency...

Submit this decision proposal? (y/n): y

🔄 Creating decision proposal...
✅ Decision DEC-J1K2L3 proposed successfully
📢 Decision announced to all network members
⏰ Voting closes in 24h
🗳️ Network members can now cast their votes

Decision Creation:

• Generates unique ID: DEC-{randomID}
• Stores in DHT
• Announces via HMMM on topic CHORUS/decisions/proposal/{type}
• Sets appropriate priority metadata

status

Show decision system status.

decision> status

Mock Status (development):

📊 Decision System Status
------------------------------
🗳️  Active Decisions: 3
⏰ Urgent Decisions: 1 (emergency timeout)
👥 Network Members: 12 (8 active, 4 idle)
📊 Participation Rate: 67% (last 7 days)
✅ Consensus Success Rate: 89%
⚖️  Decision Types:
     Technical: 45%, Operational: 30%
     Policy: 20%, Emergency: 5%

🔔 Recent Activity:
   • DEC-003: Emergency quarantine decision (45m left)
   • DEC-002: Task timeout adjustment (6h 30m left)
   • DEC-001: libp2p upgrade (2h 15m left)
   • DEC-055: Completed - Storage encryption (✅ approved)

help

Show decision help information.

back

Return to main menu.

Patch Commands

Access: hap> patch

The patch command provides patch creation, review, and submission.

Patch Sub-Commands

create

Create a new patch.

Interactive Wizard:

1. Patch type (context, code, config, docs)
2. Base UCXL address (what you're modifying)
3. Patch title
4. Patch description
5. Content changes

Patch Types:

• context - UCXL context content changes
• code - Traditional diff-based code changes
• config - Configuration changes
• docs - Documentation updates

Example:

📝 Create New Patch
-------------------------
Patch Types:
  1. context      - UCXL context content changes
  2. code         - Traditional code diff
  3. config       - Configuration changes
  4. docs         - Documentation updates

Patch type (1-4): 2
Base UCXL address (what you're modifying): ucxl://alice:dev@webapp:bug-123/src/main.go
Patch title: Fix nil pointer dereference in request handler

📖 Fetching current content...
📄 Current Content:
[shows current file content]

[Content editing workflow continues...]

diff

Review changes with temporal comparison (stub).

submit

Submit patch for peer review via HMMM network.

Workflow:

1. Validate patch completeness
2. Generate patch ID
3. Store in DHT
4. Announce via HMMM on CHORUS/patches/submit topic
5. Notify network members

list

List active patches (stub).

review

Participate in patch review process (stub).

status

Show patch system status (stub).

help

Show patch help information.

Displays:

• Patch types explained
• Temporal navigation syntax
• Workflow stages
• Integration points (HMMM, UCXL, DHT, Decision System)

back

Return to main menu.

Collaborative Editing Commands

Access: hap> collab

The collab command provides collaborative session management (stub implementation).

Collab Sub-Commands

start

Start a new collaborative session.

join

Join an existing session.

list

List active collaborative sessions.

status

Show collaborative session status.

leave

Leave current session.

help

Show collaborative editing help.

back

Return to main menu.

Web Bridge Commands

Access: hap> web

Start the HAP web bridge for browser access.

Features:

• HTTP server on port 8090
• HTML interface for all HAP features
• REST API endpoints
• WebSocket support for real-time updates (stub)

Endpoints:

Static UI:

• / - Home dashboard
• /status - Agent status
• /decisions - Decision list
• /decisions/{id} - Decision details
• /collab - Collaborative editing (stub)
• /patches - Patch management (stub)
• /hmmm - HMMM messages (stub)

API:

• /api/status - JSON status
• /api/decisions - JSON decision list
• /api/decisions/vote - POST vote submission
• /api/decisions/propose - POST decision proposal (stub)
• /api/collab/sessions - JSON session list (stub)
• /api/hmmm/send - POST HMMM message (stub)

WebSocket:

• /ws - Real-time updates (stub)

Example:

hap> web

Output:

🌐 Starting HAP Web Bridge
------------------------------
🔌 Starting web server on port 8090
✅ Web interface available at: http://localhost:8090
📱 Browser HAP interface ready
🔗 API endpoints available at: /api/*
⚡ Real-time updates via WebSocket: /ws

💡 Press Enter to return to terminal...

Web Interface Features:

• Dashboard with quick access cards
• Decision voting interface with JavaScript
• Real-time status updates
• Responsive design
• Dark mode support (status page)

Integration Points

SharedRuntime Integration

The TerminalInterface depends on runtime.SharedRuntime for:

• Config: Agent ID, role, configuration
• Node: P2P node ID, peer connections
• TaskTracker: Active task monitoring
• DHTNode: Distributed storage access
• BackbeatIntegration: Timing system status
• PubSub: Message publishing
• EncryptedStorage: UCXL content retrieval
• Logger: Logging interface

HMMM Integration

HMMM messages are published using:

router := hmmm.NewRouter(t.runtime.PubSub)
router.Publish(ctx, message)

Message Structure:

hmmm.Message{
    Topic:     "CHORUS/hmmm/{category}",
    Type:      "reasoning_start|reasoning_reply|reasoning_query|decision_proposal",
    Payload:   map[string]interface{}{...},
    Version:   "1.0",
    IssueID:   issueID,
    ThreadID:  threadID,
    MsgID:     msgID,
    NodeID:    nodeID,
    HopCount:  0,
    Timestamp: time.Now().Unix(),
    Message:   "Human-readable summary",
}

UCXL Integration

UCXL addresses are parsed and resolved using:

parsed, err := ucxl.ParseUCXLAddress(address)
content, metadata, err := t.runtime.EncryptedStorage.RetrieveUCXLContent(address)

Decision Storage

Decisions are stored in DHT using the storage interface:

func (t *TerminalInterface) saveDecision(decision *Decision) error
func (t *TerminalInterface) getDecisionByID(decisionID string) (*Decision, error)
func (t *TerminalInterface) getActiveDecisions() ([]Decision, error)

PubSub Topics

Published Topics:

• CapabilityBcast - Agent presence announcements
• CHORUS/hmmm/{topic} - HMMM reasoning messages
• CHORUS/hmmm/query/{topic} - HMMM queries
• CHORUS/hmmm/decision/{topic} - Decision proposals
• CHORUS/decisions/vote/{decisionID} - Vote announcements
• CHORUS/decisions/proposal/{type} - Decision proposals
• CHORUS/patches/submit - Patch submissions
• CHORUS/collab/{event} - Collaborative events

User Experience Features

Interactive Wizards

All complex operations use multi-step interactive wizards:

• Clear prompts with examples
• Input validation
• Confirmation steps
• Progress feedback
• Error handling with guidance

Visual Feedback

Rich terminal output with:

• Emoji indicators (✅ ❌ 🔄 📊 🗳️ etc.)
• Color support (via ANSI codes in web interface)
• Progress indicators
• Status summaries
• Formatted tables and lists

Help System

Comprehensive help at every level:

• Main help menu
• Sub-command help
• Inline examples
• Best practices
• Troubleshooting guidance

Error Handling

User-friendly error messages:

• Clear problem description
• Suggested solutions
• Alternative actions
• Non-blocking errors with warnings

Web Interface

Home Dashboard

Provides quick access to all HAP features with cards:

• Decision Management
• Collaborative Editing
• Patch Management
• HMMM Network
• Network Status
• Live Updates

Decision Voting Interface

Full-featured web UI for decisions:

• Decision list with vote counts
• Inline voting with prompts
• JavaScript-based vote submission
• Real-time status updates
• Color-coded vote indicators

API Design

RESTful JSON API:

• Standard HTTP methods
• JSON request/response
• Error handling with HTTP status codes
• Authentication ready (not yet implemented)

Real-time Updates

WebSocket endpoint for:

• Decision updates
• Vote notifications
• Collaborative session events
• Network status changes

Status: Stub implementation, connection established but no event streaming yet.

Development Status

Fully Implemented

• ✅ Terminal command processing
• ✅ HMMM message composition (all types)
• ✅ UCXL address parsing and browsing
• ✅ Decision voting and proposal
• ✅ Status reporting
• ✅ Peer listing
• ✅ Web bridge with basic UI
• ✅ Decision voting API
• ✅ Agent presence announcements

Partially Implemented

• ⚠️ UCXL content retrieval (depends on storage backend)
• ⚠️ Decision storage (DHT integration)
• ⚠️ Patch creation (wizard complete, submission pending)
• ⚠️ Web decision proposal API
• ⚠️ WebSocket real-time updates

Stub / TODO

• 🔜 Collaborative editing sessions
• 🔜 Patch review workflow
• 🔜 UCXL history tracking
• 🔜 Web HMMM message interface
• 🔜 Web collaborative editing interface
• 🔜 Web patch management interface
• 🔜 Authentication and authorization
• 🔜 Session persistence

Best Practices

For Developers

Adding New Commands:

1. Add case to commandLoop() switch statement
2. Implement handler function handle{Command}Command()
3. Add help text to printHelp()
4. Document in this file

Adding Web Endpoints:

1. Add route in startWebBridge()
2. Implement handler function web{Feature}() or api{Feature}()
3. Follow existing HTML/JSON patterns
4. Add API documentation

Error Handling:

if err != nil {
    fmt.Printf("❌ Operation failed: %v\n", err)
    fmt.Println("💡 Try: [suggestion]")
    return
}

User Feedback:

fmt.Println("🔄 Processing...")
// operation
fmt.Println("✅ Operation successful")

For Users

Effective HMMM Usage:

• Be specific and clear in reasoning
• Include relevant context and background
• Ask follow-up questions to guide discussion
• Build on previous messages in threads
• Avoid vague or overly broad statements

Decision Voting:

• Always provide detailed reasoning
• Consider impact on all network members
• Vote promptly on urgent decisions
• Use defer when more information is needed
• Abstain when lacking relevant expertise

UCXL Navigation:

• Use wildcards (*) for broad searches
• Use temporal navigation to track changes
• Include full context in addresses
• Follow project naming conventions

Security Considerations

Current Implementation

• No authentication required (trusted network assumption)
• No authorization checks
• No input sanitization (trusted users)
• No rate limiting
• No session security

Future Enhancements

• Agent identity verification
• Role-based access control
• Input validation and sanitization
• Rate limiting on votes and proposals
• Encrypted web sessions
• Audit logging

Testing

Manual Testing

Start HAP and exercise all commands:

make build-hap
./build/chorus-hap

Test each command category:

• status, peers, announce
• hmmm (new, reply, query, decide)
• ucxl (search, related, history, create)
• decide (list, view, vote, propose)
• patch (create, submit)
• collab (start, join, list)
• web (access all endpoints)

Integration Testing

Test with multiple agents:

1. Start autonomous agents
2. Start HAP
3. Verify presence announcement
4. Send HMMM messages
5. Propose and vote on decisions
6. Monitor network activity

Web Interface Testing

Test browser functionality:

1. Start web bridge: hap> web
2. Open http://localhost:8090
3. Test decision voting
4. Verify WebSocket connection
5. Test API endpoints with curl

Performance Considerations

Resource Usage

• Memory: Minimal, single-threaded scanner
• CPU: Low, blocking I/O on user input
• Network: Burst traffic on message sends
• Storage: DHT operations on demand

Scalability

• Supports hundreds of concurrent agents
• DHT lookups may slow with large decision sets
• Web server limited by single Go routine per connection
• WebSocket scaling depends on implementation

Troubleshooting

Common Issues

"Failed to announce human agent presence"

• Check PubSub connection
• Verify network connectivity
• Ensure runtime is initialized

"Storage system not available"

• DHT not configured
• EncryptedStorage not initialized
• Network partition

"Decision not found"

• Decision not yet propagated
• DHT lookup failure
• Invalid decision ID

"Web server error"

• Port 8090 already in use
• Permission denied (use port >1024)
• Network interface not available

Debug Mode

Enable verbose logging in SharedRuntime:

runtime.Logger.SetLevel(slog.LevelDebug)

Monitor network traffic:

# Watch HMMM messages
# Watch decision announcements
# Check peer connections

Future Enhancements

Phase 2 (Planned)

• Full collaborative editing implementation
• Complete patch review workflow
• UCXL history with temporal navigation
• Enhanced web interface with real-time updates
• Mobile-responsive design improvements

Phase 3 (Future)

• Rich text editor in web interface
• Visual diff tools
• Decision analytics dashboard
• Agent reputation system
• Notification system (email, webhooks)
• Plugin architecture for custom commands

Related Documentation

• /docs/comprehensive/internal/runtime.md - SharedRuntime integration
• /docs/comprehensive/pkg/hmmm.md - HMMM protocol details
• /docs/comprehensive/pkg/ucxl.md - UCXL addressing system
• /docs/comprehensive/pkg/storage.md - DHT storage backend
• /docs/comprehensive/pkg/p2p.md - P2P networking layer

Summary

The hapui package is the primary interface for human participation in the CHORUS network. It provides:

• 3,985 lines of comprehensive terminal interface
• 9 main command categories with rich sub-menus
• HMMM integration for collaborative reasoning
• UCXL browsing for context navigation
• Decision voting with transparency and reasoning
• Patch management with temporal navigation
• Web bridge for browser-based access
• RESTful API for external integrations

The interface treats humans as first-class network members, providing the same capabilities as autonomous agents while adding human-friendly wizards, help systems, and visual feedback.

Current Status: Production-ready for terminal interface, web interface in active development with core features functional and advanced features planned for upcoming phases.