Expose the /run_sse event serialization as a public function and allow an optional SSE keep-alive #7578

🔴 Required Information

Is your feature request related to a specific problem?

Applications that need different run semantics than the built-in /run_sse
(for example running the Runner outside the HTTP request, or fronting it with
their own transport) still want to emit the same wire format so existing ADK
clients keep working. Today that format is not reusable:

• The serialization lives inline in the nested event_generator() in
  cli/api_server.py. It combines three steps: the artifactDelta split into a
  content event and an action-only event, public_event(...) from
  events/_internal_metadata.py, and _redact_credential_secrets(...) from
  auth/auth_credential.py, then pydantic_core.to_json(...).
• Two of those helpers are private (underscore module / name), so a downstream
  implementation has to copy the logic and keep it in sync by hand.

The sync cost is real. The framing changed in 2.11 (public_event was
introduced into the stream) and again in 2.12 (credential redaction), and each
time a downstream copy had to be updated and its golden-framing test re-pinned.
A copy that silently diverges either leaks fields the server hides or drops
fields clients expect.

Separately, the stream is silent while the agent waits on a slow tool: nothing
is written between events, and the response writes no periodic frame. Proxies and
clients that treat prolonged silence as a dead stream close it. (Combined with
abort-on-disconnect, see #4029, that ends the run.)

Describe the Solution You'd Like

1. A public, documented function that turns an Event into the SSE frame
   exactly as run_agent_sse does (including the redaction step), used by
   run_agent_sse itself so the two cannot diverge. For example
   google.adk.cli.sse.format_event_frame(event, *, split_artifact_delta=True).
2. An optional keep-alive for /run_sse: when no event has been written for N
   seconds, emit an SSE comment (: keep-alive\n\n), which clients ignore per the
   SSE spec. Off by default, so existing behavior is unchanged.

Impact on your work

We maintain a downstream implementation of the stream and re-verify it against
every ADK minor. A public serializer turns that from "diff a private handler" into
"call a function". The keep-alive removes the need for us to inject comment frames
ourselves.

Willingness to contribute

Yes, for both. Item 1 is a refactor with a unit test that asserts the function and
the handler produce identical bytes. Item 2 is a small timer in the generator plus
a test. I would send them as two separate PRs.

🟡 Recommended Information

Describe Alternatives You've Considered

• Copying the serialization (current approach): works, but must be re-checked on
  every release, as the 2.11 and 2.12 changes showed.
• Wrapping /run_sse in a proxy that re-frames the response: loses event-level
  control and adds a hop.
• Comment frames written by a wrapper around the stream: fine as a workaround,
  but every deployment has to reinvent it.

Proposed API / Implementation

# google/adk/cli/sse.py (illustrative)
def format_event_frame(event: Event, *, split_artifact_delta: bool = True) -> list[str]:
  """Returns the `data: ...\n\n` frame(s) `run_agent_sse` writes for `event`."""

# get_fast_api_app(..., sse_keep_alive_seconds: float | None = None)

Additional Context

The contract is already de facto public: clients consume it. This asks for it to
be explicit and shared rather than copied.