dsh-zen-remote 2.0.3 → 2.2.1

package/src/activity.ts

@@ -160,6 +160,38 @@ export function createParentIndex(): ParentIndex {
   }
 }
 
+/** One persisted-session snapshot as `SessionPersistence.list()` hands it
+ * back: the detached header is all the parent index needs (`id`,
+ * `origin: 'subagent'`, `parentSession` — dsh-session's SessionHeader).
+ * Structural on purpose: the service's full snapshot carries revision and
+ * sizes we do not care about. */
+export interface PersistedSessionSnapshot {
+  header?: { id?: unknown; origin?: unknown; parentSession?: unknown } | undefined
+}
+
+/**
+ * Seed a parent index from persisted-session snapshots (2026-10-13 fix):
+ * the index otherwise rebuilds only from LIVE `session/event` traffic, so
+ * after a host restart every already-stored sidechat / subagent child lost
+ * its parent link and the relay answered `not-shared` for sessions whose
+ * share it used to inherit. Feeding `SessionPersistence.list()`'s snapshots
+ * through `observe` restores the chain; it reads headers only, never event
+ * logs. Returns how many parent links the pass recorded.
+ */
+export function seedParentIndexFromSnapshots(index: ParentIndex, snapshots: readonly PersistedSessionSnapshot[]): number {
+  let recorded = 0
+  for (const snapshot of snapshots) {
+    const header = snapshot?.header
+    if (header?.origin !== 'subagent') continue
+    const id = header.id
+    if (typeof id !== 'string') continue
+    const isNew = index.parentOf(id) === undefined
+    index.observe({ id, header })
+    if (isNew && index.parentOf(id) !== undefined) recorded += 1
+  }
+  return recorded
+}
+
 /** Duck-typed timer halves: Node's setInterval/clearInterval at runtime,
  * fakes in tests. Loose on purpose — the real NodeJS.Timeout type would
  * fight the contravariant `clearInterval` parameter under strictFunctionTypes. */

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

@@ -0,0 +1,144 @@
+/**
+ * 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
+ * silently drifted version.
+ *
+ * Product decisions (2026-10-10): reads AND writes both forward — a
+ * bridged better-sidebar is whole-server disk access, git writes, and
+ * 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).
+ *
+ * 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.
+ */
+
+import type { BridgeAdapter } from '../types.js'
+import { isVirtual } from '../../virtual-id.js'
+import { SIDEBAR_METHODS, sidebarMethodNameOf } from './methods.js'
+
+/** The relay's upload budget (`MAX_UPLOAD_BYTES` in lib/relay-server.js).
+ * Inlined rather than imported — an adapter may only lean on pure utility
+ * modules — and pinned to the original by a test in
+ * test/adapter-better-sidebar.test.cjs, which fails the pair apart when
+ * either side moves. */
+const RELAY_UPLOAD_CAP_BYTES = 100 * 1024 * 1024
+
+/** better-sidebar's own JSON body bound (lib/index.js:863
+ * `MAX_BODY_BYTES = 1 << 20`) — the adapter forwards at most what the
+ * backend would accept anyway. */
+const SIDEBAR_MAX_BODY_BYTES = 1024 * 1024
+
+/** The method name out of a `/sidebar/api/*` pathname, or `''`. */
+const apiMethodOf = (pathname: string): string => sidebarMethodNameOf(pathname) ?? ''
+
+export const dshBetterSidebarAdapter: BridgeAdapter = {
+  plugin: 'dsh-better-sidebar',
+  versions: ['0.25.0'],
+  routes: [
+    {
+      // The JSON API: the method name rides the path tail, the session
+      // fields ride the body top level (sessionId / rootSessionId /
+      // childId — the sidechat calls).
+      path: '/sidebar/api',
+      match: 'prefix',
+      methods: ['POST'],
+      maxBody: SIDEBAR_MAX_BODY_BYTES,
+      locator: { in: 'json-body', fields: ['sessionId', 'rootSessionId', 'childId'] },
+      deny: ({ pathname, currentSessionId }) => {
+        const name = apiMethodOf(pathname)
+        if (name === '') return undefined
+        // Opening apps/URLs on the HOST is a remote-panel no: refused when
+        // the browser is currently looking at a REMOTE session (the
+        // request body carries no session field of its own — client.js
+        // 9383-9392 — so the classify step could never tell). A LOCAL
+        // session's open.external never reaches here as a refusal and
+        // stays on the local machine, exactly as without zen-remote.
+        // (The sidechat methods left this hook in PB-13: their child
+        // sessions inherit the parent's share through `meta.parentSession`,
+        // so they forward like everything else.)
+        if (name === 'open.external' && currentSessionId !== undefined && isVirtual(currentSessionId)) {
+          return 'remote-open-unsupported'
+        }
+        return undefined
+      },
+    },
+    // The media route: better-sidebar registers a PREFIX, the adapter only
+    // claims the EXACT documented path — a sub-path (if a future version
+    // grows one) stays local rather than being guessed at.
+    { path: '/sidebar/file', match: 'exact', methods: ['GET'], locator: { in: 'query', name: 'sessionId' } },
+    // The archive download (lib/index.js:6949-6985).
+    { path: '/sidebar/archive', match: 'exact', methods: ['GET'], locator: { in: 'query', name: 'sessionId' } },
+    // 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 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
+    // along (they hit the same prefix route with the same segment layout).
+    { path: '/sidebar/html', match: 'prefix', methods: ['GET'], locator: { in: 'path-segment', index: 0 } },
+    // Lazy chunks: client code, session-independent, LOCAL forever.
+    { path: '/sidebar/bundle', match: 'prefix', methods: ['GET'], locator: { in: 'query', name: 'sessionId' }, local: true },
+    // The two WebSockets (PB-13, both `registerUpgrade` EXACT registrations
+    // in lib/index.js:7066-7091): the agent-opens push feed and the
+    // file-tree watch. Both carry the session id in the query; both ride
+    // PB-10's byte tunnel untouched — neither side parses frames, and the
+    // messages need no rewriting (agent-opens pushes carry the server-real
+    // sessionId but the browser never reads it — client.js:23618-23640
+    // uses its own connect-time id for the scope; fs-watch frames carry
+    // file paths, not session ids).
+    { path: '/sidebar/ws/agent-opens', match: 'exact', methods: ['GET'], upgrade: true, locator: { in: 'query', name: 'sessionId' } },
+    { path: '/sidebar/ws/fs-watch', match: 'exact', methods: ['GET'], upgrade: true, locator: { in: 'query', name: 'sessionId' } },
+  ],
+  client: {
+    request: (ctx) => {
+      const name = apiMethodOf(ctx.pathname)
+      // Belt over the deny hook's suspenders: a refused method refuses
+      // even if a future plugin version starts carrying session fields
+      // on it (which would flip it into the remote branch).
+      if (name === 'open.external') return { allow: false, reason: 'remote-open-unsupported' }
+      // Unknown method: refuse — never guess what a drifted version means.
+      if (name !== '' && SIDEBAR_METHODS[name] === undefined) return { allow: false, reason: 'adapter-method-unknown' }
+      return { allow: true }
+    },
+    response: (ctx) => {
+      const name = apiMethodOf(ctx.pathname)
+      if (name === '') return ctx.body
+      const spec = SIDEBAR_METHODS[name]
+      if (spec === undefined || spec.rewrite === undefined) return ctx.body
+      return spec.rewrite(ctx.body, ctx)
+    },
+  },
+  server: {
+    request: (ctx) => {
+      // Strip the client-supplied cwd: the backend resolves the working
+      // 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.query.get('cwd') !== null) {
+          const stripped = new URLSearchParams(ctx.query)
+          stripped.delete('cwd')
+          return { allow: true, query: stripped }
+        }
+        return { allow: true }
+      }
+      if (ctx.route.path === '/sidebar/api' && ctx.body !== null && typeof ctx.body === 'object' && !Array.isArray(ctx.body) && 'cwd' in (ctx.body as Record<string, unknown>)) {
+        const stripped = { ...(ctx.body as Record<string, unknown>) }
+        delete stripped.cwd
+        return { allow: true, body: stripped }
+      }
+      return { allow: true }
+    },
+  },
+}

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

@@ -0,0 +1,244 @@
+/**
+ * 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` 会把源码里的实际方法
+ * 名集合提取出来与这张表逐一比对，防止插件升级后漏记。
+ *
+ * 会话字段：绝大多数方法在 JSON 体顶层带 `sessionId`（client.js 的
+ * scopePayload，lib/client.js:3866）；子代理与工作流面板带
+ * `rootSessionId`；sidechat 的后续调用带 `childId`（本单一律拒绝）。
+ *
+ * 响应里带会话 id 的位置（核实于 0.25.0 源码，全部只有三处）：
+ *  - `session.cwd` 把请求的 `sessionId` 原样回显（lib/index.js:6327）；
+ *  - `subagents.live` 的响应以会话 id 为键（lib/index.js:4513
+ *    `live[sessionId] = view`，根会话与全部子会话）；
+ *  - `workflows.list` 的每行 `originSessionId`（lib/index.js:4666）与
+ *    `phases[].members[].childId`（lib/index.js:4686）。
+ * `teams.taskCreate`/`taskUpdate` 的响应是 `{ok, value:<任务记录>}`
+ * （lib/index.js:4607-4612、4650-4655），任务记录不带会话 id；
+ * `changes.ops` 返回 `{events, lastSeq}`，事件属于该会话自身的流
+ * （tool/call、tool/result），对象上没有会话 id 字段；
+ * `archive.build` 返回 `{id, entries}`（lib/index.js:3470-3473）、
+ * `archive.status` 返回 `{state, done, total, bytes, error?}`
+ * （lib/index.js:3479-3485）——都不带会话 id。这四类不改写。
+ * `sidechat.start` 返回 `{childId}`（lib/index.js:5050）——PB-13 起
+ * 虚拟化（子客户端拿它发后续调用）。
+ *
+ * 信封：`/sidebar/api` 的成功响应**全部**是 `{ok:true, value:<handler
+ * 返回值>}`（lib/index.js:889-896 的 `writeOk`），上面引用的行号都是
+ * handler 层、不是线上形状——响应改写器一律经 `rewriteEnveloped` 先剥
+ * 信封再改写再包回去（2026-10-13 修复：sidechat.start 的 childId 曾在
+ * 顶层找不到而漏虚拟化，浏览器拿真实 id 发后续调用被判本地、落到子
+ * 客户端本机报 session not found）。
+ */
+
+/** 响应改写器的上下文（框架的 AdapterResponseContext 的结构性子集）。 */
+export interface SidebarRewriteContext {
+  virtualize(id: string): string
+  isVirtual(value: unknown): boolean
+}
+
+/** 改写信封内的 value（信封外层的 ok 等字段原样保留）。 */
+type SidebarInnerRewrite = (value: unknown, ctx: SidebarRewriteContext) => unknown
+
+/** 剥 `{ok:true, value}` 信封 → 改写 value → 包回去；无信封原样改写。
+ *  `writeOk`（lib/index.js:889）给每个 /sidebar/api 成功响应都包了这层。 */
+function rewriteEnveloped(body: unknown, inner: SidebarInnerRewrite, ctx: SidebarRewriteContext): unknown {
+  if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+    const record = body as Record<string, unknown>
+    if (record.ok === true && record.value !== null && typeof record.value === 'object' && !Array.isArray(record.value)) {
+      return { ...record, value: inner(record.value, ctx) }
+    }
+  }
+  return inner(body, ctx)
+}
+
+/** 一个 `/sidebar/api` 方法的处置。 */
+export interface SidebarMethodSpec {
+  /** 该方法在 JSON 体顶层的会话字段名（settings.* 无会话字段，缺省）。 */
+  sessionField?: 'sessionId' | 'rootSessionId' | 'childId'
+  /** 读还是写（写方法在远程会话里执行的是主服务端的磁盘与 git）。 */
+  kind: 'read' | 'write'
+  /** 无会话数据的方法（settings.*）：定位结果为空，天然留本机。 */
+  local?: true
+  /** 响应改写器：把响应里的真实会话 id 换回虚拟 id。 */
+  rewrite?: (body: unknown, ctx: SidebarRewriteContext) => unknown
+}
+
+/** 无改写的普通转发方法的简写工厂。 */
+const forward = (kind: 'read' | 'write', sessionField: 'sessionId' | 'rootSessionId' | 'childId' = 'sessionId'): SidebarMethodSpec => ({ kind, sessionField })
+
+/** 0.25.0 的全部方法。 */
+export const SIDEBAR_METHODS: Readonly<Record<string, SidebarMethodSpec>> = {
+  // ---- 会话（lib/index.js:6319-6333）----
+  'session.phase': forward('read'),
+  'session.cwd': {
+    kind: 'read',
+    sessionField: 'sessionId',
+    // 请求的 sessionId 原样回显（lib/index.js:6327）。
+    rewrite: (body, ctx) => rewriteEnveloped(body, (v) => rewriteTopLevel(v, 'sessionId', ctx), ctx),
+  },
+
+  // ---- 文件（lib/index.js:6334-6442）----
+  'fs.tree': forward('read'),
+  'fs.trees': forward('read'),
+  'fs.search': forward('read'),
+  'fs.read': forward('read'),
+  'fs.write': forward('write'),
+  'fs.rename': forward('write'),
+  'fs.mkdir': forward('write'),
+  'fs.createFile': forward('write'),
+  'fs.remove': forward('write'),
+
+  // ---- git（lib/index.js:6443-6613）----
+  'git.worktrees': forward('read'),
+  'git.status': forward('read'),
+  'git.diff': forward('read'),
+  'git.diff-head': forward('read'),
+  'git.branch': forward('read'),
+  'git.log': forward('read'),
+  'git.commit-diff': forward('read'),
+  'git.show': forward('read'),
+  'git.blame': forward('read'),
+  'git.stage': forward('write'),
+  'git.unstage': forward('write'),
+  'git.commit': forward('write'),
+  'git.push': forward('write'),
+  'git.pull': forward('write'),
+  'git.checkout': forward('write'),
+  'git.discard': forward('write'),
+  'git.revert': forward('write'),
+  'git.cherry-pick': forward('write'),
+  // 提交信息生成：消耗主服务端的模型额度（产品决定：跟随会话，接）。
+  'git.suggest-message': forward('write'),
+  // 模型目录：sessionId 可选（lib/index.js:6573-6602、6614-6626）。
+  'git.commit-model': forward('read'),
+  'git.models': forward('read'),
+
+  // ---- 变更流（lib/index.js:6627-6649）----
+  // 事件对象属于该会话自身的流，不带会话 id —— 不改写。
+  'changes.ops': forward('read'),
+
+  // ---- 子代理 / 工作流 / 团队（lib/index.js:4482-4662、4770-4789）----
+  'subagents.live': {
+    kind: 'read',
+    sessionField: 'rootSessionId',
+    // 响应的 live 映射以会话 id 为键（lib/index.js:4513）。
+    rewrite: (body, ctx) => rewriteEnveloped(body, rewriteLiveKeys, ctx),
+  },
+  'workflows.list': {
+    kind: 'read',
+    sessionField: 'rootSessionId',
+    // 每行的 originSessionId（4666）与 members[].childId（4686）。
+    rewrite: (body, ctx) => rewriteEnveloped(body, rewriteWorkflowsBody, ctx),
+  },
+  // 响应是 {ok, value:<任务记录>}，不带会话 id —— 不改写。
+  'teams.taskCreate': forward('write', 'rootSessionId'),
+  'teams.taskUpdate': forward('write', 'rootSessionId'),
+
+  // ---- 归档（lib/index.js:6663-6686；响应不带会话 id）----
+  'archive.build': forward('write'),
+  'archive.status': forward('read'),
+
+  // ---- 设置（lib/index.js:6666-6682）----
+  // 无会话字段：定位结果为空，远程判定天然放行本机 —— 表里登记只为
+  // 文档完整与「未知方法」比对（真实存在，只是不转发）。
+  'settings.get': { kind: 'read', local: true },
+  'settings.update': { kind: 'write', local: true },
+
+  // ---- 外部打开（lib/index.js:6683-6687）----
+  // 在宿主机起进程：远程会话拒绝（适配器路由的 deny 钩子按「浏览器当前
+  // 会话是虚拟 id」拒绝；这里登记是让方法比对认识它）。请求体不带会话
+  // 字段（client.js:9383-9392 只发 action/path/url）。
+  'open.external': { kind: 'write', sessionField: 'sessionId' },
+
+  // ---- 侧聊（lib/index.js:4971-5140，buildSidechatApi）----
+  // PB-13 起转发：sidechat 的子会话带 `meta.parentSession = 调用会话 id`
+  // （lib/index.js:5012），zen-remote 的共享按祖先链判定，所以侧聊线程
+  // 自动继承父会话的共享——闭环是 start 的响应 childId 换成虚拟 id，
+  // 浏览器拿它发后续调用时经体定位回本适配器，服务端按继承校验放行。
+  'sidechat.start': {
+    kind: 'write',
+    sessionField: 'sessionId',
+    // 响应 `{ childId }`（lib/index.js:5050，外面还有 writeOk 信封）——
+    // 服务端真实 id 换虚拟。
+    rewrite: (body, ctx) => rewriteEnveloped(body, (v) => rewriteTopLevel(v, 'childId', ctx), ctx),
+  },
+  'sidechat.prompt': forward('write', 'childId'),
+  'sidechat.cancel': forward('write', 'childId'),
+  'sidechat.dispose': forward('write', 'childId'),
+  'sidechat.info': forward('read', 'childId'),
+  'sidechat.events': forward('read', 'childId'),
+}
+
+/** `/sidebar/api` 的路径前缀（方法名跟在后面，lib/index.js:6888）。 */
+export const SIDEBAR_API_PREFIX = '/sidebar/api/'
+
+/** 从请求 pathname 取出 API 方法名（`/sidebar/api/fs.tree` → `fs.tree`）。 */
+export function sidebarMethodNameOf(pathname: string): string | undefined {
+  if (!pathname.startsWith(SIDEBAR_API_PREFIX)) return undefined
+  const name = pathname.slice(SIDEBAR_API_PREFIX.length)
+  if (name === '' || name.includes('/')) return undefined
+  return name
+}
+
+/** 顶层字段的虚拟化改写（session.cwd 的形状）。 */
+function rewriteTopLevel(body: unknown, field: string, ctx: SidebarRewriteContext): unknown {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) return body
+  const record = body as Record<string, unknown>
+  const value = record[field]
+  if (typeof value !== 'string' || value === '' || ctx.isVirtual(value)) return body
+  return { ...record, [field]: ctx.virtualize(value) }
+}
+
+/** subagents.live 的 value（信封内）：live 映射的键是会话 id。 */
+function rewriteLiveKeys(value: unknown, ctx: SidebarRewriteContext): unknown {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value
+  const live = (value as Record<string, unknown>).live
+  if (live === null || typeof live !== 'object' || Array.isArray(live)) return value
+  const rewritten: Record<string, unknown> = {}
+  for (const [id, view] of Object.entries(live as Record<string, unknown>)) {
+    rewritten[ctx.isVirtual(id) ? id : ctx.virtualize(id)] = view
+  }
+  return { ...(value as Record<string, unknown>), live: rewritten }
+}
+
+/** workflows.list 的 value（信封内）：runs[].originSessionId 等。 */
+function rewriteWorkflowsBody(value: unknown, ctx: SidebarRewriteContext): unknown {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value
+  const runs = (value as Record<string, unknown>).runs
+  if (!Array.isArray(runs)) return value
+  return {
+    ...(value as Record<string, unknown>),
+    runs: runs.map((run) => rewriteWorkflowRun(run, ctx)),
+  }
+}
+
+/** 一行工作流运行的改写（originSessionId + phases[].members[].childId）。 */
+function rewriteWorkflowRun(run: unknown, ctx: SidebarRewriteContext): unknown {
+  if (run === null || typeof run !== 'object' || Array.isArray(run)) return run
+  const record = run as Record<string, unknown>
+  const rewritten: Record<string, unknown> = { ...record }
+  const origin = record.originSessionId
+  if (typeof origin === 'string' && origin !== '' && !ctx.isVirtual(origin)) rewritten.originSessionId = ctx.virtualize(origin)
+  if (Array.isArray(record.phases)) {
+    rewritten.phases = record.phases.map((phase) => {
+      if (phase === null || typeof phase !== 'object' || Array.isArray(phase)) return phase
+      const phaseRecord = phase as Record<string, unknown>
+      if (!Array.isArray(phaseRecord.members)) return phase
+      return {
+        ...phaseRecord,
+        members: phaseRecord.members.map((member) => {
+          if (member === null || typeof member !== 'object' || Array.isArray(member)) return member
+          const memberRecord = member as Record<string, unknown>
+          const childId = memberRecord.childId
+          if (typeof childId !== 'string' || childId === '' || ctx.isVirtual(childId)) return member
+          return { ...memberRecord, childId: ctx.virtualize(childId) }
+        }),
+      }
+    })
+  }
+  return rewritten
+}

package/src/adapters/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The adapter registry — the ONE door between `src/adapters/` and the rest
+ * of the plugin. Every adapter implementation lives in its own
+ * subdirectory (`src/adapters/<plugin-name>/`), is imported here, and adds
+ * exactly one element to the array. Nothing outside `src/index.ts` (the
+ * wiring) may import from this directory, and no file anywhere may import
+ * an adapter subdirectory — both pinned by test/adapters-pluggable.test.cjs.
+ * Deleting this whole directory leaves the plugin fully working: the wiring
+ * parameter defaults to `[]`.
+ *
+ * PB-11 ships the FRAMEWORK only: the array stays EMPTY, the first real
+ * adapter (better-sidebar) arrives with PB-12.
+ */
+
+import type { BridgeAdapter } from './types.js'
+import { dshBetterSidebarAdapter } from './dsh-better-sidebar/index.js'
+
+/** Every adapter zen-remote ships, in registration order. */
+export const ADAPTERS: readonly BridgeAdapter[] = [dshBetterSidebarAdapter]

package/src/adapters/types.ts

@@ -0,0 +1,44 @@
+/**
+ * The adapter-author face of the plugin bridge's adapter framework
+ * (PB-11). An adapter is zen-remote-internal code for ONE third-party
+ * plugin at its EXACT version: it declares which of that plugin's routes
+ * carry a session id and WHERE, and — optionally — hooks the two ends to
+ * refuse, strip or rewrite what the pure id relocation cannot express.
+ * Everything here sits on the framework shapes from
+ * `../plugin-adapter-core.js`; the framework itself never imports this
+ * file (only `src/index.ts` imports the ADAPTERS array from
+ * `./adapters/index.js`), which is what makes the whole directory
+ * removable without touching any other feature.
+ *
+ * An adapter implementation may import `types.ts` and pure utilities such
+ * as `../virtual-id.js` — nothing else.
+ */
+
+import type { AdapterRoute, AdapterRequestContext, AdapterResponseContext, AdapterVerdict } from '../plugin-adapter-core.js'
+
+export type { AdapterRoute, AdapterRequestContext, AdapterResponseContext, AdapterVerdict }
+
+/** One pluggable adapter. `versions` lists the EXACT plugin versions this
+ * adapter was written against — the installed version must be among them
+ * or the adapter does not register at all (a best-guess rewrite against a
+ * moving schema is how ids get corrupted). A plugin that registers its OWN
+ * cooperative declaration always wins; the adapter yields. */
+export interface BridgeAdapter {
+  /** The target plugin's npm package name. */
+  plugin: string
+  /** The checked exact versions; an installed version outside this list
+   * means "not adapted". */
+  versions: readonly string[]
+  routes: readonly AdapterRoute[]
+  /** The sub-client half: rewrite or refuse on the way OUT to the relay,
+   * and map the answer's real session ids back to virtual form. */
+  client?: {
+    request?(ctx: AdapterRequestContext): AdapterVerdict
+    response?(ctx: AdapterResponseContext): unknown
+  }
+  /** The main-server half: refuse or strip (e.g. a `cwd` field) before
+   * the loopback reaches the plugin. */
+  server?: {
+    request?(ctx: AdapterRequestContext): AdapterVerdict
+  }
+}

package/src/admin-routes.ts

@@ -41,6 +41,7 @@ import { request as httpRequest } from 'node:http'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ConfigSource, ZenRemoteConfig } from './config.js'
 import { responseJson, sameOriginPost } from './http.js'
+import type { BridgeRegistry } from './plugin-bridge.js'
 import type { RelayGateway } from './relay-server.js'
 import { restoreBusy } from './share-ops.js'
 import type { AgentStatusLike } from './share-ops.js'
@@ -66,6 +67,10 @@ export const ADMIN_PUSH_TEST_ROUTE = `${ADMIN_ROUTE_PREFIX}/push-test`
  * POST `{action, sessionId?}`: share / unshare / unshare-all (T33a). */
 export const ADMIN_SHARES_ROUTE = `${ADMIN_ROUTE_PREFIX}/shares`
 
+/** GET: the plugin bridge's registered plugins with their whole-machine-data
+ * consent, for the settings page's 插件桥 section (PB-5). */
+export const ADMIN_PLUGIN_BRIDGE_ROUTE = `${ADMIN_ROUTE_PREFIX}/plugin-bridge`
+
 /** Longest wait for one gateway round-trip. */
 const GATEWAY_TIMEOUT_MS = 5000
 
@@ -161,6 +166,18 @@ export interface AdminHandlerOptions {
    * durable header through it to judge subagent sessions; absent (or a
    * failing read) falls back to the projection identity. */
   sessionQuery?: () => SessionQueryLike | undefined
+  /** The plugin bridge's server half (PB-5): the declaration registry and
+   * the LIVE consent reader backing the plugin-bridge listing. Absent — a
+   * composition that never built the registry — and the route answers 404
+   * like any unknown admin path. */
+  pluginBridge?: {
+    registry: BridgeRegistry
+    getConsent: () => Record<string, boolean>
+    /** The plugins an ADAPTER currently stands in for (PB-11), read live
+     * per listing — a plugin that registered its own declaration stops
+     * being marked. Absent on a wiring that predates adapters. */
+    adaptedPlugins?: () => ReadonlySet<string>
+  }
 }
 
 /** The slice of the sessionQuery service the share action reads (RT
@@ -574,6 +591,53 @@ export function createAdminHandler(options: AdminHandlerOptions): AdminHandler {
         responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use GET or POST' } })
         return
       }
+      if (route === ADMIN_PLUGIN_BRIDGE_ROUTE) {
+        // No registry, no route: a composition that never built the plugin
+        // bridge answers like any unknown admin path.
+        if (options.pluginBridge === undefined) {
+          responseJson(res, 404, { ok: false, error: { code: 'not-found', message: 'Unknown admin route' } })
+          return
+        }
+        if (method !== 'GET') {
+          res.setHeader('Allow', 'GET')
+          responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use GET' } })
+          return
+        }
+        // Wall 2, the pair/action rule: this listing feeds a MANAGEMENT
+        // surface (the consent toggles below it), so a request that arrived
+        // through the gateway is refused — consent is granted on the server
+        // machine, by its owner, period.
+        if (req.headers['x-zen-remote-via'] !== undefined) {
+          responseJson(res, 403, {
+            ok: false,
+            error: { code: 'via-gateway', message: '插件桥设置只能在服务端本机操作' },
+          })
+          return
+        }
+        // The consent source is a live row read; a broken one reads as the
+        // empty map (nothing consented) instead of failing the listing.
+        let consent: Record<string, boolean> = {}
+        try {
+          consent = options.pluginBridge.getConsent()
+        } catch {
+          consent = {}
+        }
+        // registry.list() arrives plugin-sorted; the map keeps that order.
+        // PB-11: `adapted` marks the entries an ADAPTER stands in for —
+        // zen-remote-internal forwarding for a plugin that never registered
+        // anything — so the settings page can say「由 zen-remote 适配」.
+        // Absent (a wiring that predates adapters) reads as none.
+        const adapted = options.pluginBridge.adaptedPlugins?.() ?? new Set<string>()
+        const plugins = options.pluginBridge.registry.list().map((declaration) => ({
+          plugin: declaration.plugin,
+          version: declaration.version,
+          hasServerScope: declaration.routes.some((route) => route.scope === 'server'),
+          consent: consent[declaration.plugin] === true,
+          adapted: adapted.has(declaration.plugin),
+        }))
+        responseJson(res, 200, { ok: true, value: { plugins } })
+        return
+      }
       if (route === ADMIN_PAIR_ROUTE || route === ADMIN_ACTION_ROUTE || route === ADMIN_PUSH_TEST_ROUTE) {
         if (method !== 'POST') {
           res.setHeader('Allow', 'POST')