Drift sync with upstream agent-framework through 2026-09-04

[jamiewest]

Weekly /drift sync run. Reviews the 14 upstream dotnet/src commits between the old pin (92aec78c, 2026-08-25) and 2c49f50 (2026-09-04), ports the four applicable ones, records the skips in PORTING.md, and advances the pin.

Classification

Upstream PR	Date	Summary	Decision
#8032	09-04	[BREAKING] Clarify A2A agent run modes	port
#7671	09-04	[BREAKING] file_access_read_lines + line-numbering contract on AgentFileStore	port
#7911	08-27	Timeout for wait-for-first-completion	port
#7998	09-02	Track and update A2A task state	skip (propose) — streaming seam; artifact-metadata part ported
#7984	09-04	Foundry hosted response annotations	out of scope (Foundry)
#7976	09-03	Purview cold scope cache header	out of scope (Purview)
#7995	09-02	Azure AI Projects 3.0.0-beta.1	out of scope (Foundry)
#7986	09-02	Remove Azure.AI.OpenAI dependency	out of scope (Purview README + shared demo)
#7935	08-31	Add public API analyzers	out of scope (build/baselines only)
#3932	08-31	Cosmos DB emulator startup	out of scope (CosmosNoSql)
#6046	08-31	ADR sequence numbers	out of scope (docs)
#7932	08-28	Foundry AgentHost port binding	out of scope (Foundry)
#7913	08-27	Workflow fileinput sample	out of scope (Shared/ sample runner, no in-scope consumer)
#7864	08-26	DevUI aggregator annotations	out of scope (Aspire/DevUI)

Ported: 4. Skipped with a recorded decision: 1. Out of scope: 10. Suppressed by existing ledger entries: 1 (#7722's non-streaming-seam entry, which #7998 rests on).

What changed

#8032 — A2A run modes (BREAKING). AgentRunMode now selects which A2A artifact a run returns rather than whether the agent runs in background. disallowBackground / allowBackgroundIfSupported / allowBackgroundWhen → returnMessage / returnTask / returnTaskWhen; shouldRunInBackground → shouldReturnTask; RunInBackgroundCallback → ReturnTaskCallback. The mode is no longer forwarded as AgentRunOptions.allowBackgroundResponses, and it is no longer consulted when continuing an existing task. agents_flutter's A2A host service follows the rename.

#7671 — file-store line numbering and read_lines (BREAKING). The line contract moves onto AgentFileStore as splitLines / scanContent, with a new findMatchingFilesAsync narrowing hook and a default (no longer abstract) searchFilesAsync, so a store implementing only the mandatory members gets aligned numbers for free. Both shipped stores now number through scanContent rather than each carrying its own copy of the loop. FileSearchMatch.line keeps the line's terminator and lone-CR lines are counted, so grep and the line editor agree on what a line is. Adds file_access_read_lines (read-only tool group), FileLineEdit.expectedLine, and FileEditor.sliceLines / trimLineTerminator / lineContentLength.

#7911 — background-agents wait timeout. BackgroundAgentsProviderOptions.waitTimeout, five minutes by default; on expiry the wait tool returns control and leaves the tasks running so it can be called again.

#7998 (partial). A completed A2A task's artifact now carries the response's additional properties as metadata — the one part of that PR that does not depend on the streaming path.

Recorded decisions (PORTING.md)

• #7998 not applicable. The rewrite is built on HandleNewMessageStreamingAsync, ArtifactStreamWriter and StreamTaskUpdatesAsync — the streaming path the existing #7722 ledger entry records as not applicable to the port's non-streaming package:a2a executor seam. Only the streaming-independent artifact-metadata part is ported.
• #8032 task branch. Upstream picks between streaming into the task and aggregating one completed task from the client's ReturnImmediately flag, which the non-streaming seam does not have. The port keys that branch on AgentResponse.continuationToken instead: no token means the run finished in this call, so the task is completed with an aggregated artifact; a token means the caller polls, so the task goes submitted → working.
• scanContent matching. Dart's RegExp has no length-bounded match, so the pattern is matched against trimLineTerminator(line) — the copy upstream's LineContentLength exists to avoid. Match offsets are unaffected.
• #7911 mapping. ArgumentOutOfRangeException → RangeError; maximumWaitTimeout keeps upstream's 4,294,967,294 ms bound though Dart timers have no such limit; the Task.WhenAny + CTS race becomes a Completer raced against a Timer that is cancelled when a task wins, leaving no pending timer behind.

Extensions-edge checks (Step I2.5)

1. Upstream MEAI bump. Microsoft.Extensions.AI.OpenAI moved 10.6.0 → 10.9.0 between the pin and main (#7986); the other Microsoft.Extensions.AI* packages are unchanged at 10.9.0. That package is the .NET OpenAI SDK adapter, which ai/open_ai/ already records as N/A by design — no coordination needed this window.
2. Published-version lag — resolved. extensions was pinned ^0.6.0 with 0.7.1 on pub.dev. 0.7.0 is additive (routing chat clients, new UsageDetails members, AIFunction.asDeclarationOnly, shared function-invocation engine) and 0.7.1 is documentation-only, so the constraint is raised to ^0.7.0 in both packages. Both analyze and test clean against 0.7.1. extensions_flutter: ^0.5.0 already admits the latest 0.5.2; no change needed.
3. Blocked on extensions: none this window. Every ported item was expressible with the current package:extensions surface.

Worth flagging: extensions 0.7.0 added RoutingChatClient and RoutingContext, which makes the stated rationale for the self-contained RoutePersistingRoutingChatClient partly stale. Left as-is and annotated in PORTING.md — rebasing onto the new base is a deliberate follow-up, not drift.

Releases

packages/agents 2.0.0 → 3.0.0 and packages/agents_flutter 0.8.2 → 0.9.0, each with a matching CHANGELOG entry. A major bump on agents rather than a minor one because both #8032 and #7671 are breaking public-API changes (renamed AgentRunMode statics with no deprecated aliases, changed FileSearchMatch.line semantics and line numbering, searchFilesAsync no longer abstract). Say the word if you'd rather ship this as 2.1.0 and carry deprecated aliases instead.

Verification

• packages/agents: dart analyze clean (2 pre-existing use_super_parameters infos, untouched by this change), dart test — 1231 passed.
• packages/agents_flutter: flutter analyze — no issues, flutter test — 835 passed.
• Ripple not verified in the sibling agents_llama / agents_app checkouts — they are not available in this cloud session. AgentFileStore.searchFilesAsync changed from abstract to virtual and FileSearchMatch.line changed semantics, so please check those on the next ref bump.
• Toolchain note: this session had no Dart SDK, so Flutter 3.47.2 (Dart 3.13.2) was installed to run the checks above.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JT5obLadEohFN5f5dyHBNv

---

Generated by Claude Code