bzzz/archive/bzzz_hap_dev_plan.md

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

• Scaffold file/folder structure as above.
• 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)

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)

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)

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

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:

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.