docs(schema): warn against in-place mutation of shared stream elements

.gitignore

@@ -64,3 +64,7 @@ CLAUDE.md
 
 # Internal dev setup (not for public repo)
 /scripts/dev_setup_internal.sh
+
+# External working trees
+/examples/
+/ext/

SESSION_API_DOCUMENTATION.md

@@ -0,0 +1,68 @@
+<!--
+Copyright 2026 CloudWeGo Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Session API Documentation
+
+## Agent Interrupt Events
+
+`SessionEventAgentInterrupt` persists an agent-initiated business interrupt in the managed session timeline.
+
+```go
+const SessionEventAgentInterrupt SessionEventKind = "agent.interrupt"
+```
+
+The event is distinct from `SessionEventUserInterrupt`:
+
+- `SessionEventAgentInterrupt` means the agent paused execution and needs external input before it can resume.
+- `SessionEventUserInterrupt` means the user proactively cancelled execution.
+
+The payload is stored on `SessionEvent.AgentInterrupt`.
+
+```go
+type AgentInterruptEvent struct {
+    Cause             AgentInterruptCause `json:"cause,omitempty"`
+    CheckPointID      string              `json:"checkpoint_id,omitempty"`
+    InterruptContexts []*InterruptCtx     `json:"interrupt_contexts,omitempty"`
+    ToolUseID         string              `json:"tool_use_id,omitempty"`
+    SpanEventID       string              `json:"span_event_id,omitempty"`
+}
+```
+
+`Cause` categorizes why the interrupt happened:
+
+```go
+const (
+    AgentInterruptCauseToolPermission AgentInterruptCause = "tool_permission"
+    AgentInterruptCauseCustomTool     AgentInterruptCause = "custom_tool"
+    AgentInterruptCauseGeneric        AgentInterruptCause = "generic"
+)
+```
+
+`CheckPointID` is the checkpoint key passed to `Runner.Resume` or `Runner.ResumeWithParams`.
+
+`InterruptContexts` uses the same public `[]*InterruptCtx` shape exposed on live `AgentAction.Interrupted` events. Root-cause `InterruptCtx.ID` values are the normal keys for `ResumeParams.Targets`.
+
+```go
+resumeParams := &ResumeParams{
+    Targets: map[string]any{
+        interruptEvent.InterruptContexts[0].ID: result,
+    },
+}
+```
+
+`ToolUseID` is populated when the root-cause interrupt address contains a tool segment. The runner uses `AddressSegment.SubID` when present and falls back to `AddressSegment.ID` for compatibility with older tool-address paths.
+
+`SpanEventID` is a best-effort link to the related `span.tool_call_start` session event. It may be empty when the runner has not observed a matching tool span start event in the current run or resume drain loop.

V0.9_COMPATIBILITY_NOTE.md

@@ -0,0 +1,132 @@
+<!--
+Copyright 2026 CloudWeGo Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# V0.9 agentic-runtime Compatibility Note
+
+本文列出现有用户从 V0.8.x 升级到 V0.9 `agentic-runtime` 时需要关注的 API 和语义变化。未列出的新增能力通常不影响既有 `*schema.Message` 路径。
+
+## API 显式变更
+
+### ChatModelAgentMiddleware 新增 AfterAgent
+
+`ChatModelAgentMiddleware` 新增 `AfterAgent` 方法。手写实现该接口的类型需要补充该方法，否则会编译失败。
+
+推荐做法：
+
+- 如果 middleware 不需要特殊收尾逻辑，嵌入 `*adk.BaseChatModelAgentMiddleware`。
+- 如果 middleware 需要在 Agent 成功结束后清理状态、记录事件或补充统计，实现 `AfterAgent(ctx, state)`。
+
+影响范围：
+
+- 仅影响显式实现 `ChatModelAgentMiddleware` 的用户代码。
+- 通过 `BaseChatModelAgentMiddleware` 组合扩展的代码可保持兼容。
+
+### summarization.SummarizeMessages 被移除
+
+`summarization.SummarizeMessages` 和 `summarization.SummarizeOutput` 不再导出。
+
+迁移方式：
+
+- 构造 summarization middleware 时继续使用 `summarization.New` 或 `summarization.NewTyped`。
+- 需要主动触发同步 summarization 时，使用 `TypedMiddleware.Summarize`。
+
+该调整将 summarization 的配置、状态读取和执行逻辑收敛到 middleware 内部，避免独立函数与运行时状态语义分叉。
+
+## 需要关注语义变化的能力
+
+### Summarization Finalize 后处理语义变化
+
+V0.8.x 中，summarization middleware 会先执行默认 summary 后处理，再调用用户配置的 `Finalize`。因此自定义 `Finalize` 收到的 `summary` 已经包含 `PreserveUserMessages` 替换、`TranscriptFilePath` 注入和 summary preamble。
+
+V0.9 中，如果设置了 `Config.Finalize`，middleware 会直接把模型生成的 raw summary 传给 `Finalize`，不再自动执行默认后处理。受影响的配置包括：
+
+- `PreserveUserMessages`
+- `TranscriptFilePath`
+
+迁移方式：
+
+- 如果希望保留默认后处理，不要设置 `Finalize`，让 middleware 使用默认 finalization 路径。
+- 如果必须自定义 `Finalize`，但仍希望保留默认后处理，先通过 `DefaultFinalizer` 构造默认 finalizer，再在自定义逻辑中显式组合。
+- `DefaultFinalizer` 不会自动读取外层 `Config.PreserveUserMessages` 和 `Config.TranscriptFilePath`；需要通过 `DefaultFinalizerConfig` 显式传入。
+- 使用 `NewFinalizer().PreserveSkills(...).Build()` 的代码需要特别检查：该 finalizer 只负责 preserve skills，不会自动补上 `PreserveUserMessages` 和 `TranscriptFilePath`。
+
+### 工具列表修改路径调整
+
+`ModelContext.Tools` 不再是推荐的工具列表修改入口。
+
+升级建议：
+
+- 在 `BeforeModelRewriteState` 中修改 `state.ToolInfos`。
+- 如需模型原生 deferred tool search，修改 `state.DeferredToolInfos`。
+- 不建议在 `WrapModel` 中修改工具列表；该修改只影响当前模型调用，后续 middleware、后续 turn 或 checkpoint/resume 不会继承这次修改。
+
+### Model Retry 决策语义增强
+
+`ModelRetryConfig` 新增 `ShouldRetry`。当 `ShouldRetry` 非空时，`IsRetryAble` 会被忽略。
+
+需要注意：
+
+- 旧的 `IsRetryAble` 仍可用于错误维度的简单重试。
+- 使用 `ShouldRetry` 后，应显式处理成功输出但业务不接受的场景。
+- Interrupt 和 `ErrStreamCanceled` 不作为普通 retry error 处理。
+
+### Cancel 错误语义
+
+V0.9 引入主动取消语义后，应用需要区分主动取消、普通错误和业务 interrupt。
+
+升级建议：
+
+- 上层应区分 `CancelError`、普通 error 和业务 interrupt。
+- 如果应用主动接入 `WithCancel`，不要把 `CancelError` 当作普通业务失败处理。
+
+### AgenticMessage 迁移需要理解新的消息结构
+
+`TypedChatModelAgent[*schema.AgenticMessage]` 是面向模型原生 Agentic 协议的新路径。迁移到该路径不只是把泛型参数从 `*schema.Message` 改成 `*schema.AgenticMessage`，还需要按 `AgenticMessage` 的 content block 结构处理消息内容。
+
+需要注意：
+
+- AgenticMessage 路径使用 `AgenticModel` 与 `AgenticToolsNode` 处理工具调用。
+- 工具调用和工具结果通过 `AgenticMessage` content block 表达，尤其需要正确处理 tool call / tool result content block。
+- Agent transfer 能力不适用于 AgenticMessage 路径。
+- 既有应用如果不需要模型原生 Agentic 协议，建议继续使用默认 `*schema.Message` 路径；只有在明确要接入 `AgenticModel` 协议时再迁移。
+
+### 模型适配器需要识别新增 option
+
+V0.9 引入 `AgenticModel` 后，模型适配器需要更严格地处理 call-time options。`AgenticModel` 是 `BaseModel[*schema.AgenticMessage]` 的别名，不再提供类似 `ToolCallingChatModel.WithTools` 的增强接口；工具绑定统一通过 `model.WithTools` 作为 `model.Option` 传入。
+
+需要注意：
+
+- 所有支持 AgenticMessage 的模型适配器都应读取 `Options.Tools`，并将其映射到 provider 的 tool calling 协议。
+- `AgenticModel` 不应要求用户先调用某个 `WithTools` 方法得到“带工具的模型实例”；ADK 会在每次模型调用时通过 `model.WithTools` 传递当前工具列表。
+- 如果适配器只从自身 config 读取工具，而忽略 `model.WithTools`，在 ChatModelAgent / AgenticToolsNode 路径下会出现模型看不到工具或工具列表不随运行态变化的问题。
+
+V0.9 还在 `model.Options` 中新增：
+
+- `DeferredTools`
+- `ToolSearchTool`
+- `AgenticToolChoice`
+
+现有模型适配器忽略这些 option 通常不会导致编译失败，但会导致 deferred tool search、模型原生 tool search 或 agentic tool choice 不生效。适配器维护者应按目标 provider 的协议补齐转换逻辑。
+
+### ToolInfo 序列化形态变化
+
+`ToolInfo` 增加显式 JSON/Gob 编解码，以保留 `ParamsOneOf`。
+
+影响：
+
+- `ToolInfo` 进入了 `ChatModelAgentState.ToolInfos` / `DeferredToolInfos`，因此可能随 Agent state 一起进入 checkpoint。
+- 显式 JSON/Gob 编解码用于保证 `ParamsOneOf` 在 checkpoint、deep copy 和恢复过程中不会丢失。
+- 如果外部系统直接依赖旧版 `ToolInfo` JSON 形态，需要重新确认序列化兼容性。

V0.9_RELEASE_FINDINGS.md

@@ -0,0 +1,90 @@
+<!--
+Copyright 2026 CloudWeGo Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# v0.9 Release Findings
+
+## Comparison Scope
+
+- Compared `alpha/09` against `main` using `main...alpha/09`.
+- `main` is the merge base of `alpha/09`.
+- Branch heads observed during analysis:
+  - `main`: `5e1305506c4fa89ef5d786035a947258e29a7593`
+  - `alpha/09`: `c39433511896d6a12e379a7958c6e5d489560b5a`
+- Second validation pass confirmed `main == origin/main`, `alpha/09 == origin/alpha/09`, and `main` is the merge base.
+- Diff size: `136 files changed`, `49,967 insertions`, `2,790 deletions`.
+- Changed surface is concentrated in `adk`, `schema`, `components/model`, `components/prompt`, `compose`, and callback helpers.
+
+## Primary Features
+
+| Area | v0.9 feature | Direct diff validation |
+| --- | --- | --- |
+| Agentic message model | Adds `schema.AgenticMessage`, content-block based message schema, provider extensions, streaming metadata, MCP/server/function tool blocks, and concat support. | `A schema/agentic_message.go`; concat registration in `schema/message.go`. |
+| Generic model abstraction | Introduces `model.BaseModel[M]`; keeps `BaseChatModel` as `BaseModel[*schema.Message]`; adds `AgenticModel`. | `M components/model/interface.go`. |
+| Typed ADK | Adds typed agents, typed events, typed runner, typed `ChatModelAgent`, and typed message variants while preserving default `*schema.Message` aliases. | `M adk/interface.go`, `M adk/chatmodel.go`, `M adk/runner.go`. |
+| Agentic ChatModelAgent path | `TypedChatModelAgent[*schema.AgenticMessage]` supports a single-shot agentic model path where tool calling is handled inside the model/message protocol. | `M adk/chatmodel.go`; `TypedChatModelAgent` and agentic ReAct path are added in the diff. |
+| Cancellation | Adds `WithCancel`, `CancelMode`, safe-point cancellation, recursive cancellation, timeout escalation, `CancelHandle`, and `CancelError` with resumable interrupt contexts. | `A adk/cancel.go`; cancel integration hunks in `adk/chatmodel.go`, `adk/flow.go`, and `adk/wrappers.go`. |
+| TurnLoop | Adds a push-based `TurnLoop` runtime with `Push`, non-blocking `Stop`, idle-stop, checkpoint/resume integration, and preempt handling. | `A adk/turn_loop.go`, `A adk/turn_buffer.go`. |
+| Model retry | Upgrades retry from error-only retryability to `ShouldRetry(ctx, RetryContext) -> RetryDecision`, allowing output inspection, input rewrite, option rewrite, backoff override, and reject reason. | `M adk/retry_chatmodel.go`. |
+| Model failover | Adds ChatModel failover with `ModelFailoverConfig`, `FailoverContext`, last-success model preference, and callback-aware proxying. | `A adk/failover_chatmodel.go`; config wiring in `adk/chatmodel.go`. |
+| Tool search | Adds dynamic tool search middleware with both client-side search and model-native deferred tool search via `DeferredToolInfos`, `WithDeferredTools`, and `WithToolSearchTool`. | `M adk/middlewares/dynamictool/toolsearch/toolsearch.go`, `M components/model/option.go`. |
+| Middleware modernization | Generifies summarization, reduction, skill, filesystem, plan-task, patch-tool-calls and adds `AfterAgent`; state now carries `ToolInfos` and `DeferredToolInfos` as the recommended mutable model-call surface. | Diff hunks in `adk/handler.go`, `adk/middlewares/*`, and `adk/prebuilt/deep/deep.go`. |
+| Summarization API | Adds `TypedMiddleware.Summarize` and typed finalizer/customized-action paths; removes the old standalone `SummarizeMessages` / `SummarizeOutput` API in favor of middleware-owned summarization. | `M adk/middlewares/summarization/summarization.go`, `M customized_action.go`, `M finalizer_builder.go`. |
+| Compose/tooling | Adds `AgenticToolsNode` and tool name/argument aliases for `ToolsNode`. | `A compose/agentic_tools_node.go`, `M compose/tool_node.go`. |
+| Prompt/callback support | Adds agentic prompt templates and callback types for agentic prompt/model/tools/agent components. | `A components/prompt/agentic_chat_template.go`, `A components/*/agentic_callback_extra.go`, `M utils/callbacks/template.go`. |
+| Filesystem | Adds enhanced multimodal read support and PDF page validation. | `M adk/filesystem/backend.go`, `M adk/middlewares/filesystem/filesystem.go`. |
+| Agents.md | Adds `agentsmd` middleware for automatically loading and injecting `AGENTS.md`-style instructions. | `A adk/middlewares/agentsmd/agentsmd.go`, `A loader.go`. |
+
+## Compatibility Notes
+
+| Impact | Note |
+| --- | --- |
+| Source break for custom middleware implementers | `ChatModelAgentMiddleware` now includes `AfterAgent`. Any user-defined type that manually implements the interface must add this method or embed `BaseChatModelAgentMiddleware`. |
+| Middleware tool mutation semantics | `ModelContext.Tools` is now deprecated as a mutation surface; tool list changes should happen through `state.ToolInfos` / `state.DeferredToolInfos` in `BeforeModelRewriteState`. Mutating tools in `WrapModel` only affects one model call and is explicitly discouraged. |
+| Summarization standalone API removal | `summarization.SummarizeMessages` and `summarization.SummarizeOutput` are no longer exported. Use `New` / `NewTyped` to construct middleware, or call `TypedMiddleware.Summarize` when direct summarization is needed. |
+| Retry behavior change | If `ShouldRetry` is set, `IsRetryAble` is ignored. In streaming mode, the full stream is consumed before the retry decision is made, although events are still emitted in real time. |
+| Retry cancellation semantics | Retry now treats interrupts and `ErrStreamCanceled` as non-retryable and uses context-aware backoff rather than unconditional sleep. Users relying on retrying interrupt/cancel errors should adjust policy. |
+| Cancellation error semantics | During active cancel, business interrupts are absorbed into `CancelError`; the checkpoint preserves interrupt contexts and business interrupt can re-fire on resume. Consumers should handle `CancelError` separately from ordinary business interrupts. |
+| TurnLoop stop semantics | `TurnLoop.Stop` is non-blocking; use `Wait` for terminal state. Cancel-related stop options degrade to "finish current turn then exit" if the running agent does not support `WithCancel`. `UntilIdleFor` silently drops cancel options in the same call. |
+| Agentic path limitations | `TypedChatModelAgent[*schema.AgenticMessage]` is not feature-equivalent to `*schema.Message`: it uses a single-shot path, does not support agent transfer, and cancel monitoring/retry on model streams are not yet wired. |
+| Model adapters must honor new options | Native tool search requires model implementations to read `Options.DeferredTools`, `Options.ToolSearchTool`, and `Options.AgenticToolChoice`. Existing adapters that ignore unknown common options will compile but will not support the new behavior. |
+| Serialization shape change | `ToolInfo` now has explicit JSON/Gob encoding that preserves `ParamsOneOf`. This fixes checkpoint/deep-copy loss, but external systems depending on the previous raw JSON shape should re-check serialized payloads. |
+| Filesystem page validation | Multimodal read validates PDF `pages` and rejects ranges over 20 pages per request. Users passing arbitrary page ranges should handle validation errors. |
+| Transfer/workflow/supervisor positioning | Agent transfer, workflow agents, and supervisor are not removed, but many APIs now carry `NOT RECOMMENDED` guidance in favor of `ChatModelAgent` + `AgentTool` or `DeepAgent`. This is a semantic/product-direction compatibility note, not a signature break. |
+
+## Likely Non-Breaking Alias Changes
+
+- `BaseChatModel` becomes an alias of `BaseModel[*schema.Message]`; existing implementations with `Generate(ctx, []*schema.Message, ...)` and `Stream(ctx, []*schema.Message, ...)` should still satisfy it.
+- `Agent`, `AgentInput`, `AgentEvent`, `AgentOutput`, `ChatModelAgent`, `ChatModelAgentConfig`, `ChatModelAgentState`, `ModelContext`, and several middleware config types are preserved as `*schema.Message` aliases over typed forms.
+- `ToolOutputPart`, `ToolResult`, and related tool-result types moved from `schema/message.go` to `schema/tool.go`, but remain in package `schema`, so import paths and qualified names are unchanged.
+
+## Validation Results
+
+Completed checks:
+
+- Direct branch-ref validation:
+  - Verified `main == origin/main`, `alpha/09 == origin/alpha/09`, and the merge base is `main`.
+  - Rechecked each retained feature row with `git diff main...alpha/09` file status or hunks.
+  - Removed raw AST API-diff counts from the release findings because the script over-reported generic alias refactors as removals.
+- Representative downstream compatibility compile check:
+  - `GOWORK=off go test .` passed in a temporary external module using `replace github.com/cloudwego/eino => ..`.
+  - Verified that existing `BaseChatModel` implementations still compile against the `BaseModel[*schema.Message]` alias.
+  - Verified that `ChatModelAgentConfig`, `summarization.Config`, `reduction.Config`, `skill.Config`, `ToolResult`, and new model options are usable from downstream code.
+  - Verified that embedding `*adk.BaseChatModelAgentMiddleware` remains the safe compatibility path for middleware implementations.
+- Negative compile check for old custom middleware:
+  - `GOWORK=off go test -tags=oldmiddleware .` fails as expected with: `oldStyleMiddleware does not implement adk.TypedChatModelAgentMiddleware[*schema.Message] (missing method AfterAgent)`.
+  - This confirms the `AfterAgent` source compatibility note for users who manually implement `ChatModelAgentMiddleware` without embedding the base middleware.
+- Targeted package tests:
+  - `go test ./adk ./adk/middlewares/summarization ./adk/middlewares/reduction ./adk/middlewares/skill ./adk/middlewares/dynamictool/toolsearch ./components/model ./components/prompt ./compose ./schema` passed.