Proposal: multi-surface ask-user routing — fan-out with first-answer-wins over the user-questions waterfall (reference implementation shipped, ready to upstream)

[fan56]

Summary

v0.1.2-alpha reworked the ask-user answer path: the rc-era single-provider slot is gone, and answerers now compose on the agent-scoped 'user-questions/request' cordis waterfall (@deepseek-ai/dsh-user-questions) — return a value to answer, call next() to delegate, NO_PROVIDER when nobody accepts. That solves coexistence: two UIs in one profile no longer fight over a slot.

What it still cannot express is simultaneity. The waterfall is a queue, not a race, and registration order decides who sees the question first. This proposal asks for a first-party multi-surface routing capability on top of that waterfall — fan-out, first-answer-wins, loser dismissal — and offers a shipped, MIT-licensed reference implementation ready to upstream once external PRs are accepted.

The gap, concretely

Consider the common remote-attach deployment (the phone-remote threads #2250 / #2245 / #2097 describe the demand): one dsh process, one live session, two interaction surfaces — a desktop TUI and an IM card channel (Feishu/WeChat/Telegram-style). The human answers wherever they happen to be. Queue semantics fail this in two ways:

1. A blocking front answerer starves the rest. The first answerer in registration order renders the question and awaits its human. If that human has walked away from that surface, every later answerer — the phone — never even receives the request. This is the milder twin of userQuestions: single global provider without timeout hangs non-web channels (WeChat/Telegram gateways) forever #2544, where a single global provider with no timeout hung non-web channels forever.
2. No dismissal protocol. Even if two answerers could both see the request, there is no way to tell the loser "someone else answered, dismiss your card" — stale pending questions on the phone is exactly the Stale answered ask card: clicking reports question response rejected: not-pending #4271 failure family.

What the scenario needs is four primitives the waterfall doesn't carry:

• fan-out: deliver to every surface claiming the session, simultaneously;
• first-answer-wins: settle the outer promise once, on the first completed answer;
• settled(request, winner): notify losers so they dismiss their rendered UI;
• claim(request): a per-surface predicate ("this asking session is mine"), with a visible-somewhere-beats-failing fallback when nobody claims.

Reference implementation: dsh-ask-router (shipped)

@aiwayds/dsh-ask-router 0.2.0 (npm, MIT; repo: https://github.com/fan56/dsh-ask-router) implements exactly that protocol as ctx.askSurfaces:

• surfaces register { name, claim(request), ask(request), settled?(request, by) };
• one routed ask: claim-filter → fan-out to claimants (all registered surfaces when nobody claims) → first completed answer wins → every other surface gets settled(request, winnerName) → abort rejects everywhere via the request's own signal;
• failure containment: a throwing claim claims nothing, a throwing settled never breaks the winner, the outer promise rejects only when every target failed.

It speaks both host eras: on rc (≤0.1.1) it owns the single provider slot and multiplexes it (the only way two UIs can coexist at all there); on alpha it registers as exactly one waterfall answerer — with zero registered surfaces it delegates via next(), stepping aside so a co-present native answerer (e.g. the web UI) serves, or the request fails NO_PROVIDER upstream untouched. Live-verified on an rc host with the dual-surface pair (desktop TUI panel + Feishu interactive card on the same live session, first-answer-wins across a phone and a terminal); the alpha adapter is unit-tested, including the bare-registry next() delegation.

Why there is no conflict with the alpha mechanics

• It occupies one waterfall slot and composes: agent-scoped native answerers keep working behind it whenever it delegates; unscoped listeners are unaffected by the agent scoping.
• Everything ask() enforces upstream of the waterfall — CALLER_NOT_LIVE / DELEGATED_CALLER identity guards, BAD_INTENT validation, abort mapping — is untouched; the router sits strictly downstream and reuses the same error taxonomy (NO_PROVIDER, ASK_ABORTED).
• Presentation intents pass through opaquely: a surface honours intent if it recognises the tag, renders the generic option list otherwise — same answer fields either way.

Request

Two shapes upstream could take, in order of preference:

1. First-party surface routing in dsh-user-questions — a registry (e.g. ctx.askSurfaces or an equivalent) plus the fan-out / first-answer-wins / settled protocol as an official multi-surface answerer, so any IM/mobile channel plugin can register as a surface without each rebuilding the race and dismissal logic (and its races — Promise.race settlement order and pre-aborted-signal edge cases are exactly where a naive implementation breaks).
2. Document the composition pattern for the alpha waterfall — that next() delegation is the intended way for a router-style answerer to compose, and what a well-behaved multi-surface layer owes its losers (dismissal) and the host (one slot, taxonomy-preserving errors) — so plugin authors implement it safely.

Until external PRs are accepted, this discussion can serve as the tracking thread; the reference implementation is ready to convert as-is.

[hZsFN]

Related real-world case from the Web surface (0.1.5-rc.2) — exactly the seam this proposal addresses.

Symptom: with dsh web running and the browser open, if the session currently being displayed is not the one that is asking, ask_user_question fails immediately with no user-questions answerer accepted the request, instead of waiting for the user to switch back.

Repro (same session, same day, 3 attempts):

1. Window not focused / not showing that session → fails (noAnswerer)
2. Same again → fails
3. User switches the window back to that session → succeeds immediately

Mechanism (mirrors the waterfall semantics described above): client plugin @deepseek-ai/dsh-client-ui-user-questions returns next() early when ctx.sessions.scopeOf(owner) === undefined, so nobody accepts and the server side throws noAnswerer. The Web session view's ability to answer is implicit in "is this session currently rendered" — it is never an explicitly registered surface, so it cannot be inspected, awaited, or targeted.

This is the opposite end of the same gap as #2544:

• no browser connected + non-web driver → hangs forever (userQuestions: single global provider without timeout hangs non-web channels (WeChat/Telegram gateways) forever #2544)
• browser online but not showing that session → fails closed instantly (this case)

In neither state can the outside tell the two apart, and in both the user never learns afterwards that a question was asked.

Suggestion: when an answerer declines, being able to tell "no client at all" apart from "a client is online but not on this session" would let the latter keep the request pending (and/or show a visible "1 question waiting" affordance) instead of hard-failing the agent's tool call. Making the Web session view an explicitly registered surface — rather than relying on scopeOf existence — is precisely the shape this proposal describes.

[fan56]

Thanks @hZsFN — and to be clear, the sigh above was aimed at the two quiet weeks before you showed up, not at your comment, which is exactly the engagement this thread needed.

Your web-surface case maps 1:1 onto the seam the proposal targets, and it sharpens the argument in two places:

1. Implicit vs. explicit surfaces. The web session view answers only while the session happens to be rendered — its answerability is a side effect of scopeOf(owner), not a registered, inspectable surface. That is why the only observable outcomes are the two extremes: userQuestions: single global provider without timeout hangs non-web channels (WeChat/Telegram gateways) forever #2544's indefinite hang (no client at all) and your instant hard failure (client online, session not in view), with no way for the caller — or the user, after the fact — to tell them apart.

2. Decline semantics. Agreed the waterfall needs richer decline reasons. "No client at all" should surface as a distinct error (or queue for retry), while "online but not on this session" should keep the request pending, ideally with a visible "1 question waiting" affordance. The question was answerable — failing the agent's tool call there is a routing artifact, not a real decline.

I will fold both points into the proposal write-up here — this thread stays the tracking thread until external PRs are accepted. The web session view is precisely the missing registrant — the one surface no plugin can register on the host's behalf — which is why it belongs first-party rather than in a plugin.

Thanks again for the detailed case; genuinely useful evidence for the proposal.

[hZsFN]

哈哈我也是在让ai自动排障她看到你的内容有关就直接过来回复了

[hZsFN]

Happy to help. Count me in for the web-side verification once the upstream PR exists — I can test on both the desktop Electron shell and a plain browser tab, and report back with exact outcomes (no-client vs. online-but-elsewhere).

To sharpen the e2e assertion, here is the exact condition I can reproduce deterministically:

• dsh web running, browser attached, session A is the one asking.
• The view switches to a different session (or the window no longer shows session A) → ask_user_question fails immediately with no user-questions answerer accepted the request (no wait, no timeout).
• Switching the view back to session A and retrying → succeeds immediately.

So the assertion is roughly: same request + same online client + different viewed session ⇒ must not fail closed. Happy to also capture CDP traces / main-thread metrics if useful, though this path is a routing decline rather than a perf problem.

+1 on the split decline semantics — and the "1 question waiting" affordance is the piece users actually notice: in my case neither the agent nor I could tell afterwards that a question had ever been asked; the tool call just failed.

Ping me when the PR is up (or drop the branch name here) and I'll test it.