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

- [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.