Agent Bus Human Walkthrough

# Agent Bus Human Walkthrough


<!-- lifehub-reader-view-link -->
> **Reader View:** [Open the generated HTML reader view](../../../07_outputs/reader_site/pages/LifeHub/03_systems/Agent_Bus/00_user_guide/AGENT_BUS_HUMAN_WALKTHROUGH.html). Markdown remains the canonical source of truth.


## What this guide is

This guide explains what the Agent Bus is today from the human operator's point of view.

It is intentionally practical. It answers:

- What has actually been built?
- What can Yesh do with it right now?
- What is still only planned?
- Where do Redis Streams, tasks, Codex, Hermes, and ChatGPT fit?
- What is the next missing layer before this feels like a tool a person can sit down and use?

## The plain truth first

Agent Bus is not yet a finished user-facing app.

Right now, it is an MVP coordination engine and policy layer with tested task, delegation, result, deadletter, worker-base, inspection, and report/review-pointer behavior.

It does **not** yet provide a simple human-facing place where you can say, "put this task into the bus," watch agents consume it, and see the whole routing loop run through Redis.

That is the next usability gap.

## What Agent Bus is meant to become

Agent Bus is the local-first coordination layer for human and AI work.

Its job is not to let agents freely chat. Its job is to move bounded tasks through a controlled system:

```text
Human / Coordinator
        |
        v
Agent Bus Coordinator
        |
        v
Task records + task queues
        |
        +--> lh:q:codex
        +--> lh:q:hermes
        +--> lh:q:adam
        |
        v
Results, events, deadletters, exports, closeouts
```

The durable model is a task tree, not a chat room:

```text
root task
  ├── child task
  │   └── grandchild task
  └── child task
```

Agents process assigned tasks. Delegation creates child tasks. Results return upward.

## What exists today

The MVP currently includes these implemented pieces:

| Area | Current status |
|---|---|
| Task schemas | Implemented and tested |
| Agent records | Implemented and tested |
| Coordinator policy layer | Implemented and tested |
| Task submission rules | Implemented and tested |
| Lifecycle transitions | Implemented and tested |
| Delegation approval rules | Implemented and tested |
| Loop/delegation safety | Implemented and tested |
| Worker base behavior | Implemented and tested in mock-safe form |
| Recovery/deadletter records | Implemented and tested |
| Human inspection/export helpers | Implemented and tested |
| Codex report-ready bridge | Implemented and tested |
| Hermes review-ready bridge | Implemented and tested |
| Coordinator review-flow pointer routing | Implemented and tested |
| Durable report/closeout conventions | Documented and merged |

The important phrase is **implemented and tested**, not **running as a live daily bus**.

## What does not exist yet

These pieces are not live yet:

| Missing layer | Meaning for the human user |
|---|---|
| Persistent Redis-backed task intake | There is not yet a normal daily command/form that submits real work into a persistent bus. |
| Always-on coordinator runtime | The coordinator exists as a Python policy layer, not a long-running service you use all day. |
| Codex worker daemon | Codex is not yet sitting on `lh:q:codex` waiting for tasks. |
| Hermes worker daemon | Hermes is not yet sitting on `lh:q:hermes` waiting for reviews. |
| Adam browser watcher | Adam is not yet watching `lh:adam:web_wake`. |
| Human dashboard/UI | There is no browser UI for task intake, queues, results, or deadletters. |
| Automatic routing loop | Work does not yet flow end-to-end without deliberate operator orchestration. |

This is why the system may feel abstract right now.

## What the current CLI can do

The current CLI is mostly for inspection and export.

From the Agent Bus MVP source folder, the available commands are:

```text
lifehub-agent-bus list-agents
lifehub-agent-bus list-open-tasks
lifehub-agent-bus list-tasks [--status STATUS]
lifehub-agent-bus list-results [--task-id TASK_ID] [--root-task-id ROOT_TASK_ID]
lifehub-agent-bus list-deadletter [--recoverable true|false]
lifehub-agent-bus export-task TASK_ID
lifehub-agent-bus export-thread ROOT_TASK_ID
```

But there is a major current limitation:

```text
The CLI uses an in-memory coordinator by default.
```

That means if you run it cold, it will not show an existing persistent Redis-backed task world. It will usually show empty lists unless a script or test has populated that coordinator instance.

## What Redis means right now

Redis Streams are the intended local broker shape.

The naming and runtime design are defined, and the MVP reserves these concepts:

```text
lh:q:<agent_id>        normal agent task queue
lh:results             result stream
lh:events              event stream
lh:deadletter          deadletter stream
lh:task:<task_id>      task record
lh:children:<task_id>  child task list
lh:parent:<task_id>    parent lookup
lh:idempotency:<key>   duplicate suppression
lh:agent:<agent_id>    agent record
```

But the current human-facing flow does not yet give you a persistent Redis dashboard or intake command.

So Redis is designed into the system, but not yet exposed as a daily user surface.

## What using Agent Bus looks like today

Today, the practical path still goes through LifeHub Command Interface.

A realistic current session looks like this:

```text
Yesh: I want to move the next Agent Bus phase forward.

ChatGPT:
1. Checks live repo truth.
2. Identifies the active phase.
3. Creates or updates a plan/packet.
4. Uses Codex Dispatch if implementation is bounded and appropriate.
5. Uses Hermes Dispatch if independent review is needed.
6. Reviews the diff/PR.
7. Merges only if scope and validation are clean.
8. Records closeout.
```

That is useful, but it is not the same as a live Redis task pipeline.

It is more accurate to call today’s practical workflow:

```text
Conversation-orchestrated local agent execution
```

rather than:

```text
Fully running Redis Agent Bus
```

## Where Codex and Hermes fit today

Codex and Hermes currently attach through controlled local dispatch, not through live queue daemons.

| Actor | Current practical use |
|---|---|
| ChatGPT / LifeHub Command Interface | Decide, route, prepare packets, check repo truth, inspect diffs, open/merge PRs. |
| Codex | Execute bounded implementation/docs/code tasks on the VM when dispatched. |
| Hermes | Review, synthesize, critique, and advise when dispatched. |
| Agent Bus | Provides the target coordination model, tested schemas, policy layer, and report/review conventions. |

Later, Codex and Hermes may become true Agent Bus workers. That is not live yet.

## Current task lifecycle model

The implemented lifecycle is:

```text
open
  -> claimed
  -> in_progress
  -> done
```

Other terminal or recovery states include:

```text
failed
blocked
cancelled
deadlettered
```

A healthy future flow should look like:

```text
1. Human submits a root task.
2. Coordinator validates it.
3. Coordinator writes the task record.
4. Coordinator places it on the assigned agent queue.
5. Agent claims the task.
6. Agent starts the task.
7. Agent records a result.
8. Coordinator marks the task complete or escalates.
9. Human inspects the task thread and result.
```

Today, this flow is implemented as a policy/testable model, but not yet exposed as a persistent user-facing flow.

## What delegation means

Delegation is not free-form agent chat.

A child task may be created only through coordinator-governed rules:

```text
parent task
  |
  v
approved delegation request
  |
  v
child task assigned to another agent
```

The coordinator enforces rules such as:

- no self-delegation
- no delegation to ancestor agents
- max depth
- max children per task
- active receiving agent required
- allowed delegatees respected
- idempotency enforced

## What deadletters mean

A deadletter is a safe failure record.

Malformed, invalid, stale, unsafe, or failed work should not vanish and should not silently retry forever.

It should land in a recoverable or non-recoverable deadletter trail that a human can inspect.

Future UI value:

```text
Show me failed work.
Show me what can be recovered.
Show me why it failed.
Let me decide whether to retry, repair, or close it.
```

## What you can ask ChatGPT to do right now

Useful current commands are conversational:

```text
Where are we in Agent Bus?
```

```text
Show me what is implemented versus planned.
```

```text
Prepare the next Agent Bus packet.
```

```text
Codex Dispatch this bounded task.
```

```text
Ask Hermes to review this plan.
```

```text
Review and merge this PR if clean.
```

```text
Create a demo that lets me experience Agent Bus task flow.
```

The last command is probably the next practical usability step.

## The missing first user experience

The next thing you likely need is not browser wake yet.

You need one of these first:

### Option A: Demo seed script

A script that creates sample agents, tasks, delegation, results, and deadletters in memory so you can run inspection commands and see the model.

Good for learning the concepts quickly.

### Option B: Real task-submit CLI

A command like:

```text
lifehub-agent-bus submit-task --to codex --subject "Fix X" --body "..."
```

Good for starting to use the bus from the terminal.

### Option C: Redis-backed persistence adapter

A real Redis store behind the coordinator, so state survives process boundaries.

Good for making it feel like a real local bus.

### Option D: Tiny local dashboard

A simple HTML/local web view showing agents, queues, tasks, results, and deadletters.

Good for human visibility, but it should not hide missing runtime pieces.

## Recommended next practical sequence

Before browser wake, the recommended user-facing sequence is:

```text
1. Create this human walkthrough. ✅
2. Build a tiny demo/seed flow so Yesh can see tasks, results, delegation, and deadletters.
3. Add a submit-task CLI command or demo command.
4. Add Redis-backed persistence for real local state.
5. Only then return to browser-wake SOP and locks.
```

The reason is simple: you should be able to experience the bus before Adam/browser wake is wired into it.

## What to remember

Agent Bus is real, but not yet user-friendly.

The MVP has strong internal rules and tests. The next missing layer is a tangible human interaction path:

```text
Put task in -> see queue -> see agent claim/start/finish -> see result -> inspect thread
```

Until that exists, the system will feel more like infrastructure than a tool.