viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
beadboard/docs/plans/2026-03-05-embedded-pi-roadmap.md
zenchantlive d335e5bf71 fix: orchestrator button + Pi SDK session error 
- Move leftSidebarMode from URL state to local useState in unified-shell,
    avoiding force-dynamic router round-trip that made the button appear broken                                           - Replace fileURLToPath(new URL(..., import.meta.url)) with process.cwd()
    in bb-pi-bootstrap.ts — import.meta.url is a webpack:// URL in Next.js,
    causing cross-realm TypeError when passed to Node.js fileURLToPath()
2026-03-24 19:02:04 -05:00

373 lines
13 KiB
Markdown
Raw Permalink Blame History

# BeadBoard Embedded Pi Roadmap
**Date:** 2026-03-05
**Last Updated:** 2026-03-07
**Companion PRD:** `docs/plans/2026-03-05-embedded-pi-prd.md`
**Purpose:** Track what has already shipped for Embedded Pi in BeadBoard, what is partially complete, and what remains to reach the full PRD vision.
---
## Current status
**Phase 3 COMPLETE - Testing in progress.**
We now have:
- ✅ Working embedded orchestrator with BeadBoard tools
- ✅ Worker spawning with numbered instances (Engineer 01, etc.)
- ✅ Agent types (architect, engineer, reviewer, tester, investigator, shipper)
- ✅ Template-based team spawning
- ✅ **Bead-required workflow** - every worker task has a bead
- ✅ **Async worker coordination** - non-blocking spawn, check status, read results
- ✅ **File verification pattern** - orchestrator reads actual files to verify work
**Currently testing:**
- Worker claims bead, updates, closes correctly
- Orchestrator can check worker status mid-task
- Orchestrator can get results and verify via file reads
**Biggest remaining gaps:**
- Phase 4: Launch-anywhere UX (spawn from task cards, graph nodes)
- Phase 5: Agent presence in social/graph views
- Tests and verification
---
## What is done
### Done: Runtime substrate / managed Pi foundation
- Managed Pi bootstrap exists via `src/lib/bb-pi-bootstrap.ts`
- Pi runtime detection exists via `src/lib/pi-runtime-detection.ts`
- BeadBoard-specific Pi settings + agent dir setup exist
- Embedded daemon/orchestrator substrate exists via:
- `src/lib/embedded-daemon.ts`
- `src/lib/bb-daemon.ts`
- `src/lib/pi-daemon-adapter.ts`
### Done: Orchestrator session integration
- Per-project orchestrator session can be created and reused
- Pi SDK session is initialized through the embedded adapter
- The orchestrator can receive prompts from the frontend
- The orchestrator can execute BeadBoard tools from the frontend path
### Done: BeadBoard-aware orchestrator context
- Dynamic system prompt exists in `src/tui/system-prompt.ts`
- Prompt includes:
- active tasks
- archetypes
- templates
- Deviation recording tool exists:
- `src/tui/tools/bb-deviation.ts`
### Done: Frontend prompt + telemetry plumbing
- Prompt route exists: `src/app/api/runtime/prompt/route.ts`
- Runtime event stream exists: `src/app/api/runtime/stream/route.ts`
- Runtime events endpoint exists: `src/app/api/runtime/events/route.ts`
- Left-panel orchestrator UI exists and can submit prompts
- Bottom runtime console exists and is now minimizable
### Done: Left-panel orchestrator chat UX foundation
- Left panel supports orchestrator mode
- Left panel now renders chat-style bubbles instead of raw telemetry cards
- User prompts can appear immediately in chat
- Assistant replies are projected from Pi session/runtime events
- Session/runtime errors are kept out of the main chat transcript surface
### Done: Realtime / event-ingestion hardening
- Duplicate runtime-event ingestion was debugged and deduped in the app shell
- Activity panel merging was deduped to stop repeated React key collisions
- Prompt path was changed so frontend requests return immediately instead of blocking on full agent completion
- Runtime stream now continuously surfaces new daemon events without requiring manual refresh for each turn
---
## Partially complete
### Partial: Sessions / conversation model
What works now:
- one embedded project orchestrator
- left-panel conversation surface
- runtime console telemetry
What is still missing:
- robust multi-session model
- explicit worker-session UI
- Full activity panel integration for orchestrator + worker histories
- clearer separation of orchestrator conversation vs mission/worker conversation surfaces
### Partial: Runtime observability
What works now:
- tool execution visibility
- runtime stream
- prompt submission + visible orchestrator progress
What is still missing:
- stronger stuck-session diagnostics
- clearer "thinking vs waiting vs blocked vs completed" state presentation
- better recovery/restart UX when a live session fails
### Partial: Launch plumbing
What works now:
- orchestrator prompt flow in the left panel
- UI-triggered launch route exists
What is still missing:
- launch-anywhere completion across all PRD surfaces
- more complete task/graph/swarm/mission launch affordances
- better contextual launch packaging per surface
---
## Remaining roadmap
## Phase 1 - Worker agents / sub-agents
**Status:** ✅ DONE (2026-03-06)
**Plan:** `docs/plans/2026-03-06-phase-1-worker-spawning.md`
### Shipped
- ✅ Worker spawning tool (`bb_spawn_worker`)
- ✅ Worker status tool (`bb_worker_status`)
- ✅ Worker session manager with isolated sessions
- ✅ Worker events in runtime console with "Worker" badge
- ✅ Worker lifecycle (spawning → working → completed/failed)
- ✅ Multiple parallel workers supported
- ✅ Archetype parameter support
- ✅ Worker results merge back to orchestrator chat
---
## Phase 2 - Archetypes as executable agent types
**Status:** ✅ DONE (2026-03-06)
**Plan:** `docs/plans/2026-03-06-phase-2-archetype-configs.md`
### Shipped
- ✅ Archetype CRUD tools (`bb_list_archetypes`, `bb_create_archetype`, etc.)
- ✅ Template CRUD tools (`bb_list_templates`, `bb_create_template`, etc.)
- ✅ Worker session manager loads archetype config
- ✅ Capabilities mapped to tool access (full vs read-only)
- ✅ System prompt injection per archetype
---
## Phase 3 - Agent-based orchestration
**Status:** ✅ DONE (2026-03-07) - **Testing in progress**
**Plan:** `docs/plans/2026-03-07-phase-3-agent-orchestration.md`
### Shipped
- ✅ Renamed "archetype" → "agent" everywhere user-facing
- ✅ Agent instances with numbered display names (Engineer 01, etc.)
- ✅ Agent status panel in right panel
- ✅ Agent state persistence (`.beads/agents.jsonl`)
- ✅ Template spawning tool (`bb_spawn_team`)
- ✅ Natural language task descriptions (no task_id required)
- ✅ Auto-template selection from description keywords
- ✅ Decision tree in orchestrator prompt
- ✅ Agent assignment to beads (`bb_assign_agent`)
### Additional (2026-03-07)
- ✅ **Bead-required workflow** - every worker task has a bead
- `bb_create`, `bb_update`, `bb_close`, `bb_show`, `bb_ready` tools
- Workers must claim bead → update progress → close with summary
- ✅ **Async worker coordination** - non-blocking spawn
- `bb_worker_results` tool - get results from completed workers
- Orchestrator can check status mid-task
- Continue conversation while workers run
- ✅ **File verification pattern** - orchestrator reads actual files
- Not just result strings, but actual implementation
- Makes orchestrator a true reviewer
---
## Phase 4 - Multi-surface launch-anywhere UX
**Status:** Partially done
### Remaining work
1. Complete launch affordances on:
- task cards
- graph nodes
- swarm views
- mission inspectors
- sessions contexts
- blocked triage contexts
2. Ensure each launch path packages the right local context automatically
3. Make orchestrator interactions feel consistent across surfaces
---
## Phase 5 - Agent presence in social/graph/activity views
**Status:** Not done
### Remaining work
1. Make orchestrator + worker sessions visible in social cards, graph nodes, and activity panel
2. Support switching between active workers via left-panel orchestrator
3. Preserve longer conversation history cleanly
4. Add intervention / redirection UX for active worker sessions
---
## Phase 6 - Runtime hardening and persistence
**Status:** Partially done
### Remaining work
1. Reduce drift between TUI Pi loader path and embedded Pi loader path
2. Harden reconnect/restart behavior for embedded sessions
3. Improve stuck/hung agent diagnostics
4. Clarify true host-daemon vs in-process lifecycle direction
5. Strengthen project-scoped persistence and restoration guarantees
---
## Phase 7 — Tests and verification
**Status:** Mostly not done
### Remaining work
1. Unit coverage for runtime path resolution / event projection / chat projection
2. Contract tests for adapter and runtime event schemas
3. Integration tests for orchestrator session creation + prompt flow
4. UI tests for left-panel orchestrator chat behavior
5. End-to-end tests for prompt → tool → reply flow
6. Failure-path tests for runtime import/session/tool errors
---
## Phase 8 — Unified Settings System (Future)
**Status:** Not started, documented in PRD Section 24
### Goal
Comprehensive settings for CLI and frontend: model selection, provider auth, UI preferences, runtime config.
### See
`docs/plans/2026-03-05-embedded-pi-prd.md` Section 24 for full requirements.
---
## Phase 9 — Holistic Skill Update (After All Phases Complete)
**Status:** Not started, depends on Phases 1-8
### Goal
Update `skills/beadboard-driver/` to reflect the new agent-based architecture.
### Why This Is Needed
The skill documentation was written before Phase 1-3 decisions:
- Archetypes were renamed to Agents
- Agent instances get numbered display names (Engineer 01, etc.)
- Templates are how teams are composed
- Workers spawn via `bb_spawn_worker(description)` not `bd create`
- Natural language task descriptions, not task_id requirements
### Files to Update
**Core Skill:**
- `skills/beadboard-driver/SKILL.md` - Main runbook
**References:**
- `skills/beadboard-driver/references/archetypes-templates-swarms.md` - Rename archetypes → agents
- `skills/beadboard-driver/references/command-matrix.md` - Add new agent tools
- `skills/beadboard-driver/references/agent-state-liveness.md` - Update for numbered instances
- `skills/beadboard-driver/references/session-lifecycle.md` - Update worker spawn flow
- `skills/beadboard-driver/references/coordination-system.md` - May need updates
- `skills/beadboard-driver/references/creating-beads.md` - May need updates
### Key Changes to Document
1. **Agent Types (was Archetypes)**
- 6 built-in: architect, engineer, reviewer, tester, investigator, shipper
- CRUD tools: `bb_list_agents`, `bb_create_agent`, etc.
- Each has capabilities that determine tool access
2. **Agent Instances**
- Numbered display names: "Engineer 01", "Engineer 02"
- Unique instance IDs: `{type}-{number}-{random}`
- Status panel shows active instances
3. **Templates**
- Named compositions: feature-dev, bug-fix, etc.
- Spawn via `bb_spawn_team(description)` or `bb_spawn_team(description, template)`
- Auto-select template from description keywords
4. **Worker Spawning**
- Natural language: `bb_spawn_worker(description: "Fix the login bug")`
- No task_id required - auto-generated from description
- Optional `bead_id` to assign to existing bead
5. **Orchestrator Decision Tree**
- Small task → spawn 1 agent
- Medium task → spawn 2-3 agents
- Large task → use template
### Scripts to Review
- `scripts/generate-agent-name.mjs` - May need update for new naming
- `scripts/session-preflight.mjs` - May reference old concepts
### Effort
~2-3 hours
---
## Suggested next build order
1. **Worker spawning tool + worker session model**
2. **Archetype-backed execution config**
3. **Template-first orchestration behavior**
4. **Activity panel integration for orchestrator/workers**
5. **Launch-anywhere UX completion**
6. **Runtime hardening + automated tests**
---
## Files most relevant to current Embedded Pi implementation
### Core runtime
- `src/lib/bb-daemon.ts`
- `src/lib/embedded-daemon.ts`
- `src/lib/pi-daemon-adapter.ts`
- `src/lib/pi-runtime-detection.ts`
- `src/lib/bb-pi-bootstrap.ts`
### TUI / shared Pi integration references
- `src/tui/bb-agent-tui.ts`
- `src/tui/system-prompt.ts`
- `src/tui/tools/bb-dolt-read.ts`
- `src/tui/tools/bb-deviation.ts`
- `src/tui/tools/bb-mailbox.ts`
- `src/tui/tools/bb-presence.ts`
- `src/tui/tools/bb-spawn-worker.ts`
- `src/tui/tools/bb-spawn-template.ts`
- `src/tui/tools/bb-worker-status.ts`
- `src/tui/tools/bb-worker-results.ts`
- `src/tui/tools/bb-bead-crud.ts`
- `src/tui/tools/bb-list-agents.ts`
- `src/tui/tools/bb-create-agent.ts`
- `src/tui/tools/bb-assign-agent.ts`
### Frontend surfaces
- `src/components/shared/orchestrator-panel.tsx`
- `src/components/shared/runtime-console.tsx`
- `src/components/shared/unified-shell.tsx`
- `src/components/shared/left-panel-new.tsx`
- `src/lib/orchestrator-chat.ts`
---
## Summary
**Phase 3 COMPLETE - Testing in progress.**
What is proven now:
- ✅ Embedded orchestrator runtime
- ✅ Frontend prompt path
- ✅ Realtime telemetry
- ✅ Left-panel orchestrator chat
- ✅ BeadBoard-aware tool execution
- ✅ Worker spawning with numbered instances
- ✅ Agent types with capabilities
- ✅ Template-based team spawning
- ✅ Bead-required workflow
- ✅ Async worker coordination
What remains:
- Phase 4: Launch-anywhere UX (spawn from task cards, graph nodes)
- Phase 5: Agent presence in social/graph views
- Phase 6: Runtime hardening
- Phase 7: Tests and verification
- Phase 8: Unified Settings
- Phase 9: Holistic skill update
Reference in a new issue View git blame Copy permalink