Summary

Decouples store_media from in-run media availability. Previously, store_media=False prevented media from appearing in both the DB and the returned RunOutput, making it impossible to forward generated images/videos/audio to external services (WhatsApp, Slack) immediately after a run.

Now store_media controls only DB persistence. Generated media is always available on the returned RunOutput for the caller to act on.

Closes #5101

Bugs Fixed

This PR fixes 4 distinct bugs in the media pipeline:

Bug 1: store_media=False strips media from RunOutput

store_media_util() — which copies media from ModelResponse to RunOutput — was gated behind if agent.store_media: in all 10 run paths (4 agent + 6 team). When store_media=False, media was never placed on RunOutput, so callers couldn't forward images to WhatsApp/Slack.

Fix: Remove the gate. store_media_util() always runs. DB scrubbing happens later in cleanup_and_store.

Bug 2: Streaming images gated on store_media (asymmetry)

In handle_model_response_chunk, only images were gated behind if agent.store_media:. Videos, audio, and files were never gated. This meant streaming with store_media=False dropped images but not other media types.

Fix: Remove the gate. All media types are now consistent — always collected into run_response during streaming.

Bug 3: Session cache aliasing leaks media back to DB

After cleanup_and_store scrubbed media and stored the run, session.upsert_run(run=run_response) stored a reference to the same RunOutput object. If media was later restored on that object (e.g., via try/finally), subsequent save_session() calls would re-persist the old run with restored media — leaking it to DB despite store_media=False.

Fix: session.upsert_run(run=copy.copy(run_response)) — shallow copy breaks reference aliasing so the session cache holds an independent scrubbed snapshot.

Bug 4: scrub_media_from_run_output missed top-level output fields

scrub_media_from_run_output() scrubbed input and message media but didn't null the top-level output fields (images, videos, audio, files). This caused team member responses and workflow executor runs to leak media to DB when store_media=False, because _scrub_member_responses and _store_executor_response delegate to this function.

Fix: Add 4 lines to null top-level output fields. Safe because cleanup_and_store uses storage_copy (caller's original is untouched).

Full Data Lifecycle

BEFORE (store_media=False):

  Model generates image
        |
        v
  store_media_util()  --- if store_media: --- SKIPPED
        |                                       |
        v                                       v
  RunOutput.images = []           Media never reaches RunOutput
        |
        v
  cleanup_and_store()
        |
        +-- scrub input/messages --> DB gets scrubbed input
        |
        +-- upsert_run(run_response) --> session holds REFERENCE
        |
        +-- save_session() --> DB gets no media
        |
        v
  Caller gets RunOutput.images = None   <-- can't forward to WhatsApp/Slack


AFTER (store_media=False):

  Model generates image
        |
        v
  store_media_util()  --- ALWAYS runs --> RunOutput.images = [img]
        |
        v
  cleanup_and_store()
        |
        +-- storage_copy = copy.copy(run_response)  <-- breaks aliasing
        |
        +-- scrub_run_output_for_storage(storage_copy)
        |       |
        |       +-- scrub input/message media
        |       +-- null images/videos/audio/files
        |
        +-- upsert_run(storage_copy) --> session holds SCRUBBED COPY
        |
        +-- save_session() --> DB gets no media
        |
        v
  Caller gets RunOutput.images = [img]   <-- forwards to WhatsApp/Slack


TEAM MEMBER RESPONSES (store_media=False on member):

  Member agent generates image
        |
        v
  store_media_util() --> member RunOutput.images = [img]
        |
        v
  _scrub_member_responses()
        |
        +-- scrub_run_output_for_storage(member, member_response)
        |       |
        |       +-- scrub_media_from_run_output(member_response)
        |       |       |
        |       |       +-- null input/message media
        |       |       +-- null images/videos/audio/files  <-- Bug 4 fix
        |       |
        |       +-- (permanent scrub, no restore)
        |
        v
  Team session saved --> member media NOT in DB

Files Changed

Test Coverage (25 tests)

Agent core (8 tests) — test_store_media_run_output.py

• sync/async x non-streaming/streaming x yield_run_output/stream_events
• Regression: store_media=True still works

Scrub + DB isolation (10 tests) — test_store_media_scrub_leak.py

• scrub_media_from_run_output nulls all 4 media types (images/videos/audio/files)
• Works on both RunOutput and TeamRunOutput
• Member response scrubbing via scrub_run_output_for_storage
• store_media=True preserves media (regression guard)
• cleanup_and_store restores media for caller (sync + async)
• Session cache does NOT contain media when store_media=False

Slack integration (7 tests) — test_slack_store_media.py

• Non-streaming: mock agent, real Agent with store_media=False
• Streaming: completion chunks, content chunks with multi-image
• Real Agent streaming with store_media=False
• Regression: store_media=True still uploads

Design Decisions

Why copy.copy() instead of deepcopy?
Shallow copy is sufficient because we only need to break top-level field aliasing (storage_copy.images = None doesn't affect run_response.images). Deep copy would unnecessarily clone large media objects. Input/message media IS shared between the copy and original — this is acceptable because scrub_run_output_for_storage has always scrubbed those on the original in pre-PR code.

Why explicit nulling after scrub_run_output_for_storage?
Defensive — scrub_media_from_run_output now also nulls these fields, but the explicit block makes the intent clear at the cleanup_and_store call site.

Interaction with _scrub_member_responses:
For team member responses, scrub_media_from_run_output is called permanently (no save/restore). The top-level nulling fix (Bug 4) is critical here — without it, member-generated images leak to DB even when the member has store_media=False.

Related Issues

Type of change

• Bug fix
• New feature
• Breaking change
• Improvement
• Model update
• Other:

Checklist

• Code complies with style guidelines
• Ran format/validation scripts (./scripts/format.sh and ./scripts/validate.sh)
• Self-review completed
• Documentation updated (comments, docstrings)
• Examples and guides: Relevant cookbook examples have been included or updated (if applicable)
• Tested in clean environment
• Tests added/updated (25 new tests)