# Vela Protocol and State Machine

## Event Protocol

### Client → Server

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

### Server → Client

```ts
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

```text
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