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
/**
* A recording proxy in front of a local backend: every client in a socket scenario dials this instead
* of the backend, so what it records is what the backend was asked, whatever the backend logs.
*
* Per WebSocket it keeps the endpoint, the client kind and version the client declared on the URL, read as
* the backend reads them (`declaredKind`), when it opened and closed and with which code, and each
* `machine_select` it sent with the backend's answer (`connected` → accepted, `machine_select_error` →
* its code). An upgrade the backend refused is a refusal, never a socket. HTTP requests are counted by
* method and route, ids folded to `:id`.
*
* Written for the WebSocket roadmap (Ken, 2026-10-28): Phase 0 and Phase 1 are judged on connects a
* minute, socket lifetime, sockets that never selected, attribution and selects of deleted machines,
* and the backend's own Phase 0 logs cannot be the measure of whether Phase 0 worked.
*/
import { createServer, request, type IncomingMessage, type Server } from 'node:http'
import { once } from 'node:events'
import type { Duplex } from 'node:stream'
import WebSocket, { WebSocketServer, type RawData } from 'ws'
export interface SelectRecord { machineId: string; at: number; outcome: string | null }
export interface SocketRecord {
endpoint: string
/** One of `CLIENT_KINDS`, or `unknown`. */
client: string
version: string | null
openedAt: number
closedAt: number | null
closeCode: number | null
closeReason: string
selects: SelectRecord[]
/** The meter entry it came through (`entry()`), which tells apart clients that declare the same; null for the main one. */
via: string | null
}
export interface RefusalRecord { endpoint: string; status: number; at: number }
export interface MeterRecords {
startedAt: number
sockets: SocketRecord[]
refused: RefusalRecord[]
http: Record<string, number>
}
export interface EndpointReport {
connects: number
connectsPerMinute: number
refused: number
/** Over every socket; one still open counts its age at the report. */
medianLifetimeMs: number
livedUnder2s: number
closedWithoutSelect: number
/** The share of connects that named both a client kind and a version. */
attributed: number
/** The same share for each client kind seen, `unknown` included. */
attributedByClient: Record<string, number>
closeCodes: Record<string, number>
selectOutcomes: Record<string, number>
deletedMachineSelects: number
selectsByMachine: Record<string, number>
/** Sockets whose select was accepted and that closed within a minute: a healthy socket dropped. */
acceptedThenDiedUnder1m: number
}
export interface MeterReport {
durationMs: number
endpoints: Record<string, EndpointReport>
http: Record<string, number>
}
/** The kinds the backend tells apart (backend/src/lib/wsAttribution.ts `WS_CLIENT_KINDS`, #2029). */
export const CLIENT_KINDS = ['web', 'mobile', 'desktop', 'relay', 'group-sync', 'link', 'daemon']
const VERSION = /^[0-9A-Za-z.+-]{1,40}$/
/**
* What a socket's query declares, by #2029's rule (wsAttribution.ts `declaredKind`): a kind it does not know is
* `unknown`; the version is `v=` (the phone's `release=`) when it is a short plain token. The adapter's socket is
* the daemon's whatever it declares, as the backend tracks it.
*/
export function declaredKind(endpoint: string, query: URLSearchParams): { client: string; version: string | null } {
const declared = endpoint === '/api/adapter-ws' ? 'daemon' : query.get('client') ?? ''
const version = query.get('v') ?? query.get('release')
return { client: CLIENT_KINDS.includes(declared) ? declared : 'unknown', version: version && VERSION.test(version) ? version : null }
}
/** Hex ids (machine ids, share ids), UUIDs and numbers in a path, folded so a route counts as one. */
export function routeOf(method: string, url: string): string {
const path = url.split('?')[0]
.split('/')
.map((part) => /^[0-9a-f]{16,}$/i.test(part) || /^[0-9a-f-]{36}$/i.test(part) || /^\d+$/.test(part) ? ':id' : part)
.join('/')
return `${method} ${path}`
}
function median(values: number[]): number {
if (values.length === 0) return 0
const sorted = [...values].sort((a, b) => a - b)
const mid = sorted.length >> 1
return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2
}
const count = (into: Record<string, number>, key: string): void => { into[key] = (into[key] ?? 0) + 1 }
/** Hop-by-hop headers, and the handshake's own, which the meter's dial to the backend makes afresh. */
const HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding',
'upgrade', 'host', 'content-length', 'sec-websocket-key', 'sec-websocket-version', 'sec-websocket-extensions', 'sec-websocket-protocol'])
/** Everything the client's upgrade carried but this hop's own, so the backend reads what the client sent. */
function forwardedHeaders(req: IncomingMessage): Record<string, string | string[]> {
const out: Record<string, string | string[]> = {}
for (const [name, value] of Object.entries(req.headers)) {
if (value !== undefined && !HOP.has(name)) out[name] = value
}
return out
}
export class SocketMeter {
readonly sockets: SocketRecord[]
readonly refused: RefusalRecord[]
private readonly http: Record<string, number>
private startedAt: number
private readonly servers: Server[] = []
private readonly live = new Set<WebSocket>()
private upstream: URL | null = null
private wss: WebSocketServer | null = null
url = ''
wsUrl = ''
private constructor(records: MeterRecords) {
this.startedAt = records.startedAt
this.sockets = records.sockets
this.refused = records.refused
this.http = records.http
}
/** Start the report's window now: sockets opened before (the daemons' own start) are left out of it. */
startClock(): void {
this.startedAt = Date.now()
}
/** A meter over records already taken, for reporting alone. */
static fromRecords(records: MeterRecords): SocketMeter {
return new SocketMeter(records)
}
/** Listen on a free loopback port and forward everything to `target` (`http://127.0.0.1:PORT`). */
static async start(target: string): Promise<SocketMeter> {
const meter = new SocketMeter({ startedAt: Date.now(), sockets: [], refused: [], http: {} })
meter.upstream = new URL(target)
meter.wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, handleProtocols: (set) => [...set][0] ?? false })
const { url, wsUrl } = await meter.listen(null)
meter.url = url
meter.wsUrl = wsUrl
return meter
}
/** Another way in, on its own port, whose sockets are recorded with `via: name`: one per daemon, which declare the
* same client, version and token, so where they dial is what tells them apart. */
entry(name: string): Promise<{ url: string; wsUrl: string }> {
return this.listen(name)
}
private async listen(via: string | null): Promise<{ url: string; wsUrl: string }> {
const meter = this
const upstream = this.upstream!
const wss = this.wss!
const server = createServer((req, res) => {
count(meter.http, routeOf(req.method ?? 'GET', req.url ?? '/'))
const forward = request({ host: upstream.hostname, port: upstream.port, method: req.method, path: req.url,
headers: { ...req.headers, host: upstream.host } }, (answer) => {
res.writeHead(answer.statusCode ?? 502, answer.headers)
answer.pipe(res)
})
forward.on('error', () => { if (!res.headersSent) res.writeHead(502); res.end() })
req.pipe(forward)
})
server.on('upgrade', (req, socket, head) => meter.upgrade(req, socket, head, upstream, wss, via))
server.listen(0, '127.0.0.1')
await once(server, 'listening')
const port = (server.address() as { port: number }).port
this.servers.push(server)
return { url: `http://127.0.0.1:${port}`, wsUrl: `ws://127.0.0.1:${port}` }
}
private upgrade(req: IncomingMessage, socket: Duplex, head: Buffer, upstream: URL, wss: WebSocketServer, via: string | null): void {
const query = new URL(req.url ?? '/', 'http://meter').searchParams
const endpoint = (req.url ?? '/').split('?')[0]
let attached = false
const protocols = String(req.headers['sec-websocket-protocol'] ?? '').split(',').map((p) => p.trim()).filter(Boolean)
const backend = new WebSocket(`ws://${upstream.host}${req.url ?? '/'}`, protocols, {
headers: forwardedHeaders(req), perMessageDeflate: false })
const refuse = (status: number): void => {
this.refused.push({ endpoint, status, at: Date.now() })
if (status > 0) socket.end(`HTTP/1.1 ${status} Refused\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`)
else socket.destroy()
}
let opened = false
backend.once('unexpected-response', (_r, res) => { opened = true; refuse(res.statusCode ?? 0); backend.terminate() })
backend.once('error', () => { if (!opened) { opened = true; refuse(0) } })
socket.once('error', () => backend.terminate())
// A client that gave up before the backend answered: the backend's side must not outlive it. The upgrade's
// socket is paused, so its end is only seen by reading it; a client sends nothing before the 101, and anything
// it did send goes back where `ws` finds it.
const quit = (): void => { if (!attached) backend.terminate() }
const watch = (): void => {
const early = socket.read()
if (early) { socket.off('readable', watch); socket.unshift(early) }
}
socket.on('readable', watch)
socket.once('end', quit)
socket.once('close', quit)
backend.once('open', () => {
opened = true
// Frames the backend sends before the client side is up wait here, in order.
const early: Array<[RawData, boolean]> = []
const hold = (data: RawData, binary: boolean): void => { early.push([data, binary]) }
backend.on('message', hold)
socket.off('readable', watch)
if (socket.destroyed || socket.readableEnded) { backend.terminate(); return }
attached = true
wss.handleUpgrade(req, socket, head, (client) => this.attach(client, backend, endpoint, query, early, hold, via))
})
}
private attach(client: WebSocket, backend: WebSocket, endpoint: string, query: URLSearchParams,
early: Array<[RawData, boolean]>, hold: (data: RawData, binary: boolean) => void, via: string | null): void {
const record: SocketRecord = { endpoint, ...declaredKind(endpoint, query), openedAt: Date.now(), closedAt: null, closeCode: null,
closeReason: '', selects: [], via }
this.sockets.push(record)
this.live.add(client)
const pending = new Map<string, SelectRecord>()
const fromBackend = (data: RawData, binary: boolean): void => {
if (!binary) this.readAnswer(data, pending)
if (client.readyState === WebSocket.OPEN) client.send(data, { binary })
}
backend.off('message', hold)
for (const [data, binary] of early) fromBackend(data, binary)
backend.on('message', fromBackend)
client.on('message', (data, binary) => {
if (!binary) {
const frame = parse(data)
const machineId = frame?.type === 'machine_select' ? frame.payload?.machineId : undefined
if (typeof machineId === 'string') {
const select: SelectRecord = { machineId, at: Date.now(), outcome: null }
record.selects.push(select)
pending.set(machineId, select)
}
}
if (backend.readyState === WebSocket.OPEN) backend.send(data, { binary })
})
const finish = (code: number, reason: Buffer): void => {
if (record.closedAt !== null) return
record.closedAt = Date.now()
record.closeCode = code
record.closeReason = reason.toString()
this.live.delete(client)
}
backend.on('close', (code, reason) => {
finish(code, reason)
// 1005 (no code) and 1006 (abnormal) cannot be sent on the wire; they are what the client sees anyway.
if (code === 1005) client.close()
else if (code === 1006) client.terminate()
else client.close(code, reason)
})
client.on('close', (code, reason) => {
finish(code, reason)
if (code === 1005) backend.close()
else if (code === 1006) backend.terminate()
else backend.close(code, reason)
})
client.on('error', () => backend.terminate())
backend.on('error', () => client.terminate())
}
private readAnswer(data: RawData, pending: Map<string, SelectRecord>): void {
const frame = parse(data)
const machineId = frame?.payload?.machineId
if (!frame?.payload || typeof machineId !== 'string') return
const select = pending.get(machineId)
if (!select) return
if (frame.type === 'connected') select.outcome = 'accepted'
else if (frame.type === 'machine_select_error') select.outcome = String(frame.payload.error)
else return
pending.delete(machineId)
}
report(options: { now?: number; deletedMachineIds?: string[] } = {}): MeterReport {
const now = options.now ?? Date.now()
const deleted = new Set(options.deletedMachineIds ?? [])
const durationMs = now - this.startedAt
const endpoints: Record<string, EndpointReport> = {}
const inWindow = this.sockets.filter((s) => s.openedAt >= this.startedAt)
const refused = this.refused.filter((r) => r.at >= this.startedAt)
const names = new Set([...inWindow.map((s) => s.endpoint), ...refused.map((r) => r.endpoint)])
for (const name of names) {
const sockets = inWindow.filter((s) => s.endpoint === name)
const lifetimes = sockets.map((s) => (s.closedAt ?? now) - s.openedAt)
const closeCodes: Record<string, number> = {}
const selectOutcomes: Record<string, number> = {}
const selectsByMachine: Record<string, number> = {}
for (const s of sockets) {
if (s.closeCode !== null) count(closeCodes, String(s.closeCode))
for (const select of s.selects) {
count(selectOutcomes, select.outcome ?? 'unanswered')
count(selectsByMachine, select.machineId)
}
}
endpoints[name] = {
connects: sockets.length,
connectsPerMinute: durationMs > 0 ? sockets.length / (durationMs / 60_000) : 0,
refused: refused.filter((r) => r.endpoint === name).length,
medianLifetimeMs: median(lifetimes),
livedUnder2s: lifetimes.filter((ms) => ms < 2_000).length,
closedWithoutSelect: sockets.filter((s) => s.closedAt !== null && s.selects.length === 0).length,
attributed: attributedShare(sockets),
attributedByClient: Object.fromEntries([...new Set(sockets.map((s) => s.client))]
.map((kind) => [kind, attributedShare(sockets.filter((s) => s.client === kind))])),
closeCodes,
selectOutcomes,
deletedMachineSelects: sockets.reduce((n, s) => n + s.selects.filter((select) => deleted.has(select.machineId)).length, 0),
selectsByMachine,
acceptedThenDiedUnder1m: sockets.filter((s) => s.closedAt !== null && s.closedAt - s.openedAt < 60_000
&& s.selects.some((select) => select.outcome === 'accepted')).length,
}
}
return { durationMs, endpoints, http: { ...this.http } }
}
async close(): Promise<void> {
for (const ws of this.live) ws.terminate()
await Promise.all(this.servers.splice(0).map((server) => {
server.closeAllConnections()
return new Promise((resolve) => server.close(resolve))
}))
}
}
/** Attributed: a known kind and a version, as #2029 counts its 95%. */
function attributedShare(sockets: SocketRecord[]): number {
return sockets.length ? sockets.filter((s) => s.client !== 'unknown' && s.version).length / sockets.length : 1
}
function parse(data: RawData): { type?: string; payload?: Record<string, any> } | null {
try {
const frame = JSON.parse(data.toString())
return frame && typeof frame === 'object' ? frame : null
} catch {
return null
}
}