fix(middleware): expose runtime context in onAgent

[guslegend0510]

AgentScope-Java Version

2.0.0-SNAPSHOT

Description

背景

当前 MiddlewareBase#onAgent(...) 中传入的 Agent 参数没有稳定可用的 getRuntimeContext() 访问入口，导致 middleware 想读取或修改运行时上下文时，只能依赖 instanceof AgentBase 之类的实现细节判断。
这会带来两个问题：

1. MiddlewareBase 的公共扩展点和 Agent 的公共契约不一致；
2. onAgent 阶段即使拿到了 Agent，也可能无法直接访问有效的 RuntimeContext。

这个 PR 主要是修复 issue #1672，让 middleware 在 onAgent 阶段可以通过统一 API 访问运行时上下文。

目的

让 MiddlewareBase#onAgent(...) 中的 agent 参数具备稳定、统一的 RuntimeContext 访问能力，避免 middleware 依赖 AgentBase 的具体实现细节。

主要改动

1. 在 Agent 接口中新增默认方法 getRuntimeContext()，将运行时上下文暴露为公共契约的一部分。
2. 在 AgentBase / HarnessAgent 上对该能力进行对接，保持现有实现一致。
3. 调整 ReActAgent 的 runtime context 生命周期：
   • 在 onAgent middleware 执行前即可访问当前调用对应的 RuntimeContext；
   • 真正进入 call() 生命周期后复用同一份上下文对象；
   • 对 middleware 短路场景补充清理逻辑，避免 context 泄漏到下一次调用。
4. 清理 core / harness 中相关 middleware 对 AgentBase 的 instanceof 依赖，统一改为使用 agent.getRuntimeContext()。
5. 保留 agent == null 的兼容处理，避免已有单元测试或边界调用因为直接访问新接口而触发 NPE。
6. 新增回归测试，验证：
   • onAgent 可以拿到 live RuntimeContext
   • onAgent 中写入的上下文数据可以继续被后续 hook / phase 读取

如何测试

已执行以下定向验证：

mvn -pl agentscope-core "-Dtest=ReActAgentMiddlewareIntegrationTest" test "-Dsurefire.failIfNoSpecifiedTests=false"
mvn -pl agentscope-harness -am "-Dtest=AtPathExpansionMiddlewareTest" test "-Dsurefire.failIfNoSpecifiedTests=false"

重点关注：

ReActAgentMiddlewareIntegrationTest#onAgentHookCanAccessLiveRuntimeContext
AtPathExpansionMiddlewareTest

Checklist

Code has been formatted with mvn spotless:apply
All tests are passing (mvn test)

Javadoc comments are complete and follow project conventions
Related documentation has been updated (e.g. links, examples, etc.)

Code is ready for review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[guslegend0510]

@LearningGp 麻烦审核一下谢谢

[AgentScopeJavaBot]

🤖 AI Review

This PR cleanly resolves issue #1672 by promoting getRuntimeContext() to the Agent interface as a default method, eliminating the need for instanceof AgentBase casts throughout middleware code. The lifecycle management for RuntimeContext in ReActAgent is well-designed — Flux.defer() ensures lazy context creation at subscription time, ensurePendingRuntimeContext() guarantees availability before middleware execution, and clearPendingRuntimeContextIfUnbound() handles both normal completion and short-circuit scenarios correctly. Test coverage is comprehensive, covering live context access, caller-supplied contexts, short-circuit cleanup, and post-invocation nullness. One minor cleanup opportunity exists (dead-code null check), but no functional issues were found.