Description
Reliable Chat Turn Dispatch is the runtime that turns a message into a durable conversation outcome. It validates the requested conversation and provider, checks access and cost limits, snapshots the user's prompt and controls, assembles provider input, executes the agent, and commits the complete ordered result. The same contract supports interactive UI turns, API-driven callers, and automation-triggered conversations without letting those surfaces invent separate orchestration rules.
The runtime is divided into prepare, execute, and commit phases. That boundary lets an out-of-process worker run the provider call while the application retains authoritative persistence and side effects. Successful turns persist the user message, tool activity, assistant response, citations, artifacts, provider session metadata, and usage totals once. Cancellation or post-spawn failure still produces a coherent terminal envelope rather than leaving an ambiguous half-turn.
Selling Points
- One orchestration contract keeps interactive, automated, buffered, and streamed turns behaviorally aligned, reducing surface-specific surprises.
- Exactly-once persistence protects users from duplicated messages or side effects when a provider or network path retries.
- Typed failure outcomes distinguish missing conversations, unknown providers, cancellations, queue pressure, and cost-cap blocks so callers can respond honestly.
- Provider-neutral execution lets the same conversation workflow use local CLIs, direct models, or remote gateways without changing the stored transcript.
- Durable usage and session metadata make later resume, reporting, and audit experiences possible without replaying the agent run.
User Story
A user sends a request from an existing conversation and selects a coding-agent provider. Dots prepares the turn with that conversation's current mode, sources, workspace, and provider session, runs the agent, then appends the resulting messages in order. The user walks away with a complete, resumable transcript even if the provider used tools or encountered a recoverable failure along the way.
Extension Surface
This feature is extensible: packages/chat/src/contracts/turn-seams.ts defines injected resolvers for tools, prompt overlays, invoked Superpowers, chips, and auto-title suppression, while packages/chat/src/contracts/provider-registry.ts accepts provider implementations structurally. These are deliberate in-repo seams used by composition roots, but they are not a published third-party plugin registration API.
Capabilities & Limits
- It prepares, executes, and commits turns through serializable phase contracts.
- It records ordered messages, usage, citations, artifacts, and adapter-session state in one confirmed persistence operation.
- It supports cancellation, bounded per-conversation queuing, and both human and automation actors.
- Limit: it does not create the UI, resolve tenant-specific services, or write conversation rows directly; those responsibilities stay in composition and persistence adapters.
Implementation Map
packages/chat/src/dispatch/provider-turn.tspackages/chat/src/dispatch/prepare-turn.tspackages/chat/src/dispatch/execute-turn.tspackages/chat/src/dispatch/commit-turn.tspackages/chat/src/contracts/turn-phases.ts