fix(openai-agents): stop double-counting a failed run's token spend

Two sources describe the same spend and they overlap. The run hooks add each
turn as it finishes, so by the time the run raises they already hold every
completed turn, and the exception carries the SDK's own aggregate over those
same turns. The error path added the aggregate to the accumulator, so any run
that failed after paid turns reported roughly twice what it cost.

MaxTurnsExceeded does that by definition, which makes this the common case
rather than an edge one. A three-turn run reporting 70 input tokens reported
140.

The aggregate is the authoritative figure, so it now replaces the accumulator
rather than adding to it, matching what the TypeScript handler does. When the
error carries no aggregate, which is what a tool handler's own error looks
like, the accumulator is all there is and is used instead. Neither having
anything still writes nothing, because all-zero attributes would assert the run
cost nothing.

Three tests, one per branch. The double-count one fails with 140 against 70
when the fix is reverted, which is how I checked it pins the bug rather than
the behaviour.

Found by Bugbot on #33, severity High.

Author: apucacao

packages/openai-agents/src/launchdarkly_ai_openai_agents/handler.py

@@ -26,6 +26,7 @@
     AiConfigRep,
     LDContext,
     ProviderHandler,
+    RunUsage,
     SpanUsage,
     config,
     create_handler,
@@ -289,6 +290,34 @@ def abandon_open_spans(self, ended: set[int]) -> None:
             self.open_model_span = None
 
 
+def _write_failed_run_usage(
+    span: Any,
+    config: AiConfigRep,
+    error: BaseException,
+    run_usage: RunUsage,
+) -> None:
+    """Writes what a failed run spent onto the root, without counting it twice.
+
+    Two sources describe the same spend, and they overlap. The run hooks add each turn as it
+    finishes, so by the time the run raises they already hold every completed turn. The exception
+    also carries the SDK's own aggregate over those same turns.
+
+    Adding the aggregate to the accumulator therefore roughly doubles the reported cost of any run
+    that failed after paid turns, which MaxTurnsExceeded does by definition. The aggregate is the
+    authoritative figure, so it replaces the accumulator rather than adding to it.
+
+    When the error carries no aggregate, which is what a tool handler's own error looks like, the
+    accumulator is all there is and is used instead. Nothing is written when neither has anything:
+    all-zero attributes would assert the run cost nothing, which a run that died on its first call
+    cannot claim.
+    """
+    spent = _usage_from_error(error)
+    if spent is not None:
+        finish_root_span(span, config, spent)
+    elif run_usage.reported:
+        finish_root_span(span, config, run_usage.total)
+
+
 def _usage_from_error(error: BaseException) -> SpanUsage | None:
     """The run's spend at the point it raised, when the SDK attached one.
 
@@ -373,11 +402,7 @@ async def _call_impl(
             }
         except Exception as exc:
             hooks.close_open_spans(exc)
-            spent = _usage_from_error(exc)
-            if spent is not None:
-                run_usage.add(spent)
-            if run_usage.reported:
-                finish_root_span(span, config, run_usage.total)
+            _write_failed_run_usage(span, config, exc, run_usage)
             fail_span(span, exc)
             raise
 
@@ -493,11 +518,7 @@ async def _stream_gen(
 
     except Exception as exc:
         hooks.close_open_spans(exc)
-        spent = _usage_from_error(exc)
-        if spent is not None:
-            run_usage.add(spent)
-        if run_usage.reported:
-            finish_root_span(span, config, run_usage.total)
+        _write_failed_run_usage(span, config, exc, run_usage)
         fail_span(span, exc, ended)
         raise
     finally:

packages/openai-agents/tests/test_handler.py

@@ -1381,3 +1381,97 @@ def test_history_without_prior_instructions(self) -> None:
         assert instructions is not None
         assert "Conversation History:" in instructions
         assert "user: What is feature flagging?" in instructions
+
+
+# ---------------------------------------------------------------------------
+# TELEMETRY-CONTRACT.md section 6: what a failed run reports it spent
+# ---------------------------------------------------------------------------
+
+
+class _AgentsError(Exception):
+    """An AgentsException-shaped error: it carries the SDK's own run aggregate.
+
+    MaxTurnsExceeded is the common case, and by definition it happens after paid turns.
+    """
+
+    def __init__(self, input_tokens_: int, output_tokens_: int) -> None:
+        super().__init__("max turns exceeded")
+
+        class _Usage:
+            # Matches agents.Usage, which is snake_case.
+            input_tokens = input_tokens_
+            output_tokens = output_tokens_
+            input_tokens_details = None
+
+        class _Ctx:
+            usage = _Usage()
+
+        class _RunData:
+            context_wrapper = _Ctx()
+
+        self.run_data = _RunData()
+
+
+class TestFailedRunUsage:
+    async def test_reports_the_sdk_aggregate_once_not_twice(self) -> None:
+        # The hooks already added every completed turn by the time the run raises, and the exception
+        # carries the SDK's aggregate over those same turns. Adding one to the other roughly doubles
+        # the reported cost of any run that failed after paid turns.
+        turns = [
+            {
+                "output": _text_output("one"),
+                "usage": {"input_tokens": 30, "output_tokens": 5},
+            },
+            {
+                "output": _text_output("two"),
+                "usage": {"input_tokens": 40, "output_tokens": 7},
+            },
+        ]
+
+        async def run(agent: Any, prompt: str, hooks: Any = None, **kw: Any) -> Any:
+            await _drive_turns(hooks, agent, prompt, turns)
+            raise _AgentsError(70, 12)
+
+        ctx, rec = _recording()
+        agents_mod = _fake_agents_module(run=run)
+        with ctx, _patched_agents(agents_mod), pytest.raises(_AgentsError):
+            await create_openai_agent_handler()(CONFIG, "q", {}, {})
+
+        # 70 and 12 are the aggregate. 140 and 24 would be the aggregate counted twice.
+        assert rec.root.attributes["gen_ai.usage.input_tokens"] == 70
+        assert rec.root.attributes["gen_ai.usage.output_tokens"] == 12
+
+    async def test_falls_back_to_the_turns_it_saw_when_the_error_carries_nothing(
+        self,
+    ) -> None:
+        # A tool handler's own error propagates unwrapped and has no run_data, so the accumulated
+        # turns are the only record of what the run spent.
+        turns = [
+            {
+                "output": _text_output("one"),
+                "usage": {"input_tokens": 30, "output_tokens": 5},
+            }
+        ]
+
+        async def run(agent: Any, prompt: str, hooks: Any = None, **kw: Any) -> Any:
+            await _drive_turns(hooks, agent, prompt, turns)
+            raise RuntimeError("tool exploded")
+
+        ctx, rec = _recording()
+        agents_mod = _fake_agents_module(run=run)
+        with ctx, _patched_agents(agents_mod), pytest.raises(RuntimeError):
+            await create_openai_agent_handler()(CONFIG, "q", {}, {})
+
+        assert rec.root.attributes["gen_ai.usage.input_tokens"] == 30
+
+    async def test_writes_nothing_when_the_run_died_before_any_turn(self) -> None:
+        # All-zero attributes would assert the run cost nothing, which is a different claim.
+        async def run(agent: Any, prompt: str, hooks: Any = None, **kw: Any) -> Any:
+            raise RuntimeError("died immediately")
+
+        ctx, rec = _recording()
+        agents_mod = _fake_agents_module(run=run)
+        with ctx, _patched_agents(agents_mod), pytest.raises(RuntimeError):
+            await create_openai_agent_handler()(CONFIG, "q", {}, {})
+
+        assert "gen_ai.usage.input_tokens" not in rec.root.attributes