Python: Add timeout for wait-for-first-completion

[westey (westey-m)]

Motivation & Context

Without a timeout, waiting for background agents can continue indefinitely.

Description & Review Guide

Allow developers to specify a timeout.

Related Issue

Fixes #7454

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

Adds a configurable bounded wait for Python background agents, preventing indefinite blocking.

Changes:

• Adds a five-minute default and configurable wait timeout.
• Returns normally on timeout without stopping background tasks.
• Adds validation and timeout-focused tests.

Reviewed changes

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

Show a summary per file

File	Description
_background_agents.py	Implements timeout behavior and validation.
_agent.py	Exposes timeout through harness creation.
_agent.pyi	Updates the public typing signature.
test_harness_background_agents.py	Tests defaults, validation, and timeout behavior.
test_harness_agent.py	Tests harness timeout forwarding.
_workflows/_agent.py	Formatting-only change.
_harness/_loop.py	Formatting-only changes.

---

💡 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/core/agent_framework/_harness
_agent.py	132	2	98%	203, 642
_background_agents.py	350	39	88%	144–145, 147–150, 152–153, 197, 222–223, 248–250, 253–254, 257–258, 426, 436, 440–443, 457, 495–496, 543, 594, 597, 625, 634, 638, 645–646, 701–704
_loop.py	303	7	97%	493, 532, 626, 703, 746, 821, 977
packages/core/agent_framework/_workflows
_agent.py	324	32	90%	80, 84, 128–129, 278, 291, 358, 369, 371, 427, 438, 493, 563, 641, 671, 699, 746, 755, 816, 823, 829–830, 841, 873, 880, 901, 910, 914, 916–918, 925
TOTAL	48235	4483	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9774	36 💤	0 ❌	0 🔥	2m 38s ⏱️

[github-actions]

MAF Automated Review — Iteration 1

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

Overview

The PR adds a provider-controlled, validated timeout and preserves timed-out tasks so their results can be observed later. The new tests cover validation, propagation, timeout return, and retained task state. However, returning control while timed-out tasks continue running creates an unbounded allocation loop with no automatic production cleanup, exposing shared process resources to persistent exhaustion.

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

Affected areas: python/packages/core/agent_framework/_harness/_background_agents.py