voice: output retries for run(output_type=...)

[theomonnom]

A run with an output_type ends with final_output=None whenever the model finishes its turn in prose instead of calling the task's completion tool — common with chatty models, and currently surfaced as a generic RuntimeError that callers can't distinguish or recover from.

Following pydantic-ai's output-tool semantics:

• New output_options on run() (an options TypedDict in the style of keyterm_options/expressiveness): when the run ends without its output_type, the session re-prompts in the same context as a per-turn system message (max_retries, default 2) before raising; retry_instructions overrides the built-in retry prompt.

  result = await sess.run(
      user_input=...,
      output_type=SummarizeOutput,
      output_options={"max_retries": 2, "retry_instructions": "Call submit_analysis, nothing else."},
  )

• A distinct UnexpectedModelBehavior (exported from livekit.agents, same name as pydantic-ai's) replaces the generic RuntimeError once the budget is exhausted, so callers can catch the failure specifically.

Defaults convert the dominant failure (model summarizes in prose) into a recovered run. Unit tests cover recovery, the prompt override, and exhaustion via FakeLLM.

🤖 Generated with Claude Code

[devin-ai-integration]

Devin Review found 3 new potential issues.

[devin-ai-integration]

📝 Info: Default output_retries mismatch between RunResult constructor and AgentSession.run()

The RunResult.__init__ default for output_retries is 1 (run_result.py:82), but AgentSession.run() always passes output_options.get('max_retries', 2) (agent_session.py:623), defaulting to 2. This means direct construction of RunResult (e.g., at agent_session.py:854 for capture_run) gets 1 retry, while runs through session.run() get 2. The capture_run path at line 854 doesn't set output_type, so retries are irrelevant there, but the inconsistency could be confusing for any future code path that constructs RunResult directly with an output_type.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[theomonnom]

Intentional: one silent recovery is the desired out-of-box behavior (it converts the dominant failure into a recovered run, matching pydantic-ai's default of 1 output retry), and the latency cost only occurs on runs that would previously have failed outright. The exception change is called out in the PR description; output_options={"retries": 0} restores fail-fast.

[chenghao-mou]

should this include NOT_GIVEN so None can be used to disable the retry behavior? otherwise we have to type {"max_retries": 0} to disable it explicitly.

[chenghao-mou]

nitpicking: we could follow the _resolve* pattern here to have explicit default value(s).

[chenghao-mou]

nitpicking: should we just pass the output options here so default values and resolution can stay in one place?