RFC: Runtime-open root page, details, inbox, and plugin-event seams for external UI plugins

[tianzecn]

Motivation

External DSH plugins can contribute Host behavior and Client bundles, but an external plugin that needs a persistent root-level UI currently has no generic way to:

• add a navigation action without replacing the workspace browser;
• show a main page instead of the current conversation;
• reuse the root details column for plugin-owned details;
• present a global decision inbox above the shell;
• publish a schema-validated Host-to-Client event without extending the built-in static event allowlist;
• mount a plugin-owned Web read route behind the same DNS-rebinding and same-origin checks as /api.

Without public seams, plugins must either stay Host-only or depend on DOM takeover, private Desktop APIs, Session-event misuse, or a second shell owner. Those alternatives are difficult to compose and lifecycle-test.

Proposed generic ownership

This proposal is intentionally product-agnostic:

1. ui-layout owns keyed root surfaces and transient active keys:
   • shell.page
   • shell.details
   • shell.inbox
   • ctx.layout.openPage/closePage
   • ctx.layout.openDetails/closeDetails
   • ctx.layout.openInbox/closeInbox
2. ui-sidebar owns two additive list seats:
   • sidebar.navigation
   • sidebar.inbox
3. api-remotes owns a runtime-open, schema-validated event registry. A publisher is bound to the caller fiber, cannot shadow built-in events, and carries only JSON-safe tuple arguments.
4. client-connection exposes its already-resolved browser request trust fence as a public Host service so plugin-owned routes do not duplicate trustedHosts parsing or default open.

The shell stores only active registration keys. Business state and callbacks remain in the contributing plugin. Unknown, unloaded, or abdicated keys close through the shell owner.

Accessibility and lifecycle expectations

• A narrow root-details surface becomes a full-height drawer.
• Only the topmost overlay has aria-modal, keyboard trapping, Escape handling, and focus restoration.
• Background columns become inert while the drawer or global inbox is modal.
• Slot withdrawal reconciles and closes the selected surface.
• Empty sidebar list seats collapse without reserving visual space.

Security boundary

• The event registry validates names and argument tuples before publication; API Proxy retains the final lossless JSON gate.
• A plugin Web route mounts only when both webServer and the shared request-trust owner are present.
• The proposal does not expose private Host records, executable catalog data, credentials, install commands, or Desktop-private APIs.

Prototype evidence

A local external-plugin prototype over dsh-v0.1.1-rc.1 exercised these generic seams without modifying Desktop APIs:

• complete GUI suite: 4,010 passed / 1 skipped;
• CI-style Web replay: 281 passed / 15 skipped;
• real Loader composition for page → details → inbox;
• temporary Web profile with three external packages: Host read routes and browser navigation passed three consecutive runs;
• unknown-key, contribution withdrawal, stacked-modal, focus-trap, event lifecycle, trust-fence, and JSON-boundary tests.

The current upstream dsh-v0.1.1-rc.2 does not yet expose equivalent seams. The rc.2 image-pipeline changes overlap only with the Connection and API Proxy integration points; the ownership model remains compatible.

Questions for maintainers

1. Are root page/details/inbox surfaces aligned with the intended slot-system direction?
2. Should runtime-open plugin events remain in api-remotes, or is another public carrier planned?
3. Is exposing the connection-owned request-trust service acceptable, or should plugin Web routes use a different shared authorization API?
4. If these seams are directionally useful, what smaller contract slice would be most helpful to discuss first?

I can provide the tested patch and focused contract examples if maintainers want to review the implementation direction. I understand that the repository is not accepting external pull requests at this time; this Discussion is intended to validate the public extension model, not to bypass that policy.

[Oklahomawhore]

I have a tested implementation for the event-registry slice of this RFC, together with the related upstream changes required by a separately released collaboration plugin.

Patch

• Compare against upstream master
• Fork branch
• Head: ec3763012486a6b5834bf6e997a84c098800679e

The implementation:

• adds a Host-owned forwardedEvents registry to API Proxy, so an external Bundle can register one-way events on the existing events.host() stream without modifying dsh-api-remotes;
• keeps the existing host/remote-event frame and final JSON validation;
• installs and removes Cordis listeners with the registering plugin's lifetime, while rejecting blank or duplicate event names;
• lets a separately compiled Typert workspace recognize the standard Remote marker types imported from @deepseek-ai/dsh-typert-protocol;
• makes auxiliary LLM call purposes merge-extensible through GeneratePurposeMap;
• accepts dsh web --host 0.0.0.0 for local multi-node plugin testing.

This intentionally does not implement the RFC's root page/details/inbox slots or plugin-owned Web read routes. It also introduces no collaboration-product entities into Harness. The patch is limited to generic extension points needed by independently released plugins.

Verification

• focused API Proxy, Typert generator, and Web tests: 79 tests passed;
• focused TypeScript faces passed;
• CI=true pnpm run doc-sync;
• CI=true pnpm run lint;
• CI=true pnpm run build;
• built dsh web --host 0.0.0.0 --no-open --port 0 smoke passed.

The change includes bilingual package/subsystem documentation and an implemented Agent Note. The affected Markdown set changes from 60,467 to 61,334 words (+867).

Would maintainers prefer this tested slice to remain one proposal, or be discussed separately as API Proxy event registration, external Typert marker discovery, and Web bind-address support?