a6371e156a
Enables parallel agents to communicate through a CLI-based conversation mechanism coordinated via tRPC. Agents can ask questions to peers and receive answers, with target resolution by agent ID, task ID, or phase ID.
230 lines
9.7 KiB
Markdown
230 lines
9.7 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 from DB log chunks |
|
|
| getActiveRefineAgent | query | Active refine agent for initiative |
|
|
| listWaitingAgents | query | Agents waiting for input |
|
|
| onAgentOutput | subscription | Live raw JSONL output stream via EventBus |
|
|
|
|
### 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 branch/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 initiative context (phases, execution tasks only, pages) |
|
|
| spawnArchitectRefine | mutation | Refine agent (generates proposals) |
|
|
| spawnArchitectDetail | mutation | Detail agent (generates tasks). Passes initiative context (phases, execution tasks only, 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. Validates defaultBranch exists in repo |
|
|
| listProjects | query | All projects |
|
|
| getProject | query | Single project |
|
|
| updateProject | mutation | Update project settings (defaultBranch). Validates branch exists in repo |
|
|
| 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`
|
|
|
|
## Preview Procedures
|
|
|
|
Docker-based preview deployments. No database table — Docker is the source of truth.
|
|
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `startPreview` | mutation | Start preview: `{initiativeId, phaseId?, projectId, branch}` → PreviewStatus |
|
|
| `stopPreview` | mutation | Stop preview: `{previewId}` |
|
|
| `listPreviews` | query | List active previews: `{initiativeId?}` → PreviewStatus[] |
|
|
| `getPreviewStatus` | query | Get preview status: `{previewId}` → PreviewStatus |
|
|
|
|
Context dependency: `requirePreviewManager(ctx)` — requires `PreviewManager` from container.
|
|
|
|
## Conversation Procedures
|
|
|
|
Inter-agent communication for parallel agents.
|
|
|
|
| Procedure | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `createConversation` | mutation | Ask a question: `{fromAgentId, toAgentId?, phaseId?, taskId?, question}` → Conversation |
|
|
| `getPendingConversations` | query | Poll for incoming questions: `{agentId}` → Conversation[] |
|
|
| `getConversation` | query | Get conversation by ID: `{id}` → Conversation |
|
|
| `answerConversation` | mutation | Answer a conversation: `{id, answer}` → Conversation |
|
|
|
|
Target resolution: `toAgentId` → direct; `taskId` → find running agent by task; `phaseId` → find running agent by any task in phase.
|
|
|
|
Context dependency: `requireConversationRepository(ctx)`, `requireAgentManager(ctx)`.
|