Skip to content

feat(shared): add parallel Stream Event v1 channel to RunManager - #42

Open
sjr666666 wants to merge 3 commits into
helsome:mainfrom
sjr666666:feat/27-stream-event-runtime
Open

feat(shared): add parallel Stream Event v1 channel to RunManager#42
sjr666666 wants to merge 3 commits into
helsome:mainfrom
sjr666666:feat/27-stream-event-runtime

Conversation

@sjr666666

@sjr666666 sjr666666 commented Sep 11, 2026

Copy link
Copy Markdown
Collaborator

背景与动机

issue #27 需要一条版本化、带单调 sequence 与显式取消的流式事件协议。#41 落了协议类型;本 PR 是第二步:在 RunManager 里加一条并行的协议通道,让现有 AgentEvent 消费方完全不受影响。

完成了什么

  • packages/shared/src/kernel/stream-event-adapter.ts(新增):纯函数 toStreamEvents(AgentEvent) -> StreamEvent[] 的映射。现有 8 事件映射到 12 种协议事件:message_deltatext_delta(保留增量字段)、tool_completedtool_resultrun_failed(code=RUN_CANCELLED) → 显式 cancelled(不再从失败推断取消);时间戳统一为 ISO 8601。
  • RunManager.subscribeStream(sessionId, event):新的并行订阅入口;现有 subscribe / AgentEvent 路径与全部消费方未改动,没有 stream 订阅者时不产生额外工作
  • sequence 契约:runtime 与本管理器都会自产事件、各自从 1 计数,因此在 emit 唯一汇聚点统一重排为 run 内严格 +1(幂等键与 replay 游标都依赖它)。
  • 映射分支单测(6 例)+ kernel 回归。

向后兼容

对现有消费方无行为变更;未注册 stream 订阅者时零开销。renderer / transport 接线是下一步(#43)。

关联 Issue

Refs #27(第二步,不关闭)、#34(身份模型)。依赖 #41

验证

环境:Bun 1.4.2 / Windows 11 (NT 10.0.26200)

CI(本 PR 的 checks,全部 pass):Typecheck / Focused tests / Full unit tests (advisory) / Secret scan。

本地

bun test --isolate packages/shared/src/kernel/stream-event-adapter.test.ts \
  packages/shared/src/kernel/run-manager.test.ts packages/core/src/stream-events.test.ts
→ 28 passed / 0 failed(adapter 9 · run-manager 15 · core 4)

本机 Windows 依赖安装不完整(execa 等解析失败,origin/main 上同样存在),长桥链路相关的 E2E 无法在本机加载,由 CI 覆盖。

Open questions

与 ADR 0001 §Open questions 一致(resume 数据源、status.phase 取值充分性)。messageIdrunId 的身份问题已在 #43 收敛为"message 级事件带 messageId、run 级不带"。

Rebase 说明

已 rebase 到最新 main(046b5d3)。栈 #41#42#43;合并时以 #43 栈顶一次性带入,不再分别 squash #41/#42

@helsome helsome left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

先随 #41/#43 一起暂缓。adapter + parallel channel 本身拆分合理,但它依赖尚未定型的 v1 identity contract;同时 reconnect/replay 目前仍只存在于 ADR 描述,没有 runtime replay source。请按 #43 的 review 统一修顶层 stack,避免在 main 留一个半迁移协议。

@helsome helsome left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

更新审核结论:#42 本身无需再追加 reconnect/identity 改动,这些已经在顶层 #43 完成。保持 stacked 中间层即可;最终以 #43 为合入单元,rebase 最新 main 后跑基础 CI 即可,不再要求完整真实 Copilot E2E 作为前置。

@sjr666666
sjr666666 force-pushed the feat/27-stream-event-runtime branch 2 times, most recently from 0ce4fa7 to 2f0ba16 Compare September 11, 2026 09:12
@sjr666666
sjr666666 force-pushed the feat/27-stream-event-runtime branch 2 times, most recently from 23e2b9d to 3fcb288 Compare September 13, 2026 13:01
石敬荣 added 3 commits September 13, 2026 21:03
Introduce the pure-type foundation for the structured streaming event protocol (issue helsome#27): versioned envelope, 12 typed events, and the idempotency/cancel/reconnect contracts as types. Zero runtime change.

Adds ADR 0001 documenting context, decision, migration path and open questions for maintainer review.
Emit Stream Event Protocol v1 events alongside the existing AgentEvent stream (issue helsome#27, ADR 0001 migration step 2). Adds toStreamEvents mapping (8 AgentEvent types -> 12 protocol events, cancel normalized to 'cancelled') and RunManager.subscribeStream. Existing AgentEvent consumers are untouched; the parallel channel only activates when a stream subscriber is registered.
StreamEvent was a single indexed-union instantiation (Tagged StreamEventEnvelope<StreamEventType>), so payload could not be narrowed by type in switch/if. Rewrite as a distributive mapped union; on-disk type shape is unchanged. Adjusts adapter unit-test helper accordingly.
@sjr666666
sjr666666 force-pushed the feat/27-stream-event-runtime branch from 3fcb288 to 9275dec Compare September 13, 2026 13:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants