Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

12.8 KB
Raw Blame
/**
 * Shared tabs' relay (docs/superpowers/specs/2026-10-15-agent-messages-across-accounts-design.md): the backend's blind
 * relay between the machines of a tab shared across accounts (`/api/agent-messages-ws`, backend/src/lib/agentMessagesWs.ts).
 * It routes by tab and machine, stamps who sent each frame, and reads nothing else: what it carries was sealed by
 * `TabKey` (gateway/tabKey.ts) before it got here.
 *
 * One long-lived socket per shared tab, not one for all of them: the relay admits a socket for one tab at a time
 * (this account owns this machine and is the tab's owner or an accepted member), and checks it again as the tab
 * changes, so a socket per tab keeps that admission per tab. Removed from one tab, this machine loses that tab's
 * socket and keeps the others.
 *
 * A close of 4403 stops for good: the account left the tab or was removed from it, and dialling again would only be
 * refused again. 4409 stops too: another socket of this machine took the tab over, and dialling again would take it
 * back from that one, and so on. Both are told to Agent Messages (`closed`); every other close dials again, backing
 * off as the backend link does (gateway/upstream.ts).
 */
import { WebSocket } from 'ws'
import type { GatewayEvents, TabRelay } from '../core/api.js'
import { SHARED_TAB_FRAME_MAX } from '../lib/e2ee/tabSession.js'
import { BACKEND_IDLE_DEADLINE_MS, watchSocketLiveness, type LivenessWatch } from '../lib/wsLiveness.js'
import { declaredClientQuery } from '../lib/declaredClient.js'

/** The relay closes a socket that sends a frame bigger than this (agentMessagesWs.ts `MAX_FRAME`): refused here first. */
export const TAB_RELAY_MAX_FRAME = SHARED_TAB_FRAME_MAX
/** How long a frame sent before the relay admitted the socket waits for it. */
export const TAB_RELAY_READY_WAIT_MS = 5_000
/** The relay closes a socket that sends more than this many frames in a second (agentMessagesWs.ts `PER_SECOND`). */
export const TAB_RELAY_FRAMES = 20
/** The window those frames are kept to here: a second, and a tenth more for the frames' jitter on the way, so that
 *  twenty sent at the end of one of our windows and twenty at the start of the next never reach the relay in one of its. */
export const TAB_RELAY_WINDOW_MS = 1_100
/**
 * The most a send waits, from the moment it is called, for the relay to admit the socket and then for its turn within
 * the rate; past it the send answers false and the frame is never sent. Below the core's wait on the gateway
 * (core/gatewayLink.ts `TAB_RELAY_WAIT_MS`, 10 s): a frame that outlived that wait would be answered false to Agent
 * Messages by the core and still be sent by the gateway later, so the two would disagree on what was sent.
 */
export const TAB_RELAY_SEND_DEADLINE_MS = 8_000
/** The most frames that may wait per tab, for the relay or their turn: two seconds' worth at the relay's rate. Beyond it
 *  a send is refused at once, rather than hold its frame (up to 128 KiB) in memory for a turn it cannot get in time. */
export const TAB_RELAY_QUEUE = 2 * TAB_RELAY_FRAMES
const BASE_DELAY_MS = 1_000
const MAX_DELAY_MS = 30_000
const HANDSHAKE_TIMEOUT_MS = 10_000
/** What the relay may send: its frames are below `TAB_RELAY_MAX_FRAME` and the stamp it adds, with room to spare. */
const MAX_PAYLOAD = 2 * SHARED_TAB_FRAME_MAX
/** The relay's ids for a shared tab; it drops an upgrade for anything else before it answers. */
const SHARED_TAB_ID = /^[a-f0-9]{24}$/

export interface TabRelayDeps {
  /** The backend's WebSocket base (`env.BACKEND_WS_URL`). */
  base: string
  /** The account's environment (`prod`, …), which the relay checks the token against. */
  environment: string
  machineId: () => string
  /** The account's token, asked for at each dial; `force` after a 401, once, for the token that was refused. */
  accessToken(options?: { force?: boolean; failedToken?: string }): Promise<string>
  emit: GatewayEvents['tabFrame']
  now?: () => number
}

interface TabSocket {
  ws: WebSocket | null
  ready: boolean
  attempts: number
  timer: NodeJS.Timeout | null
  closed: boolean
  waiters: Array<(ok: boolean) => void>
  heartbeat: LivenessWatch | null
  /** When each of the last frames went, for the relay's rate. */
  sentAt: number[]
  /** The frames waiting for their turn, in the order they were sent. */
  pacing: Promise<unknown>
  /** How many sends wait now, for the relay or their turn (`TAB_RELAY_QUEUE`). */
  waiting: number
  /** Wakes the turn sleeping for its slot, when the tab is closed. */
  sleepers: Set<() => void>
}

type Payload = Record<string, unknown>
const isRecord = (value: unknown): value is Payload => !!value && typeof value === 'object' && !Array.isArray(value)
const why = (error: unknown): string => (error instanceof Error ? error.message : String(error))

export class TabRelaySockets implements TabRelay {
  private readonly sockets = new Map<string, TabSocket>()
  private readonly now: () => number

  constructor(private readonly deps: TabRelayDeps) {
    this.now = deps.now ?? Date.now
  }

  async open(sharedTabId: string): Promise<void> {
    if (!SHARED_TAB_ID.test(sharedTabId) || this.sockets.has(sharedTabId)) return
    const entry: TabSocket = { ws: null, ready: false, attempts: 0, timer: null, closed: false, waiters: [], heartbeat: null, sentAt: [], pacing: Promise.resolve(), waiting: 0, sleepers: new Set() }
    this.sockets.set(sharedTabId, entry)
    void this.dial(sharedTabId, entry)
  }

  async send(sharedTabId: string, to: string, payload: Record<string, unknown>): Promise<boolean> {
    const entry = this.sockets.get(sharedTabId)
    if (!entry || typeof to !== 'string' || !to || to.length > 128 || !isRecord(payload)) return false
    let data: string
    try { data = JSON.stringify({ type: 'amsg_frame', to, payload }) } catch { return false }
    if (Buffer.byteLength(data) > TAB_RELAY_MAX_FRAME || entry.waiting >= TAB_RELAY_QUEUE) return false
    const deadline = this.now() + TAB_RELAY_SEND_DEADLINE_MS
    entry.waiting++
    try {
      if (!entry.ready && !await this.whenReady(entry)) return false
      return await this.pace(entry, deadline, data)
    } finally {
      entry.waiting--
    }
  }

  close(sharedTabId: string): void {
    const entry = this.sockets.get(sharedTabId)
    if (!entry) return
    this.sockets.delete(sharedTabId)
    entry.closed = true
    if (entry.timer) clearTimeout(entry.timer)
    entry.timer = null
    entry.heartbeat?.stop()
    entry.ws?.close(1000, 'Closed')
    this.settle(entry, false)
    for (const wake of [...entry.sleepers]) wake()
  }

  /** The gateway stops: every tab's socket goes with it. */
  closeAll(): void {
    for (const sharedTabId of [...this.sockets.keys()]) this.close(sharedTabId)
  }

  private async dial(sharedTabId: string, entry: TabSocket): Promise<void> {
    const short = sharedTabId.slice(0, 8)
    let token: string
    try {
      token = await this.deps.accessToken()
    } catch (error) {
      this.retry(sharedTabId, entry, `no token (${why(error)})`)
      return
    }
    if (entry.closed) return
    const { base, environment } = this.deps
    const url = `${base.replace(/\/$/, '')}/api/agent-messages-ws?share=${encodeURIComponent(sharedTabId)}`
      + `&machine=${encodeURIComponent(this.deps.machineId())}&autonomousEnv=${encodeURIComponent(environment)}&${declaredClientQuery('relay')}`
    let ws: WebSocket
    try {
      ws = new WebSocket(url, [token], { handshakeTimeout: HANDSHAKE_TIMEOUT_MS, maxPayload: MAX_PAYLOAD })
    } catch (error) {
      this.retry(sharedTabId, entry, `could not dial (${why(error)})`)
      return
    }
    entry.ws = ws
    let refused: number | null = null
    // The relay answering the upgrade with a status rather than a socket: a 401 is the token, refreshed below.
    ws.on('unexpected-response', (_request, response) => { refused = Number(response.statusCode); ws.terminate() })
    ws.on('open', () => {
      entry.heartbeat = watchSocketLiveness(ws, {
        onIdle: (idleMs) => console.log(`[shared-tabs] ${short} no traffic for ${Math.round(idleMs / 1000)}s — terminating`),
        onWake: (sleptMs, givingUp) => console.log(`[shared-tabs] ${short} woke after ${Math.round(sleptMs / 1000)}s asleep — ${givingUp ? 'giving up on the link' : 're-probing'}`),
        peerGivesUpAfterMs: BACKEND_IDLE_DEADLINE_MS,
      })
    })
    ws.on('message', (raw) => this.heard(sharedTabId, entry, String(raw)))
    // Every error ends in a close, which is where it is handled.
    ws.on('error', () => {})
    // One socket a tab at a time: the next is dialled only after this one's close.
    ws.on('close', (code, reason) => {
      entry.ws = null
      entry.ready = false
      entry.heartbeat?.stop()
      entry.heartbeat = null
      if (entry.closed) return
      if (code === 4403 || code === 4409) {
        this.sockets.delete(sharedTabId)
        entry.closed = true
        this.settle(entry, false)
        console.log(`[shared-tabs] ${short} closed ${code} — not dialling again`)
        this.deps.emit({ sharedTabId, closed: { code, reason: reason.toString() } })
        return
      }
      if (refused === 401) {
        void this.deps.accessToken({ force: true, failedToken: token }).then(
          () => this.retry(sharedTabId, entry, 'token refused, refreshed'),
          () => this.retry(sharedTabId, entry, 'token refused, refresh failed'))
        return
      }
      this.retry(sharedTabId, entry, refused === null ? `closed ${code}` : `refused ${refused}`)
    })
  }

  private heard(sharedTabId: string, entry: TabSocket, raw: string): void {
    // Closed here, what was still on its way is nobody's: the tab's frames are not told after its close.
    if (entry.closed) return
    let frame: unknown
    try { frame = JSON.parse(raw) } catch { return }
    if (!isRecord(frame)) return
    if (frame.type === 'amsg_ready') {
      entry.ready = true
      entry.attempts = 0
      this.settle(entry, true)
      this.deps.emit({ sharedTabId, ready: true })
    } else if (frame.type === 'amsg_frame') {
      const from = frame.from
      if (!isRecord(from) || typeof from.machineId !== 'string' || typeof from.userId !== 'string' || !isRecord(frame.payload)) return
      this.deps.emit({ sharedTabId, from: { machineId: from.machineId, userId: from.userId }, payload: frame.payload })
    } else if (frame.type === 'amsg_undeliverable' && typeof frame.to === 'string') {
      this.deps.emit({ sharedTabId, undeliverable: frame.to })
    }
  }

  private retry(sharedTabId: string, entry: TabSocket, why: string): void {
    if (entry.closed) return
    const delay = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** Math.min(entry.attempts++, 5))
    console.log(`[shared-tabs] ${sharedTabId.slice(0, 8)} ${why} — retrying in ${Math.round(delay / 1000)}s (attempt ${entry.attempts})`)
    entry.timer = setTimeout(() => { entry.timer = null; void this.dial(sharedTabId, entry) }, delay)
    entry.timer.unref?.()
  }

  /** True once the relay admits the socket, false after `TAB_RELAY_READY_WAIT_MS` or once the tab is closed. */
  private whenReady(entry: TabSocket): Promise<boolean> {
    return new Promise((resolve) => {
      const waiter = (ok: boolean) => { clearTimeout(timer); resolve(ok) }
      const timer = setTimeout(() => {
        entry.waiters.splice(entry.waiters.indexOf(waiter), 1)
        resolve(false)
      }, TAB_RELAY_READY_WAIT_MS)
      timer.unref()
      entry.waiters.push(waiter)
    })
  }

  private settle(entry: TabSocket, ok: boolean): void {
    for (const waiter of entry.waiters.splice(0)) waiter(ok)
  }

  /**
   * Send the frame in its turn within the relay's rate, after every frame sent before it: true once written. False,
   * and never written, when the tab is closed, its socket is not admitted when the turn comes, or the deadline passed.
   * Only a frame written takes a slot of the rate.
   */
  private pace(entry: TabSocket, deadline: number, data: string): Promise<boolean> {
    const turn = entry.pacing.then(async (): Promise<boolean> => {
      for (;;) {
        const at = this.now()
        if (entry.closed || at >= deadline) return false
        while (entry.sentAt.length && at - entry.sentAt[0] >= TAB_RELAY_WINDOW_MS) entry.sentAt.shift()
        if (entry.sentAt.length < TAB_RELAY_FRAMES) {
          const ws = entry.ws
          if (!entry.ready || !ws || ws.readyState !== WebSocket.OPEN) return false
          entry.sentAt.push(at)
          ws.send(data)
          return true
        }
        await this.sleep(entry, Math.min(entry.sentAt[0] + TAB_RELAY_WINDOW_MS, deadline) - at)
      }
    })
    entry.pacing = turn
    return turn
  }

  /** Sleep for a turn's slot; woken early when the tab is closed. Never keeps the process alive. */
  private sleep(entry: TabSocket, ms: number): Promise<void> {
    return new Promise((resolve) => {
      const wake = () => { clearTimeout(timer); entry.sleepers.delete(wake); resolve() }
      const timer = setTimeout(wake, ms)
      timer.unref()
      entry.sleepers.add(wake)
    })
  }
}