Python: include checkpoint_id on AG-UI interrupt metadata (#8150)

[lsmlhi_25 (FOWEPJF255)]

Motivation & Context

AG-UI workflow interrupts need a durable pause checkpoint_id so multi-worker clients can resume via forwardedProps.checkpoint_id without a side-channel lookup (Option A from #8150).

Description & Review Guide

• What are the major changes?
  • Attach the pause checkpoint_id to each interrupt's metadata.agent_framework when AG-UI workflow runs finish with interrupts and checkpoint storage is active.
  • Prefer this runner's last-saved pause checkpoint over shared get_latest(workflow_name=...) (avoids cross-owner races / stale ids).
  • Resolve builder-configured checkpoint storage via the workflow runner when run_workflow_stream does not pass checkpoint_storage.
  • Skip storage work when interrupts is empty; remove the unused checkpoint_id kwarg on _workflow_interrupt_metadata.
• What is the impact of these changes?
  • Clients can round-trip the pause checkpoint id from interrupt metadata for durable resume across workers.
• What do you want reviewers to focus on?
  • Correctness of pause-id selection vs shared get_latest, builder-only storage path, and empty-interrupt short-circuit.

Related Issue

Fixes #8150

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]

🟡 Changes recommended

Checkpoint selection can advertise a stale or different request owner’s checkpoint ID.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds checkpoint IDs to AG-UI workflow interrupt metadata for durable multi-worker resume.

Changes:

• Resolves and attaches pause checkpoint IDs to interrupts.
• Adds helper and checkpoint-resume coverage.

File summaries

File	Description
_workflow_run.py	Adds checkpoint lookup and interrupt metadata enrichment.
test_workflow_run.py	Tests attachment and checkpoint ID propagation.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 3
• Review effort level: Balanced

---

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

[lsmlhi_25 (FOWEPJF255)]

Addressed review feedback:

1. Stop using shared get_latest(workflow_name=...) (races across owners / stale ids). Prefer this runner's _previous_checkpoint_id and only advertise it when the checkpoint's pending request set covers the interrupt ids.
2. Resolve builder-configured storage via the workflow runner when run_workflow_stream does not pass checkpoint_storage.
3. Skip storage work when interrupts is empty; remove the unused checkpoint_id kwarg on _workflow_interrupt_metadata.
4. Added regression tests for competing shared latest + builder-only storage.

[Evan Mattson (moonbox3)]

lsmlhi_25 (@FOWEPJF255):

1. Please update the PR body to use our approved template: https://github.com/microsoft/agent-framework/blob/main/.github/pull_request_template.md
2. Per our contributing guidelines, please respond to all open PR comments as to whether they're addressed or not. Then resolve the threads once done.
3. Please also fix the failing code quality checks.

[lsmlhi_25 (FOWEPJF255)]

Evan Mattson (@moonbox3) Thanks 鈥?addressed your checklist:

1. PR body updated to the approved template.
2. Replied on each review thread and resolved them.
3. Pushed a follow-up for the failing code quality checks: ruff I001 (import blank line) and ty ignores on the new yield_output("done") test helpers.

[lsmlhi_25 (FOWEPJF255)]

Evan Mattson (@moonbox3) Follow-up for the run-scoped / core-helper review:

• Workflow.get_last_checkpoint_id() + Workflow.resolve_pause_checkpoint_id(...) in core (storage precedence, pending-request coverage, run-scoped baseline filter).
• AG-UI captures the baseline before workflow.run() and no longer digs into Runner private fields for pause-id selection.
• Regression tests in core test_pause_checkpoint_resolve.py and AG-UI run-scoped coverage.

Commit: 68f5abe.

[lsmlhi_25 (FOWEPJF255)]

Merged the pause-checkpoint ownership follow-up on the PR branch (FOWEPJF255#2). Ready for another maintainer pass.

[lsmlhi_25 (FOWEPJF255)]

All open review threads from Evan Mattson (@moonbox3) / Eduard van Valkenburg (@eavanvalkenburg) are addressed on the PR head (d42a8b3, via FOWEPJF255#2):

• Workflow owns run baseline + excludes restored checkpoint from pause candidates
• AG-UI reuses _build_run_finished_event (no extra helper / issue link in docstring)
• Core tests live in test_workflow.py (no dedicated bug-fix test file)

Ready for another look when you have a moment.

[lsmlhi_25 (FOWEPJF255)]

All open review threads from Evan Mattson (@moonbox3) / Eduard van Valkenburg (@eavanvalkenburg) are addressed on the PR head (d42a8b3, via FOWEPJF255#2):

• Workflow owns run baseline + excludes restored checkpoint from pause candidates
• AG-UI reuses _build_run_finished_event (no extra helper / issue link in docstring)
• Core tests live in test_workflow.py (no dedicated bug-fix test file)

Ready for another look when you have a moment.

[LI (ktz03)]

lsmlhi_25 (@FOWEPJF255) Eduard van Valkenburg (@eavanvalkenburg) Follow-up for the builder-storage resume round-trip is ready: FOWEPJF255#5. Please merge into the PR branch when convenient.

[lsmlhi_25 (FOWEPJF255)]

Merged the builder-storage resume round-trip follow-up onto this PR head (f0008da / 1d8d702).

Resume with checkpoint_id + resume now loads pending requests from the workflow's effective builder/runtime storage when AG-UI was not given an explicit checkpoint_storage, matching how pause IDs are emitted for WorkflowBuilder(checkpoint_storage=...).

Coverage: test_builder_checkpoint_storage_resume_without_agui_storage.

[Evan Mattson (moonbox3)]

Please fix failing CI/CD checks.

[Eduard van Valkenburg (eavanvalkenburg)]

Thanks for the contribution. I found one blocking issue in the builder-storage resume path and left it inline. The current Test Typing Checks and Merge Gatekeeper runs are also failing; please address the inline finding and get those checks passing before re-requesting review.

[lsmlhi_25 (FOWEPJF255)]

Fixed the CI typing failure on this head (f9928d7).

Test Typing Checks failed on ty :: ag-ui for the new builder-storage resume test (yield_output expected Never). Aligned the ignore markers with the other HITL helpers: # type: ignore[arg-type] # pyrefly: ignore[...] # ty: ignore[invalid-argument-type].

Please re-run / re-check once workflows refresh.

[lsmlhi_25 (FOWEPJF255)]

Follow-up for Eduard van Valkenburg (@eavanvalkenburg) / Evan Mattson (@moonbox3): builder-owned checkpoint storage now round-trips through AgentFrameworkWorkflow.run() without requiring wrapper/endpoint checkpoint_storage (c37ac97).

Regression: test_workflow_wrapper_resumes_builder_storage_without_agui_storage.

[lsmlhi_25 (FOWEPJF255)]

Evan Mattson (@moonbox3) Eduard van Valkenburg (@eavanvalkenburg) tip c37ac97 (builder-storage resume via AgentFrameworkWorkflow.run()) is up. Same CI gate: workflows on this tip are action_required until a maintainer Approves and runs them.