docs/diagrams/clanker-voice-and-tools.mmd

flowchart TD Start["Voice activity entrypoint"]

subgraph Session["Active voice session"]
    Audio["Incoming speaker audio / transcript"]
    TurnDecision{"Addressed to bot,

conversation engaged, or command follow-up?"} VoiceReply["Run voice reply path"] Skip["Skip / stay quiet"] ThoughtTimer["Per-session silence timer"] ThoughtEligible{"initiative.voice.enabled silence + interval met eagerness roll passed?"} VoiceThought["Generate voice thought"] end

subgraph Modes["Reply-path planning"]
    Native["replyPath=native"]
    Bridge["replyPath=bridge"]
    Brain["replyPath=brain"]
end

subgraph Context["Shared continuity context"]
    Continuity["Conversation windows

fact profiles + guidance facts behavioral memory by relevance"] end

subgraph Tooling["Planning + tool ownership"]
    ProviderNative["Provider-native planning + exported realtime tools

(local + MCP when supported)"] Orchestrator["Full-brain orchestrator reply loop shared + voice tools"] end

subgraph ThoughtPath["Ambient voice path"]
    ThoughtBinding["initiative.voice.execution binding"]
    ThoughtOutput["Speak via realtime utterance or API TTS"]
end

subgraph Controls["Main knobs"]
    Conversation["voice.conversationPolicy.*"]
    Admission["voice.admission.*"]
    Transcription["voice.transcription.*"]
    Runtime["agentStack.runtimeConfig.voice.*"]
    ThoughtKnobs["initiative.voice.*"]
end

Audio --> TurnDecision
TurnDecision -->|No| Skip
TurnDecision -->|Yes| VoiceReply

ThoughtTimer --> ThoughtEligible
ThoughtEligible -->|No| Skip
ThoughtEligible -->|Yes| VoiceThought

VoiceReply --> Native
VoiceReply --> Bridge
VoiceReply --> Brain

Continuity --> ProviderNative
Continuity --> Orchestrator
Continuity --> ThoughtBinding

Native --> ProviderNative
Bridge --> ProviderNative
Brain --> Orchestrator

ProviderNative --> Output["Answer / tool call / playback"]
Orchestrator --> Output

VoiceThought --> ThoughtBinding
ThoughtBinding --> ThoughtOutput

Conversation --> TurnDecision
Admission --> TurnDecision
Transcription --> Audio
Runtime --> Native
Runtime --> Bridge
Runtime --> Brain
Runtime --> ThoughtOutput
ThoughtKnobs --> ThoughtEligible