@kinocode/dsh-mobile-bridge 0.0.0-stage → 0.3.2

package/lib/preview.mjs

@@ -0,0 +1,149 @@
+// What a phone may see about a pending request.
+// - `describe` builds the full in-app view (served only to signed devices).
+// - `pushPreview` builds what leaves the computer through the relay and FCM: redacted by default.
+
+const CONTROL_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g
+
+/**
+ * @param {string} text
+ * @param {number} max
+ */
+export function clip(text, max) {
+  const clean = String(text ?? '').replace(CONTROL_CHARS, '').trim()
+  if (clean.length <= max) return clean
+  return `${clean.slice(0, Math.max(0, max - 1))}…`
+}
+
+/**
+ * Human-readable arguments: prefer a shell command, then a path, else compact JSON.
+ * @param {string} raw - tool-call arguments JSON text
+ */
+export function formatArguments(raw) {
+  if (typeof raw !== 'string' || raw === '') return ''
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return raw
+  }
+  if (parsed === null || typeof parsed !== 'object') return String(parsed)
+  for (const key of ['command', 'cmd', 'script']) {
+    const value = parsed[key]
+    if (typeof value === 'string') return value
+    if (Array.isArray(value) && value.every(item => typeof item === 'string')) return value.join(' ')
+  }
+  for (const key of ['path', 'file_path', 'filePath', 'url', 'pattern']) {
+    if (typeof parsed[key] === 'string') return `${key}: ${parsed[key]}`
+  }
+  return JSON.stringify(parsed)
+}
+
+/**
+ * @typedef {object} QuestionView
+ * @property {string} id
+ * @property {string} question
+ * @property {string} header
+ * @property {boolean} multiSelect
+ * @property {string[]} options
+ */
+
+/**
+ * Normalize ask_user_question items from a forwarded request.
+ * @param {unknown} questions
+ * @returns {QuestionView[]}
+ */
+export function questionViews(questions) {
+  if (!Array.isArray(questions)) return []
+  return questions
+    .filter(q => q !== null && typeof q === 'object' && typeof q.id === 'string' && typeof q.question === 'string')
+    .slice(0, 20)
+    .map(q => ({
+      id: q.id,
+      question: clip(q.question, 2000),
+      header: typeof q.header === 'string' ? clip(q.header, 80) : '',
+      multiSelect: q.multiSelect === true,
+      options: Array.isArray(q.options)
+        ? q.options.filter(o => o !== null && typeof o === 'object' && typeof o.label === 'string').slice(0, 20).map(o => clip(o.label, 200))
+        : [],
+    }))
+}
+
+/**
+ * Full view for the in-app inbox.
+ * @param {import('./gateway-client.mjs').PendingEvent} pending
+ * @param {import('./sessions.mjs').SessionTracker} sessions
+ * @param {number} maxChars
+ */
+export function describe(pending, sessions, maxChars) {
+  const request = pending.request
+  const base = {
+    eventId: pending.eventId,
+    kind: pending.kind,
+    sessionId: pending.sessionId,
+    sessionTitle: sessions.title(pending.sessionId),
+    receivedAt: pending.receivedAt,
+  }
+  if (pending.kind === 'approval') {
+    const callId = typeof request.callId === 'string' ? request.callId : undefined
+    const call = sessions.call(pending.sessionId, callId)
+    return {
+      ...base,
+      toolName: typeof request.toolName === 'string' ? request.toolName : '',
+      reason: typeof request.reason === 'string' ? clip(request.reason, 1000) : '',
+      preview: call === undefined ? '' : clip(formatArguments(call.arguments), maxChars),
+      questions: [],
+    }
+  }
+  return { ...base, toolName: 'ask_user_question', reason: '', preview: '', questions: questionViews(request.questions) }
+}
+
+/**
+ * Text that may leave the computer in a push notification.
+ * @param {ReturnType<typeof describe>} view
+ * @param {'redacted'|'full'} mode
+ */
+export function pushPreview(view, mode) {
+  if (view.kind === 'approval') {
+    if (mode !== 'full') return view.toolName
+    return clip(view.preview !== '' ? `${view.toolName}: ${view.preview}` : `${view.toolName} ${view.reason}`, 400)
+  }
+  const first = view.questions[0]
+  if (mode !== 'full' || first === undefined) return first?.header ?? ''
+  return clip(first.question, 400)
+}
+
+/**
+ * Validate an answer value against the pending request.
+ * @param {ReturnType<typeof describe>} view
+ * @param {unknown} value
+ * @returns {unknown} the value to forward
+ * @throws {Error} with `.code = 'invalid_value'`
+ */
+export function validateAnswer(view, value) {
+  const fail = (message) => Object.assign(new Error(message), { code: 'invalid_value' })
+  if (view.kind === 'approval') {
+    if (value === 'allowed-once' || value === 'rejected') return value
+    throw fail('approval value must be "allowed-once" or "rejected"')
+  }
+  if (value === null || typeof value !== 'object' || !Array.isArray(value.answers)) throw fail('answers array required')
+  const byId = new Map(view.questions.map(q => [q.id, q]))
+  const seen = new Set()
+  const answers = value.answers.map((answer) => {
+    if (answer === null || typeof answer !== 'object' || typeof answer.id !== 'string') throw fail('answer id required')
+    const question = byId.get(answer.id)
+    if (question === undefined || seen.has(answer.id)) throw fail('unknown or duplicate question id')
+    seen.add(answer.id)
+    const selected = Array.isArray(answer.selected) ? answer.selected : []
+    if (!selected.every(label => typeof label === 'string' && question.options.includes(label))) throw fail('selected must be option labels')
+    if (new Set(selected).size !== selected.length) throw fail('duplicate selection')
+    if (!question.multiSelect && selected.length > 1) throw fail('single-select question')
+    const out = { id: answer.id, selected }
+    if (answer.custom !== undefined) {
+      if (typeof answer.custom !== 'string' || answer.custom.length > 4000) throw fail('custom must be a string ≤ 4000 chars')
+      if (answer.custom.trim() !== '') out.custom = answer.custom
+    }
+    return out
+  })
+  if (seen.size !== byId.size) throw fail('every question must be answered')
+  return { answers }
+}

package/lib/push.mjs

@@ -0,0 +1,173 @@
+// Decides which phones hear about what, and what text leaves the computer (docs/PROTOCOL.md §6).
+
+import { clip, describe, pushPreview } from './preview.mjs'
+
+const NOTIFIED_TTL_MS = 6 * 60 * 60 * 1000
+const TURN_STATUSES = new Set(['completed', 'error', 'blocked', 'max-tokens', 'aborted', 'interrupted'])
+
+export class Notifier {
+  /**
+   * @param {object} deps
+   * @param {import('./state.mjs').StateStore} deps.state
+   * @param {import('./sessions.mjs').SessionTracker} deps.sessions
+   * @param {() => (import('./relay-tunnel.mjs').RelayTunnel | undefined)} deps.tunnel
+   * @param {number} deps.previewMaxChars
+   * @param {(...args: unknown[]) => void} deps.log
+   * @param {() => number} [deps.now]
+   */
+  constructor(deps) {
+    this.deps = deps
+    this.now = deps.now ?? Date.now
+    /** eventId -> {devices, sessionId, at} so `resolved` reaches exactly the phones that were told. */
+    this.notified = new Map()
+  }
+
+  /** @param {import('./gateway-client.mjs').PendingEvent} pending */
+  async pending(pending) {
+    // The Gateway redelivers open requests after a reconnect; notify once per request.
+    if (this.notified.has(pending.eventId)) return
+    const watchers = this.deps.state.watchers(pending.sessionId)
+    if (watchers.length === 0) {
+      this.deps.log('push: no watching phone', JSON.stringify({ kind: pending.kind, sessionId: pending.sessionId }))
+      return
+    }
+    const view = describe(pending, this.deps.sessions, this.deps.previewMaxChars)
+    const title = view.sessionTitle !== '' ? clip(view.sessionTitle, 80) : 'DeepSeek Harness'
+    const firstQuestion = view.questions[0]
+    const groups = groupByMode(watchers)
+    const told = new Set()
+    for (const [mode, devices] of groups) {
+      /** @type {Record<string, string>} */
+      const data = {
+        v: '1',
+        kind: pending.kind,
+        hostId: this.deps.state.hostId,
+        sessionId: pending.sessionId,
+        eventId: pending.eventId,
+        title,
+        preview: pushPreview(view, mode),
+        createdAt: String(pending.receivedAt),
+      }
+      if (pending.kind === 'approval') data.toolName = clip(view.toolName, 80)
+      if (pending.kind === 'question' && firstQuestion !== undefined) {
+        data.questionId = firstQuestion.id
+        data.multiSelect = String(firstQuestion.multiSelect)
+        const usable = view.questions.length === 1 && !firstQuestion.multiSelect && firstQuestion.options.length > 0 && firstQuestion.options.length <= 3
+        data.options = JSON.stringify(usable ? firstQuestion.options.map(o => clip(o, 40)) : [])
+      }
+      if (await this.send(devices, data, { collapseKey: pending.eventId, ttlSec: 6 * 3600 })) {
+        for (const [id] of devices) told.add(id)
+      }
+    }
+    if (told.size > 0) this.remember(pending.eventId, told, pending.sessionId)
+  }
+
+  /**
+   * Withdraw notifications for a request that is no longer pending.
+   * @param {string} eventId
+   * @param {string} [answeredBy] - device id that answered (it updates its own notification)
+   */
+  async resolved(eventId, answeredBy) {
+    const entry = this.notified.get(eventId)
+    if (entry === undefined) return
+    this.notified.delete(eventId)
+    const devices = [...entry.devices]
+      .filter(id => id !== answeredBy)
+      .map(id => [id, this.deps.state.device(id)])
+      .filter(([, record]) => record?.fcmToken)
+    if (devices.length === 0) return
+    await this.send(devices, {
+      v: '1',
+      kind: 'resolved',
+      hostId: this.deps.state.hostId,
+      sessionId: entry.sessionId,
+      eventId,
+      createdAt: String(this.now()),
+    }, { collapseKey: eventId, ttlSec: 6 * 3600 })
+  }
+
+  /**
+   * Withdraw every notification this process sent for a still-open request, for example when DSH
+   * is quitting and the requests die with it. Best effort; the app also drops notifications that
+   * are missing from `/v1/pending` when it next lists them.
+   */
+  async withdrawAll() {
+    const eventIds = [...this.notified.keys()]
+    await Promise.allSettled(eventIds.map(eventId => this.resolved(eventId)))
+    return eventIds.length
+  }
+
+  /**
+   * @param {string} sessionId
+   * @param {string} reason - TurnEndReason kind
+   */
+  async turnEnded(sessionId, reason) {
+    if (!TURN_STATUSES.has(reason)) return
+    const watchers = this.deps.state.watchers(sessionId)
+    if (watchers.length === 0) {
+      this.deps.log('push: no watching phone', JSON.stringify({ kind: 'turn', sessionId }))
+      return
+    }
+    const title = this.deps.sessions.title(sessionId)
+    for (const [mode, devices] of groupByMode(watchers)) {
+      const text = this.deps.sessions.lastAssistantText(sessionId)
+      await this.send(devices, {
+        v: '1',
+        kind: 'turn',
+        hostId: this.deps.state.hostId,
+        sessionId,
+        eventId: '',
+        status: reason,
+        title: title !== '' ? clip(title, 80) : 'DeepSeek Harness',
+        preview: mode === 'full' ? clip(text, 200) : '',
+        createdAt: String(this.now()),
+      }, { collapseKey: `turn-${sessionId}`, ttlSec: 3600 })
+    }
+  }
+
+  /**
+   * @param {Array<[string, import('./state.mjs').DeviceRecord]>} devices
+   * @param {Record<string, string>} data
+   * @param {{collapseKey?: string, ttlSec?: number}} options
+   */
+  async send(devices, data, options) {
+    const tunnel = this.deps.tunnel()
+    if (tunnel === undefined || !tunnel.connected) {
+      this.deps.log('push skipped: relay not connected', JSON.stringify({ kind: data.kind }))
+      return false
+    }
+    const tokens = devices.map(([, record]) => record.fcmToken).filter(Boolean)
+    const result = await tunnel.push(tokens, data, options)
+    this.deps.log('push', JSON.stringify({ kind: data.kind, devices: tokens.length, ok: result.ok }))
+    if (result.invalidTokens.length > 0) {
+      const invalid = new Set(result.invalidTokens)
+      for (const [id, record] of devices) {
+        if (invalid.has(record.fcmToken)) this.deps.state.updateDevice(id, (r) => { r.fcmToken = null }, true)
+      }
+      this.deps.log('dropped invalid FCM tokens', JSON.stringify({ count: invalid.size }))
+    }
+    return result.ok
+  }
+
+  remember(eventId, devices, sessionId) {
+    const now = this.now()
+    this.notified.set(eventId, { devices, sessionId, at: now })
+    if (this.notified.size > 256) {
+      for (const [id, entry] of this.notified) if (now - entry.at > NOTIFIED_TTL_MS) this.notified.delete(id)
+    }
+  }
+}
+
+/**
+ * @param {Array<[string, import('./state.mjs').DeviceRecord]>} devices
+ * @returns {Map<'redacted'|'full', Array<[string, import('./state.mjs').DeviceRecord]>>}
+ */
+function groupByMode(devices) {
+  const groups = new Map()
+  for (const entry of devices) {
+    const mode = entry[1].previewMode === 'full' ? 'full' : 'redacted'
+    if (!groups.has(mode)) groups.set(mode, [])
+    groups.get(mode).push(entry)
+  }
+  return groups
+}

package/lib/relay-tunnel.mjs

@@ -0,0 +1,256 @@
+// Outbound WebSocket from this computer to the relay (docs/PROTOCOL.md §5).
+// The relay forwards phone control requests over it and asks us nothing else;
+// we send push requests the other way.
+
+import { randomUUID } from 'node:crypto'
+
+const PUSH_TIMEOUT_MS = 15_000
+const HELLO_TIMEOUT_MS = 10_000
+const MAX_FRAME_BYTES = 256 * 1024
+
+/**
+ * @typedef {object} TunnelRequest
+ * @property {string} method
+ * @property {string} path
+ * @property {Record<string, string>} headers
+ * @property {string} body
+ */
+
+export class RelayTunnel {
+  /**
+   * @param {object} options
+   * @param {string} options.relayUrl - https://… base
+   * @param {string} options.hostId
+   * @param {string} options.hostSecret
+   * @param {string} [options.enrollToken]
+   * @param {string} options.label
+   * @param {string} options.version
+   * @param {(request: TunnelRequest) => Promise<{status: number, body: unknown}>} options.handle
+   * @param {(...args: unknown[]) => void} options.log
+   * @param {typeof WebSocket} [options.WebSocketImpl]
+   */
+  constructor(options) {
+    this.options = options
+    this.url = tunnelUrl(options.relayUrl, options.hostId)
+    this.socket = undefined
+    this.open = false
+    /** @type {Map<string, {resolve: Function, timer: NodeJS.Timeout}>} */
+    this.pushes = new Map()
+    this.stopped = false
+  }
+
+  get connected() { return this.open }
+
+  /** @param {AbortSignal} signal */
+  async run(signal) {
+    const WebSocketImpl = this.options.WebSocketImpl ?? await loadWebSocket()
+    let delay = 1000
+    while (!signal.aborted) {
+      const started = Date.now()
+      await this.connectOnce(WebSocketImpl, signal)
+      if (signal.aborted) break
+      if (Date.now() - started > 60_000) delay = 1000
+      const jitter = Math.floor(Math.random() * 500)
+      await sleep(delay + jitter, signal)
+      delay = Math.min(delay * 2, 60_000)
+    }
+    this.failPushes('tunnel stopped')
+  }
+
+  /**
+   * @param {typeof WebSocket} WebSocketImpl
+   * @param {AbortSignal} signal
+   */
+  connectOnce(WebSocketImpl, signal) {
+    return new Promise((resolve) => {
+      let settled = false
+      let socket
+      try {
+        socket = new WebSocketImpl(this.url)
+      } catch (error) {
+        this.options.log('relay connect failed:', error?.message ?? String(error))
+        resolve()
+        return
+      }
+      this.socket = socket
+      const helloTimer = setTimeout(() => {
+        this.options.log('relay hello timed out')
+        try { socket.close(4408, 'hello timeout') } catch { /* already closing */ }
+      }, HELLO_TIMEOUT_MS)
+      const keepAlive = setInterval(() => this.send({ type: 'ping' }), 25_000)
+      const finish = () => {
+        if (settled) return
+        settled = true
+        clearTimeout(helloTimer)
+        clearInterval(keepAlive)
+        signal.removeEventListener('abort', onAbort)
+        this.open = false
+        this.socket = undefined
+        this.failPushes('tunnel closed')
+        resolve()
+      }
+      const onAbort = () => {
+        try { socket.close(1000, 'plugin stopping') } catch { /* already closed */ }
+        finish()
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+      socket.addEventListener('open', () => {
+        socket.send(JSON.stringify({
+          type: 'hello',
+          v: 1,
+          hostId: this.options.hostId,
+          hostSecret: this.options.hostSecret,
+          ...(this.options.enrollToken ? { enrollToken: this.options.enrollToken } : {}),
+          label: this.options.label,
+          plugin: this.options.version,
+        }))
+      })
+      socket.addEventListener('message', (event) => {
+        const raw = typeof event.data === 'string' ? event.data : Buffer.from(event.data).toString('utf8')
+        if (raw.length > MAX_FRAME_BYTES) return
+        let frame
+        try {
+          frame = JSON.parse(raw)
+        } catch {
+          return
+        }
+        if (frame?.type === 'hello-ok') {
+          clearTimeout(helloTimer)
+          this.open = true
+          this.options.log('relay connected')
+          return
+        }
+        if (!this.open) return
+        this.onFrame(frame)
+      })
+      socket.addEventListener('close', (event) => {
+        if (event.code === 4401) this.options.log('relay refused this host (check relayEnrollToken / host secret)')
+        else if (event.code === 4000) this.options.log('relay tunnel replaced by a newer connection')
+        finish()
+      })
+      socket.addEventListener('error', () => { /* close follows */ })
+    })
+  }
+
+  /** @param {any} frame */
+  onFrame(frame) {
+    switch (frame?.type) {
+      case 'request':
+        void this.serve(frame)
+        return
+      case 'push-result': {
+        const waiter = this.pushes.get(frame.id)
+        if (waiter === undefined) return
+        this.pushes.delete(frame.id)
+        clearTimeout(waiter.timer)
+        waiter.resolve({ ok: frame.ok === true, invalidTokens: Array.isArray(frame.invalidTokens) ? frame.invalidTokens : [] })
+        return
+      }
+      case 'ping':
+        this.send({ type: 'pong' })
+        return
+      default:
+    }
+  }
+
+  /** @param {any} frame */
+  async serve(frame) {
+    if (typeof frame.id !== 'string' || typeof frame.method !== 'string' || typeof frame.path !== 'string') return
+    let result
+    try {
+      result = await this.options.handle({
+        method: frame.method,
+        path: frame.path,
+        headers: frame.headers !== null && typeof frame.headers === 'object' ? frame.headers : {},
+        body: typeof frame.body === 'string' ? frame.body : '',
+      })
+    } catch (error) {
+      this.options.log('control handler failed:', error?.message ?? String(error))
+      result = { status: 500, body: { error: 'internal_error' } }
+    }
+    this.send({ type: 'response', id: frame.id, status: result.status, body: JSON.stringify(result.body ?? {}) })
+  }
+
+  /**
+   * Ask the relay to deliver one FCM data message.
+   * @param {string[]} tokens
+   * @param {Record<string, string>} data
+   * @param {{ttlSec?: number, collapseKey?: string}} [options]
+   * @returns {Promise<{ok: boolean, invalidTokens: string[]}>}
+   */
+  push(tokens, data, options = {}) {
+    if (!this.open || tokens.length === 0) return Promise.resolve({ ok: false, invalidTokens: [] })
+    const id = randomUUID()
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.pushes.delete(id)
+        resolve({ ok: false, invalidTokens: [] })
+      }, PUSH_TIMEOUT_MS)
+      this.pushes.set(id, { resolve, timer })
+      const sent = this.send({ type: 'push', id, tokens, data, ttlSec: options.ttlSec ?? 3600, ...(options.collapseKey ? { collapseKey: options.collapseKey } : {}) })
+      if (!sent) {
+        clearTimeout(timer)
+        this.pushes.delete(id)
+        resolve({ ok: false, invalidTokens: [] })
+      }
+    })
+  }
+
+  /** @param {object} frame */
+  send(frame) {
+    const socket = this.socket
+    if (socket === undefined || socket.readyState !== 1) return false
+    try {
+      socket.send(JSON.stringify(frame))
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  failPushes(reason) {
+    for (const [id, waiter] of this.pushes) {
+      clearTimeout(waiter.timer)
+      waiter.resolve({ ok: false, invalidTokens: [], error: reason })
+      this.pushes.delete(id)
+    }
+  }
+}
+
+/**
+ * @param {string} relayUrl
+ * @param {string} hostId
+ */
+export function tunnelUrl(relayUrl, hostId) {
+  const url = new URL(relayUrl)
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) {
+    throw new Error('relayUrl must be https:// (http:// only for loopback testing)')
+  }
+  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/v1/hosts/${encodeURIComponent(hostId)}/tunnel`
+  url.search = ''
+  url.hash = ''
+  return url.toString()
+}
+
+async function loadWebSocket() {
+  if (typeof globalThis.WebSocket === 'function') return globalThis.WebSocket
+  try {
+    const mod = await import('ws')
+    return mod.WebSocket ?? mod.default
+  } catch {
+    throw new Error('no WebSocket implementation available (needs Node 22+ or the "ws" package)')
+  }
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms)
+    function done() {
+      signal?.removeEventListener('abort', done)
+      clearTimeout(timer)
+      resolve()
+    }
+    signal?.addEventListener('abort', done, { once: true })
+  })
+}