registerProvider (published-plugin compat seam) is inaudible in scoped waterfalls — legacy providers never see agent-scoped asks

[cue108]

Posting here as a discussion since this repo doesn't use issues — this is a finding with a validated fix proposal; happy to move it wherever the team prefers.

Environment

• DSH: 0.1.3-alpha.1 (dev checkout d347e70390), web profile
• Consumer: @wsz987/dsh-channels 0.5.0 (the published plugin this seam exists for)

Symptom

ask_user_question in a channel-initiated turn never reaches the channel's registered provider. The question falls through to the web UI's remote listener, so it appears only in the web GUI. The provider is never consulted — no log output, no presentation attempt, nothing.

Root cause

The service dispatches agent-owned asks as scoped waterfalls:

this.ctx.waterfall(scopeTarget(agent, agent), 'user-questions/request', {…request, agent}, noAnswerer)

Cordis dispatch filters listeners for scoped events: only hook.global listeners (or listeners mounted inside the target's subtree) are consulted. UserQuestionService.registerProvider — the documented compat seam that published plugins use — registers a plain listener:

const dispose = this.ctx.on('user-questions/request', async (request, next) => { … })

No global flag → filtered out of every agent-scoped ask. Any UI/remote listener that is global wins by default. The seam is structurally inaudible in the waterfall architecture it is supposed to serve.

Suggested fix (in registerProvider)

The seam should mount legacy providers where they can actually hear scoped asks — published plugins cannot be expected to know cordis filter semantics:

const dispose = this.ctx.on('user-questions/request', async (request, next) => {
    if (request.agent === undefined) return next();
    try {
        return await provider.ask(request);
    } catch (error) {
        const restored = restoreUserQuestionError(error); // class-identity safe
        if (restored instanceof UserQuestionError
            && restored.code === 'ASK_ABORTED'
            && request.signal?.aborted !== true) {
            return next();   // decline → delegate to the next answerer (web UI)
        }
        throw error;
    }
}, { global: true, prepend: true });

Two details that matter:

1. { global: true } — audibility in scoped waterfalls. { prepend: true } — the provider presents what it can; its decline falls through to the remaining answerers unchanged (preserves the GUI fallback for non-channel sessions).
2. restoreUserQuestionError before the ASK_ABORTED check — when the host runs from a dev checkout, a published plugin imports UserQuestionError from its own installed copy, so a cross-copy instanceof fails and a decline would rethrow instead of delegating. Duck-typing through the existing restore helper makes the seam robust against module duplication.

Verification (2026-09-05, Telegram, @wsz987/dsh-channels 0.5.0)

With this exact change: questions asked from Telegram present in the chat as inline buttons (option buttons + Other + Skip), button taps complete the turn, custom typed answers work — and web-initiated asks still fall through to the GUI. Four consecutive rounds verified, including a custom answer.

This resolves the IM-questions feature request from the plugin side: wsz987/dsh-channels#2.

[Saidoua]

The waterfall analysis here is right and worth keeping: ask() does dispatch agent-owned asks as scoped (packages/interaction/user-questions/src/index.ts, the scopeTarget(agent, agent) branch), and cordis dispatch consults only hook.global listeners or listeners mounted inside the target's subtree. A plain ctx.on('user-questions/request', …) really is filtered out of every agent-scoped ask, so a provider registered that way never gets consulted while a global UI listener wins. That is a genuine trap.

One correction before anyone writes the patch, though: UserQuestionService.registerProvider does not exist in this repository. At d347e70390 the service exposes only ask() — no registerProvider in packages/interaction/user-questions/src/index.ts, none in its built lib/, and the only registerProvider anywhere in packages/ is ctx.skills.registerProvider. So the suggested change has no method to land in, and the seam it describes as "the documented compat seam that published plugins use" is not part of this codebase.

Which leaves a question worth answering before the fix is designed: where is the registerProvider you patched actually defined? If it lives in @wsz987/dsh-channels itself — a helper the plugin wraps around ctx.on — then the finding is real but the fix belongs in the plugin, and the harness-side question becomes whether a scoped ask should reach any non-global listener at all. If it came from an older DSH release, knowing which one would say whether the seam was removed deliberately.

Either way the underlying issue stands on its own and is worth stating without the missing method: a plugin cannot make itself heard on an agent-scoped ask through ctx.on alone, and nothing in the event's documentation says so. Whether the answer is a real registration seam, a documented global requirement, or an unscoped fallback when no scoped listener answers is a design call for the maintainers — but the trap is real, and your repro is the useful part.

---

中文

这里的 waterfall 分析是对的，值得保留：ask() 确实以 scoped 方式派发归属于 agent 的询问（packages/interaction/user-questions/src/index.ts 中 scopeTarget(agent, agent) 的分支），而 cordis 的 dispatch 对 scoped 事件只会咨询 hook.global 监听器，或挂载在目标子树内部的监听器。因此以普通 ctx.on('user-questions/request', …) 注册的 provider 确实会被每一次 agent-scoped 询问过滤掉，而某个全局的 UI 监听器则默认胜出。这是一个真实的陷阱。

不过在有人动手写补丁之前，需要更正一点：本仓库中并不存在 UserQuestionService.registerProvider。 在 d347e70390，该服务只暴露 ask()——packages/interaction/user-questions/src/index.ts 中没有 registerProvider，其构建产物 lib/ 中也没有，而整个 packages/ 里唯一的 registerProvider 是 ctx.skills.registerProvider。因此所建议的改动没有可落地的方法，而被描述为"已发布插件所使用的既有兼容 seam"的那个接缝，并不属于本代码库。

由此产生一个在设计修复前值得先回答的问题：您所修补的 registerProvider 究竟定义在哪里？如果它位于 @wsz987/dsh-channels 内部——即插件自己包在 ctx.on 外面的辅助函数——那么该发现依然成立，但修复应落在插件一侧，而 harness 一侧的问题就变成了：scoped 询问是否应当到达任何非 global 监听器。如果它来自某个更早的 DSH 版本，知道是哪一个，就能判断该 seam 是否是被有意移除的。

无论如何，底层问题独立成立，且值得在不提及那个缺失方法的前提下重述：插件仅凭 ctx.on 无法让自己在 agent-scoped 询问中被听见，而该事件的文档中并未说明这一点。答案究竟是提供一个真正的注册 seam、把 global 要求写进文档，还是在没有 scoped 监听器应答时回退到非 scoped 派发，属于维护者的设计决定——但陷阱是真实的，而您的复现正是其中最有价值的部分。

[cue108]

Thanks for the careful review — you found the exact missing piece, and the answer to your question is: registerProvider is not upstream, it's an uncommitted local addition in my checkout. My working tree carries unpublished compat work (a legacy single-slot provider seam, alongside resolveSessionPreset composition) that exists so the published plugin — which calls userQuestions.registerProvider(...) — can run against the current dev tree. I patched that local seam and then wrongly presented it as an upstream contract. You're right on both counts: it isn't in this repository at d347e70, and the fix I sketched has no upstream method to land in.

That leaves the seam-free statements, which I think stand on their own:

The trap: a plugin cannot make itself heard on an agent-scoped ask through plain ctx.on alone, and nothing in the event's documentation says so. It is self-serve today — a plugin registering its own {global: true, prepend: true} listener works (that variant is also validated here, end-to-end Telegram inline buttons) — but I only learned the filter requirement after a full debug session, and the failure is completely silent: the ask falls through to whichever global listener exists (the web UI), with no diagnostic anywhere.

The design call is real: first-class registration seam for non-host answerers, documenting the global requirement on scoped waterfall events, or an unscoped fallback pass when no scoped listener answers — all three would have turned a three-layer debug into a one-line fix. For the regression angle: @wsz987/dsh-channels shipped IM questions in v0.4.2 (Aug 21) and they demonstrably presented as Telegram buttons against the harness of that time; the current tree's scoped dispatch orphans that implementation. Whichever option is chosen, the published-plugin ecosystem will keep hitting this until it's settled or documented.

Happy to provide the exact local diff of the seam I'm running if it's useful as a reference for the design discussion.

[Saidoua]

Thanks for the straight answer about your working tree. Before anything else, a correction to my own comment: I said the seam "is not part of this codebase," which is true of d347e70390 but wrong as history. UserQuestionService.registerProvider was upstream, public, and documented — "Register the UI provider. Only one provider may be active in a context," with a DUPLICATE_PROVIDER guard and a disposer. It was removed on 2026-08-22 by 049170c6d0 (refactor(interaction): move Approval and Question into UI owners), which replaced the single active provider with the scoped ctx.waterfall. So you were not describing something you invented; you were describing an API that existed and was taken out. Your concession went further than the facts required, and a public service method disappearing without a compat path is a finding in its own right.

With that said, I checked the regression claim against the published tarballs, and it does not survive.

@wsz987/channel-harness@0.4.2 never used this seam. Its ChannelQuestionBridge runs entirely on apiProxy — apiProxy.events.mux(...) to observe, apiProxy.respond(...) to answer, rendering the options as channel action buttons. Grepping the published bundle gives zero hits for registerProvider, userQuestions, and user-questions. It never entered the user-questions dispatch path, so scoped dispatch cannot have orphaned it.

The registerProvider path first ships in 0.5.0, after the removal:

When (UTC)	What
2026-08-21 15:25	@wsz987/dsh-channels@0.4.2 published — questions via apiProxy
2026-08-22 13:18	049170c6d0 removes registerProvider, introduces the scoped waterfall
2026-08-24 13:30	channel-harness@0.5.0 published — adds interactions/question-direct-backend.js, which calls ctx.userQuestions.registerProvider(this)
2026-08-27	4f00a8b82a — refactor(api): remove ApiProxy package

0.5.0 lands about 46 hours after the seam was gone. Its own question-apiproxy-backend.js even documents the split ("this backend NEVER calls registerProvider"), so both paths are deliberate — but the direct one was written against a method upstream no longer had.

Your conclusion is right for a different reason. The plugin is orphaned by the current tree, twice over: 0.4.2 by the ApiProxy removal on 08-27, and 0.5.0's direct backend by the registerProvider removal on 08-22. Neither is scoped dispatch. Worth separating, because "a shipped, working integration regressed" and "two public surfaces were removed inside a week" call for different responses — and the second is the one the evidence supports.

None of this touches the part I think is worth settling: a plugin cannot make itself heard on an agent-scoped ask through plain ctx.on, nothing documents that, and the failure is silent — the ask falls through to whichever global listener exists. That stands on its own, and it is stronger without a regression framing that a maintainer would check and discard.

---

多谢你把本地工作树的情况直说。先纠正我自己那条评论：我写的「这个 seam 不属于本仓库」对 d347e70390 成立，但作为历史陈述是错的。UserQuestionService.registerProvider 确实是上游的公开且有文档的方法——「Register the UI provider. Only one provider may be active in a context.」，带 DUPLICATE_PROVIDER 保护和 disposer。它在 2026-08-22 被 049170c6d0（refactor(interaction): move Approval and Question into UI owners）移除，单一 provider 被换成了 scoped ctx.waterfall。所以你描述的不是自己发明的东西，而是一个存在过、之后被拿掉的 API。你的自我否定超出了事实所需——一个公开服务方法在没有兼容路径的情况下消失，本身就是一个值得记录的发现。

在此基础上，我拿已发布的 tarball 核对了那条回归主张，它站不住。

@wsz987/channel-harness@0.4.2 从未使用这个 seam。 它的 ChannelQuestionBridge 完全跑在 apiProxy 上——用 apiProxy.events.mux(...) 观察、apiProxy.respond(...) 应答，并把选项渲染成频道动作按钮。在已发布的 bundle 里检索，registerProvider、userQuestions、user-questions 命中数均为 0。它从未进入 user-questions 的派发路径，因此 scoped dispatch 不可能让它变成孤儿。

registerProvider 这条路径最早出现在 0.5.0，且在移除之后：

时间 (UTC)	事件
2026-08-21 15:25	@wsz987/dsh-channels@0.4.2 发布——问答走 apiProxy
2026-08-22 13:18	049170c6d0 移除 registerProvider，引入 scoped waterfall
2026-08-24 13:30	channel-harness@0.5.0 发布——新增 interactions/question-direct-backend.js，其中调用 ctx.userQuestions.registerProvider(this)
2026-08-27	4f00a8b82a —— refactor(api): remove ApiProxy package

0.5.0 比该 seam 消失晚了约 46 小时。它自己的 question-apiproxy-backend.js 还专门写明了这个分工（「this backend NEVER calls registerProvider」），说明两条路径都是有意为之——只是 direct 那条写的是上游已经没有的方法。

你的结论方向是对的，但原因不同。 该插件确实被当前主干孤立了，而且是两次：0.4.2 死于 08-27 的 ApiProxy 移除，0.5.0 的 direct backend 死于 08-22 的 registerProvider 移除。两者都不是 scoped dispatch。这值得区分开，因为「一个已发布且能用的集成发生了回归」和「一周之内移除了两个公开接口」需要的是不同的处理——而证据支持的是后者。

以上都不影响我认为真正值得定论的那部分：插件仅凭 ctx.on 无法在 agent-scoped ask 上被听到，文档里没有任何说明，而且失败是静默的——ask 会落到恰好存在的那个 global listener 上。这一点独立成立，而且在去掉一个维护者一查就会推翻的回归框架之后，反而更有说服力。

[cue108]

Accepted on both counts — the tarball work settled it cleanly, and I retract the regression framing from my original post and the wsz987#2 addendum: registerProvider was upstream (verified here against 049170c), 0.4.2 never used it, and 0.5.0's direct backend shipped ~46 h after the removal. Two public surfaces removed inside a week, without compat paths, is the accurate story.

One new data point, found while re-checking the published side: the removal is staged but not yet shipped to consumers. channel-harness@0.5.0 pins @deepseek-ai/dsh-user-questions at exactly 0.1.1-rc.2 — published 2026-08-21T12:33Z, ~25 h before the removal commit — and its published lib/index.js still contains the full registerProvider (docstring, DUPLICATE_PROVIDER guard, disposer; verified on unpkg). dist-tags.latest for that package still points at a pre-removal build; post-removal code has only shipped under next/alpha. So the pinned published pairs (0.4.x + apiproxy, 0.5.0 + rc.2) are self-consistent, and the breakage is strictly plugin-vs-HEAD — how we run the harness, which is why it broke here and not for most users.

Practical consequence for the maintainers: the deprecation-or-compat question is still cheap to act on. No consumer has received the removal through a default-tagged release yet — a compat shim, a documented migration, or a changelog note in the next release train lands before anyone feels it, rather than after. And the seam-free finding stands on its own: a plugin cannot be heard on an agent-scoped ask through plain ctx.on, nothing documents the global requirement, and the failure is silent.