release: 0.11.0

[stainless-app]

Automated Release PR

0.11.0 (2026-05-05)

Full Changelog: v0.10.4...v0.11.0

Features

• openai_agents: expose real usage, response_id, plumb previous_response_id, opt-in prompt_cache_key for stateful responses and prompt caching (#335) (ba5d64b)

Chores

• internal: reformat pyproject.toml (76e0299)
• internal: version bump (0d318ad)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

Greptile Summary

• Introduces batched span dispatch (on_spans_start/on_spans_end) across the tracing stack: AsyncTracingProcessor gets default fan-out implementations, SGPAsyncTracingProcessor overrides them to coalesce all spans in a drain batch into a single upsert_batch HTTP call, and AsyncSpanQueue._process_items is reworked to group spans by processor before dispatching.
• Three issues flagged in prior review threads remain unresolved: _spans is populated before the upsert_batch call (orphaned end events on HTTP failure), shutdown() lacks a disabled guard (crashes with AttributeError when disabled spans are in-flight), and the assert type-guard in _process_items is silently elided under python -O.
• New concern this pass: the default on_spans_start fans out to self.on_span_start, while SGPAsyncTracingProcessor.on_span_start delegates to self.on_spans_start; any future subclass that follows the same delegation pattern without also overriding on_spans_start will hit infinite recursion.

Confidence Score: 4/5

Safe to merge with caveats — the three issues from prior review threads remain open, but they are bounded in scope; the new mutual-recursion trap is P2 only.

Score capped at 4 due to the unresolved P1 shutdown() crash when disabled=True (flagged in a prior thread). No new P0 or P1 issues were introduced in this pass; the mutual-recursion concern and empty-batch HTTP call are P2.

src/agentex/lib/core/tracing/processors/sgp_tracing_processor.py — unresolved shutdown/disabled crash and stale-_spans-on-failure issues from prior review; src/agentex/lib/core/tracing/span_queue.py — assert guard elided under -O.

Important Files Changed

Filename	Overview
src/agentex/lib/core/tracing/processors/sgp_tracing_processor.py	Refactored to delegate single-span methods to batched variants; populates _spans before the HTTP call (stale entry on failure) and shutdown() crashes on disabled=True with in-flight spans — both flagged in previous review threads plus a new empty-batch HTTP call issue.
src/agentex/lib/core/tracing/processors/tracing_processor_interface.py	Adds default on_spans_start/on_spans_end methods that fan out to per-span calls; design creates a mutual-recursion trap for future subclasses that delegate on_span_start → on_spans_start without also overriding on_spans_start.
src/agentex/lib/core/tracing/span_queue.py	Reworked _process_items to group spans by processor and dispatch via batched methods; assert guard for same-event-type precondition is stripped by -O (flagged in prior review thread); logic otherwise sound.
tests/lib/core/tracing/processors/test_sgp_tracing_processor.py	Adds batch start/end tests verifying single upsert_batch call and correct span tracking; coverage is thorough for the happy path.
tests/lib/core/tracing/processors/test_tracing_processor_interface.py	New test file verifying default fanout behavior, failure isolation, and per-span error logging; well-structured.
tests/lib/core/tracing/test_span_queue.py	Adds TestProcessItemsPreconditions and TestAsyncSpanQueueBatchedDispatch suites; mock helper updated to fan out batched calls to per-span mocks for backwards-compatible test assertions.

Sequence Diagram

sequenceDiagram
    participant Q as AsyncSpanQueue
    participant PI as _process_items
    participant AP as AsyncTracingProcessor (default)
    participant SGP as SGPAsyncTracingProcessor

    Q->>PI: _process_items(starts)
    PI->>PI: group spans by processor
    PI->>SGP: on_spans_start([span_a, span_b, ...])
    SGP->>SGP: populate _spans[id] for each
    SGP->>SGP: if disabled → return
    SGP-->>SGP: upsert_batch(all spans in one HTTP call)

    Note over PI,AP: Processor using default fallback
    PI->>AP: on_spans_start([span_a, span_b])
    AP->>AP: asyncio.gather(on_span_start(a), on_span_start(b))
    AP-->>AP: per-span exceptions caught and logged

    Q->>PI: _process_items(ends)
    PI->>SGP: on_spans_end([span_a, span_b, ...])
    SGP->>SGP: pop _spans, update fields
    SGP-->>SGP: upsert_batch(ended spans)

    Q->>SGP: shutdown()
    SGP-->>SGP: upsert_batch(_spans remaining)
    Note over SGP: crashes if disabled=True with spans in-flight

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
src/agentex/lib/core/tracing/processors/tracing_processor_interface.py:44-65
**Mutual-recursion trap for future processor implementations**

The default `on_spans_start` fans out to `self.on_span_start`, and `SGPAsyncTracingProcessor.on_span_start` delegates back to `self.on_spans_start([span])`. This only works today because `SGPAsyncTracingProcessor` also overrides `on_spans_start`. Any future subclass that follows the same delegation pattern in `on_span_start` (calling `self.on_spans_start([span])`) but forgets to override `on_spans_start` will hit infinite recursion: default `on_spans_start` → `on_span_start` → `on_spans_start` → …. The docstring should explicitly warn that processors overriding `on_span_start` to delegate to `on_spans_start` must also override `on_spans_start`, otherwise they create an infinite loop.

### Issue 2 of 2
src/agentex/lib/core/tracing/processors/sgp_tracing_processor.py:190-195
**`shutdown()` sends an unnecessary HTTP request when `_spans` is empty**

In the normal case where all spans are properly closed before shutdown, `_spans` is empty and `shutdown()` still calls `upsert_batch(items=[])`. This is a pointless network round-trip every time the processor shuts down cleanly. A guard like `if not self._spans: return` (after any disabled check) would avoid the empty call.

_{Reviews (10): Last reviewed commit: "release: 0.11.0" | Re-trigger Greptile}

[greptile-apps]

assert in production guard defeats data-corruption protection

The code comment correctly identifies this as a potential "silent data-corruption bug," but using assert for the guard means it is silently stripped when Python runs with the -O (optimize) flag. If a caller ever passes a mixed-event-type list, START and END spans would be fed to the wrong batched method with no warning. Use an explicit if/raise instead.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/core/tracing/span_queue.py
Line: 107-111

Comment:
**`assert` in production guard defeats data-corruption protection**

The code comment correctly identifies this as a potential "silent data-corruption bug," but using `assert` for the guard means it is silently stripped when Python runs with the `-O` (optimize) flag. If a caller ever passes a mixed-event-type list, START and END spans would be fed to the wrong batched method with no warning. Use an explicit `if/raise` instead.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

_spans populated before upsert — stale entries on HTTP failure

Spans are added to self._spans before the upsert_batch HTTP call (lines 155–156). If the batch upsert throws (network error, server 5xx), the exception is caught upstream by the queue's _handle, but _spans already holds entries for spans whose start event was never delivered to SGP. A subsequent on_spans_end will find those spans, update them, and send end-only upserts — orphaned end events with no matching start on the server.

The old single-span code registered the span in _spans only after a successful upsert, so failures were cleanly skipped on the end path. Consider populating _spans only after confirming the batch call succeeded, or rolling back entries on exception.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/core/tracing/processors/sgp_tracing_processor.py
Line: 141-163

Comment:
**`_spans` populated before upsert — stale entries on HTTP failure**

Spans are added to `self._spans` before the `upsert_batch` HTTP call (lines 155–156). If the batch upsert throws (network error, server 5xx), the exception is caught upstream by the queue's `_handle`, but `_spans` already holds entries for spans whose start event was never delivered to SGP. A subsequent `on_spans_end` will find those spans, update them, and send end-only upserts — orphaned end events with no matching start on the server.

The old single-span code registered the span in `_spans` only after a successful upsert, so failures were cleanly skipped on the end path. Consider populating `_spans` only after confirming the batch call succeeded, or rolling back entries on exception.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

shutdown() crashes with AttributeError when disabled=True and spans are in-flight

on_spans_start now populates self._spans (line 155) before the if self.disabled: return guard (line 158). If any spans are started but not yet ended when shutdown() is called in disabled mode, it reaches self.sgp_async_client.spans.upsert_batch(...) where self.sgp_async_client is None, triggering an AttributeError. Before this PR the disabled path returned before populating _spans, so _spans was always empty at shutdown time and this was never triggered in practice. The fix is to either move the self._spans[span.id] = sgp_span assignment after the if self.disabled guard, or add an early if self.disabled: return check at the top of shutdown() (mirroring how on_spans_end handles it at line 184).

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/core/tracing/processors/sgp_tracing_processor.py
Line: 154-163

Comment:
**`shutdown()` crashes with `AttributeError` when `disabled=True` and spans are in-flight**

`on_spans_start` now populates `self._spans` (line 155) **before** the `if self.disabled: return` guard (line 158). If any spans are started but not yet ended when `shutdown()` is called in disabled mode, it reaches `self.sgp_async_client.spans.upsert_batch(...)` where `self.sgp_async_client` is `None`, triggering an `AttributeError`. Before this PR the disabled path returned before populating `_spans`, so `_spans` was always empty at shutdown time and this was never triggered in practice. The fix is to either move the `self._spans[span.id] = sgp_span` assignment after the `if self.disabled` guard, or add an early `if self.disabled: return` check at the top of `shutdown()` (mirroring how `on_spans_end` handles it at line 184).

How can I resolve this? If you propose a fix, please make it concise.