dsh-zen-remote 2.0.3 → 2.2.1

package/src/index.ts

@@ -38,7 +38,7 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 import { readFileConfig, resolveConfig, unwrapVolatile } from './config.js'
-import { createActivityTracker, createParentIndex, startSweeper } from './activity.js'
+import { createActivityTracker, createParentIndex, seedParentIndexFromSnapshots, startSweeper, type PersistedSessionSnapshot } from './activity.js'
 import { ADMIN_ROUTE_PREFIX, createAdminHandler } from './admin-routes.js'
 import type { SessionQueryLike } from './admin-routes.js'
 import { normalizedRowServerUrl } from './client-pairing.js'
@@ -59,8 +59,22 @@ import { checkGatewayShape } from './intercept-shape.js'
 import type { GatewayShapeCheck } from './intercept-shape.js'
 import { checkFetchRouteShape, installFetchRouteIntercept } from './fetch-route-intercept.js'
 import type { FetchRouteInterceptDiagnostics, FetchRouteInterceptHandle, FetchRouteShapeCheck } from './fetch-route-intercept.js'
+import { checkWebServerShape, installPluginRouteIntercept } from './plugin-route-intercept.js'
+import type { PluginRouteInterceptDiagnostics, PluginRouteInterceptHandle, WebServerShapeCheck } from './plugin-route-intercept.js'
+import { normalizeAdapter, adapterOwnsRegistryEntry } from './plugin-adapter-core.js'
+import type { NormalizedAdapter } from './plugin-adapter-core.js'
+import { ADAPTERS } from './adapters/index.js'
 import { createRelayHandler, loadServerId, RELAY_PREFIX, resolveDshVersion } from './relay-server.js'
 import type { RelayGateway, RelayHandler } from './relay-server.js'
+import { createBridgeRegistry, compareBridges } from './plugin-bridge.js'
+import type { BridgeDeclaration, BridgeRegistry, BridgeStatus, ServerPluginEntry, ZenRemoteService } from './plugin-bridge.js'
+import { createPluginLoopback } from './plugin-loopback.js'
+import { createPluginTunnel } from './plugin-tunnel.js'
+
+// The plugin bridge's public types (PB-1), re-exported so another plugin's
+// author can `import type { … } from 'dsh-zen-remote'` without reaching into
+// lib/types. Type-only: no runtime code, no Context augmentation.
+export type { BridgeDeclaration, ZenRemoteService } from './plugin-bridge.js'
 
 // The loader's config schema (settings form) and the role normalizer live in
 // src/config.ts next to the resolution they describe; re-exported so the
@@ -126,6 +140,22 @@ export function getRelayClient(): RelayClient | undefined {
   return clientRelayClient
 }
 
+/**
+ * The plugin bridge's declaration registry (PB-1), created inside apply() on
+ * BOTH roles and kept on the module so later tasks (the handshake's plugins
+ * table, the client-side rewrite) can reach it without reaching into a
+ * context. Undefined in compositions that never ran this module's apply, and
+ * — identity-guarded below — after the row that owned a registry was
+ * unloaded or reloaded, so a reloaded row never leaves a stale table where
+ * the getter can hand it out (the T23a-fix discipline).
+ */
+let bridgeRegistry: BridgeRegistry | undefined
+
+/** The live bridge registry, if a plugin row is currently applied. */
+export function getBridgeRegistry(): BridgeRegistry | undefined {
+  return bridgeRegistry
+}
+
 /** Host half config. Every field below arrives through the loader as a
  * volatile live reference — a `{ get() }` wrapper over the stored value, not
  * the value itself (src/config.ts explains why every field is volatile) — so
@@ -461,6 +491,76 @@ export async function handleUpload(
  */
 export function apply(ctx: Context, config: MobileNavConfig = {}): void {
   const effective = resolveConfig(config, readFileConfig(), process.env)
+  // The plugin bridge's zenRemote service (PB-1), provided on BOTH roles
+  // before any role branch: a plugin that wants its panel data forwarded in
+  // remote sessions declares that against THIS process whichever role it
+  // runs as, and the declaration registry is the one piece of PB-1 both the
+  // server half (handshake plugins table) and the client half (route
+  // rewrite) will read. ctx.provide (cordis 4) registers the service owned
+  // by THIS row's fiber: visible to `inject(['zenRemote'])` dependents once
+  // the row is active, withdrawn when the row unloads — so a composition
+  // without zen-remote never fires those injects and a row reload swaps the
+  // service wholesale. The registry goes into the module slot BEFORE the
+  // provide so this apply's consumers never see a window without it; the
+  // effect's identity guard then clears the slot exactly when THIS row
+  // unloads (a reload installs the new registry before the old disposer
+  // runs, same shape as clientRelayClient). provide() throwing is not worth
+  // failing the row over — the bridge stays off, everything else keeps
+  // working — so it degrades to a warning like the session feeds do.
+  const registry = createBridgeRegistry({
+    warn: (text) => { ctx.logger?.warn('dsh-zen-remote plugin bridge: %s', text) },
+  })
+  bridgeRegistry = registry
+  try {
+    const service: ZenRemoteService = {
+      bridge: (declaration: BridgeDeclaration) => registry.register(declaration),
+    }
+    ctx.provide('zenRemote', service)
+  } catch (error) {
+    ctx.logger?.warn('dsh-zen-remote: cannot provide the "zenRemote" service: %s', message(error))
+  }
+  ctx.effect(() => () => {
+    if (bridgeRegistry === registry) bridgeRegistry = undefined
+  }, 'dsh-zen-remote: plugin bridge registry disposal')
+  // The adapters (PB-11): each one registers ONLY against its target's
+  // EXACT installed version, probed off the host's `pluginPackages` service
+  // (`packageOf(name, ctx.baseUrl)` — verified on 0.2.0-rc.2 to answer
+  // `{name, version, dir, …}` or undefined; any other shape, a missing
+  // service or a probe failure reads as "not installed" and the adapter
+  // stays out). A plugin that registers its OWN cooperative declaration
+  // always wins: the adapter yields at registration time (logged), and the
+  // runtime re-checks the registry digest on every request. Both roles run
+  // this loop — the registry entries drive the handshake table, the bridge
+  // verdicts and the settings listing on either side, while the returned
+  // array feeds the two request halves.
+  const adapters: NormalizedAdapter[] = []
+  {
+    const adapterWarn = (text: string): void => { ctx.logger?.warn('dsh-zen-remote adapter: %s', text) }
+    for (const adapter of ADAPTERS) {
+      try {
+        const holder = ctx as unknown as { get?: (name: string) => unknown; baseUrl?: string }
+        const packages = holder.get?.('pluginPackages') as { packageOf?: (specifier: string, parentURL: string) => unknown } | undefined
+        const found = packages?.packageOf?.(adapter.plugin, holder.baseUrl ?? '') as { version?: unknown } | undefined
+        const installedVersion = found !== null && typeof found === 'object' && typeof (found as { version?: unknown }).version === 'string'
+          ? (found as { version: string }).version
+          : undefined
+        if (installedVersion === undefined || installedVersion === '') {
+          adapterWarn(`${adapter.plugin}: target package (or its version) not found; not registered`)
+          continue
+        }
+        const normalized = normalizeAdapter(adapter, installedVersion)
+        if (registry.get(normalized.plugin) !== undefined) {
+          adapterWarn(`${normalized.plugin}: the plugin registers its own bridge declaration; the adapter yields`)
+          continue
+        }
+        registry.registerNormalized(normalized.declaration)
+        adapters.push(normalized)
+        ctx.logger?.info('dsh-zen-remote adapter: %s adapted at version %s', normalized.plugin, installedVersion)
+      } catch (error) {
+        adapterWarn(`${adapter.plugin} refused: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+  }
   if (effective.values.role === 'host') {
     // A row that switched from client to host must not leave a stale relay
     // client where getRelayClient() can find it (T23a-fix).
@@ -557,6 +657,32 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       const agents = (agentsCtx as Context & { agents: { list(): readonly AgentStatusLike[] } }).agents
       restoreBusy(store, () => agents.list())
     })
+    // Restart repair (2026-10-13): the parent index 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 a session whose share it used to inherit through the
+    // ancestor chain. Seed the index once from the persistence service's
+    // snapshot list — headers only, event logs are never read.
+    try {
+      ctx.inject(['sessionPersistence'], (persistenceCtx) => {
+        const persistence = (persistenceCtx as Context & {
+          sessionPersistence?: { list(): Promise<readonly PersistedSessionSnapshot[]> } | undefined
+        }).sessionPersistence
+        if (persistence === undefined) {
+          ctx.logger.warn('dsh-zen-remote: no sessionPersistence service — pre-restart subagent sessions stay not-shared until they emit an event')
+          return
+        }
+        void persistence
+          .list()
+          .then((snapshots) => {
+            const recorded = seedParentIndexFromSnapshots(parentIndex, snapshots)
+            if (recorded > 0) ctx.logger.info?.('dsh-zen-remote: restored %d persisted parent links', recorded)
+          })
+          .catch((error: unknown) => ctx.logger.warn('dsh-zen-remote cannot seed parent links from persisted sessions: %s', message(error)))
+      })
+    } catch (error) {
+      ctx.logger.warn('dsh-zen-remote cannot listen on "sessionPersistence": %s', message(error))
+    }
     // Settings-surface admin routes (T14). The browser cannot call the
     // gateway's loopback-only admin API from DSH's origin, so the host
     // process re-exposes it same-origin and the handler calls the gateway AS
@@ -597,6 +723,16 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           // composition lacks the service.
           viewerCount: (id) => relayHandler?.viewerCount(id) ?? 0,
           sessionQuery: () => webCtx.reflect.get('sessionQuery') as SessionQueryLike | undefined,
+          // The plugin bridge listing (PB-5): the SAME registry this apply
+          // built and the SAME live consent reader the relay's plugins table
+          // uses — one source of truth per question. PB-11: the listing
+          // marks the plugins an adapter stands in for (live — a plugin
+          // that registered its own declaration stops being marked).
+          pluginBridge: {
+            registry,
+            getConsent: () => resolveConfig(config, readFileConfig(), process.env).values.pluginBridgeConsent,
+            adaptedPlugins: () => new Set(adapters.filter((adapter) => adapterOwnsRegistryEntry(adapter, registry.get(adapter.plugin))).map((adapter) => adapter.plugin)),
+          },
         }),
       }), 'dsh-zen-remote: admin routes')
     })
@@ -645,6 +781,32 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       // ~7 ms per computation against a full registry; a failed compute
       // lands as the empty map inside the relay handler's own guard.
       relayCtx.effect(() => {
+        // The plugin bridge's loopback facts (PB-3), both read PER REQUEST
+        // through the reflection layer: the web server may have restarted on
+        // another port or protocol, and the connection service's
+        // authenticatedUrl — the token-exchange entry the lan-gate wiring
+        // also reads (0.1.1 hosts lack the method entirely) — lives on a
+        // service deliberately NOT in this inject's declaration list (same
+        // reason as getApiFetch above: adding it would keep the whole relay
+        // prefix off compositions that lack it).
+        const getLoopbackTarget = () => {
+          const webServer = relayCtx.reflect.get('webServer') as { protocol?: unknown; port?: unknown } | undefined
+          const port = typeof webServer?.port === 'number' && webServer.port > 0 ? webServer.port : undefined
+          if (port === undefined) throw new Error('the web server exposes no loopback port')
+          return { protocol: webServer?.protocol === 'https:' ? ('https:' as const) : ('http:' as const), port }
+        }
+        const getTokenUrl = () => {
+          const connection = relayCtx.reflect.get('connection') as
+            | { authenticatedUrl?: (base: string) => string | undefined }
+            | undefined
+          if (typeof connection?.authenticatedUrl !== 'function') return undefined
+          const { protocol, port } = getLoopbackTarget()
+          return connection.authenticatedUrl(`${protocol}//127.0.0.1:${port}`)
+        }
+        // One loopback executor for BOTH plugin halves (the HTTP forward and
+        // the PB-10 tunnel): a single cookie cache behind two consumers.
+        const pluginLoopback = createPluginLoopback({ getTarget: getLoopbackTarget, getTokenUrl })
+        const pluginConsent = () => resolveConfig(config, readFileConfig(), process.env).values.pluginBridgeConsent
         const handler = createRelayHandler({
           secret: relaySecret,
           store,
@@ -662,6 +824,43 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
             serverName: () => resolveConfig(config, readFileConfig(), process.env).values.serverName,
             dshVersion: resolveDshVersion(),
             fingerprints: () => computeFingerprints(relayCtx),
+            // PB-2: the plugin bridge table, rebuilt FRESH at every handshake
+            // from the PB-1 registry and the row's consent map — both live:
+            // the registry through this apply's own closure, the consent
+            // through resolveConfig on the SAME row object (a volatile field,
+            // read at use time per the hard constraint, never snapshotted).
+            plugins: () => {
+              const consent = resolveConfig(config, readFileConfig(), process.env).values.pluginBridgeConsent
+              const table: Record<string, ServerPluginEntry> = {}
+              for (const declaration of registry.list()) {
+                table[declaration.plugin] = {
+                  version: declaration.version,
+                  digest: declaration.digest,
+                  serverScopeConsent: consent[declaration.plugin] === true,
+                }
+              }
+              return table
+            },
+          },
+          // PB-3: the forwarding half of the plugin bridge — the registry
+          // this apply built (the zenRemote service's table), the consent
+          // map read LIVE per request (a volatile row field), and the
+          // loopback executor over the wiring's two reflection getters.
+          // PB-10: the WebSocket byte tunnel's server half shares the SAME
+          // loopback (one cookie cache) and the same live consent; its
+          // reachability judgment rides the store directly (the handler's
+          // own isAccessible closure is not visible out here).
+          pluginBridge: {
+            registry,
+            getConsent: pluginConsent,
+            loopback: pluginLoopback,
+            adapters,
+            tunnel: createPluginTunnel({
+              bridge: { registry, getConsent: pluginConsent, loopback: pluginLoopback },
+              getTarget: getLoopbackTarget,
+              isAccessible: (sessionId) => store.isAccessible(sessionId, parentIndex.parentOf),
+              heartbeatMs: 15_000,
+            }),
           },
         })
         const unregister = relayCtx.webServer.register({
@@ -735,6 +934,15 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       computeOwnFingerprints: () => computeFingerprints(ctx),
     })
     clientRelayClient = relayClient
+    // The plugin bridge's live verdict (PB-2), the CLIENT role's job — a host
+    // has no remote sessions of its own to bridge anything into. Computed PER
+    // CALL (never a stored conclusion): the local registry is this apply's
+    // own closure, the server's table is the LAST handshake's `plugins`
+    // (undefined until one succeeded — an old server reads server-too-old),
+    // and `online` is the client's CURRENT state — so a registry change, a
+    // fresh handshake or a link flip shows up at the very next read.
+    const pluginBridgeStatus = (): BridgeStatus[] =>
+      compareBridges(registry.list(), relayClient.handshakeInfo?.plugins, relayClient.state === 'online')
     // A stopped or reloaded row must not leave a stale instance where the
     // module getter can hand it out (T23a-fix), and its reconnect machinery
     // (T43) must not outlive the row either: stop() cancels the armed retry
@@ -931,6 +1139,74 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
         if (fetchRouteHandle === handle) fetchRouteHandle = undefined
       }, 'dsh-zen-remote: fetch-route intercept')
     })
+    // The plugin bridge's route interception (PB-4): the local webServer's
+    // `match` wrap forwarding bridged-plugin requests for REMOTE sessions
+    // through the relay. Injected on `webServer` alone — the only service
+    // it reads — and the raw instance comes off the reflection layer's
+    // symbols lookup, the same face the typert and fetch-route wraps use.
+    // The diagnostics flow to the client status route like theirs, refused
+    // installs included.
+    let pluginRouteHandle: PluginRouteInterceptHandle | undefined
+    let pluginRouteRefused: WebServerShapeCheck | undefined
+    const pluginRouteDiagnostics = (): PluginRouteInterceptDiagnostics | undefined => {
+      if (pluginRouteHandle !== undefined) return pluginRouteHandle.diagnostics()
+      if (pluginRouteRefused !== undefined) {
+        return {
+          installed: false,
+          shape: pluginRouteRefused,
+          forwarded: 0,
+          refused: 0,
+          refusalsByReason: {},
+          recentFailures: [],
+          adapterForwarded: 0,
+          adapterResponseRewrites: 0,
+          adapterResponsePassthroughs: 0,
+          tunnelsCurrent: 0,
+          tunnelsOpened: 0,
+          tunnelsClosed: 0,
+        }
+      }
+      return undefined
+    }
+    ctx.inject(['webServer'], (wsCtx) => {
+      const logWarn = (...args: Parameters<Context['logger']['warn']>): void => { ctx.logger?.warn(...args) }
+      const proxy = (wsCtx as Context & { webServer?: unknown }).webServer
+      const raw = proxy !== null && typeof proxy === 'object'
+        ? (proxy as unknown as Record<PropertyKey, unknown>)[symbols.original]
+        : undefined
+      if (raw === null || typeof raw !== 'object') {
+        pluginRouteRefused = { ok: false, reasons: ['original: webServer[symbols.original] is not an object'] }
+        logWarn('dsh-zen-remote plugin-route intercept not installed: %s', pluginRouteRefused.reasons[0])
+        return
+      }
+      // Shape first, like every wrap: a failed check leaves the webServer
+      // exactly as it was — local routing untouched, remote bridging off.
+      const shape = checkWebServerShape(raw)
+      if (!shape.ok) {
+        pluginRouteRefused = shape
+        logWarn('dsh-zen-remote plugin-route intercept not installed: %s', shape.reasons.join('; '))
+        return
+      }
+      const handle = installPluginRouteIntercept({
+        webServer: raw,
+        registry,
+        relay: relayClient,
+        getServerId: () => relayClient.handshakeInfo?.serverId,
+        getStatus: pluginBridgeStatus,
+        adapters,
+        // PB-12: the browser's currently open session — a VIRTUAL id means
+        // a remote panel is the request's origin, the signal the adapter
+        // routes' deny hooks read (better-sidebar's open.external carries
+        // no session field of its own).
+        getCurrentSession: () => (reportedCurrentSession.kind === 'open' ? reportedCurrentSession.sessionId : undefined),
+        log: (format, ...args) => { ctx.logger?.info(`dsh-zen-remote ${format}`, ...args) },
+      })
+      pluginRouteHandle = handle
+      wsCtx.effect(() => () => {
+        handle.uninstall()
+        if (pluginRouteHandle === handle) pluginRouteHandle = undefined
+      }, 'dsh-zen-remote: plugin route intercept')
+    })
     ctx.inject(['webServer', 'connection'], (clientCtx) => {
       clientCtx.effect(() => clientCtx.webServer.register({
         kind: 'prefix',
@@ -941,6 +1217,8 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           getRelayClient: () => relayClient,
           getIntercept: interceptDiagnostics,
           getFetchRouteIntercept: fetchRouteDiagnostics,
+          getPluginRouteIntercept: pluginRouteDiagnostics,
+          getPluginBridgeStatus: pluginBridgeStatus,
           onCurrentSession,
         }),
       }), 'dsh-zen-remote: client routes')