dsh-zen-remote 2.2.1 → 2.2.2

package/src/adapters/dsh-better-sidebar/index.ts

@@ -1,10 +1,12 @@
 /**
  * The dsh-better-sidebar adapter (PB-12), written against EXACTLY
- * version 0.25.0. Everything it knows about the plugin came off
- * `/tmp/bs-versions/0.25.0/lib/index.js` (the installed copy at
- * `~/.dsh/profiles/desktop/node_modules/dsh-better-sidebar` is the same
- * build); the method table lives in `methods.ts` beside this file, and the
- * test suite re-extracts the plugin's real method-name set to catch a
+ * versions 0.25.0 and 0.26.0 (PB-15 widened the list; 0.26.0 is a JSON-api
+ * superset of 0.25.0 — it grows fs.readPage and the sidechat dequeue/model/
+ * models methods, and moves fs.write's content onto the new raw-text
+ * /sidebar/write route). Everything the adapter knows about the plugin came
+ * off `/tmp/bs-versions/{0.25.0,0.26.0}/lib/index.js`; the method table
+ * lives in `methods.ts` beside this file, and the test suite re-extracts
+ * the plugin's real method-name set (the two-version UNION) to catch a
  * silently drifted version.
  *
  * Product decisions (2026-10-10): reads AND writes both forward — a
@@ -12,15 +14,18 @@
  * model spend (commit-message generation), documented as such; NO path
  * fencing; `open.external` refuses for a remote session; `settings.*` and
  * `/sidebar/bundle` stay local; the adapter registers as whole-machine
- * data (consent per plugin, default off).
+ * data (consent per plugin, default off). PB-15: the 0.26.0 WebSocket
+ * `/sidebar/ws/sidechat` is deliberately NOT declared (not bridged).
  *
  * The `cwd` handling is the one subtle part: better-sidebar resolves a
  * request's working directory as the session's own `header.cwd` first and
- * only falls back to a `cwd` field the CLIENT supplied (lib/index.js:6295,
- * 6075-6099). A remote panel must not steer the server by path, so the
- * server hook strips `cwd` — from the JSON body (`/sidebar/api`) and from
- * the query (`/sidebar/file`, `/sidebar/upload`) — and lets the backend
- * resolve from the (validated, real) session id.
+ * only falls back to a `cwd` field the CLIENT supplied (0.25.0
+ * lib/index.js:6295, 6075-6099; 0.26.0 resolves /sidebar/write's cwd the
+ * same way, lib/index.js:7902). A remote panel must not steer the server
+ * by path, so the server hook strips `cwd` — from the JSON body
+ * (`/sidebar/api`) and from the query (`/sidebar/file`, `/sidebar/upload`,
+ * `/sidebar/write`) — and lets the backend resolve from the (validated,
+ * real) session id.
  */
 
 import type { BridgeAdapter } from '../types.js'
@@ -44,7 +49,7 @@ const apiMethodOf = (pathname: string): string => sidebarMethodNameOf(pathname)
 
 export const dshBetterSidebarAdapter: BridgeAdapter = {
   plugin: 'dsh-better-sidebar',
-  versions: ['0.25.0'],
+  versions: ['0.25.0', '0.26.0'],
   routes: [
     {
       // The JSON API: the method name rides the path tail, the session
@@ -82,6 +87,13 @@ export const dshBetterSidebarAdapter: BridgeAdapter = {
     // The raw upload (lib/index.js:6905-6948): binary bytes, capped by the
     // relay's own upload budget.
     { path: '/sidebar/upload', match: 'exact', methods: ['POST'], maxBody: RELAY_UPLOAD_CAP_BYTES, locator: { in: 'query', name: 'sessionId' } },
+    // The raw text write (0.26.0, lib/index.js:7875-7919): the document IS
+    // the POST body (text/plain — no JSON escaping layer), the session id,
+    // path and a client cwd ride the QUERY. The plugin caps the body at
+    // WRITE_BODY_GUARD_BYTES = 8 MiB (lib/index.js:6854); the adapter takes
+    // 10 MiB — headroom over the plugin's own guard, under the relay's
+    // 100 MiB upload budget.
+    { path: '/sidebar/write', match: 'exact', methods: ['POST'], maxBody: 10 * 1024 * 1024, locator: { in: 'query', name: 'sessionId' } },
     // The HTML preview (lib/index.js:7026+): the session id is the FIRST
     // path segment after the prefix; the rest of the segments are the
     // preview file's relative path. Same-prefix relative resources ride
@@ -125,7 +137,7 @@ export const dshBetterSidebarAdapter: BridgeAdapter = {
       // directory from the (already validated) session id's own header,
       // falling back to the persisted record — a remote panel never
       // steers the server by path.
-      if (ctx.pathname === '/sidebar/file' || ctx.pathname === '/sidebar/upload') {
+      if (ctx.pathname === '/sidebar/file' || ctx.pathname === '/sidebar/upload' || ctx.pathname === '/sidebar/write') {
         if (ctx.query.get('cwd') !== null) {
           const stripped = new URLSearchParams(ctx.query)
           stripped.delete('cwd')

package/src/adapters/dsh-better-sidebar/methods.ts

@@ -1,10 +1,19 @@
 /**
- * better-sidebar 0.25.0 的 `/sidebar/api` 方法表（PB-12）——适配器唯一
- * 认识的接口清单，逐条对着 `/tmp/bs-versions/0.25.0/lib/index.js` 复核
- * （行号见各条注释，以 0.25.0 的构建产物为准）。表里没有的方法在远程
- * 会话里一律拒绝（reason `adapter-method-unknown`）：宁可少转发，不可
- * 误转发——`test/adapter-better-sidebar.test.cjs` 会把源码里的实际方法
- * 名集合提取出来与这张表逐一比对，防止插件升级后漏记。
+ * better-sidebar 0.25.0 + 0.26.0 的 `/sidebar/api` 方法表（PB-12/PB-15）
+ * ——适配器唯一认识的接口清单，逐条对着 `/tmp/bs-versions/{0.25.0,
+ * 0.26.0}/lib/index.js` 复核（行号见各条注释，未标版本的一律以 0.25.0
+ * 的构建产物为准；0.26.0 是 0.25.0 的 JSON-api 超集，除下述三处外形状
+ * 不变）。表里没有的方法在远程会话里一律拒绝（reason
+ * `adapter-method-unknown`）：宁可少转发，不可误转发——
+ * `test/adapter-better-sidebar.test.cjs` 会把两版源码里的实际方法名集合
+ * 提取出来求并集，与这张表逐一比对，防止插件升级后漏记。
+ *
+ * 0.26.0 相对 0.25.0 的差异（本表如何覆盖两版）：
+ *  - 新增 `fs.readPage` 与 sidechat 的 `dequeue`/`model`/`models` 三个；
+ *  - `fs.write` 从 JSON api 移除，改走新的 `/sidebar/write` HTTP 路由
+ *    （内容作纯文本 POST 体，见 index.ts 的路由条目）。表里保留
+ *    `fs.write`：0.25.0 的宿主仍从 JSON api 派发它；0.26.0 的客户端
+ *    不再调它，登记无害。
  *
  * 会话字段：绝大多数方法在 JSON 体顶层带 `sessionId`（client.js 的
  * scopePayload，lib/client.js:3866）；子代理与工作流面板带
@@ -70,7 +79,7 @@ export interface SidebarMethodSpec {
 /** 无改写的普通转发方法的简写工厂。 */
 const forward = (kind: 'read' | 'write', sessionField: 'sessionId' | 'rootSessionId' | 'childId' = 'sessionId'): SidebarMethodSpec => ({ kind, sessionField })
 
-/** 0.25.0 的全部方法。 */
+/** 两版（0.25.0 + 0.26.0）方法名的并集，各条目的处置见上。 */
 export const SIDEBAR_METHODS: Readonly<Record<string, SidebarMethodSpec>> = {
   // ---- 会话（lib/index.js:6319-6333）----
   'session.phase': forward('read'),
@@ -86,6 +95,11 @@ export const SIDEBAR_METHODS: Readonly<Record<string, SidebarMethodSpec>> = {
   'fs.trees': forward('read'),
   'fs.search': forward('read'),
   'fs.read': forward('read'),
+  // 分页读（0.26.0 lib/index.js:7332-7338）：payload 形状同 fs.read 加
+  // 顶层 `offset` 数字；响应是文件文本，不带会话 id —— 不改写。
+  'fs.readPage': forward('read'),
+  // 0.26.0 起从 JSON api 移除（写内容改走 /sidebar/write 路由，见
+  // index.ts）；保留给 0.25.0 的宿主——0.26.0 的客户端不再派发它。
   'fs.write': forward('write'),
   'fs.rename': forward('write'),
   'fs.mkdir': forward('write'),
@@ -171,6 +185,15 @@ export const SIDEBAR_METHODS: Readonly<Record<string, SidebarMethodSpec>> = {
   'sidechat.dispose': forward('write', 'childId'),
   'sidechat.info': forward('read', 'childId'),
   'sidechat.events': forward('read', 'childId'),
+  // 撤回排队消息（0.26.0 lib/index.js:6206-6226）：childId 定位，可选
+  // `messageId`；响应 {accepted, removed} 不带会话 id —— 不改写。
+  'sidechat.dequeue': forward('write', 'childId'),
+  // 模型目录（0.26.0 lib/index.js:6228）：handler 不收 payload、无会话
+  // 字段 → local（settings.* 先例），登记只为「未知方法」比对。
+  'sidechat.models': { kind: 'read', local: true },
+  // 给线程切模型（0.26.0 lib/index.js:6229-6245）：childId 定位；响应
+  // {accepted, selection} 不带会话 id —— 不改写。
+  'sidechat.model': forward('write', 'childId'),
 }
 
 /** `/sidebar/api` 的路径前缀（方法名跟在后面，lib/index.js:6888）。 */

package/src/intercept.ts

@@ -84,6 +84,7 @@ import type { RelayClient, RelayClock, RelayState } from './relay-client.js'
 import { checkGatewayShape } from './intercept-shape.js'
 import type { GatewayShapeCheck } from './intercept-shape.js'
 import { fromVirtual, isVirtual, toVirtual } from './virtual-id.js'
+import { INVOKE_BINARY_RESULT_METHODS, extractResultAttachments, restoreInvokeBinary, type ResultAttachment } from './invoke-binary.js'
 import {
   createControlMerger,
   createWorkspaceMerger,
@@ -240,7 +241,7 @@ export const CLIENT_METHOD_FIELDS: Readonly<Record<string, readonly SessionField
  * envelope WE construct carries `details: {}` (the host rpcFailure's
  * fallback). */
 export type DispatchEnvelope =
-  | { ok: true; value: unknown }
+  | { ok: true; value: unknown; attachments?: ResultAttachment[] }
   | { ok: false; error: { code: string; message?: string; details: Record<string, unknown> } }
 
 /**
@@ -2699,7 +2700,26 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
       // The session answered: any closed-session entry for it is stale
       // (re-shared and served again) — the banner may go.
       clearClosed(virtuals)
-      return { ok: true, value: rewriteResult(endpoint, value, serverId) }
+      // 2026-10-14: a binary-result method's answer arrives marker-encoded
+      // (invoke-binary.ts) — the relay's JSON channel cannot carry a typed
+      // array, so the server marked it and the caller's own zod validation
+      // needs the real Uint8Array back.
+      const restored = INVOKE_BINARY_RESULT_METHODS.has(endpoint) ? restoreInvokeBinary(value) : value
+      // 2026-10-14 (root cause, live-probed): dispatchRpc's envelope contract
+      // carries Uint8Arrays in the ATTACHMENTS side channel (dsh-api-gateway
+      // encodeRpcResult) — value positions become null and the renderer
+      // re-attaches by path. A raw typed array in the value dies on the
+      // background→browser bridge (JSON), which is exactly the remote image
+      // preview's "expected Uint8Array" zod failure. Restore, then re-extract.
+      if (INVOKE_BINARY_RESULT_METHODS.has(endpoint)) {
+        const extracted = extractResultAttachments(restored)
+        return {
+          ok: true,
+          value: rewriteResult(endpoint, extracted.value, serverId),
+          ...(extracted.attachments.length > 0 ? { attachments: extracted.attachments } : {}),
+        }
+      }
+      return { ok: true, value: rewriteResult(endpoint, restored, serverId) }
     } catch (error) {
       const code = error instanceof RelayError ? error.code : 'internal'
       recordFailure(endpoint, code)

package/src/invoke-binary.ts

@@ -0,0 +1,134 @@
+/**
+ * invoke 二进制载荷的线上标记（2026-10-14 修复）：`v1/invoke` 是纯 JSON
+ * 通道，而 `workspaceFiles/readBytes` 的结果带 `data: Uint8Array`——直接
+ * `JSON.stringify` 会把 typed array 打成普通对象，子客户端侧的 zod 校验
+ * （expected "Uint8Array"）当场拒绝，远程会话的图片预览报「读取失败」。
+ *
+ * 两端共用同一份规则：服务端在应答前对已知二进制方法的结果做深度标记
+ * （typed array → `{ $zr-u8: <base64> }`），子客户端在 forwardInvoke 拿回
+ * 值后还原成真 `Uint8Array`。两端都按同一个 `INVOKE_BINARY_RESULT_METHODS`
+ * 常量开关——单一来源，不可能漂移（这是登记表同步硬约束之外的第三张
+ * 「小表」，但它只此一处定义）。
+ *
+ * 纯逻辑：不 import DSH、不碰 I/O。
+ */
+
+/** 标记键。线上只会出现服务端写入的标记；客户端只认这个键。 */
+export const BINARY_MARKER = '$zr-u8'
+
+/** 结果里带二进制的方法（`namespace/method`）。请求侧参数不带二进制
+ * （readBytes 的参数是 scope/paths），故只有结果方向需要标记。 */
+export const INVOKE_BINARY_RESULT_METHODS: ReadonlySet<string> = new Set(['workspaceFiles/readBytes'])
+
+/** 深度上限：与其余 walker（share-store 祖先链、会话引用扫描）一致。 */
+const MAX_DEPTH = 16
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value) && !isTypedArray(value)
+
+const isTypedArray = (value: unknown): value is ArrayBufferView =>
+  ArrayBuffer.isView(value) === true && !(value instanceof DataView)
+
+/** 深度遍历，把 typed array（含 Buffer）换成 `{ $zr-u8: base64 }` 标记。 */
+export function markInvokeBinary(value: unknown, depth = 0): unknown {
+  if (depth >= MAX_DEPTH) return value
+  if (isTypedArray(value)) return { [BINARY_MARKER]: Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString('base64') }
+  if (Array.isArray(value)) {
+    let changed = false
+    const out: unknown[] = []
+    for (const item of value) {
+      const marked = markInvokeBinary(item, depth + 1)
+      if (marked !== item) changed = true
+      out.push(marked)
+    }
+    return changed ? out : value
+  }
+  if (isPlainObject(value)) {
+    let changed = false
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value)) {
+      const marked = markInvokeBinary(item, depth + 1)
+      if (marked !== item) changed = true
+      out[key] = marked
+    }
+    return changed ? out : value
+  }
+  return value
+}
+
+/** 深度遍历，把 `{ $zr-u8: base64 }` 标记还原成 `Uint8Array`。
+ *  标记只会是本模块的 `markInvokeBinary` 写下的（键名即凭据），base64
+ *  恒有效；万一混入同键的怪值，`Buffer.from(..., 'base64')` 的宽容解码
+ *  也不会抛。非标记对象原样返回（同一引用，不惊动浅比较的调用方）。 */
+export function restoreInvokeBinary(value: unknown, depth = 0): unknown {
+  if (depth >= MAX_DEPTH) return value
+  if (Array.isArray(value)) {
+    let changed = false
+    const out: unknown[] = value.map((item) => {
+      const restored = restoreInvokeBinary(item, depth + 1)
+      if (restored !== item) changed = true
+      return restored
+    })
+    return changed ? out : value
+  }
+  if (isPlainObject(value)) {
+    const marked = value[BINARY_MARKER]
+    // 空串也是合法标记（base64 空串 = 0 字节，mark 自己写下的）；
+    // 只排除非字符串与带兄弟键的诱饵形状。
+    if (typeof marked === 'string' && Object.keys(value).length === 1) {
+      return new Uint8Array(Buffer.from(marked, 'base64'))
+    }
+    let changed = false
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value)) {
+      const restored = restoreInvokeBinary(item, depth + 1)
+      if (restored !== item) changed = true
+      out[key] = restored
+    }
+    return changed ? out : value
+  }
+  return value
+}
+
+/** dispatchRpc 信封的附件旁路形状（dsh-api-gateway 的 encodeRpcResult）：
+ *  Uint8Array 不进 JSON 值，抽到 `attachments: [{path, bytes}]`，原位置
+ *  置 null，渲染层按 path 回填。远程路径必须产出同样的契约，否则
+ *  typed array 在后台→浏览器的桥上被 JSON 压扁（2026-10-14 实机定位）。 */
+export interface ResultAttachment {
+  path: (string | number)[]
+  bytes: Uint8Array
+}
+
+/** 把（已还原的）结果值里的 Uint8Array 抽成附件；值内原位置置 null。
+ *  没有 typed array 时 value 原引用返回、attachments 为空数组。 */
+export function extractResultAttachments(value: unknown): { value: unknown; attachments: ResultAttachment[] } {
+  const attachments: ResultAttachment[] = []
+  const walk = (input: unknown, path: (string | number)[], depth: number): unknown => {
+    if (depth >= MAX_DEPTH) return input
+    if (isTypedArray(input)) {
+      attachments.push({ path, bytes: input as Uint8Array })
+      return null
+    }
+    if (Array.isArray(input)) {
+      let changed = false
+      const out: unknown[] = input.map((item, index) => {
+        const extracted = walk(item, [...path, index], depth + 1)
+        if (extracted !== item) changed = true
+        return extracted
+      })
+      return changed ? out : input
+    }
+    if (isPlainObject(input)) {
+      let changed = false
+      const out: Record<string, unknown> = {}
+      for (const [key, item] of Object.entries(input)) {
+        const extracted = walk(item, [...path, key], depth + 1)
+        if (extracted !== item) changed = true
+        out[key] = extracted
+      }
+      return changed ? out : input
+    }
+    return input
+  }
+  return { value: walk(value, [], 0), attachments }
+}

package/src/relay-server.ts

@@ -48,6 +48,7 @@ import { routeMethodsOf, routeMaxBodyOf } from './plugin-bridge.js'
 import { createPluginTunnel, validatePluginCall, type PluginTunnelRoutes } from './plugin-tunnel.js'
 import type { PluginLoopback } from './plugin-loopback.js'
 import { isLoopbackAuthError } from './plugin-loopback.js'
+import { INVOKE_BINARY_RESULT_METHODS, markInvokeBinary } from './invoke-binary.js'
 import type { NormalizedAdapter, AdapterVerdict } from './plugin-adapter-core.js'
 import { matchAdapterRoute, locateAdapterIds, adapterOwnsRegistryEntry, AdapterMultiValueQueryError } from './plugin-adapter-core.js'
 
@@ -1363,7 +1364,14 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
               : decision.filter === 'model-catalog'
                 ? filterModelCatalogResult(value)
                 : value
-        responseJson(res, 200, { ok: true, value: travels })
+        // 2026-10-14: a binary-result method (workspaceFiles/readBytes) cannot
+        // ride JSON.stringify — typed arrays collapse into plain objects and
+        // the sub-client's own zod validation rejects the answer (remote image
+        // preview: "expected Uint8Array"). The marker round-trip
+        // (invoke-binary.ts) is restored on the client half (intercept.ts).
+        const wire =
+          INVOKE_BINARY_RESULT_METHODS.has(`${namespace}/${method}`) ? markInvokeBinary(travels) : travels
+        responseJson(res, 200, { ok: true, value: wire })
       } catch (error) {
         // The gateway's own failures (unknown namespace, absent service) are
         // business answers, not transport errors: they ride a 200 envelope