# apps/server

## Purpose

Ktor HTTP + WebSocket server. Exposes the orchestration kernel to CLI and TUI clients, manages session lifecycle, and streams events over WebSocket.

## Ownership

All sources under `apps/server/src/`.

## Local Contracts

### HTTP REST routes
- `GET/POST /sessions` — session browse and start
- `POST /sessions/{id}/resume` — resume a session after restart
- `GET/POST /tasks` — task listing and management
- `GET/POST /providers` — provider configuration
- `GET/POST /workflows` — workflow management
- `GET /health` — health report (probes: event-store, llama-server, disk watermark)
- `GET /stats` — metrics report (MetricsProjection)

### WebSocket protocol (`/ws`)
- **ServerMessage** (server → client): sealed hierarchy — `SessionMessage` (event-derived, carries `sequence` + `sessionSequence`) and `NonEventMessage` (control/infra). Variants include session lifecycle, approval requests, clarification requests, narration, proposed workflows, health/metrics pushes.
- **ClientMessage** (client → server): `StartSession`, `ApproveToolCall`, `RejectToolCall`, `GrantApproval`, `AnswerClarification`, `SetChatMode`, and others.
- All protocol types are in `protocol/` (Dtos.kt, ServerMessage.kt, ClientMessage.kt, ProtocolSerializer.kt).

### Health monitoring
- `HealthMonitor` runs probes on a schedule; results folded via `HealthProjection` into `HealthState`.
- Adding a probe: implement `HealthProbe`, register in `ServerModule`.

## Work Guidance

- Follow Kotlin rules in root CLAUDE.md.
- Route handlers must not contain domain logic — delegate to core services injected via `ServerModule`.
- New WS message variants require updating both `ServerMessage`/`ClientMessage` sealed classes and `ProtocolSerializer`.

## Verification

```
./gradlew :apps:server:test --rerun-tasks
```

## Child DOX Index

No child AGENTS.md (leaf module).