-`vertex_express(ctx, key)`: same URL, header `x-goog-api-key`. The key is never in the URL.
-`api_key(key)`: `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=<key>`, model `models/{m}`. The documented form puts the key in the query, the one place the foundation rule "key never in a URL" cannot hold; `WsUrl::display()` and every error omit the query.
-`url_override` replaces the URL (loopback tests, proxies).
- No credential: `NotConfiguredError` (503 NOT_CONFIGURED) before any socket. Bad input (model id, voice, modality, caps, mime, header characters): `GoogleError` 400 INVALID_ARGUMENT before any socket or send.
- Upstream failures map to `GoogleError` with service `live`: refused upgrade 400/401/403/404/429 keep their status, other upgrade failures and I/O are 502 UNAVAILABLE, timeouts 504 DEADLINE_EXCEEDED, a close frame before `setupComplete` is 409 FAILED_PRECONDITION carrying Google's close code and reason (e.g. 1008 "Publisher model ... was not found").
- Framing: client frames always masked; server frames must be unmasked; RSV bits, unknown opcodes, fragmented or oversize control frames, non-minimal lengths, continuation without start, new message inside a fragmented one, invalid UTF-8 text all close with 1002 / 1007 and throw. Over-cap frame or message closes with 1009. Pings are answered with the same payload. A close frame is echoed; a dropped connection without close frame reports code 1006.
- Server JSON arrives in text and in binary frames; both are parsed.
- One server message can yield several events. Order: setupComplete; model text and inline data in part order; input/output transcription; interrupted; generationComplete; turnComplete last. Inline `audio/*` is `Audio` (decoded bytes), other inline data `Media`. Undecodable messages become one `Error` event, unknown ones `Unknown`, never silence.
- Sending is thread safe; one reader thread receives. `close()` sends a close frame, waits up to the grace, joins.
- Resumption: with `config.session_resumption` the server sends `sessionResumptionUpdate` (`newHandle`, `resumable`); the session keeps the latest resumable handle. `LiveSession::resume()` stops the current connection, opens a new one with that handle in `setup.sessionResumption.handle`, waits for `setupComplete` and restarts the reader; queued events and sequence numbers carry on, and the old connection's `Closed` event stays in the queue. It is explicit (call it on a `GoAway` event or after a `Closed` event), never automatic, and capped at 5 per session. Without the option or without a handle it throws before any socket.
- Setup options beyond text and audio: `activity_detection` (automaticActivityDetection: disabled, start / end sensitivity, prefix padding 0..5000 ms, silence duration 0..10000 ms), `activity_handling`, `turn_coverage`, `affective_dialog`, `media_resolution`, `compression_trigger_tokens` / `compression_target_tokens` (int64, sent as JSON strings). Enum values are checked before any socket. Not in `LiveConfig`: `proactivity` (an empty `ProactivityConfig` in Discovery, no fields to declare), `historyConfig`, `labels`.
- TLS: `TlsStream` uses `ITlsSession` (wolfSSL) on a blocking fd with socket read and write timeouts. The wolfSSL session (`src/clients/transports/tls_wolfssl.cpp`) now tells the cases apart: a socket read or write timeout throws `TlsTimeoutError` (a `TlsError`), a closed connection (TLS close_notify, or a TCP drop without one) returns 0 with `last_read_status() == TlsReadStatus::kClosed`. Measured against a local TLS 1.3 server with a 500 ms `SO_RCVTIMEO`: silence is `wolfSSL_read` -1 with `WOLFSSL_ERROR_WANT_READ`, a drop without close_notify is 0 then `WOLFSSL_ERROR_SYSCALL`, a close_notify is 0 then `WOLFSSL_ERROR_ZERO_RETURN` (the old code compared these against the `WOLFSSL_CBIO_ERR_*` constants, which never matched). A session that does not say (`kUnknown`, e.g. a test passthrough) falls back to elapsed time against the read timeout. Writes go through a send callback with `MSG_NOSIGNAL`, so a vanished peer cannot raise SIGPIPE; `TlsStream` no longer changes the process signal disposition. An `ITlsSession` supplied through `LiveOptions::tls` must not raise SIGPIPE either.
| Vertex, express key as `Authorization: Bearer` | refused: close 1008 "Request had invalid authentication credentials" |
| Gemini API form with the express key (`?key=`) | upgrade ok, close 1008 "Gemini API ... has not been used in project ... or it is disabled" (the key's project has the API disabled; the form itself is accepted) |
| `responseModalities: ["TEXT"]` on the native audio model | close 1007 "Text output is not supported for native audio output model." |
| region `global`, or model `gemini-2.0-flash-live-001` | close 1008 "Publisher model ... was not found" |
Observed: server audio mime type is plain `audio/pcm` (no `rate=`); the
docs state 24 kHz output and 16 kHz input (`audio/pcm;rate=16000`). The
server closes TCP after its close frame without TLS close_notify.
Opt-in tests: `MOLO_LIVE_NET=1` with `GOOGLE_CLOUD_PROJECT` and
`GOOGLE_API_KEY` or `GOOGLE_ACCESS_TOKEN` (`live_net.*`, loud SKIP otherwise).
Second round, 2026-10-24, same model and region, every test once with the
express key (header) and once with the OAuth bearer, a few tiny messages each
(`tests/src/google/live/test_live_net.cpp`):
| Feature | Result |
|---|---|
| Tool call round trip | `setup.tools.functionDeclarations` with `get_temperature(city)`; the model sent `toolCall.functionCalls[]` with `id`, `name` and `args {"city":"Utrecht"}`; the turn that carried the call ends with `generationComplete` / `turnComplete` (empty transcription), so a client must not stop at that first `turnComplete`; after `toolResponse.functionResponses[{id,name,response}]` the model answered in a second turn ("The temperature in Utrecht is currently 17 degrees Celsius."), both auth forms |
| `clientContent` turn | `turns[{role:user,parts[{text}]}]` + `turnComplete:true` starts a model turn, both auth forms (it carried the tool question above and the resumption turns) |
| Output transcription | `outputTranscription` events with text, both auth forms |
| Input transcription | audio in (the model's own speech, resampled 24 kHz to 16 kHz, `audio/pcm;rate=16000` chunks of 250 ms): `inputTranscription` events arrived, both auth forms. Needed about 1 s of trailing silence: `audioStreamEnd` alone, without silence, produced no event at all within 30 s (it is accepted without error); silence followed by `audioStreamEnd` worked |
| Session resumption | `sessionResumption: {}` in setup: `sessionResumptionUpdate {newHandle, resumable:true}` (36 characters) arrived around the turn end. Reconnecting with `sessionResumption.handle` (new object and `LiveSession::resume()` on the same object) kept the context: asked for "the secret word" (pineapple, mango) the model answered it, both auth forms |
| Interruption | new `realtimeInput.text` while the model spoke: an `interrupted` event, both auth forms |
| Video input | `realtimeInput.video {data, mimeType:"image/jpeg"}` frames (4 frames, 700 ms apart) of a solid red 256x256 JPEG, then a text question: "Red." on both auth forms. A 64x64 frame was accepted without error but the model answered that it could not see an image; the first turn after frames is sometimes empty, so the test asks once more |
| `goAway` | idle session with resumption on, express key: `goAway` after 514 s with `timeLeft` 57 s (parsed from the protobuf duration string), `Closed` code 1000 at 571 s. The server's connection lifetime is about 9.5 minutes here |
| Setup options | `automaticActivityDetection` (sensitivities LOW, padding 100 ms, silence 700 ms), `activityHandling`, `mediaResolution`, `contextWindowCompression` (`triggerTokens`, `slidingWindow.targetTokens` as strings): accepted, a turn completed, both auth forms |
| `?key=` on the Vertex endpoint | observed with a one-off websocket-client probe (not in the tree): upgrade, setup with the project model name and `setupComplete`, no turn |
| Express key, model name without a project (`publishers/google/models/{m}`) | observed with the same probe: `setupComplete` |
- The Vertex Live reference page (docs.cloud.google.com ... reference/models/live-api) could not be read in full, and a second attempt in the gap-closing round was refused by the fetch tool (session limit), so Vertex-specific message differences from the Gemini API reference are still unread. The Vertex endpoint path, both auth forms and every message shape used above were verified live instead.
- `toolCallCancellation` was never seen: a pending `toolCall` followed by new input did not produce it (probe, express key); its shape (`ids`) is from the Gemini API reference and local tests only.
- Not exercised live: `activityStart` / `activityEnd` messages (manual VAD), `generationConfig.thinkingConfig`, the Gemini API form (`api_key`) past upgrade (the express key's project has the API disabled), and the effect of `affective_dialog` (setup option accepted by the locally built message only).
- Session limits (audio-only 15 min, audio+video 2 min) are from a community guide; the one measured lifetime is about 9.5 minutes (goAway at 514 s, close at 571 s, express key, audio only, resumption on), so treat the guide's numbers as unconfirmed. The module enforces its own 1800 s cap.
- Whether `audioStreamEnd` flushes an utterance when automatic VAD is disabled: only measured with VAD on.