boocode/openspec/changes/paseo-orchestrator/tasks.md

# Tasks — Paseo-like Orchestrator

## Phase 1: Trace System + Observability (5 tasks)

### 1. Create tool_traces DB table + migration
Add `tool_traces` table to `apps/server/src/schema.sql`:
- Columns: id (UUID PK), session_id (UUID FK → sessions), chat_id (UUID FK → chats), turn_number (int), tool_name (text), input (jsonb), output (jsonb), started_at (timestamptz), finished_at (timestamptz), latency_ms (int), tokens_used (int), cache_tokens (int), reasoning_tokens (int), error (text), outcome (text)
- Index on (chat_id, turn_number, started_at) for trace queries
- Index on (session_id) for session-level aggregation
- Applied idempotently via `applySchema()` — wrap in `CREATE TABLE IF NOT EXISTS`
**Verification**: `psql` shows `tool_traces` table with all columns and indexes. Schema re-run is no-op.

### 2. Add tool_trace WS frame + contracts schema
Add `tool_trace` frame to `WsFrameSchema` in `packages/contracts/src/ws-frames.ts`:
- Frame types: `tool_trace:start` (tool_name, input, started_at) and `tool_trace:complete` (tool_name, output, latency_ms, tokens_used, cache_tokens, reasoning_tokens, error)
- Add to `InferenceFrame` loose union in `apps/server/src/services/inference/turn.ts`
- Add to strict `WsFrame` discriminated union in `apps/web/src/api/types.ts`
- Rebuild contracts: `pnpm -C packages/contracts build`
**Verification**: tsc --noEmit passes. WS client receives `tool_trace:start` and `tool_trace:complete` frames.

### 3. Instrument tool-phase.ts with start/end timing
Update `apps/server/src/services/tools/tool-phase.ts`:
- Before `executeToolCall`: record `clock_timestamp()` as start, publish `tool_trace:start` frame with tool_name and input
- After `executeToolCall`: record `clock_timestamp()` as finish, compute latency_ms, extract token counts from response metadata, INSERT into `tool_traces` table, publish `tool_trace:complete` frame
- Handle errors: on thrown error, publish `tool_trace:complete` with error field set, set outcome='error'; on success, outcome='success'
- Use `sql.json(input as never)` for JSONB columns — no double-serialization
**Verification**: Every tool call produces a `tool_traces` row with correct latency_ms and outcome. WS client receives both start and complete frames.

### 4. Add GET /api/chats/:id/traces endpoint
Create `apps/server/src/routes/traces.ts`:
- `GET /api/chats/:id/traces` — paginated, ordered by (turn_number, started_at)
- Query params: `cursor` (opaque cursor for keyset pagination), `limit` (default 50, max 200), `turn_number` (optional filter to single turn)
- Returns `{traces: Trace[], next_cursor: string | null}`
- Register in Fastify router with `chatOwnershipPreHandler` guard
**Verification**: `curl /api/chats/:id/traces` returns paginated trace rows. Turn filter returns only matching traces.

### 5. Build trace viewer frontend component
Create `apps/web/src/components/TraceViewer.tsx` (and supporting files):
- Collapsible tree grouped by turn_number
- Per tool call row: tool_name badge, latency bar (relative bar width, color-coded: green <1s, yellow <5s, red ≥5s), token count, expand/collapse chevron
- Expanded view: tool input (JSON formatted), tool output (JSON formatted), error message if any
- Fetch traces from `/api/chats/:id/traces` on pane mount, paginate on scroll
- Integrate as a new pane option in the multi-pane workspace (existing pane registry)
**Verification**: Trace viewer loads, groups by turn, shows timing bars, expands/collapses tool calls. Pagination works for sessions with 50+ traces.

## Phase 2: Session Persistence + Resume (3 tasks)

### 6. Serialize agent state to DB on turn boundaries
Modify `apps/coder` agent dispatch:
- On each turn boundary (after LLM response, before next tool call loop), serialize `AgentSession` state to `agent_sessions` table
- Persist: provider config, turn history, pending tool calls, current phase, token budget remaining
- Use JSONB column for the snapshot state, `clock_timestamp()` for last_update
- Guard against rapid consecutive saves (debounce 200ms)
**Verification**: Agent session state is written to `agent_sessions` after each LLM turn. JSONB snapshot contains all fields needed for resume.

### 7. Restore state on WS reconnect
Update `apps/server/src/services/ws.ts`:
- On `snapshot` frame from a reconnecting client, check for `AgentSession` in `in_progress` or `awaiting_input` state
- If found, rehydrate the coder pane: restore provider config, replay pending tool calls, set turn history
- Publish a `session_restored` frame with the restored state metadata
- Client-side: `useSessionStream` handles `session_restored` by resetting pane state to match
**Verification**: Refresh browser mid-agent-session → after reconnect, the coder pane shows the same turn state, pending tool calls, and conversation history.

### 8. Agent session timeline view
Add timeline component to the coder pane:
- Horizontal timeline showing all turns in the current agent session
- Each turn entry: turn number, start time, tool call count, token usage, cache hit rate
- Active turn highlighted, past turns dimmed
- Clicking a past turn scrolls the conversation to that turn and collapses later turns
- Fetch turn metadata from existing session data (no new endpoint needed)
**Verification**: Timeline shows all turns. Clicking a turn scrolls to it. Active turn is highlighted.

## Phase 3: Dynamic Workflow Engine (6 tasks)

### 9. Create isolated-vm workflow sandbox
Create `apps/server/src/services/workflow/sandbox.ts`:
- Use `isolated-vm` npm package to create a V8 isolate for each workflow run
- No `require`, `fs`, `net`, `child_process` accessible in the sandbox
- Expose only the workflow API surface (`agent`, `parallel`, `pipeline`, `phase`, `budget`, `log`, `args`)
- Token budget enforcement: inject a step counter, throw when budget exceeded
- Timeout: 30s default, configurable per workflow
- Error boundary: caught exceptions produce structured error results instead of crashing the worker
- Add `isolated-vm` to `apps/server/package.json` dependencies
**Verification**: Workflow script that calls `agent()` runs without error. Script trying `require('fs')` throws a sandbox violation. Run exceeding budget is killed with a clear message.

### 10. Implement agent/parallel/pipeline primitives
Create `apps/server/src/services/workflow/api.ts`:
- `agent(id, { prompt, model?, tools?, budget? })` — registers a sub-agent. Returns an object with `.run(input)` that dispatches the agent through the existing agent dispatch system and returns result.
- `parallel([agents], { budget? })` — runs all agents concurrently. Returns when all complete (or any fails). Shared token budget across parallel agents. Uses `Promise.allSettled` for resilience.
- `pipeline([steps], { budget? })` — runs steps sequentially. Each step receives the previous step's output. Steps can be `agent()` results or inline functions.
- `phase(name, { agents, budget })` — groups agents under a named phase. Phases can have their own budget. Results are namespaced by phase name.
- `budget(limit)` — sets token or step limits. Returns a budget object consumed by agent/parallel/pipeline.
- `log(msg)` — emits a structured log entry tagged with current phase/agent context. Published as WS frame to the Orchestrator pane.
- `args` — the input arguments passed to `workflow.run(args)`.
**Verification**: A test workflow using `agent()`, `parallel()`, and `pipeline()` executes correctly. Logs appear in the output stream. Token budgets are enforced.

### 11. Workflow file discovery system
Create `apps/server/src/services/workflow/discovery.ts`:
- Scan `.boocode/workflows/*.js` (project root, relative to `PROJECT_ROOT_WHITELIST`)
- Scan `~/.boocode/workflows/*.js` (global, `os.homedir()`)
- Scan `data/workflows/` (built-in catalog)
- Each file must export a `workflow` object: `{name, description, run(args) => {...}}`
- Validate the workflow object at discovery time: required fields, run must be a function
- On server start, run full discovery. Cache results in a `Map<name, Workflow>`.
- Log discovered workflows with name + description at `info` level
**Verification**: Placing a valid `.boocode/workflows/test.js` file makes the workflow appear in `WorkflowManager.list()`. Invalid workflow files are logged as warnings and skipped.

### 12. Workflow manager + built-in catalog
Create `apps/server/src/services/workflow/manager.ts`:
- `WorkflowManager` singleton class:
  - `list()` — returns all discovered workflows with name, description, and arg schema
  - `get(name)` — returns a workflow by name
  - `run(workflow, args)` — creates a sandbox, injects args, executes `workflow.run()`. Returns a runId (UUID).
  - `cancel(runId)` — terminates the sandbox, marks run as cancelled
  - `status(runId)` — returns run status: `pending|running|completed|failed|cancelled`, with progress info
- Concurrency limit: configurable via `WORKFLOW_MAX_CONCURRENT` env var (default 3)
- Token budget: configurable via `WORKFLOW_DEFAULT_BUDGET` env var (default 100_000 tokens)
- Run state tracked in-memory with optional DB persistence

Built-in workflows in `data/workflows/`:
- `deep-research` — parallel source search → per-source analysis → synthesis report
- `multi-review` — run code health + security + standards reviews in parallel, merge findings
- `plan-verify` — generate implementation plan → verify plan → generate work items
- `bounty-hunt` — parallel vulnerability scans with different focus areas (injection, auth, crypto, business logic)
**Verification**: `list()` returns built-in workflows. `run()` executes a workflow and returns runId. `status()` reflects progress. `cancel()` stops execution cleanly.

### 13. Workflow resumability (hash-based cache)
Create `apps/server/src/services/workflow/cache.ts`:
- Compute SHA-256 hash of each agent spec: `crypto.createHash('sha256').update(JSON.stringify({prompt, options})).digest('hex')`
- Before executing an agent, check in-memory LRU cache for existing result matching the hash
- Hit: return cached result, emit `log('cached', agentId, hash)` — no actual dispatch
- Miss: execute agent, store result in cache keyed by hash
- LRU eviction: `WORKFLOW_CACHE_SIZE` env var (default 100 entries)
- Optional DB persistence: `workflow_cache` table with `hash`, `result`, `created_at` — cross-session reuse
- Re-run detection: identical workflow with same args → all agents skipped
- Partial re-run: changed args → only changed agents re-execute, unchanged ones read from cache
**Verification**: First run of a workflow executes all agents. Second run with identical args skips all agents (logs show 'cached'). Run with modified args for one agent only re-executes that agent.

### 14. Workflow UI integration with Orchestrator panel
Extend `apps/web/src/components/Orchestrator/`:
- Add workflow selector dropdown listing workflows from `WorkflowManager.list()`
- Add "Run Workflow" button that opens workflow args editor (JSON or form)
- Extend existing run pane to show workflow steps with per-agent progress
- Live log stream from workflow `log()` calls, displayed in a scrollable log view
- Cancel button for running workflows
- Resumability indicator: "3/5 steps cached — skipping" when hash cache hits
- Fetch workflow list via new API endpoint or WS message (add `GET /api/orchestrator/workflows`)
**Verification**: Workflow selector lists built-in workflows. Running a workflow shows step-by-step progress in the run pane. Cancelling a running workflow works. Cached steps show "skipped" indicator.

## Phase 4: Background Subagents (3 tasks)

### 15. Background task queue + spawn_subagent tool
Modify `apps/coder/` and `apps/server/`:
- Extend `tasks` table usage with a new task type marker for background subagent tasks
- Create `spawn_subagent` tool in `apps/server/src/services/tools/`:
  - Schema: `{prompt, model?, tools?, budget?, metadata?}`
  - Creates a `tasks` row with state=`pending`, type=`background_subagent`
  - Returns `{task_id, status: 'pending'}` immediately — does NOT block
- Background worker loop: polls `tasks` table for `background_subagent` tasks in `pending` state, picks one up, executes it via existing agent dispatch, writes result back to tasks row on completion
- Max concurrency: `BACKGROUND_MAX_CONCURRENT` env var (default 2)
- Worker polls interval: 1s (configurable)
**Verification**: Calling `spawn_subagent` returns immediately with a task_id. The task eventually completes with a result in the tasks table. Multiple background tasks run concurrently up to the concurrency limit.

### 16. subagent_status + subagent_result tools
Create two tools in `apps/server/src/services/tools/`:
- `subagent_status(task_id)`:
  - Schema: `{task_id}`
  - Returns: `{task_id, status: 'pending'|'running'|'completed'|'failed', progress?: string, started_at?, finished_at?}`
  - Queries `tasks` table for the status
- `subagent_result(task_id)`:
  - Schema: `{task_id}`
  - Returns: `{task_id, status, result?: json, error?: string}`
  - Only returns result when status='completed'; returns empty result otherwise with a message
  - Updates task state to `read` on successful result retrieval (optional)
**Verification**: Calling `subagent_status` on a running task returns 'running'. Calling `subagent_result` on a completed task returns the full result. Calling `subagent_result` on a pending task returns a clear "not ready yet" message.

### 17. Background agent pane
Create `apps/web/src/components/BackgroundAgentPane.tsx`:
- New pane type showing running, completed, and failed background subagents
- Each entry: agent name/description, status badge, duration (elapsed or total), progress indicator
- Running entries: progress bar (if available), cancel button
- Completed entries: "View Result" action that opens a modal or inline view with the full output
- Failed entries: error message, "Retry" action
- Badge counter on pane tab showing number of running tasks
- Poll status every 2s for running entries, stop polling on completion
- Register in pane registry alongside existing pane types
**Verification**: Background pane shows spawning tasks as "pending", transitioning to "running", then "completed"/"failed". "View Result" shows the full output. Badge counter reflects active running tasks.

## Phase 5: Multi-modal + Cache Shape (4 tasks)

### 18. Multi-modal attachment pipeline
Add file upload support:
- Accept file uploads via drag-drop or file picker in the message input area
- Store uploaded files on tmpfs (`/tmp/boocode-uploads/` by default, configurable via `UPLOAD_DIR`)
- Reference attachments in message row via `message_parts` with `type='image'` and a `url` pointing to the tmpfs path
- Forward to DeepSeek API: encode image as base64 data URI, send as multimodal content part in the user message
- Supported formats: png, jpg, jpeg, gif, webp
- Size limit: 20MB default, configurable via `MAX_ATTACHMENT_SIZE_MB` env var
- Server-side cleanup: delete tmpfs files after message is fully processed or on a periodic sweep
**Verification**: Uploading an image creates a file on tmpfs and a referenced `message_parts` row. DeepSeek API call includes the image as a base64 content part. Error on files over size limit.

### 19. Image render in message bubble
Update message rendering in `apps/web/src/components/MessageBubble.tsx`:
- Detect `message_parts` with `type='image'` in the message content
- Render attached images inline in the chat bubble, below the text content
- Thumbnail: max 300px wide, aspect-ratio preserved, rounded corners
- Lightbox: clicking the thumbnail opens a full-size overlay with close button
- Loading state: skeleton placeholder while image loads from tmpfs URL
- Error state: broken image placeholder with retry option
- Clean layout: images displayed in a grid (1-2 columns depending on count)
**Verification**: Chat messages with image attachments render inline thumbnails. Clicking opens lightbox. Large images are thumbnailed. Broken images show error state.

### 20. Cache shape telemetry data pipeline
Extract and store cache metrics:
- In the DeepSeek provider response handler, extract `prompt_cache_hit_tokens` and `prompt_cache_miss_tokens` from the API response metadata
- Break down cache segments: system prompt tokens, tool schema tokens, conversation history tokens (approximate by measuring each segment length)
- Store cache metrics in `tool_traces.cache_tokens` column (already created in Phase 1)
- Optionally create a `cache_stats` table for per-segment breakdown: `{turn_id, segment_name, hit_tokens, miss_tokens}`
- Expose via existing traces API (cache fields already part of the Trace schema)
**Verification**: After a DeepSeek call, `tool_traces` row has `cache_tokens` populated. Cache segment breakdown is available when querying traces.

### 21. Cache shape visualization in trace viewer
Update the TraceViewer component with cache metrics:
- Per-turn cache hit bar: horizontal stacked bar showing cached (green) vs non-cached (gray) tokens
- Hit rate percentage displayed as a badge next to token count
- Cumulative cache hit rate in the session footer: "Cache hit rate: 67% (45K/67K tokens)"
- Color coding: green ≥60%, yellow 30-59%, red <30%
- Tooltip on hover showing segment breakdown if available
- Animate transitions when new trace data arrives
**Verification**: Trace viewer shows cache hit/miss bars per turn. Cumulative rate in footer updates as new traces load. Color coding matches thresholds.