# Runtime Contract

This repository contains only the Combrabo Voice LiveKit runtime helper. It is a media worker, not a business service.

## Responsibilities

- Connect to the LiveKit room using bot credentials generated by `lmrobot-app`.
- Publish one `bot-main-audio` track.
- Play prepared greeting audio from `CV_GREETING_AUDIO_FILE` or `CV_GREETING_AUDIO_URL`.
- Receive user audio in S7 and pass one completed voice turn to the Java turn bridge.
- Publish reliable LiveKit Data Message for `device_output` smoke and later voice command output.

## Non-goals

- No SDK token authentication.
- No database access.
- No order, entitlement or billing logic.
- No prompt, ASR, LLM, TTS or message persistence authority.
- No LiveKit server modification.

`lmrobot-app` remains the business authority for call state, role permission, greeting prepare/consume, ASR, prompt/history, LLM, TTS, message persistence, activity, diagnostics and reasonCode.

## Required environment variables

| Name | Source | Notes |
| --- | --- | --- |
| `CV_CALL_ID` | `lmrobot-app` | Public call alias, not DB id. |
| `CV_TRACE_ID` | `lmrobot-app` | Used to correlate logs and activity. |
| `CV_LIVEKIT_URL` | `lmrobot-app` | Helper reachable LiveKit URL. |
| `CV_LIVEKIT_ROOM_ID` | `lmrobot-app` | Sensitive connection material; do not log raw value in shared docs. |
| `CV_LIVEKIT_BOT_TOKEN` | `lmrobot-app` | Sensitive connection token. |
| `CV_LIVEKIT_BOT_PARTICIPANT_IDENTITY` | `lmrobot-app` | Sensitive connection material. |

Optional first-audio variables:

| Name | Notes |
| --- | --- |
| `CV_FIRST_AUDIO_SOURCE` | `fixed_greeting_tts`, `cached_tts` or diagnostic value. |
| `CV_GREETING_AUDIO_FILE` | Local WAV / MP3 file path. |
| `CV_GREETING_AUDIO_URL` | WAV / MP3 URL fetched by helper. |
| `CV_GREETING_TEXT` | Diagnostic metadata only; do not log user/private content. |

Optional device-output smoke variables:

| Name | Notes |
| --- | --- |
| `CV_DEVICE_OUTPUT_SMOKE_ENABLED` | `true` enables deterministic Data Message smoke. Default false. |
| `CV_DEVICE_OUTPUT_DESTINATION_IDENTITIES` | Comma-separated target identities. Empty falls back to user identity or room broadcast. |

## LiveKit Data Message payload

For device output, helper sends reliable Data Message:

```json
{
  "type": "device_output",
  "schemaVersion": "1.0",
  "commandId": "cmd_xxx",
  "callId": "cv_call_xxx",
  "traceId": "trace_xxx",
  "turnId": "turn_xxx",
  "commandCode": "vibration.start",
  "params": {
    "step": 1,
    "durationSec": 3,
    "extension": {}
  },
  "source": {
    "kind": "voice_command"
  }
}
```

The payload must not include token, room credential, user raw speech, ASR text, LLM prompt or full reply text.