HITL Service

Port 4006. Manages operator oversight of AI agent conversations.

Endpoints

Route	Method	Purpose
`/health`	GET	Health check
`/hitl/escalations`	POST	Create escalation
`/hitl/escalations`	GET	List escalations (filter: status, mine)
`/hitl/escalations/:id`	GET	Get escalation + notes
`/hitl/escalations/:id/claim`	POST	Claim from queue
`/hitl/escalations/:id/respond`	POST	Send operator message
`/hitl/escalations/:id/handback`	POST	Hand back to AI
`/hitl/escalations/:id/close`	POST	Close escalation
`/hitl/escalations/:id/notes`	POST	Add internal note
`/hitl/approvals`	GET	List approvals (filter: status). Returns `id`, `conversationId`, `botId`, `botName`, `userMessage`, `originalResponse`, `status`, `createdAt`
`/hitl/approvals/:id/approve`	POST	Approve response as-is. Publishes approved response to Redis, records billing, broadcasts WS `approval.resolved`
`/hitl/approvals/:id/edit`	POST	Edit and approve response. Publishes edited response to Redis with `wasEdited: true`, sets status to `edited`, records billing, broadcasts WS `approval.resolved` with `status: "edited"`
`/hitl/approvals/:id/reject`	POST	Reject with reason. Publishes rejection to Redis, broadcasts WS `approval.resolved` with `status: "rejected"`
`/hitl/operators`	GET	List org operators
`/hitl/operators/me`	GET	Current operator session
`/hitl/operators/status`	PUT	Update operator status
`/hitl/operators/schedule`	PUT	Update working hours
`/hitl/operators/heartbeat`	POST	Heartbeat + Redis refresh
`/hitl/operators/availability`	GET	Check operator availability
`/hitl/ws`	WS	WebSocket for real-time operator feed

Architecture

Redis Pub/Sub Channels

Channel Pattern	Direction	Purpose
`hitl:escalation:{orgId}`	Bot → HITL	Escalation requests
`hitl:approval:{orgId}`	Bot → HITL	Approval requests
`hitl:message:{conversationId}`	HITL → Bot	Operator messages to end users
`hitl:user_message:{conversationId}`	Bot → HITL	User messages to operators
`hitl:resolution:{botId}`	HITL → Bot	Handback/close/expire events
`hitl:approved:{conversationId}`	HITL → Bot	Approval results (approved/rejected)
`hitl:escalation_result:{conversationId}`	HITL → Bot	Assignment result for synchronous flow

WebSocket Events

All WS broadcasts use the event key (not type).

Event	Direction	Purpose
`escalation.created`	Server → Client	New escalation
`escalation.claimed`	Server → Client	Operator claimed
`escalation.resolved`	Server → Client	Handback/close/expire
`escalation.assigned`	Server → Client	Auto-assigned from queue
`approval.created`	Server → Client	New approval request. Payload: `id`, `approvalId`, `conversationId`, `botId`, `botName`, `originalResponse`, `userMessage`, `status`, `createdAt`
`approval.resolved`	Server → Client	Approval processed. Payload: `approvalId`, `conversationId`, `status` (`approved`/`edited`/`rejected`), `reviewedBy`
`presence.update`	Server → Client	Operator online/offline
`escalation.claim`	Client → Server	Claim an escalation
`conversation.respond`	Client → Server	Send message to user
`escalation.handback`	Client → Server	Hand back to AI
`escalation.close`	Client → Server	Close escalation
`operator.availability`	Client → Server	Update status

Key Services

Service	Purpose
`orchestrator.service.ts`	Core routing brain — handles escalation/approval events, claim/handback/close, timeout checker, queue drain
`assignment.service.ts`	Finds available operators (round-robin by load, agent scope, working hours)
`notification.service.ts`	Dispatches alerts to email/Slack/Discord/webhook channels
`schedule.service.ts`	Timezone-aware working hours check
`redis.service.ts`	Pub/sub + operator presence tracking

Database Tables

escalation_requests — Escalation lifecycle (7 statuses: pending → queued → assigned → active → resolved/expired)
operator_sessions — Operator availability, load, agent scope, working hours
escalation_events — Append-only audit log
approval_queue — Response approval workflow. original_response stores the AI-generated text; edited_response stores operator edits; metadata JSONB stores endUserMessage (the user’s message that triggered the response). Bot name is resolved at query time via LEFT JOIN bots ON bots.id = approval_queue.bot_id
notification_channels — Multi-channel notification config
escalation_notes — Internal operator notes

Concurrency

All claim and approval operations use atomic UPDATE ... WHERE status IN (...) RETURNING * to prevent TOCTOU race conditions. If two operators claim simultaneously, only one succeeds.

Bot Service Integration

The bot service connects via hitl-bridge.service.ts:

Subscribes to hitl:resolution:*, hitl:message:*, hitl:approved:*
Escalation tool (escalate-to-human.ts) has 4 lifecycle hooks: preResponse, postResponse, onToolCall, promptInjection
Escalation requests are synchronous — bot waits up to 5s for assignment result to customize user messages
All user-facing messages are configurable per-agent via tool config

Frontend Routes

The Conversations module (/conversations) provides the operator interface:

Route	Purpose
`/conversations`	Overview — pending escalations, active conversations, pending approvals, resolved counts
`/conversations/inbox`	Shared Inbox with seven view chips (All, Unassigned, Mine, Assigned, AI handling, Approvals, Resolved)
`/conversations/settings`	Presence, timezone, working hours configuration
`/conversations/[id]`	Single conversation thread (live or resolved, same route)

Environment Variables

HITL_SERVICE_PORT (default: 4006)
DATABASE_URL
REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
LOG_LEVEL

Overview

Services

Architecture

Agent Provisioning API

Deployment

Design System (Neo)

HITL Service

HITL Service

Endpoints

Architecture

Redis Pub/Sub Channels

WebSocket Events

Key Services

Database Tables

Concurrency

Bot Service Integration

Frontend Routes

Environment Variables

​HITL Service

​Endpoints

​Architecture

​Redis Pub/Sub Channels

​WebSocket Events

​Key Services

​Database Tables

​Concurrency

​Bot Service Integration

​Frontend Routes

​Environment Variables

HITL Service

Endpoints

Architecture

Redis Pub/Sub Channels

WebSocket Events

Key Services

Database Tables

Concurrency

Bot Service Integration

Frontend Routes

Environment Variables