docs: document the closed forwarded-event surface for browser plugin halves (emit vs waterfall)

[andreagosto]

Summary

Out-of-tree ("bundle") plugins that ship a browser half have no documentation in the extension path (docs/user/develop/*, docs/cookbook/*) describing which Host events actually reach the browser, that the set is closed, and the emit-vs-waterfall semantic trap. The only source of truth is an internal package README (packages/api/remotes/README.md → API_REMOTE_FORWARDED_EVENTS), which is not discoverable from the authoring guides.

Why it matters

We built a plugin whose browser half blinks the tab title when a workspace finishes / errors / waits for the user. Two of our first three attempts failed because the authoring docs do not state:

• Only ctx.remote.$on(...) events listed in API_REMOTE_FORWARDED_EVENTS (in dsh-api-remotes) reach the browser. A plugin cannot add a host→client channel (e.g. ctx.emit('my-custom-event') on the host is never forwarded) — that requires the internal Typert toolchain.
• emit events are broadcast to every listener; waterfall events (e.g. user-questions/request, approval/request) are single-consumer and claimed by the official answerers in registration order, so a passive observer can silently lose them.

Suggested documentation

A page under docs/user/develop/ (or the extension cookbook) titled roughly "Observing Host state from a browser plugin", covering:

1. The forwarded-event allowlist and where it lives (packages/api/remotes, src/remote-events.ts).
2. That the list is fixed per release — adding an event or a custom channel requires in-repo work / Typert tooling.
3. The emit vs waterfall delivery difference and its consequence for passive observers.
4. Payload shapes (they are declared in each owner package's client-safe ./types, cross-linked).

Environment

• Runtime @deepseek-ai/dsh 0.1.2-rc.1 (and current main at time of writing).

[argszero]

@andreagosto

I built the same kind of browser-half plugin and hit the identical wall — API_REMOTE_FORWARDED_EVENTS is real and it's the whole ground truth. I want to add one precision that makes the "closed" claim exact, because it's subtly two different closures.

Confirmed against master (c389f96):

• packages/api/remotes/src/remote-events.ts is literally "the one home of this application's forwarded-Host-event allowlist" — 18 entries today, each { event, mode: 'emit' | 'waterfall' } (agent-preset/selected, approval/request, api-session/*, commands/change, llm/adapters-updated, settings/document-updated, user-questions/request, etc.). Both the Host forwarding loop and the ctx.remote.$on key face read this single declaration; ./types.ts derives the type projection from it and stays type-only.
• packages/api/gateway/src/index.ts:243 throws typert gateway: forwarded Remote event source is already registered — the runtime holds one registerRemoteEvents slot.

The exact "two closures":

1. Type seat is OPEN. TypertRemoteEventSelection (packages/typert/protocol/src/types.ts:134) is an empty interface you can declaration-merge to extend the selection face; TypertForwardableEventEntry (:125) types each allowlist row. So in TypeScript the surface looks extensible.
2. Runtime is CLOSED. The gateway registerRemoteEvents has a single slot and throws on a second registration; and the Host forwarding loop iterates the compiled allowlist, so it can never statically enumerate a plugin-defined custom channel — a plugin's ctx.emit('my-custom-event') on the host side is simply never forwarded. That's the trap: the type deck makes it look addable, but the wire/channel set is fixed per release, and adding an event requires in-repo work + the Typert toolchain.

On the emit vs waterfall trap — your read is exactly right. emit broadcasts to every listener; waterfall (approval/request, user-questions/request) is single-consumer, claimed by the official answerer in registration order, so a passive observer silently loses it. That's why for "did a workspace finish / error / wait on the user" you must lean on observable, multi-consumer signals (e.g. api-session/status, api-session/activity) rather than the waterfall approval/request — and #5898's ctx.uiSession.pendingInteractions is the right passive-safe signal for the "waiting" branch.

Support for the docs page — your proposed structure is good and the placement under docs/user/develop/ (or extension cookbook) is right. Two additions I'd fold in: (a) a short note that the allowlist is both the Host dispatch strategy AND the legal ctx.remote.$on key set (one thing, two faces — that's the fixable misconception), and (b) a "this is closed per release; to add an event you need in-repo + Typert" callout up front so authors don't burn a cycle like we both did. I'm happy to help draft the emit-vs-waterfall delivery table from the actual remote-events.ts entries if that would unblock you.