release: 0.21.1 - #4467

Release readiness review (v0.21.0 -> TARGET ecd7c33)

This is a release readiness report done by $final-release-review skill.

Diff

v0.21.0...ecd7c33

Release intent

• Review mode: final candidate
• Intended release: patch, version 0.21.1
• Minimum required release type: patch
• Versioning verdict: compatible

Release call

🟢 GREEN LIGHT TO SHIP The candidate is a compatible patch release with consistent metadata, a frozen public API contract, and no confirmed release blocker.

Scope summary

• 112 files changed (+11113/-726); key areas touched: model-call timeouts and retry cleanup, sandbox working-directory and provider options, session accounting and persistence, Chat Completions reasoning replay, Realtime lifecycle handling, SQLite safety, documentation, tests, and the three-file release manifest.

Risk assessment (ordered by impact)

1. Model-call timeout and retry lifecycle

   • Risk: 🟢 LOW. Users gain an optional per-attempt timeout without changing default model behavior.
   • Evidence: ModelSettings.timeout is appended with a None default; timeout cleanup preserves streaming ownership, retry classification, cancellation, tracing redaction, and replay-safety checks.
   • Files: src/agents/model_settings.py, src/agents/run_internal/model_retry.py, src/agents/models/openai_responses.py, src/agents/exceptions.py
   • Action: Publish the timeout scope and retry guidance from docs: document v0.21.1 runtime behavior #4460 after 0.21.1 is available.

2. Sandbox path, isolation, and resource options

   • Risk: 🟢 LOW. New working-directory, Docker network-isolation, and Modal sizing options are opt-in and preserve existing defaults.
   • Evidence: SandboxRunConfig.cwd is appended; built-in tools use one POSIX workspace scope; Docker network_mode="none" is validated and persisted; Modal CPU and memory settings survive replacement and snapshot restoration.
   • Files: src/agents/run_config.py, src/agents/sandbox/, src/agents/extensions/sandbox/modal/sandbox.py
   • Action: Keep the validation, non-confinement, persistence, and provider-default qualifiers in the post-release documentation.

3. Durable state and public API freeze

   • Risk: 🟢 LOW. Schema 1.16 and the release contract add behavior without dropping released readers, exports, or positional meanings.
   • Evidence: historical RunState versions remain readable; exact per-call approval decisions override sticky decisions; new public constructor fields are appended or keyword-only; the frozen contract adds ModelTimeoutError, RealtimeModelEndOfStreamEvent, and SandboxWorkspaceScope with no removed exports.
   • Files: src/agents/run_state.py, src/agents/run_context.py, tests/fixtures/run_state/, tests/fixtures/released_api_contract.json
   • Action: Retain the schema corpus and generated v0.21.1 contract as the compatibility baseline for the next release.

4. Provider, session, and Realtime correctness fixes

   • Risk: 🟢 LOW. The release corrects reasoning replay boundaries, request and compaction usage accounting, SQLite table ownership, provider cleanup, raster validation, and clean Realtime stream termination.
   • Evidence: BASE-versus-TARGET paths preserve native reasoning precedence, count completed Responses calls without inventing token data, reject ambiguous SQLite ownership before access, and distinguish normal Realtime end-of-stream from abnormal disconnects.
   • Files: src/agents/models/, src/agents/memory/, src/agents/extensions/memory/advanced_sqlite_session.py, src/agents/realtime/
   • Action: Preserve the tested adapter, persistence, and normal-versus-error lifecycle boundaries.

Documentation coverage (non-blocking)

• Coverage source: docs: document v0.21.1 runtime behavior #4460 at head d3a998d73216529a010ed4982482d08758e90e37, plus the target's generated Realtime model-events reference.
• Status: covered
• Covered obligations: per-attempt model timeout and retries, run-scoped sandbox cwd, Docker network isolation, Modal resource sizing, automatic compaction usage accounting, and the new Realtime end-of-stream event reference.
• Gaps or post-release suggestions: none required for release readiness.
• Publication timing: merge docs: document v0.21.1 runtime behavior #4460 after the 0.21.1 package is available because it documents unreleased behavior.

Notes

• The prospective packaged-contract gate and final released-contract check succeeded on the exact candidate base.
• The final refresh confirmed that the release commit parent is current origin/main.