feat(telemetry): complete bb-buff.1.3 - Backend Liveness Refactor
STORY: The session backend needed to aggregate agent health from a live telemetry stream rather than static bead metadata. This refactor makes liveness signals real-time and accurate. COLLABORATION: We extended the ActivityEvent model with a native 'heartbeat' kind, updated extendActivityLease() to emit through the activity bus, and refactored getAgentLivenessMap() to prioritize heartbeat activity history over stale bead metadata. DELIVERABLES: - ActivityEvent extended with 'heartbeat' kind - extendActivityLease() emits heartbeats through activity bus - getAgentLivenessMap() prefers telemetry over static metadata - Registry APIs support projectRoot injection for testing - Tests verify preference logic via TDD VERIFICATION: - 93/93 tests PASSING - Heartbeat override verified in isolated temp projects CLOSES: bb-buff.1.3 BLOCKS: bb-buff.3.2, bb-buff.3.3, bb-buff.2.1
This commit is contained in:
zenchantlive
parent
0016b57e37
commit
4ee550c333
36 changed files with 1380 additions and 541 deletions
|
|
@ -1,66 +1,78 @@
|
|||
---
|
||||
name: beadboard-driver
|
||||
description: Drive BeadBoard agent workflows with strict preflight, per-session unique agent identity, and evidence-backed closeout. Use when handling bead lifecycle work that combines bd status commands with bb agent coordination (register/list/show, send/inbox/read/ack, reserve/release/status), especially in multi-agent sessions where path resolution, collision avoidance, and verification discipline are required.
|
||||
description: Drive BeadBoard agent workflows with strict Operative Protocol v1 compliance. Use when handling bead lifecycle work that combines bd status commands with bb agent coordination (register/adopt, activity-lease, reserve/release, send/ack), especially in multi-agent sessions requiring silent observability and collision avoidance.
|
||||
---
|
||||
|
||||
# Beadboard Driver
|
||||
# Beadboard Driver (Operative Protocol v1)
|
||||
|
||||
## Overview
|
||||
|
||||
Use this skill to run repeatable `bd` + `bb` workflows without drift. Resolve `bb` safely, generate a unique session identity, coordinate with reservations/mail, and produce closeout evidence before claiming completion.
|
||||
Use this skill to run repeatable `bd` + `bb` workflows under the **Activity Lease** (Parking Permit) model. Resolve `bb` safely, bootstrap via `bb-init`, coordinate via traceable incursions, and maintain liveness through real work.
|
||||
|
||||
## Core Workflow
|
||||
|
||||
1. Run preflight:
|
||||
1. **Bootstrap & Handshake**:
|
||||
Run `bb-init` to resolve paths and identify yourself. Use `--adopt` if resuming a task with uncommitted changes.
|
||||
```bash
|
||||
node skills/beadboard-driver/scripts/session-preflight.mjs
|
||||
node scripts/bb-init.mjs --register <agent-name> --role <role> --json
|
||||
# OR
|
||||
node scripts/bb-init.mjs --adopt <prior-agent-id> --non-interactive --json
|
||||
```
|
||||
|
||||
2. Generate a unique per-session agent name:
|
||||
2. **Claim Territory**:
|
||||
Reserve your work surface before making edits to prevent silent collisions.
|
||||
```bash
|
||||
node skills/beadboard-driver/scripts/generate-agent-name.mjs
|
||||
```
|
||||
|
||||
3. Register identity, then claim bead:
|
||||
```bash
|
||||
& "$env:BB_REPO\bb.ps1" agent register --name <agent-name> --role <role>
|
||||
& "$env:BB_REPO\bb.ps1" agent reserve --agent <agent-id> --scope "src/lib/*" --bead <bead-id>
|
||||
bd update <bead-id> --status in_progress --claim
|
||||
```
|
||||
|
||||
4. Coordinate during implementation:
|
||||
3. **Physical Change -> Contextual Lookup**:
|
||||
If you encounter uncommitted changes in a file you didn't personally edit: **STOP and Query**.
|
||||
```bash
|
||||
& "$env:BB_REPO\bb.ps1" agent reserve --agent <agent-name> --scope "<path-glob>" --bead <bead-id>
|
||||
& "$env:BB_REPO\bb.ps1" agent send --from <agent-name> --to <peer-agent> --bead <bead-id> --category HANDOFF --subject "<subject>" --body "<body>"
|
||||
& "$env:BB_REPO\bb.ps1" agent status --agent <agent-id>
|
||||
& "$env:BB_REPO\bb.ps1" agent inbox --agent <agent-id> --state unread
|
||||
```
|
||||
|
||||
5. Build readiness summary before close:
|
||||
4. **Explain Deltas**:
|
||||
Send high-fidelity signals when you hit milestones or incursions.
|
||||
```bash
|
||||
& "$env:BB_REPO\bb.ps1" agent send --from <agent-id> --to <peer> --bead <bead-id> --category INFO --subject "Patched parser.ts for UI sync" --body "..."
|
||||
```
|
||||
|
||||
5. **Liveness Maintenance**:
|
||||
Liveness is **Passive**. Any `bb agent` command extends your lease. Use `activity-lease` if you haven't run a command in > 10 minutes.
|
||||
```bash
|
||||
& "$env:BB_REPO\bb.ps1" agent activity-lease --agent <agent-id> --json
|
||||
```
|
||||
|
||||
6. **Closeout Evidence**:
|
||||
```bash
|
||||
node skills/beadboard-driver/scripts/readiness-report.mjs --checks '[{"name":"typecheck","ok":true}]' --artifacts '[{"path":"artifacts/final.png","required":true}]'
|
||||
bd close <bead-id> --reason "..."
|
||||
```
|
||||
|
||||
## Path Resolution Policy
|
||||
## Identity & Adoption Policy
|
||||
|
||||
- Treat `BB_REPO` as authoritative when set.
|
||||
- On invalid `BB_REPO`, stop and return remediation text. Do not silently bypass.
|
||||
- If `BB_REPO` is unset, resolve from global `bb`, then cached path, then bounded discovery.
|
||||
- Update the skill cache only after a verified path is found.
|
||||
- Never mutate shell profile/env vars automatically.
|
||||
- **Uniqueness**: Create one unique `adjective-noun` identity per session unless adopting.
|
||||
- **Adoption Guardrails**: Adoption is ONLY allowed if uncommitted changes exist in the scope OR you own an `in_progress` bead.
|
||||
- **Audit**: Every adoption triggers a `RESUME` event in the audit feed.
|
||||
|
||||
## Identity Policy
|
||||
## Activity Lease (Parking Permit)
|
||||
|
||||
- Create one unique agent identity per session.
|
||||
- Use adjective-noun names and retry on collisions.
|
||||
- Register identity before any mail/reservation command.
|
||||
- Keep bead claim authority in `bd`; identity alone is not a claim.
|
||||
- **Active (0-15m)**: Lease is valid. You are protected from takeover.
|
||||
- **Stale (15-30m)**: Lease expired. Others can takeover with `--takeover-stale`.
|
||||
- **Evicted (30m+)**: Lease dead. Others should takeover and archive your reservation.
|
||||
- **Idle (60m+)**: Ghost state. You are considered gone.
|
||||
|
||||
## Verification Policy
|
||||
## Red Flags - STOP and Start Over
|
||||
|
||||
- Do not claim completion without fresh command evidence.
|
||||
- Require typecheck, test, and lint evidence for closeout tasks.
|
||||
- Use readiness report output in bead notes.
|
||||
- **Silent Incursion**: Editing a reserved file without sending an `INFO` message.
|
||||
- **Identity Reuse**: Reusing an agent ID from a previous session without an adoption handshake.
|
||||
- **Mocking**: Implementing mocks instead of coordinating with the domain owner.
|
||||
- **Terminal Pop-ups**: Spawning background workers that disrupt the user's desktop.
|
||||
|
||||
## References
|
||||
|
||||
- Command and argument contracts: `references/command-matrix.md`
|
||||
- Failure and recovery handling: `references/failure-modes.md`
|
||||
- End-to-end session choreography: `references/session-lifecycle.md`
|
||||
- Protocol Specification: `docs/protocols/operative-protocol-v1.md`
|
||||
Loading…
Add table
Add a link
Reference in a new issue