Python: Align AG-UI run continuity

[Evan Mattson (moonbox3)]

Motivation & Context

This aligns several AG-UI runtime paths that had evolved independently, reducing surprising differences between normal, interrupted, and follow-up runs.

Description & Review Guide

• What are the major changes?
  • Align workflow continuation bookkeeping across live, snapshot-backed, and checkpoint-backed runs.
  • Keep request-provided tool declarations local to the active run.
  • Clarify related usage guidance and extend regression coverage.
• What is the impact of these changes?
  • AG-UI runs behave more consistently across continuation and sequential-request scenarios.
• What do you want reviewers to focus on?
  • Runtime lifecycle consistency and backward compatibility.

Related Issue

N/A - tracking is handled separately.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

Aligns AG-UI runtime behavior across sequential, interrupted, snapshot-backed, and checkpoint-backed runs.

Changes:

• Makes client tool declarations request-scoped.
• Adds workflow interrupt ownership validation and persistence.
• Expands security guidance and regression coverage.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
python/packages/ag-ui/agent_framework_ag_ui/_workflow.py	Adds workflow interrupt ownership tracking.
python/packages/ag-ui/agent_framework_ag_ui/_tooling.py	Removes persistent client-tool registration.
python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py	Uses run-local merged tools.
python/packages/ag-ui/tests/ag_ui/test_endpoint.py	Adds lifecycle and ownership regressions.
python/packages/ag-ui/tests/ag_ui/test_tooling.py	Removes obsolete registration tests.
python/packages/ag-ui/README.md	Documents conversation trust boundaries.
python/packages/ag-ui/AGENTS.md	Adds security guidance for contributors.
docs/specs/004-python-function-calling-loop.md	Records new continuity guarantees.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui
_agent_run.py	1398	145	89%	158, 218, 237, 284, 302, 318–319, 441, 494–495, 502, 611, 615, 617, 634, 661–662, 716, 745, 759, 763, 767, 770, 775, 780, 789, 792, 799–805, 816, 830, 837, 847, 862, 865, 897, 932, 956, 968–972, 1018, 1033, 1036, 1038, 1064, 1066, 1068, 1071–1075, 1099, 1130, 1166, 1221–1222, 1264, 1278, 1323–1329, 1338, 1346, 1374, 1396, 1400, 1403, 1405, 1465–1466, 1472–1478, 1575, 1579–1580, 1583, 1588–1589, 1592, 1598–1599, 1603–1605, 1623–1625, 1650–1651, 1674–1675, 1688, 1730–1732, 1743–1745, 1747, 1761–1763, 1891, 1899, 1929, 1933, 1978, 2180, 2331, 2333, 2340, 2356, 2415, 2432, 2501, 2644, 2682, 2690, 2692, 2695, 2701, 2756, 2759, 2769–2770, 2777, 2824
_tooling.py	38	0	100%
_workflow.py	261	18	93%	75, 77, 104, 108, 112, 116, 178, 183, 222, 331, 415–416, 420, 444, 459–461, 480
TOTAL	46711	4359	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9423	36 💤	0 ❌	0 🔥	1m 53s ⏱️

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 3866974e66a6
Model: gpt-5.6-sol

Overview

The PR removes shared chat-client mutation for request-scoped client tools and adds ownership checks for direct shared-workflow interrupts, with focused cross-thread, cross-scope, disconnect, and restart tests. The request-local tool merge is well constrained, but the new workflow ownership registry can be overwritten from stale snapshots, retains abandoned entries without bounds, and can leave a durable checkpoint unusable when its auxiliary metadata write fails.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (2 high, 1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/ag-ui/agent_framework_ag_ui/_workflow.py

[github-actions]

MAF Automated Review — Iteration 2

Result: Findings reported
Scope: 1 net-new commit(s): 6e4fbbc24bdf
Model: gpt-5.6-sol

Overview

The PR removes the process-wide owner map and binds ownership to live pending event occurrences, which fixes the previously reported stale-snapshot and unbounded-retention paths. The new tests establish fail-closed behavior for explicitly threaded cold resumes and preserve legacy unthreaded resumes. Residual authorization gaps remain where ownerless checkpoint requests and replayed live interrupts are treated as claimable, and checkpoint preflight now bypasses normal workflow error framing.

Reviewed the supplied incremental change set across correctness, security/reliability, architecture, and failure behavior.
4 verified findings remained after source verification (3 high, 1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/ag-ui/agent_framework_ag_ui/_workflow.py