136 lines
3.9 KiB
Markdown
136 lines
3.9 KiB
Markdown
# Coordination Events, Sessions, and Acknowledgment
|
|
|
|
This guide defines how agents coordinate work using the live BeadBoard surface:
|
|
- `bb agent send|inbox|read|ack`
|
|
- `bd mail` delegated to `bb agent` through `bb-mail-shim.mjs`
|
|
|
|
For full command reference, see `coordination-system.md`.
|
|
|
|
## Canonical Event Categories
|
|
|
|
Use only these categories:
|
|
- `HANDOFF`
|
|
- `BLOCKED`
|
|
- `DECISION`
|
|
- `INFO`
|
|
|
|
Do not use deprecated categories such as `RESUME` or `INCURSION`.
|
|
|
|
## Message Lifecycle and ACK Rules
|
|
|
|
Message states are:
|
|
- `unread`
|
|
- `read`
|
|
- `acked`
|
|
|
|
Rules:
|
|
- `HANDOFF` and `BLOCKED` set `requires_ack=true` automatically.
|
|
- `DECISION` and `INFO` set `requires_ack=false`.
|
|
- `bb agent ack` on an unread message advances state to `acked` and sets both read/ack timestamps.
|
|
- Only the recipient can `read`/`ack` a message.
|
|
|
|
## WHEN-to-Use Trigger Map
|
|
|
|
1. You finished your slice and someone else now owns the next step: send `HANDOFF`.
|
|
2. You are hard blocked by dependency/input/env: send `BLOCKED` and set your agent state to `stuck`.
|
|
3. You need a decision but can still make partial progress: send `DECISION`.
|
|
4. You want traceable FYI context (milestone, caveat, pointer): send `INFO`.
|
|
5. You receive `HANDOFF`/`BLOCKED` and have taken responsibility: run `read` then `ack`.
|
|
6. You receive actionable mail before claiming a bead: process inbox first, then claim.
|
|
7. You are stuck after retries: poll inbox, send/refresh `BLOCKED`, keep state `stuck` until unblocked.
|
|
|
|
## Inbox Polling Protocol
|
|
|
|
Minimum checkpoints:
|
|
- session start
|
|
- immediately before claiming a bead
|
|
- before closing a bead
|
|
- whenever local execution becomes stuck
|
|
|
|
Recommended during active execution:
|
|
- poll every 60-120 seconds
|
|
|
|
Commands:
|
|
|
|
```bash
|
|
bb agent inbox --agent <agent-id> --state unread --limit 25
|
|
bb agent read --agent <agent-id> --message <message-id>
|
|
bb agent ack --agent <agent-id> --message <message-id>
|
|
```
|
|
|
|
## Worked BLOCKED Flow (End-to-End)
|
|
|
|
1. Agent hits a blocker and notifies coordinator/peer.
|
|
|
|
```bash
|
|
bb agent send \
|
|
--from amber-otter \
|
|
--to lead-orchestrator \
|
|
--bead beadboard-maf.8 \
|
|
--category BLOCKED \
|
|
--subject "Cannot run mail contract test" \
|
|
--body "bd mail delegate missing in this repo; need delegate config or approval to run preflight patch"
|
|
```
|
|
|
|
2. Agent marks itself stuck for BeadBoard liveness/Witness surface.
|
|
|
|
```bash
|
|
bd agent state amber-otter stuck
|
|
```
|
|
|
|
3. User sees the blocked signal in BeadBoard UI and intervenes (provides input, clears dependency, or updates config).
|
|
|
|
4. Agent checks inbox and reads response.
|
|
|
|
```bash
|
|
bb agent inbox --agent amber-otter --state unread
|
|
bb agent read --agent amber-otter --message <message-id>
|
|
```
|
|
|
|
5. If the response resolved the blocker, agent acknowledges and resumes.
|
|
|
|
```bash
|
|
bb agent ack --agent amber-otter --message <message-id>
|
|
bd agent state amber-otter running
|
|
```
|
|
|
|
6. Agent resumes bead execution and continues heartbeat + evidence updates.
|
|
|
|
## `bd mail` Delegate Path (Alternative Invocation)
|
|
|
|
`bd mail` should delegate to the BeadBoard mail shim:
|
|
|
|
```bash
|
|
bd config set mail.delegate "node <abs-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs"
|
|
export BB_AGENT=<agent-id>
|
|
```
|
|
|
|
Delegate mapping:
|
|
- `bd mail send ...` -> `bb agent send --from <BB_AGENT> ...`
|
|
- `bd mail inbox ...` -> `bb agent inbox --agent <BB_AGENT> ...`
|
|
- `bd mail read <id>` -> `bb agent read --agent <BB_AGENT> --message <id>`
|
|
- `bd mail ack <id>` -> `bb agent ack --agent <BB_AGENT> --message <id>`
|
|
|
|
If delegate is missing or invalid, run:
|
|
|
|
```bash
|
|
node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs
|
|
```
|
|
|
|
## Reservation Conflict Protocol
|
|
|
|
Use reservations before editing contested scope:
|
|
|
|
```bash
|
|
bb agent reserve --agent <agent-id> --scope <path-or-surface> --bead <bead-id>
|
|
```
|
|
|
|
Conflict handling:
|
|
- Active reservation conflict: stop and coordinate through mail.
|
|
- Stale reservation warning: retry with `--takeover-stale` only after explicit coordination.
|
|
|
|
Release when done:
|
|
|
|
```bash
|
|
bb agent release --agent <agent-id> --scope <path-or-surface>
|
|
```
|