Remote Host integration: CommandRuntime, Session/Message mapping, Presentation, and wire profile`

[Blank-not-black]

背景

我们正在维护一个独立的 dsh-remote-std 参考适配项目，将 DSH Remote 的插件能力逐步迁移到 dsh-std。当前已经验证了 Community v0.15 dsh-plugin.json、Host Facet、Lifecycle，以及 commands.dsh/v1alpha1 的最小接入。

项目地址：https://github.com/Blank-not-black/dsh-Remote-std

我们希望优先使用 dsh-std 中已经明确的协议接口；对于尚未覆盖的能力保留产品实现，不在本地发明新的协议字段或远程封帧规则。

希望确认或补充的接口

1. Remote consumer 如何使用 CommandRuntime

adapter-dsh 已经提供 CommandRuntime 和 session-scoped command 执行入口，但标准客户端在远程 Host 中如何获得 transport-neutral 的 typed client、如何传递 session identity 和 presentation agreement，目前缺少完整的推荐示例。

我们希望确认：

• CommandRuntime 的远程 consumer 入口是否由 connection 承载；
• contextId、session identity 和 invocation identity 的推荐映射；
• 标准命令在传统 DSH ctx.commands 与标准 Facet 之间的渐进迁移方式。

2. Session / Message 的 DSH 事件映射

Remote 当前同时承载 mux 和 host 两类下行事件。希望有一份推荐映射，明确：

• 哪些事件应进入 session.dsh/v1alpha1；
• 哪些事件应进入 messages.dsh/v1alpha1；
• privacyClass、scope、sequence、replay 和未知事件如何处理；
• 网关重连、基线重放和事件游标是否属于协议层语义。

3. Presentation 跨端点调用

审批、提问、选择和取消操作需要绑定到一次 invocation，而不是长期注册。希望明确标准 adapter/connection 对远程 Presentation client 的推荐实现，尤其是：

• invocation-scoped agreement 如何传递；
• 断线、取消、超时和重复响应如何处理；
• Presentation 操作是否应该单独定义 wire profile。

4. Connection wire profile

Remote 场景需要认证绑定、重连、流控、封帧、序列化和关闭语义。当前 connection 文档将这些内容列为尚未标准化的部分。

希望确认这些内容后续应归入：

• @dsh-std/connection 的正式 wire profile；
• 独立的 carrier profile；
• 或另一个 Remote/Transport RFC。

我们希望避免每个 Host 都各自发明一套不兼容的远程 wire protocol。

5. Legacy DSH plugin migration

希望有一个推荐的渐进迁移模式，说明同时拥有传统 DSH apply(ctx) 和标准 facets.host.entry 的插件应该如何：

• 声明 optional contract；
• 在 adapter 不存在时保持 legacy fallback；
• 在标准能力可用后切换为标准路径；
• 最终安全移除传统入口。

我们可以提供的验证

我们可以为上述接口提供真实的移动端/网关场景 fixture，包括：

• 文本、图片、文件和会话事件；
• 审批、提问、取消和断线恢复；
• mux/host 双流、游标和基线重放；
• DSH 重启、网关重启和客户端恢复。

如果其中某些方向已经有对应 proposal 或正在实现，也请指向相应文档；我们会优先按现有方向适配并回传测试结果。

[Yan-Zero]

非常欢迎！dsh-Remote-std 的实践对整个生态至关重要，特别是“避免各端各自发明不兼容的远程私有 wire 协议”这一点，完全契合 dsh-std 的初衷。

其实我们在 dsh-tui 的 feat/std-v1-remote 分支中，已经做了一套完整的 Remote TUI 参考实现（涵盖了 Channel Server、/connect 命令以及 Presentation 远程中继 Relay）。

说明一下该分支的背景：这个分支目前还没合并进 dsh-tui 上游，主要是因为重构幅度较大、涉及整个架构分层，上游 maintainer 短时间内 review 不过来。此外，该分支中自带的 remote 示例没有加入复杂的鉴权系统——这在设计上是刻意为之的：因为 @dsh-std/connection 本身是 信道无关（Carrier-agnostic） 的。在生产落地时，只需将底层的 HTTP/WS 通道提升为 QUIC（或 SSH/TLS）并配上简单的 Token 鉴权，就能天然做到无法监听、高效且安全，标准层无需重复发明传输认证协议。

结合该分支的落地经验与现有的规范设计，针对你提到的 5 个问题逐一回复：

---

1. Remote 消费端如何使用 CommandRuntime 与 Presentation 绑定

• 承载方式：统一由 @dsh-std/connection 承载。远程客户端通过 ConnectionService 取得协商后的类型化 CommandRuntime client；
• 单次调用上下文传递（推荐参考实现）：
  • 推荐参考 dsh-tui 中的 PresentationRelay 实现：服务端在收到远程命令执行请求时，通过 AsyncLocalStorage 记录当前的 { connectionId, invocationId, sessionId }；
  • 当命令执行过程中需要调用 Presentation（如审批/提问）时，动态路由到该 connectionId 对应的连接客户端上，调用结束后该 Scope 自动释放，不会污染全局状态；
• 命令注册：标准命令通过 context.extensions.publish(commandProtocol, ...) 发布，adapter-dsh 会自动投影到 DSH 的 ctx.commands，因此本地和远程客户端都能触发。

---

2. Session 与 Message 的事件划分

• session.dsh/v1alpha1（@dsh-std/session）：负责持久化会话事实（Durable Session Lifecycle），例如会话创建/销毁、分支切换、落盘快照、会话元数据变更；
• messages.dsh/v1alpha1（@dsh-std/messages）：负责消息内容流与交互片段（Message Payload & Chunks），如下行增量文本、ToolCall 片段、状态指示器（Thinking/Status 等）；
• 重连与游标：sequence 保证单个会话内单调递增；断线重连、基线重放和游标（Cursor）属于 Carrier / Gateway 传输层的投递保证职责，协议信封本身保持纯数据与幂等。

---

3. Presentation 跨端点调用

• Invocation-Scoped 绑定：
  • 审批（approve）、提问（ask）、单选（select）必须绑定到单次 invocationId；
  • 客户端在握手协商阶段声明自己支持的 Presentation kind（如 OpenExternal、UserInteraction），宿主在调用时动态注入该 client；
• 断线与超时处理：
  • 严格遵循 Fail-Closed（失败关闭） 原则：如果远程连接断开或超时，未完成的审批/提问立即以 InteractionAborted / Timeout 失败关闭，绝不悬挂阻塞后台进程；
• Wire 传输：Presentation 请求直接复用底层的标准 attachment 数据帧，无需单独搞一套私有线协议。

---

4. Connection Wire Profile 的统一规范

• 正式归宿：
  • 统一归入 @dsh-std/connection 的 connection.cbor.dsh/v1alpha1 wire profile（参考草案 docs/proposals/connection-wire.zh.md）；
  • 标准定义了基于 RFC 8949 CBOR 的确定性二进制帧（Length-prefixed CBOR frame），统一承载 Hello、Offer、Acceptance、Attachment 数据流、流控与优雅关闭；
  • 底层 Carrier（如 WebSocket、SSH channel、QUIC、TLS）只负责提供可靠、有序、已认证的通道，各端共享同一套二进制 wire 编解码。

---

5. 传统插件的平滑过渡（Legacy Migration）

• 双模兼容方案：
  • 插件可以在 package.json 中保留传统 apply(ctx) 入口，同时在 dsh-plugin.json 中声明标准 facets.host.entry；
  • 当环境中存在 @dsh-std/adapter-dsh 时，adapter 会优先加载标准 Facet 并建立协议协商；若运行在没有标准 adapter 的旧版 DSH 中，插件回退执行 apply(ctx)；
  • 待生态大部分环境具备标准支持后，再逐步移除 apply(ctx)。

---

你们手里积累的真实移动端和网关测试场景（Fixtures，包含审批弹窗、断网恢复、重启重放等）非常宝贵！后续非常欢迎把这些真实用例沉淀进官方的一致性测试套件（Conformance Fixtures）。

有任何具体实现细节，随时交流！