assistant/docs/protocol.md

Vela Protocol and State Machine

Event Protocol

Client → Server

type ClientEvent =
  | { type: "start_listening" }
  | { type: "stop_listening" }
  | { type: "audio_chunk"; data: string } // PCM16 base64
  | { type: "interrupt" };

Server → Client

type ServerEvent =
  | { type: "state"; value: "idle" | "listening" | "thinking" | "speaking" }
  | { type: "partial_transcript"; text: string }
  | { type: "final_transcript"; text: string }
  | { type: "assistant_text_delta"; text: string }
  | { type: "tool_call_started"; tool: string }
  | { type: "tool_call_finished"; tool: string; result: unknown }
  | { type: "tts_audio_chunk"; data: string }
  | { type: "assistant_done" }
  | { type: "error"; message: string };

State Machine

idle
 → listening
 → thinking
 → speaking
 → idle

Interrupt can occur at:

• listening → restart
• thinking → cancel
• speaking → stop immediately

Interrupt Handling Requirements

• immediate stop of TTS playback
• immediate stop of LLM streaming
• reset session state to listening or idle, depending on UX decision

Mechanism

The interrupt event cancels:

• TTS process
• current LLM request
• tool execution when possible

Protocol Notes for Implementation

• keep the protocol backward compatible when possible
• prefer additive event changes over breaking renames
• document protocol updates in this file whenever implementation changes behavior
• when implementation diverges from the initial contract, update this document in the same change