RFC: 统一外部长连接流为 actor 一等抽象（SessionStreamGAgent 方向）— 求团队讨论与互评

[loning]

id: cluster-triage-stream-session-actor-contract
severity: high
requires_design: true

来源

本 issue 由 maintainer 手动开，maintainer 重新加 auto-loop-triage 后，triage codex 按当前代码重新调研并补充 evidence。

核心问题

外部长连接 session 还没有一套 runtime-neutral、actor-owned 的统一 contract。NyxIdChat SSE 现在通过 request handler 持有 writer 并把 AGUIEvent 直接映射到 HTTP response；VoicePresence 已经把部分 session/lease 事实收敛进 actor-owned state，但 host 侧仍以 capability preflight + lease handle + volatile transport attachment 组合承载连接接续；Channel inbound 另有 in-process transport buffer；CQRS/AGUI 还有 EventChannel<T> sink。

这些局部修复方向大体正确，但缺少统一的 StreamSessionGAgent / StreamFrame 设计边界时，后续 solver 很容易再次把外部长连接、projection observation、channel webhook、LLM token delta、voice media data plane 都混成一个 “streaming” 抽象，违反 actor 边界、读写分离、投影主链和内部状态 Protobuf 建模要求。

本 issue 是 design issue，不要求在同一 PR 内实现完整流处理子系统；目标是把外部长连接 session 的权威 owner、frame 范围、projection/AGUI/channel 边界、host failover/replay 语义裁定清楚，再拆 first-slice implementation。

Evidence

1. NyxIdChat streaming endpoint 仍由 HTTP request handler 持有 live SSE writer

agents/Aevatar.GAgents.NyxidChat/NyxIdChatEndpoints.Streaming.cs:73

var writer = new NyxIdChatSseWriter(http.Response);
...
var result = await interactionService.ExecuteAsync(
    new NyxIdChatCommand(...),
    async (evt, _) =>
    {
        await NyxIdChatStreamingRunner.WriteAguiEventAsync(evt, messageId, writer);
    },
    null,
    ct);

违反点：命令交互骨架已经比旧 runner 收敛，但外部长连接 session 的 lifecycle、seq、ack、reconnect、replay/gap 仍没有 actor-owned contract。HTTP request 只应持有 wire handle；连接会话事实不能由 Host/request stack 暗含。

2. NyxIdChatStreamingRunner 当前只是 AGUI 到 NyxId SSE 的 presentation mapper

agents/Aevatar.GAgents.NyxidChat/NyxIdChatStreamingRunner.cs:8

internal static class NyxIdChatStreamingRunner
{
    public static async ValueTask<string?> WriteAguiEventAsync(
        AGUIEvent aguiEvent,
        string messageId,
        NyxIdChatSseWriter writer)

违反点：早期 TaskCompletionSource + SubscribeAsync<EventEnvelope> + Task.Delay 形态已经不再是当前代码证据；当前剩余问题不是“给 runner 打补丁”，而是缺少一个可复用的 external stream session contract，让 NyxIdChat outbound、approval continuation、AGUI wire mapping 与 connection delivery 语义分层。

3. VoicePresence 已有 actor-owned lease/state，但 session 仍是能力专用形状

src/Aevatar.Foundation.VoicePresence.Abstractions/Protos/voice_presence.proto:81

message VoicePresenceRuntimeState {
  VoicePresenceRuntimeStatus status = 1;
  ...
  string active_session_id = 15;
  google.protobuf.Timestamp lease_expires_at = 16;
  string active_transport_lease_id = 18;
  string active_lease_owner_id = 19;
  int64 lease_epoch = 21;
}

src/Aevatar.Foundation.VoicePresence/Hosting/ActorOwnedVoicePresenceSessionResolver.cs:86

var leaseRequest = new VoicePresenceSessionLeaseRequest(
    capability.ActorId,
    capability.ModuleName,
    Guid.NewGuid().ToString("N"),
    HostOwnerId,
    _timeProvider.GetUtcNow().Add(DefaultLeaseTtl),
    capability.StateVersion,
    capability.RemoteAudioSupport);

违反点：VoicePresence 是最接近正确形状的现有实现，但它是 voice-specific session/lease contract，不是通用 external stream session contract。ADR 需要决定哪些语义上提为共享 StreamSession，哪些留在 VoicePresence typed media/session domain。

4. Voice transport callbacks 已事件化，但 frame/replay/drop 语义仍按能力自定义

src/Aevatar.Foundation.VoicePresence.Abstractions/Protos/voice_presence.proto:225

message VoiceTransportControlFrameReceived {
  string session_id = 1;
  string transport_lease_id = 2;
  VoiceControlFrame control_frame = 3;
  string owner_id = 4;
  google.protobuf.Timestamp lease_expires_at = 5;
  int64 lease_epoch = 6;
}

message VoiceTransportAudioFrameReceived {
  string session_id = 1;
  string transport_lease_id = 2;
  bytes pcm16 = 3;
  ...
}

违反点：control/audio 都已强类型且事件化，这是正确方向；但通用 stream design 必须明确 text/tool/control/lifecycle 可 replay，heartbeat/audio/video 默认不 replay 或走 media fast path，不能让每个 capability 用不同隐式规则处理 seq/ack/gap。

5. Channel transport 明确是 in-process inbound buffer，不是 durable/session 边界

agents/Aevatar.GAgents.Channel.Abstractions/Transport/IChannelTransport.cs:14

/// InitializeAsync must succeed exactly once before StartReceivingAsync.
/// The inbound stream is a single-reader, in-process buffer and is not the durable ingress boundary.
...
ChannelReader<ChatActivity> InboundStream { get; }

违反点：channel webhook / bot adapter 的 IChannelTransport 不能被直接收编为 StreamSessionGAgent。它处理平台绑定、鉴权、normalize 和 inbound buffer；只有真正需要长连接接续、seq/ack、replay/gap 的连接才进入 StreamSession 抽象。

6. CQRS EventChannel<T> 是 sink/backpressure primitive，不是 actor-owned session fact source

src/Aevatar.CQRS.Core.Abstractions/Streaming/EventSink.cs:33

public sealed class EventChannel<TEvent> : IEventSink<TEvent>
{
    private readonly Channel<TEvent> _channel;
    ...
    public async IAsyncEnumerable<TEvent> ReadAllAsync(...)

违反点：EventChannel<T> 适合作为 projection/interaction live sink，但它是进程内 channel，不拥有跨 host/session 事实。AGUI/CQRS observation 可以继续走统一 Projection Pipeline；外部长连接 delivery contract 不能退化成 sink channel 或 request-local writer。

7. NyxID 是外部能力 surface，不应要求改外部仓库

已按仓库规则检查 ../NyxID 存在。NyxID 当前文档/代码已经提供代理、SSE passthrough、LLM gateway streaming、channel bot relay 等外部能力 surface；本 issue 不要求 NyxID 增加端点、改 schema 或承担 aevatar 的 session actor contract。aevatar 应在本仓库内用现有外部 surface 适配。

违反条款

AGENTS.md / CLAUDE.md：

• 严格分层：Domain / Application / Infrastructure / Host；API 仅做宿主与组合，不承载核心业务编排。
• 投影编排 Actor 化：Projection 的会话、订阅、关联关系等运行态必须由 Actor 或分布式状态承载；禁止在中间层通过进程内注册表/字典持有事实状态。
• 明确读写分离：Command -> Event，Query -> ReadModel；异步完成通过事件通知与推送，不在会话内临时拼装流程。
• 已提交领域事件必须可观察：write-side 一旦完成 committed domain event，必须把该事实送入统一 observation/projection 主链。
• 投递语义必须 runtime-neutral：publish/send 统一表示进入目标 actor inbox 等待处理，不得因 self 或 runtime 差异退化为 inline dispatch。
• ACK 语义必须诚实：同步返回只能承诺已经真实达到的阶段，默认应是 accepted for dispatch + stable command id。
• 查询始终走 readmodel；不得把 actor 内部状态、state mirror payload 或 event replay 暴露成查询主路径。
• projection 只消费 committed 事实：禁止订阅入站 command、self continuation 或 actor 运行时偶然结构去推测业务完成态。
• Actor/模块运行态只能在事件处理主线程修改；回调只发信号。
• 中间层禁止维护 entity/actor/workflow-run/session 等 ID 到上下文或事实状态的进程内映射。
• 所有序列化与反序列化操作统一使用 Protobuf，尤其是 State、领域事件、命令、回调载荷、快照、缓存载荷、跨 Actor/跨节点内部传输对象。

新原则

外部长连接 session 是 actor-owned delivery state，不是 projection hub、channel webhook、AGUI event 名字或 request-local SSE writer。StreamSessionGAgent 只拥有连接投递事实：session lifecycle、attachment、seq、ack、heartbeat、bounded replay window、gap/resync。业务事实仍由 consumer actor 拥有并提交 typed domain events；Projection Pipeline 继续只消费 committed facts 并一对多物化 readmodel/AGUI observation。

AGUI 保留为 presentation wire format；StreamFrame 是内部 session/delivery frame。需要把 projection observation 推给前端时，由 adapter 映射成 AGUI/SSE/WebSocket wire，不把 Projection Pipeline 折成 long-lived bidirectional session hub。

Channel inbound 继续走 IChannelTransport -> ChatActivity -> durable inbox/conversation。Webhook-only inbound 不是 stream session；只有具备长连接接续、seq/ack、replay/gap 的 transport attachment 才接入 StreamSession。

Fix boundary

建议 scope paths：

• docs/adr/00xx-stream-session-actor-contract.md
• src/Aevatar.Foundation.Abstractions/Streaming/*
• src/Aevatar.Foundation.Runtime/Streaming/*
• src/Aevatar.Foundation.Runtime.Implementations.Orleans.Streaming/*
• src/Aevatar.CQRS.Core.Abstractions/Streaming/EventSink.cs
• src/Aevatar.CQRS.Core/Streaming/*
• src/Aevatar.Presentation.AGUI/*
• agents/Aevatar.GAgents.NyxidChat/NyxIdChatEndpoints.Streaming.cs
• agents/Aevatar.GAgents.NyxidChat/NyxIdChatStreamingRunner.cs
• src/Aevatar.Foundation.VoicePresence.Abstractions/Protos/voice_presence.proto
• src/Aevatar.Foundation.VoicePresence/Hosting/*
• src/Aevatar.Foundation.VoicePresence/Modules/VoicePresenceModule.cs
• agents/Aevatar.GAgents.Channel.Abstractions/Transport/IChannelTransport.cs
• agents/Aevatar.GAgents.Channel.Runtime/TurnStreamingReplySink.cs
• agents/Aevatar.GAgents.Scheduled/SkillRunnerStreamingReplySink.cs
• focused tests under test/Aevatar.AI.Tests/, test/Aevatar.Foundation.VoicePresence.Tests/, test/Aevatar.Foundation.Runtime.Hosting.Tests/, and CQRS/AGUI tests as touched.

避免 scope：

• 不改 NyxID / chrono / Ornn 等外部 sibling repositories。
• 不把 long-lived bidirectional stream 折回 Projection Pipeline。
• 不把 IChannelTransport 的 webhook/inbound abstraction 改名或强行收编为 StreamSession。
• 不用 Metadata / string key 决定 frame 是否持久化；业务持久化规则必须在 consumer actor typed policy 中表达。
• 不在 Host/API 保存 session_id -> context/writer/transport 事实状态；host 只能持有 volatile wire handle。
• 不在首个 implement slice 中一次性吃下 audio/video/screen 全模态；先裁定 P0 text/tool/approval/control/lifecycle 与 media fast path 边界。

human_brief

这是 refactor loop 范畴，原因是它直接触及 AGENTS/CLAUDE 的 actor session 状态、projection 主链、CQRS/AGUI 统一 observation、Host 只做 wire adapter、Protobuf 强类型建模等架构规则。当前 issue 已有团队评论收敛到 StreamSessionGAgent 命名、AGUI 保留 wire format、channel inbound 不收编、text/control 与 media data plane 分层等方向；下一步需要 Phase 9 design-solving 把这些收敛意见变成可执行 ADR + first-slice 边界。

建议 first-slice 不直接“统一所有 stream”，而是输出 ADR 与 P0 contract：StreamSessionGAgent / StreamSessionState / StreamFrame 覆盖 text、tool、approval、control、lifecycle、heartbeat、ack；NyxIdChat outbound 是第一个落地点；VoicePresence 作为 P1/Poc 验证 media fast path 与 audio non-replay；AGUI sink/EventChannel 和 reply throttler 合并作为后续独立 slice。

Decision questions

1. Actor 命名是否裁定为 StreamSessionGAgent，并明确禁止继续使用 StreamProxy/StreamingProxy 表示 connection session？
2. P0 StreamFrame 是否包含 text_chunk/text_end/tool_call_start/tool_call_end/approval_request/approval_decision/lifecycle/control/heartbeat/ack，而 audio/video/screen 后置到 VoicePresence PoC 或独立 media frame？
3. session_id 是否作为 opaque logical delivery stream actor id，user_id/conversation_id/transport_kind 只作为 typed state/lookup 条件，不参与 actor id 派生？
4. Transport attachment 是否必须通过 actor command/event 注册，并禁止 Host 保存 session_id -> writer/context/transport 事实状态？
5. Replay policy 是否按 frame kind 强类型裁定：text/tool/control/lifecycle 在 bounded window 内可 replay，heartbeat 不 replay，audio/video/screen 默认 gap/resync 或 media fast path？
6. AGUI 是否保留为 presentation wire format，由 adapter 做 StreamFrame <-> AGUIEvent 映射，而不是把 AGUI 收编成核心 StreamFrame 子集？
7. NyxIdChat P0 是只替换 outbound transport-session delivery 语义，还是同时删除 NyxIdChatStreamingRunner mapper；若保留 mapper，应重命名为 presentation adapter 以免继续叫 runner？
8. ADR 是否需要同步更新 docs/canon/cqrs-projection.md 或新增 canon，明确 Projection Observation 与 StreamSession Delivery 的边界？

original_authors

为遵守共享规则，GitHub 正文不生成 maintainer 私名或 @ mention。

• agents/Aevatar.GAgents.NyxidChat/NyxIdChatEndpoints.Streaming.cs: loning
• agents/Aevatar.GAgents.NyxidChat/NyxIdChatStreamingRunner.cs: loning
• src/Aevatar.Foundation.VoicePresence.Abstractions/Protos/voice_presence.proto: loning
• src/Aevatar.Foundation.VoicePresence/Hosting/ActorOwnedVoicePresenceSessionResolver.cs: loning
• agents/Aevatar.GAgents.Channel.Abstractions/Transport/IChannelTransport.cs: louis.li

⟦AI:AUTO-LOOP⟧

[eanzhao]

A. 抽象本身

A1 命名 → StreamSessionGAgent

核心实体是一个 stream session，拥有连接会话的 lifecycle / seq / ack / heartbeat / reconnect 语义。ConnectionGAgent 容易被读成单次物理连接，但物理连接重连后会变，session actor 必须仍是同一个。

放置位置 → src/Aevatar.Foundation.Streaming.*（或 Aevatar.Foundation.StreamSessions 收得更窄，避免和现有 Aevatar.Foundation.Runtime.Implementations.Orleans.Streaming 撞名）。基础设施层 agent，给 NyxIdChat / VoicePresence / AGUI / WebSocket adapter 复用。

ADR 应明确：这里的 stream 只指外部长连接 session，不覆盖以下 4 类，建议各自分名：

现叫法	实质	建议命名归属
NyxIdChat WebSocket / SSE	外部长连接 session	Stream/Session/Frame（本 RFC 域）
CommittedStateEventPublished projection 实时投递	committed-fact 观察	Observation/LiveObservation/Feed
LLM token delta（intra-run）	run 内部 chunk 流	Run/Step/Delta 或类似（agent runtime 域）
Lark CardKit streaming edit	HTTP 多次 edit-in-place	不是长连接，归 channel adapter 命名 IncrementalEdit/Throttle

并建议把现有 StreamingProxyGAgent（实质是 room broker：room name / participants / messages / terminal sessions）改名 GroupChatRoomGAgent，避免继续占用 StreamingProxy 这个易混淆词。

A2 frame 范围 → P0 收窄，多模态独立 typed kind

P0 只承诺 text + control + heartbeat/lifecycle，多模态后置为独立 typed frame kind / 独立 proto（与 @louis4li 的判断一致）。

理由：

• text / control / approval：可靠投递、seq/ack、有限 replay → 同一套 inbox / persistence 语义。
• audio / video data plane：50Hz+ 帧率、不可 replay、不进 event store → 完全不同 delivery model。
• 同一 oneof 意味着接收端要在 inbox 层判断"这帧要不要持久化 / 进 replay 窗口"，这是 flag 驱动一切。

更清晰的边界：StreamFrame 只承载控制平面 + 文本输出；audio / video 走独立 MediaFrame proto + 可能不同的 MediaSessionGAgent，可复用 attachment 抽象但不复用 inbox（media 走 fast path，绕过 actor inbox 与 event store）。day-1 proto 形状预留多模态命名空间（typed frame kind 分类法），但不塞进同一个 oneof。

A3 actor identity → session = 逻辑投递流，physical connection = attachment

session_id = 一条 logical delivery stream 的 StreamSessionGAgent identity，不派生自 (user_id, conversation_id, transport_kind)：

• conversation_id 关联业务会话，但不替代 session_id（同一会话可以有多个 session，例如 text + media）。
• transport_kind 是某次连接的物理形态，不参与 identity（SSE → WebSocket 重连应仍是同一 session）。
• physical connection 是 attachment，不是 fact source。host failover 后换物理连接，attachment 改变，session 不变。

机制：

• 同一逻辑投递流（同一段 text/control 输出从 SSE 重连到 WebSocket，或 host failover 后换物理连接）→ 复用同一 session_id / 同一 actor。seq / ack / replay window / terminal 状态有唯一权威源。
• 不同 delivery 语义（text/control 与高频 media data plane）→ 拆成不同 stream session（text 走 StreamSessionGAgent，media 走 MediaSessionGAgent），不共享 actor inbox。

业务会话由业务 owner actor 拥有；StreamSessionGAgent 只拥有连接投递事实；物理连接是 attachment。

B. 边界

B1 与 Projection Pipeline 的边界 → StreamSession 不持有业务事实

StreamSession 只持有连接事实，业务事实由业务 owner actor 决定持久化（与 @louis4li 的方向一致）。具体机制：

• StreamSession 不带 persistence_policy metadata（不要让 frame 里的 flag 决定下游是否持久化）。
• inbound frame：业务 owner actor 订阅 frame_received → 自己跑业务契约 → 自己决定 PersistDomainEventAsync。
• outbound frame：业务 owner actor PublishFrameAsync(typedFrame) → StreamSession 只管投递。
• AGUI live output / CommittedStateEventPublished projection 不走 StreamSession——它们是 committed fact 观察，归 projection pipeline。如果某个前端要把 projection 结果经由外部长连接送达，是 adapter 层 把 projection observation 翻译成 StreamFrame，不是 projection 借道 stream session。

text 是否进对话历史、approval 是否成业务事件、audio 是否丢弃——都由业务 owner actor 决定，不由 frame metadata 决定，也不由 StreamSession hardcode。

B2 与 IChannelTransport 的关系 → 二维正交，不互相收编

IChannelTransport（webhook ingress）与 StreamSessionGAgent（长连接 session）是两条正交的轴，不互相收编（与 @louis4li 同）。二维分类：

	webhook-only ingress	long-lived session
platform native	Lark / Telegram inbound	future: WebRTC for VoicePresence
platform synthesized	NyxID relay callback	Studio playground WebSocket

NyxID relay 是 webhook in + REST out 反复 callback，不是 session——业务 actor 自己持有短期 reply token 是合理的，不需要 session actor 介入。

如果未来某个 channel gateway 底层是长连接，可以在底层连接管理上复用 StreamSession 的生命周期语义；但 normalize 后的 channel activity 仍进 channel pipeline / durable inbox，不会把 IChannelTransport 主链改成 StreamFrame。

C. 跨节点鲁棒性

C1 host 宕机接续 → virtual actor + attached/detached 阶段 + 三向 bounded buffer

• session actor 持久化只包含：last_acked_seq + 未 ack 的 replay buffer + lifecycle phase。其余 transient。
• transport attachment 是非持久化的 per-host 资源：host A 死 = attachment 死，actor 不需被通知；actor 在下一次 publish 时发现"no attached transport"进入 detached 阶段。
• client 重连：连到任意 host B → host B 用 session_id 找回 actor（Orleans 自动在某 silo 激活）→ host B 把新 transport 注册为 attachment → actor replay from last_acked_seq + 1。
• detached 期间的 backpressure：actor 在 detached 阶段暂停 outbound 投递，但 inbound 写 replay buffer；buffer 三向 bounded（见 C2），溢出即 terminal。这要求上游业务 owner actor 必须能被 backpressure（不是 cancel）——继续产 frame，但接受 publish 进 buffer 而不是立即送达。
• session terminal 判定：(a) 客户端显式 close；(b) detached 超过 N 秒；(c) replay buffer 溢出；(d) 业务 owner actor 主动结束。任一触发 → 写 SessionTerminatedEvent（这是该 actor 真正的"业务事实"，进 ES），actor 可被 GC。

outbound_seq / last_acked / 当前 replay buffer 是 actor state（Protobuf，与 CLAUDE.md 一致），host failover 后随 actor 复活；不放外部 store。

C2 出站 frame 回放 → 按 frame kind 分层 + 三向 bounded 窗口

frame kind	重连后行为	状态位置
text / approval / tool result（未 ack）	从 last_acked_seq + 1 replay	actor state（bounded buffer）
heartbeat	不 replay（陈旧无意义）	—
control（lifecycle / cancel）	必 replay（控制语义）	actor state
audio / video	不 replay（即时性）	不进 actor，不存

回放窗口三向 bounded：时间（默认 30s） ∧ 序号（默认 N=200） ∧ state size（默认 64KB），超出任一阈值 → terminal，client 必须重发原始请求。各阈值在 ADR 里参数化。

text/control 可靠 replay、heartbeat / audio 不 replay——这条边界已经隐含说明：audio/video 不该和 text 共用一个 frame proto / 一个 actor inbox（呼应 A2 / A3）。

D. AGUI 兼容

D1 AGUI 保留为前端 wire format，边界 adapter 1:1 映射

AGUI 与 StreamFrame 语义轴不同（与 @louis4li 同）：

• AGUI：前端 run / thread / message / tool / approval / error / finished 这类 UI 事件。
• StreamFrame：连接投递语义（session / seq / ack / reconnect / heartbeat / delivery lifecycle）。

把 AGUI 收编成 StreamFrame 子集会让 UI 协议污染连接 session 内核，也会让 Projection Observation 和外部长连接 session 混在一起。AGUI 继续作为 UI wire format；若底层需要可靠投递，由边界 adapter 使用 StreamSession 的连接投递能力。

E. 切片

E1 P0 收窄到 transport session 部分

NyxIdChatStreamingRunner 今天同时干两件事：跑 LLM/tool loop，和维护 host-side WebSocket session（TCS + SubscribeAsync + 120s timer）。本 RFC 的 P0 只覆盖后一半——拿 StreamSessionGAgent 替换 host-side TCS / timer / 120s 等 transport-session 职责；LLM/tool loop 那部分是独立的 agent runtime 重构，不在本 RFC 范围（可平行推进）。

P0   StreamSessionGAgent skeleton（text + control + heartbeat），换掉 NyxIdChatStreamingRunner 里 host-side 维持 session 的部分
P1   VoicePresence host bridge 实体化（验证 media fast path / actor inbox 高频压力 / replay-or-drop 策略）
P2   AGUI sink + EventChannel 合并到 projection observation 命名（与 StreamSession 解耦）
P3   两个 reply throttler 合并
P4   重写 WebSocketTransport（StreamSession 落地后此项简化）
P5+  长尾

NyxIdChatStreamingRunner 只在 P0 + 独立的 agent runtime 重构都到位后才能真正消失。

E2 是否先 PoC → 分 phase

• text-only StreamSession（Studio playground / NyxidChat outbound）：可以直接进 ADR。text + heartbeat + bounded replay 是 well-trodden 路径，无需 PoC。
• VoicePresence：必须 PoC。媒体 fast path 是不是真的要绕开 actor inbox、replay 窗口对 audio 的策略、host failover 时正在编码的 audio buffer 怎么处理——这些 ADR 写不死，必须跑出来。

→ 建议 ADR 拆 phase：phase 1 text/control（直接写）；phase 2 multi-modal（PoC 先跑 VoicePresence，结果回写 ADR）。

仍需团队 review 的具体点

• C1 的 detached 超时阈值、C2 的 replay 窗口三向阈值具体取值——建议在 ADR 草稿里参数化，实际值通过 P0 / P1 跑出来。
• A2 的 MediaFrame 是不是真的要独立 proto——VoicePresence PoC（P1）结束后回写。
• StreamSession 与上游业务 owner actor 之间的 PublishFrameAsync / inbound frame 订阅模式——P0 落地最小 skeleton 后再拍接缝。

[louis4li]

先给我的阶段性意见。我支持“外部长连接 session actor 化”这个方向，但建议 RFC 阶段先把抽象边界、identity 和 AGUI 关系收紧，避免把所有叫 streaming 的东西都收进一个新抽象里。

A. 抽象本身

A1 命名

我倾向 StreamSessionGAgent，不倾向 SessionStreamGAgent。

核心实体是一个 StreamSession：它拥有连接会话的 lifecycle、seq、ack、heartbeat、reconnect 等语义。ConnectionGAgent 容易被理解成一次物理连接；重连后物理连接会变，但 session actor 应该仍然是同一个。

同时建议 ADR 里明确：这里的 stream 只指外部长连接 session，不覆盖 room broker、AGUI live output、LLM token stream 或 Projection Observation。

A2 frame 范围

我建议 P0 只承诺 text + control + heartbeat/lifecycle 的最小闭环，不在 day-1 承诺完整多模态。

但核心抽象不要设计成 text-only。ADR 可以明确未来 audio/video/screen/image 等多模态 frame 允许作为 typed frame kind 扩展，但 P0 不把它们纳入同一套 inbox、持久化和 replay 责任里。

原因是 text/control 和 audio/video 的语义不同：前者通常需要可靠 delivery、seq、ack、有限 replay；后者多是高频 data plane，不应默认进入 actor inbox、event store 或 projection 主链。多模态方向可以预留，但 day-1 的权威语义应先收敛在连接控制和文本输出闭环上。

A3 identity 语义

session_id 的语义需要收紧：它应该表示一条 logical delivery stream 的 StreamSessionGAgent identity，不能同时表示业务会话、用户身份、transport 类型或某次物理连接。

我不建议用 (user_id, conversation_id, transport_kind) 派生 session actor identity。conversation_id 可以关联业务会话，但不替代 session_id；transport_kind 可以描述某次连接方式，但不参与定义 session identity。

多 transport 同时连接同一个业务会话时，关键要看它们是否承载同一条 delivery stream：

• 如果是同一条 delivery stream，例如同一段 text/control 输出从 SSE 重连到 WebSocket，或 host failover 后换了物理连接，应复用同一个 session_id / 同一个 StreamSessionGAgent，不同物理连接只是该 session 下的 attachment。这样 seq、ack、replay window、terminal delivery 状态有唯一权威来源。
• 如果是不同 delivery 语义，例如 text/control stream 和高频 media data plane，不应为了“同一个 conversation”强行塞进同一个 session actor；应在 ADR 里明确是否拆成不同 stream session，以及各自拥有哪类连接投递事实。

也就是说，业务会话由业务 owner actor 拥有；StreamSessionGAgent 只拥有连接投递事实；物理连接只是 attachment，不应成为新的事实源。

B. 边界

B1 与 Projection Pipeline 的边界

StreamSessionGAgent 应只拥有连接事实，例如 lifecycle、seq、ack、heartbeat、reconnect、有限回放窗口等。它不应拥有业务事实，也不应决定哪些内容进入 event store / conversation history。

text 是否进入对话历史、approval 是否成为业务事件，应由业务 owner actor 和 typed business contract 决定；audio/video 这类高频数据也不应因为进了 stream frame 就默认成为 committed domain fact。

所以不建议通过泛化 metadata 决定“是否持久化”，也不建议由 StreamSessionGAgent hardcode 业务内容的持久化策略。更稳的边界是：业务 actor 决定业务事实，StreamSession 只处理连接投递事实。

B2 与 IChannelTransport 的关系

我建议现存 channel inbound 继续维持独立的 IChannelTransport / channel pipeline 抽象，不收编为 session stream 的一种。

两者回答的问题不同：

• IChannelTransport 是平台通道 ingress 抽象：负责 Lark / Telegram / NyxIdRelay 这类平台入口的绑定、鉴权、验签、接收、normalize，并把平台事件变成 channel activity。
• StreamSessionGAgent 是长连接 session 运行态抽象：负责 WebSocket / SSE / WebRTC / long polling 这类连接会话的 session_id、seq、ack、heartbeat、reconnect、replay/gap。

所以 webhook 型 channel inbound 不是 session stream。它没有“client 带 session_id 重连，并从 last_acked_seq 续传同一个连接会话”的语义。

如果未来某个 channel gateway 底层本身是长连接，可以在底层连接管理上复用 StreamSession 的生命周期语义；但 normalize 后的 channel activity 仍应进入 channel pipeline / durable inbox，而不是把 IChannelTransport 的公共抽象改成 StreamFrame 主链。

D. AGUI 兼容

D1 AGUI 与 StreamFrame 的关系

我同意 AGUI 保留为前端 wire format，由边界 adapter 映射，不收编成 StreamFrame 子集。

原因是两者语义轴不同：

• AGUI 表达前端 run/thread/message/tool/approval/error/finished 这类 UI 事件。
• StreamFrame 表达连接投递语义，例如 session、seq、ack、reconnect、heartbeat、delivery lifecycle。

把 AGUI 收编成 StreamFrame 子集，会让 UI 协议污染连接 session 内核，也会让 Projection Observation 和外部长连接 session 混在一起。更合适的是：AGUI 继续作为 UI wire format；如果底层需要可靠投递，再由边界 adapter 使用 StreamSession 的连接投递能力。

[jason-aelf]

A. 抽象本身

A1. 命名终裁

结论：命名用 StreamSessionGAgent。

理由：

1. StreamSession 是领域名词，表达“一个可重连、可观察、可排序的流式会话”。SessionStream 更像“某个 session 的 stream”，主语不够清楚。
2. 不用 ConnectionGAgent。connection 是 TCP/WebSocket/WebRTC 等 wire 层概念，host 断线后会消失；actor 拥有的是跨重连延续的 logical session，不是某根 socket。
3. 不用 ExternalStreamGAgent。External 只描述边界来源，没有表达会话身份、seq、ack、heartbeat、lifecycle 这些 actor 拥有的事实。
4. 不用 StreamProxyGAgent 或 StreamingProxyGAgent。当前仓库已经有 agents/Aevatar.GAgents.StreamingProxy/StreamingProxyGAgent.cs，而且它是 group chat room broker，代码注释也明确是“多参与者群聊房间消息 broker”，不是 transport/session 抽象。

命名边界建议：

1. Actor 类型：StreamSessionGAgent
2. Actor state：StreamSessionState
3. Frame proto：StreamFrame
4. Host-side wire bridge：StreamTransportAdapter 或具体 SseStreamTransportAdapter、WebRtcStreamTransportAdapter
5. 不在任何新类型名里使用 Proxy，避免继续和现有 StreamingProxyGAgent 撞语义。

A2. Frame 范围

结论：P0 不做全模态，但 day-1 的 StreamFrame 必须是可演进的强类型 oneof。P0 最小范围不是“text + control”这么窄，而是“text + tool/approval + lifecycle/control/heartbeat/ack”。

理由：

1. 当前 NyxIdChat P0 要替换的路径不只有文本。NyxIdChatEndpoints.Streaming.cs 已经把 TextMessage*、ToolCallEvent、ToolResultEvent、ToolApprovalRequestEvent、MediaContentEvent 映射为 SSE。P0 如果只有 text/control，会立刻丢掉 tool approval 续流能力。
2. VoicePresence 已经有 typed duplex transport，IVoiceTransport 暴露 SendAudioAsync、SendControlAsync、ReceiveFramesAsync，voice_presence.proto 也有 remote session open/close、audio input/output、control frame。audio 是 P1 的真实消费场景，不是凭空想象。
3. video、screen 现在没有同等成熟的生产方/消费方。按仓库规则，不能因为“未来可能有”就先塞一组泛化字段或 Metadata bag。

建议范围：

阶段	StreamFrame 分支	说明
P0	text_chunk、text_end、tool_call_start、tool_call_end、approval_request、approval_decision、lifecycle、control、heartbeat、ack	覆盖 NyxIdChat outbound 和 tool approval 续流，不引入音视频复杂度
P1	audio	用 VoicePresence 反向验证 session actor，不把 audio 强行塞进 P0
P2+	image、video、screen	只有出现明确 producer/consumer 和 transport adapter 时再加 typed oneof 分支

关键约束：新增模态走 protobuf 字段演进，不走 Metadata 或字符串 key。编号区间可以在 ADR 中规划，但 proto 里只落已经有明确消费场景的字段。

A3. Actor identity

结论：StreamSessionGAgent 的 actor identity 使用 opaque session_id。user_id、conversation_id、transport_kind 是 typed state 或 lookup 条件，不参与 actor id 派生。

理由：

1. session_id 是逻辑会话身份。它可以跨 host 重连、跨 transport attachment 延续。user_id、conversation_id、transport_kind 是会话属性，不是会话地址。
2. 用 (user_id, conversation_id, transport_kind) 派生 actor id 会把可变业务事实写进地址。用户换设备、同一会话同时开 SSE 和 WebRTC、transport 从 SSE 升级到 WebSocket，都会变成 actor identity 问题。
3. 当前 VoicePresence 的 RemoteActorVoicePresenceSessionResolver 在 host bridge 里生成 Guid sessionId，并用 _state 保存 attachment。这个 sessionId 应该上移为 actor id 对应的权威会话，而不是留在 host 内存。

多 transport 同时连接一个会话的处理：

1. actor 仍然只有一个：StreamSessionGAgent(session_id)。
2. 每个 transport 连接是一个 attachment_id，状态里记录 typed transport_kind、peer capabilities、last_acked_outbound、heartbeat 水位。
3. P0 默认每个 transport_kind 只允许一个 active attachment。重复连接时按明确策略处理：拒绝旧连接、替换旧连接，或只作为 observer 加入。不要让 host 自己决定。
4. 后续需要 SSE + WebRTC 同时存在时，在同一个 session actor 内按 frame type 路由：text/control 可以发给 SSE，audio 发给 WebRTC，lifecycle/heartbeat 可广播给所有 attachment。

B. 边界

B1. 与 Projection Pipeline 的边界

结论：是否 PersistDomainEventAsync 由 consumer GAgent 的 typed domain policy 决定，不由 StreamSessionGAgent 决定，也不由 StreamFrame 自带 metadata 决定。

边界应固定为：

1. StreamSessionGAgent 拥有 transport 会话事实：session lifecycle、attachment、seq、ack、heartbeat、短期 replay window。
2. Consumer GAgent 拥有业务事实：对话历史、tool approval 结果、workflow run 推进、voice transcript、群聊消息等。
3. Projection Pipeline 只消费 consumer GAgent 已提交的 committed domain event，继续物化 readmodel 和 AGUI/CQRS observation。

理由：

1. Projection 是 committed fact replication，不是长连接 transport hub。PR docs(audit): 2026-05-03 architecture audit + stream processing assessment #559 的审计文档已经把这一点说清楚：把 long-lived bidirectional stream 折回 Projection 会让 hub 承担 session/握手/back-pressure，形状不对。
2. StreamFrame 是传输会话帧，不天然等于业务事实。text chunk 可能要进入对话历史，audio frame 多数时候不该进入 event store，tool approval decision 则必须成为业务事件。
3. 如果让 frame 自带 “persist = true/false” metadata，等于把业务持久化决策下放给 transport 层，违反读写分离和强类型语义规则。

实现口径：

1. StreamSessionGAgent 可以持久化自己的 session 事件，例如 StreamSessionOpened、StreamAttachmentConnected、StreamFrameAcked。
2. Consumer GAgent 接到 frame 后，把有业务意义的输入转换成自己的 typed domain event，例如 ChatMessageAccepted、ToolApprovalDecisionEvent、VoiceTranscriptCommitted。
3. text 是否持久化不是全局规则。NyxIdChat、Workflow、Channel conversation 可以不同，但每个 consumer 必须把规则写在自己的 typed mapper/policy 里。

B2. 与 IChannelTransport 的关系

结论：现存 channel inbound 不是 StreamSessionGAgent 的一种。IChannelTransport 继续作为 inbound adapter / bot binding lifecycle 抽象保留；只有真正需要长连接接续、seq/ack、出站 replay 的交互，才进入 StreamSessionGAgent。

理由：

1. IChannelTransport 的注释已经说明 InboundStream 是 single-reader、in-process buffer，且“not the durable ingress boundary”。它负责把 Lark/Telegram/NyxIdRelay 等平台输入规范化成 ChatActivity，不是拥有用户会话事实。
2. webhook 类 inbound 是离散事件，不是一个需要 seq/ack/replay 的双向长连接。把它强行建模为 stream session，会把 bot binding、credential、platform verification、durable inbox 等职责混进 session actor。
3. Channel runtime 已经有 durable inbox、conversation actor、reply delivery 这条业务主链。StreamSessionGAgent 应该服务“实时连接会话”，不是替代 channel ingress。

关系建议：

1. Lark/Telegram/NyxIdRelay webhook：继续走 IChannelTransport -> ChatActivity -> durable inbox/conversation。
2. Channel 的流式出站编辑和实时 reply：后续可以把“某一次 reply stream”接到 StreamSessionGAgent 或共用 OutboundFrameThrottler，但这属于出站体验层，不改变 inbound 抽象。
3. 如果未来某个平台提供真正的 socket-mode/realtime channel，可以由该 adapter 为每个实时连接创建 StreamSessionGAgent。这不是所有 channel inbound 的默认路径。

C. 跨节点鲁棒性

C1. Host 宕机接续

结论：client 重连必须带 session_id 和 signed reconnect token。host B 用 session_id 解析同一个 StreamSessionGAgent，再提交新的 attachment；host 不维护 session_id -> context 进程内表。

接续流程：

1. 首次连接时，host 创建或解析 StreamSessionGAgent(session_id)，返回 session_id、reconnect token、当前 outbound_seq。
2. host A 只持有 wire handle。它不拥有 session fact。
3. host A 宕机后，client 连到 host B，提交 session_id、reconnect token、last_acked_outbound、transport_kind。
4. host B 通过 actor runtime 定位 StreamSessionGAgent(session_id)，发送 AttachTransportRequested。
5. actor 校验 token、lifecycle、peer descriptor，标记旧 attachment stale，注册新 attachment，按 C2 的 replay policy 补发可回放帧。
6. 如果旧 host 没有正常 close，actor 通过 heartbeat/durable timeout 对账，不依赖旧 host 回调。

理由：

1. 当前 VoicePresence 的 RemoteActorVoicePresenceSessionBridge 用 _state 保存 attachment，host 挂了就丢。这个状态必须改为 actor-owned session state + host-owned transient I/O handle。
2. 当前 NyxIdChat runner 没有 session actor，只是在 HTTP 请求内 SubscribeAsync<EventEnvelope> 并用 TaskCompletionSource 等终态。host 断线或跨 silo 失败时没有可接续事实源。
3. 这个设计满足仓库“中间层不得维护 session ID 到事实状态进程内映射”的约束。

安全约束：session_id 是 opaque address，不是授权凭据。reconnect 必须校验 user/scope/actor binding，不能仅凭 session_id 接续。

C2. 出站 frame 回放

结论：按 frame 类型决定。text/tool/control/lifecycle 默认可回放；audio/video/screen 默认不回放；超出 replay window 时显式返回 gap/resync，不假装成功。

建议策略：

Frame 类型	默认策略	理由
text chunk/end	可回放，必要时可合并为 message-level snapshot	用户需要完整文本；体积可控，可用 seq 去重
tool call / tool result / approval	可回放	影响 UI 状态和人工决策，丢了会误导用户
lifecycle / control / heartbeat / ack	control/lifecycle 可回放，heartbeat 不需要补历史	只需要恢复当前连接状态
audio	不回放，发 gap/resync	实时音频补 50 帧通常没有用户价值，还会造成播放错位
video/screen	不回放，发 gap/resync	体积和实时性都不适合 actor replay

投递语义：

1. 不承诺 exactly-once。承诺 at-least-once within replay window + monotonic seq + client-side idempotency。
2. actor state 记录 outbound_seq 和 last_acked_outbound。
3. 可回放帧保留 bounded replay window。窗口大小和 TTL 必须是 typed config，不能藏在 Metadata。
4. 如果 client 的 last_acked_outbound 太旧，actor 发 StreamGapDetected 或等价 typed control frame，客户端回 readmodel / conversation snapshot 做 resync。

这条规则能同时覆盖 NyxIdChat 文本 SSE 和 VoicePresence 音频：文本不能随便丢，音频不能随便补。

D. AGUI 兼容

D1. AGUI 是子集还是 wire format

结论：保留 AGUI 作为前端 wire format，StreamFrame 是内部 session frame。transport/presentation adapter 做 StreamFrame <-> AGUIEvent 的显式映射。

理由：

1. 当前仓库已经有 AGUIEvent proto、AGUISseWriter、GAgentDraftRunSessionEventProjector、WorkflowExecutionRunEventProjector 和一批测试。把 AGUI 重命名收编为 StreamFrame 会破坏现有前端和 projection session 语义。
2. AGUI 是 presentation contract，StreamFrame 是 runtime/session contract。把 AGUI 放进核心 session 抽象，会让 Foundation 层依赖前端 wire 词汇。
3. Workflow/Scope 的 AGUI 流仍然应该来自 Projection Pipeline，因为它表达 committed observation。NyxIdChat/VoicePresence 的 long-lived stream 则由 StreamSessionGAgent 承载。两者通过 adapter 对齐用户可见格式，而不是混成同一层。

映射口径：

1. StreamFrame.text_chunk -> AGUIEvent.TextMessageContent
2. StreamFrame.text_end -> AGUIEvent.TextMessageEnd
3. StreamFrame.tool_call_start -> AGUIEvent.ToolCallStart
4. StreamFrame.tool_call_end -> AGUIEvent.ToolCallEnd
5. StreamFrame.approval_request -> AGUI CustomEvent 或后续 typed AGUI approval event，不能用匿名 JSON bag 扩散到核心层
6. StreamFrame.lifecycle -> RunStarted / RunFinished / RunError 等 wire 事件

AGUI 可以是 StreamFrame 的一个 wire projection，但不是 StreamFrame 的名字，也不是核心 oneof 的命名来源。

E. 切片

E1. P0-P5 排序

结论：issue 中的排序大体合理，但 P0 需要改写为“最小 shared stream-session contract + NyxIdChat outbound”，不能只修 NyxIdChat。

建议排序：

优先级	切片	调整意见	建议 owner 角色
P0	StreamSessionGAgent 最小契约 + NyxIdChat outbound 替换 runner	必须删除 NyxIdChatStreamingRunner 的 TCS/Subscribe/Delay 模式；但只做 text/tool/approval/control/lifecycle，不做 audio/video	AI/NyxIdChat owner + Foundation/runtime reviewer
P1	VoicePresence host bridge actor 化	用现有 VoicePresence 验证 duplex、attachment、heartbeat、session close；audio branch 在这里落地	VoicePresence owner + Foundation/runtime reviewer
P2	AGUI sink + EventChannel<T> 收敛	AGUIEventChannel 和 EventChannel<AGUIEvent> 形状重复，可以独立重构，不阻塞 P0	CQRS/Projection owner
P3	TurnStreamingReplySink + SkillRunnerStreamingReplySink 合并	提取通用 outbound throttler，但不要先于 P0 改业务语义	Channel runtime owner + Scheduled/Skill runner owner
P4	IExternalLinkTransport / WebSocketTransport 重写	当前 WebSocketTransport 源码注释已列出限制：无 framing、无 sub-protocol、无 custom headers、固定 8KB buffer。应作为通用 WS adapter 模板，但不是 M1 blocker	Foundation ExternalLinks owner
P5+	Channel inbound、OpenAI realtime、long tail	等 P0/P1 验证后逐条收敛，避免 mega-PR	各能力 owner

为什么 P0 必须带 shared contract：

1. 当前 critical violation 在 NyxIdChatStreamingRunner.cs，它用 TaskCompletionSource、SubscribeAsync<EventEnvelope>、Task.Delay(120_000) 等请求内状态判定终态。
2. 如果 P0 只在 NyxIdChat 里改一层包装，很容易变成“NyxIdChat 专用 session runner 2.0”，下次 VoicePresence、Channel reply、AGUI WebSocket 又会各写一套。
3. 但 P0 也不能吃下全流处理子系统。最小公共面就是 session actor identity、typed frame、seq/ack、attach/detach、replay policy、NyxIdChat adapter。

E2. 是否先做 PoC

结论：需要 PoC，但 PoC 的位置是“ADR 草案之后、ADR 定稿之前”，并且必须是 throwaway / draft branch，不进生产，不改 NyxIdChatStreamingRunner 主线。

理由：

1. VoicePresence 是当前最接近正确形状的实现：typed duplex transport 已经存在，actor dispatch + actor subscription 也已经存在。它暴露的问题正是 session actor 要解决的问题：host bridge _state、attachment lifecycle、跨 host 接续。
2. NyxIdChat 是 text-only，拿它做 PoC 容易低估 duplex、heartbeat、attachment stale、audio non-replay 这些关键风险。
3. 不先验证 VoicePresence，ADR 很可能写出一个只能修文本 SSE、不能承载实时音频的抽象。

PoC 只回答三个问题：

1. host 断开后，client 用同一个 session_id 连到新 host，能否重新 attach 到同一个 session actor。
2. actor 能否权威维护 outbound_seq、last_acked_outbound、lifecycle，并让 host 只持有 transient transport handle。
3. text/control 可回放、audio 不回放的策略在代码形态上是否自然。

PoC 不做：

1. 不替换 NyxIdChat production runner。
2. 不定义完整 video/screen/image 模态。
3. 不修改外部仓库。
4. 不把 Projection Pipeline 改造成 long-lived stream hub。

ADR 定稿时，把 PoC 结果写成风险验证结论：哪些假设成立，哪些需要降级，P0 是否仍然只做 NyxIdChat outbound。