Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
dd36ae3b4This file is pinned to the selected release. Download the original to open it in your design tool.
import { randomUUID } from 'node:crypto'
import type http from 'node:http'
import type { Socket } from 'node:net'
import { WebSocket, WebSocketServer, type RawData } from 'ws'
import type { Frame, LocalClientSink } from './backendSocket.js'
import { decodeTerminalLocal, TERMINAL_BINARY_VERSION, type TerminalBinaryClear } from './lib/terminalBinary.js'
import { RelayConnectError, type RelaySession, type RemoteRelayPool } from './lib/remoteRelay.js'
export const LOCAL_WS_PATH = '/api/local-ws'
export const LOCAL_WS_PROTOCOL_VERSION = 1
const MAX_JSON_BYTES = 512 * 1024
const HEARTBEAT_MS = 20_000
export interface LocalWsBackend {
registerLocalClient: (connId: string, sink: LocalClientSink) => boolean
unregisterLocalClient: (connId: string) => Promise<void>
handleLocalFrame: (connId: string, frame: Frame) => void
handleLocalBinary: (connId: string, frame: TerminalBinaryClear) => Promise<void>
}
export interface LocalWsServerOptions {
machineId: string
backend: LocalWsBackend
/** Serves a `machine_select` for any OTHER machine this signed-in user owns, by relaying to
* backend's `/api/web-ws` — see lib/remoteRelay.ts. Omit to keep today's own-machine-only behavior. */
relayPool?: RemoteRelayPool
autonomousEnv?: string
/** The desktop app opened an agent's terminal — which agent, and on which machine. Lets the dial follow
* the window, so the two screens stay one desk. */
onAppFocus?: (machineId: string, agentId: string) => void
/** Every agent the window currently has a tile for, across all its machines. */
onAppPanes?: (agentIds: string[]) => void
}
export interface LocalWsServer {
close: () => Promise<void>
}
function isLoopback(address: string | undefined): boolean {
return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1'
}
function rejectUpgrade(socket: Socket, status: number, reason: string): void {
if (socket.destroyed) return
socket.end(
`HTTP/1.1 ${status} ${reason}\r\n` +
'Connection: close\r\n' +
'Content-Length: 0\r\n' +
'\r\n',
)
}
function jsonFrame(raw: RawData): Frame | null {
const bytes = Buffer.isBuffer(raw)
? raw
: raw instanceof ArrayBuffer
? Buffer.from(raw)
: Array.isArray(raw)
? Buffer.concat(raw)
: Buffer.alloc(0)
if (!bytes.length || bytes.length > MAX_JSON_BYTES) return null
try {
const value = JSON.parse(bytes.toString('utf8')) as unknown
if (!value || typeof value !== 'object' || Array.isArray(value)) return null
const frame = value as Frame
return typeof frame.type === 'string' && frame.type.length <= 100 ? frame : null
} catch {
return null
}
}
function binaryBytes(raw: RawData): Uint8Array {
if (Buffer.isBuffer(raw)) return new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)
if (raw instanceof ArrayBuffer) return new Uint8Array(raw)
if (Array.isArray(raw)) return new Uint8Array(Buffer.concat(raw))
return new Uint8Array()
}
/**
* Add an internal loopback WebSocket endpoint to the CLI's existing HTTP server. It intentionally has
* no credential: loopback-only, no Origin header, and the desktop computer-id validation identify the
* local process without placing SSO credentials on this transport.
*/
export function attachLocalWsServer(server: http.Server, options: LocalWsServerOptions): LocalWsServer {
const wss = new WebSocketServer({
noServer: true,
maxPayload: MAX_JSON_BYTES,
// The loopback endpoint deliberately has no credential. Echo a protocol only for generic WS
// clients that insist on proposing one; it carries no authority and is never inspected.
handleProtocols: (protocols) => [...protocols][0] ?? false,
})
const onUpgrade = (req: http.IncomingMessage, socket: Socket, head: Buffer): void => {
const path = (req.url ?? '').split('?')[0]
if (path !== LOCAL_WS_PATH) return
if (!isLoopback(req.socket.remoteAddress)) {
rejectUpgrade(socket, 403, 'Forbidden')
return
}
if (req.headers.origin) {
rejectUpgrade(socket, 403, 'Forbidden')
return
}
wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req))
}
server.on('upgrade', onUpgrade)
wss.on('connection', (ws) => {
const connId = `local:${randomUUID()}`
let selected = false
// Which machine THIS connection is bound to. The app opens one local socket per machine, so it is
// fixed for the life of the connection — set once, beside `selected`.
let boundMachineId: string | null = null
let relay: RelaySession | null = null
/** Whether this connection ever reported a tile roster — only then is clearing it ours to do. */
let sentPanes = false
let alive = true
let chain = Promise.resolve()
const sink: LocalClientSink = {
sendFrame: (frame) => {
if (ws.readyState !== WebSocket.OPEN) return false
try { ws.send(JSON.stringify(frame)); return true } catch { return false }
},
sendBinary: (frame) => {
if (ws.readyState !== WebSocket.OPEN) return false
try { ws.send(frame, { binary: true }); return true } catch { return false }
},
}
const close = (code: number, reason: string): void => {
try { ws.close(code, reason) } catch { ws.terminate() }
}
ws.on('pong', () => { alive = true })
ws.on('message', (raw, isBinary) => {
chain = chain.then(async () => {
if (!selected) {
if (isBinary) { close(4400, 'machine_select required'); return }
const frame = jsonFrame(raw)
const payload = frame?.payload as Record<string, unknown> | undefined
const requestedMachineId = payload?.machineId
if (typeof requestedMachineId === 'string') boundMachineId = requestedMachineId
if (frame?.type !== 'machine_select'
|| typeof requestedMachineId !== 'string'
|| payload?.localProtocolVersion !== LOCAL_WS_PROTOCOL_VERSION) {
close(4403, 'machine mismatch')
return
}
if (requestedMachineId === options.machineId) {
if (!options.backend.registerLocalClient(connId, sink)) {
close(1011, 'local registration failed')
return
}
selected = true
sink.sendFrame({
type: 'connected',
payload: {
machineId: options.machineId,
transport: 'local',
localProtocolVersion: LOCAL_WS_PROTOCOL_VERSION,
terminalProtocolVersion: TERMINAL_BINARY_VERSION,
e2ee: false,
},
})
return
}
// Not this daemon's own machine — relay to backend for the other machines this same
// signed-in user owns, if the daemon was wired up to do that (see lib/remoteRelay.ts).
if (!options.relayPool || !options.autonomousEnv) {
close(4403, 'machine mismatch')
return
}
// The local client observed a live RPC time out against an otherwise-"connected" machine —
// its pooled entry is suspect (most commonly the relayed machine's own Harness process
// restarted, dropping its E2EE session without the transport itself ever closing). Drop it
// so this select dials fresh instead of handing back the same dead session again.
if (payload?.forceReconnect === true) options.relayPool.invalidate(requestedMachineId)
try {
relay = await options.relayPool.acquire(requestedMachineId, options.autonomousEnv, frame, sink, close)
selected = true
} catch (err) {
const noPeerLink = err instanceof RelayConnectError && err.message === 'NO_PEER_LINK'
const code = noPeerLink ? 4404 : err instanceof RelayConnectError && err.closeCode ? err.closeCode : 1011
close(code, err instanceof Error ? err.message.slice(0, 120) : 'relay failed')
}
return
}
// THE APP MOVED — tell whoever wants to follow it, before the frame is dispatched either way.
// Sniffed here rather than in the backend socket because that path never sees a RELAYED machine's
// frames: those are forwarded upstream a few lines below and would be invisible, which is exactly
// the case that matters — the dial has to follow the window onto ANOTHER machine too.
// The window's tile ROSTER. Consumed here like `app_focus` — it describes
// a screen at this desk, not anything the machine could act on.
//
// It carries every agent the window has open, INCLUDING ones belonging
// to other machines, and the app sends the same list to every daemon it
// is connected to. That is deliberate: the dial is served by whichever
// daemon owns the cable, and only a full picture lets that one decide
// whether a finished turn is already in front of the person.
if (!isBinary && options.onAppPanes) {
const roster = jsonFrame(raw)
if (roster?.type === 'app_panes') {
const raw = (roster.payload as Record<string, unknown> | undefined)?.agentIds
const ids = Array.isArray(raw) ? raw.filter((id): id is string => typeof id === 'string' && id !== '') : []
sentPanes = true
options.onAppPanes(ids)
return
}
}
if (!isBinary && options.onAppFocus && boundMachineId) {
const moved = jsonFrame(raw)
const agentId = (moved?.payload as Record<string, unknown> | undefined)?.agentId
if (typeof agentId === 'string' && agentId) {
// `app_focus` is the window SAYING where it is looking. `terminal_open` is it being
// inferred from a side effect, which is all there was when a window could only show one
// terminal: every move opened a stream, so opening one meant it had moved.
//
// A pane grid breaks that equivalence. Clicking a tile that already holds a live session
// opens nothing at all, so the dial never heard about it and stayed on the agent the last
// rail click had opened. Both are still read: an older app build only sends the second.
if (moved?.type === 'app_focus') {
options.onAppFocus(boundMachineId, agentId)
// Consumed here. It describes a hand at THIS desk and the machine has no use for it —
// forwarding it would put an unknown frame type on the wire for every pane click.
return
}
if (moved?.type === 'terminal_open') options.onAppFocus(boundMachineId, agentId)
}
}
if (relay) {
// The relay now terminates E2EE itself (lib/remoteRelay.ts) — every frame past this point is
// already plaintext going in and out, so binary frames use the SAME local wire format as this
// daemon's own machine.
if (isBinary) {
const clear = decodeTerminalLocal(binaryBytes(raw))
if (!clear) { close(4400, 'invalid terminal frame'); return }
await relay.sendBinary(clear)
return
}
const frame = jsonFrame(raw)
if (!frame) { close(4400, 'invalid json frame'); return }
await relay.send(frame)
return
}
if (isBinary) {
const frame = decodeTerminalLocal(binaryBytes(raw))
if (!frame) { close(4400, 'invalid terminal frame'); return }
await options.backend.handleLocalBinary(connId, frame)
return
}
const frame = jsonFrame(raw)
if (!frame) { close(4400, 'invalid json frame'); return }
options.backend.handleLocalFrame(connId, frame)
}).catch(() => close(1011, 'local dispatch failed'))
})
const heartbeat = setInterval(() => {
if (!alive) { ws.terminate(); return }
alive = false
try { ws.ping() } catch { ws.terminate() }
}, HEARTBEAT_MS)
heartbeat.unref?.()
const cleanup = (): void => {
clearInterval(heartbeat)
// A window that went away has no tiles open. Left standing, the roster
// would keep silencing the dial for agents nobody can see any more —
// exactly backwards, and permanently.
if (sentPanes) options.onAppPanes?.([])
if (relay) { relay.detach(); relay = null }
else if (selected) void options.backend.unregisterLocalClient(connId)
selected = false
}
ws.once('close', cleanup)
ws.once('error', () => { /* close performs cleanup */ })
})
return {
close: async () => {
server.off('upgrade', onUpgrade)
for (const client of wss.clients) client.close(1001, 'server shutting down')
await new Promise<void>((resolve) => wss.close(() => resolve()))
},
}
}