Proposal: document ctx.uiSession.pendingInteractions as the browser-side signal for pending user interactions

[andreagosto]

Summary

The only reliable browser-side signal for "a session is waiting on the user" (approval or user-question pending) is the undocumented ctx.uiSession.pendingInteractions projection (dsh-client-ui-session). Passive out-of-tree browser plugins cannot depend on the user-questions/request / approval/request waterfall events (see discussion on the closed forwarded-event surface #5897): they are single-consumer and claimed by the official answerers in registration order, and the forwarded request does not carry a stable agent/session identity.

Observed facts

• ctx.uiSession.pendingInteractions.getSnapshot() returns Map<sessionId, interaction> where interaction.kind ∈ approval | question | plan-review, fed by the official UI answerers via registerPendingInteraction(precedence) while they wait for the user, and cleared when the interaction resolves. It is not mentioned anywhere in docs/ (0 matches).
• Depending on an incidental UI service's internal projection is fragile for third parties and undocumented for everyone.

Suggested behavior

Document pendingInteractions (and subscribe) as the supported observation point for pending user interactions on dsh-client-ui-session, ideally promoted to a stable contract:

• snapshot shape (Map<sessionId, { kind: 'approval' | 'question' | 'plan-review', ... }>)
• precedence rule (one entry per session, highest precedence wins)
• that entries clear when the user answers
• a label/human description helper would also help passive notifiers.

Alternatively/additionally expose a dedicated public event or projection so observers do not reach into a UI service.

Motivation / affected users

Community plugin authors (topic dsh-plugin) building attention/notification/watchdog-style browser features. Concrete consumer: https://github.com/andreagosto/dsh-tab-watchdog.