Transcripts, rendering, and voice
Messaging keeps conversation state across restarts, turns streaming CLI events into readable status messages, and accepts voice notes as another form of user input. It preserves the links between platform messages and conversation nodes while adapting the same transcript to Discord and Telegram display rules. See Messaging platforms, Messaging turn workflows, and Messaging conversation trees for the surrounding platform and turn model.
Session continuity
Session continuity separates two kinds of state. Conversation snapshots preserve the work tree and its platform references. A managed message log records which platform message IDs belong to the application so cleanup actions can act on owned messages without treating the whole chat as application state.
Conversation persistence
The conversation store restores typed conversation snapshots before platform traffic starts. Each snapshot is scoped to a platform chat and keeps the nodes needed to resume or reconcile queued work. The active CLI session ID is saved when the CLI reports its real ID, so later turns can reuse the correct session or fork from a reply target.
References: src/…/store.py• L19-44 src/…/store.py• L91-109 src/…/snapshot.py• L13-60 src/…/node_event_pipeline.py• L21-55
Writes are delayed and combined during normal activity. A direct write is used for authoritative clear operations. The persistence layer writes a complete JSON snapshot through a temporary file and replaces the target atomically, which reduces the chance that a process stop leaves a partial state file.
References: src/…/persistence.py• L21-31 src/…/persistence.py• L48-69 src/…/persistence.py• L130-161 src/…/store.py• L153-162
Managed message history
The managed message log is an ownership ledger, not a copy of message text. It keeps inbound and outbound IDs in chat order with a direction and kind such as prompt, voice, command, or status. Duplicate IDs are ignored, and an optional per-chat cap limits how much cleanup history is retained.
References: src/…/managed_message_log.py• L7-13 src/…/managed_message_log.py• L48-72 src/…/managed_message_log.py• L99-131 src/…/workflow.py• L622-677
Clear operations use this ledger with the conversation snapshots. They delete or forget only the messages that the application owns, while a scope clear removes the selected platform chat from both state stores and leaves other chats intact.
References: src/…/store.py• L135-158 src/…/workflow.py• L606-620 src/…/turn_intake.py• L163-195
Transcript display
A transcript is the live user-facing view of one CLI turn. The node runner receives parsed CLI events, applies them to an ordered buffer, and edits one platform status message as the turn advances. The buffer is temporary display state; the durable conversation snapshot stores node and session state rather than the complete rendered text.
References: src/…/node_runner.py• L59-73 src/…/node_runner.py• L113-169 src/…/models.py• L24-48
Event buffering
The buffer groups streamed events into readable segments. It can show thinking, answer text, tool calls, tool results, subagent activity, and errors. Start, delta, stop, and block events update open segments so partial CLI output can be displayed before the turn ends.
References: src/…/buffer.py• L30-102 src/…/segments.py• L18-24 src/…/segments.py• L26-66 src/…/segments.py• L69-119
Nested Task work is shown as a compact subagent entry instead of repeating its inner thinking and answer text in the parent view. The display still exposes the subagent description and a summary of its tool use, which keeps long delegated work readable.
References: src/…/buffer.py• L47-51 src/…/buffer.py• L138-181 src/…/subagents.py• L10-54 src/…/segments.py• L122-164
Incremental rendering
Rendering applies a platform context to each segment. The context supplies the platform’s bold, code, escaping, and Markdown functions, while segment-level tail limits prevent one long thinking block, answer, or tool result from using the whole display. The final result also carries the current status line.
References: src/…/context.py• L7-18 src/…/segments.py• L40-45 src/…/segments.py• L62-66 src/…/segments.py• L112-119
The renderer enforces a total character budget after it combines the segments and status. When the result is too long, it drops the oldest rendered parts first and marks the result as truncated. If only a small tail can fit, it keeps the end of the last part or returns the status alone.
References: src/…/renderer.py• L10-16 src/…/renderer.py• L26-63
Status message updates
The workflow creates or adopts one status message for a turn. The editor updates that message at most once per second unless a boundary such as block completion or turn completion requires an immediate refresh. It skips unchanged text and sends edits through the platform outbox, so the user sees one growing message instead of a new message for every stream event.
The main transcript path follows this sequence:
flowchart LR
A[CLI event stream] --> B[Parsed event]
B --> C[Transcript buffer]
C --> D[Platform rendering profile]
D --> E[Character budget]
E --> F[Status message edit]
F --> G[Platform outbox]
References: src/…/turn_intake.py• L84-105 src/…/ui_updates.py• L13-29 src/…/ui_updates.py• L48-99 src/…/outbox.py• L64-82
Markdown profiles
The rendering profile keeps transcript content platform-neutral until the last step. It selects the syntax, escaping rules, parse mode, status format, and display budget for the destination platform. Discord and Telegram therefore receive the same meaning even though their Markdown rules differ.
References: src/…/profiles.py• L29-53 src/…/workflow.py• L165-175
Discord Markdown
Discord uses standard Markdown sent as plain message content. The profile escapes characters that can change formatting, preserves common emphasis, links, lists, quotes, and code blocks, and converts tables into readable fenced text. Its transcript budget is 1,900 characters, below the transport’s 2,000-character send and edit limit.
References: src/…/discord_markdown.py• L1-36 src/…/discord_markdown.py• L55-60 src/…/discord_markdown.py• L249-307 src/…/profiles.py• L37-53 src/…/discord_io.py• L9-19
Telegram MarkdownV2
Telegram uses MarkdownV2 with an explicit parse mode. The profile escapes Telegram’s wider set of control characters, formats emphasis and code with Telegram syntax, and converts tables into fenced code blocks. If Telegram rejects a formatted message because of an entity parse error, the delivery layer retries without a parse mode so a response can still reach the user as plain text.
References: src/…/telegram_markdown.py• L1-49 src/…/telegram_markdown.py• L52-78 src/…/telegram_markdown.py• L262-320 src/…/profiles.py• L37-53 src/…/telegram_io.py• L102-125
Shared Markdown normalization
Both profiles normalize GitHub-style tables before parsing them. The normalization only changes table recognition outside fenced code, which protects literal code content while making table output more stable across the two platforms.
References: src/…/markdown_tables.py• L9-20 src/…/markdown_tables.py• L25-47 src/…/discord_markdown.py• L55-61 src/…/telegram_markdown.py• L52-58
Voice interaction
Voice input enters the same turn system as text after transcription. Platform adapters identify an audio item and supply download and reply actions to a shared voice flow. That flow owns the temporary status message, transcription work, handoff to the normal message handler, and cleanup when the work does not complete.
References: src/…/voice_flow.py• L36-58 src/…/voice_flow.py• L96-114 src/…/voice_flow.py• L144-152
Audio intake
Discord accepts an audio attachment when a message has no text. Telegram accepts a voice update. Both adapters normalize the event into a VoiceNoteRequest, which keeps platform IDs, reply context, thread context, a temporary file suffix, and platform-specific status text together.
References: src/…/discord.py• L160-184 src/…/discord_inbound.py• L23-28 src/…/discord_inbound.py• L77-112 src/…/telegram.py• L137-145 src/…/telegram_inbound.py• L76-133
The shared flow first reserves the voice message and sends a reply such as “Transcribing voice note...”. It downloads the audio to a temporary file, rejects a missing or oversized file, and removes the file after processing. A missing transcriber produces a clear disabled response instead of entering the normal turn path.
References: src/…/voice_flow.py• L24-29 src/…/voice_flow.py• L116-123 src/…/voice_flow.py• L159-208 src/…/voice_flow.py• L303-306 src/…/voice_flow.py• L381-388
Local transcription
The local transcription service turns the temporary audio file into English text through a lazily loaded Whisper pipeline. It runs the blocking model work outside the async event loop and serializes access to its owned model. Empty recognition results become a user-visible “no speech detected” value rather than an empty prompt.
References: src/…/transcription.py• L21-40 src/…/transcription.py• L42-72 src/…/transcription.py• L74-111 src/…/transcription.py• L125-132
Voice handoff
After transcription, the flow creates an ordinary IncomingMessage whose text is the transcription. It keeps the original voice message ID and the pre-sent status message ID, then hands the message to the same handler used for text turns. The normal intake path edits that status message into the turn’s first status instead of sending a second status message.
References: src/…/voice_flow.py• L205-230 src/…/models.py• L24-48 src/…/turn_intake.py• L84-105
Voice cancellation
Pending voice work has one owner per platform chat and source message. The registry also recognizes the status message as a reference to that work, so stop and clear actions can cancel a voice operation before or during handoff. Cancellation drains the owned task and returns the message IDs that should be removed, which prevents stale “transcribing” messages from remaining in the chat.
The voice path joins the transcript path only after it has produced text:
sequenceDiagram
participant User
participant Platform
participant Voice as Voice flow
participant STT as Transcription service
participant Turns as Turn handler
participant UI as Status message
User->>Platform: Send voice note
Platform->>Voice: Normalized voice request
Voice->>UI: Send transcribing status
Voice->>STT: Download and transcribe audio
STT-->>Voice: Text
Voice->>Turns: Handoff as incoming text
Turns->>UI: Edit status with transcript progress
Turns-->>User: Final rendered result
References: src/…/voice.py• L64-82 src/…/voice.py• L89-123 src/…/voice.py• L181-250 src/…/voice_flow.py• L125-142
Change checklist
When these files or sections are changed, remember to consider these:
- Keep
SessionStorepersistence fields aligned with snapshot loading, legacy migration, and managed-message cleanup. A field that loads but does not save can break restart behavior without an immediate error. - Keep the rendering profile’s parse mode and escaping functions paired. Changing one platform formatter without its
RenderCtxcan produce text that the platform rejects. - Keep the transcript character budget below the matching platform transport limit. Otherwise, a valid rendered transcript can still fail when sent or edited.
- Keep voice status ownership linked to both the source voice ID and the generated status ID. Stop and clear flows rely on both references to remove stale work safely.
- Keep voice handoff input compatible with
IncomingMessage.status_message_id. Removing that link makes voice turns create a second status message instead of reusing the first one. - Keep table normalization outside fenced code blocks. Applying it to code can change user content before either Markdown profile renders it.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Session JSON is malformed or cannot be read | The process starts without the saved conversation state | SessionStore logs the load failure; restart continuity is lost until a valid snapshot is available |
| A newer session change supersedes a delayed write | An older snapshot could overwrite newer state | Debounced persistence checks its generation before replacing the file |
| A rendered status exceeds the platform budget | The platform may reject the edit or truncate content unexpectedly | The renderer drops old segments and marks the display as truncated |
| Telegram MarkdownV2 contains an invalid entity | The formatted send or edit fails | Telegram retries the operation without a parse mode |
| Voice transcription is unavailable, fails, or exceeds the audio size limit | The voice note cannot become a turn | The flow replies with a disabled or retry message and cleans up pending state and temporary audio |
| Stop or clear races with voice handoff | A cancelled voice turn could continue or leave its status message behind | PendingVoiceRegistry owns reservations, drains cancellation, and returns deletion IDs |
Key files
| File | Why to read it |
|---|---|
| src/…/store.py | Main boundary for conversation snapshots and managed message ownership |
| src/…/persistence.py | Persistence timing and safe replacement behavior |
| src/…/managed_message_log.py | Meaning and scope of the managed message ledger |
| src/…/node_runner.py | Connection between one CLI turn, its transcript, and its status message |
| src/…/buffer.py | Event-to-segment buffering and nested Task display behavior |
| src/…/renderer.py | Total display budget and truncation policy |
| src/…/ui_updates.py | Rate-limited incremental status edits |
| src/…/profiles.py | Platform choice of Markdown rules and character budget |
| src/…/discord_markdown.py | Discord output contract |
| src/…/telegram_markdown.py | Telegram MarkdownV2 output contract and fallback context |
| src/…/voice_flow.py | Shared voice lifecycle from audio request to normal turn handoff |
| src/…/transcription.py | Local speech-to-text boundary |
| src/…/voice.py | Voice ownership and cancellation contract |