The dispatcher is a deterministic state machine, not an LLM choice.
Agent type is read from session.agentType; tool catalog is derived
from the YAML template at agent construction; every transition between
stages is a typed TurnTransition (ok / suspend / replan / escalate /
fail) validated by Zod v4.
Migration status (2026-07): this is the LEGACY TUCAN dispatcher. The
second-generation engine Condor (ddx-api/src/ai/condor/**, see
[[condor-engine]]) runs side-by-side and progressively ports individual
flows off this path via its agentic-flow-router.service.ts. TUCAN's
session.agentType persisted-dispatch invariant carries over verbatim to
Condor — dispatch is never an LLM choice in either engine.
Structural note: the former dispatch/engine.ts +
dispatch/dispatch-engine.module.ts were consolidated — the turn engine now
lives in dispatch/stages/dispatcher.ts (staged pipeline) fronted by
agent-dispatcher.service.ts; dispatch/index.ts is the barrel.
Business Purpose
TUCAN's reliability lives in the dispatcher. The product promise — "the
AI does real clinical work" — collapses if any of the following is
true on a given turn:
The wrong agent type runs (Document agent answering a clinical
question, voice operator running on a chat session).
The user's Stop click is silently dropped because the abort
arrived before the dispatcher reached its first await.
A suspended workflow leaks across users because the next POST
matched the wrong pending entry.
A tool error becomes a 500 instead of a typed escalate /
fail transition the UI can render.
The dispatcher is the boundary that owns these guarantees. It:
Reads agent identity from persisted session state, not from
the LLM. (Project memory invariant
[[project_tucan_no_guided_consumers]].)
Registers an AbortSignal synchronously before the first
await, so Stop works across the gap between HTTP 201 response
and the first SSE event.
Tracks suspended workflows by session.metadata.suspendedWorkflows[taskId]
— keyed entries, first-entry-wins, never matched across sessions.
Reduces every per-stage outcome into a typed TurnTransition
(ok | suspend | replan | escalate | fail) via the
dispatch/transitions.ts factory functions — the only way
the engine moves forward.
That's why "TUCAN dispatcher" is its own KB page: the reliability
contract is architecturally distinct from the LLM agent invocation
and from the per-turn UI rendering.
Audiences
Investor: TUCAN's defensibility is that it does not depend on
the LLM being correct about routing. State-machine routing reduces
the surface where an LLM hallucination can do harm to "what the
tool I'm allowed to call does," not "which agent or workflow to
run."
Developer / partner: A new stage is a class with a single
run() method that returns a TurnTransition. The
AgentDispatcherService.processMessage pipeline composes them
serially with abort-checks between every stage. No magic.
Internal (ops / support): When a turn looks wrong in production
("the AI answered scheduling questions with a clinical agent"),
the answer is in session.agentType and session.metadata.mode,
not the LLM. SQL is your friend.
The staged dispatcher pipeline (current architecture)
The earlier "target architecture" — a framework-light DispatchEngine
async-generator in dispatch/engine.ts — was realized and then folded in.
The turn pipeline now lives in dispatch/stages/ (dispatcher.ts,
intent-classifier.ts, rewriter.ts, trivial-bypass.ts, suspender.ts,
reporter.ts, turn-prologue.ts), coordinated by
agent-dispatcher.service.ts (AgentDispatcherService). The standalone
dispatch/engine.ts + dispatch/dispatch-engine.module.ts no longer exist;
the retired DispatcherStage class note is in stages/dispatcher.ts itself.
Each stage still reduces to a typed TurnTransition — that invariant survived
the consolidation and carries forward into [[condor-engine]].
The engine returns the generator after emitting any terminal
transition (fail, escalate, terminal ok with the report
envelope, or suspend). After return, the consumer must not pull
further values.
Per-stage classes
All dispatch/stages/ classes share the contract async run(input)
returning a transition or a stage-typed envelope. Today's set:
Stage class
File
Purpose
TrivialBypassStage
stages/trivial-bypass.ts
Skip LLM for greetings + one-token inputs (pre-rewriter and post-rewriter phases)
RewriterStage
stages/rewriter.ts
Mastra agent that turns raw prompt into structured rewrite
IntentClassifierStage
stages/intent-classifier.ts
Map rewrite → intent label via intent-descriptor.registry
SuspenderStage
stages/suspender.ts
Resume Mastra workflow from suspendedWorkflows[taskId]
DispatcherStage
stages/dispatcher.ts
The Mastra Agent.generate(...) invocation
ReporterStage
stages/reporter.ts
Narrate dispatcher output to HTML / Markdown for the UI
ReporterAggregators
stages/reporter-aggregators.ts
Helpers for reporter
TurnPrologue
stages/turn-prologue.ts
Standard prologue per turn
types
stages/types.ts
Shared per-stage types
The dispatch/trivial-input.classifier.ts module backs TrivialBypassStage
with the actual classification logic.
Tech Stack & Choices
Component
Choice
Why
Composition
Serial stages in AgentDispatcherService.processMessage
One ordered pipeline, easy to reason about and trace.
DispatchEngine (Phase 6) imports no Mastra, no SSE
Consumer-side side effects; engine is pure transition reduction. Equivalence-tested against legacy in dispatch/__tests__/transition-equivalence.spec.ts.
Alternatives rejected:
LLM-chosen agent type (the "guided" pattern) — explicit project
invariant ([[project_tucan_no_guided_consumers]]). Adding it
silently breaks the SSE contract assumption that
agent:start reports a known, persisted agent ID.
Hard-coded order in one giant method — what we had before stage
classes. Hard to test individual transitions; impossible to
selectively bypass a stage for a given input.
State machine via XState — overkill for a 7-stage serial
pipeline; would have hidden the typed-transition contract
behind an additional library.
Data Flow
Business outcome: A doctor clicks Stop on a turn that is
running a slow tool. The turn aborts, the SSE stream closes
cleanly, and the UI flips back to "ready" within one frame.
Technical mechanism:
Controller receives stop POST and calls abort() on the
AbortController registered for requestId.
The next checkAborted() inside the dispatcher throws
DispatchAbortedError
(ddx-api/src/ai/tucan/dispatch/agent-dispatcher.service.ts:156).
The outer try/catch publishes agent:complete { aborted: true }
and clears streamingCompleted: true.
The SSE channel sees agent:complete; the consumer hook resets
the UI.
Business outcome: A patient-search workflow asks the doctor
"did you mean John Garcia or Juan García?" The dispatcher pauses,
the doctor picks the correct candidate, the same workflow resumes
with that decision.
Technical mechanism:
Tool execution returns a DispatchStep.suspend envelope with
formId: 'clarify-candidate' and a payload containing the
candidate list.
DispatchEngine.executeStep (engine.ts:204) sees the
step.suspend shape and emits suspend(formId, payload)
transition.
The dispatcher service persists
session.metadata.suspendedWorkflows[taskId] and publishes
workflow:suspended SSE.
Doctor picks "John Garcia" → POST /sessions/:id/messages
with a ResumeDecision body.
ChatOrchestratorService.resume
(ddx-api/src/ai/tucan/orchestrator/chat-orchestrator.service.ts:152)
validates against ResumeDecisionSchema, looks up the entry,
calls Mastra workflow.createRun({ runId }) and
run.resume({ step: entry.stepId, resumeData: decision }).
The Mastra workflow continues from the suspended step with the
doctor's decision as resumeData; the dispatcher emits the
final ok (report) transition.
Implicated Code
ddx-api/src/ai/tucan/dispatch/agent-dispatcher.service.ts:88 —
class AgentDispatcherService.
ddx-api/src/ai/tucan/dispatch/agent-dispatcher.service.ts:113 —
resolveTurn(dto, …) returns { agentType, pendingSuspendedWorkflows }
— agent identity comes from persisted state, NOT the LLM.
ddx-api/src/ai/tucan/dispatch/agent-dispatcher.service.ts:126 —
Abort-signal handshake (registered synchronously before first
await).
ddx-api/src/ai/tucan/dispatch/agent-dispatcher.service.ts:155 —
turnSignal set + checkAborted closure.
ddx-api/src/ai/tucan/dispatch/stages/dispatcher.ts — the staged turn
coordinator (the former dispatch/engine.tsDispatchEngine generator was
folded here; DispatcherStage is retired per the file's own header note).
TUCAN does NOT have guided consumers today.
([[project_tucan_no_guided_consumers]]) Agent dispatch is persisted
state, NOT LLM-chosen. There are no enum/regex tools wired to a
guided pattern; the plumbing exists in the registry but ships
dormant. Do not document the aspirational guided pattern as live.
Agent type is set by the caller, not chosen by the LLM. The
EmbeddableAssistant resolver hardcodes 'clinical-assistant'; the
voice operator sets 'tucan'; the messenger consumer sets the
channel-appropriate type ([[ai-chat-sessions]] §Architecture).
useSessionResolver ALWAYS creates 'clinical-assistant' — does
NOT forward the selected type (see MEMORY_TUCAN_AI; defect to
file).
get_clinical_notes is a hallucination. Real tool:
list-clinical-notes. If the dispatcher logs tool_unknown for
it, the clinical agent's prompt has drifted — re-eval.
Abort registration must be synchronous. The controller MUST
register the signal in activeStreams synchronously before the
fire-and-forget Promise starts. Any new HTTP path that calls
processMessage without doing this breaks Stop.
First-entry-wins on suspended workflow lookup. The
ChatOrchestratorService.resume reads
Object.entries(suspendedWorkflows)[0]
(chat-orchestrator.service.ts:197). Multi-suspend is not
supported today.
agent:resolved SSE event is emitted by the specialist
factory when the dispatch picks a specific specialist
([[agent-templates]] §Specialist factory). UI relies on it for
the "answered by X" label.
Replan budget defaults to 1. Engine emits replan(reason, Math.max(0, remaining)). After replan exhaustion the engine
emits fail({code:'budget_exhausted', kind:'replan'}). Tune the
budget per-intent in the descriptor registry, not globally.
SSE channel naming MUST use SSEChannels.session(id). Raw
template literals like `agent:session-${id}` are banned by
the SSE contract channel rules (SSEChannels.session(id), never raw literals).
Related Topics
[[tucan-assistant]] — orchestration entry point; the
service-level overview.
[[tucan-orchestrator]] — layered execution L1-L5; consumer of
some of the same primitives.
[[tucan-intent-filtering]] — the intent classifier stage in
detail.
[[agent-templates]] — provides the resolved agent that
DispatcherStage actually invokes.
[[ai-medical-tools]] — produces the ToolResult<O> envelopes the
engine reduces.