# 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