HAP Analysis: Archive docs and create implementation action plan
- Archive all existing markdown documentation files - Create comprehensive HAP_ACTION_PLAN.md with: * Analysis of current BZZZ implementation vs HAP vision * 4-phase implementation strategy * Structural reorganization approach (multi-binary) * HAP interface implementation roadmap - Preserve existing functionality while adding human agent portal - Focus on incremental migration over rewrite 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
208
archive/bzzz_hap_dev_plan.md
Normal file
208
archive/bzzz_hap_dev_plan.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user