feat(adk): unify foreground and background task runtime

[shentongmartin]

Unified Task Ownership Runtime

Problem

Foreground work may outlive the call that started it. The old runtime handled this in two incompatible ways:

• Sub-agents transferred lifecycle ownership from the parent to background.Manager, but follow-up input and nested completion still needed one durable identity and mailbox.
• Local and managed-tool auto-background started the real operation under the caller context, then handed a waiter or adopted handle to the Manager. Caller cancellation could therefore kill work that was supposed to continue, and explicit background used a different execution path.

Public auto-background config also referenced adk/internal/foreground.CandidateInfo, which external modules cannot name.

Solution

This PR introduces one Task model with stable identity, durable communication, and explicit ownership:

• TaskID identifies one finite execution; ChildSessionID identifies durable conversation history.
• A durable Mailbox routes queue/preempt input and nested completion to the current owner.
• Parent-owned Sub-agent execution can hand off without changing TaskID, mailbox, or child session; generation fencing rejects stale owners.
• Auto-backgroundable Local and Managed Tool work is Manager-owned from Attempt 1. Foreground is only a projection of the same operation, so timeout or caller abort never requires adopting a running handle.
• Publication is independent from lifecycle ownership: Deferred remains hidden during foreground observation, OnCreate publishes explicit background work, and OnBackground publishes when the projection detaches.
• Manager.Publish(taskID) performs the only legal publication transition and does not advance lifecycle Version, so it cannot invalidate the active attempt.
• Public adk/task/foreground contains only policy leaf types; timer, publish, cancellation, and terminal races remain in the internal task-first coordinator.

Decisions

• Foreground/background describes observation; Parent/Manager describes execution ownership; Publication describes when the Task becomes visible. They are separate dimensions.
• Direct foreground execution remains parent-owned when auto-background is disabled. Explicit and automatic background execution share the Manager-owned path.
• Caller abort defaults to publish-and-detach. An explicit policy may request cancellation; publication failure after the caller disappears cancels the Task to avoid a hidden orphan.
• Timeout rejection requests cancellation and waits for the terminal Canceled snapshot before returning.
• Publication does not increment lifecycle Version; Store locking and expected-version fencing still make publish/terminal and publish/cancel races atomic.
• No compatibility layer is retained for the old adk/backgroundtask package or the managed-tool handoff/adopt API introduced within this branch.

Key Insight

A Task has three independent concerns:

execution owner: Parent | Manager
projection:      Foreground | Detached
publication:     Deferred | OnCreate | OnBackground

Keeping these dimensions separate lets one Manager attempt continue unchanged while the caller stops observing it, and lets true parent-owned Sub-agent handoff retain its existing ownership-transfer semantics.

Validation

• Full repository tests, ADK race tests, go vet, and golangci-lint pass locally.
• Go 1.18 ADK compatibility tests pass.
• Publication races ran 100 times under race detection; task-first timeout/caller-abort cases ran 50 times.
• High-level integration tests cover nested completion before/after handoff, restart recovery, and concurrent continuation admission.

---

统一 Task Ownership Runtime

问题

Foreground 工作可能在当前调用结束后继续。旧 runtime 对这类场景有两套不一致的处理：

• Sub-agent 会把 lifecycle owner 从 parent 转给 background.Manager，但后续输入和 nested completion 仍需要稳定的 Task 身份与 durable mailbox。
• Local 和 Managed Tool 的 auto-background 先在 caller context 下启动真实操作，超时后再把 waiter 或 adopted handle 交给 Manager。这样 caller cancel 可能误杀本应继续的工作，而且显式后台与自动后台走不同执行路径。

此外，公开配置引用了 adk/internal/foreground.CandidateInfo，外部 module 无法命名该类型。

方案

本 PR 建立统一 Task 模型，把身份、通信、执行 owner 和可见性明确拆开：

• TaskID 表示一次有限执行，ChildSessionID 表示可持续的对话历史。
• durable Mailbox 将 queue/preempt 输入和 nested completion 路由给当前 owner。
• Parent-owned Sub-agent handoff 不改变 TaskID、mailbox 或 child session，并通过 generation fence 拒绝旧 owner。
• 可自动后台化的 Local 和 Managed Tool 从 Attempt 1 起就由 Manager 执行。Foreground 只是同一操作的临时 projection，timeout 或 caller abort 不再需要接管正在运行的 handle。
• Publication 与 owner 正交：Deferred 在前台观察期间隐藏，OnCreate 用于显式后台，OnBackground 在 projection detach 时发布。
• Manager.Publish(taskID) 固定执行唯一合法的 publication transition，且不推进 lifecycle Version，因此不会让 active attempt 丢失 authority。
• 公开 adk/task/foreground 只保留 policy leaf types；timer、publish、cancel 和 terminal 竞态都留在 internal task-first coordinator。

关键决策

• foreground/background 表示是否仍在观察；Parent/Manager 表示谁拥有执行；Publication 表示 Task 何时可见。三者是独立维度。
• 未配置 auto-background 的 direct foreground 仍由 parent 执行；显式后台和自动后台共用 Manager-owned 路径。
• caller abort 默认 publish-and-detach。显式 policy 可以请求取消；caller 已消失且 publication 失败时，取消 Task，避免留下不可发现的 hidden orphan。
• timeout policy 拒绝后台化时，先请求取消并等待 terminal Canceled snapshot，再同步返回。
• Publication 不增加 lifecycle Version；Store lock 与 expected-version fencing 仍保证 publish/terminal、publish/cancel 竞态只有一个原子结果。
• 不保留旧 adk/backgroundtask 包，也不保留本分支曾引入的 managed-tool handoff/adopt API。

核心认识

Task 有三个互相独立的维度：

execution owner: Parent | Manager
projection:      Foreground | Detached
publication:     Deferred | OnCreate | OnBackground

拆开这三个维度后，caller 停止观察不会改变或重启 Manager attempt；真正的 parent-owned Sub-agent handoff 也可以继续保持明确的 owner transfer 语义。

验证

• 本地全仓测试、ADK race、go vet 和 golangci-lint 通过。
• Go 1.18 ADK 兼容测试通过。
• Publication 竞态在 race 下运行 100 轮；task-first timeout/caller-abort 场景运行 50 轮。
• 高层集成测试覆盖 handoff 前后 nested completion、重建恢复和并发 continuation admission。

Streaming Task Event Persistence

A background event may contain a one-shot stream. Serializing it before entering the runtime loses the original event shape; passing the live reader directly to a Store makes persistence compete with live delivery and can hold authorization for the lifetime of the stream.

The runtime now separates those responsibilities:

• executor-specific TaskEventPersister[E, Chunk] receives the typed event and a persistence-owned stream;
• TaskEventWriter owns TaskID, Attempt, and EventID and revalidates authority for every appended part;
• EventID identifies the logical event, while stable PartID values make partial stream replay idempotent;
• Final closes the logical event, so recovery can replay an accepted prefix but cannot append after completion.

The Store remains responsible only for durable bytes, ordering, and fencing. Local, Managed Tool, and Local Sub-agent integrations provide defaults while allowing callers to replace serialization. AgentTool already gives each receiver an independent stream copy, so persistence cannot consume the caller's live stream.

Streaming Task Event 持久化

后台 event 可能携带一次性 stream。过早序列化会丢失原始 event 结构；把 live reader 直接交给 Store，又会让持久化与实时消费竞争，并让授权跨越整个 stream 生命周期。

新的边界把职责拆开：

• executor-specific TaskEventPersister[E, Chunk] 接收 typed event 和 persistence-owned stream；
• TaskEventWriter 持有 TaskID、Attempt 和 EventID，并在每个 part 写入时重新校验 authority；
• EventID 标识 logical event，稳定的 PartID 保证 partial stream 可幂等重放；
• Final 封闭 logical event，恢复可以重放已接受前缀，但不能在完成后继续追加。

Store 只负责 durable bytes、顺序和 fencing。Local、Managed Tool 和 Local Sub-agent 提供默认 persister，同时允许调用方替换序列化。AgentTool 已为每个 receiver 提供独立 stream copy，因此持久化不会消费 caller 的 live stream。

[codecov]

Codecov Report

❌ Patch coverage is 85.41667% with 119 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (alpha/10@3174841). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
adk/internal/taskfirst/coordinator.go	82.95%	25 Missing and 20 partials ⚠️
adk/middlewares/subagent/agent_tool.go	89.52%	22 Missing and 11 partials ⚠️
adk/middlewares/filesystem/bash_run.go	61.76%	24 Missing and 2 partials ⚠️
adk/prebuilt/deep/deep.go	86.11%	5 Missing and 5 partials ⚠️
adk/middlewares/filesystem/filesystem.go	90.47%	1 Missing and 1 partial ⚠️
adk/middlewares/task/middleware.go	75.00%	2 Missing ⚠️
adk/middlewares/subagent/middleware.go	93.75%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             alpha/10    #1204   +/-   ##
===========================================
  Coverage            ?   83.06%           
===========================================
  Files               ?      228           
  Lines               ?    41746           
  Branches            ?        0           
===========================================
  Hits                ?    34677           
  Misses              ?     4691           
  Partials            ?     2378           

☔ View full report in Codecov by Harness.
📢 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.

[github-actions]

🚨 Breaking API Changes Detected

Package: github.com/cloudwego/eino/adk/backgroundtask/tool

Incompatible changes:

• AdoptRequest: removed
• AdoptResult: removed
• BackgroundTool: removed
• ErrResumeInputRejected: removed
• ExecutorKey: removed
• ForegroundHandoffTool: removed
• InputPreparer: removed
• InputRequest: removed
• ManagedToolConfig: removed
• ManagedToolResponseEvent: removed
• ManagedToolResponseEventForegroundResult: removed
• ManagedToolResponseEventLaunchResult: removed
• ManagedToolResponseEventType: removed
• ManagedToolResponseEventUpdate: removed
• MaterializeOutputRequest: removed
• NewManagedTool: removed
• NewProgressReader: removed
• NewRegistry: removed
• Outcome: removed
• OutputMaterializer: removed
• ProgressReader: removed
• ReadInputRequest: removed
• RecoverRequest: removed
• RecoverableBackgroundTool: removed
• RecoverableExecutorKey: removed
• RegisterExecutors: removed
• Registration: removed
• Registry: removed
• ReserveOutputRequest: removed
• ResumableBackgroundTool: removed
• ResumeRequest: removed
• Run: removed
• StartRequest: removed
• StartResult: removed
• Submit: removed
• SubmitRequest: removed
• Update: removed
• UpdateSource: removed

Review Guidelines

Please ensure that:

• The changes are absolutely necessary
• They are properly documented
• Migration guides are provided if needed

⚠️ Please resolve this thread after reviewing the breaking changes.

[shentongmartin]

当前通用能力已迁移到 adk/task/tool，ManagedToolConfig、NewManagedTool、Registry、Submit、Run 等仍在新包；ForegroundHandoffTool/Adopt* 等 tool-specific owner-transfer API 按 task-first 设计删除，auto 与 explicit background 统一由 Manager-owned execution 执行。迁移文档明确不为旧 alpha 包面提供兼容 shim。这是alpha breaking API决策，请维护者确认。

[github-actions]

🚨 Breaking API Changes Detected

Package: github.com/cloudwego/eino/adk/middlewares/subagent

Incompatible changes:

• BackgroundConfig: removed
• DurableBackgroundConfig: removed
• DurableTaskProgressReader: removed
• LocalBackgroundConfig: removed
• NameFromTask: changed from func(*github.com/cloudwego/eino/adk/backgroundtask.Task) string to func(*github.com/cloudwego/eino/adk/task/background.TaskSnapshot) string
• NewDurableTaskProgressReader: removed
• TypedBackgroundConfig: removed
• TypedConfig.Background: removed
• TypedDurableBackgroundConfig: removed
• TypedLocalBackgroundConfig: removed

Review Guidelines

Please ensure that:

• The changes are absolutely necessary
• They are properly documented
• Migration guides are provided if needed

⚠️ Please resolve this thread after reviewing the breaking changes.

[shentongmartin]

当前 adk/middlewares/subagent 将 Config.Background 收敛为 Config.Tasks，使用 TypedTaskConfig{Local, Durable}；durable 配置以 subagent.Controller 作为统一 Start/Continue/Handle/恢复/handoff 入口，NameFromTask 相应接收持久化的 TaskSnapshot。这是alpha breaking API决策，请维护者确认。

[github-actions]

🚨 Breaking API Changes Detected

Package: github.com/cloudwego/eino/adk/middlewares/filesystem

Incompatible changes:

• CommandFromTask: changed from func(*github.com/cloudwego/eino/adk/backgroundtask.Task) string to func(*github.com/cloudwego/eino/adk/task/background.TaskSnapshot) string
• LocalBackgroundConfig.Runner: changed from *github.com/cloudwego/eino/adk/backgroundtask/local.Runner to *github.com/cloudwego/eino/adk/task/local.Runner
• ManagedExecuteToolDesc: value changed from "Executes a bash command and returns its output.\n\n- Working directo... to "Executes a bash command and returns its output.\n\n- Working directo...
• ManagedExecuteToolDescChinese: value changed from "执行一条 bash 命令并返回其输出。\n\n- 工作目录在多次调用间保持，但优先使用绝对路径 —— 复合命令中的 cd 可能触发权... to "执行一条 bash 命令并返回其输出。\n\n- 工作目录在多次调用间保持，但优先使用绝对路径 —— 复合命令中的 cd 可能触发权...
• RecoverableBackgroundConfig.Executors: removed
• RecoverableBackgroundConfig.Manager: changed from *github.com/cloudwego/eino/adk/backgroundtask.Manager to *github.com/cloudwego/eino/adk/task/background.Manager
• RecoverableBackgroundConfig.OutputMaterializer: changed from github.com/cloudwego/eino/adk/backgroundtask/tool.OutputMaterializer to github.com/cloudwego/eino/adk/task/tool.OutputMaterializer
• RecoverableBackgroundConfig.Shell: changed from github.com/cloudwego/eino/adk/backgroundtask/shell.RecoverableShell to github.com/cloudwego/eino/adk/task/shell.RecoverableShell
• RecoverableBackgroundConfig.ShouldAutoBackground: changed from func(context.Context, *github.com/cloudwego/eino/adk/internal/foreground.CandidateInfo) bool to github.com/cloudwego/eino/adk/task/foreground.ShouldAutoBackground
• RecoverableBackgroundConfig.ToolRegistry: changed from *github.com/cloudwego/eino/adk/backgroundtask/tool.Registry to *github.com/cloudwego/eino/adk/task/tool.Registry

Review Guidelines

Please ensure that:

• The changes are absolutely necessary
• They are properly documented
• Migration guides are provided if needed

⚠️ Please resolve this thread after reviewing the breaking changes.

[shentongmartin]

当前 filesystem 配置显式区分 BackgroundConfig.Local 与 Recoverable；相关类型迁移到 adk/task/{background,local,shell,tool,foreground}，Executors 删除后由 Manager.LoadOrRegisterExecutor 内聚注册，策略回调改用可公开引用的 foreground 类型。工具描述变更对应新的 task-first 行为。这是alpha breaking API决策，请维护者确认。

[github-actions]

🚨 Breaking API Changes Detected

Package: github.com/cloudwego/eino/adk/prebuilt/deep

Incompatible changes:

• BackgroundConfig: removed
• RecoverableShellConfig.OutputMaterializer: changed from github.com/cloudwego/eino/adk/backgroundtask/tool.OutputMaterializer to github.com/cloudwego/eino/adk/task/tool.OutputMaterializer
• RecoverableShellConfig.Shell: changed from github.com/cloudwego/eino/adk/backgroundtask/shell.RecoverableShell to github.com/cloudwego/eino/adk/task/shell.RecoverableShell
• TypedBackgroundConfig: removed
• TypedConfig.Background: removed
• TypedDurableSubAgentConfig.Executor: removed
• TypedDurableSubAgentConfig.RunOptionsFactories: changed from map[string]github.com/cloudwego/eino/adk/backgroundtask/subagent.RunOptionsFactory to map[string]github.com/cloudwego/eino/adk/task/subagent.RunOptionsFactory

Review Guidelines

Please ensure that:

• The changes are absolutely necessary
• They are properly documented
• Migration guides are provided if needed

⚠️ Please resolve this thread after reviewing the breaking changes.

[shentongmartin]

当前 adk/prebuilt/deep 将 Config.Background 收敛为 Config.Tasks/TypedTaskConfig，在同一 TaskID 空间统一 sub-agent、local/recoverable shell 与 task control；durable sub-agent 由 Runtime *subagent.Controller 取代外置 Executor，相关依赖迁移到 adk/task/...。这是alpha breaking API决策，请维护者确认。

[github-actions]

🚨 Breaking API Changes Detected

Package: github.com/cloudwego/eino/adk/prebuilt/deep

Incompatible changes:

• BackgroundConfig: removed
• RecoverableShellConfig.OutputMaterializer: changed from github.com/cloudwego/eino/adk/backgroundtask/tool.OutputMaterializer to github.com/cloudwego/eino/adk/task/tool.OutputMaterializer
• RecoverableShellConfig.Shell: changed from github.com/cloudwego/eino/adk/backgroundtask/shell.RecoverableShell to github.com/cloudwego/eino/adk/task/shell.RecoverableShell
• TypedBackgroundConfig: removed
• TypedConfig.Background: removed
• TypedDurableSubAgentConfig.Executor: removed
• TypedDurableSubAgentConfig.RunOptionsFactories: changed from map[string]github.com/cloudwego/eino/adk/backgroundtask/subagent.RunOptionsFactory to map[string]github.com/cloudwego/eino/adk/task/subagent.RunOptionsFactory

Review Guidelines

Please ensure that:

• The changes are absolutely necessary
• They are properly documented
• Migration guides are provided if needed

⚠️ Please resolve this thread after reviewing the breaking changes.

[shentongmartin]

与前一条 deep 报告相同：当前 adk/prebuilt/deep 使用 Config.Tasks/TypedTaskConfig 统一 TaskID 空间，durable sub-agent 改由 Runtime *subagent.Controller 管理，shell/tool 类型迁移到 adk/task/...，不保留旧 Background/Executor 配置面。这是alpha breaking API决策，请维护者确认。

[shentongmartin]

与前一条 deep 报告相同：当前 adk/prebuilt/deep 使用 Config.Tasks/TypedTaskConfig 统一 TaskID 空间，durable sub-agent 改由 Runtime *subagent.Controller 管理，shell/tool 类型迁移到 adk/task/...，不保留旧 Background/Executor 配置面。这是alpha breaking API决策，请维护者确认。