122 lines
2.9 KiB
Markdown
122 lines
2.9 KiB
Markdown
|
# Coordination Events, Sessions, and Acknowledgment
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
|
||
|
|
Define how agents communicate status, blockers, incursions, and handoffs in a machine-readable way that BeadBoard can render and users can act on.
|
||
|
|
|
||
|
|
## Operating Model
|
||
|
|
|
||
|
|
- Agent works in a target repository.
|
||
|
|
- User watches and orchestrates from BeadBoard UI.
|
||
|
|
- Agent communication must flow through coordination events and inbox state transitions, not ad-hoc notes.
|
||
|
|
|
||
|
|
## Event Categories
|
||
|
|
|
||
|
|
Use explicit categories with clear intent:
|
||
|
|
|
||
|
|
- `HANDOFF`: transfer ownership or next action.
|
||
|
|
- `BLOCKED`: explicit dependency or missing input.
|
||
|
|
- `RESUME`: adoption/resumption event.
|
||
|
|
- `INFO`: milestone or important context.
|
||
|
|
- `INCURSION`: overlap/collision signal for reserved scope.
|
||
|
|
|
||
|
|
## Session Stream Expectations
|
||
|
|
|
||
|
|
Session feeds should be audit-friendly:
|
||
|
|
|
||
|
|
- Every coordination event has sender, recipient/system target, bead id, and timestamp.
|
||
|
|
- `INCURSION` and `RESUME` are first-class timeline rows, not hidden diagnostics.
|
||
|
|
- Events should be understandable by humans without reading implementation code.
|
||
|
|
|
||
|
|
## Message Lifecycle
|
||
|
|
|
||
|
|
Inbox state machine:
|
||
|
|
|
||
|
|
1. `unread` when message is delivered.
|
||
|
|
2. `read` when recipient opens/reads message.
|
||
|
|
3. `acked` when recipient explicitly acknowledges.
|
||
|
|
|
||
|
|
Required behavior:
|
||
|
|
|
||
|
|
- Only recipient may ack.
|
||
|
|
- Acks are explicit, not implied by read.
|
||
|
|
- Blocker and handoff flows should request ack when coordination certainty is required.
|
||
|
|
|
||
|
|
## Recommended Command Patterns
|
||
|
|
|
||
|
|
Send structured coordination event:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bb agent send \
|
||
|
|
--from <agent-id> \
|
||
|
|
--to <peer-agent-id> \
|
||
|
|
--bead <bead-id> \
|
||
|
|
--category <HANDOFF|BLOCKED|RESUME|INFO|INCURSION> \
|
||
|
|
--subject "<short summary>" \
|
||
|
|
--body "<actionable details>"
|
||
|
|
```
|
||
|
|
|
||
|
|
Read inbox for current bead/session work:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
bb agent inbox --agent <agent-id> --state unread --bead <bead-id>
|
||
|
|
bb agent read --agent <agent-id> --message <message-id>
|
||
|
|
bb agent ack --agent <agent-id> --message <message-id>
|
||
|
|
```
|
||
|
|
|
||
|
|
## Coordination Contracts
|
||
|
|
|
||
|
|
### Handoff
|
||
|
|
|
||
|
|
A `HANDOFF` should include:
|
||
|
|
|
||
|
|
- what is done,
|
||
|
|
- what remains,
|
||
|
|
- concrete next action,
|
||
|
|
- whether ack is required.
|
||
|
|
|
||
|
|
### Blocked
|
||
|
|
|
||
|
|
A `BLOCKED` should include:
|
||
|
|
|
||
|
|
- blocker description,
|
||
|
|
- requested action,
|
||
|
|
- urgency,
|
||
|
|
- ack requirement.
|
||
|
|
|
||
|
|
### Incursion
|
||
|
|
|
||
|
|
An `INCURSION` should include:
|
||
|
|
|
||
|
|
- overlap kind (`exact` or `partial`),
|
||
|
|
- owner identity,
|
||
|
|
- incoming identity,
|
||
|
|
- owner liveness,
|
||
|
|
- resolution hint.
|
||
|
|
|
||
|
|
### Resume
|
||
|
|
|
||
|
|
A `RESUME` should include:
|
||
|
|
|
||
|
|
- resume reason,
|
||
|
|
- prior session identity,
|
||
|
|
- adopted identity,
|
||
|
|
- evidence summary for safe adoption.
|
||
|
|
|
||
|
|
## UX Alignment
|
||
|
|
|
||
|
|
Session UI should map event semantics to plain-language actions:
|
||
|
|
|
||
|
|
- Handoff label: "Passed to"
|
||
|
|
- Blocked label: "Needs input"
|
||
|
|
- Read action: "Seen"
|
||
|
|
- Ack action: "Accepted"
|
||
|
|
|
||
|
|
## Anti-Patterns
|
||
|
|
|
||
|
|
- Using comments instead of coordination events for handoffs.
|
||
|
|
- Silent reservation collisions with no `INCURSION`/`INFO` signal.
|
||
|
|
- Treating read as ack.
|
||
|
|
- Sending vague events with no actionable payload.
|
||
|
|
- Closing a blocked bead without tracking unblock communication.
|