dsh-plugin-mobile-gateway 0.7.2 → 0.7.4

package/lib/index.mjs

@@ -128,7 +128,9 @@ import crypto from 'node:crypto'
 import Schema from '@deepseek-ai/schemastery'
 import { WebSocketServer } from 'ws'
 import devicesModule from './devices.js'
-import { createDshHostAdapter } from './dsh-host-adapter.mjs'
+import { createDshHostAdapter, DSH_VERSION, SESSION_FORMAT_VERSION } from './dsh-host-adapter.mjs'
+import { createSessionFollower } from './session-follower.mjs'
+import { createGatewayState, GATEWAY_MODES } from './gateway-state.mjs'
 import QRCode from 'qrcode'
 
 const { createRegistry } = devicesModule
@@ -201,6 +203,10 @@ const Config = Schema.object({
   path: Schema.string().default(DEFAULT_WS_PATH),
   requireAuth: Schema.boolean().default(true),
   gatewayEnabled: Schema.boolean().default(false),
+  gatewayMode: Schema.union(GATEWAY_MODES),
+  gatewayStateFile: Schema.string().default(''),
+  gatewayName: Schema.string().default(''),
+  endpoints: Schema.array(Schema.string()).default([]),
   gatewayWaitTimeoutMs: Schema.natural().min(30_000).max(30 * 60 * 1000).default(DEFAULT_GATEWAY_WAIT_TIMEOUT_MS),
   maxPayloadBytes: Schema.natural().min(1024 * 1024).max(160 * 1024 * 1024).default(DEFAULT_MAX_WS_PAYLOAD_BYTES),
   fileDownloadsEnabled: Schema.boolean().default(true),
@@ -259,7 +265,10 @@ function imagesOf(blocks) {
 // Build the small, owned JSON wire record for one session event. Reads only
 // leaf fields of the live SessionEvent — never serializes live objects.
 function buildWireEvent(session, event) {
-  const base = { kind: 'event', sessionId: String(session.id), seq: event.seq, time: event.time }
+  const base = { kind: 'event', sessionId: String(session.id), seq: event.seq, time: event.time,
+    ...(event.surfaceOp === undefined ? {} : { surfaceOp: event.surfaceOp }),
+    ...(event.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: event.sourceEventSeqs }),
+  }
   const d = event.data || {}
   switch (event.type) {
     case 'user/message': {
@@ -273,15 +282,6 @@ function buildWireEvent(session, event) {
         },
       })
     }
-    case 'assistant/chunk': {
-      const chunk = d.chunk || {}
-      const ev = { type: 'assistant/chunk', turn: d.turn, step: d.step, chunkType: chunk.type }
-      if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') ev.text = chunk.text
-      if (chunk.type === 'tool-call-delta') ev.tool = { id: chunk.id, name: chunk.name, argumentsDelta: chunk.argumentsDelta }
-      if (chunk.type === 'usage') ev.usage = chunk.usage
-      if (chunk.type === 'finish') ev.finish = { kind: chunk.reason && chunk.reason.kind }
-      return Object.assign(base, { event: ev })
-    }
     case 'assistant/message': {
       const blocks = (d.message && d.message.content) || []
       let text = ''
@@ -295,9 +295,15 @@ function buildWireEvent(session, event) {
         else if (block.type === 'tool-call') toolCalls.push({ id: block.id, name: block.name, arguments: block.arguments })
       }
       return Object.assign(base, {
-        event: { type: 'assistant/message', turn: d.turn, step: d.step, text, reasoning, toolCalls, ...(images.length ? { images } : {}) },
+        event: { type: 'assistant/message', turn: d.turn, step: d.step, text, reasoning, toolCalls,
+          ...(d.interrupted === true ? { interrupted: true } : {}),
+          ...(d.usage === undefined ? {} : { usage: d.usage }),
+          ...(images.length ? { images } : {}),
+        },
       })
     }
+    case 'assistant/attempt':
+      return Object.assign(base, { event: { type: event.type, turn: d.turn, step: d.step, stream: d.stream } })
     case 'session/title':
       return Object.assign(base, {
         event: {
@@ -324,7 +330,7 @@ function buildWireEvent(session, event) {
           turn: d.turn,
           step: d.step,
           callId: d.message && d.message.source && d.message.source.callId,
-          isError: !!d.error,
+          isError: !!d.error || ((d.message && d.message.content) || []).some(block => block?.type === 'tool-result' && block.isError === true),
           preview,
         },
       })
@@ -474,7 +480,7 @@ async function admitCommand(host, msg) {
     if (!descriptor) {
       return { kind: 'error', code: 'unknown-command', message: `command not found: /${name}`, requestType: 'command-execute', sessionId: sessionId.value }
     }
-    if (parsedImages.value.length > 0 && descriptor.input?.images !== true) {
+    if (parsedImages.value.length > 0 && !commandAcceptsAttachments(descriptor)) {
       return { kind: 'error', code: 'bad-request', message: `/${name} does not accept image attachments`, requestType: 'command-execute', sessionId: sessionId.value }
     }
     return executeHostCommand(host, sessionId.value, line, parsedImages.value, 'command-execute')
@@ -1032,8 +1038,15 @@ function trimConversationEvent(event) {
   switch (event.type) {
     case 'assistant/chunk':
     case 'request/header':
+    case 'request/context':
+    case 'system/message':
       // token-level replay / system-prompt header: not rendered on the chat page
       return null
+    case 'assistant/message':
+    case 'assistant/attempt': {
+      const { stream, ...data } = event.data || {}
+      return { ...event, data }
+    }
     case 'tool/result': {
       const d = event.data || {}
       const message = d.message
@@ -1083,12 +1096,46 @@ function capHistoryEvents(events, maxBytes, trim) {
   return { events: processed.slice(keptStart), bytes: total, dropped: keptStart }
 }
 
+function validateHistoryCursor(msg, sessionId, field) {
+  if (msg[field] === undefined && msg.historyFormatVersion === undefined) return null
+  if (msg.historyFormatVersion !== SESSION_FORMAT_VERSION) {
+    return { kind: 'error', code: 'history-format-mismatch', requestType: msg.type, sessionId,
+      historyFormatVersion: SESSION_FORMAT_VERSION, resetRequired: true,
+      message: 'Reload the Session baseline before using a history or fork cursor; historyFormatVersion must be 3' }
+  }
+  if (msg[field] !== undefined && (!Number.isSafeInteger(msg[field]) || msg[field] < 0)) {
+    return { kind: 'error', code: 'bad-request', requestType: msg.type, sessionId,
+      message: `${field} must be a non-negative safe integer` }
+  }
+  return null
+}
+
+function historyPage(value, msg) {
+  const rawEvents = value.events.map(entry => entry.event)
+  const maxBytes = Number.isSafeInteger(msg.maxBytes) && msg.maxBytes > 0 ? msg.maxBytes : HISTORY_DEFAULT_MAX_BYTES
+  const trim = msg.view === 'conversation'
+  const capped = capHistoryEvents(rawEvents, maxBytes, trim)
+  const hasMore = value.hasMore === true || capped.dropped > 0
+  // An all-hidden page still needs a cursor so callers can reach older text.
+  const oldest = capped.events[0]?.seq ?? rawEvents[0]?.seq
+  return { ...value, kind: 'history', sessionId: msg.sessionId,
+    events: capped.events, bytes: capped.bytes, hasMore,
+    ...(trim ? { view: 'conversation' } : {}),
+    ...(hasMore && oldest !== undefined ? { nextBeforeSeq: oldest } : {}),
+  }
+}
+
 function resolveCommandCatalogCopy(locale) {
   return typeof locale === 'string' && !locale.toLowerCase().startsWith('zh')
     ? COMMAND_CATALOG_COPY.en
     : COMMAND_CATALOG_COPY.zh
 }
 
+// DSH 0.1.5-rc.2 command descriptors use input.attachments.
+function commandAcceptsAttachments(command) {
+  return command?.input?.attachments === true
+}
+
 function commandUiDescriptor(command, copy) {
   const override = COMMAND_UI_OVERRIDES[command.name]
   if (override) return { ...override, insertText: `/${command.name}` }
@@ -1099,7 +1146,7 @@ function commandUiDescriptor(command, copy) {
       insertText: `/${command.name} `,
       hint: command.input.hint,
       ...(displayHint ? { displayHint } : {}),
-      images: command.input.images === true,
+      images: commandAcceptsAttachments(command),
       submitRequest: 'command-execute',
     }
   }
@@ -1274,33 +1321,13 @@ async function handleQuery(api, host, agentDefaultModel, msg) {
     if (!sessionId) {
       return { kind: 'error', code: 'bad-request', message: 'history requires a sessionId', requestType: 'history' }
     }
+    const cursorError = validateHistoryCursor(msg, sessionId, 'beforeSeq')
+    if (cursorError) return cursorError
     const payload = { sessionId }
     if (typeof msg.beforeSeq === 'number' && Number.isFinite(msg.beforeSeq)) payload.beforeSeq = msg.beforeSeq
     if (typeof msg.maxMessages === 'number' && Number.isFinite(msg.maxMessages)) payload.maxMessages = msg.maxMessages
     const frame = await proxyQuery(api, 'history', api.sessions.history.bind(api.sessions), payload)
-    if (frame.kind === 'history') {
-      // Scheme A base: pass the raw SessionEvent list through (drop the host
-      // render intent); keep the projections block and echo the sessionId.
-      const rawEvents = Array.isArray(frame.events) ? frame.events.map((entry) => entry.event) : []
-      // Byte budget + optional conversation trim — keeps the frame under the
-      // client's WebSocket limit and pages the rest via nextBeforeSeq.
-      const maxBytes = typeof msg.maxBytes === 'number' && Number.isFinite(msg.maxBytes) && msg.maxBytes > 0
-        ? Math.floor(msg.maxBytes)
-        : HISTORY_DEFAULT_MAX_BYTES
-      const trim = msg.view === 'conversation'
-      const capped = capHistoryEvents(rawEvents, maxBytes, trim)
-      frame.events = capped.events
-      frame.sessionId = sessionId
-      frame.bytes = capped.bytes
-      if (trim) frame.view = 'conversation'
-      // hasMore combines the host's message-count pagination with byte-drop.
-      const apiHasMore = frame.hasMore === true
-      const byteDropped = capped.dropped > 0
-      frame.hasMore = apiHasMore || byteDropped > 0
-      if (frame.hasMore && capped.events.length > 0) {
-        frame.nextBeforeSeq = capped.events[0].seq // oldest kept event: page back from here
-      }
-    }
+    if (frame.kind === 'history') return historyPage(frame, { ...msg, sessionId })
     return frame
   }
   if (msg.type === 'attachment') {
@@ -1358,6 +1385,8 @@ async function handleQuery(api, host, agentDefaultModel, msg) {
   if (msg.type === 'fork') {
     const sessionId = requireSessionId(msg)
     if (sessionId.error) return sessionId.error
+    const cursorError = validateHistoryCursor(msg, sessionId.value, 'atSeq')
+    if (cursorError) return cursorError
     const payload = { sessionId: sessionId.value }
     if (typeof msg.atSeq === 'number' && Number.isFinite(msg.atSeq)) payload.atSeq = Math.floor(msg.atSeq)
     const frame = await proxyQuery(api, 'fork', api.sessions.fork.bind(api.sessions), payload)
@@ -1510,7 +1539,7 @@ async function handleQuery(api, host, agentDefaultModel, msg) {
           action: 'execute',
           ui: commandUiDescriptor(command, copy),
           ...(command.input && typeof command.input.hint === 'string'
-            ? { input: { hint: command.input.hint, ...(command.input.images === true ? { images: true } : {}) } }
+            ? { input: { hint: command.input.hint, ...(commandAcceptsAttachments(command) ? { images: true } : {}) } }
             : {}),
         }))
       if (!commands.some((command) => command.name === 'model')) {
@@ -1845,11 +1874,13 @@ function normalizePublicUrl(value, req, wsPath) {
     const host = req.headers.host || `127.0.0.1`
     raw = `${req.socket && req.socket.encrypted ? 'wss' : 'ws'}://${host}${wsPath}`
   }
-  const url = new URL(raw)
+  let url
+  try { url = new URL(raw) } catch { throw badRequest('invalid WebSocket endpoint URL') }
   if (url.protocol === 'https:') url.protocol = 'wss:'
   if (url.protocol === 'http:') url.protocol = 'ws:'
   if (url.protocol !== 'ws:' && url.protocol !== 'wss:') throw badRequest('publicUrl must use wss:// (ws:// is allowed only for localhost and private LAN addresses)')
   if (url.username || url.password || url.search || url.hash) throw badRequest('publicUrl must not contain credentials, query parameters, or a fragment')
+  if (['0.0.0.0', '[::]', '::'].includes(url.hostname)) throw badRequest('endpoint must not use an unspecified listen address')
   if (url.protocol === 'ws:' && !isPrivateNetworkHostname(url.hostname)) throw badRequest('publicUrl must use wss:// outside localhost or a private LAN')
   return url.toString()
 }
@@ -1882,8 +1913,12 @@ function readBody(req) {
         reject(error)
         return
       }
-      try { resolve(data === '' ? {} : JSON.parse(data)) } catch (cause) {
-        const error = new Error('request body must be valid JSON', { cause })
+      try {
+        const body = data === '' ? {} : JSON.parse(data)
+        if (!body || typeof body !== 'object' || Array.isArray(body)) throw new TypeError('expected an object')
+        resolve(body)
+      } catch (cause) {
+        const error = new Error('request body must be a JSON object', { cause })
         error.status = 400
         reject(error)
       }
@@ -1974,6 +2009,9 @@ const plugin = {
       path: DEFAULT_WS_PATH,
       requireAuth: true,
       gatewayEnabled: false,
+      gatewayStateFile: '',
+      gatewayName: '',
+      endpoints: [],
       gatewayWaitTimeoutMs: DEFAULT_GATEWAY_WAIT_TIMEOUT_MS,
       maxPayloadBytes: DEFAULT_MAX_WS_PAYLOAD_BYTES,
       fileDownloadsEnabled: true,
@@ -2006,6 +2044,17 @@ const plugin = {
     let requireAuth = options.requireAuth !== false
     const adminLoopbackOnly = options.adminLoopbackOnly !== false
     const deviceFile = options.deviceFile || path.join(os.homedir(), '.dsh', 'mobile-gateway-devices.json')
+    if (options.gatewayMode !== undefined && !GATEWAY_MODES.includes(options.gatewayMode)) throw new Error('invalid gatewayMode')
+    if (typeof options.gatewayName !== 'string' || options.gatewayName.trim().length > 80) throw new Error('gatewayName must be at most 80 characters')
+    const normalizeEndpoints = (values) => {
+      if (!Array.isArray(values) || values.length > 16 || values.some((value) => typeof value !== 'string' || !value.trim() || value.length > 2048)) {
+        throw badRequest('endpoints must be an array of at most 16 nonempty URLs (2048 characters each)')
+      }
+      return [...new Set(values.map((value) => normalizePublicUrl(value, { headers: {} }, wsPath)))]
+    }
+    const configuredEndpoints = normalizeEndpoints(options.endpoints)
+    const gatewayState = createGatewayState(options.gatewayStateFile || `${deviceFile}.gateway.json`)
+    const gatewayIdentity = { gatewayId: gatewayState.gatewayId, gatewayName: options.gatewayName.trim() || os.hostname().slice(0, 80) }
     const registry = createRegistry(deviceFile, { pairingTtlMs: options.pairingTtlMs })
     const wss = new WebSocketServer({
       noServer: true,
@@ -2028,8 +2077,10 @@ const plugin = {
     const backgroundStreamAbort = new AbortController()
     let archivedSessionIds = null
     let sessionQueues = null
+    let sessionProjectionBaselines = {}
     let counter = 0
-    let gatewayEnabled = options.gatewayEnabled === true
+    let gatewayMode = gatewayState.mode ?? options.gatewayMode ?? (options.gatewayEnabled === true ? 'persistent' : 'disabled')
+    let gatewayEnabled = gatewayMode !== 'disabled'
     let waitExpiresAt = null
     let waitTimer = null
     let connectedSinceEnabled = false
@@ -2053,25 +2104,44 @@ const plugin = {
       }
     }
 
-    const setGatewayEnabled = (enabled, reason) => {
+    const advertisedEndpoints = (primary, extra = []) => {
+      const publicUrl = configuredPublicUrl()
+      return normalizeEndpoints([...new Set([
+        ...(primary ? [primary] : []),
+        ...extra,
+        ...configuredEndpoints,
+        ...(publicUrl ? [publicUrl] : []),
+        ...(lanListening ? lanWebSocketUrls(options, wsPath, lanBoundPort) : []),
+      ])])
+    }
+
+    const setGatewayMode = (mode, reason, persist = true) => {
+      if (!GATEWAY_MODES.includes(mode)) throw badRequest('mode must be disabled, temporary, or persistent')
+      // Commit before changing the live service, so a failed save never reports success.
+      if (persist) gatewayState.setMode(mode)
       if (waitTimer) clearTimeout(waitTimer)
       waitTimer = null
-      gatewayEnabled = enabled
+      gatewayMode = mode
+      gatewayEnabled = mode !== 'disabled'
       waitExpiresAt = null
-      connectedSinceEnabled = false
-      if (enabled) {
+      connectedSinceEnabled = [...clients].some((client) => client.readyState === 1)
+      if (mode === 'temporary' && !connectedSinceEnabled) {
         waitExpiresAt = Date.now() + options.gatewayWaitTimeoutMs
         waitTimer = setTimeout(() => {
           waitTimer = null
-          if (!gatewayEnabled || connectedSinceEnabled || clients.size > 0) return
+          if (!gatewayEnabled || connectedSinceEnabled || [...clients].some((client) => client.readyState === 1)) return
           gatewayEnabled = false
+          gatewayMode = 'disabled'
           waitExpiresAt = null
+          try { gatewayState.setMode('disabled') } catch (error) {
+            log(`failed to persist automatic gateway disable: ${error.message}`)
+          }
           log('mobile gateway automatically disabled: no device connected before timeout')
         }, options.gatewayWaitTimeoutMs)
-      } else {
+      } else if (mode === 'disabled') {
         for (const client of clients) client.close(4004, 'mobile gateway disabled')
       }
-      log(`mobile gateway ${enabled ? 'enabled' : 'disabled'}${reason ? `: ${reason}` : ''}`)
+      log(`mobile gateway mode=${mode}${reason ? `: ${reason}` : ''}`)
     }
 
     const logAuthRejected = (req) => {
@@ -2303,12 +2373,8 @@ const plugin = {
       }
     }
 
-    // Startup-config enablement (gatewayEnabled: true in cordis.patch.yml) is a
-    // standing-service decision made by the operator: do NOT arm the no-device
-    // auto-close. That safety net stays attached to the ephemeral panel toggle,
-    // where it belongs. gatewayEnabled is already true from options at this point,
-    // so nothing else is needed here beyond the log line.
-    if (gatewayEnabled) log('mobile gateway enabled by startup config: standing mode, no auto-close timer')
+    // Saved user choice wins; a temporary startup gets a fresh first-connection window.
+    setGatewayMode(gatewayMode, 'startup', false)
 
     log(`applying: version=${PLUGIN_VERSION} interactionProtocol=${INTERACTION_PROTOCOL_REVISION} path=${wsPath}, webServer.port=${webServer.port}, gatewayEnabled=${gatewayEnabled}, requireAuth=${requireAuth}, devices=${registry.count()}`)
 
@@ -2333,6 +2399,9 @@ const plugin = {
               version: PLUGIN_VERSION,
               requireAuth,
               gatewayEnabled,
+              gatewayMode,
+              ...gatewayIdentity,
+              endpoints: advertisedEndpoints(),
               waitExpiresAt,
               connectedClients: clients.size,
               webPort: webServer.port,
@@ -2364,9 +2433,10 @@ const plugin = {
             sendJson(res, 200, result)
           } else if (req.method === 'POST' && p === '/mgw/gateway') {
             const body = await readBody(req)
-            if (typeof body.enabled !== 'boolean') throw badRequest('enabled must be a boolean')
-            setGatewayEnabled(body.enabled, 'changed from management UI')
-            sendJson(res, 200, { gatewayEnabled, waitExpiresAt, connectedClients: clients.size })
+            if (body.mode !== undefined && body.enabled !== undefined) throw badRequest('provide mode or enabled, not both')
+            if (body.mode === undefined && typeof body.enabled !== 'boolean') throw badRequest('mode or boolean enabled is required')
+            setGatewayMode(body.mode !== undefined ? body.mode : (body.enabled ? 'temporary' : 'disabled'), 'changed from management UI')
+            sendJson(res, 200, { gatewayEnabled, gatewayMode, waitExpiresAt, connectedClients: clients.size })
           } else if (req.method === 'POST' && p === '/mgw/auth') {
             const body = await readBody(req)
             if (typeof body.enabled !== 'boolean') throw badRequest('enabled must be a boolean')
@@ -2393,12 +2463,15 @@ const plugin = {
             const body = await readBody(req)
             const name = typeof body.name === 'string' ? body.name : undefined
             const publicUrl = normalizePublicUrl(body.publicUrl || configuredPublicUrl(), req, wsPath)
+            const endpoints = advertisedEndpoints(publicUrl, normalizeEndpoints(body.endpoints ?? []))
             const pairing = registry.createPairing(name)
             const payload = {
               version: 2,
               publicUrl,
               pairingCode: pairing.code,
               expiresAt: pairing.expiresAt,
+              ...gatewayIdentity,
+              endpoints,
             }
             // QR/manual pairing has one canonical wire representation: the
             // UTF-8 JSON payload encoded as unpadded Base64URL. Base64URL is
@@ -2491,6 +2564,26 @@ const plugin = {
             log('mobile gateway wait completed: device connected')
           }
 
+          const sendFrame = frame => {
+            if (ws.readyState === 1) ws.send(JSON.stringify(frame))
+          }
+          ws.sessionFollower = createSessionFollower(api, {
+            onFrame(frame, context) {
+              if (frame.type === 'snapshot') {
+                sendFrame({ ...historyPage(frame.history, { sessionId: context.sessionId, view: 'conversation' }),
+                  kind: 'session-snapshot', ...context, assistantStream: frame.assistantStream, replace: true })
+              } else if (frame.type === 'event') {
+                sendFrame({ ...buildWireEvent({ id: context.sessionId }, frame.event), ...context })
+              } else {
+                sendFrame({ kind: 'assistant-stream', ...context, frame: frame.frame })
+              }
+            },
+            onError(error, context) {
+              sendFrame({ kind: 'session-stream-reset', ...context,
+                code: error.code || 'stream-interrupted', message: error.message })
+            },
+          })
+
           ws.on('message', (data) => {
             let msg
             try {
@@ -2510,12 +2603,32 @@ const plugin = {
             if (msg.type === 'ping') {
               ws.send(JSON.stringify({ kind: 'pong', at: Date.now() }))
             } else if (msg.type === 'subscribe') {
-              ws.filterSessionId = typeof msg.sessionId === 'string' ? msg.sessionId : undefined
-              ws.send(JSON.stringify({ kind: 'subscribed', sessionId: ws.filterSessionId || null }))
+              if (msg.assistantStream !== undefined && typeof msg.assistantStream !== 'boolean') {
+                sendFrame({ kind: 'error', code: 'bad-request', requestType: 'subscribe', message: 'assistantStream must be a boolean' })
+                return
+              }
+              const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() ? msg.sessionId.trim() : undefined
+              if (msg.assistantStream === true && !sessionId) {
+                sendFrame({ kind: 'error', code: 'bad-request', requestType: 'subscribe', message: 'assistantStream requires a sessionId' })
+                return
+              }
+              ws.sessionFollower.stop()
+              ws.filterSessionId = sessionId
+              ws.sessionFollowerActive = msg.assistantStream === true
+              const subscriptionId = crypto.randomUUID()
+              sendFrame({ kind: 'subscribed', sessionId: sessionId || null, subscriptionId, assistantStream: ws.sessionFollowerActive })
+              if (ws.sessionFollowerActive) {
+                void ws.sessionFollower.start(sessionId, subscriptionId).catch(error => {
+                  log(`session follower failed: ${error.message}`)
+                  if (ws.readyState === 1) ws.close(1011, 'session follower failed')
+                })
+              }
               replayPendingInteractions(ws, 'subscribe')
             } else if (msg.type === 'unsubscribe') {
+              ws.sessionFollower.stop()
+              ws.sessionFollowerActive = false
               ws.filterSessionId = undefined
-              ws.send(JSON.stringify({ kind: 'subscribed', sessionId: null }))
+              sendFrame({ kind: 'subscribed', sessionId: null, assistantStream: false })
             } else if (msg.type === 'question-answer' || msg.type === 'question-cancel') {
               respondToQuestion(msg, msg.type === 'question-cancel').then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
@@ -2553,6 +2666,7 @@ const plugin = {
           })
 
           ws.on('close', () => {
+            ws.sessionFollower.stop()
             clients.delete(ws)
             if (ws.deviceId) registry.disconnected(ws.deviceId)
             releaseUnclaimedInteractions()
@@ -2568,13 +2682,20 @@ const plugin = {
               kind: 'paired',
               token: paired.token,
               device: paired.device,
+              ...gatewayIdentity,
             }))
           }
           ws.send(JSON.stringify({
             kind: 'hello',
+            ...gatewayIdentity,
             protocol: 3,
+            dshVersion: DSH_VERSION,
+            historyFormatVersion: SESSION_FORMAT_VERSION,
             capabilities: [
               'split-channels',
+              'assistant-stream-v1',
+              'history-format-version',
+              'projection-baseline',
               'images',
               'session-create',
               'commands',
@@ -2597,6 +2718,9 @@ const plugin = {
           if (ws.mobileChannel !== 'conversation' && sessionQueues !== null) {
             ws.send(JSON.stringify({ kind: 'session-queues', queues: Object.fromEntries(sessionQueues) }))
           }
+          if (ws.mobileChannel !== 'conversation') {
+            sendFrame({ kind: 'projection-baseline', projections: sessionProjectionBaselines })
+          }
           replayPendingInteractions(ws, 'connect')
         })
     }
@@ -2666,7 +2790,7 @@ const plugin = {
       }
       const payload = JSON.stringify(wire)
       for (const client of clients) {
-        if (client.mobileChannel === 'control') continue
+        if (client.mobileChannel === 'control' || client.sessionFollowerActive) continue
         if (client.filterSessionId && client.filterSessionId !== String(session.id)) continue
         if (client.readyState === 1) client.send(payload)
       }
@@ -2799,6 +2923,33 @@ const plugin = {
       log(`session queue forwarded: session=${sessionId} items=${items.length}`)
     }
 
+    const projectionFrame = (sessionId, key, value, seq) => ({
+      kind: key === 'todos' ? 'tasks-updated' : 'goal-updated', sessionId, asOfSeq: seq,
+      [key]: value,
+    })
+
+    const installProjectionBaseline = value => {
+      if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid projection baseline')
+      const next = {}
+      for (const [sessionId, baseline] of Object.entries(value)) {
+        if (!Number.isSafeInteger(baseline?.asOfSeq) || !baseline.values || typeof baseline.values !== 'object' || Array.isArray(baseline.values)) {
+          throw new Error('invalid session projection baseline')
+        }
+        Object.defineProperty(next, sessionId, { enumerable: true, configurable: true, writable: true,
+          value: { asOfSeq: baseline.asOfSeq, values: { todos: baseline.values.todos ?? null, goal: baseline.values.goal ?? null } } })
+      }
+      const previous = sessionProjectionBaselines
+      sessionProjectionBaselines = next
+      broadcastSessionMetadataFrame({ kind: 'projection-baseline', projections: next })
+      for (const sessionId of new Set([...Object.keys(previous), ...Object.keys(next)])) {
+        const baseline = Object.hasOwn(next, sessionId) ? next[sessionId] : null
+        for (const key of ['todos', 'goal']) {
+          broadcastInteractionFrame(projectionFrame(sessionId, key, baseline?.values[key] ?? null,
+            baseline?.asOfSeq ?? previous[sessionId].asOfSeq))
+        }
+      }
+    }
+
     const workspaceTask = (async () => {
       while (!backgroundStreamAbort.signal.aborted) {
         try {
@@ -2827,19 +2978,16 @@ const plugin = {
           const stream = await api.openControlStream(backgroundStreamAbort.signal)
           for await (const frame of stream) {
             if (frame?.type === 'baseline') {
+              installProjectionBaseline(frame.value?.projections)
               installSessionQueueBaseline(frame.value?.queues)
             } else if (frame?.type === 'queue') {
               installSessionQueue(frame.sessionId, frame.items)
             } else if (frame?.type === 'projection' && (frame.key === 'todos' || frame.key === 'goal')) {
               const sessionId = String(frame.sessionId)
-              const kind = frame.key === 'todos' ? 'tasks-updated' : 'goal-updated'
-              const valueKey = frame.key === 'todos' ? 'todos' : 'goal'
-              broadcastInteractionFrame({
-                kind,
-                sessionId,
-                asOfSeq: frame.seq,
-                [valueKey]: frame.value,
-              })
+              const previous = Object.hasOwn(sessionProjectionBaselines, sessionId) ? sessionProjectionBaselines[sessionId] : null
+              Object.defineProperty(sessionProjectionBaselines, sessionId, { enumerable: true, configurable: true, writable: true,
+                value: { asOfSeq: frame.seq, values: { ...previous?.values, [frame.key]: frame.value } } })
+              broadcastInteractionFrame(projectionFrame(sessionId, frame.key, frame.value, frame.seq))
               log(`projection forwarded: key=${frame.key} session=${sessionId} seq=${frame.seq}`)
             }
           }
@@ -2870,7 +3018,10 @@ const plugin = {
       disposeQuestions()
       disposeApprovals()
       if (lanServer) lanServer.close()
-      for (const client of clients) client.terminate()
+      for (const client of clients) {
+        client.sessionFollower?.stop()
+        client.terminate()
+      }
       clients.clear()
       wss.close()
       log('plugin stopped, all sockets closed')