@huynle/hub 0.0.0-stage → 0.6.1

package/src/central/speech/settings.ts

@@ -0,0 +1,375 @@
+// Speech settings (persisted in state.json): which provider, model, voice, key and base URL to use for
+// speech-to-text and text-to-speech. Precedence, per direction and field: the user's own settings (multi-
+// user hubs) > the saved server default > hub.json (`speech`) > the hub's environment (OPENROUTER_API_KEY,
+// VOICE_STT_MODEL, VOICE_TTS_MODEL, VOICE_VOICE). Keys are only ever shown masked ({set, last4, source});
+// a user sees last4 of their own key only.
+import { ValidationError } from "../auth"
+import { OPENROUTER_BASE_URL } from "./openrouter"
+
+export const SPEECH_PROVIDERS = ["openrouter", "openai-compatible"] as const
+export type SpeechProviderName = (typeof SPEECH_PROVIDERS)[number]
+
+export interface StoredStt {
+  provider?: SpeechProviderName
+  model?: string
+  apiKey?: string
+  baseURL?: string
+  language?: string
+}
+
+export interface StoredTts {
+  provider?: SpeechProviderName
+  model?: string
+  voice?: string
+  apiKey?: string
+  baseURL?: string
+  speed?: number
+}
+
+export interface StoredSpeech {
+  stt?: StoredStt
+  tts?: StoredTts
+}
+
+/** Hub environment defaults (see CentralConfig). */
+export interface SpeechDefaults {
+  /** OPENROUTER_API_KEY; only ever used with the openrouter provider. */
+  readonly apiKey?: string
+  readonly sttModel: string
+  readonly ttsModel: string
+  readonly voice: string
+  /** Speech settings from hub.json, layered under the saved ones. */
+  readonly file?: StoredSpeech
+}
+
+/** user: the caller's own key; settings: the saved server default; config: hub.json; env: OPENROUTER_API_KEY. */
+export type KeySource = "user" | "settings" | "config" | "env" | "none"
+
+export interface KeyView {
+  readonly set: boolean
+  readonly last4?: string
+  readonly source: KeySource
+}
+
+/** Effective settings of one direction, including the key to use (never sent to clients). */
+export interface Resolved {
+  readonly provider: SpeechProviderName
+  readonly model: string
+  readonly baseURL: string
+  readonly apiKey?: string
+  readonly keySource: KeySource
+}
+
+export interface ResolvedStt extends Resolved {
+  readonly language?: string
+}
+
+export interface ResolvedTts extends Resolved {
+  readonly voice: string
+  readonly speed?: number
+}
+
+export interface SttView {
+  readonly provider: SpeechProviderName
+  readonly model: string
+  readonly baseURL?: string
+  readonly language?: string
+  readonly apiKey: KeyView
+}
+
+export interface TtsView {
+  readonly provider: SpeechProviderName
+  readonly model: string
+  readonly voice: string
+  readonly baseURL?: string
+  readonly speed?: number
+  readonly apiKey: KeyView
+}
+
+/** GET /api/settings/speech */
+export interface SpeechView {
+  readonly stt: SttView
+  readonly tts: TtsView
+  readonly voiceHints: Readonly<Record<string, readonly string[]>>
+  /** Whether each direction is usable (see speechReady). */
+  readonly ready: SpeechReady
+}
+
+/** A user's own saved fields, key masked (source "user"). */
+export interface OwnSpeechView {
+  readonly stt: Omit<StoredStt, "apiKey"> & { readonly apiKey?: KeyView }
+  readonly tts: Omit<StoredTts, "apiKey"> & { readonly apiKey?: KeyView }
+}
+
+/** GET /api/settings/speech for a user of a multi-user hub: effective settings plus where they come from. */
+export interface UserSpeechView extends SpeechView {
+  readonly scope: "user"
+  /** The server default (keys: set and source only). */
+  readonly default: { readonly stt: SttView; readonly tts: TtsView }
+  readonly user: OwnSpeechView
+}
+
+/** Voices known to work, keyed by model ID prefix (voices are model-specific). */
+export const VOICE_HINTS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  "microsoft/mai-voice": ["en-US-Harper:MAI-Voice-2.1-Flash"],
+  "hexgrad/kokoro-82m": ["af_heart", "af_bella", "af_nicole", "af_sky", "am_adam", "am_michael", "bf_emma", "bm_george"],
+  "openai/": ["alloy", "ash", "ballad", "coral", "echo", "fable", "nova", "onyx", "sage", "shimmer", "verse"],
+})
+
+export const MAX_NAME_CHARS = 200
+export const MIN_SPEED = 0.5
+export const MAX_SPEED = 2
+const MAX_KEY_CHARS = 500
+const MAX_URL_CHARS = 500
+/** Keys go into an Authorization header: printable ASCII without spaces. */
+const KEY_PATTERN = /^[\x21-\x7e]+$/
+const LANGUAGE_PATTERN = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8}){0,3}$/
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"])
+
+/**
+ * Hosts on a private network, where plain http:// is acceptable for self-hosted speech servers:
+ * loopback, RFC 1918 and Tailscale (100.64/10) addresses, single-label names (Docker services) and
+ * .local / .lan / .internal / .home.arpa names.
+ */
+export function isPrivateHost(hostname: string): boolean {
+  if (LOCAL_HOSTS.has(hostname)) return true
+  const ip = hostname.match(/^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/)
+  if (ip) {
+    const [a, b] = [Number(ip[1]), Number(ip[2])]
+    return a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127)
+  }
+  if (!hostname.includes(".")) return /^[a-z0-9-]+$/i.test(hostname)
+  return /\.(local|lan|internal|home\.arpa)$/i.test(hostname)
+}
+
+/**
+ * One direction's saved settings over hub.json's. The file's section is ignored when the saved provider
+ * differs from it, and its key is dropped when the saved base URL differs: a key never follows the
+ * settings to another endpoint.
+ */
+export function layer<T extends StoredStt | StoredTts>(file: T | undefined, saved: T | undefined): T | undefined {
+  if (!file) return saved
+  if (saved?.provider !== undefined && saved.provider !== (file.provider ?? "openrouter")) return saved
+  const merged: T = { ...file, ...saved }
+  if (saved?.baseURL !== undefined && saved.baseURL !== file.baseURL && saved.apiKey === undefined) delete merged.apiKey
+  return merged
+}
+
+function resolve(
+  own: { user?: StoredStt | StoredTts; saved?: StoredStt | StoredTts },
+  merged: StoredStt | StoredTts | undefined,
+  model: string,
+  defaults: SpeechDefaults,
+): Resolved {
+  const provider = merged?.provider ?? "openrouter"
+  const envKey = provider === "openrouter" ? defaults.apiKey : undefined
+  const key = merged?.apiKey
+  const apiKey = key ?? envKey
+  return {
+    provider,
+    model: merged?.model ?? model,
+    baseURL: merged?.baseURL ?? OPENROUTER_BASE_URL,
+    ...(apiKey ? { apiKey } : {}),
+    keySource: key ? (own.user?.apiKey === key ? "user" : own.saved?.apiKey === key ? "settings" : "config") : envKey ? "env" : "none",
+  }
+}
+
+/** One direction's layers merged: user over the saved server default over hub.json. */
+function merged<K extends "stt" | "tts">(kind: K, stored: StoredSpeech, defaults: SpeechDefaults, user?: StoredSpeech): StoredSpeech[K] {
+  const lower = layer(defaults.file?.[kind], stored[kind]) as StoredSpeech[K]
+  return user ? (layer(lower, user[kind]) as StoredSpeech[K]) : lower
+}
+
+/** The server default and hub.json merged: the layer under a user's own settings. */
+export function lowerLayers(stored: StoredSpeech, defaults: SpeechDefaults): StoredSpeech {
+  const stt = merged("stt", stored, defaults)
+  const tts = merged("tts", stored, defaults)
+  return { ...(stt ? { stt } : {}), ...(tts ? { tts } : {}) }
+}
+
+export function resolveStt(stored: StoredSpeech, defaults: SpeechDefaults, user?: StoredSpeech): ResolvedStt {
+  const stt = merged("stt", stored, defaults, user)
+  return { ...resolve({ user: user?.stt, saved: stored.stt }, stt, defaults.sttModel, defaults), ...(stt?.language ? { language: stt.language } : {}) }
+}
+
+export function resolveTts(stored: StoredSpeech, defaults: SpeechDefaults, user?: StoredSpeech): ResolvedTts {
+  const tts = merged("tts", stored, defaults, user)
+  return {
+    ...resolve({ user: user?.tts, saved: stored.tts }, tts, defaults.ttsModel, defaults),
+    voice: tts?.voice ?? defaults.voice,
+    ...(tts?.speed !== undefined ? { speed: tts.speed } : {}),
+  }
+}
+
+/** `own`: last4 only for the caller's own key (user views), else for any key (the server default's view). */
+function keyView(resolved: Resolved, own?: "user"): KeyView {
+  const key = resolved.apiKey
+  if (!key) return { set: false, source: "none" }
+  const last4 = key.length >= 12 && (own === undefined || resolved.keySource === "user")
+  return { set: true, ...(last4 ? { last4: key.slice(-4) } : {}), source: resolved.keySource }
+}
+
+function sections(stored: StoredSpeech, defaults: SpeechDefaults, user: StoredSpeech | undefined, own?: "user") {
+  const stt = resolveStt(stored, defaults, user)
+  const tts = resolveTts(stored, defaults, user)
+  const sttView: SttView = {
+    provider: stt.provider,
+    model: stt.model,
+    ...(merged("stt", stored, defaults, user)?.baseURL ? { baseURL: stt.baseURL } : {}),
+    ...(stt.language ? { language: stt.language } : {}),
+    apiKey: keyView(stt, own),
+  }
+  const ttsView: TtsView = {
+    provider: tts.provider,
+    model: tts.model,
+    voice: tts.voice,
+    ...(merged("tts", stored, defaults, user)?.baseURL ? { baseURL: tts.baseURL } : {}),
+    ...(tts.speed !== undefined ? { speed: tts.speed } : {}),
+    apiKey: keyView(tts, own),
+  }
+  return { stt: sttView, tts: ttsView, ready: speechReady(stt, tts) }
+}
+
+/** Settings as shown to the phone (the server default's scope): effective values, keys masked. */
+export function speechView(stored: StoredSpeech, defaults: SpeechDefaults): SpeechView {
+  const { stt, tts, ready } = sections(stored, defaults, undefined)
+  return { stt, tts, voiceHints: VOICE_HINTS, ready }
+}
+
+/**
+ * A user's view: effective settings (own → server default → hub.json → env), the server default and the
+ * user's own fields. Keys that are not the user's own show only whether they are set and where from.
+ */
+export function userSpeechView(stored: StoredSpeech, defaults: SpeechDefaults, user: StoredSpeech): UserSpeechView {
+  const { stt, tts, ready } = sections(stored, defaults, user, "user")
+  const fallback = sections(stored, defaults, undefined, "user")
+  const own = <T extends StoredStt | StoredTts>(section: T | undefined) => {
+    const { apiKey, ...rest } = section ?? ({} as T)
+    const view = { ...rest } as Omit<T, "apiKey"> & { apiKey?: KeyView }
+    if (apiKey) view.apiKey = { set: true, ...(apiKey.length >= 12 ? { last4: apiKey.slice(-4) } : {}), source: "user" }
+    return view
+  }
+  return {
+    stt,
+    tts,
+    voiceHints: VOICE_HINTS,
+    ready,
+    scope: "user",
+    default: { stt: fallback.stt, tts: fallback.tts },
+    user: { stt: own(user.stt), tts: own(user.tts) },
+  }
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** https:// anywhere, or plain http:// to a private-network host (self-hosted speech servers). Credentials, query and fragment refused. */
+export function validBaseURL(raw: unknown, field: string): string {
+  if (typeof raw !== "string" || raw.length > MAX_URL_CHARS) throw new ValidationError(`${field} must be a URL`)
+  let url: URL
+  try {
+    url = new URL(raw.trim())
+  } catch {
+    throw new ValidationError(`${field} must be a URL`)
+  }
+  const local = url.protocol === "http:" && isPrivateHost(url.hostname)
+  if (url.protocol !== "https:" && !local) {
+    throw new ValidationError(`${field} must start with https:// (http:// only for private-network hosts)`)
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new ValidationError(`${field} must not contain credentials, a query or a fragment`)
+  }
+  return url.toString().replace(/\/+$/, "")
+}
+
+type Section = Record<string, unknown>
+
+/** Applies one optional text field: null or "" clears, a string sets (validated), absent keeps. */
+function text(next: Section, input: Section, key: string, field: string, check?: (value: string) => boolean): void {
+  if (!(key in input)) return
+  const value = input[key]
+  if (value === null || value === "") return void delete next[key]
+  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`)
+  const trimmed = value.trim()
+  if (!trimmed || trimmed.length > MAX_NAME_CHARS || /[\x00-\x1f\x7f]/.test(trimmed) || (check && !check(trimmed))) {
+    throw new ValidationError(`${field} is not valid`)
+  }
+  next[key] = trimmed
+}
+
+function section<T extends StoredStt | StoredTts>(prev: T | undefined, input: unknown, kind: "stt" | "tts", file?: T): T | undefined {
+  if (input === undefined) return prev
+  if (!isObj(input)) throw new ValidationError(`${kind} must be an object`)
+  const next: Section = { ...prev }
+
+  if ("provider" in input) {
+    if (input.provider === null) delete next.provider
+    else if (!SPEECH_PROVIDERS.includes(input.provider as SpeechProviderName)) {
+      throw new ValidationError(`${kind}.provider must be one of ${SPEECH_PROVIDERS.join(", ")}`)
+    } else next.provider = input.provider
+  }
+  text(next, input, "model", `${kind}.model`)
+  if (kind === "stt") text(next, input, "language", "stt.language", (v) => LANGUAGE_PATTERN.test(v))
+  if (kind === "tts") {
+    text(next, input, "voice", "tts.voice")
+    if ("speed" in input) {
+      const speed = input.speed
+      if (speed === null) delete next.speed
+      else if (typeof speed !== "number" || !Number.isFinite(speed) || speed < MIN_SPEED || speed > MAX_SPEED) {
+        throw new ValidationError(`tts.speed must be a number from ${MIN_SPEED} to ${MAX_SPEED}`)
+      } else next.speed = speed
+    }
+  }
+  if ("baseURL" in input) {
+    if (input.baseURL === null || input.baseURL === "") delete next.baseURL
+    else next.baseURL = validBaseURL(input.baseURL, `${kind}.baseURL`)
+  }
+
+  if ("apiKey" in input) {
+    const key = input.apiKey
+    if (key === null || key === "") delete next.apiKey
+    else if (typeof key !== "string" || key.trim().length > MAX_KEY_CHARS || !KEY_PATTERN.test(key.trim())) {
+      // Never echo the value: it may be a real key with a typo.
+      throw new ValidationError(`${kind}.apiKey must be a single token of printable characters`)
+    } else next.apiKey = key.trim()
+  } else if ((prev?.provider ?? file?.provider ?? "openrouter") !== (next.provider ?? file?.provider ?? "openrouter") || prev?.baseURL !== next.baseURL) {
+    // A stored key never follows the settings to a different endpoint.
+    delete next.apiKey
+  }
+
+  const effective = layer(file, next as T)
+  if (effective?.provider === "openai-compatible" && !effective.baseURL) {
+    throw new ValidationError(`${kind}.baseURL is required for the openai-compatible provider`)
+  }
+  return next as T
+}
+
+/** Partial update from untrusted input (validated together with hub.json's layer); throws ValidationError and returns a new object. */
+export function updateSpeech(prev: StoredSpeech, input: unknown, file: StoredSpeech = {}): StoredSpeech {
+  if (!isObj(input)) throw new ValidationError("Expected {stt?, tts?}")
+  const stt = section(prev.stt, input.stt, "stt", file.stt)
+  const tts = section(prev.tts, input.tts, "tts", file.tts)
+  return { ...(stt ? { stt } : {}), ...(tts ? { tts } : {}) }
+}
+
+export interface SpeechReady {
+  readonly stt: boolean
+  readonly tts: boolean
+  /** Why speech is not usable yet (absent when both directions are ready). */
+  readonly reason?: string
+}
+
+/** Whether a direction can work at all: openrouter needs a key, openai-compatible a base URL. */
+function missing(resolved: Resolved): string | undefined {
+  if (resolved.provider === "openrouter") return resolved.apiKey ? undefined : "an OpenRouter API key"
+  return resolved.baseURL ? undefined : "a base URL"
+}
+
+export function speechReady(stt: Resolved, tts: Resolved): SpeechReady {
+  const needs = [
+    ["Speech-to-text", missing(stt)],
+    ["Text-to-speech", missing(tts)],
+  ].filter((entry): entry is [string, string] => entry[1] !== undefined)
+  const ready = { stt: !missing(stt), tts: !missing(tts) }
+  if (needs.length === 0) return ready
+  return { ...ready, reason: `${needs.map(([what, need]) => `${what} needs ${need}`).join("; ")}. Set it in Settings → Speech.` }
+}

package/src/central/spoke-ws.ts

@@ -0,0 +1,300 @@
+// Spoke WebSocket endpoint (/spoke/ws): bearer-token authentication, hello/welcome handshake, frame
+// validation, heartbeats, server→spoke request/response correlation, and spoke→server requests.
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun"
+import {
+  encode,
+  MAX_FRAME,
+  parseSpokeMessage,
+  PROTOCOL_VERSION,
+  type Req,
+  type ResultFor,
+  type ServerMessage,
+  type ServerRequest,
+  type SpokeRequest,
+} from "../protocol"
+import type { Auth } from "./auth"
+import type { PushDetail, PushExtra, PushKind } from "./push"
+import type { Registry } from "./registry"
+import { newID, type Store } from "./store"
+
+/** Push notifications (implemented by Push in push.ts) to `ownerID`'s devices. Returns the number of devices notified. */
+export interface Notifier {
+  notify(kind: PushKind, sessionID: string, title: string, detail?: PushDetail, body?: string, ownerID?: string, extra?: PushExtra): Promise<number>
+}
+
+/** The spoke answered with an error, or disconnected before answering. */
+export class SpokeError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "SpokeError"
+  }
+}
+
+/** A request that would not fit in one protocol frame (the spoke would drop it and never answer). */
+export class RequestTooLargeError extends Error {
+  constructor(op: string) {
+    super(`The ${op} request is too large to send to OpenCode`)
+    this.name = "RequestTooLargeError"
+  }
+}
+
+export class RequestTimeoutError extends Error {
+  constructor(op: string) {
+    super(`OpenCode did not answer the ${op} request in time`)
+    this.name = "RequestTimeoutError"
+  }
+}
+
+export interface SpokeSocketData {
+  readonly connID: string
+  readonly machineID: string
+  readonly machineName: string
+  ready: boolean
+  lastSeen: number
+  helloTimer?: ReturnType<typeof setTimeout>
+}
+
+type Socket = ServerWebSocket<SpokeSocketData>
+
+export interface SpokeHubOptions {
+  readonly store: Store
+  readonly auth: Auth
+  readonly registry: Registry
+  readonly publicURL: string
+  readonly notifier: Notifier
+  /** Sends a message to the SSE subscribers of `tenant` (a user ID). */
+  readonly broadcast: (message: { type: string; [key: string]: unknown }, tenant: string) => void
+  readonly turnTimeoutMs: number
+  /** Added to turnTimeoutMs for the hub-side wait (default TURN_GRACE_MS). */
+  readonly turnGraceMs?: number
+  readonly requestTimeoutMs?: number
+  readonly helloTimeoutMs?: number
+  readonly heartbeatMs?: number
+  readonly staleMs?: number
+}
+
+interface Pending {
+  readonly connID: string
+  readonly op: string
+  readonly resolve: (value: unknown) => void
+  readonly reject: (error: Error) => void
+  readonly timer: ReturnType<typeof setTimeout>
+}
+
+/** Extra time the hub waits past the turn timeout so the spoke's own timeout result arrives first. */
+export const TURN_GRACE_MS = 15_000
+/** Creating a session and opening it in a new Herdr tab (the spoke allows `herdr agent start` 20 s). */
+export const CREATE_IN_HERDR_TIMEOUT_MS = 45_000
+
+const CLOSE_PROTOCOL = 4000
+const CLOSE_REVOKED = 4001
+const CLOSE_STALE = 4002
+
+export class SpokeHub {
+  private readonly sockets = new Map<string, Socket>()
+  private readonly pending = new Map<string, Pending>()
+  private readonly heartbeat: ReturnType<typeof setInterval>
+  private seq = 0
+  readonly websocket: WebSocketHandler<SpokeSocketData>
+
+  constructor(private readonly options: SpokeHubOptions) {
+    const staleMs = options.staleMs ?? 60_000
+    this.heartbeat = setInterval(() => {
+      const now = Date.now()
+      for (const ws of this.sockets.values()) {
+        if (now - ws.data.lastSeen > staleMs) ws.close(CLOSE_STALE, "heartbeat timeout")
+        else ws.ping()
+      }
+    }, options.heartbeatMs ?? 20_000)
+    this.heartbeat.unref?.()
+
+    this.websocket = {
+      open: (ws) => this.open(ws),
+      message: (ws, raw) => this.message(ws, raw),
+      close: (ws) => this.closed(ws),
+      pong: (ws) => this.seen(ws),
+      idleTimeout: 0,
+    }
+  }
+
+  /** Authenticates and upgrades /spoke/ws. Returns a Response on failure, undefined when upgraded. */
+  upgrade(request: Request, server: Server<SpokeSocketData>): Response | undefined {
+    const match = /^Bearer\s+(\S+)$/i.exec(request.headers.get("authorization") ?? "")
+    const machine = match?.[1] ? this.options.store.findMachine(match[1]) : undefined
+    const owner = machine && this.options.store.user(machine.ownerID)
+    if (!machine || !owner || owner.disabled) return Response.json({ error: "Invalid or revoked machine token" }, { status: 401 })
+    const data: SpokeSocketData = {
+      connID: newID("conn"),
+      machineID: machine.id,
+      machineName: machine.name,
+      ready: false,
+      lastSeen: Date.now(),
+    }
+    if (server.upgrade(request, { data })) return undefined
+    return Response.json({ error: "Expected a WebSocket upgrade" }, { status: 426 })
+  }
+
+  /** Sends a request to a connected spoke and resolves with its result. */
+  request<R extends ServerRequest>(connID: string, req: R): Promise<ResultFor[R["op"]]> {
+    const ws = this.sockets.get(connID)
+    if (!ws?.data.ready) return Promise.reject(new SpokeError("OpenCode process disconnected"))
+    const id = `r${++this.seq}`
+    const frame = encode({ t: "req", id, req })
+    if (frame.length > MAX_FRAME) return Promise.reject(new RequestTooLargeError(req.op))
+    const base = this.options.requestTimeoutMs ?? 15_000
+    const timeoutMs =
+      req.op === "turn"
+        ? this.options.turnTimeoutMs + (this.options.turnGraceMs ?? TURN_GRACE_MS)
+        : req.op === "create" && req.herdrWorkspace
+          ? Math.max(base, CREATE_IN_HERDR_TIMEOUT_MS) // the spoke waits for OpenCode to start in the new tab
+          : base
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new RequestTimeoutError(req.op))
+      }, timeoutMs)
+      this.pending.set(id, { connID, op: req.op, resolve: resolve as (v: unknown) => void, reject, timer })
+      ws.send(frame)
+    })
+  }
+
+  /** Disconnects every socket of a machine (after revocation). */
+  closeMachine(machineID: string, reason: string): void {
+    for (const ws of this.sockets.values()) if (ws.data.machineID === machineID) this.bye(ws, reason, CLOSE_REVOKED)
+  }
+
+  stop(): void {
+    clearInterval(this.heartbeat)
+    for (const ws of this.sockets.values()) this.bye(ws, "server shutting down", 1001)
+  }
+
+  private open(ws: Socket): void {
+    this.sockets.set(ws.data.connID, ws)
+    ws.data.helloTimer = setTimeout(() => {
+      if (!ws.data.ready) this.bye(ws, "hello timeout")
+    }, this.options.helloTimeoutMs ?? 10_000)
+  }
+
+  private seen(ws: Socket): void {
+    ws.data.lastSeen = Date.now()
+    if (ws.data.ready) this.options.registry.touch(ws.data.connID)
+  }
+
+  private message(ws: Socket, raw: string | Buffer): void {
+    this.seen(ws)
+    const message = parseSpokeMessage(raw)
+    if (!message) return this.bye(ws, "protocol error")
+    const { registry } = this.options
+    const { connID } = ws.data
+
+    if (!ws.data.ready) {
+      if (message.t !== "hello") return this.bye(ws, "protocol error")
+      if (message.v !== PROTOCOL_VERSION) {
+        return this.bye(ws, `unsupported protocol version ${message.v}; server speaks version ${PROTOCOL_VERSION}`)
+      }
+      clearTimeout(ws.data.helloTimer)
+      ws.data.ready = true
+      registry.connect(connID, { id: ws.data.machineID, name: ws.data.machineName }, message)
+      this.options.store.touchMachine(ws.data.machineID)
+      this.send(ws, { t: "welcome", v: PROTOCOL_VERSION, machineID: ws.data.machineID, publicURL: this.options.publicURL })
+      return
+    }
+
+    switch (message.t) {
+      case "hello":
+        return this.bye(ws, "protocol error")
+      case "sessions":
+        registry.setSessions(connID, message.sessions)
+        return this.resendConversations(connID)
+      case "terminals":
+        return registry.setTerminals(connID, message)
+      case "event":
+        return registry.observe(connID, message.event)
+      case "req":
+        void this.answer(ws, message)
+        return
+      case "res": {
+        const pending = this.pending.get(message.id)
+        if (!pending || pending.connID !== connID) return
+        this.pending.delete(message.id)
+        clearTimeout(pending.timer)
+        if (message.ok) pending.resolve(message.result)
+        else pending.reject(new SpokeError(message.error || `OpenCode ${pending.op} request failed`))
+        return
+      }
+      case "bye":
+        ws.close(1000, "bye")
+        return
+    }
+  }
+
+  private async answer(ws: Socket, frame: Req<SpokeRequest>): Promise<void> {
+    try {
+      const result = await this.handle(ws, frame.req)
+      this.send(ws, { t: "res", id: frame.id, ok: true, result })
+    } catch (cause) {
+      this.send(ws, { t: "res", id: frame.id, ok: false, error: cause instanceof Error ? cause.message : String(cause) })
+    }
+  }
+
+  /** The machine's current owner (read live: ownership can move, e.g. on migration). */
+  ownerOf(machineID: string): string | undefined {
+    return this.options.store.machines().find((m) => m.id === machineID)?.ownerID
+  }
+
+  private async handle(ws: Socket, req: SpokeRequest): Promise<ResultFor[SpokeRequest["op"]]> {
+    const { auth, publicURL } = this.options
+    const owner = this.ownerOf(ws.data.machineID)
+    if (!owner) throw new Error("This machine is no longer enrolled")
+    switch (req.op) {
+      case "pairCode": {
+        const { code, expiresAt } = auth.issuePairCode(owner)
+        return { code, url: `${publicURL}/pair`, expiresAt }
+      }
+      case "handoff": {
+        // Only the machine owner's own (or not yet reported) sessions: never another user's title or ID.
+        const tenant = this.options.registry.sessionTenant(req.sessionID)
+        if (tenant !== undefined && tenant !== owner) throw new Error("Unknown session")
+        this.options.broadcast({ type: "handoff", sessionID: req.sessionID }, owner)
+        const title = (tenant && this.options.registry.status(req.sessionID)?.[0]?.title) || req.sessionID
+        return { notified: await this.options.notifier.notify("handoff", req.sessionID, title, undefined, undefined, owner) }
+      }
+      case "openLink": {
+        const { code } = auth.issueLoginCode(owner)
+        const next = req.sessionID ? `/s/${encodeURIComponent(req.sessionID)}${req.voice ? "?voice=1" : ""}` : "/"
+        return { url: `${publicURL}/login?code=${code}&next=${next}` }
+      }
+    }
+  }
+
+  /** Tells a (re)connected owner about sessions the phone has in conversation mode. */
+  private resendConversations(connID: string): void {
+    for (const sessionID of this.options.registry.conversationResends(connID)) {
+      this.request(connID, { op: "conversation", sessionID, on: true }).catch((cause) => {
+        console.error("[hub] re-sending conversation mode failed:", cause instanceof Error ? cause.message : cause)
+      })
+    }
+  }
+
+  private closed(ws: Socket): void {
+    clearTimeout(ws.data.helloTimer)
+    const { connID } = ws.data
+    this.sockets.delete(connID)
+    for (const [id, pending] of this.pending) {
+      if (pending.connID !== connID) continue
+      this.pending.delete(id)
+      clearTimeout(pending.timer)
+      pending.reject(new SpokeError("OpenCode process disconnected"))
+    }
+    if (ws.data.ready) this.options.registry.disconnect(connID)
+  }
+
+  private bye(ws: Socket, reason: string, code = CLOSE_PROTOCOL): void {
+    this.send(ws, { t: "bye", reason })
+    ws.close(code, reason)
+  }
+
+  private send(ws: Socket, message: ServerMessage): void {
+    ws.send(encode(message))
+  }
+}