correx/apps/server/AGENTS.md

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 accepts an optional intent brief, parity with the WS StartSession)
• 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)
• GET /metrics/tool-reliability — per-model tool-call validity across the event log (ToolReliabilityInspectionService); groundwork for capability-aware routing
• Optional [git] transport creates run/<sessionId> from a server-local checkout and pushes it at terminal state; clients review with ordinary Git and never supply a remote URL as cwd.
• Repo-map L3 embeddings use bounded, recorded source descriptors (module/package, imports, leading purpose comment, symbols); raw file bodies are never embedded. Their versioned repomap:v2 namespace forces a one-time re-embed when the semantic document format changes.
• At boot, tools.workspace_root is the authoritative default tool jail. Every session records its own resolved workspace binding; repo maps, project memory, profile/instruction snapshots, and git run branches use that binding and skip unbound sessions. [project] never supplies a workspace root.

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).