refactor(adk): improve cancel propagation, encapsulate TurnLoop stop options, add UntilIdleFor

[shentongmartin]

Summary

Problem	Solution
Cancel modes propagate to nested agents by default — inner agent safe-points fire before the root agent, surprising users	Make propagation opt-in via WithRecursive(): cancel modes only affect the root agent by default
TurnLoop.Stop and TurnLoop.Push directly expose AgentCancelOption and CancelMode, leaking lower-level ChatModelAgent concepts into the higher-level TurnLoop API	Replace raw options with use-case-driven APIs: WithGraceful/WithGracefulTimeout for Stop, WithPreempt/WithPreemptTimeout for Push

Feature 1: Opt-in Recursive Cancel (WithRecursive)

Key Insight

Cancel has two orthogonal dimensions: timing (when to cancel) and scope (where to cancel).

• Timing is the CancelMode: CancelImmediate, CancelAfterChatModel, CancelAfterToolCalls
• Scope is the AgentCancelOption: WithRecursive()

Conflating scope with timing (e.g., making CancelRecursive a bitmask bit in CancelMode) leads to problems:

1. CancelImmediate = 0 cannot be OR'd with anything
2. Timing and scope are different categories — they belong in different types

Design Decisions

Why root-only by default? In ChatModelAgent → AgentTool → ChatModelAgent, users expect CancelAfterChatModel to fire after the root agent's ChatModel, not an arbitrary inner one. Deep propagation is powerful but surprising for the common case.

Monotonic escalation. Once WithRecursive() is set via any cancel call, it stays set. Escalation is monotonic, never reversed.

Mid-flight escalation. A recursiveChan (closed on first setRecursive(true)) enables mid-flight escalation: parked deriveChild goroutines wake up and propagate immediately when a later cancel call adds WithRecursive().

Grace period gating. wrapGraphInterruptWithGracePeriod now checks isRecursive() && hasActiveChildren() — without recursive mode, there are no child interrupts to wait for.

Feature 2: TurnLoop Cancel Option Encapsulation

Key Insight

TurnLoop is a higher-level orchestrator; it should not expose ChatModelAgent-specific cancel concepts (CancelMode, AgentCancelOption) in its public API. Instead, it should present use-case-driven vocabulary:

• Stop is about shutdown: "graceful" vs "immediate" (the default).
• Preempt is about interrupting the current turn at a "safe point", optionally with a timeout that escalates to immediate cancel.

The SafePoint bitmask (AfterToolCalls, AfterChatModelCall, AnySafePoint) maps internally to CancelMode but hides that detail from TurnLoop users.

API Mapping

Old (removed)	New
Stop(WithAgentCancel(WithAgentCancelMode(CancelImmediate)))	Stop()
Stop(WithAgentCancel(WithAgentCancelMode(CancelAfterToolCalls)))	Stop(WithGraceful())
Stop(WithAgentCancel(..., WithAgentCancelTimeout(d)))	Stop(WithGracefulTimeout(d))
Push(x, WithPreempt[T]())	Push(x, WithPreempt[T](AnySafePoint))
Push(x, WithPreempt[T](WithAgentCancelMode(CancelAfterToolCalls)))	Push(x, WithPreempt[T](AfterToolCalls))
Push(x, WithPreempt[T](WithAgentCancelMode(CancelImmediate)))	Push(x, WithPreemptTimeout[T](AnySafePoint, smallDuration))

Design Decisions

Two-function pattern over variadic/pointer. WithGraceful() + WithGracefulTimeout(d) instead of WithGraceful(d ...time.Duration) or WithGraceful(d *time.Duration). Variadic allows passing multiple values (semantic mismatch); 0 as a duration conflicts with WithGraphInterruptTimeout(0) meaning "immediate".

WithGraceful bundles recursive automatically. Graceful shutdown implies wanting to reach a safe point across the entire agent hierarchy, so WithRecursive() is included by default. Immediate stop (bare Stop()) does not set recursive — it just cancels the context.

Preempt does not set recursive. Preemption is a turn-level concern. The user preempts the current turn to process a higher-priority item; recursive propagation is not the default expectation.

---

摘要

问题	方案
Cancel 模式默认传播到 AgentTool 内的嵌套 Agent，内层安全点先触发，不符合预期	改为 opt-in：默认只影响根 Agent，使用 WithRecursive() 显式传播
TurnLoop.Stop 和 Push 直接暴露 AgentCancelOption / CancelMode，将底层 ChatModelAgent 概念泄露到更高层的 TurnLoop API	用面向用例的 API 替代：Stop 用 WithGraceful/WithGracefulTimeout，Push 用 WithPreempt/WithPreemptTimeout

功能 1：可选递归取消（WithRecursive）

核心洞察

Cancel 有两个正交维度：时机（CancelMode）和范围（WithRecursive()）。将 scope 混入 bitmask 会导致 CancelImmediate = 0 无法做 OR 运算。分离为独立的 AgentCancelOption 更清晰。

设计要点

• 默认只影响根 Agent：用户期望 CancelAfterChatModel 在根 Agent 触发，而非内层。
• 单调升级：WithRecursive() 一旦设置不可回退。
• recursiveChan 中途升级：后续 cancel 调用加入 WithRecursive() 后，已阻塞的 deriveChild goroutine 立即被唤醒。
• Grace period 条件化：只在 recursive 且有活跃子节点时生效。

功能 2：TurnLoop Cancel Option 封装

核心洞察

TurnLoop 是更高层的编排器，不应暴露 ChatModelAgent 特有的 cancel 概念。用面向用例的词汇替代：

• Stop：优雅关停（WithGraceful/WithGracefulTimeout）vs 立即关停（默认）
• Preempt：在安全点中断当前轮次（WithPreempt(SafePoint)），可选超时升级（WithPreemptTimeout）

SafePoint 位掩码（AfterToolCalls、AfterChatModelCall、AnySafePoint）内部映射为 CancelMode，但对 TurnLoop 用户隐藏了这一细节。

设计要点

• 双函数模式：WithGraceful() + WithGracefulTimeout(d) 而非变参或指针，避免语义歧义。
• WithGraceful 自动包含递归：优雅关停意味着整个层级都应到达安全点。
• Preempt 不设递归：Preempt 是轮次级关注点，默认不传播到子 Agent。

[codecov]

Codecov Report

❌ Patch coverage is 93.98907% with 11 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (alpha/09@26b0af2). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
adk/turn_buffer.go	93.44%	2 Missing and 2 partials ⚠️
adk/turn_loop.go	95.40%	2 Missing and 2 partials ⚠️
adk/cancel.go	90.90%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             alpha/09     #942   +/-   ##
===========================================
  Coverage            ?   82.14%           
===========================================
  Files               ?      162           
  Lines               ?    20228           
  Branches            ?        0           
===========================================
  Hits                ?    16616           
  Misses              ?     2438           
  Partials            ?     1174           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.