[hhugo-gradium]

Summary

Three commits on the Gradium STT stream's session end, plus the test harness they share.

• The model delay was read from a key the server never sends. The ready message carries delay_in_frames; the stream looked up delay_in_tokens and always fell back to 6. Production models run with a delay of 10, so a turn was finalized 4 steps (320 ms) before the model had emitted its last words, which then surfaced as a spurious new turn: a START_OF_SPEECH, a one-word FINAL_TRANSCRIPT, an END_OF_SPEECH.
• The session never ended on its own. When the input channel closed, send_task returned without telling the server and the closing_ws flag was never set, so recv_task polled until the server dropped the idle socket two minutes later, which was then reported as an unexpected close and retried against a closed input. The unused _CLOSE_MSG (terminate_session) was another provider's protocol. Now {"type": "end_of_stream"} is sent once the input ends, and on the server's end_of_stream the buffered words are emitted as the final transcript before the stream returns. Server error frames raise APIError with the server's message instead of being logged as an unknown type, and the VAD silence flush is skipped once the input channel is closed.
• Every way a session ends keeps the transcript. Only the server's end_of_stream path emitted the words buffered since the last VAD finalization; a close frame in its place, or the receive timeout while closing, dropped them. All three exits finalize now. A server-initiated end_of_stream while audio is still being sent (a duration limit, for instance) used to be treated as a clean end, after which the next audio write failed with a raw, non-retryable connection error; it now finalizes and raises a retryable APIStatusError so the stream reconnects. The final end_of_stream send is guarded against the server closing first.

Testing

• tests/test_plugin_gradium_stt.py gains a scripted fake websocket that replays ready, text and step frames, blocks until the client's end_of_stream like a live socket, then replies with the server's EOS and a normal close. Six tests: a positive VAD finalizes after the delay the ready message announced; end_input() sends end_of_stream and the stream ends with the pending words as a final transcript; an error frame raises with the server message; a close in place of the server's reply still yields the final transcript; a server end_of_stream mid-input finalizes then raises a retryable error; the final send on an already-closed socket is not an error. All fail on main. The module is hermetic and now carries the unit marker so CI runs it.
• ruff, ruff format --check and mypy --strict clean on the plugin.
• Live against api.gradium.ai with the repository's 46 s speech sample streamed in real time: one turn, and the stream ended 0.5 s after end_input(). On main the same run split the speech into two turns and, after end_input(), hung until the server closed the socket with 1008 "Session produced no output for 120 seconds". WER against the reference was 0.034 on 2026-10-14 and 0.074 on 2026-10-16, when the server returned lowercase, unpunctuated text that the scorer counts word by word; the plugin relays the text unchanged.

Related

#7814 reports the configured model name for STT as well. The remaining STT fixes (cumulative interim transcripts, vad_bucket=0, connect timeout) are stacked on this PR as the next one.

🤖 Generated with Claude Code

[davencyw]

Thanks @hhugo-gradium! The changes make sense to me and are clean. There are two things that stood out:

Audio sends can still fail with a raw, non-retryable error:
The final end_of_stream send is guarded now, but the audio sends in the send_task loop aren't. If the server closes the socket and an audio write happens before recv_task processes the EOS/close frame, send_task raises ClientConnectionResetError. gather passes it up, and the base class treats any non-APIError as fatal, so it doesn't retry. That's the same failure the PR describes, just through a race. I'd catch aiohttp.ClientError / ConnectionError around the audio sends too, and either return (so recv_task reports the close) or raise a retryable APIConnectionError.

Every error frame is retried:
_api_error returns a plain APIError, which defaults to retryable=True. So errors like "Unsupported language" or "no credits" are retried max_retry times with backoff before failing, and the server message ends up behind a generic "failed to recognize speech after N attempts". Since we parse the frame now, could we mark config/billing errors as retryable=False, e.g. based on the code field?

Not sure if those two are worth to fix already since the code is already an upgrade, your choice!

[davencyw]

This changes the public API, not sure if it will break anything downstreams? Alternatively we could have an alias. But it does indeed change the semantics. Unsure what the right thing to do is here.

[davencyw]

Does it make sense to have 6 hardcoded here? Do we know where it is coming from? Do we expect the key to not exist in certain cases? I know it's not your code, but I thought you might have found something along the way.

[davencyw]

Nit: Top level import might be a bit cleaner.