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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* Backend hub — remote-machine adapter endpoint (`/api/adapter-ws`).
*
* A "remote" machine has no manager/agent-node: the user's own COMPUTER runs the machine-adapter CLI,
* which dials in here and occupies the NODE side of the machineId — the same role a manager socket
* plays for a docker node:
* - down:{machineId} (client chat/RPC) → forwarded to the adapter socket
* - adapter `up` frames (normalized claude events + `<x>_result` RPC replies) → publishUp(machineId)
* - presence key machine:{machineId}:mgr = 'remote' while connected → drives web node_status
*
* Auth: the first WebSocket subprotocol is the user's SSO access token. The stable `computer` query
* parameter selects (or creates) that user's Remote machine; a managed machine never gains a second
* writer for its down:{machineId} channel.
*
* A team session (lib/teamSession.ts), a Mac's team account, connects only as its own computer's machine
* and only while that row is a team machine. Its socket hears only the device-key pushes, never the
* account's grid name, raises no pairing notice on the person's apps, and may take only its own key off
* the device key log. A connect records which kind of sign-in serves the machine (`sessionKind`) when that changed.
*/
import type { Machine } from '@prisma/client'
import type { IncomingMessage } from 'http'
import type { Duplex } from 'stream'
import { WebSocket, type RawData } from 'ws'
import { createWss, upgradeStatusText, WS_LIMITS } from './wsServer.js'
import { prisma } from './prisma.js'
import {
publishUp, claimMachineOwner, releaseMachineOwner, publishDeviceE2eePair,
subscribeTerminalDown,
setMachineAppState, clearMachineAppState, noteTuiPresence,
} from './bus.js'
import { deliverUpLocal, trackSocketLiveness } from './hub.js'
import { PROCESS_ID } from './registry.js'
import { guardedSend, guardedSendJson } from './wsSend.js'
import { trackSocket } from './wsAttribution.js'
import { attachNodeRole, PRESENCE_TTL_SEC } from './nodeRole.js'
import { machineConnectChanges, presenceStateFromRow, presenceTracker, presenceWriteDue, recordTurnStarted, touchClientOnlineDay, touchMachineOnlineDay, touchUserOnlineDay, TUI_SURFACES, type ClientSurface, type MachineConnectChanges, type PresenceWriteState } from './dailyTracking.js'
import { countryCodeFromHeaders } from './clientGeo.js'
import { recordCreatedAgent, recordDeletedAgent } from './agentTracker.js'
import type { Frame, UpBusMsg } from './tunnel.js'
import { logger } from '../utils/logger.js'
import { utcDayKey } from '../types/analytics.js'
import { machineBillingAllowsDataPlane } from './billingState.js'
import { normalizeComputerId } from './deviceAuth.js'
import { authenticateAccessToken, SsoAuthError } from './ssoAuth.js'
import { relayAccountPushes } from './adapterAccountPushes.js'
import { relaySwarmDeliveries } from './swarmDeliveryPushes.js'
import { relaySwarmHostChanges } from './swarmHostPushes.js'
import { DAEMONS } from '../config/env.js'
import { parseAutonomousEnvironment } from './autonomousEnvironment.js'
import { machineService } from '../services/MachineService.js'
import { appendDeviceKey } from './deviceKeyLog.js'
import { TEAM_CONVERTED_FRAME } from './teamSession.js'
import { AppError } from '../errors/index.js'
import {
isEncryptedTerminalFrame,
TERMINAL_ENVELOPE_MAX_BYTES,
TERMINAL_UP_TYPES,
terminalFrameBytes,
TerminalRateGuard,
} from './terminalRelay.js'
import { decodeTerminalHop, TerminalBinaryKind, TerminalHopDirection } from './terminalBinary.js'
import {
isEncryptedP2pFrame,
P2P_SIGNAL_MAX_BYTES,
P2P_UP_TYPES,
p2pFrameBytes,
P2pSignalRateGuard,
terminalP2pPolicy,
} from './p2pSignaling.js'
import { ShortTurnGuard } from './shortTurnGuard.js'
import { markCpuKind } from './selfProfile.js'
import { createConnectionRoutes } from './terminalRoute.js'
import { recordRelay } from './relayStats.js'
import { computerSignedIn } from '../superTabs/computerMoves.js'
const wss = createWss(WS_LIMITS.adapter, { echoFirstProtocol: true })
// machineId → the current adapter socket. One writer per machineId: down:{machineId} must have exactly
// one consumer, so a reconnecting adapter supersedes its predecessor (same as attachNode does).
const owners = new Map<string, WebSocket>()
/** Frames the adapter sends us. `up.frame` is opaque (ServerEvents / `<x>_result` replies /
* commander_event device cards). Eligibility is per-frame: web defaults true, commander defaults
* false — the adapter opts device frames in (mirrors the node's managerSocket.emitUp channels). */
type AdapterFrame =
| { t: 'up'; frame: Frame; webEligible?: boolean; commanderEligible?: boolean; targetConnId?: string; userEligible?: boolean }
| { t: 'ping' }
// Which desktop app a remote computer drives, and whether it is running. Sent as an `up` frame with
// BOTH eligibility flags false, so it reaches the per-machine subscribeUp watchers (deviceWs) without
// ever being fanned out to an attached client — no existing firmware can see an unknown frame type.
const APP_ENGINES = new Set(['cursor'])
const APP_STATES = new Set(['open', 'closed', 'missing'])
// `?v=` is self-declared by the client, so it is never persisted raw: anything outside a plain
// semver-ish token (or longer than 64 chars) is dropped rather than stored.
const CLIENT_VERSION_RE = /^[A-Za-z0-9._+-]{1,64}$/
// How often an OPEN adapter socket refreshes `machines.lastSeenAt`. Rides the node role's existing 15s
// heartbeat (plus every app ping) rather than a timer of its own — this is just the floor between two
// Mongo writes, so a machine that is up all day costs ~300 updates, not ~6000. The floor starts from the row's own
// stamp, so a connect stamps only when that is due too (#2676); a close at most once a minute (MACHINE_CLOSE_FLOOR_MS).
const MACHINE_PRESENCE_WRITE_MS = 5 * 60_000
// A close stamps the exact "offline since", unless the row was stamped less than this ago: a looping adapter reconnects every
// few seconds, and each close rewrote the row (task #3119, Ken's prod scan of 11-05: `Machine.update` by adapter-ws slow 31
// times at peak). Offline since is then at most this early.
const MACHINE_CLOSE_FLOOR_MS = 60_000
// Daily presence of the PERSON (`user_daily_presence`): the daemon reports its own loopback clients —
// `open` the moment a desktop window attaches, `ping` on its 15s app-ping tick while one stays, at
// most once a minute (cli backendSocket sendAppPresence) — and this is the floor between two Mongo
// writes for the `ping` kind. `open` always writes — it is what `connections` counts. The web-ws upgrade
// used to be the source, but the desktop app never dials web-ws directly (only the daemon does, and
// only to relay a foreign machine), so a single-machine user was invisible there.
const USER_PRESENCE_WRITE_MS = 5 * 60_000
// `open` is not floored by the interval above (each one IS a session), but it is floored on its own:
// the window reconnects its local socket a few times a minute at worst during a daemon restart, and
// an adapter sending more than that is looping or lying — either way not a session per frame, and
// not a Mongo upsert per frame.
const USER_PRESENCE_OPEN_MS = 10_000
const APP_PRESENCE_KINDS = new Set(['open', 'ping'])
// `turn_started` tap (agent/machine daily presence). `agentId` is a plain token the CLI derives from
// its registry (a UUID, or the engine's own session id as fallback), so it is bounded and
// character-restricted before it becomes a Mongo index key — an oversized or exotic value would
// otherwise either fail the unique index (>1024-byte key) or let a misbehaving adapter mint an
// unbounded number of `agent_daily_presence` rows. The per-minute cap is the same idea for volume:
// a real turn is human-paced (a handful a minute across every agent on one machine), so anything
// past this is a bug or abuse and is dropped, never written.
const TURN_AGENT_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/
const TURN_WRITES_PER_MINUTE = 120
function sanitizeClientVersion(raw: string | null): string | undefined {
const v = raw?.trim()
return v && CLIENT_VERSION_RE.test(v) ? v : undefined
}
/** Adapter authentication is SSO-only: accept precisely the first WS subprotocol, never x-api-key. */
function accessTokenFromProtocol(req: IncomingMessage): string | undefined {
const raw = req.headers['sec-websocket-protocol']
const first = (Array.isArray(raw) ? raw[0] : raw)?.split(',')[0]?.trim()
return first || undefined
}
/** Fastify/http upgrade hook for `/api/adapter-ws`. Auth = user SSO access token. */
export function handleAdapterUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
// Reject with an explicit HTTP 401 (not a silent destroy) so the adapter's ws client surfaces
// "Unexpected server response: 401" — which it treats as a FATAL deauthorization (deleted/unknown
// machine) and clears its saved token, instead of an ambiguous close-1006 it would retry forever.
const deny = (): void => {
try { socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
socket.destroy()
}
// One computer per machine: when a DIFFERENT computer already holds this machine, reject with an
// explicit HTTP 409 (not 401 — the adapter treats 401/403 as deauth and would WIPE its valid token).
// The adapter surfaces 409 as an info message ("already connected from another computer") and stops.
const denyBusy = (): void => {
try { socket.write('HTTP/1.1 409 Conflict\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
socket.destroy()
}
// Billing suspension is retryable: unlike 401/403, the adapter must retain its token so it can
// reconnect automatically after the owner renews or re-subscribes.
const denyPayment = (): void => {
try { socket.write('HTTP/1.1 402 Payment Required\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
socket.destroy()
}
const accessToken = accessTokenFromProtocol(req)
if (!accessToken) { deny(); return }
// The adapter sends its computer's hostname as `?label=`, a stable `?computer=` id, its version,
// and the selected Autonomous environment. `computer` is required: without it the backend has no
// safe way to choose between a user's Remote machines.
let label: string | undefined
let computerId: string | undefined
let clientVersion: string | undefined
let claimedMachineId: string | undefined
let autonomousEnv: 'prod' | 'stag' = 'prod'
try {
const params = new URL(req.url ?? '', 'http://x').searchParams
label = params.get('label') || undefined
computerId = normalizeComputerId(params.get('computer') ?? '') ?? undefined
// The machine id this daemon still believes it is. Optional: a freshly logged-in CLI has none
// yet. When present it lets `resolveOrCreateForComputer` tell a REVOKED daemon apart from a
// first-time pairing, instead of silently minting it a replacement machine.
claimedMachineId = params.get('machine') || undefined
clientVersion = sanitizeClientVersion(params.get('v'))
autonomousEnv = parseAutonomousEnvironment(params.get('autonomousEnv'))
} catch { deny(); return }
if (!computerId) { deny(); return }
// Where this computer is, per Cloudflare (absent off-Cloudflare). Read once here, at the only point
// that still has the upgrade request, and carried into the machine row + its daily presence.
const countryCode = countryCodeFromHeaders(req.headers)
const forbid = (): void => {
try { socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n') } catch { /* ignore */ }
socket.destroy()
}
void (async () => {
let user
// A team session is taken here only as the machine of the computer it is bound to (below).
try { user = await authenticateAccessToken(accessToken, autonomousEnv, { allowHarnessSession: 'computer', allowTeamSession: true }) } catch (err) {
if (err instanceof SsoAuthError && (err.code === 'AUTONOMOUS_ENV_MISMATCH' || err.code === 'AUTONOMOUS_ENV_NOT_ALLOWED')) {
forbid()
return
}
deny()
return
}
const team = user.harnessSessionKind === 'team'
// Never another machine of the account: a team session names its own computer, or nothing is looked up at all.
if (team && computerId !== user.harnessComputerId) { forbid(); return }
let machine
if (team) {
machine = (await machineService.resolveForTeamComputer(user, computerId, label ?? 'computer', claimedMachineId)).machine
} else {
machine = (await machineService.resolveOrCreateForComputer(user.sub, user.autonomousEnv, computerId, label ?? 'computer', claimedMachineId, 'computer')).machine
// Before it attaches: a former team machine now served by a normal sign-in must not be read as a team machine. Any
// other row is stamped by the connect's own update below; until then it is not a team machine either.
if (machine.sessionKind === 'team') {
await prisma.machine.update({ where: { machineId: machine.machineId }, data: { sessionKind: 'computer' } })
machine = { ...machine, sessionKind: 'computer' }
}
}
const machineId = machine.machineId
if (!machineBillingAllowsDataPlane(machine)) { denyPayment(); return }
// Single-computer claim BEFORE upgrade/attach, so a rejected second computer never supersedes the first.
if (!(await claimMachineOwner(machineId, computerId, PRESENCE_TTL_SEC))) { denyBusy(); return }
const row = machine
wss.handleUpgrade(req, socket, head, (ws) => void attachAdapter(ws, row, label, computerId, clientVersion, countryCode, user.harnessSessionId, team))
// A computer is signed in as one account at a time: Swarm entries of the account signed in here before move to this one
// (superTabs/computerMoves.ts, #3122). Never awaited: the connect does not wait on Swarms.
if (!team) {
void computerSignedIn({ machineId, ownerId: user.sub, computerId, autonomousEnv: user.autonomousEnv })
.catch(error => logger.warn('[swarm] computer move failed', { machineId, error: String(error) }))
}
})().catch((err) => {
if (err instanceof AppError) {
// 403 is the revoked-machine answer from `resolveOrCreateForComputer`, 429 its new-id rate limit
// (the CLI retries it with backoff and keeps its token); the CLI keys off the numeric status, but
// sending it under the wrong reason phrase would mislead anyone reading a capture or a proxy log.
try { socket.write(`HTTP/1.1 ${err.statusCode} ${upgradeStatusText(err.statusCode)}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`) } catch { /* ignore */ }
socket.destroy()
return
}
logger.warn('adapter-ws upgrade failed', { error: String(err) })
socket.destroy()
})
}
/** The machine row as the upgrade read it: a connect writes only the facts that differ from it, and stamps only when its
* `lastSeenAt` is due. */
type AttachedMachine = Pick<Machine, 'machineId' | 'userId' | 'name' | 'hostname' | 'clientVersion' | 'computerId' | 'countryCode' | 'sessionKind' | 'lastSeenAt'>
async function attachAdapter(ws: WebSocket, machine: AttachedMachine, label?: string, computerId?: string, clientVersion?: string, countryCode?: string, harnessSessionId?: string, team = false): Promise<void> {
const { machineId, userId, name: currentName } = machine
// A different computer was already rejected at the upgrade (denyBusy), so this only closes our OWN
// stale local socket on a same-computer reconnect landing on this worker.
owners.get(machineId)?.close(4000, 'superseded')
owners.set(machineId, ws)
const send = (obj: unknown): boolean => guardedSendJson(ws, obj, 'must', { machineId, kind: 'adapter' })
// Its connect and disconnect lines (lib/wsAttribution.ts): 227 adapter reconnects in 45 minutes in prod (2026-10-28)
// could not be explained without the close codes.
const track = trackSocket('adapter', 'adapter', ws, { client: 'daemon', version: clientVersion ?? null, machineId, computer: label })
ws.once('close', (code: number, reason?: Buffer) => track.closed(code, reason?.toString()))
send({ t: 'connected', machineId })
// What changed for the ACCOUNT on some worker (its tabs, its machine list): this computer's app
// re-reads through its daemon rather than polling for it. See adapterAccountPushes.ts.
// A team machine reads none of the account's desk, zoo, machines or connections: it hears only the device-key pushes.
const accountPushesUnsub = await relayAccountPushes(userId, send, { zoo: DAEMONS.on, team })
// Work waiting for this machine's Swarm agents, team machine or not: its host reads it at once (swarmDeliveryPushes.ts).
const swarmPushesUnsub = await relaySwarmDeliveries(machineId, send)
// A commit that changed what this machine's host reads: it reads its Swarm changes at once (swarmHostPushes.ts, WS Phase 2a).
const swarmHostUnsub = await relaySwarmHostChanges(machineId, send)
// Last desktop-app state THIS socket asserted. Socket-scoped on purpose: a new adapter connection
// starts with no claim and must re-assert, so a fresh value can never renew a stale one.
let appState: { engine: string; state: string } | undefined
const terminalRate = new TerminalRateGuard()
// Fixed one-minute window for the `turn_started` tap — two integers, no timer, no allocation.
let turnWindowStart = 0
let turnWindowCount = 0
const allowTurnWrite = (nowMs: number): boolean => {
if (nowMs - turnWindowStart >= 60_000) { turnWindowStart = nowMs; turnWindowCount = 0 }
return ++turnWindowCount <= TURN_WRITES_PER_MINUTE
}
const shortTurns = new ShortTurnGuard()
const p2pSignalRate = new P2pSignalRateGuard()
// A machine appends its own key once per sign-in, a removal when someone asks for one: a few a minute
// is generous, and it keeps a looping daemon from rebuilding the log on every frame.
const devlogRate = { windowStart: 0, count: 0, allow(): boolean {
const now = Date.now()
if (now - this.windowStart >= 60_000) { this.windowStart = now; this.count = 0 }
return ++this.count <= 10
} }
// Buffer messages from RIGHT NOW, because the real handler cannot be installed until after the
// `await attachNodeRole(...)` below — and `ws` drops any message emitted with no listener attached.
// An adapter that (reasonably) sends as soon as its socket opens therefore lost its FIRST frame,
// every time. That was invisible for a long while because the CLI's first frame is a resend-on-tick,
// so it just looked like a one-tick delay; an adapter whose first frame is one-shot state lost it
// outright. Buffer, then replay in order once the handler exists.
const preHandlerQueue: Array<[RawData, boolean]> = []
let onMessage: ((raw: RawData, isBinary: boolean) => void) | null = null
ws.on('message', (raw: RawData, isBinary: boolean) => {
markCpuKind(isBinary ? 'adapter-ws binary' : 'adapter-ws text')
if (onMessage) onMessage(raw, isBinary)
else if (preHandlerQueue.length < 64) preHandlerQueue.push([raw, isBinary])
})
// Two separate fields, deliberately: `hostname` tracks whichever computer connected LAST, while
// `name` is the user-editable display name and is only ever SEEDED here — a connect must never
// clobber a name the owner set. Best-effort; never blocks the connection.
const seededName = !currentName?.trim() && label ? label.slice(0, 120) : null
// Normalized on the way to Mongo so this column matches what the device-auth grant stamps — the
// reuse lookup is an equality match on it. The RAW `computerId` keeps driving the Redis owner claim
// (see the upgrade handler): that key is a self-consistent liveness token nothing joins against, and
// re-keying it would 409 every already-connected adapter until its old claim aged out.
const boundComputer = computerId ? normalizeComputerId(computerId) : null
// Each overwrite-every-connect fact (`hostname`, `clientVersion`, `computerId`, `countryCode`: absent from an old client
// or off Cloudflare leaves the last value), the seeded name, and which kind of sign-in serves the machine now
// (lib/teamSession.ts; a team row was checked, and a former team row flipped, before the socket attached). Only the ones
// that differ from the row are written, in the connect's one update with its stamp (touchMachinePresence below): a
// reconnect used to rewrite them all and stamp separately, two updates of one row at once (#2676).
const connectChanges = machineConnectChanges(machine, {
hostname: label?.slice(0, 120), name: seededName ?? undefined, clientVersion, computerId: boundComputer ?? undefined, countryCode,
sessionKind: team ? 'team' : 'computer',
})
// Tell the adapter its machine's display name (it mirrors it locally for `harness status`); null when
// unnamed so a stale mirror clears. Renames while connected arrive the same way (machine_meta).
// The account's private harness grid, carried on the frame the adapter already gets on connect.
// Minted and remembered by `routes/grid.ts`; read-only here. A user who has never signed in since
// the route shipped simply has none yet, and the daemon treats that as "no grid" rather than an
// error — the next `harness login` mints it.
// Never on a team machine (lib/teamSession.ts): the grid is the person's inference endpoint, not teammates'.
const gridName = team ? null : (await prisma.user.findUnique({ where: { id: userId }, select: { gridName: true } })
.catch(() => null))?.gridName ?? null
send({ t: 'down', connId: '', frame: { type: 'machine_meta', payload: { name: currentName?.trim() || seededName, gridName } } })
// The machine's last-seen stamp (plus the fleet's connect total), mirroring the user/device variants in
// webWs/deviceWs. The guard only advances on a SUCCESSFUL write, so a transient DB failure is retried on the next
// heartbeat instead of being silently skipped until the interval elapses again. Heartbeats also
// skip while a write is still in flight: `onHeartbeat` fires from two 15s sources (node role
// interval + app ping), and before the connect write lands `presenceWriteDue` would say "due" —
// without this a slow Mongo gets a second concurrent upsert precisely when it is already slow.
// The floor starts from the row's own stamp, not from this socket: a reconnect a minute after the last stamp neither
// stamps on connect nor on its first heartbeat (#2676). A close stamps the "offline since" unless the row was stamped less
// than MACHINE_CLOSE_FLOOR_MS ago.
const lastMachinePresence: PresenceWriteState = presenceStateFromRow(machine.lastSeenAt)
let machinePresenceInFlight = false
// The connect's changed facts until a write carries them: a failed connect write is retried by the next heartbeat.
let pendingChanges: MachineConnectChanges = {}
const touchMachinePresence = (kind: 'connect' | 'heartbeat' | 'close', changes?: MachineConnectChanges): void => {
const now = new Date()
if (changes) pendingChanges = changes
const carried = pendingChanges
const due = kind === 'close' ? presenceWriteDue(lastMachinePresence, now, MACHINE_CLOSE_FLOOR_MS)
: presenceWriteDue(lastMachinePresence, now, MACHINE_PRESENCE_WRITE_MS)
if (kind === 'heartbeat' && machinePresenceInFlight) return
if (kind !== 'connect' && !due && !Object.keys(carried).length) return
const stamp = due
machinePresenceInFlight = true
touchMachineOnlineDay(userId, machineId, now, { isNewConnection: kind === 'connect', countryCode, changes: carried, stamp })
.then(() => {
if (pendingChanges === carried) pendingChanges = {}
if (stamp) { lastMachinePresence.dayKey = utcDayKey(now); lastMachinePresence.wroteAt = now.getTime() }
})
.catch((err) => logger.warn('machine presence tracking failed', { machineId, kind, error: String(err) }))
.finally(() => { machinePresenceInFlight = false })
}
// Same shape for the person behind the app: `open` bypasses the interval the way `connect` does
// above, `ping` is rate-floored. `userId` is the machine's owner — the only person a desktop app
// on this computer can be signed in as. The row is keyed by THIS machine too, so the same person
// on a second computer lands in a second row rather than in this one.
const userPresenceFloors = { pingFloorMs: USER_PRESENCE_WRITE_MS, openFloorMs: USER_PRESENCE_OPEN_MS }
const touchUserPresence = presenceTracker(
(now, isNewConnection) => touchUserOnlineDay(userId, machineId, now, { isNewConnection }),
(kind, err) => logger.warn('user presence tracking failed', { machineId, userId, kind, error: String(err) }),
userPresenceFloors,
)
// `harness tui` on this computer: the daemon reports it like a window but names the surface, and it
// is kept out of the desktop app's table (`user_daily_client_presence`, schema.prisma).
// One tracker per surface it reports (TUI_SURFACES): each is its own row and its own write floor.
const tuiTrackers = new Map<ClientSurface, ReturnType<typeof presenceTracker>>()
const touchTuiPresence = (surface: ClientSurface, kind: 'open' | 'ping') => {
let track = tuiTrackers.get(surface)
if (!track) {
track = presenceTracker(
(now, isNewConnection) => touchClientOnlineDay(userId, surface, now, { isNewConnection }),
(k, err) => logger.warn('tui presence tracking failed', { machineId, userId, surface, kind: k, error: String(err) }),
userPresenceFloors,
)
tuiTrackers.set(surface, track)
}
track(kind)
}
// The node role — down subscription, presence, `__clients` resync, node_status — is shared with
// every other backer of a machine and lives in nodeRole.ts. Only the delivery and teardown are
// adapter-specific, so only those are passed in.
const role = await attachNodeRole({
machineId,
owner: 'remote',
offlineReason: 'remote computer offline',
deliver: (msg) => {
if (ws.readyState !== WebSocket.OPEN) return
// Its computer just turned itself into a team machine (lib/harnessSession.ts): a socket still connected under the
// old sign-in must not keep serving a machine marked `team`. Backend-only (`__`), never forwarded.
if ((msg.frame as { type?: string } | undefined)?.type === TEAM_CONVERTED_FRAME) {
if (!team) { try { ws.close(4009, 'now a team machine') } catch { /* ignore */ } }
return
}
send({ t: 'down', connId: msg.connId, frame: msg.frame })
// `machine_revoked` used to be pushed and nothing more, leaving the socket open and the machine
// still serving if the client ignored it — an old CLI, a dropped frame. Close it ourselves right
// after the send so revocation does not depend on the client cooperating. Same shape as
// onBillingSuspended below; the close must happen HERE rather than in MachineService because the
// socket may live on another backend instance, reachable only through the Redis fan-out.
if ((msg.frame as { type?: string } | undefined)?.type === 'machine_revoked') {
try { ws.close(4004, 'machine revoked') } catch { /* ignore */ }
}
},
onBillingSuspended: () => {
// Close the live machine session WITHOUT revoking its saved token: the adapter's normal retry
// loop then receives HTTP 402 until billing is restored, and reconnects by itself afterwards.
try { ws.close(4003, 'subscription required') } catch { /* ignore */ }
},
onHeartbeat: () => {
if (computerId) void claimMachineOwner(machineId, computerId, PRESENCE_TTL_SEC) // renew the one-computer claim
// Same tick renews the app-state key, so it shares presence's TTL and can never outlive it.
if (appState) void setMachineAppState(machineId, appState.engine, appState.state, PRESENCE_TTL_SEC)
touchMachinePresence('heartbeat') // throttled inside — see MACHINE_PRESENCE_WRITE_MS
},
})
touchMachinePresence('connect', connectChanges)
const terminalDownUnsub = await subscribeTerminalDown(machineId, (packet) => {
// Terminal input toward the adapter is 'must': dropping keystrokes is not recoverable client-side.
guardedSend(ws, packet, 'must', { machineId, kind: 'adapter' })
})
// Liveness. The previous implementation pinged every 25 s and terminated on a single missed PONG —
// and counted pongs only, so an adapter that was actively sending application traffic could still
// be killed if one pong went missing. `trackSocketLiveness` counts message/ping/pong against a time
// deadline instead, which is the same fix already applied to the hub's own sockets.
const releaseLiveness = trackSocketLiveness(ws, 'adapter')
// Frames for one viewer go straight to it when it is on this process, else to the process holding it
// (lib/terminalRoute.ts); a connection keeps the route its first frame took for this socket's life.
const routes = createConnectionRoutes(machineId)
// A frame for one connection takes its route; a target that is not a plausible connection id (the daemon sets it) is
// published as before, never used as a route or Redis key.
const sendTargeted = (msg: UpBusMsg & { targetConnId: unknown }): void => {
const target = msg.targetConnId
if (typeof target === 'string' && target.length > 0 && target.length <= 128) routes.targeted({ ...msg, targetConnId: target })
else void publishUp(machineId, msg as UpBusMsg)
}
onMessage = (raw: RawData, isBinary: boolean): void => {
if (isBinary) {
const hop = decodeTerminalHop(new Uint8Array(raw as Buffer))
if (!hop || hop.direction !== TerminalHopDirection.up
|| (hop.kind !== TerminalBinaryKind.output && hop.kind !== TerminalBinaryKind.keyframe
&& hop.kind !== TerminalBinaryKind.sync)
|| !terminalRate.allow(
hop.kind === TerminalBinaryKind.output
? 'terminal_output'
: hop.kind === TerminalBinaryKind.keyframe ? 'terminal_keyframe' : 'terminal_sync',
hop.clientFrame.length,
)) return
routes.hop(Buffer.from(raw as Buffer), hop.connId)
return
}
let env: AdapterFrame
try { env = JSON.parse(raw.toString()) as AdapterFrame } catch { return }
if (env.t === 'ping') {
role.touch() // refreshes presence and renews the machine claim
return
}
if (env.t === 'up' && env.frame) {
const terminalType = env.frame.type as string | undefined
if (typeof terminalType === 'string' && terminalType.startsWith('terminal_')) {
if (!TERMINAL_UP_TYPES.has(terminalType)) return
const bytes = terminalFrameBytes(env.frame)
if (!env.targetConnId || bytes > TERMINAL_ENVELOPE_MAX_BYTES
|| !isEncryptedTerminalFrame(env.frame) || !terminalRate.allow(terminalType, bytes)) return
sendTargeted({
webEligible: true,
commanderEligible: false,
targetConnId: env.targetConnId,
targetKind: 'web',
frame: env.frame,
})
return
}
if (typeof terminalType === 'string' && terminalType.startsWith('p2p_')) {
const bytes = p2pFrameBytes(env.frame)
if (!P2P_UP_TYPES.has(terminalType) || !env.targetConnId
|| !terminalP2pPolicy(userId, machineId).enabled
|| bytes > P2P_SIGNAL_MAX_BYTES || !isEncryptedP2pFrame(env.frame)
|| !p2pSignalRate.allow(bytes)) return
sendTargeted({
webEligible: true,
commanderEligible: false,
targetConnId: env.targetConnId,
targetKind: 'web',
frame: env.frame,
})
return
}
// Desktop-app presence. Handled in full here and NEVER falls through to the generic publish:
// the eligibility flags are forced false locally rather than trusted from the frame, so no
// adapter can fan an unknown frame type out to web clients or devices. Validated against a
// closed vocabulary so an arbitrary string can never reach the enum the firmware parses.
// Unchanged values are suppressed (the heartbeat keeps the TTL alive), which caps a chatty
// adapter at the heartbeat rate.
const app = env.frame as { type?: string; payload?: { engine?: unknown; state?: unknown } }
if (app.type === 'machine_app_status') {
const engine = typeof app.payload?.engine === 'string' ? app.payload.engine : ''
const state = typeof app.payload?.state === 'string' ? app.payload.state : ''
if (!APP_ENGINES.has(engine) || !APP_STATES.has(state)) return
if (appState?.engine === engine && appState.state === state) return
appState = { engine, state }
void setMachineAppState(machineId, engine, state, PRESENCE_TTL_SEC)
void publishUp(machineId, {
webEligible: false,
commanderEligible: false,
frame: { type: 'machine_app_status', payload: { engine, state } } as unknown as Frame,
})
return
}
// The daemon saying a desktop window is attached to it (cli backendSocket sendAppPresence).
// Bookkeeping only — absorbed here, never published: no client has any use for it and an
// unknown frame type must not reach the firmware.
if (app.type === 'app_presence') {
const { kind, surface } = (app.payload ?? {}) as { kind?: unknown; surface?: unknown }
if (typeof kind !== 'string' || !APP_PRESENCE_KINDS.has(kind)) return
// No surface = the desktop app (every daemon before this field, and the desktop window now). A
// TUI says where it runs (TUI_SURFACES); a name this backend does not know counts as nothing,
// never as the desktop app.
if (surface === undefined) touchUserPresence(kind as 'open' | 'ping')
else if (typeof surface === 'string' && TUI_SURFACES.has(surface)) {
touchTuiPresence(surface as ClientSurface, kind as 'open' | 'ping')
// Its account's daemons relay the events only a terminal app reads while one is open (bus.ts noteTuiPresence).
void noteTuiPresence(userId, kind as 'open' | 'ping')
}
return
}
// The machine appending to its account's device key log (lib/deviceKeyLog.ts): its own key, or a
// removal it signs. Over THIS socket so the entry is tied to the machine that sent it — a
// machine can only register a key under its own id. Answered to the machine alone, never published.
if (app.type === 'devlog_append') {
const p = (app.payload ?? {}) as { requestId?: unknown; entry?: unknown }
const requestId = typeof p.requestId === 'string' ? p.requestId.slice(0, 64) : ''
if (!devlogRate.allow()) {
send({ t: 'down', connId: '', frame: { type: 'devlog_append_result', payload: { requestId, error: 'RATE_LIMITED' } } })
return
}
void appendDeviceKey(userId, p.entry, { kind: 'machine', machineId, ...(harnessSessionId ? { harnessSessionId } : {}), ...(team ? { team } : {}) })
.then((r) => send({ t: 'down', connId: '', frame: { type: 'devlog_append_result', payload: r.ok
? { requestId, head: r.head }
: { requestId, error: r.code, ...('head' in r ? { head: r.head } : {}) } } }))
.catch((err) => {
logger.warn('devlog append failed', { machineId, error: String(err) })
send({ t: 'down', connId: '', frame: { type: 'devlog_append_result', payload: { requestId, error: 'UNAVAILABLE' } } })
})
return
}
// Hub tap (mirrors managerWs): keep `machine_agents` in sync from the adapter's agent
// lifecycle frames. Needed so the device voice path's agent-ownership check
// (deviceWs: `machineAgent.findFirst`) recognizes remote tmux sessions.
const f = env.frame as { type?: string; agentId?: unknown; replay?: unknown; payload?: { agent?: unknown; agentId?: unknown; machineId?: unknown } }
if (f.type === 'agent_synced') {
void recordCreatedAgent(machineId, f.payload?.agent as { id?: unknown; name?: unknown } | undefined)
} else if (f.type === 'agent_deleted' && typeof f.payload?.agentId === 'string') {
// Every producer sends `agentId` (machine-adapter cli.ts, machine-node websocket.ts/agents.ts).
// Reading `machineId` here meant no deletion was EVER recorded, so machine_agents grew a row per
// agent forever — and that table is what the plan cap counts.
void recordDeletedAgent(machineId, f.payload.agentId)
} else if (f.type === 'turn_started' && f.replay !== true) {
// Usage signal for machine_daily_presence / agent_daily_presence. Only the plaintext `type`,
// top-level `agentId` and `replay` (set by the CLI's correlateAgentEvent / emitSessionEvents)
// are read — the payload is E2EE ciphertext (cli e2ee/core.ts ENCRYPTED_UP_TYPES) and stays
// opaque here. The CLI already dedupes engines that re-announce one turn (cursor/agy/copilot,
// cli.ts), so one frame == one turn. `replay: true` is the CLI saying this one did NOT start
// now — a turn resumed at attach, or a prompt re-read from a transcript already on disk
// (measured 2026-09-17: 42 such frames in one second credited to one agent). It still relays,
// it is just not a turn today. A frame with no (or a malformed) agentId has nothing to
// attribute the turn to and is not counted.
// A machine starting turns in a loop (lib/shortTurnGuard.ts): past the cap its turn starts are neither counted
// nor relayed for a while. Everything else it sends still is.
const verdict = shortTurns.admit()
if (verdict !== 'relay') {
if (verdict === 'pause_started') logger.warn('machine is starting turns in a loop; holding its turn starts for 60 s', { machineId, userId })
return
}
const now = new Date()
const agentId = typeof f.agentId === 'string' && TURN_AGENT_ID_RE.test(f.agentId) ? f.agentId : undefined
if (agentId && allowTurnWrite(now.getTime())) {
void recordTurnStarted(userId, machineId, agentId, now, team)
.catch((err) => logger.warn('turn tracking failed', { machineId, agentId, error: String(err) }))
}
}
if (env.userEligible) {
// A team machine raises no notice on the person's apps: pairing a device with a machine is the person's to start.
if (!team) {
void publishUserDeviceE2eePair(userId, machineId, env.frame).catch((err) => {
logger.warn('adapter user-level e2ee pair publish failed', { machineId, userId, error: String(err) })
})
}
if (env.webEligible === false && env.commanderEligible !== true && !env.targetConnId) return
}
const up = {
webEligible: env.webEligible !== false, // default true (plain event/RPC frames)
commanderEligible: env.commanderEligible === true, // devices get only opted-in frames
frame: env.frame,
}
// An E2EE per-client push (pairing, welcome, an RPC reply) takes its connection's route, so it keeps its order with
// that connection's terminal frames.
if (env.targetConnId) { sendTargeted({ ...up, targetConnId: env.targetConnId }); return }
// Every client of the machine: this process's own first, then the rest through Redis, whose copy this process
// skips (originPid), as manager-ws does. A local viewer's targeted frames are delivered here at once, so its
// untargeted ones must be too, or an RPC reply would overtake the event the daemon sent before it (review 2026-10-31).
deliverUpLocal(machineId, up)
void publishUp(machineId, { ...up, originPid: PROCESS_ID }).then(n => recordRelay('up broadcast', 'published', n))
}
}
// Drain whatever arrived while the role was being attached, in the order it was sent.
for (const [raw, isBinary] of preHandlerQueue) onMessage(raw, isBinary)
preHandlerQueue.length = 0
const cleanup = (): void => {
releaseLiveness()
routes.close()
terminalDownUnsub()
accountPushesUnsub()
swarmPushesUnsub()
swarmHostUnsub()
// Only the CURRENT owner tears the role down — a superseded socket must not mark the fresh
// connection offline. A superseded socket still releases its own liveness tracking above.
if (owners.get(machineId) === ws) {
owners.delete(machineId)
void role.detach()
if (computerId) void releaseMachineOwner(machineId, computerId) // free the claim (compare-and-delete)
// Drop the app claim with the socket. role.detach() already publishes node_status{online:false},
// and every row builder omits the app keys when offline, so the device converges on that frame;
// this delete is what stops a reconnect from briefly re-reading the dead value.
void clearMachineAppState(machineId)
touchMachinePresence('close') // lastSeenAt at disconnect, floored (MACHINE_CLOSE_FLOOR_MS); a superseded socket must not stamp it
}
}
ws.on('close', cleanup)
ws.on('error', cleanup)
}
async function publishUserDeviceE2eePair(userId: string, machineId: string, frame: Frame): Promise<void> {
const type = frame.type as string | undefined
if (type !== 'device_e2ee_pair_pending' && type !== 'device_e2ee_pair_cleared') return
const p = (frame.payload ?? {}) as Record<string, unknown>
const pairId = typeof p.pairId === 'string' ? p.pairId : ''
if (!pairId) return
const machine = await prisma.machine.findUnique({
where: { machineId },
select: { name: true },
})
const base = {
machineId,
machineName: machine?.name ?? null,
pairId,
computerFingerprint: typeof p.computerFingerprint === 'string' ? p.computerFingerprint : null,
}
if (type === 'device_e2ee_pair_pending') {
await publishDeviceE2eePair(userId, {
kind: 'pending',
...base,
label: typeof p.label === 'string' ? p.label : 'Device',
expiresAt: typeof p.expiresAt === 'number' ? p.expiresAt : Date.now() + 60_000,
})
return
}
const result = p.result === 'paired' || p.result === 'failed' || p.result === 'cancelled' ? p.result : 'failed'
await publishDeviceE2eePair(userId, { kind: 'cleared', ...base, result })
}