CHORUS/docs/comprehensive/commands/chorus-hap.md

chorus-hap - Human Agent Portal Binary

Binary: chorus-hap Source: cmd/hap/main.go Status: 🔶 Beta (Terminal interface: ✅ Production, Web interface: ⏳ Stubbed) Purpose: Human-friendly interface for participating in P2P agent networks

---

Overview

chorus-hap (Human Agent Portal) is the executable that enables human users to participate in CHORUS P2P agent networks as first-class peers. Unlike autonomous agents, HAP provides interactive interfaces (terminal and web) for humans to collaborate with agents using the same protocols.

Key Features

• ✅ Terminal Interface: Full-featured command-line interaction (Production)
• ⏳ Web Interface: Browser-based UI (Stubbed, falls back to terminal)
• ✅ HMMM Composition: Human-friendly reasoning message helpers
• ✅ UCXL Browsing: Navigate and explore context addresses
• ✅ Decision Participation: Vote on network decisions
• ✅ Collaborative Sessions: Multi-party editing coordination
• ✅ Patch Creation: Submit changes to codebase
• ✅ P2P Protocols: Same networking as autonomous agents
• ✅ Peer Management: View and interact with network peers

Human vs Agent Mode

Feature	chorus-agent	chorus-hap
Task Execution	Automatic	Manual approval required
UI Mode	Headless	Terminal or Web
HMMM Messages	AI-generated	Human-composed
Decision Making	Autonomous	Interactive prompts
Network Role	Autonomous peer	Human peer
Use Case	Batch processing	Oversight & collaboration

---

Usage

Basic Invocation

# With required environment variables
CHORUS_LICENSE_ID=dev-123 \
CHORUS_AGENT_ID=human-alice \
CHORUS_HAP_MODE=terminal \
./chorus-hap

Help Output

$ ./chorus-hap --help
CHORUS-hap 0.5.0-dev

Usage:
  chorus-hap [--help] [--version]

CHORUS Human Agent Portal - Human Interface to P2P Agent Networks

This binary provides a human-friendly interface to participate in P2P agent
coordination networks. Humans can collaborate with autonomous agents using
the same protocols and appear as peers in the distributed network.

Environment (common):
  CHORUS_LICENSE_ID              (required)
  CHORUS_AGENT_ID                (optional; auto-generated if empty)
  CHORUS_P2P_PORT                (default 9000)
  CHORUS_API_PORT                (default 8080)
  CHORUS_HEALTH_PORT             (default 8081)
  CHORUS_DHT_ENABLED             (default true)
  CHORUS_BOOTSTRAP_PEERS         (comma-separated multiaddrs)
  OLLAMA_ENDPOINT                (default http://localhost:11434)

HAP-Specific Environment:
  CHORUS_HAP_MODE                (terminal|web, default terminal)
  CHORUS_HAP_WEB_PORT            (default 8082)

Example:
  CHORUS_LICENSE_ID=dev-123 \
  CHORUS_AGENT_ID=human-alice \
  CHORUS_HAP_MODE=terminal \
  CHORUS_P2P_PORT=9001 ./chorus-hap

HAP Features:
  - Human-friendly message composition
  - HMMM reasoning template helpers
  - UCXL context browsing
  - Collaborative decision participation
  - Terminal and web interface modes
  - Same P2P protocols as autonomous agents

Version Information

$ ./chorus-hap --version
CHORUS-hap 0.5.0-dev

---

Source Code Analysis

File: cmd/hap/main.go

Lines: 126 Package: main Imports:

• chorus/internal/hapui - Terminal and web interface implementations
• chorus/internal/runtime - Shared P2P runtime infrastructure

main() Function Flow

func main() {
    // 1. CLI Argument Handling (lines 14-58)
    //    - Check for --help, -h, help
    //    - Check for --version, -v
    //    - Print usage and exit early if found

    // 2. Initialize Shared Runtime (lines 60-66)
    sharedRuntime, err := runtime.Initialize("hap")
    if err != nil {
        // Fatal error, exit 1
    }
    defer sharedRuntime.Cleanup()

    // 3. Start HAP Mode (lines 68-72)
    if err := startHAPMode(sharedRuntime); err != nil {
        // Fatal error, exit 1
    }
}

Execution Phases

Phase 1: Early CLI Handling (lines 14-58)

Purpose: Handle help/version requests without loading configuration

Code:

for _, a := range os.Args[1:] {
    switch a {
    case "--help", "-h", "help":
        // Print HAP-specific help with terminal/web mode info
        fmt.Printf("%s-hap %s\n\n", runtime.AppName, runtime.AppVersion)
        // ... detailed usage information ...
        return
    case "--version", "-v":
        fmt.Printf("%s-hap %s\n", runtime.AppName, runtime.AppVersion)
        return
    }
}

Help Output Details (lines 17-52):

• Describes HAP purpose and human participation model
• Lists common environment variables (same as chorus-agent)
• Lists HAP-specific variables (mode, web port)
• Shows example invocation with human-focused agent ID
• Highlights features: HMMM helpers, UCXL browsing, decision participation

Why Important: Users can explore HAP capabilities without needing valid license.

Phase 2: Runtime Initialization (line 61)

Function Call: runtime.Initialize("hap")

What Happens:

1. Load configuration from environment variables
2. Validate CHORUS license with KACHING server
3. Initialize AI provider (Ollama or ResetData)
4. Create P2P libp2p node (same as agent)
5. Start mDNS discovery
6. Initialize PubSub messaging
7. Setup DHT (if enabled)
8. Start election manager
9. Create task coordinator
10. Start HTTP API server
11. Start UCXI server (if enabled)
12. Initialize health checks
13. Setup SHHH sentinel

Returns: *runtime.SharedRuntime containing all initialized components

Key Difference from Agent: Mode parameter is "hap" instead of "agent", which configures runtime for human interaction patterns.

See: internal/runtime Documentation for complete initialization details

Phase 3: HAP Mode Selection (lines 75-95)

Function: startHAPMode(runtime *runtime.SharedRuntime) error

What Happens:

1. Reads CHORUS_HAP_MODE environment variable (default: "terminal")
2. Routes to appropriate interface:
   • "terminal": Starts interactive command-line interface
   • "web": Attempts web interface (falls back to terminal if stubbed)
   • Invalid: Returns error

Code:

func startHAPMode(runtime *runtime.SharedRuntime) error {
    runtime.Logger.Info("👤 Starting CHORUS Human Agent Portal (HAP)")
    runtime.Logger.Info("🔗 Connected to P2P network as human agent")
    runtime.Logger.Info("📝 Ready for collaborative reasoning and decision making")

    hapMode := os.Getenv("CHORUS_HAP_MODE")
    if hapMode == "" {
        hapMode = "terminal"
    }

    switch hapMode {
    case "terminal":
        return startTerminalInterface(runtime)
    case "web":
        return startWebInterface(runtime)
    default:
        return fmt.Errorf("unknown HAP mode: %s (valid: terminal, web)", hapMode)
    }
}

Phase 4: Terminal Interface (lines 97-108)

Function: startTerminalInterface(runtime *runtime.SharedRuntime) error

Implementation:

func startTerminalInterface(runtime *runtime.SharedRuntime) error {
    runtime.Logger.Info("💻 Starting terminal interface for human interaction")

    // Create and start the HAP terminal interface
    terminal := hapui.NewTerminalInterface(runtime)

    runtime.Logger.Info("🎯 Human agent terminal interface ready")

    // Start the interactive terminal (blocks until quit)
    return terminal.Start()
}

Terminal Capabilities:

• Interactive REPL with hap> prompt
• Command parsing and execution
• HMMM message composition with templates
• UCXL context browsing
• Network status monitoring
• Peer management
• Decision voting
• Collaborative session management
• Patch submission

See: Terminal Interface Details section for full command reference

Phase 5: Web Interface (lines 110-126)

Function: startWebInterface(runtime *runtime.SharedRuntime) error

Current Status: ⏳ STUBBED - Phase 3 Implementation

Code:

func startWebInterface(runtime *runtime.SharedRuntime) error {
    runtime.Logger.Info("🌐 Starting web interface for human interaction")

    // TODO Phase 3: Implement web interface
    // - HTTP server with WebSocket for real-time updates
    // - Web forms for HMMM message composition
    // - Context browser UI
    // - Decision voting interface

    runtime.Logger.Info("⚠️ Web interface not yet implemented")
    runtime.Logger.Info("🔄 HAP running in stub mode - P2P connectivity established")
    runtime.Logger.Info("📍 Next: Implement Phase 3 web interface")

    // For now, fall back to terminal mode
    return startTerminalInterface(runtime)
}

Planned Features (Phase 3):

• HTTP server with WebSocket for real-time updates
• Web forms for HMMM message composition
• Visual context browser UI
• Interactive decision voting interface
• Multi-user collaborative session views
• Real-time network status dashboard

Current Behavior: Falls back to terminal interface with warning logs

---

Terminal Interface

Implementation Details

Source: internal/hapui/terminal.go Lines: ~3985 Status: ✅ Production

Welcome Screen

When terminal interface starts:

================================================================================
🎭 CHORUS Human Agent Portal (HAP) - Terminal Interface
================================================================================
Agent ID: human-alice
P2P Node: 12D3KooW...short
Connected to: 3 peers

You are now connected to the CHORUS P2P agent network as a human participant.
You can collaborate with autonomous agents using the same protocols.
================================================================================

Available Commands

Core Commands

Command	Description	Status
help	Show command reference	✅
status	Show network and agent status	✅
peers	List connected P2P peers	✅
quit	Exit HAP terminal	✅
announce	Re-announce human agent presence	✅

Collaborative Commands

Command	Description	Status
hmmm	Compose and send HMMM reasoning message	✅
ucxl <address>	Browse UCXL context address	✅
patch	Create and submit patches	✅
collab	Collaborative editing sessions	✅
decide <topic>	Participate in distributed decision	✅

Advanced Commands

Command	Description	Status
web	Start web bridge for browser access	🔶 Beta

Command Details

status - Network Status

Usage: status

Output:

Network Status:
  Agent ID: human-alice
  P2P Node ID: 12D3KooWABC...
  Listening Addresses:
    - /ip4/192.168.1.100/tcp/9001
    - /ip6/::1/tcp/9001
  Connected Peers: 5
  DHT Status: Active
  Election: Follower (current leader: chorus-agent-3)
  Active Tasks: 0/5

Implementation: Queries runtime.SharedRuntime for live status

peers - Peer List

Usage: peers

Output:

Connected Peers (5):
  1. chorus-agent-1 (12D3KooWXYZ...)
     Type: autonomous
     Address: /ip4/192.168.1.101/tcp/9000
     Latency: 15ms

  2. chorus-agent-2 (12D3KooWABC...)
     Type: autonomous
     Address: /ip4/192.168.1.102/tcp/9000
     Latency: 22ms

  3. human-bob (12D3KooWDEF...)
     Type: human
     Address: /ip4/192.168.1.103/tcp/9001
     Latency: 8ms

Implementation: Enumerates runtime.Node.ConnectedPeers() with metadata

hmmm - HMMM Message Composition

Usage: hmmm

Interactive Flow:

hap> hmmm

📝 Composing HMMM (Hierarchical Meta-level Model of Meaning) Message
====================================================================

Select HMMM message type:
  1. Observation - Share an observation about the system
  2. Question - Ask peers for input
  3. Proposal - Propose a solution or approach
  4. Objection - Raise concerns about a proposal
  5. Synthesis - Summarize discussion or findings

Enter selection [1-5]: 3

Enter proposal title: Implement rate limiting for API endpoints

Enter proposal description (end with empty line):
> We should add rate limiting to prevent abuse of public API endpoints.
> Suggested approach: token bucket algorithm with 100 req/min per IP.
> This would protect against DoS attacks while allowing normal usage.
>

Enter affected components (comma-separated, optional): api,security

Confidence level (0.0-1.0) [0.8]: 0.9

Preview:
--------
Type: Proposal
Title: Implement rate limiting for API endpoints
Description: We should add rate limiting to prevent abuse of public API...
Components: api, security
Confidence: 0.9
Author: human-alice

Send this HMMM message? [y/N]: y

✅ HMMM message sent to network (ID: hmmm-20250930-abc123)
📡 Published to topic: hmmm/meta-discussion/v1

Implementation:

• Guided wizard for HMMM message construction
• Validation of message fields
• Publishes to hmmm/meta-discussion/v1 PubSub topic
• Records message in local history

ucxl <address> - UCXL Context Browser

Usage: ucxl <ucxl-address>

Example:

hap> ucxl ucxl://chorus/decision/20250930/task-123

📍 UCXL Context Browser
====================================================================
Address: ucxl://chorus/decision/20250930/task-123

Metadata:
  Type: decision
  Created: 2025-09-30 14:32:15 UTC
  Creator: chorus-agent-1
  Status: completed

Content:
{
  "task_id": "task-123",
  "description": "Implement API rate limiting",
  "outcome": "approved",
  "votes": {
    "approve": 3,
    "reject": 0,
    "defer": 1
  },
  "participants": [
    "chorus-agent-1",
    "chorus-agent-2",
    "human-alice"
  ]
}

Related Contexts:
  - ucxl://chorus/task/20250930/task-123 (parent task)
  - ucxl://chorus/hmmm/20250930/proposal-xyz (related discussion)

[Press 'p' for parent, 'r' for related, 'q' to quit browser]

Implementation:

• Resolves UCXL address via DHT
• Parses and displays context data
• Supports navigation to related contexts
• Interactive browser for exploration

decide <topic> - Decision Participation

Usage: decide <decision-topic>

Interactive Flow:

hap> decide api-rate-limiting

🗳️ Decision Participation: api-rate-limiting
====================================================================

Decision: Should we implement rate limiting on API endpoints?
Proposed by: chorus-agent-1 (autonomous)
Status: voting
Deadline: 2025-09-30 18:00:00 UTC (2h 15m remaining)

Current Votes:
  ✅ Approve: 2 (chorus-agent-1, chorus-agent-2)
  ❌ Reject: 0
  ⏸️ Defer: 1 (chorus-agent-3)
  ⭕ Abstain: 0

Your vote [approve/reject/defer/abstain]: approve

Enter reasoning (optional, end with empty line):
> Rate limiting is essential for API security. The proposed token bucket
> approach is standard and well-tested. I support implementation.
>

Confidence level (0.0-1.0) [0.8]: 0.9

Confirm vote:
  Decision: api-rate-limiting
  Vote: approve
  Reasoning: Rate limiting is essential...
  Confidence: 0.9

Submit this vote? [y/N]: y

✅ Vote submitted successfully
📡 Published to topic: chorus/decisions
📍 UCXL recorded: ucxl://chorus/vote/20250930/human-alice-rate-limiting

Implementation:

• Fetches decision from DHT
• Displays current voting status
• Collects human vote with reasoning
• Publishes vote to network
• Records vote in UCXL

patch - Patch Creation

Usage: patch

Interactive Flow:

hap> patch

🔧 Patch Creation & Submission
====================================================================

Enter patch title: Fix typo in API documentation

Enter files affected (one per line, empty to finish):
> docs/api/endpoints.md
>

Enter patch description:
> Fixed spelling error: "recieve" -> "receive" in authentication section
>

Enter patch diff or file path:
> --- a/docs/api/endpoints.md
> +++ b/docs/api/endpoints.md
> @@ -15,7 +15,7 @@
>  Authentication
>  --------------
>
> -All API requests must include a valid token to recieve a response.
> +All API requests must include a valid token to receive a response.
>
>  Token format: Bearer <token>
>

Submit patch to network? [y/N]: y

✅ Patch submitted (ID: patch-20250930-abc123)
📡 Published to topic: chorus/patches
📍 UCXL recorded: ucxl://chorus/patch/20250930/human-alice-typo-fix

Awaiting peer review...

Implementation:

• Guided patch creation wizard
• Supports diff input or file paths
• Publishes patch to network
• Creates UCXL record for tracking
• Notifies peers for review

collab - Collaborative Sessions

Usage: collab [start|join|status|leave]

Subcommands:

collab start - Start new session:

hap> collab start

Starting collaborative editing session...
Session ID: collab-20250930-xyz789
Owner: human-alice
Status: active

Share this command with collaborators:
  collab join collab-20250930-xyz789

Waiting for participants...

collab join <session-id> - Join existing session:

hap> collab join collab-20250930-xyz789

Joining collaborative session...
Session ID: collab-20250930-xyz789
Owner: human-bob
Participants: human-bob, chorus-agent-5

✅ Joined session successfully
Real-time editing enabled

collab status - Show session info:

hap> collab status

Active Collaborative Session:
  Session ID: collab-20250930-xyz789
  Owner: human-bob
  Participants:
    - human-bob (owner)
    - human-alice (you)
    - chorus-agent-5
  Status: active
  Created: 15m ago

collab leave - Exit session:

hap> collab leave

Left collaborative session collab-20250930-xyz789

Implementation:

• Creates distributed editing session
• Uses PubSub for real-time updates
• Supports human and agent participants
• Tracks session state in DHT

web - Web Bridge

Usage: web [start|stop|status]

Status: 🔶 Beta

Subcommands:

web start - Start web server:

hap> web start

Starting web bridge server...
Listening on: http://localhost:8082
WebSocket endpoint: ws://localhost:8082/ws

Open in browser: http://localhost:8082

Web bridge ready for browser connections

web stop - Stop web server:

hap> web stop

Stopping web bridge server...
Web bridge stopped

web status - Show web server status:

hap> web status

Web Bridge Status:
  Running: Yes
  Listen Address: http://localhost:8082
  Active Connections: 2
  Uptime: 1h 23m

Implementation:

• Starts HTTP server with WebSocket
• Bridges terminal commands to web UI
• Allows browser-based interaction
• Maintains terminal session alongside web

Command Loop Structure

Implementation (internal/hapui/terminal.go lines 131-180):

func (t *TerminalInterface) commandLoop() {
    for {
        fmt.Print("hap> ")

        if !t.scanner.Scan() {
            break  // EOF or error
        }

        input := strings.TrimSpace(t.scanner.Text())
        if input == "" {
            continue
        }

        parts := strings.Fields(input)
        command := strings.ToLower(parts[0])

        switch command {
        case "help", "h":
            t.printHelp()
        case "status", "s":
            t.showStatus()
        case "peers", "p":
            t.listPeers()
        case "hmmm":
            t.composeHMMMMessage()
        case "ucxl":
            if len(parts) < 2 {
                fmt.Println("Usage: ucxl <address>")
                continue
            }
            t.browseUCXL(parts[1])
        case "patch":
            t.createPatch()
        case "collab":
            t.handleCollabCommand(parts[1:])
        case "decide":
            if len(parts) < 2 {
                fmt.Println("Usage: decide <topic>")
                continue
            }
            t.participateInDecision(parts[1])
        case "web":
            t.handleWebCommand(parts[1:])
        case "announce":
            t.announceHumanAgent()
        case "quit", "q", "exit":
            t.Stop()
            return
        default:
            fmt.Printf("Unknown command: %s (type 'help' for commands)\n", command)
        }
    }
}

---

Configuration

Required Environment Variables

Variable	Description	Example
CHORUS_LICENSE_ID	License key from KACHING	dev-123

Optional Environment Variables

Variable	Default	Description
CHORUS_AGENT_ID	Auto-generated	Human agent identifier (e.g., human-alice)
CHORUS_P2P_PORT	9000	libp2p listening port
CHORUS_API_PORT	8080	HTTP API port
CHORUS_HEALTH_PORT	8081	Health check port
CHORUS_DHT_ENABLED	true	Enable distributed hash table
CHORUS_BOOTSTRAP_PEERS	""	Comma-separated multiaddrs
OLLAMA_ENDPOINT	http://localhost:11434	Ollama API endpoint

HAP-Specific Variables

Variable	Default	Description
CHORUS_HAP_MODE	terminal	Interface mode: terminal or web
CHORUS_HAP_WEB_PORT	8082	Web interface HTTP port (when mode=web)

Naming Conventions

Human Agent IDs: Use human-recognizable names to distinguish from autonomous agents:

# Good examples
CHORUS_AGENT_ID=human-alice
CHORUS_AGENT_ID=human-bob-reviewer
CHORUS_AGENT_ID=human-ops-team

# Less clear (looks like autonomous agent)
CHORUS_AGENT_ID=agent-123
CHORUS_AGENT_ID=chorus-worker-1

---

Runtime Behavior

Startup Sequence

1. Parse CLI arguments
   ├─→ --help → print help, exit 0
   ├─→ --version → print version, exit 0
   └─→ (none) → continue

2. Initialize shared runtime
   ├─→ Load environment configuration
   ├─→ Validate license with KACHING
   │   └─→ FAIL → print error, exit 1
   ├─→ Configure AI provider
   ├─→ Create P2P node
   ├─→ Start mDNS discovery
   ├─→ Initialize PubSub
   ├─→ Setup DHT (optional)
   ├─→ Start election manager
   ├─→ Create task coordinator
   ├─→ Start HTTP API server
   └─→ Initialize health checks

3. Determine HAP mode
   ├─→ Read CHORUS_HAP_MODE
   ├─→ Default to "terminal"
   └─→ Validate mode (terminal or web)

4. Start appropriate interface
   ├─→ TERMINAL:
   │   ├─→ Create TerminalInterface
   │   ├─→ Print welcome message
   │   ├─→ Show help
   │   ├─→ Announce human agent to network
   │   └─→ Start command loop (blocking)
   │
   └─→ WEB (currently stubbed):
       ├─→ Log web mode request
       ├─→ Log stub status warning
       ├─→ Fall back to terminal mode
       └─→ TODO: Start HTTP server with WebSocket

5. Run until quit command or signal
   ├─→ Terminal: wait for 'quit' command
   └─→ Web: wait for SIGINT/SIGTERM

6. Cleanup on shutdown
   ├─→ Close active collaborative sessions
   ├─→ Unsubscribe from PubSub topics
   ├─→ Close P2P connections
   ├─→ Stop HTTP servers
   └─→ Exit gracefully

Signal Handling

Signal	Behavior
SIGINT (Ctrl+C)	Graceful shutdown, close sessions
SIGTERM	Graceful shutdown
SIGHUP	Reload configuration (if applicable)

Human Participation Model

Differences from Autonomous Agents:

Aspect	chorus-agent	chorus-hap
Task Assignment	Accepts automatically	Prompts human for approval
HMMM Messages	AI-generated reasoning	Human-composed reasoning
Decision Voting	Autonomous voting	Interactive voting prompts
Code Execution	Automatic in sandbox	Manual approval required
Availability	24/7 operation	Human working hours
Network Role	Autonomous peer	Human oversight peer

Announcement to Network:

On startup, HAP announces human presence:

{
  "type": "peer_announcement",
  "agent_id": "human-alice",
  "agent_type": "human",
  "capabilities": [
    "hmmm_composition",
    "decision_participation",
    "code_review",
    "collaborative_editing"
  ],
  "availability": "interactive",
  "timestamp": "2025-09-30T14:30:00Z"
}

Published to: chorus/coordination/v1 topic

Purpose:

• Helps autonomous agents identify human peers
• Adjusts interaction patterns (e.g., wait for human responses)
• Enables mixed human-agent collaboration

---

P2P Networking

Peer Discovery

Same as chorus-agent:

mDNS (Local):

• Discovers peers on local network
• Service name: chorus-peer-discovery
• Automatic peer connection

DHT (Global):

• Discovers peers across networks
• Requires bootstrap peers
• Content-addressed routing

Topics Subscribed

Topic	Purpose
chorus/coordination/v1	Task coordination messages
hmmm/meta-discussion/v1	Collaborative reasoning (human participates here)
chorus/election/v1	Leader election heartbeats
chorus/decisions	Decision announcements (voting)
chorus/patches	Patch submission and review
chorus/collaborative	Collaborative editing sessions
chorus/health	Health status broadcasts

Human-Specific Behaviors

Slower Response Times: HAP doesn't auto-respond to messages. Autonomous agents should:

• Wait longer for human responses
• Include timeout considerations
• Provide clear prompts/context

Interactive Approval: Tasks requiring human execution trigger interactive prompts:

hap>
🔔 Task Assignment Request
====================================================================
Task ID: task-123
From: chorus-agent-2
Description: Review security patch for API endpoints
Priority: high
Estimated Time: 30 minutes

Accept this task? [y/N]: _

---

Health Checks

HTTP Endpoints

Liveness Probe:

curl http://localhost:8081/healthz
# Returns: 200 OK if HAP is alive

Readiness Probe:

curl http://localhost:8081/ready
# Returns: 200 OK if HAP is ready (human available)
# Returns: 503 if human is away/unavailable

Health Details:

curl http://localhost:8081/health
# Returns JSON with:
# - P2P connectivity status
# - Interface mode (terminal/web)
# - Active sessions
# - Human availability status

Availability Indicators

HAP reports human availability status:

Status	Meaning
available	Human actively using terminal
idle	Terminal open but no recent activity
away	Extended idle period
offline	HAP closed

Implementation:

• Tracks last command timestamp
• Idle timeout: 15 minutes → idle
• Away timeout: 1 hour → away

---

Integration Points

HMMM Protocol

Human Participation in Meta-Discussion:

HAP enables humans to compose HMMM messages:

1. Observation: Share insights about system behavior
2. Question: Ask network for input
3. Proposal: Suggest solutions
4. Objection: Raise concerns
5. Synthesis: Summarize findings

Message Format:

{
  "type": "hmmm/proposal",
  "id": "hmmm-20250930-abc123",
  "author": "human-alice",
  "author_type": "human",
  "title": "Implement rate limiting",
  "description": "...",
  "confidence": 0.9,
  "timestamp": "2025-09-30T14:30:00Z"
}

See: HMMM Protocol

UCXL Context Addressing

Browser Support:

HAP provides UCXL browser for exploring contexts:

• Navigate context tree
• View related contexts
• Follow links between decisions/tasks
• Export context data

Example Navigation:

ucxl://chorus/task/20250930/task-123
  └─→ ucxl://chorus/decision/20250930/decision-abc
      └─→ ucxl://chorus/hmmm/20250930/proposal-xyz
          └─→ ucxl://chorus/patch/20250930/patch-def

See: UCXL Specification

Decision Voting

Democratic Participation:

Humans vote on network decisions:

• Approve/Reject/Defer/Abstain
• Provide reasoning
• Express confidence level
• Track voting history

Vote Weight: Configurable per deployment:

• Equal weight (1 human = 1 agent)
• Expert weight (humans have higher weight)
• Role-based weight

See: Decision System

---

Example Deployments

Local Development

#!/bin/bash
# Run HAP for local development

export CHORUS_LICENSE_ID=dev-local-123
export CHORUS_AGENT_ID=human-developer
export CHORUS_P2P_PORT=9001
export CHORUS_API_PORT=8080
export CHORUS_HEALTH_PORT=8081
export CHORUS_HAP_MODE=terminal
export OLLAMA_ENDPOINT=http://localhost:11434

./chorus-hap

Docker Container

FROM debian:bookworm-slim

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Copy binary
COPY chorus-hap /usr/local/bin/chorus-hap

# Expose ports
EXPOSE 9000 8080 8081 8082

# HAP typically runs interactively, but can be daemonized
ENTRYPOINT ["/usr/local/bin/chorus-hap"]

docker run -it \
  --name chorus-hap-alice \
  -e CHORUS_LICENSE_ID=dev-123 \
  -e CHORUS_AGENT_ID=human-alice \
  -e CHORUS_HAP_MODE=terminal \
  -p 9001:9000 \
  -p 8080:8080 \
  -p 8081:8081 \
  chorus-hap:latest

Note: Interactive terminal requires -it flags for stdin/stdout

Web Mode Deployment (Future)

# When web interface is implemented:
export CHORUS_HAP_MODE=web
export CHORUS_HAP_WEB_PORT=8082

./chorus-hap
# Access via http://localhost:8082

Multi-User Setup

# Multiple humans can join network with different agent IDs

# Human 1 (Alice)
CHORUS_AGENT_ID=human-alice CHORUS_P2P_PORT=9001 ./chorus-hap &

# Human 2 (Bob)
CHORUS_AGENT_ID=human-bob CHORUS_P2P_PORT=9002 ./chorus-hap &

# Both connect to same network via mDNS/DHT
# Both can collaborate on same decisions/tasks

---

Troubleshooting

HAP Won't Start

Symptom: HAP exits immediately with error

Possible Causes:

1. Invalid or missing license

   ❌ Failed to initialize CHORUS HAP: license validation failed
   

   Fix: Check CHORUS_LICENSE_ID and KACHING server connectivity

2. Port already in use

   ❌ Failed to initialize: bind: address already in use
   

   Fix: Change CHORUS_P2P_PORT or kill process on port

3. P2P node creation failed

   ❌ Failed to create P2P node: ...
   

   Fix: Check network connectivity and firewall rules

Terminal Not Accepting Input

Symptom: hap> prompt doesn't respond to keyboard

Possible Causes:

1. Running without TTY Fix: Use -it flags if running in Docker: docker run -it ...

2. STDIN redirected Fix: Ensure terminal has direct stdin access

3. Terminal encoding issues Fix: Set LANG=en_US.UTF-8 or appropriate locale

No Peers Discovered

Symptom: HAP shows 0 connected peers

Possible Causes:

1. mDNS blocked by firewall Fix: Allow UDP port 5353, or use bootstrap peers

2. No other agents running Fix: Start at least one chorus-agent on network

3. Network isolation Fix: Ensure HAP can reach other peers on P2P ports

Web Mode Falls Back to Terminal

Symptom: Web mode requested but terminal interface starts

Expected Behavior: This is normal! Web interface is currently stubbed (Phase 3).

Log Output:

🌐 Starting web interface for human interaction
⚠️ Web interface not yet implemented
🔄 HAP running in stub mode - P2P connectivity established
💻 Starting terminal interface for human interaction

Workaround: Use terminal interface until Phase 3 implementation

HMMM Messages Not Received

Symptom: Compose HMMM message but peers don't see it

Possible Causes:

1. Not subscribed to topic Check: Verify PubSub subscription status Fix: Restart HAP to re-subscribe

2. PubSub not enabled Check: status command shows PubSub status Fix: Ensure DHT is enabled

3. Message formatting error Check: HAP logs for publish errors Fix: Report issue with message details

Commands Don't Work

Symptom: Type command but nothing happens

Possible Causes:

1. Typo in command name Fix: Type help to see valid commands

2. Missing required arguments

   Usage: ucxl <address>
   

   Fix: Provide required arguments

3. Backend error (silent failure) Fix: Check HAP logs for error messages

---

Related Documentation

• chorus-agent - Autonomous agent binary
• chorus - Deprecated compatibility wrapper
• internal/runtime - Shared runtime initialization
• internal/hapui - Terminal and web interface implementations
• HMMM Protocol - Meta-discussion protocol
• UCXL Specification - Context addressing
• Decision System - Democratic voting
• Configuration - Environment variables

---

Implementation Status

Feature	Status	Notes
Terminal Interface	✅ Production	Full interactive REPL
Web Interface	⏳ Stubbed	Phase 3 implementation pending
P2P Networking	✅ Production	Same as chorus-agent
HMMM Composition	✅ Production	Guided wizard with templates
UCXL Browser	✅ Production	Interactive context navigation
Decision Voting	✅ Production	Full voting workflow
Collaborative Sessions	✅ Production	Multi-party editing
Patch Creation	✅ Production	Diff-based submission
Web Bridge	🔶 Beta	Experimental browser access
Task Approval	✅ Production	Interactive task acceptance
Peer Management	✅ Production	List and monitor peers
Health Checks	✅ Production	Liveness & readiness
Availability Tracking	✅ Production	Idle/away detection
License Validation	✅ Production	KACHING integration

Phase 3 Roadmap: Web Interface

Planned Components:

1. HTTP Server with WebSocket

   • Real-time bidirectional communication
   • Server-sent events for notifications
   • WebSocket for collaborative sessions

2. Web Forms for HMMM

   • Rich text editor for message composition
   • Template selection dropdown
   • Preview before submission

3. Visual Context Browser

   • Tree view of UCXL contexts
   • Graph visualization of relationships
   • Search and filter capabilities

4. Decision Voting UI

   • Card-based decision display
   • Interactive voting buttons
   • Real-time vote tallies
   • Voting history timeline

5. Dashboard

   • Network status overview
   • Connected peers visualization
   • Active sessions monitoring
   • Personal activity feed

6. Multi-User Support

   • Authentication for web users
   • Session management
   • User presence indicators

Implementation Estimate: 2-3 development sprints

See: cmd/hap/main.go lines 114-126 for TODO details

---

Best Practices

Agent ID Naming

Recommended Format:

# Human agents: prefix with "human-"
CHORUS_AGENT_ID=human-alice
CHORUS_AGENT_ID=human-bob-ops
CHORUS_AGENT_ID=human-security-team

# Makes it clear in network views who is human vs autonomous

Working Hours Configuration

Availability Signaling:

HAP automatically signals availability based on activity. For scheduled availability:

# Set custom idle/away timeouts via configuration
# (Future enhancement)
CHORUS_HAP_IDLE_TIMEOUT=900      # 15 minutes
CHORUS_HAP_AWAY_TIMEOUT=3600     # 1 hour

Collaborative Workflow

Best Practice for Human-Agent Collaboration:

1. Start HAP at beginning of work session
2. Announce presence: announce command
3. Monitor network status: Use status and peers regularly
4. Participate in decisions: Check for pending votes with decide
5. Collaborate actively: Join collaborative sessions when invited
6. Review agent work: Use UCXL browser to audit agent decisions
7. Clean exit: Use quit command (not Ctrl+C) for graceful shutdown

Security Considerations

Sensitive Operations:

Humans can override agent decisions for sensitive operations:

• Production deployments
• Database schema changes
• Security policy updates
• API versioning changes

Recommended Setup:

• Use separate license for HAP (human-authorized)
• Grant HAP elevated permissions for overrides
• Require human approval for sensitive task categories

---

Last Updated: 2025-09-30