feat(runners): stop a live agent and edit a previous prompt

[a2105z]

Link to Issue or Description of Change

• Closes: Stop a Running Agent / Edit a previous prompt #3849
• Related: Add an API Endpoint to Cancel In-Progress Agent Tasks #2425, Add Force Stop Capability to Interrupt Agent Reasoning or Tool Calls #2853

Summary

This issue has been open since December. Chat UIs still cannot stop a live agent or edit a previous prompt.

Stop. Runner.cancel_async(user_id=, session_id=, invocation_id=None) aborts the live invocation: LLM loops see end_invocation, blocked tool/model work is cancelled, and an interrupted=True event is persisted. POST /apps/{app}/users/{user}/sessions/{session}/cancel exposes it. /run_sse also cancels when the client disconnects, matching /run.

Edit. Runner.edit_message_async(...) cancels anything in flight on that session, rewinds to the targeted user turn (rewind_async), then regenerates with the new prompt. POST /apps/{app}/users/{user}/sessions/{session}/edit exposes it.

await runner.cancel_async(user_id="u", session_id="s")

async for event in runner.edit_message_async(
    user_id="u",
    session_id="s",
    invocation_id="inv-of-the-user-turn",
    new_message=types.Content(role="user", parts=[types.Part(text="edited")]),
):
    ...

POST /apps/my_app/users/u/sessions/s/cancel
{"invocationId": "optional-live-id"}

POST /apps/my_app/users/u/sessions/s/edit
{"invocationId": "inv-of-the-user-turn", "newMessage": {"role": "user", "parts": [{"text": "edited"}]}}

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

uv run python -m pytest tests/unittests/test_runners_stop_and_edit.py tests/unittests/test_runners.py tests/unittests/cli/test_fast_api.py -q -k "run_async or rewind or run_sse or cancel or edit_agent or agent_run"
102 passed in test_runners.py + stop/edit
23 passed for the API / runner filter above

Covers: cancel of a blocked BaseAgent and LlmAgent, idempotent cancel, edit of a completed earlier turn, edit of a live turn (cancel + rewind + regenerate), REST cancel/edit, existing /run_sse disconnect tests.

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.

Additional context

cc @sertacakdogan @klateefa @wuliang229 @Jacksunwei @yeesian @xuanyang15 @steren @llalitkumarrr @GWeale — ready for review. This is the ChatGPT-class stop + edit-prompt flow requested on #3849 (open since Dec 2025).