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()
This commit is contained in:
zenchantlive
parent
643fa299dd
commit
d335e5bf71
98 changed files with 17851 additions and 944 deletions
373
docs/plans/2026-03-05-embedded-pi-roadmap.md
Normal file
373
docs/plans/2026-03-05-embedded-pi-roadmap.md
Normal file
|
|
@ -0,0 +1,373 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue