indifferentketchup
abe9c5a3a8
Phase 1: Trace System + Observability - tool_traces DB table + insert/update service - tool_trace_start/tool_trace_finish WS frames (contracts + FE types) - Instrumented tool-phase.ts with timing around every tool call - GET /api/chats/:id/traces paginated endpoint - Trace viewer frontend (collapsible panel with timing bars + token breakdown) Phase 2: Session Persistence + Resume - agent_snapshots table (UPSERT per chat, persisted on turn boundaries) - save/load/delete service functions - Agent snapshot sent on WS reconnect - Session timeline view (vertical timeline with scroll-to + restore) Tooling: - run_command tool (execFile, 30s timeout, 32KB cap, path-guarded) - Auto-fix loop: after write tools, runs pnpm build, injects errors into next turn
240 lines
8.5 KiB
Markdown
240 lines
8.5 KiB
Markdown
# Paseo-like Orchestrator — Implementation Plan
|
|
|
|
> **Goal:** Transform BooCode into a Paseo-style thin-client orchestration layer with observability, dynamic workflows, resumability, background subagents, multi-modal, and cache shape telemetry.
|
|
>
|
|
> **Architecture:** Durable agent execution engine beneath thin chat/coder frontends. Trace system as foundation, workflow engine as the structural addition, everything else layered on top.
|
|
>
|
|
> **Inspired by:** Paseo (agent lifecycle, worktree isolation), Whale (workflow engine, cache telemetry), OpenCode (session resume), Claude Code (workflow script format).
|
|
|
|
---
|
|
|
|
## TL;DR
|
|
|
|
> **Quick Summary**: Build a durable orchestration layer with trace observability, dynamic JS workflows, session persistence, background subagents, and multi-modal support over 5 phases.
|
|
>
|
|
> **Deliverables**:
|
|
> - Trace system with DB persistence + viewer UI
|
|
> - Dynamic workflow engine (JS sandbox, agent/parallel/pipeline)
|
|
> - Workflow resumability (hash-based step caching)
|
|
> - Background subagent runtime
|
|
> - Session persistence across refreshes
|
|
> - Cache shape telemetry (DeepSeek KV cache viz)
|
|
> - Multi-modal attachment support
|
|
>
|
|
> **Estimated Effort**: XL — 5 phases, ~2-3 weeks total
|
|
> **Parallel Execution**: YES — phases 1-2 can partially overlap
|
|
> **Critical Path**: Trace system → Workflow engine → All downstream features
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
### Original Request
|
|
User wants BooCode to become "like Paseo — a thin client" with observability, dynamic workflows, session persistence, background agents, multi-modal, cache shape telemetry, and workflow resumability. They invoked skills across model evaluation, long context, SGLang, LangChain, LangSmith, agentic eval, agent harness construction, agent governance, and chat SDKs — indicating broad ambition for a production-quality AI coding platform.
|
|
|
|
### Key Decisions
|
|
- **Trace system first**: Foundation for all debugging and optimization
|
|
- **isolated-vm for workflow sandbox**: Node-native, no external deps
|
|
- **DB-backed sessions**: Postgres for trace store + session state
|
|
- **Existing WS frames + new `tool_trace` frame**: Live streaming to frontend
|
|
- **Phase ordering**: Foundation (trace) → UX (persistence) → Power (workflows) → Polish (background/multi-modal/cache)
|
|
|
|
---
|
|
|
|
## Phases
|
|
|
|
### Phase 1: Trace System + Observability
|
|
**Est. effort**: 3-4 days
|
|
|
|
Core observability infrastructure. Every tool call gets timed, logged, and persisted.
|
|
|
|
**Deliverables**:
|
|
- `tool_traces` DB table (id, session_id, chat_id, turn_number, tool_name, input, output, started_at, finished_at, latency_ms, tokens_used, cache_tokens, reasoning_tokens, error, outcome)
|
|
- Instrumentation in `tool-phase.ts` wrapping `executeToolCall` with start/end timing
|
|
- `tool_trace` WS frame type for live streaming to frontend
|
|
- GET `/api/chats/:id/traces` endpoint (paginated)
|
|
- Trace viewer pane (collapsible tree, timing bars, expand/collapse per call)
|
|
|
|
**Files to create**: 5-7 files across server + web + contracts
|
|
**Dependencies**: None — standalone feature
|
|
|
|
---
|
|
|
|
### Phase 2: Session Persistence + Resume
|
|
**Est. effort**: 2-3 days
|
|
|
|
Agent state survives browser refresh. Active sessions can be resumed.
|
|
|
|
**Deliverables**:
|
|
- Serialize active agent state to DB on each turn boundary
|
|
- Restore state on WS reconnect (existing `snapshot` frame enhanced)
|
|
- Agent session timeline view (history of all turns in a session)
|
|
- Coder pane rehydrates from persisted state
|
|
|
|
**Files to modify**: ws.ts, useSessionStream.ts, session store, dispatcher
|
|
**Dependencies**: None — standalone, but benefits from Phase 1 trace data
|
|
|
|
---
|
|
|
|
### Phase 3: Dynamic Workflow Engine
|
|
**Est. effort**: 5-7 days
|
|
|
|
JS sandbox for multi-agent orchestration. Claude Code compatible.
|
|
|
|
**Deliverables**:
|
|
- `isolated-vm` sandbox (or Node `vm` module with restricted context)
|
|
- Workflow API: `agent()`, `parallel()`, `pipeline()`, `phase()`, `budget()`, `log()`, `args`
|
|
- Workflow file discovery (`.boocode/workflows/*.js` → project, `~/.boocode/workflows/*.js` → global)
|
|
- Built-in workflow catalog (deep-research, multi-review, etc.)
|
|
- Workflow manager with concurrency limits, token budgets
|
|
- Integration with existing Orchestrator panel for UI
|
|
|
|
**Files to create**: 10-15 files (workflow runtime, scheduler, tool bridge, manager, catalog)
|
|
**Dependencies**: Phase 1 traces feed into workflow observability
|
|
|
|
**Workflow Resumability** (within Phase 3):
|
|
- SHA-256 hash of agent spec (prompt + options)
|
|
- Cache completed results by hash
|
|
- On re-run, skip cached agents, only execute new/changed ones
|
|
- In-memory cache for current session, optional DB persistence
|
|
|
|
**Est. effort**: 1-2 days within Phase 3
|
|
|
|
---
|
|
|
|
### Phase 4: Background Subagents
|
|
**Est. effort**: 2-3 days
|
|
|
|
Non-blocking subagent execution. `spawn_subagent` returns immediately, results collected later.
|
|
|
|
**Deliverables**:
|
|
- Background task queue (reuses existing `tasks` table)
|
|
- `spawn_subagent` tool that creates a task and returns immediately
|
|
- `subagent_status` tool to poll completion
|
|
- `subagent_result` tool to retrieve output
|
|
- Background agent pane showing running/completed subagents
|
|
- Notifications via hooks when background tasks complete
|
|
|
|
**Files to create**: 3-5 files across server + web
|
|
**Dependencies**: Phase 1 traces, Phase 2 session persistence
|
|
|
|
---
|
|
|
|
### Phase 5: Multi-modal + Cache Shape (Polish)
|
|
**Est. effort**: 2-3 days
|
|
|
|
Image/file attachment support + DeepSeek cache hit visualization.
|
|
|
|
**Deliverables (Multi-modal)**:
|
|
- Image/file attachment storage (tmpfs, referenced in message)
|
|
- Forward image content through DeepSeek API's multimodal support
|
|
- Render attached images in message bubble
|
|
- Model can "see" screenshots, diagrams, UI mocks
|
|
|
|
**Deliverables (Cache Shape)**:
|
|
- Extract `prompt_cache_hit_tokens` from DeepSeek provider metadata
|
|
- Build cache segment visualization (system prompt, tool schema, conversation)
|
|
- Per-turn cache hit rate in trace viewer
|
|
- Cumulative cache stats in session view
|
|
|
|
**Files to create**: 3-5 files
|
|
**Dependencies**: Phase 1 traces (for cache shape), existing DeepSeek integration
|
|
|
|
---
|
|
|
|
## Execution Strategy
|
|
|
|
### Parallel Execution Waves
|
|
|
|
```
|
|
Wave 1 (Start Immediately):
|
|
├── Phase 1: Trace system backend (tool_traces table + instrumentation) [deep]
|
|
├── Phase 1: Trace viewer frontend [visual-engineering]
|
|
└── Phase 2: Session persistence backbone [deep]
|
|
|
|
Wave 2 (After Wave 1):
|
|
├── Phase 3: Workflow engine sandbox + API surface [deep]
|
|
├── Phase 3: Workflow file discovery + manager [unspecified-high]
|
|
├── Phase 3: Workflow resumability cache [quick]
|
|
└── Phase 4: Background subagent queue + tools [unspecified-high]
|
|
|
|
Wave 3 (After Wave 2):
|
|
├── Phase 4: Background agent pane + notifications [visual-engineering]
|
|
├── Phase 5: Multi-modal attachment pipeline [deep]
|
|
└── Phase 5: Cache shape telemetry UI [visual-engineering]
|
|
|
|
Wave FINAL:
|
|
├── F1: Plan compliance audit (oracle)
|
|
├── F2: Code quality review (unspecified-high)
|
|
├── F3: Integration QA (unspecified-high)
|
|
└── F4: Scope fidelity check (deep)
|
|
```
|
|
|
|
---
|
|
|
|
## TODOs
|
|
|
|
> Phase 1: Trace System + Observability
|
|
|
|
- [ ] 1. Create tool_traces DB table + migration
|
|
|
|
- [ ] 2. Add tool_trace WS frame + contracts schema
|
|
|
|
- [ ] 3. Instrument tool-phase.ts with start/end timing
|
|
|
|
- [ ] 4. Add GET /api/chats/:id/traces endpoint
|
|
|
|
- [ ] 5. Build trace viewer frontend component
|
|
|
|
> Phase 2: Session Persistence + Resume
|
|
|
|
- [ ] 6. Serialize agent state to DB on turn boundaries
|
|
|
|
- [ ] 7. Restore state on WS reconnect
|
|
|
|
- [ ] 8. Agent session timeline view
|
|
|
|
> Phase 3: Dynamic Workflow Engine
|
|
|
|
- [ ] 9. Create isolated-vm workflow sandbox
|
|
|
|
- [ ] 10. Implement agent/parallel/pipeline primitives
|
|
|
|
- [ ] 11. Workflow file discovery system
|
|
|
|
- [ ] 12. Workflow manager + built-in catalog
|
|
|
|
- [ ] 13. Workflow resumability (hash-based cache)
|
|
|
|
- [ ] 14. Workflow UI integration with Orchestrator panel
|
|
|
|
> Phase 4: Background Subagents
|
|
|
|
- [ ] 15. Background task queue + spawn_subagent tool
|
|
|
|
- [ ] 16. subagent_status + subagent_result tools
|
|
|
|
- [ ] 17. Background agent pane
|
|
|
|
> Phase 5: Multi-modal + Cache Shape
|
|
|
|
- [ ] 18. Multi-modal attachment pipeline
|
|
|
|
- [ ] 19. Image render in message bubble
|
|
|
|
- [ ] 20. Cache shape telemetry data pipeline
|
|
|
|
- [ ] 21. Cache shape visualization in trace viewer
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
- Tool trace viewer shows every call with timing bars and token costs
|
|
- Browser refresh preserves agent session state
|
|
- Workflow scripts run in isolated sandbox with agent/parallel/pipeline
|
|
- Re-running a workflow skips cached agents (hash-based)
|
|
- Background subagents run independently, results collected later
|
|
- Model can see attached images in chat
|
|
- Cache hit rate visible per-turn and cumulative
|