0407f05332
Full rename across the codebase for clarity: - breakdown (initiative→phases) is now "plan" - decompose (phase→tasks) is now "detail" Updates schema enums, TypeScript types, events, prompts, output handler, tRPC procedures, CLI commands, frontend components, tests, and docs. Also fixes 0022 migration multi-statement issue (adds statement-breakpoint markers).
201 lines
8.1 KiB
Markdown
201 lines
8.1 KiB
Markdown
# Server & API Module
|
|
|
|
`src/server/` — HTTP server, `src/trpc/` — tRPC procedures, `src/coordination/` — merge queue.
|
|
|
|
## HTTP Server
|
|
|
|
**Framework**: Native `node:http` (no Express/Fastify)
|
|
**Default**: `127.0.0.1:3847`
|
|
**PID file**: `~/.cw/server.pid`
|
|
|
|
### Routes
|
|
|
|
| Route | Method | Purpose |
|
|
|-------|--------|---------|
|
|
| `/health` | GET | Health check (`{ status, uptime, processCount }`) |
|
|
| `/status` | GET | Full server status with process list |
|
|
| `/trpc/*` | POST | All tRPC procedure calls |
|
|
|
|
### Lifecycle
|
|
- `CoordinationServer.start()` — checks PID file, creates HTTP server, emits `server:started`
|
|
- `CoordinationServer.stop()` — emits `server:stopped`, closes server, removes PID file
|
|
- `GracefulShutdown` handles SIGTERM/SIGINT/SIGHUP with 10s timeout
|
|
|
|
### tRPC Adapter
|
|
`trpc-adapter.ts` converts `node:http` IncomingMessage/ServerResponse to fetch Request/Response for tRPC. Subscriptions stream via ReadableStream bodies (SSE).
|
|
|
|
## tRPC Context
|
|
|
|
All procedures share a context with optional dependencies:
|
|
|
|
```typescript
|
|
interface TRPCContext {
|
|
eventBus: EventBus // always present
|
|
serverStartedAt: Date | null
|
|
processCount: number
|
|
agentManager?: AgentManager // optional
|
|
taskRepository?: TaskRepository
|
|
// ... all 10 repositories, 3 managers, credentialManager, workspaceRoot
|
|
}
|
|
```
|
|
|
|
Each procedure uses `require*Repository(ctx)` helpers that throw `TRPCError(INTERNAL_SERVER_ERROR)` if a dependency is missing.
|
|
|
|
## Procedure Reference
|
|
|
|
### System
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| health | query | Health check with uptime |
|
|
| status | query | Server status with process list |
|
|
| systemHealthCheck | query | Account, agent, project health |
|
|
|
|
### Agents
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| spawnAgent | mutation | Spawn new agent (taskId, prompt, provider, mode) |
|
|
| stopAgent | mutation | Stop agent by name or ID |
|
|
| deleteAgent | mutation | Delete agent and clean up worktree |
|
|
| dismissAgent | mutation | Dismiss agent (set userDismissedAt) |
|
|
| resumeAgent | mutation | Resume with answers |
|
|
| listAgents | query | All agents |
|
|
| getAgent | query | Single agent by name or ID |
|
|
| getAgentResult | query | Execution result |
|
|
| getAgentQuestions | query | Pending questions |
|
|
| getAgentOutput | query | Full output (DB chunks or file fallback) |
|
|
| getActiveRefineAgent | query | Active refine agent for initiative |
|
|
| listWaitingAgents | query | Agents waiting for input |
|
|
| onAgentOutput | subscription | Live output stream + buffered history |
|
|
|
|
### Tasks
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| listTasks | query | Child tasks of parent |
|
|
| getTask | query | Single task |
|
|
| updateTaskStatus | mutation | Change task status |
|
|
| createInitiativeTask | mutation | Create task on initiative |
|
|
| createPhaseTask | mutation | Create task on phase |
|
|
| listInitiativeTasks | query | All tasks for initiative |
|
|
| listPhaseTasks | query | All tasks for phase |
|
|
| listPendingApprovals | query | Tasks with status=pending_approval |
|
|
| approveTask | mutation | Approve and complete task |
|
|
|
|
### Initiatives
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| createInitiative | mutation | Create with optional projectIds, auto-creates root page |
|
|
| listInitiatives | query | Filter by status |
|
|
| getInitiative | query | With projects array |
|
|
| updateInitiative | mutation | Name, status |
|
|
| updateInitiativeConfig | mutation | mergeRequiresApproval, executionMode |
|
|
|
|
### Phases
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| createPhase | mutation | Create in initiative |
|
|
| listPhases | query | By initiative |
|
|
| getPhase | query | Single phase |
|
|
| updatePhase | mutation | Name, content, status |
|
|
| approvePhase | mutation | Validate and approve |
|
|
| deletePhase | mutation | Cascade delete |
|
|
| createPhasesFromPlan | mutation | Bulk create from agent output |
|
|
| createPhaseDependency | mutation | Add dependency edge |
|
|
| removePhaseDependency | mutation | Remove dependency edge |
|
|
| listInitiativePhaseDependencies | query | All dependency edges |
|
|
| getPhaseDependencies | query | What this phase depends on |
|
|
| getPhaseDependents | query | What depends on this phase |
|
|
|
|
### Phase Dispatch
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| queuePhase | mutation | Queue approved phase |
|
|
| dispatchNextPhase | mutation | Start next ready phase |
|
|
| getPhaseQueueState | query | Queue state |
|
|
| createChildTasks | mutation | Create tasks from detail parent |
|
|
|
|
### Architect (High-Level Agent Spawning)
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| spawnArchitectDiscuss | mutation | Discussion agent |
|
|
| spawnArchitectPlan | mutation | Plan agent (generates phases). Passes full initiative context (existing phases, tasks, pages) |
|
|
| spawnArchitectRefine | mutation | Refine agent (generates proposals) |
|
|
| spawnArchitectDetail | mutation | Detail agent (generates tasks). Passes full initiative context (sibling phases, tasks, pages) |
|
|
|
|
### Dispatch
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| queueTask | mutation | Add task to dispatch queue |
|
|
| dispatchNext | mutation | Dispatch next ready task |
|
|
| getQueueState | query | Queue state |
|
|
| completeTask | mutation | Complete with approval check |
|
|
|
|
### Coordination (Merge Queue)
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| queueMerge | mutation | Queue task for merge |
|
|
| processMerges | mutation | Process merge queue |
|
|
| getMergeQueueStatus | query | Queue state |
|
|
| getNextMergeable | query | Next ready-to-merge task |
|
|
|
|
### Projects
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| registerProject | mutation | Clone git repo, create record |
|
|
| listProjects | query | All projects |
|
|
| getProject | query | Single project |
|
|
| deleteProject | mutation | Delete clone and record |
|
|
| getInitiativeProjects | query | Projects for initiative |
|
|
| updateInitiativeProjects | mutation | Sync junction table |
|
|
|
|
### Pages
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| getRootPage | query | Auto-creates if missing |
|
|
| getPage | query | Single page |
|
|
| getPageUpdatedAtMap | query | Bulk updatedAt check |
|
|
| listPages | query | By initiative |
|
|
| listChildPages | query | By parent page |
|
|
| createPage | mutation | Create, emit page:created |
|
|
| updatePage | mutation | Title/content/sortOrder, emit page:updated |
|
|
| deletePage | mutation | Delete, emit page:deleted |
|
|
|
|
### Accounts
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| listAccounts | query | All accounts |
|
|
| addAccount | mutation | Create account |
|
|
| removeAccount | mutation | Delete account |
|
|
| refreshAccounts | mutation | Clear expired exhaustion |
|
|
| updateAccountAuth | mutation | Update credentials |
|
|
| markAccountExhausted | mutation | Set exhaustion timer |
|
|
| listProviderNames | query | Available provider names |
|
|
|
|
### Proposals
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| listProposals | query | By agent or initiative |
|
|
| acceptProposal | mutation | Apply side effects, auto-dismiss agent |
|
|
| dismissProposal | mutation | Dismiss, auto-dismiss agent |
|
|
| acceptAllProposals | mutation | Bulk accept with error collection |
|
|
| dismissAllProposals | mutation | Bulk dismiss |
|
|
|
|
### Subscriptions (SSE)
|
|
| Procedure | Type | Events |
|
|
|-----------|------|--------|
|
|
| onEvent | subscription | All 30+ event types |
|
|
| onAgentUpdate | subscription | agent:* events (8 types) |
|
|
| onTaskUpdate | subscription | task:* + phase:* events (8 types) |
|
|
| onPageUpdate | subscription | page:created/updated/deleted |
|
|
|
|
Subscriptions use `eventBusIterable()` — queue-based async generator, max 1000 events, 30s heartbeat.
|
|
|
|
## Coordination Module
|
|
|
|
`src/coordination/` manages merge queue:
|
|
|
|
- **CoordinationManager** port: `queueMerge`, `getNextMergeable`, `processMerges`, `handleConflict`, `getQueueState`
|
|
- **DefaultCoordinationManager** adapter: in-memory queue, dependency-ordered processing
|
|
- **ConflictResolutionService**: creates resolution tasks for merge conflicts
|
|
- Merge flow: queue → check deps → merge via WorktreeManager → handle conflicts
|
|
- Events: `merge:queued`, `merge:started`, `merge:completed`, `merge:conflicted`
|