userQuestions: single global provider without timeout hangs non-web channels (WeChat/Telegram gateways) forever

[tiae8823-byte]

Summary

ask_user_question hangs indefinitely when the agent is driven from a non-web channel (e.g. a WeChat/Telegram gateway) because:

1. dsh-host-apiproxy registers the only userQuestions provider unconditionally at startup (registerProvider rejects a second one with DUPLICATE_PROVIDER).
2. Its ask() pushes the question into the browser RPC queue with no timeout and no offline detection — if no browser is connected, the queue is never consumed and the tool call never settles.

Repro

• Run dsh web (host only, no browser connected).
• Drive a session from any non-web client (our case: a WeChat gateway plugin, but Telegram/Discord/CLI drivers would hit the same).
• Model calls ask_user_question → tool hangs until the agent turn is manually cancelled.

Workaround we shipped

We built a WeChat gateway plugin (dsh-chatnode-wechat) that works around this by scoped-shadowing ask_user_question (registering a same-name tool on the agent's scoped ctx — documented in docs/subsystems/tools.md: "Scoped tools shadow globals") and broadcasting the question to both the web UI (via ctx.userQuestions.ask()) and the WeChat text channel, first answer wins, WeChat lane times out after 10 minutes. It works, but it is a large workaround for what looks like a core capability gap.

Suggested improvements (any subset would help)

1. Timeout / offline detection in the web provider: if no client has consumed the question within N seconds, reject with a dedicated error so the model can fall back to asking in plain text.
2. Multiple providers or per-agent routing: allow gateways to register their own userQuestions provider (e.g. matched by request.agent) instead of a global singleton.
3. Question event: emit an event when ask() is invoked (like approval/request already does), so external channels can forward the question to the user and answer it — this is the pattern approval/request establishes and userQuestions currently lacks.

Context

• Docs: docs/subsystems/user-questions.md ("Only one provider may be active in a context")
• The approval seam already works the way gateways need: approval/request → forward → reply → resolve, with a default-deny timeout. userQuestions has no equivalent event or timeout.
• Community precedent: HermesClaw explicitly unblocks pending prompts on gateway disconnect instead of hanging; Hermes Agent uses platform-native buttons on Telegram/Discord, but WeChat personal accounts are text-only, so a text-numbered prompt + reply-parsing contract (what our plugin implements) is the pragmatic floor.

Thanks for the great plugin architecture — the scoped-shadow escape hatch made the workaround possible without touching core.

[argszero]

Verified every claim against master (47f9438) — your analysis is accurate, and this is the interaction-seam sibling of an unbounded-wait family I've been tracking (#1607, cordis_inspect_query). Adding the source-level layer:

1. All three claims confirm at source. The provider registers unconditionally (packages/host/apiproxy/src/api-proxy.ts:1369 — always in apply(), no browser-presence gate), registerProvider rejects a second with DUPLICATE_PROVIDER (packages/interaction/user-questions/src/index.ts:64-73), and ask() settles on exactly three paths: mux answer, abort signal (ASK_ABORTED), or provider disposal — none of which fire when no browser is connected, because the for (const queue of muxQueues) fan-out at api-proxy.ts:1394 iterates an empty set (muxQueues fills only when a client opens events.mux, :3432). Confirmed: hang until turn-cancel, exactly as you describe.

2. Precision on the approval contrast — it's fail-closed fallthrough, not a timeout. The approval seam doesn't have a "default-deny timeout" either; it has an answerer chain with a fail-closed default: when no handler claims the request the chain calls next() and the ask settles 'unavailable' (packages/interaction/user-approval/src/index.ts:25/:53/:89 — "failure yields the fail-closed default"). The userQuestions provider has no chain — it IS the single sink, so there's no fallthrough to settle the promise. That's the structural gap: approval is a dispatch with a default; userQuestions is a sink with no default. Any fix should add the missing "no answerer → settle" arm rather than a blanket timeout, because...

3. The key design point: distinguish "no listener" from "listener hasn't answered". A hard timeoutMs on ask_user_question would punish slow human readers (the tool registers no timeoutMs today, so the cooperative guard at packages/guard/timeout-policy/src/index.ts:57-59 can't rescue it either). But offline detection is trivially and safely implementable: muxQueues.size === 0 at ask time → reject synchronously with a distinct code (ASK_NO_CLIENT-style) so the model can fall back to plain-text asking. The race window (client connecting between ask and reject) is handled by the mux replay at api-proxy.ts:3438-3443 — pending questions are re-pushed to a newly-connecting client — so a short grace period (e.g. 2–5 s before the no-client rejection) preserves connect-race semantics for free.

4. Your suggestion 3 (question event) matches the in-repo precedent exactly. approval/request already establishes the forward→reply→resolve pattern with the approval/asked+approval/decided audit pair; a question/requested event on the service (not just the mux frame) would let gateways forward without shadowing. And suggestion 2 (per-agent routing) fits the existing ask(request) signature — it already receives request.agent?.id (used for the sessionId requirement at api-proxy.ts:1373-1378) — so a provider-selection layer on agent is a natural extension, not a new concept.

5. Family note. This is the second confirmed instance of the "promise that never settles while the listener is absent" class: #1607 (cordis_inspect_query, same empty-fanout shape, same manual-cancel rescue, same cooperative-timeout gap — packages/extensions/tool-cordis/src/index.ts:61-90 registers no timeoutMs). Both are fixed by the same two-layer recipe: fail-fast when zero listeners + optional generous timeoutMs as safety net. If the maintainers want a single small PR, the no-listener check at ask time is ~5 lines in api-proxy.ts plus a distinct error code in user-questions — and it would close both reports' core gap.

Your scoped-shadowing workaround is a nice illustration that the architecture is right even where the capability is missing — worth keeping in the thread as the community reference implementation.