为第三方插件提供宿主→客户端事件转发扩展点（如 session/open）

[sharkisyou]

一句话预期结果：第三方插件（如桌宠）应能通过官方 API 把宿主事件（如 session/open）转发给 Web 客户端，客户端用 ctx.remote.$on 订阅，而无需修改官方 allowlist 或绕过 harness。

背景 / 动机

桌宠插件（dsh-pet-plugin）需要在"用户点击桌宠托盘里的会话项"时，让 DSH Web 客户端跳转到对应会话。链路是：

桌宠托盘点击 → pet server → 桥接插件（宿主）ctx.emit('session/open', …)
  → 需要宿主把该事件转发给 Web 客户端 → 客户端 ctx.remote.$on('session/open') → sessions.open()

但当前宿主→客户端事件只有一条通道：packages/api/remotes/src/remote-events.ts 的 API_REMOTE_FORWARDED_EVENTS。官方设计明确说明：

• "The Host assembly's forwarding selection; api/remotes' allowlist fills it, no other package does."
• "Producer operations remain private. Business plugins can call only $on."

也就是说第三方插件没有官方扩展点来把宿主事件加入转发表。目前的可行做法只有：

1. 直接改官方 dsh-api-remotes 安装包的 allowlist（升级 DSH 即被覆盖，且修改了官方代码）；
2. 向官方仓库 PR 加入 allowlist 条目（但 CONTRIBUTING 说明当前不接受外部 PR）；
3. 绕过 harness（客户端直接连 pet server 等）。

期望

提供一个官方扩展点，让第三方插件能注册一个可转发的宿主事件，例如：

• 一个可注入的服务/API：registerForwardedEvent({ event: 'session/open', mode: 'emit' })，或
• 声明式（插件 manifest / bundle 补丁）声明转发事件。

注册后，客户端即可通过现有 ctx.remote.$on('session/open', …) 订阅，无需其他改官方代码。

验收条件

• 一个第三方插件无需修改官方任何包，即可注册并接收至少一个宿主→客户端事件；
• DSH 升级后该能力不被覆盖；
• ctx.remote.$on 的类型/模式约束（TypertForwardableEventEntry）对注册事件同样生效。

用户或模型可见变化

桌宠托盘点击 → DSH GUI 切换到对应会话，不再依赖修改官方代码。

测试证据

• 参考实现：https://github.com/yshark/dsh-pet-plugin 的 plugins/pet（桥接插件）与 apps/desktop-pet（桌宠 + 独立托盘窗口）。
• 当前为让链路跑通，我们 patch 了本机 dsh-api-remotes 的 API_REMOTE_FORWARDED_EVENTS（加入 { event: 'session/open', mode: 'emit' }），alpha 升级时补丁即被覆盖、需重打——这正是希望官方解决的脆弱点。
• 相关官方文档：.agents/notes/implemented/architecture/2026-08-10-remote-event-delivery.md。

[argszero]

Verified against 4e84901e64 (dsh 0.1.2-alpha.4). All three of your observations check out — and there is one runtime fact that makes the gap even harder than the docstring suggests, plus a piece of good news on the type side.

1. The runtime gate is single-slot, not just convention

typertGateway.registerRemoteEvents is a single-registration service:

• packages/api/gateway/src/index.ts:242-244 — if (this.remoteEvents !== undefined) throw new Error('typert gateway: forwarded Remote event source is already registered').
• The Host assembly (dsh-api-remotes) takes the only slot at apply time (packages/api/remotes/src/index.ts:33-37).

So a third-party plugin calling registerRemoteEvents fails with a hard throw — and even a plugin registering before the Host assembly would make the Host throw. This is not "discouraged by convention"; it is structurally impossible today. I'd argue this is the strongest single fact for the request: the extension point is a runtime gate, so no plugin-side trick can work around it.

2. The type side is already open — the merge seats exist

The type projection is not a private list; it is merge-extensible by design:

• TypertRemoteEventSelection is a declare module seat that owner packages already extend — packages/api/session-controller/src/remote-events.ts:3-11 merges its five api-session/* events into the exact interface your client $on keys come from.
• TypertForwardableEventEntry (packages/typert/protocol/src/types.ts:125-131) derives from the merge-extensible Cordis Events map, so any plugin that declares its own event in Events can already produce a valid, type-checked { event, mode } entry.
• The client comment is explicit about what happens without a seat: "without it in the consumer's compilation face TypertRemoteEvent is never and every $on call fails" (packages/api/remotes/src/client/index.ts:60-62).

So the current asymmetry is: types are open, runtime is closed. A plugin can already declare session/open at the type level, but nothing will ever deliver it at runtime.

3. session/open is not an official event — and the view switch is client-local

The session-controller forwarded vocabulary is exactly five events, all already allowlisted: api-session/activity|added|error|removed|status (packages/api/session-controller/src/remote-events.ts:3-8). The client already subscribes to all five (packages/api/session-controller/src/client/index.ts:91-99), but they only mutate list state (handleSessionAdded / handleSessionStatus in client/sessions/manager.ts). View navigation is a client-local action: sessions.open(id) (client/contract/sessions.ts:44) is invoked by UI clicks; no host→client event drives it. That is exactly the seam your pet-tray flow needs — and it confirms the forwarded-event path (not a host RPC) is the right shape.

Design sketch (minimal, preserving the current intent)

The current design's intent is an auditable forward surface: one file lists every event a client can ever see, and producers stay private so business plugins can only $on. The extension should preserve that intent rather than "open the allowlist":

1. Gateway: slot → set. registerRemoteEvents appends to a Set<RegisteredRemoteEventSource> instead of throwing. The existing disposer semantics are per-source identity (gateway/src/index.ts:255-260 checks this.remoteEvents === registration), so they carry over naturally; each source keeps its own queue and listener set (remotes/src/index.ts remoteEventSource already returns an independent queue).
2. Host-side service for plugins: e.g. ctx.remoteEvents.registerForwardedEvent(entry: TypertForwardableEventEntry): () => void, wired through ctx.effect() so plugin unload removes it. mode: 'emit' is the realistic mode for plugin events — the waterfall path needs a scoped carrier subject resolved via carrierKeyOf(this) (remotes/src/index.ts:60-72), which host-side plugin emits won't have.
3. Type side: zero new machinery. The plugin declares its event in Events and extends TypertRemoteEventSelection exactly like session-controller does today; the client $on then type-checks with the official payload signature. The seats are already there.
4. Safety that already exists and stays: every forwarded event passes assertJsonArgs (remotes/src/index.ts:52), so a plugin event is JSON-gated at push time. Plugin-registered events are also profile-visible (the plugin is mounted), which preserves the audit story — the set of client-visible events is still exactly the allowlist plus each mounted plugin's declarations.

Your acceptance criteria map cleanly onto this: no official edits (the plugin registers through the service), survives upgrades (it is an official API), and TypertForwardableEventEntry mode/type constraints apply verbatim.

Workaround today, precisely scoped: if the bridge plugin drives the session open through the official host-side session services, the client's list state will already update via the existing api-session/* events — but the GUI will not switch views, because navigation is the client-local sessions.open(id). So the pure-event workaround covers list state only; the view switch genuinely needs either this extension point or a client-side companion reading a plugin-visible channel. Note the client assembly is static (packages/api/remotes/src/client/index.ts imports official remotes only), so there is no plugin-injectable client seam today — which again points at the Host side as the right place to open.

Thanks for the reference implementation — dsh-pet-plugin is a clean driver for this. If you open a PR for the gateway Set change, I'll be happy to help verify the forwarding-loop implications in the thread.