TUCAN Operator — Voice I/O Pipeline over the TUCAN Processor Agent
Audiences: developer, internal
The voice front-end for TUCAN: a LiveKit-connected pipeline (STT → operator agent → TTS) that lets a user talk to the existing TUCAN processor agent. The operator agent does NOT replace TUCAN — it is a thin voice-control layer that delegates real work to TUCAN via
peer:*events and itsdelegate-to-tucantool. Lives atddx-api/src/ai/tucan-operator/(@since 2.6.0).
What it is
OperatorModule provides voice I/O capabilities that interface with the existing
TUCAN processor agent via peer:* events (module header, operator.module.ts).
It depends on TucanModule (EventBusService, AgentDispatcherService,
SessionService) and AiModule (PrismaAiService for OperatorSession
persistence).
HTTP surface — @Controller('operator')
| Method | Route | Purpose |
|---|---|---|
| POST | sessions/:sessionId/start | start a voice operator session (connects LiveKit + STT/TTS pipeline) |
| POST | sessions/:sessionId/stop | tear down the session |
| GET | sessions/:sessionId/status | session status |
| GET / PATCH | sessions/:sessionId/settings | read / update operator settings |
| POST | sessions/:sessionId/mute | mute control |
Pipeline (pipeline/)
deepgram-stt.adapter.ts— speech-to-text ingestion.dudoxx-tts.adapter.ts— text-to-speech output (Dudoxx TTS).livekit-connection.service.ts— the LiveKit room/track connection.vad.service.ts— voice-activity detection (turn boundaries).
Operator agent (agent/)
operator-agent.factory.ts+operator-prompt.builder.tsbuild the operator agent.- Tools:
delegate-to-tucan.tool.ts(hand a request to the TUCAN processor),get-operator-context.tool.ts,reply-to-operator-direct.tool.ts,voice-control.tool.ts(mute/interrupt/turn control).
Events & services
- Publishers:
operator-events.publisher.ts,peer-events.publisher.ts,voice-events.publisher.ts— emitpeer:*/ voice events on the bus. - Services:
operator-session.service.ts(lifecycle + persistence),operator-settings.service.ts,operator-agent.service.ts,peer-bridge.service.ts(bridges operator ↔ TUCAN peer channel),peer-request-tracker.ts,metrics-collector.service.ts,voice-message-persistence.service.ts.
Relationship to TUCAN and Vivoxx
The operator is the voice adapter for the TUCAN processor agent (delegation,
not replacement). It is distinct from the newer Vivoxx/Condor voice work — this
shard documents the TUCAN-era operator pipeline as it exists in ai/tucan-operator/.
Related Topics
- TUCAN Orchestrator — the processor agent the operator delegates to.
- TUCAN Agent Types — where the operator agent sits in the type taxonomy.
- TUCAN Dispatcher — how a delegated request is routed inside TUCAN.