fix(responses): add aggregate memory budget

[eoinfennessy]

Closes #953

Summary

Add request-wide retained-payload accounting for OpenAI Responses agentic executions. This bounds memory retained across loop state, response history, SSE parsing, tool dispatch, response-store persistence, and terminal serialization while preserving canonical ownership of response data.

Changes

• Add openai_agentic_loop.max_retained_bytes:
  • Default: 64 MiB
  • Valid range: 4 KiB–256 MiB
  • The smallest configured value wins across loop instances.
• Enforce max_infer_iters against Praxis’ global iteration ceiling.
• Add aggregate payload accounting to ResponsesState, including independently owned JSON values, strings, buffers, parser state, approval records, and sibling-filter state.
• Replace cloned dispatcher payloads with indexed assignments and borrowed views where possible.
• Make response finalization transactional:
  • Initial overflow returns HTTP 413.
  • Buffered continuation overflow returns HTTP 502.
  • Already-committed streams emit one SSE error event without response.completed or [DONE].
  • Failed requests skip persistence and release retained payload state.
• Bound transient SSE parser/event/frame ownership, tool-call argument accumulation, local lifecycle synthesis, terminal canonicalization, usage merging, and citation annotation staging.
• Coordinate the loop owner and dispatchers so request-side mutations occur only after all budget admissions and each provider response is processed once.
• Apply aggregate budgeting to:
  • File-search response decoding, model-context formatting, public results, citations, and in-place output reconciliation.
  • MCP result batches, approval resumption, deferred discovery, and approval output generation.
  • Web-search response bodies, result formatting, bridge messages, and indexed output updates.
• Add response-store payload accounting and size-only pending-approval queries for SQLite and PostgreSQL. Oversized approval resumptions remain retryable and are not consumed.
• Preserve ordered built-in max_tool_calls accounting across web search and file search while keeping MCP on its independent limit.
• Document the new configuration and add an overflow example configuration.

Tests

• Expanded unit coverage for retained-payload accounting, ownership transitions, streaming overflow, terminal construction, file search, web search, MCP approvals, persistence, citations, and usage merging.
• Added OpenAI SDK integration coverage for buffered and streaming requests using the explicit retained-payload budget.
• Added a synthetic inference fixture proving that committed-stream overflow emits exactly response.created plus error, suppresses [DONE], and does not persist the response.
• Updated inference fixture coverage and generated documentation.

[eoinfennessy]

@leseb, this is finally ready for review. The changes became much larger than originally anticipated, but I'm not sure if there's anyway I could split this up into more manageable PRs.

[praxis-bot]

Review: fix(responses): add aggregate memory budget

Comprehensive review of the retained-payload accounting system across agentic loop, dispatchers, streaming, and persistence.

Summary

This is a large, carefully structured change that adds request-wide memory budgeting to the Responses agentic execution. The design is sound: every independently owned value is accounted for, preflighted transactionally before mutation, and budget-failed requests are terminated cleanly with appropriate HTTP status codes (413 initial, 502 continuation, SSE error post-commit). The indexed dispatch assignments (OutputAssignment, WebSearchAssignment, ToolCallAssignment) are a meaningful improvement over the previous clone-heavy approach, both for memory and for correctness of the budget model.

Test coverage is thorough -- dedicated tests for transactional rejection before state mutation, streaming overflow producing exactly one error without [DONE], approval resumption leaving unconsumed records retryable, file-search formatting preflight, and allocation comparison benchmarks.

No Critical or Large findings. Two Medium findings below.

[praxis-bot]

Resolved by b9e322a

The fragile string matching has been replaced with a shared constant RETAINED_PAYLOAD_OVERFLOW_MESSAGE used in both locations.

[eoinfennessy]

Hey @leseb, should I continue rebasing and fixing tests? Or do we want to defer this change to a future milestone?

[leseb]

Hey @leseb, should I continue rebasing and fixing tests? Or do we want to defer this change to a future milestone?

We need to rework this in smaller PRs and continue this in 0.5.0:

1. Safety guardrail: aggregate budget, iteration cap, fail-closed wire behavior, boundary tests. Release blocker.
2. Core ownership: ResponsesState and agentic_loop move/index refactor.
3. Streaming lifecycle: parser accounting, terminal construction, committed-stream overflow.
4. MCP and persistence: dispatch, approvals, response-store sizing and retryability.
5. Hosted tools: file/web search, citations, formatting, and relevant allocation benchmarks.

wdyt? if you agree let's close this one

[eoinfennessy]

Hey @leseb, should I continue rebasing and fixing tests? Or do we want to defer this change to a future milestone?

We need to rework this in smaller PRs and continue this in 0.5.0:

1. Safety guardrail: aggregate budget, iteration cap, fail-closed wire behavior, boundary tests. Release blocker.
2. Core ownership: ResponsesState and agentic_loop move/index refactor.
3. Streaming lifecycle: parser accounting, terminal construction, committed-stream overflow.
4. MCP and persistence: dispatch, approvals, response-store sizing and retryability.
5. Hosted tools: file/web search, citations, formatting, and relevant allocation benchmarks.

wdyt? if you agree let's close this one

@leseb, that sounds good to me - I could turn the original issue into an epic if you think that makes sense? Number 2 on the list will still likely be a huge cross-cutting change though, although probably no avoiding that.

[leseb]

Hey @leseb, should I continue rebasing and fixing tests? Or do we want to defer this change to a future milestone?

We need to rework this in smaller PRs and continue this in 0.5.0:

1. Safety guardrail: aggregate budget, iteration cap, fail-closed wire behavior, boundary tests. Release blocker.
2. Core ownership: ResponsesState and agentic_loop move/index refactor.
3. Streaming lifecycle: parser accounting, terminal construction, committed-stream overflow.
4. MCP and persistence: dispatch, approvals, response-store sizing and retryability.
5. Hosted tools: file/web search, citations, formatting, and relevant allocation benchmarks.

wdyt? if you agree let's close this one

@leseb, that sounds good to me - I could turn the original issue into an epic if you think that makes sense? Number 2 on the list will still likely be a huge cross-cutting change though, although probably no avoiding that.

yes small epic with sub issues please