Python: fix(python): add release_session API to prevent BackgroundAgentsProvider memory leaks

[pratik wayase (PratikWayase)]

Motivation & Context

Currently, BackgroundAgentsProvider keeps non-serializable per-session runtime (tasks, child sessions) in self._runtime, keyed by session_id. Entries are inserted on first use and never removed.

In a long-lived host serving many sessions concurrently (e.g., a shared-agent web server), this leaks one _RuntimeState per session that ever started a background task, for the entire process lifetime. Furthermore, naive eviction by the host is unsafe: tasks still running when a session is abandoned are never cancelled, resulting in orphaned work that keeps executing (and calling tools) with results nobody will read, or causing "Task was destroyed but it is pending" errors if garbage collected mid-flight.

Description & Review Guide

• What are the major changes?

  • Added an explicit eviction API: async BackgroundAgentsProvider.release_session(session_id, *, cancel_running=True).
  • This method safely cancels and awaits all in-flight asyncio.Task objects before dropping the _RuntimeState entry.
  • Added a safety guard that raises a RuntimeError if cancel_running=False and unfinished tasks still exist, preventing the accidental orphaning of background work.
  • Added 4 comprehensive unit tests covering cancellation/await semantics, idempotency, session isolation, and the cancel_running=False guard.

• What is the impact of these changes?

  • Hosts can now safely tear down sessions when a user's conversation ends, completely resolving the per-session memory leak without risking mid-flight task corruption.
  • The change is purely additive; there are no breaking changes to existing APIs.

• What do you want reviewers to focus on?

  • Design decision regarding "Structural Cleanup" (Option 3 from the issue): The issue listed "structural release of a task's background_sessions entry when finalized" as an "at minimum" fallback option. I intentionally did not implement this fallback because it conflicts with the background_agents_continue_task tool. If we automatically drop the child AgentSession from runtime.background_sessions the moment a task finishes (inside _finalize_task), the LLM can no longer call continue_task on it, as the session reference is gone. Because the preferred Option 1 (Eviction API) is implemented here, the long-lived process memory leak is fully resolved via the host calling release_session() without breaking the task continuation feature.
  • The asyncio.wait cancellation semantics and the cancel_running=False guard logic.

Related Issue

Fixes #7385

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 host-facing lifecycle API to the Python harness BackgroundAgentsProvider so long-lived processes can explicitly evict per-session non-serializable runtime state (in-flight asyncio.Tasks and child AgentSessions), addressing unbounded retention over the process lifetime.

Changes:

• Introduces async BackgroundAgentsProvider.release_session(session_id, *, cancel_running=True) to cancel/await in-flight tasks and drop per-session runtime state.
• Adds unit tests covering release behavior (cancellation path, guard when cancel_running=False, idempotency, and session isolation).

Reviewed changes

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

File	Description
python/packages/core/agent_framework/_harness/_background_agents.py	Adds release_session() implementation to evict per-session runtime and cancel/await tasks.
python/packages/core/tests/core/test_harness_background_agents.py	Adds new async unit tests for the new session-release lifecycle API.

[pratik wayase (PratikWayase)]

Evan Mattson (@moonbox3) Eduard van Valkenburg (@eavanvalkenburg) Does this PR fulfill all the requirements of the issue, or does it need any further modifications?

[westey (westey-m)]

Thanks for the PR pratik wayase (@PratikWayase), added two small comments, and there are some type checking failures to fix. See the associated build.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_harness
_background_agents.py	344	39	88%	143–144, 146–149, 151–152, 196, 221–222, 247–249, 252–253, 256–257, 419, 429, 433–436, 450, 488–489, 532, 577, 580, 608, 617, 621, 628–629, 684–687
TOTAL	45806	4267	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9291	36 💤	0 ❌	0 🔥	2m 30s ⏱️

[pratik wayase (PratikWayase)]

westey (@westey-m) I've addressed both of your comments. All tests and linting are passing locally now. Ready for another look when you have a moment!