fix(stream-events): enforce timeout_secs after a silent backend

[mkoushni]

Summary

openai_stream_events.timeout_secs was only checked when an SSE chunk or end-of-stream arrived. After the first event, a silent backend never invokes those callbacks, so the documented wall-clock budget did not fire.

• Cap the selected peer's read_timeout at timeout_secs (without relaxing a tighter cluster timeout) from on_request and on_request_body.
• Treat IRR idle/deadline stream termination as a stream timeout and record the same responses.stream_error_* metadata as a parser timeout.
• Pair the stream-events and agentic-loop examples with cluster read_timeout_ms so a silent connection is torn down without waiting for another body callback.

A filter-only timer cannot wake Pingora without body traffic. Cluster read_timeout_ms remains the reliable idle deadline when load balancing has not yet set ctx.upstream.

Related issue

Closes #938

Validation

• Unit tests
• Integration or functional tests
• make lint

cargo clippy -p praxis-ai-apis --all-targets -- -D warnings
cargo test -p praxis-ai-apis --lib -- stream_events
cargo test -p praxis-tests-integration --test suite -- \
  stream_events_idle_backend_is_cut_off_by_read_timeout \
  stream_events_accumulates_state

The new integration test sends one response.in_progress event, stalls 10s, and asserts the proxy cuts the stream in under 4s via read_timeout_ms: 1000 plus timeout_secs: 1.

Checklist

• I reviewed every changed line and can explain the change.
• New capabilities include an example config and functional example test.
• User-facing behavior and generated documentation are updated.
• Commits are signed and include a Signed-off-by trailer.

[praxis-bot]

Review: fix(stream-events): enforce timeout_secs after a silent backend

Well-structured change. The approach of capping the upstream read_timeout at timeout_secs and then recognizing transport-level idle timeouts as stream timeouts is sound. The validate_stream_end refactoring into StreamEndKind is cleaner than the original.

One correctness concern below.

Severity	Count
Medium	1

[leseb]

blocked by #1013 since this uses logical_stream and 1031 removes it

in the meantime:

P2 — Lines 330–333 ignore the actual filter-induced timeout classification. Praxis 0.5.4 reports a winning peer read_timeout as StreamTerminationCause::Io, not IdleTimeout; logical error bytes are then discarded because IRR still considers the termination unhandled.
P2 — Lines 311–316 implement a per-read timeout, not the documented duration “from first chunk to completion.” It can expire before the first event, while a stream that stalls near the deadline can survive almost twice the configured duration.

[leseb]

P1: timeout_secs is never applied in the documented IRR ordering because both cap attempts occur before load balancing selects ctx.upstream. The integration test passes only because it separately sets read_timeout_ms.
P2: matching every StreamTerminationCause::Io mislabels ordinary transport failures as timeouts. Coverage fails deterministically: 622 passed, 1 failed.
P2: read_timeout remains per-read, not an absolute deadline from the first SSE chunk; it may fire before that chunk or permit nearly 2T.

[mkoushni]

P1 — cap after load balancing. openai_responses_proxy buffers the request body, so IRR runs that phase before load_balancer sets ctx.upstream. Both earlier cap attempts were no-ops; the idle test only passed because it also set read_timeout_ms: 1000. The documented stream-events.yaml (and irr-terminal-streaming.yaml) now place openai_stream_events after load_balancer, and on_request caps the selected peer. The idle test no longer tightens cluster read_timeout_ms.

Agentic configs keep the filter before openai_agentic_loop so the loop still sees raw SSE on the reverse response path. Idle there still pairs with cluster read_timeout_ms.

P2 — Io mislabel. Praxis reports a winning peer read_timeout as Io, but so do truncated chunks. Io is a stream timeout only after a first SSE chunk and timeout_secs has elapsed. late_upstream_failure_does_not_replace_committed_sse now asserts the body does not contain exceeded timeout.

P2 — remaining budget. The parser deadline still starts at the first SSE chunk. After that chunk the peer cap is the leftover time, not another full period. Praxis snapshots read_timeout at dispatch, so later remaining-budget caps apply only while ctx.upstream is still visible.

[leseb]

@mkoushni final

After each chunk, the filter tries to shorten ctx.upstream.read_timeout, but IRR response-body contexts have upstream: None; Praxis already copied the original timeout into the live body. A chunk near deadline therefore restarts the full per-read timer, allowing nearly 2T instead of an absolute T.

[leseb]

blocked on 0.5.6 core release

[leseb]

ready once rebased over #1203