Atomic cancellation receipts for long-running stop-streaming flows

[davidahmann]

Problem observed

In live stop/cancel flows for long-running tools, cancellation responses were emitted without a dedicated persisted cancellation marker in state delta. That means replay/session reconstruction could infer outcome only from textual response payloads or transient runtime context. If interruption occurred around cancellation handling, durable state lacked a single canonical cancellation-status receipt.

Why it matters operationally

Long-running tools are increasingly used in production-like streams, where operators need deterministic postmortem state. Durable cancellation markers reduce ambiguity for resume, replay, and audit trails. Without them, investigations depend on event text parsing and can misclassify whether a stream was cleanly cancelled, still pending cancellation, or never active at the time of stop request.

Minimal repro

1. Start a live invocation that registers a streaming tool task.
2. Invoke stop_streaming for that tool.
3. Inspect persisted event state deltas for a durable cancellation outcome key.

Fix approach

Stop-streaming handling now writes cancellation outcomes atomically into state delta under _adk_long_running_tool_cancellations. The same response path records cancelled, pending, or not_found, so cancellation state and response outcome are persisted together. This keeps behavior fail-closed for replay by producing a stable machine-readable receipt in the same update boundary.

Validation evidence

• uv run pyink --check --diff src/google/adk/flows/llm_flows/functions.py tests/unittests/flows/llm_flows/test_functions_stop_streaming_state.py passed.
• uv run pytest tests/unittests/flows/llm_flows/test_functions_stop_streaming_state.py -q passed.
• Added focused async tests for successful cancel and missing-stream outcomes.

Open follow-up question for maintainers

Would you prefer formalizing _adk_long_running_tool_cancellations as a documented stable key, or keeping it internal while exposing a higher-level helper later?

This contribution was informed by patterns from Wrkr. Wrkr scans your GitHub repo and evaluates every AI dev tool configuration against policy.: https://github.com/Clyra-AI/wrkr