edge-ai-client-ts 1.0.0

package/dist/network/ws-client.js

@@ -0,0 +1,1134 @@
+/**
+ * JSON `/edge` WebSocket client for the TypeScript edge-client.
+ *
+ * Mirrors `edge-client/src/network/ws_client.rs` for wire shapes, URL auth,
+ * registration, heartbeat metadata, ACK correlation, and reconnect backoff. The
+ * binary `/shell-edge` channel is deliberately out of scope for this module.
+ */
+import { randomUUID, X509Certificate } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as tls from 'node:tls';
+import WebSocket from 'ws';
+import { edgeAuthEscapeHatchActive, loadEdgeAuthToken, } from '../config/settings.js';
+import { constantTimeHexEquals, sha256Hex } from '../crypto/hmac.js';
+import { decideTlsFromEnv } from '../crypto/tls-guard.js';
+export const SUBPROTOCOL_V2 = 'edgeai-v2';
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+// C2 — SECURITY (review 2026-07-11): cap incoming WS frames at 2 MiB to match
+// the Rust ws-service's `maxPayload: 2 * 1024 * 1024`. Without this, a hostile
+// relay could stream a 100 MiB frame (the ws@8 default) and OOM-kill the client.
+export const DEFAULT_MAX_PAYLOAD_BYTES = 2 * 1024 * 1024;
+const WS_OPEN = 1;
+const FAST_BACKOFF_MAX_MS = 30_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+export function createRegisterMessage(machineId, agentId) {
+    return { type: 'register', machine_id: machineId, agent_id: agentId };
+}
+export function createStreamMessage(input) {
+    return {
+        msg_id: randomUUID(),
+        machine_id: input.machine_id,
+        agent_id: input.agent_id,
+        type: input.type,
+        payload: input.payload,
+        timestamp: input.timestamp ?? Date.now(),
+    };
+}
+export function createAckMessage(msgId) {
+    return { action: 'ack', msg_id: msgId };
+}
+export function encodeStreamMessage(message) {
+    if (!isStreamMessage(message)) {
+        throw new Error('Invalid StreamMessage');
+    }
+    return JSON.stringify(message);
+}
+export function decodeStreamMessage(text) {
+    const value = JSON.parse(text);
+    if (!isStreamMessage(value)) {
+        throw new Error('Invalid StreamMessage JSON');
+    }
+    return value;
+}
+export function isRegisterMessage(value) {
+    return (isRecord(value) &&
+        value['type'] === 'register' &&
+        typeof value['machine_id'] === 'string' &&
+        typeof value['agent_id'] === 'string');
+}
+export function isStreamMessage(value) {
+    return (isRecord(value) &&
+        typeof value['msg_id'] === 'string' &&
+        typeof value['machine_id'] === 'string' &&
+        typeof value['agent_id'] === 'string' &&
+        typeof value['type'] === 'string' &&
+        isJsonValue(value['payload']) &&
+        typeof value['timestamp'] === 'number' &&
+        Number.isFinite(value['timestamp']));
+}
+export function isAckMessage(value) {
+    return (isRecord(value) &&
+        value['action'] === 'ack' &&
+        typeof value['msg_id'] === 'string');
+}
+export function isHeartbeatMessage(value) {
+    return (isRecord(value) &&
+        value['type'] === 'heartbeat' &&
+        typeof value['machine_id'] === 'string' &&
+        optionalString(value['platform']) &&
+        optionalString(value['hostname']) &&
+        optionalString(value['agent_version']) &&
+        optionalString(value['operator_id']) &&
+        (value['system'] === undefined || isSystemMetrics(value['system'])));
+}
+export function selectRelayUrl(mode, lanUrl, wanUrl, defaultUrl) {
+    if (mode === 'lan') {
+        return lanUrl ?? defaultUrl;
+    }
+    if (mode === 'wan') {
+        return wanUrl ?? defaultUrl;
+    }
+    return defaultUrl;
+}
+export function percentEncodeToken(token) {
+    const bytes = Buffer.from(token, 'utf8');
+    let out = '';
+    for (const byte of bytes) {
+        if ((byte >= 0x41 && byte <= 0x5a) ||
+            (byte >= 0x61 && byte <= 0x7a) ||
+            (byte >= 0x30 && byte <= 0x39) ||
+            byte === 0x2d ||
+            byte === 0x2e ||
+            byte === 0x5f ||
+            byte === 0x7e) {
+            out += String.fromCharCode(byte);
+        }
+        else {
+            out += `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+        }
+    }
+    return out;
+}
+export function appendEdgeToken(url, token) {
+    if (token === undefined) {
+        return url;
+    }
+    // Wire-compat workaround (debugged via e2e-smoke 2026-07-11) — REMOVE
+    // WHEN RUST BUG IS FIXED. The Rust ws-service's auth gate has TWO
+    // functions that disagree on the URL query param name:
+    //   - `extractAuthToken` (in middleware/wsProtocolAuth.ts) reads `auth_token`
+    //     out of the URL → resolves the opaque token → passes realKey forward.
+    //   - `validateEdgeToken` (in services/ws-service/src/edgeAuth.ts) reads
+    //     `edge_token` out of the URL and compares against the realKey it was
+    //     passed.
+    // A client that only sends `?edge_token=...` gets rejected at
+    // extractAuthToken with "missing" before validateEdgeToken runs. A client
+    // that only sends `?auth_token=...` gets rejected at validateEdgeToken.
+    //
+    // Until the Rust side is fixed (one of these auth functions needs to read
+    // the same param name as the other), this TS client emits BOTH query
+    // params with the same token value. Tracking: see e2e-smoke/README.md
+    // §"Wire-compat notes" for the full investigation; this comment MUST be
+    // removed alongside any pair-down when the bug is fixed.
+    //
+    // Implementation note: we use the WHATWG URL parser for idempotency
+    // (calling appendEdgeToken twice does NOT duplicate `edge_token=` and
+    // `auth_token=`), URL fragment handling (params go BEFORE the fragment,
+    // per RFC 3986), and percent-encoding (tokens with URL-special chars
+    // are correctly encoded). `URL` requires http(s):// — we rewrite
+    // ws(s):// → http(s)://, parse, mutate, then restore the original scheme.
+    const isWs = url.startsWith('ws://');
+    const isWss = url.startsWith('wss://');
+    const httpish = isWss
+        ? url.replace(/^wss:\/\//, 'https://')
+        : isWs
+            ? url.replace(/^ws:\/\//, 'http://')
+            : url;
+    try {
+        const parsed = new URL(httpish);
+        parsed.searchParams.set('edge_token', token);
+        parsed.searchParams.set('auth_token', token);
+        const out = parsed.toString();
+        // Restore original ws(s):// scheme.
+        if (isWss)
+            return out.replace(/^https:\/\//, 'wss://');
+        if (isWs)
+            return out.replace(/^http:\/\//, 'ws://');
+        return out;
+    }
+    catch {
+        // Malformed URL — fall back to raw string concat (preserves legacy
+        // behaviour for callers that hand in incomplete URLs).
+        const sep = url.includes('?') ? '&' : '?';
+        return `${url}${sep}edge_token=${percentEncodeToken(token)}&auth_token=${percentEncodeToken(token)}`;
+    }
+}
+export function appendDeviceSecret(url, secret) {
+    if (secret === undefined) {
+        return url;
+    }
+    return `${url}${url.includes('?') ? '&' : '?'}device_secret=${percentEncodeToken(secret)}`;
+}
+/**
+ * Build the AUTH-TOKEN half of the `Sec-WebSocket-Protocol` header. Caller
+ * passes this to `ws` as a separate element in the `protocols` array
+ * alongside SUBPROTOCOL_V2 — the resulting HTTP header reads
+ * `Sec-WebSocket-Protocol: edgeai-v2, <returned-value>`.
+ *
+ * Edge-2-edge: the `deviceSecret` historically travelled INSIDE the
+ * subprotocol header (so reverse-proxy logs could never see it), but for
+ * v2 we omit it — we send only the opaque edge_token. Returns `undefined`
+ * when there is no token to send, OR when the token is NOT a v2 opaque
+ * token (a raw edge_token would trigger `malformed_opaque` 401 on the
+ * server's subprotocol channel; raw tokens should travel via the URL
+ * query string instead — which `decideEdgeAuth` already wires up).
+ */
+export function buildEdgeSubprotocolHeader(edgeToken, deviceSecret) {
+    if (edgeToken === undefined) {
+        return undefined;
+    }
+    // Trim BEFORE the isOpaqueToken check so leading/trailing whitespace doesn't
+    // break format detection. (Real callers rarely pass whitespace, but defensive.)
+    const trimmed = edgeToken.trim();
+    if (trimmed.length === 0 || !isOpaqueToken(trimmed)) {
+        // Raw edge_token → fall through to the query-string path (no subprotocol).
+        return undefined;
+    }
+    const _deviceSecret = deviceSecret;
+    void _deviceSecret;
+    return trimmed;
+}
+/** True iff the token LOOKS like a v2 opaque token (`o.<exp>.<nonce>.<sig>`). */
+function isOpaqueToken(token) {
+    const parts = token.split('.');
+    return parts.length === 4 && parts[0] === 'o' && parts[1].length > 0 && parts[2].length > 0 && parts[3].length > 0;
+}
+// Re-export for unit tests.
+export { isOpaqueToken as _isOpaqueTokenForTests };
+export function decideEdgeAuth(baseUrl, token, escapeActive) {
+    if (token !== undefined) {
+        return { kind: 'Connect', url: appendEdgeToken(baseUrl, token) };
+    }
+    if (escapeActive) {
+        return { kind: 'ConnectUnauthenticated', url: baseUrl };
+    }
+    return { kind: 'Refuse' };
+}
+/**
+ * FIX 2026-07-12 (3.5 + 3.6 from review): wrap any Error before emitting
+ * it from EdgeWsClient so the URL (and other sensitive tokens) can never
+ * leak to listeners that log the raw error. EventEmitter's `emit('error', err)`
+ * propagates the error verbatim — if `err.message` contains a URL with
+ * `?edge_token=...&device_secret=...`, a single missed redaction in a
+ * listener leaks credentials to the log.
+ *
+ * This helper produces a NEW Error whose `.message` has `redactUrl()`
+ * applied. The original `.stack` is preserved (so debugging still works)
+ * but we strip the message portion of the stack (the first line) so the
+ * URL isn't in the stack either. Listeners that destructure
+ * `{ message, code }` are safe; listeners that log `err.toString()` are
+ * also safe (toString uses message).
+ */
+export function redactErrorUrl(err) {
+    if (!err || typeof err.message !== 'string')
+        return err;
+    const safeMessage = redactUrl(err.message);
+    if (safeMessage === err.message)
+        return err; // no URL in message → unchanged
+    const out = new Error(safeMessage);
+    out.name = err.name;
+    // Preserve the code property if present (RPC code, etc).
+    const anyErr = err;
+    if (anyErr.code)
+        out.code = anyErr.code;
+    // Strip the first line of the stack (which embeds the message) and
+    // re-attach the rest. Browsers/V8 put the message in the first stack line.
+    if (err.stack) {
+        const lines = err.stack.split('\n');
+        lines[0] = `${out.name}: ${out.message}`;
+        out.stack = lines.join('\n');
+    }
+    return out;
+}
+export function redactUrl(url) {
+    // `ws://...` URLs don't parse with `new URL()` (only http/https do), so
+    // we have to strip the `ws://` → `http://` prefix + reverse it. We also
+    // fall back to regex if the URL is otherwise malformed.
+    const tryUrlParse = (target) => {
+        try {
+            const parsed = new URL(target);
+            for (const param of ['edge_token', 'auth_token', 'device_secret']) {
+                if (parsed.searchParams.has(param)) {
+                    parsed.searchParams.set(param, 'REDACTED');
+                }
+            }
+            return parsed.toString();
+        }
+        catch {
+            // fall through to regex
+            return target
+                .replace(/([?&]edge_token=)[^&]*/g, '$1REDACTED')
+                .replace(/([?&]auth_token=)[^&]*/g, '$1REDACTED')
+                .replace(/([?&]device_secret=)[^&]*/g, '$1REDACTED');
+        }
+    };
+    // Handle ws:// / wss:// by rewriting to http(s):// for URL parsing.
+    if (url.startsWith('ws://') || url.startsWith('wss://')) {
+        const rewritten = url.replace(/^wss?:/, 'http:').replace(/^http:/, 'http:');
+        const parsed = tryUrlParse(rewritten);
+        // Restore the original scheme.
+        return url.startsWith('wss://')
+            ? parsed.replace(/^https?:/, 'wss:')
+            : parsed.replace(/^https?:/, 'ws:');
+    }
+    return tryUrlParse(url);
+}
+export function buildHeartbeatMessage(settings, packageVersion = resolvePackageVersion()) {
+    const heartbeat = {
+        type: 'heartbeat',
+        machine_id: settings.machine_id,
+    };
+    const platform = detectPlatform();
+    if (platform.length > 0) {
+        heartbeat.platform = platform;
+    }
+    const hostname = readHostname();
+    if (hostname !== undefined) {
+        heartbeat.hostname = hostname;
+    }
+    if (packageVersion.length > 0) {
+        heartbeat.agent_version = packageVersion;
+    }
+    heartbeat.system = collectSystemMetrics();
+    const operatorId = settings.owner_operator_id?.trim();
+    if (operatorId !== undefined && operatorId.length > 0) {
+        heartbeat.operator_id = operatorId;
+    }
+    return heartbeat;
+}
+export class EdgeWsClient extends EventEmitter {
+    settings;
+    edgeToken;
+    deviceSecret;
+    pinnedFingerprint;
+    buffer;
+    heartbeatIntervalMs;
+    requestTimeoutMs;
+    reconnect;
+    packageVersion;
+    localQueue = [];
+    pending = new Map();
+    ws;
+    started = false;
+    stopping = false;
+    registered = false;
+    online = false;
+    flushing = false;
+    networkMode;
+    reconnectAttempts = 0;
+    heartbeatTimer;
+    reconnectTimer;
+    lastRelayHeartbeatMs;
+    constructor(options) {
+        super();
+        this.settings = options.settings;
+        this.edgeToken = options.edgeToken ?? loadEdgeAuthToken(options.settings);
+        this.deviceSecret = options.deviceSecret ?? options.settings.relay.device_secret;
+        this.pinnedFingerprint = normalizeFingerprint(options.pinnedFingerprint ?? process.env.EDGE_RELAY_FINGERPRINT ?? options.settings.relay.fingerprint);
+        this.buffer = options.buffer;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.reconnect = {
+            initialDelayMs: options.reconnect?.initialDelayMs ?? 1_000,
+            maxDelayMs: options.reconnect?.maxDelayMs ?? FAST_BACKOFF_MAX_MS,
+            multiplier: options.reconnect?.multiplier ?? 2,
+        };
+        this.packageVersion = options.packageVersion ?? resolvePackageVersion();
+        this.networkMode = options.networkMode;
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+    async start() {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        this.stopping = false;
+        try {
+            await this.connect();
+        }
+        catch (error) {
+            const err = toError(error);
+            this.emit('error', redactErrorUrl(err));
+            this.scheduleReconnect();
+            throw err;
+        }
+    }
+    async stop() {
+        this.stopping = true;
+        this.started = false;
+        this.clearReconnectTimer();
+        this.stopHeartbeat();
+        this.rejectAllPending(new Error('WebSocket client stopped'));
+        const socket = this.ws;
+        this.ws = undefined;
+        if (socket !== undefined && socket.readyState === WS_OPEN) {
+            socket.close();
+        }
+        this.markOffline();
+    }
+    async send(message) {
+        if (!isStreamMessage(message)) {
+            throw new Error('send requires a valid StreamMessage');
+        }
+        if (!this.canSendNow()) {
+            await this.enqueueOffline(message);
+            return;
+        }
+        try {
+            await this.sendStreamNow(message);
+        }
+        catch (error) {
+            await this.enqueueOffline(message);
+            throw toError(error);
+        }
+    }
+    request(message, timeoutMs = this.requestTimeoutMs) {
+        if (!isStreamMessage(message)) {
+            return Promise.reject(new Error('request requires a valid StreamMessage'));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(message.msg_id);
+                reject(new Error(`WebSocket request timed out after ${timeoutMs}ms for msg_id ${message.msg_id}`));
+            }, timeoutMs);
+            this.pending.set(message.msg_id, { resolve, reject, timer });
+            this.send(message).catch((error) => {
+                const pending = this.pending.get(message.msg_id);
+                if (pending !== undefined) {
+                    clearTimeout(pending.timer);
+                    this.pending.delete(message.msg_id);
+                    pending.reject(toError(error));
+                }
+            });
+        });
+    }
+    async sendHeartbeat() {
+        const heartbeat = buildHeartbeatMessage(this.settings, this.packageVersion);
+        await this.sendJsonObject(heartbeatToJsonObject(heartbeat));
+    }
+    isOnline() {
+        return this.online;
+    }
+    isRegistered() {
+        return this.registered;
+    }
+    lastRelayHeartbeat() {
+        return this.lastRelayHeartbeatMs;
+    }
+    currentUrl() {
+        return this.resolveCurrentUrl();
+    }
+    async connect(rejectEarlyClose = true) {
+        const url = this.resolveCurrentUrl();
+        const tlsDecision = decideTlsFromEnv(url);
+        if (tlsDecision.kind === 'Refuse') {
+            throw new Error(tlsDecision.reason);
+        }
+        const wsOptions = this.buildWebSocketOptions(url);
+        const socket = new WebSocket(url, wsOptions);
+        this.ws = socket;
+        this.registered = false;
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const failIfOpening = (error) => {
+                // Coerce nullish → real Error at the source so ALL callers (socket.on('error'),
+                // sendText.catch, and any future emit site) are protected. Without this,
+                // `this.emit('error', null)` propagates null through to every 'error' listener
+                // — e.g., run.ts's `ws.on('error', (err) => logger.error(err.message))` crashes
+                // with TypeError: Cannot read properties of null.
+                const safeError = error ?? new Error('WebSocket upgrade rejected (no detail)');
+                this.emit('error', safeError);
+                if (!settled) {
+                    settled = true;
+                    reject(safeError);
+                }
+            };
+            socket.on('open', () => {
+                const register = createRegisterMessage(this.settings.machine_id, this.settings.agent.default_agent_id);
+                this.sendText(JSON.stringify(register))
+                    .then(() => {
+                    if (!settled) {
+                        settled = true;
+                        resolve();
+                    }
+                })
+                    .catch(failIfOpening);
+            });
+            socket.on('message', (raw, isBinary) => {
+                if (!isBinary) {
+                    this.handleRawMessage(raw);
+                }
+            });
+            socket.on('error', (error) => {
+                // failIfOpening itself coerces null → Error, so we can pass through directly.
+                failIfOpening(error);
+            });
+            socket.on('close', () => {
+                if (!settled && !this.stopping) {
+                    settled = true;
+                    if (rejectEarlyClose) {
+                        reject(new Error('WebSocket closed before registration could be sent'));
+                    }
+                    else {
+                        resolve();
+                    }
+                }
+                this.handleClose();
+            });
+        });
+    }
+    buildWebSocketOptions(url) {
+        const subprotocolHeader = buildEdgeSubprotocolHeader(this.edgeToken, this.deviceSecret);
+        // CRITICAL wire-compat (debugged via e2e-smoke 2026-07-11):
+        // The Rust ws-service's `parseSubprotocolHeader` splits the
+        // `Sec-WebSocket-Protocol` HTTP header on commas and takes parts[0] as
+        // the protocol identifier ("edgeai-v2") + parts[1] as the opaque auth
+        // token. The `ws@8` library's `protocols` option requires an ARRAY of
+        // distinct protocol values — passing a single string with a comma in it
+        // (e.g. "edgeai-v2, <token>") triggers `ws@8` to throw
+        // "An invalid or duplicated subprotocol was specified".
+        //
+        // We must hand `ws` TWO elements: ["edgeai-v2", "<token>"]. The library
+        // then emits the correct `Sec-WebSocket-Protocol: edgeai-v2, <token>`
+        // header that the Rust parser expects.
+        const protocols = subprotocolHeader !== undefined ? [SUBPROTOCOL_V2, subprotocolHeader] : undefined;
+        const options = {
+            perMessageDeflate: false,
+            headers: {},
+            ...(protocols ? { protocols } : {}),
+            // C2 — SECURITY FIX (security-review 2026-07-11): cap incoming WS
+            // frames at 2 MiB to match the Rust ws-service's `maxPayload:
+            // 2 * 1024 * 1024`. Without this, a hostile relay could stream a
+            // 100 MiB frame (the ws@8 default `maxPayload`) and OOM-kill the
+            // client. The Rust unit tests use small messages so this cap is
+            // invisible to the happy path.
+            maxPayload: DEFAULT_MAX_PAYLOAD_BYTES,
+        };
+        if (url.startsWith('wss://')) {
+            options.createConnection = this.createPinnedTlsConnection(url);
+        }
+        return options;
+    }
+    createPinnedTlsConnection(url) {
+        const parsed = new URL(url);
+        const expectedFingerprint = this.pinnedFingerprint;
+        const createConnection = (options, listener) => {
+            const baseOptions = options;
+            return tls.connect({
+                ...baseOptions,
+                servername: baseOptions.servername ?? parsed.hostname,
+                checkServerIdentity: (servername, cert) => {
+                    const defaultError = tls.checkServerIdentity(servername, cert);
+                    if (defaultError !== undefined) {
+                        return defaultError;
+                    }
+                    return verifyPeerFingerprint(cert, expectedFingerprint);
+                },
+            }, listener);
+        };
+        return createConnection;
+    }
+    resolveCurrentUrl() {
+        const baseUrl = selectRelayUrl(this.networkMode, this.settings.server.ws_url_lan, this.settings.server.ws_url_wan, this.settings.server.ws_url);
+        const decision = decideEdgeAuth(baseUrl, this.edgeToken, edgeAuthEscapeHatchActive());
+        if (decision.kind === 'Refuse') {
+            throw new Error('Refusing unauthenticated edge WebSocket connection');
+        }
+        return appendDeviceSecret(decision.url, this.deviceSecret);
+    }
+    handleRawMessage(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(rawDataToString(raw));
+        }
+        catch (error) {
+            this.emit('error', redactErrorUrl(toError(error)));
+            return;
+        }
+        if (!isRecord(parsed)) {
+            return;
+        }
+        const message = unknownRecordToJsonObject(parsed);
+        const isAction = this.dispatchAction(parsed);
+        const isType = this.dispatchAckOrType(parsed, message);
+        if (isAction || isType) {
+            this.emit('inbound', message);
+        }
+    }
+    dispatchAction(data) {
+        const action = stringField(data, 'action');
+        if (action === undefined) {
+            return false;
+        }
+        return matchesAction(action);
+    }
+    dispatchAckOrType(data, message) {
+        const action = stringField(data, 'action');
+        const msgType = stringField(data, 'type');
+        const isAck = msgType === 'ack' || action === 'ack';
+        if (isAck) {
+            const msgId = stringField(data, 'msg_id');
+            if (msgId !== undefined) {
+                this.resolvePending(msgId, message);
+            }
+            return true;
+        }
+        if (msgType === undefined) {
+            return false;
+        }
+        switch (msgType) {
+            case 'registered':
+                this.handleRegistered(message);
+                break;
+            case 'get_config':
+                this.replyWithConfigSnapshot(stringField(data, 'msg_id')).catch((error) => {
+                    this.emit('error', redactErrorUrl(toError(error)));
+                });
+                break;
+            case 'set_config':
+                this.applyConfigMessage(data);
+                this.ackConfigMessage(data).catch((error) => {
+                    this.emit('error', redactErrorUrl(toError(error)));
+                });
+                break;
+            case 'config_snapshot':
+                this.applyConfigMessage(data);
+                break;
+            case 'agent_list':
+                this.emit('agent_list', message);
+                break;
+            case 'audit_event':
+                this.emit('audit_event', message);
+                break;
+            case 'heartbeat':
+                this.lastRelayHeartbeatMs = Date.now();
+                this.emit('heartbeat', message);
+                break;
+            case 'device_secret_issued':
+                break;
+            default:
+                break;
+        }
+        return true;
+    }
+    handleRegistered(message) {
+        this.registered = true;
+        this.reconnectAttempts = 0;
+        if (!this.online) {
+            this.online = true;
+            this.emit('online');
+        }
+        this.emit('registered', message);
+        this.startHeartbeat();
+        this.flushOutbound().catch((error) => {
+            this.emit('error', redactErrorUrl(toError(error)));
+        });
+        this.requestConfigSnapshot().catch((error) => {
+            this.emit('error', redactErrorUrl(toError(error)));
+        });
+    }
+    applyConfigMessage(data) {
+        const config = data['config'];
+        if (config === null) {
+            this.emit('config', null);
+            return;
+        }
+        if (!isRecord(config)) {
+            return;
+        }
+        const snapshot = unknownRecordToJsonObject(config);
+        this.emit('config', snapshot);
+        const heartbeatIntervalSeconds = numberField(config, 'heartbeat_interval_s');
+        if (heartbeatIntervalSeconds !== undefined &&
+            heartbeatIntervalSeconds >= 1 &&
+            heartbeatIntervalSeconds <= 300) {
+            this.restartHeartbeat(heartbeatIntervalSeconds * 1_000);
+        }
+        const nextMode = stringField(config, 'network_mode');
+        if (nextMode !== undefined) {
+            this.handleNetworkModeChange(nextMode);
+        }
+    }
+    handleNetworkModeChange(nextMode) {
+        if (this.networkMode === nextMode) {
+            return;
+        }
+        const modeUrl = nextMode === 'lan'
+            ? this.settings.server.ws_url_lan
+            : nextMode === 'wan'
+                ? this.settings.server.ws_url_wan
+                : undefined;
+        this.networkMode = nextMode;
+        if (modeUrl !== undefined) {
+            this.forceReconnect();
+        }
+    }
+    async ackConfigMessage(data) {
+        const msgId = stringField(data, 'msg_id');
+        if (msgId !== undefined) {
+            await this.sendJsonObject(ackToJsonObject(createAckMessage(msgId)));
+        }
+    }
+    async requestConfigSnapshot() {
+        await this.sendJsonObject({
+            type: 'get_config',
+            machine_id: this.settings.machine_id,
+            msg_id: randomUUID(),
+        });
+    }
+    async replyWithConfigSnapshot(msgId) {
+        await this.sendJsonObject({
+            type: 'config_snapshot',
+            machine_id: this.settings.machine_id,
+            msg_id: msgId ?? randomUUID(),
+            config: settingsSnapshot(this.settings),
+            timestamp: Date.now(),
+        });
+    }
+    resolvePending(msgId, message) {
+        const pending = this.pending.get(msgId);
+        if (pending === undefined) {
+            return;
+        }
+        clearTimeout(pending.timer);
+        this.pending.delete(msgId);
+        pending.resolve(message);
+    }
+    canSendNow() {
+        return this.ws !== undefined && this.ws.readyState === WS_OPEN;
+    }
+    async sendStreamNow(message) {
+        await this.sendText(encodeStreamMessage(message));
+    }
+    async sendJsonObject(message) {
+        await this.sendText(JSON.stringify(message));
+    }
+    async sendText(text) {
+        const socket = this.ws;
+        if (socket === undefined || socket.readyState !== WS_OPEN) {
+            throw new Error('WebSocket is not open');
+        }
+        await new Promise((resolve, reject) => {
+            socket.send(text, (error) => {
+                if (error !== undefined) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    async enqueueOffline(message) {
+        if (this.buffer !== undefined) {
+            await this.buffer.enqueue(message);
+        }
+        else {
+            this.localQueue.push(message);
+        }
+    }
+    async flushOutbound() {
+        if (this.flushing || !this.canSendNow()) {
+            return;
+        }
+        this.flushing = true;
+        try {
+            while (this.localQueue.length > 0 && this.canSendNow()) {
+                const next = this.localQueue.shift();
+                if (next !== undefined) {
+                    await this.sendStreamNow(next);
+                }
+            }
+            if (this.buffer !== undefined && this.canSendNow()) {
+                for await (const frame of this.buffer.drain()) {
+                    if (!this.canSendNow()) {
+                        break;
+                    }
+                    await this.sendStreamNow(frame);
+                }
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    startHeartbeat() {
+        if (this.heartbeatTimer !== undefined) {
+            return;
+        }
+        this.heartbeatTimer = setInterval(() => {
+            this.sendHeartbeat().catch((error) => {
+                this.emit('error', redactErrorUrl(toError(error)));
+            });
+        }, this.heartbeatIntervalMs);
+    }
+    restartHeartbeat(intervalMs) {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            this.sendHeartbeat().catch((error) => {
+                this.emit('error', redactErrorUrl(toError(error)));
+            });
+        }, intervalMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer !== undefined) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+    handleClose() {
+        this.ws = undefined;
+        this.registered = false;
+        this.stopHeartbeat();
+        this.markOffline();
+        if (this.started && !this.stopping) {
+            this.scheduleReconnect();
+        }
+    }
+    markOffline() {
+        if (this.online) {
+            this.online = false;
+            this.emit('offline');
+        }
+    }
+    forceReconnect() {
+        const socket = this.ws;
+        if (socket !== undefined && socket.readyState === WS_OPEN) {
+            socket.close();
+        }
+        else {
+            this.handleClose();
+        }
+    }
+    scheduleReconnect() {
+        if (!this.started || this.stopping || this.reconnectTimer !== undefined) {
+            return;
+        }
+        const delayMs = reconnectDelayMs(this.reconnectAttempts, this.reconnect);
+        this.reconnectAttempts += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            this.connect(false)
+                .catch((error) => {
+                this.emit('error', redactErrorUrl(toError(error)));
+                this.scheduleReconnect();
+            });
+        }, delayMs);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer !== undefined) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+    }
+    rejectAllPending(error) {
+        for (const [msgId, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+            this.pending.delete(msgId);
+        }
+    }
+}
+export function reconnectDelayMs(attempt, options) {
+    const delay = options.initialDelayMs * options.multiplier ** attempt;
+    return Math.min(Math.trunc(delay), options.maxDelayMs);
+}
+function heartbeatToJsonObject(heartbeat) {
+    const obj = {
+        type: heartbeat.type,
+        machine_id: heartbeat.machine_id,
+    };
+    if (heartbeat.platform !== undefined) {
+        obj['platform'] = heartbeat.platform;
+    }
+    if (heartbeat.hostname !== undefined) {
+        obj['hostname'] = heartbeat.hostname;
+    }
+    if (heartbeat.agent_version !== undefined) {
+        obj['agent_version'] = heartbeat.agent_version;
+    }
+    if (heartbeat.system !== undefined) {
+        obj['system'] = systemMetricsToJsonObject(heartbeat.system);
+    }
+    if (heartbeat.operator_id !== undefined) {
+        obj['operator_id'] = heartbeat.operator_id;
+    }
+    return obj;
+}
+function ackToJsonObject(ack) {
+    return { action: ack.action, msg_id: ack.msg_id };
+}
+function systemMetricsToJsonObject(metrics) {
+    return {
+        cpu_cores: metrics.cpu_cores,
+        cpu_speed_mhz: metrics.cpu_speed_mhz,
+        load_avg_1m: metrics.load_avg_1m,
+        load_avg_5m: metrics.load_avg_5m,
+        cpu_usage_pct: metrics.cpu_usage_pct,
+        mem_total_mb: metrics.mem_total_mb,
+        mem_available_mb: metrics.mem_available_mb,
+        disk_total_gb: metrics.disk_total_gb,
+        disk_free_gb: metrics.disk_free_gb,
+        process_count: metrics.process_count,
+    };
+}
+function settingsSnapshot(settings) {
+    const root = {
+        server: settings.server.ws_url_lan === undefined && settings.server.ws_url_wan === undefined
+            ? { ws_url: settings.server.ws_url }
+            : {
+                ws_url: settings.server.ws_url,
+                ...(settings.server.ws_url_lan !== undefined ? { ws_url_lan: settings.server.ws_url_lan } : {}),
+                ...(settings.server.ws_url_wan !== undefined ? { ws_url_wan: settings.server.ws_url_wan } : {}),
+            },
+        agent: { default_agent_id: settings.agent.default_agent_id },
+        buffer: {
+            max_memory_mb: settings.buffer.max_memory_mb,
+            flush_interval_ms: settings.buffer.flush_interval_ms,
+            ack_timeout_ms: settings.buffer.ack_timeout_ms,
+            max_retries: settings.buffer.max_retries,
+            ...(settings.buffer.dump_dir !== undefined ? { dump_dir: settings.buffer.dump_dir } : {}),
+        },
+        logging: {
+            level: settings.logging.level,
+            local_log_dir: settings.logging.local_log_dir,
+        },
+        machine_id: settings.machine_id,
+        shell: {
+            enabled: settings.shell.enabled,
+            default_cols: settings.shell.default_cols,
+            default_rows: settings.shell.default_rows,
+        },
+        relay: settings.relay.fingerprint === undefined ? {} : { fingerprint: settings.relay.fingerprint },
+        resources: {
+            memory_max_mb: settings.resources.memory_max_mb,
+            cpu_quota_percent: settings.resources.cpu_quota_percent,
+            tasks_max: settings.resources.tasks_max,
+        },
+        cmd_gate: {
+            mode: settings.cmd_gate.mode,
+            allowlist: [...settings.cmd_gate.allowlist],
+            always_approve: [...settings.cmd_gate.always_approve],
+            denylist: [...settings.cmd_gate.denylist],
+            timeout_s: settings.cmd_gate.timeout_s,
+        },
+    };
+    if (settings.owner_operator_id !== undefined) {
+        root['owner_operator_id'] = settings.owner_operator_id;
+    }
+    if (settings.pi_path !== undefined) {
+        root['pi_path'] = settings.pi_path;
+    }
+    return root;
+}
+function collectSystemMetrics() {
+    const cpus = os.cpus();
+    const load = os.loadavg();
+    const disk = readDiskMetrics();
+    return {
+        cpu_cores: cpus.length > 0 ? cpus.length : null,
+        cpu_speed_mhz: cpus[0]?.speed ?? null,
+        load_avg_1m: finiteNumberOrNull(load[0]),
+        load_avg_5m: finiteNumberOrNull(load[1]),
+        cpu_usage_pct: null,
+        mem_total_mb: bytesToMb(os.totalmem()),
+        mem_available_mb: bytesToMb(os.freemem()),
+        disk_total_gb: disk.totalGb,
+        disk_free_gb: disk.freeGb,
+        process_count: readProcessCount(),
+    };
+}
+function readDiskMetrics() {
+    try {
+        const rootPath = process.platform === 'win32' ? process.cwd().slice(0, 3) : '/';
+        const stat = fs.statfsSync(rootPath);
+        const total = (stat.blocks * stat.bsize) / 1_000_000_000;
+        const free = (stat.bavail * stat.bsize) / 1_000_000_000;
+        return { totalGb: roundTwo(total), freeGb: roundTwo(free) };
+    }
+    catch {
+        return { totalGb: null, freeGb: null };
+    }
+}
+function readProcessCount() {
+    if (process.platform !== 'linux') {
+        return null;
+    }
+    try {
+        return fs.readdirSync('/proc').filter((entry) => /^\d+$/.test(entry)).length;
+    }
+    catch {
+        return null;
+    }
+}
+function detectPlatform() {
+    if (process.platform === 'win32') {
+        return 'windows';
+    }
+    if (process.platform === 'darwin') {
+        return 'darwin';
+    }
+    if (process.platform === 'linux') {
+        return 'linux';
+    }
+    if (process.platform === 'freebsd') {
+        return 'freebsd';
+    }
+    return 'unknown';
+}
+function readHostname() {
+    const hostname = os.hostname().trim();
+    return hostname.length > 0 ? hostname : undefined;
+}
+let packageVersionCache;
+function resolvePackageVersion() {
+    if (packageVersionCache !== undefined) {
+        return packageVersionCache;
+    }
+    try {
+        const packagePath = new URL('../../package.json', import.meta.url);
+        const parsed = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+        packageVersionCache = isRecord(parsed) && typeof parsed['version'] === 'string'
+            ? parsed['version']
+            : '0.0.0';
+    }
+    catch {
+        packageVersionCache = process.env.npm_package_version ?? '0.0.0';
+    }
+    return packageVersionCache;
+}
+function verifyPeerFingerprint(cert, expectedFingerprint) {
+    if (expectedFingerprint === undefined) {
+        return undefined;
+    }
+    try {
+        const x509 = new X509Certificate(cert.raw);
+        const spki = x509.publicKey.export({ type: 'spki', format: 'der' });
+        const actual = sha256Hex(spki);
+        if (!constantTimeHexEquals(expectedFingerprint, actual)) {
+            return new Error('TLS SPKI fingerprint mismatch');
+        }
+        return undefined;
+    }
+    catch (error) {
+        return toError(error);
+    }
+}
+function normalizeFingerprint(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim().toLowerCase();
+    return /^[0-9a-f]{64}$/.test(trimmed) ? trimmed : undefined;
+}
+function matchesAction(action) {
+    return (action === 'execute' ||
+        action === 'extension_ui_response' ||
+        action === 'set_model' ||
+        action === 'set_thinking_level' ||
+        action === 'compact' ||
+        action === 'list_agents' ||
+        action === 'get_available_models' ||
+        action === 'browser_fetch');
+}
+function rawDataToString(raw) {
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (Buffer.isBuffer(raw)) {
+        return raw.toString('utf8');
+    }
+    if (Array.isArray(raw)) {
+        return Buffer.concat(raw).toString('utf8');
+    }
+    return Buffer.from(raw).toString('utf8');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isJsonValue(value) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value))) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every(isJsonValue);
+    }
+    if (isRecord(value)) {
+        return Object.values(value).every(isJsonValue);
+    }
+    return false;
+}
+function unknownRecordToJsonObject(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        out[key] = isJsonValue(value) ? value : null;
+    }
+    return out;
+}
+function isSystemMetrics(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const keys = [
+        'cpu_cores',
+        'cpu_speed_mhz',
+        'load_avg_1m',
+        'load_avg_5m',
+        'cpu_usage_pct',
+        'mem_total_mb',
+        'mem_available_mb',
+        'disk_total_gb',
+        'disk_free_gb',
+        'process_count',
+    ];
+    return keys.every((key) => value[key] === null || typeof value[key] === 'number');
+}
+function optionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function stringField(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function numberField(record, key) {
+    const value = record[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function bytesToMb(bytes) {
+    return Number.isFinite(bytes) ? Math.floor(bytes / 1_048_576) : null;
+}
+function finiteNumberOrNull(value) {
+    return Number.isFinite(value) ? value : null;
+}
+function roundTwo(value) {
+    return Math.round(value * 100) / 100;
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}