将 ChatRuntime / ChannelLlmReplyInboxRuntime 收敛为 actor-owned Agent Continuation

[eanzhao]

背景

这个 issue 承接 Discussion #568 的 Agent Continuation 方向，用来讨论并落地当前 Lark bot / channel reply / agent chat 链路里的 runtime 边界问题。

更新：已采纳 issue comment 中的替代 phasing。最终方向调整为：先把错误的 hosted-service 容器换成 run-scoped actor，再补观察；ES 只记录业务事实，不把每个 LLM round / tool call 都持久化；tool 按能力边界分流，不一刀切 actor 化。

相关讨论：#568

当前问题

简化后的当前链路：

%%{init: {"maxTextSize": 100000, "flowchart": {"useMaxWidth": false, "nodeSpacing": 10, "rankSpacing": 50}, "themeVariables": {"fontSize": "10px"}}}%%
flowchart LR
  C["ConversationGAgent"] --> I["ChannelLlmReplyInboxRuntime\nIHostedService singleton"]
  I --> G["NyxIdConversationReplyGenerator"]
  G --> R["ChatRuntime"]
  R --> L["LLMProvider"]
  R --> T["ToolCallLoop / StreamingToolExecutor"]
  T --> Tools["Tools / Skills"]
  R --> G
  G --> I
  I --> C

Loading

诊断

1. ChannelLlmReplyInboxRuntime 是 IHostedService 单例，却承担 stale gate、metadata enrichment、fallback timeout、drop classification、streaming sink build、reply-ready 回送等 run-scoped 决策。这是当前最不符合 actor-owned continuation 的容器。

2. ChatRuntime / ToolCallLoop 通过本地 for loop 承载 LLM/tool 多轮推进，本质也是 in-stack continuation。但它不是第一阶段最该动的点。先把外层容器换正确，再逐步拆内层 loop。

3. ConversationGAgent 是 conversation-scoped 权威事实源，不能把真实 LLM/tool IO 塞回它的 actor turn，否则群聊/频道会变成热点串行执行容器。

4. 不应把每个 LLM round / tool call 都做成 ES 持久化事件。它们更多是 run trace / usage ledger / observability，不是恢复业务正确性所需的权威事实。

5. tool 不要一刀切 actor 化。跨 actor / 外部异步能力需要 continuation；纯函数、短耗时、无副作用工具可以继续 inline。

目标架构

第一目标不是立刻删除 ChatRuntime，而是先让一次 reply/run 有正确的 actor 容器：

%%{init: {"maxTextSize": 100000, "flowchart": {"useMaxWidth": false, "nodeSpacing": 10, "rankSpacing": 50}, "themeVariables": {"fontSize": "10px"}}}%%
flowchart LR
  Ingress["Lark / NyxID Relay"] --> C["ConversationGAgent\nadmission / dedup / pending / delivery commit"]
  C --> D["IChannelLlmReplyRunDispatcher\nthin port, no state"]
  D --> R["AgentRunGAgent[runId]\nrun-scoped continuation owner"]

  R --> CR["ChatRuntime\ntransitional local loop"]
  CR --> L["LLMProvider\nsingle sampling IO"]
  CR --> T["Tools / Skills\ninline or actor-backed"]

  R -->|"LlmReplyReadyEvent / Drop"| C
  R --> O["Observation\ntransient run steps + terminal facts"]
  C --> Outbound["Channel outbound reply/edit"]

Loading

命名说明：实现底层可以仍然是 Orleans grain，但仓库代码命名优先使用 GAgent，所以先用 AgentRunGAgent 而不是 AgentRunGrain。

职责边界

ConversationGAgent

• conversation-scoped 唯一权威状态。
• 负责入站准入、去重、pending reply、最终 delivery commit。
• 不执行长耗时 LLM/tool IO。
• 从“enqueue inbox runtime”改为“dispatch run actor”。

IChannelLlmReplyRunDispatcher

• 位于 Channel.Runtime 抽象层。
• 只做投递端口，不持有 run state。
• 让 ConversationGAgent 不直接依赖 NyxidChat 的具体 run actor 实现。

AgentRunGAgent

• 以 runId = correlationId 寻址。
• 拥有一次 Lark bot reply / agent run 的 continuation。
• 第一阶段 1:1 承接 ChannelLlmReplyInboxRuntime.ProcessAsync 的逻辑。
• 初期内部仍可调用现有 IConversationReplyGenerator / ChatRuntime，降低迁移风险。
• ES 只记录 run started / result produced / failed / dropped 等最小业务事实。

ChatRuntime

• 第一阶段保留为 transitional local loop。
• 不再作为长期核心抽象继续扩展 run 语义。
• 后续拆成 prompt/message builder、single LLM sampling adapter、stream normalizer、tool-call parser 等小组件。

Tools / Skills

• actor-backed / external async tool：走 continuation。
• pure/local tool：继续 inline。
• skills lifecycle 与进程级 registry 问题单独开议题，不绑死在第一阶段。

实施步骤

Phase A：杀掉 hosted-service，落 run-scoped actor

这是第一批 PR 的目标范围。

1. 新增 AgentRunGAgent 及最小 state / event contract。

   • 建议先放在 Aevatar.GAgents.NyxidChat，因为当前依赖 IConversationReplyGenerator、NyxID relay options、UserConfig 等 NyxidChat 侧服务。
   • runId 使用 correlationId。

2. 新增 IChannelLlmReplyRunDispatcher。

   • 放在 Aevatar.GAgents.Channel.Runtime。
   • 方法语义类似 DispatchAsync(NeedsLlmReplyEvent request, CancellationToken ct)。
   • 不保留 service-level dictionary / queue / run state。

3. 在 NyxidChat 中实现 dispatcher。

   • 创建或获取 AgentRunGAgent[runId]。
   • 向 run actor 投递 typed command，例如 AgentRunStartRequested。

4. 迁移 ChannelLlmReplyInboxRuntime.ProcessAsync 逻辑到 AgentRunGAgent。

   • malformed / stale / missing relay token gate。
   • metadata enrichment。
   • fallback timeout。
   • streaming sink build。
   • IConversationReplyGenerator.GenerateReplyAsync。
   • LlmReplyReadyEvent / DeferredLlmReplyDroppedEvent 回送 ConversationGAgent。

5. 修改 ConversationGAgent.DispatchPendingLlmReplyAsync。

   • 从 IChannelLlmReplyInbox.EnqueueAsync 改为 IChannelLlmReplyRunDispatcher.DispatchAsync。
   • 保留现有 durable retry / rehydration 语义。

6. 下线旧 inbox runtime。

   • 移除 ChannelLlmReplyInboxRuntime / ChannelLlmReplyInboxHostedService 注册。
   • 移除或废弃 IChannelLlmReplyInbox。
   • 移除 channel-runtime:llm-reply:inbox stream。

7. 测试迁移。

   • ChannelLlmReplyInboxRuntimeTests 迁到 AgentRunGAgentTests。
   • 保持现有 ConversationGAgent dedup / reply-token / streaming 行为不回退。

建议验证：

dotnet test test/Aevatar.GAgents.ChannelRuntime.Tests/Aevatar.GAgents.ChannelRuntime.Tests.csproj --nologo
dotnet test test/Aevatar.GAgents.Channel.Protocol.Tests/Aevatar.GAgents.Channel.Protocol.Tests.csproj --nologo
bash tools/ci/test_stability_guards.sh

Phase B：观察走 transient stream + readmodel，不做 ES 写放大

1. AgentRunGAgent 终态事实进入 ES：started、result produced、failed、dropped。
2. 每轮 LLM/tool 完成时发布 transient observation，例如：

RunStepObserved(runId, stepKind, model, latency, tokenIn, tokenOut, toolName, success)

3. 物化为 trace/telemetry 型 readmodel，例如 active_runs、run_trace、tool_usage_stats。
4. 不把 LLMSamplingRequested/Completed、ToolInvocationRequested/Completed 默认写入 ES。

Phase C：actor-backed tool 走 continuation

1. 给 tool/capability 增加执行边界描述：Inline / ActorBacked / ExternalAsync。
2. Inline tool 继续在当前调用栈执行。
3. ActorBacked / ExternalAsync tool：
   • run actor 记录 pending invocation。
   • 发 command 或事件。
   • 当前 turn 结束。
   • 回执事件唤醒 run actor 继续。
4. 不把纯函数工具 actor 化。

Phase D：metadata enrichment 前移到 admit / routing policy

1. bot owner LLM config / sender preference 是入站 routing 决策，逐步前移到 ChannelConversationTurnRunner / admit policy。
2. AgentRunGAgent 只消费已经固化的 effective metadata。
3. secret token 仍只走 transient command，不进 ES、不进 readmodel。

Phase E：拆掉 ChatRuntime 的 loop 职责

1. 把 ChatRuntime 拆成小组件：

   • prompt/message builder
   • single LLM sampling adapter
   • stream normalizer
   • tool-call parser
   • length recovery helper

2. 多轮推进由 AgentRunGAgent 的 actor event choreography 决定。

3. ToolCallLoop / StreamingToolExecutor 逐步退化为局部 helper 或删除。

非目标

• 不要求 NyxID / Ornn / chrono-* 外部仓库新增 endpoint 或 schema。
• 不做插件市场。
• 不把 LLM/tool 长耗时 IO 塞回 ConversationGAgent 的单个 actor turn。
• 第一阶段不解决 skills lifecycle / registry 的完整治理问题。
• 第一阶段不要求每个 LLM round / tool call 都成为 ES 持久化事件。

第一批 PR 的验收标准

• ChannelLlmReplyInboxRuntime 不再作为 hosted service 参与生产链路。
• deferred LLM reply 由 ConversationGAgent -> dispatcher -> AgentRunGAgent -> ConversationGAgent 完成。
• reply token 不进入持久化 state / event store / readmodel。
• stale / malformed / missing token drop 行为保持。
• streaming reply 行为保持，包括 final chunk 与 ready event 的顺序保护。
• 现有 channel runtime / protocol 测试通过。

[eanzhao]

补一个替代 phasing,作为讨论入口(我自己倾向这条路径)。

同意诊断

• ChannelLlmReplyInboxRuntime 是 IHostedService 单例,却承担了 stale gate / metadata enrichment / fallback timeout / drop classification / streaming sink build 这些 run-scoped 决策——这是当前最违反 CLAUDE.md "Actor 即业务实体 / 中间层状态约束"的形状。
• ChatRuntime + ToolCallLoop 的多轮 for 循环是 in-stack continuation,与"Actor 执行模型 / 跨 actor 等待 continuation 化"不一致。
• conversation 是热点 actor,确实不能塞 LLM/tool IO 进它的 turn。

想压一压的部分

1. Phase 顺序倾向反过来:先换容器,再加 observability。

issue 当前 Phase 1 是先在两个旧 runtime 上挂 typed observation。但 inbox runtime 自身的容器就是错的(hosted-service singleton 持有 run-scoped 决策),在错的容器上埋点意味着下一步还要拆一次。先把容器换成 virtual actor,事件自然落在 actor 内、由 actor 自己 emit,反而更省。

2. 不要 ES 到每轮 LLM round / 每个 tool call。

issue 列的事件链 LLMSamplingRequested → ...Completed → ToolInvocationRequested → ...Completed → TurnContinuationDecided 做成 typed event 没问题,但做成 ES 持久化事件过重:

• LLM 一次 sampling 失败重来不依赖 event store(OpenAI / NyxID 不暴露 idempotency key),事件只是"我们试过了"的痕迹,不是 resumability。
• 每轮 2 条事件 × N 轮 × M 会话 = 真实写放大。
• 想要 timeline 观察走 readmodel + transient stream(每轮一条 round summary)就够。
• ES 只承载真正的业务事实:run started、reply delivered(side-effect committed)、terminal。

3. tool 不要一刀切 actor 化。

"跨 actor 等待 continuation 化"管的是跨 actor,不是凡是 tool 都 continuation:

• actor-backed tool(ServiceInvoke / Workflow / 远端 Skill 拉取)→ 发 ToolInvocationRequested,end turn,等回执唤醒。
• 纯函数 tool(格式化 / 计算 / 字符串处理)→ inline await,不发事件。

一刀切 actor 化只换来事件爆炸,没有新约束 / 能力。

4. Turn vs Run 当前一层就够。

lark-bot 入站路径是 一次 LLM/tool cycle = 一次 reply,turn 与 run 是同一件事。先用 AgentRunGrain[runId] 一层;等真的有跨 turn 的 run 语义(plan-execute / multi-turn ack)再分。否则就是 trivial-check 想堵的"只是改名"。

替代 phasing

[今] ConversationGAgent
       → ChannelLlmReplyInboxRuntime (hosted-service singleton)
       → ChatRuntime (callstack for-loop)
       → LLM / tools

[标] ConversationGAgent
       → AgentRunGrain[runId] (virtual actor)
       → ChatRuntime (loop on actor turn, continuation 仅给 actor-backed tool)
       → LLM / tools

Phase A — 杀掉 hosted-service,落 virtual actor

• 新增 IAgentRunGrain,按 runId = correlationId 寻址。
• 1:1 搬过来 ChannelLlmReplyInboxRuntime.ProcessAsync 的逻辑(metadata enrichment / stale gate / fallback timeout / IConversationReplyGenerator.GenerateReplyAsync / LlmReplyReadyEvent 回送)。代码几乎不动。
• ConversationGAgent.DispatchPendingLlmReplyAsync 从 inbox.EnqueueAsync 改成往 AgentRunGrain[runId] 投 command。
• AgentRunGrain ES 事件仅 4 条:AgentRunStarted / AgentRunReplyDelivered / AgentRunCompleted / AgentRunFailed。LLM round / tool 不进 ES。
• ChannelLlmReplyInboxRuntime / IChannelLlmReplyInbox / channel-runtime:llm-reply:inbox stream 全部下线。
• 测试从 ChannelLlmReplyInboxRuntimeTests 迁到 grain 测试。

Phase B — observability via readmodel

• AgentRunGrain 每轮 LLM/tool 完成时往 transient stream 推 RunStepObserved(runId, stepKind, model, latency, tokenIn/Out, toolName, success)。
• projection 物化为 readmodel active_runs / tool_usage_stats。
• ES 仍然只承载终态 / 侧效。

Phase C — actor-backed tool 走 continuation

• ToolCallLoop 执行 tool 前判定 capability 类型:actor-backed 发事件 + self-message resume;纯函数 inline。
• streaming chunk 路径不动(继续 sink → ConversationGAgent)。

Phase D — metadata enrichment 下移到 ConversationGAgent admit

• bot owner LLM config / sender preference 本质是入站时的 conversation-scoped routing 决策,移进 admit policy。
• AgentRunGrain 只消费已固化的 effective metadata。

对原 phase 计划的差异

维度	原 phase 计划	替代
先做什么	observation events	换容器(hosted-service → virtual actor)
LLM round 是否进 ES	是	否,走 readmodel + transient
tool 是否一律 actor	倾向是	按 capability 类型
Turn vs Run	两层(待讨论)	当前一层

回应原 issue 的 6 个 open questions

1. 命名 → AgentRunGrain 一层够用,等需要时再分。
2. 完成契约 → AgentRunGrain emit AgentRunCompleted/Failed 到 ConversationGAgent,conversation 仍持久化 ConversationTurnCompletedEvent(保持现状)。
3. streaming delta → transient stream,不进 durable。
4. tool actor 化 → 只 actor-backed 的走,纯函数不走。
5. skills lifecycle → 单独议题,不在第一阶段裹挟。
6. Phase 2 内部继续调 ChatRuntime → 同意,初期就是这样;loop 拆解走 Phase C。