Skip to content

docs: add ADR 0054 for cross-process background task coordination - #10150

Open
Karthik Thota (karthik-0306) wants to merge 2 commits into
microsoft:mainfrom
karthik-0306:docs/adr-background-task-coordination
Open

Karthik Thota (karthik-0306) wants to merge 2 commits into
microsoft:mainfrom
karthik-0306:docs/adr-background-task-coordination

Conversation

@karthik-0306

Copy link
Copy Markdown
Contributor

Motivation & Context

  1. Why is this change required?
    BackgroundAgentsProvider keeps its running-task state in process memory, while the task records travel with the
    session. With several replicas, one process marks a healthy task of another process as Lost, results are orphaned,
    and a session release cannot cancel remote work (seven scenarios in [Feature]: BackgroundAgentsProvider cannot tell a task that is running on another process from one whose owner died #8760).

  2. What problem does it solve?
    It records the cross-process contract that both Python and .NET must implement before any code is written, as
    requested by the maintainers.

  3. What scenario does it contribute to?
    Multi-replica hosts without session affinity.

  4. Issue Link:
    Part of [Feature]: BackgroundAgentsProvider cannot tell a task that is running on another process from one whose owner died #8760. This is a design document only.


Description & Review Guide

  • What are the major changes? One new file, docs/decisions/0054-background-task-cross-process-coordination.md
    (status proposed). It compares five options and recommends a shared coordination contract with an in-memory
    default, keyed by session, task and execution id.
  • What is the impact of these changes? None at runtime. No code and no public API change.
  • What do you want reviewers to focus on? The chosen option, the reader and owner rules, and the seven open
    questions at the end. The deciders listed in the front matter are a proposal.

Related Issue

Part of #8760. It is intentionally not a closing reference: the implementation follows once this ADR is accepted. The
direction came from the maintainer on #9040: "define the cross-process ownership and result-handoff contract in a
shared .NET/Python ADR before implementation". #9040 is closed and informed this ADR. The single-process fixes already
landed in #9387.


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 links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved coordination identity and lifecycle rules can lose completed results, leave owner state unreclaimed, and cancel work against caller intent.

7 open issues
What changed in this PR

Adds proposed ADR 0054 to define cross-process background task coordination for Python and .NET, following the single-process fixes in #9387 and the design direction from #9040. This is a documentation-only change toward #8760, with no runtime or public API changes.

Changes:

  • Compares five approaches and recommends a shared coordination contract with an in-memory default.
  • Defines execution identity, ownership, result handoff, cancellation, and remote status handling.
  • Outlines conformance tests, implementation sequencing, and seven open design questions.
File Description
docs/​decisions/​0054-background-task-cross-process-coordination.md Proposes the shared coordination contract, trade-offs, and validation plan.

Review effort: Balanced

This branch was previously deployed

1 inactive deployment
github-app-auth — 253f1f1a Deployed Nov 6, 2026 by karthik-0306 via add_label #27313
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants