@hardlydifficult/worker-server 1.0.0

package/dist/ConnectionHandler.d.ts

@@ -0,0 +1,38 @@
+import type WebSocket from "ws";
+import { type WorkerConnectedHandler, type WorkerDisconnectedHandler, type WorkerMessageHandler, type WorkerServerLogger } from "./types.js";
+import { type WorkerPool } from "./WorkerPool.js";
+export interface ConnectionHandlerConfig {
+    authToken?: string;
+    heartbeatTimeoutMs: number;
+    heartbeatIntervalMs: number;
+}
+/**
+ * Handles WebSocket connection lifecycle and message routing.
+ *
+ * Protocol messages (registration, heartbeat) are handled internally.
+ * All other messages are dispatched by `type` to registered handlers.
+ */
+export declare class ConnectionHandler {
+    private readonly pool;
+    private readonly config;
+    private readonly messageHandlers;
+    private readonly connectedHandlers;
+    private readonly disconnectedHandlers;
+    private readonly logger;
+    constructor(pool: WorkerPool, config: ConnectionHandlerConfig, logger?: WorkerServerLogger);
+    /**
+     * Register a handler for a specific message type.
+     * Returns an unsubscribe function.
+     */
+    onMessage<T = Record<string, unknown>>(type: string, handler: WorkerMessageHandler<T>): () => void;
+    onWorkerConnected(handler: WorkerConnectedHandler): () => void;
+    onWorkerDisconnected(handler: WorkerDisconnectedHandler): () => void;
+    /** Set up event handlers for a new WebSocket connection. */
+    handleConnection(ws: WebSocket): void;
+    private handleMessage;
+    private handleRegistration;
+    private handleHeartbeat;
+    private handleDisconnect;
+    private unknownWorkerInfo;
+}
+//# sourceMappingURL=ConnectionHandler.d.ts.map

package/dist/ConnectionHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionHandler.d.ts","sourceRoot":"","sources":["../src/ConnectionHandler.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,SAAS,MAAM,IAAI,CAAC;AAGhC,OAAO,EAML,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAE9B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EAExB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAahE,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAU1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVzB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG5B;IACJ,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqC;IACvE,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAwC;IAC7E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAGzB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,uBAAuB,EAChD,MAAM,CAAC,EAAE,kBAAkB;IAK7B;;;OAGG;IACH,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,MAAM,IAAI;IAab,iBAAiB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAO9D,oBAAoB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,IAAI;IAOpE,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAkBrC,OAAO,CAAC,aAAa;IAmDrB,OAAO,CAAC,kBAAkB;IA2G1B,OAAO,CAAC,eAAe;IA2BvB,OAAO,CAAC,gBAAgB;IAqCxB,OAAO,CAAC,iBAAiB;CAc1B"}

package/dist/ConnectionHandler.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionHandler = void 0;
+const crypto_1 = require("crypto");
+const safeCompare_js_1 = require("./safeCompare.js");
+const types_js_1 = require("./types.js");
+const WorkerPool_js_1 = require("./WorkerPool.js");
+function noop() {
+    // intentional no-op
+}
+const NO_OP_LOGGER = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+};
+/**
+ * Handles WebSocket connection lifecycle and message routing.
+ *
+ * Protocol messages (registration, heartbeat) are handled internally.
+ * All other messages are dispatched by `type` to registered handlers.
+ */
+class ConnectionHandler {
+    pool;
+    config;
+    messageHandlers = new Map();
+    connectedHandlers = new Set();
+    disconnectedHandlers = new Set();
+    logger;
+    constructor(pool, config, logger) {
+        this.pool = pool;
+        this.config = config;
+        this.logger = logger ?? NO_OP_LOGGER;
+    }
+    /**
+     * Register a handler for a specific message type.
+     * Returns an unsubscribe function.
+     */
+    onMessage(type, handler) {
+        let set = this.messageHandlers.get(type);
+        if (set === undefined) {
+            set = new Set();
+            this.messageHandlers.set(type, set);
+        }
+        const h = handler;
+        set.add(h);
+        return () => {
+            set.delete(h);
+        };
+    }
+    onWorkerConnected(handler) {
+        this.connectedHandlers.add(handler);
+        return () => {
+            this.connectedHandlers.delete(handler);
+        };
+    }
+    onWorkerDisconnected(handler) {
+        this.disconnectedHandlers.add(handler);
+        return () => {
+            this.disconnectedHandlers.delete(handler);
+        };
+    }
+    /** Set up event handlers for a new WebSocket connection. */
+    handleConnection(ws) {
+        this.logger.debug("New WebSocket connection from potential worker");
+        ws.on("message", (data) => {
+            this.handleMessage(ws, data);
+        });
+        ws.on("close", (code, reason) => {
+            this.handleDisconnect(ws, code, reason.toString());
+        });
+        ws.on("error", (error) => {
+            this.logger.error("Worker WebSocket error", {
+                error: error.message,
+            });
+        });
+    }
+    handleMessage(ws, data) {
+        let message;
+        try {
+            message = JSON.parse(data.toString());
+        }
+        catch {
+            this.logger.warn("Invalid JSON message from worker");
+            return;
+        }
+        const { type } = message;
+        if (typeof type !== "string") {
+            this.logger.warn("Message missing type field");
+            return;
+        }
+        // Handle protocol messages internally
+        if (type === "worker_registration") {
+            this.handleRegistration(ws, message);
+            return;
+        }
+        if (type === "heartbeat") {
+            this.handleHeartbeat(ws, message);
+            return;
+        }
+        // Dispatch to registered handlers by type
+        const handlers = this.messageHandlers.get(type);
+        if (handlers !== undefined && handlers.size > 0) {
+            const { workerId } = ws;
+            const worker = workerId !== undefined ? this.pool.get(workerId) : undefined;
+            const info = worker !== undefined
+                ? (0, WorkerPool_js_1.toWorkerInfo)(worker)
+                : this.unknownWorkerInfo(workerId);
+            for (const handler of handlers) {
+                try {
+                    handler(info, message);
+                }
+                catch (err) {
+                    this.logger.error("Error in message handler", {
+                        type,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+        else {
+            this.logger.warn("Unhandled message type from worker", { type });
+        }
+    }
+    handleRegistration(ws, message) {
+        // Validate auth token if required
+        if (this.config.authToken !== undefined &&
+            !(0, safeCompare_js_1.safeCompare)(message.authToken ?? "", this.config.authToken)) {
+            this.logger.warn("Worker registration rejected: invalid auth token", {
+                workerId: message.workerId,
+            });
+            const ack = {
+                type: "worker_registration_ack",
+                success: false,
+                error: "Invalid authentication token",
+            };
+            ws.send(JSON.stringify(ack));
+            ws.close(4001, "Authentication failed");
+            return;
+        }
+        // Replace existing worker with same ID
+        const existing = this.pool.get(message.workerId);
+        if (existing !== undefined) {
+            this.logger.info("Replacing existing worker connection", {
+                workerId: message.workerId,
+            });
+            existing.websocket.workerId =
+                undefined;
+            try {
+                existing.websocket.close(4003, "Replaced by new connection");
+            }
+            catch {
+                // Old socket may already be dead
+            }
+            // Notify disconnected handlers for pending requests on old connection
+            if (existing.pendingRequests.size > 0) {
+                this.logger.warn("Replaced worker had pending requests", {
+                    workerId: message.workerId,
+                    count: existing.pendingRequests.size,
+                });
+                const info = (0, WorkerPool_js_1.toWorkerInfo)(existing);
+                for (const handler of this.disconnectedHandlers) {
+                    try {
+                        handler(info, existing.pendingRequests);
+                    }
+                    catch (err) {
+                        this.logger.error("Error in disconnected handler", {
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+            }
+            this.pool.remove(message.workerId);
+        }
+        const sessionId = (0, crypto_1.randomUUID)();
+        const now = new Date();
+        const worker = {
+            id: message.workerId,
+            name: message.workerName,
+            websocket: ws,
+            capabilities: message.capabilities,
+            status: types_js_1.WorkerStatus.Available,
+            sessionId,
+            connectedAt: now,
+            lastHeartbeat: now,
+            activeRequests: 0,
+            pendingRequests: new Set(),
+            completedRequests: 0,
+        };
+        this.pool.add(worker);
+        ws.workerId = message.workerId;
+        const ack = {
+            type: "worker_registration_ack",
+            success: true,
+            sessionId,
+            heartbeatIntervalMs: this.config.heartbeatIntervalMs,
+        };
+        ws.send(JSON.stringify(ack));
+        this.logger.info("Worker registered", {
+            workerId: message.workerId,
+            workerName: message.workerName,
+            models: message.capabilities.models.map((m) => m.modelId),
+            maxConcurrentRequests: message.capabilities.maxConcurrentRequests,
+        });
+        // Notify connected handlers
+        const info = (0, WorkerPool_js_1.toWorkerInfo)(worker);
+        for (const handler of this.connectedHandlers) {
+            try {
+                handler(info);
+            }
+            catch (err) {
+                this.logger.error("Error in connected handler", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    handleHeartbeat(ws, message) {
+        const worker = this.pool.get(message.workerId);
+        if (worker === undefined) {
+            this.logger.warn("Heartbeat from unknown worker", {
+                workerId: message.workerId,
+            });
+            return;
+        }
+        worker.lastHeartbeat = new Date();
+        if (worker.status === types_js_1.WorkerStatus.Unhealthy) {
+            worker.status =
+                worker.activeRequests < worker.capabilities.maxConcurrentRequests
+                    ? types_js_1.WorkerStatus.Available
+                    : types_js_1.WorkerStatus.Busy;
+        }
+        const nextDeadline = new Date(Date.now() + this.config.heartbeatTimeoutMs);
+        const ack = {
+            type: "heartbeat_ack",
+            timestamp: message.timestamp,
+            nextHeartbeatDeadline: nextDeadline.toISOString(),
+        };
+        ws.send(JSON.stringify(ack));
+    }
+    handleDisconnect(ws, code, reason) {
+        const { workerId } = ws;
+        if (workerId === undefined) {
+            this.logger.debug("Unregistered WebSocket connection closed", {
+                code,
+                reason,
+            });
+            return;
+        }
+        const worker = this.pool.get(workerId);
+        if (worker !== undefined) {
+            const info = (0, WorkerPool_js_1.toWorkerInfo)(worker);
+            const pendingCopy = new Set(worker.pendingRequests);
+            if (worker.pendingRequests.size > 0) {
+                this.logger.warn("Worker disconnected with pending requests", {
+                    workerId,
+                    count: worker.pendingRequests.size,
+                });
+            }
+            this.pool.remove(workerId);
+            this.logger.info("Worker disconnected", { workerId, code, reason });
+            for (const handler of this.disconnectedHandlers) {
+                try {
+                    handler(info, pendingCopy);
+                }
+                catch (err) {
+                    this.logger.error("Error in disconnected handler", {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+    }
+    unknownWorkerInfo(workerId) {
+        return {
+            id: workerId ?? "unknown",
+            name: "unknown",
+            status: types_js_1.WorkerStatus.Unhealthy,
+            capabilities: { models: [], maxConcurrentRequests: 0 },
+            sessionId: "",
+            connectedAt: new Date(0),
+            lastHeartbeat: new Date(0),
+            activeRequests: 0,
+            completedRequests: 0,
+            pendingRequestIds: new Set(),
+        };
+    }
+}
+exports.ConnectionHandler = ConnectionHandler;
+//# sourceMappingURL=ConnectionHandler.js.map

package/dist/ConnectionHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionHandler.js","sourceRoot":"","sources":["../src/ConnectionHandler.ts"],"names":[],"mappings":"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"}

package/dist/WorkerPool.d.ts

@@ -0,0 +1,50 @@
+import { type ConnectedWorker, type WorkerInfo, type WorkerServerLogger } from "./types.js";
+/** Convert internal ConnectedWorker to public WorkerInfo (strips websocket). */
+export declare function toWorkerInfo(w: ConnectedWorker): WorkerInfo;
+/**
+ * Manages connected worker state and selection.
+ */
+export declare class WorkerPool {
+    private readonly workers;
+    private readonly logger;
+    constructor(logger?: WorkerServerLogger);
+    add(worker: ConnectedWorker): void;
+    remove(id: string): ConnectedWorker | undefined;
+    get(id: string): ConnectedWorker | undefined;
+    has(id: string): boolean;
+    values(): IterableIterator<ConnectedWorker>;
+    /**
+     * Get the least-loaded available worker supporting the given model.
+     */
+    getAvailableWorker(model: string): ConnectedWorker | null;
+    /**
+     * Get any available worker (for tasks that don't need a specific model).
+     */
+    getAnyAvailableWorker(): ConnectedWorker | null;
+    /**
+     * Track a request as sent to a worker.
+     */
+    trackRequest(workerId: string, requestId: string): void;
+    /**
+     * Release a request from whichever worker is handling it.
+     */
+    releaseRequest(requestId: string, options?: {
+        incrementCompleted?: boolean;
+    }): void;
+    getCount(): number;
+    getAvailableCount(): number;
+    /** Get public info about all connected workers. */
+    getWorkerInfoList(): WorkerInfo[];
+    /**
+     * Check health of all workers based on heartbeat timeout.
+     * Returns IDs of workers that are presumed dead (heartbeat > timeout * 3).
+     */
+    checkHealth(heartbeatTimeoutMs: number): string[];
+    /** Send a JSON message to a specific worker. */
+    send(workerId: string, message: Record<string, unknown>): boolean;
+    /** Broadcast a JSON message to all connected workers with open sockets. */
+    broadcast(message: Record<string, unknown>): void;
+    /** Close all worker connections. */
+    closeAll(): void;
+}
+//# sourceMappingURL=WorkerPool.d.ts.map

package/dist/WorkerPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerPool.d.ts","sourceRoot":"","sources":["../src/WorkerPool.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,kBAAkB,EAExB,MAAM,YAAY,CAAC;AAapB,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,EAAE,eAAe,GAAG,UAAU,CAa3D;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,MAAM,CAAC,EAAE,kBAAkB;IAIvC,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAIlC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAQ/C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAI5C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,MAAM,IAAI,gBAAgB,CAAC,eAAe,CAAC;IAI3C;;OAEG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAkCzD;;OAEG;IACH,qBAAqB,IAAI,eAAe,GAAG,IAAI;IAY/C;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAcvD;;OAEG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,GACzC,IAAI;IAqBP,QAAQ,IAAI,MAAM;IAIlB,iBAAiB,IAAI,MAAM;IAU3B,mDAAmD;IACnD,iBAAiB,IAAI,UAAU,EAAE;IAIjC;;;OAGG;IACH,WAAW,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,EAAE;IA0BjD,gDAAgD;IAChD,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;IAiBjE,2EAA2E;IAC3E,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAajD,oCAAoC;IACpC,QAAQ,IAAI,IAAI;CAUjB"}

package/dist/WorkerPool.js

@@ -0,0 +1,220 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerPool = void 0;
+exports.toWorkerInfo = toWorkerInfo;
+const ws_1 = __importDefault(require("ws"));
+const types_js_1 = require("./types.js");
+function noop() {
+    // intentional no-op
+}
+const NO_OP_LOGGER = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+};
+/** Convert internal ConnectedWorker to public WorkerInfo (strips websocket). */
+function toWorkerInfo(w) {
+    return {
+        id: w.id,
+        name: w.name,
+        status: w.status,
+        capabilities: w.capabilities,
+        sessionId: w.sessionId,
+        connectedAt: w.connectedAt,
+        lastHeartbeat: w.lastHeartbeat,
+        activeRequests: w.activeRequests,
+        completedRequests: w.completedRequests,
+        pendingRequestIds: w.pendingRequests,
+    };
+}
+/**
+ * Manages connected worker state and selection.
+ */
+class WorkerPool {
+    workers = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = logger ?? NO_OP_LOGGER;
+    }
+    add(worker) {
+        this.workers.set(worker.id, worker);
+    }
+    remove(id) {
+        const worker = this.workers.get(id);
+        if (worker !== undefined) {
+            this.workers.delete(id);
+        }
+        return worker;
+    }
+    get(id) {
+        return this.workers.get(id);
+    }
+    has(id) {
+        return this.workers.has(id);
+    }
+    values() {
+        return this.workers.values();
+    }
+    /**
+     * Get the least-loaded available worker supporting the given model.
+     */
+    getAvailableWorker(model) {
+        let bestWorker = null;
+        let lowestLoad = Infinity;
+        for (const worker of this.workers.values()) {
+            if (worker.status !== types_js_1.WorkerStatus.Available) {
+                continue;
+            }
+            const supportsModel = worker.capabilities.models.some((m) => m.modelId === model ||
+                m.modelId.includes(model) ||
+                model.includes(m.modelId));
+            if (!supportsModel) {
+                continue;
+            }
+            if (worker.activeRequests >= worker.capabilities.maxConcurrentRequests) {
+                continue;
+            }
+            const load = worker.activeRequests / worker.capabilities.maxConcurrentRequests;
+            if (load < lowestLoad) {
+                lowestLoad = load;
+                bestWorker = worker;
+            }
+        }
+        return bestWorker;
+    }
+    /**
+     * Get any available worker (for tasks that don't need a specific model).
+     */
+    getAnyAvailableWorker() {
+        for (const w of this.workers.values()) {
+            if (w.status === types_js_1.WorkerStatus.Available ||
+                w.status === types_js_1.WorkerStatus.Busy) {
+                return w;
+            }
+        }
+        return null;
+    }
+    /**
+     * Track a request as sent to a worker.
+     */
+    trackRequest(workerId, requestId) {
+        const worker = this.workers.get(workerId);
+        if (worker === undefined) {
+            return;
+        }
+        worker.activeRequests++;
+        worker.pendingRequests.add(requestId);
+        if (worker.activeRequests >= worker.capabilities.maxConcurrentRequests) {
+            worker.status = types_js_1.WorkerStatus.Busy;
+        }
+    }
+    /**
+     * Release a request from whichever worker is handling it.
+     */
+    releaseRequest(requestId, options) {
+        for (const worker of this.workers.values()) {
+            if (worker.pendingRequests.has(requestId)) {
+                worker.pendingRequests.delete(requestId);
+                worker.activeRequests = Math.max(0, worker.activeRequests - 1);
+                if (options?.incrementCompleted === true) {
+                    worker.completedRequests++;
+                }
+                if (worker.status === types_js_1.WorkerStatus.Busy &&
+                    worker.activeRequests < worker.capabilities.maxConcurrentRequests) {
+                    worker.status = types_js_1.WorkerStatus.Available;
+                }
+                break;
+            }
+        }
+    }
+    getCount() {
+        return this.workers.size;
+    }
+    getAvailableCount() {
+        let count = 0;
+        for (const worker of this.workers.values()) {
+            if (worker.status === types_js_1.WorkerStatus.Available) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /** Get public info about all connected workers. */
+    getWorkerInfoList() {
+        return Array.from(this.workers.values()).map(toWorkerInfo);
+    }
+    /**
+     * Check health of all workers based on heartbeat timeout.
+     * Returns IDs of workers that are presumed dead (heartbeat > timeout * 3).
+     */
+    checkHealth(heartbeatTimeoutMs) {
+        const now = Date.now();
+        const deadWorkerIds = [];
+        for (const worker of this.workers.values()) {
+            const timeSinceHeartbeat = now - worker.lastHeartbeat.getTime();
+            if (timeSinceHeartbeat > heartbeatTimeoutMs) {
+                if (worker.status !== types_js_1.WorkerStatus.Unhealthy) {
+                    this.logger.warn("Worker heartbeat timeout", {
+                        workerId: worker.id,
+                        timeSinceHeartbeat,
+                        threshold: heartbeatTimeoutMs,
+                    });
+                    worker.status = types_js_1.WorkerStatus.Unhealthy;
+                }
+                if (timeSinceHeartbeat > heartbeatTimeoutMs * 3) {
+                    deadWorkerIds.push(worker.id);
+                }
+            }
+        }
+        return deadWorkerIds;
+    }
+    /** Send a JSON message to a specific worker. */
+    send(workerId, message) {
+        const worker = this.workers.get(workerId);
+        if (worker === undefined) {
+            return false;
+        }
+        if (worker.websocket.readyState !== ws_1.default.OPEN) {
+            return false;
+        }
+        try {
+            worker.websocket.send(JSON.stringify(message));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Broadcast a JSON message to all connected workers with open sockets. */
+    broadcast(message) {
+        const json = JSON.stringify(message);
+        for (const worker of this.workers.values()) {
+            if (worker.websocket.readyState === ws_1.default.OPEN) {
+                try {
+                    worker.websocket.send(json);
+                }
+                catch {
+                    // Worker may be disconnecting
+                }
+            }
+        }
+    }
+    /** Close all worker connections. */
+    closeAll() {
+        for (const worker of this.workers.values()) {
+            try {
+                worker.websocket.close(1001, "Server shutting down");
+            }
+            catch {
+                // Ignore close errors
+            }
+        }
+        this.workers.clear();
+    }
+}
+exports.WorkerPool = WorkerPool;
+//# sourceMappingURL=WorkerPool.js.map

package/dist/WorkerPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerPool.js","sourceRoot":"","sources":["../src/WorkerPool.ts"],"names":[],"mappings":"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"}

package/dist/WorkerServer.d.ts

@@ -0,0 +1,67 @@
+import type { HttpRequestHandler, WebSocketConnectionHandler, WorkerConnectedHandler, WorkerDisconnectedHandler, WorkerInfo, WorkerMessageHandler, WorkerServerOptions } from "./types.js";
+/**
+ * WebSocket server for managing remote worker connections.
+ *
+ * Handles all transport-level concerns:
+ * - HTTP + WebSocket server with path-based routing
+ * - Worker registration with optional auth
+ * - Heartbeat protocol and health checks
+ * - Message routing by `type` field to registered handlers
+ * - Worker pool management (selection, request tracking)
+ *
+ * Consumers register handlers for domain-specific messages
+ * via `onWorkerMessage()` and interact with workers via `send()`.
+ */
+export declare class WorkerServer {
+    private readonly port;
+    private readonly heartbeatTimeoutMs;
+    private readonly healthCheckIntervalMs;
+    private readonly logger;
+    private httpServer;
+    private workerWss;
+    private readonly additionalEndpoints;
+    private healthCheckInterval;
+    private readonly httpHandlers;
+    private readonly pool;
+    private readonly connectionHandler;
+    constructor(options: WorkerServerOptions);
+    /** Called when a worker successfully registers. Returns unsubscribe. */
+    onWorkerConnected(handler: WorkerConnectedHandler): () => void;
+    /** Called when a worker disconnects. Returns unsubscribe. */
+    onWorkerDisconnected(handler: WorkerDisconnectedHandler): () => void;
+    /**
+     * Register a handler for a specific worker message type.
+     * Messages are routed by the `type` field in the parsed JSON.
+     * Returns an unsubscribe function.
+     */
+    onWorkerMessage<T = Record<string, unknown>>(type: string, handler: WorkerMessageHandler<T>): () => void;
+    /** Send a JSON message to a specific worker. Returns false if failed. */
+    send(workerId: string, message: Record<string, unknown>): boolean;
+    /** Broadcast a JSON message to all connected workers. */
+    broadcast(message: Record<string, unknown>): void;
+    /** Get the least-loaded available worker supporting the given model. */
+    getAvailableWorker(model: string): WorkerInfo | null;
+    /** Get any available worker (model-agnostic). */
+    getAnyAvailableWorker(): WorkerInfo | null;
+    /** Total connected worker count. */
+    getWorkerCount(): number;
+    /** Available worker count. */
+    getAvailableWorkerCount(): number;
+    /** Get public info about all connected workers. */
+    getWorkerInfo(): WorkerInfo[];
+    /** Track a request as assigned to a worker. */
+    trackRequest(workerId: string, requestId: string): void;
+    /** Release a tracked request. */
+    releaseRequest(requestId: string, options?: {
+        incrementCompleted?: boolean;
+    }): void;
+    /** Add an HTTP handler. Handlers are called in order until one returns true. */
+    addHttpHandler(handler: HttpRequestHandler): void;
+    /** Add an additional WebSocket endpoint at a specific path. */
+    addWebSocketEndpoint(path: string, handler: WebSocketConnectionHandler): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private runHealthCheck;
+    private handleHttpRequest;
+}
+//# sourceMappingURL=WorkerServer.d.ts.map

package/dist/WorkerServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerServer.d.ts","sourceRoot":"","sources":["../src/WorkerServer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,UAAU,EACV,oBAAoB,EAEpB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAoBpB;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAE5C,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAGhC;IACJ,OAAO,CAAC,mBAAmB,CAA+C;IAC1E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4B;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoB;gBAE1C,OAAO,EAAE,mBAAmB;IAuBxC,wEAAwE;IACxE,iBAAiB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAI9D,6DAA6D;IAC7D,oBAAoB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,IAAI;IAIpE;;;;OAIG;IACH,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,MAAM,IAAI;IAMb,yEAAyE;IACzE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;IAIjE,yDAAyD;IACzD,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMjD,wEAAwE;IACxE,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAKpD,iDAAiD;IACjD,qBAAqB,IAAI,UAAU,GAAG,IAAI;IAK1C,oCAAoC;IACpC,cAAc,IAAI,MAAM;IAIxB,8BAA8B;IAC9B,uBAAuB,IAAI,MAAM;IAIjC,mDAAmD;IACnD,aAAa,IAAI,UAAU,EAAE;IAM7B,+CAA+C;IAC/C,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIvD,iCAAiC;IACjC,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,GACzC,IAAI;IAMP,gFAAgF;IAChF,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAIjD,+DAA+D;IAC/D,oBAAoB,CAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,0BAA0B,GAClC,IAAI;IAgBP,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmEhB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC3B,OAAO,CAAC,cAAc;YAkBR,iBAAiB;CAqBhC"}

package/dist/WorkerServer.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerServer = void 0;
+const http_1 = require("http");
+const ws_1 = require("ws");
+const ConnectionHandler_js_1 = require("./ConnectionHandler.js");
+const WorkerPool_js_1 = require("./WorkerPool.js");
+const DEFAULTS = {
+    heartbeatTimeoutMs: 60_000,
+    healthCheckIntervalMs: 10_000,
+    heartbeatIntervalMs: 15_000,
+};
+function noop() {
+    // intentional no-op
+}
+const NO_OP_LOGGER = {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+};
+/**
+ * WebSocket server for managing remote worker connections.
+ *
+ * Handles all transport-level concerns:
+ * - HTTP + WebSocket server with path-based routing
+ * - Worker registration with optional auth
+ * - Heartbeat protocol and health checks
+ * - Message routing by `type` field to registered handlers
+ * - Worker pool management (selection, request tracking)
+ *
+ * Consumers register handlers for domain-specific messages
+ * via `onWorkerMessage()` and interact with workers via `send()`.
+ */
+class WorkerServer {
+    port;
+    heartbeatTimeoutMs;
+    healthCheckIntervalMs;
+    logger;
+    httpServer = null;
+    workerWss = null;
+    additionalEndpoints = new Map();
+    healthCheckInterval = null;
+    httpHandlers = [];
+    pool;
+    connectionHandler;
+    constructor(options) {
+        this.port = options.port;
+        this.heartbeatTimeoutMs =
+            options.heartbeatTimeoutMs ?? DEFAULTS.heartbeatTimeoutMs;
+        this.healthCheckIntervalMs =
+            options.healthCheckIntervalMs ?? DEFAULTS.healthCheckIntervalMs;
+        this.logger = options.logger ?? NO_OP_LOGGER;
+        this.pool = new WorkerPool_js_1.WorkerPool(this.logger);
+        this.connectionHandler = new ConnectionHandler_js_1.ConnectionHandler(this.pool, {
+            authToken: options.authToken,
+            heartbeatTimeoutMs: this.heartbeatTimeoutMs,
+            heartbeatIntervalMs: options.heartbeatIntervalMs ?? DEFAULTS.heartbeatIntervalMs,
+        }, this.logger);
+    }
+    // ========== Lifecycle Events ==========
+    /** Called when a worker successfully registers. Returns unsubscribe. */
+    onWorkerConnected(handler) {
+        return this.connectionHandler.onWorkerConnected(handler);
+    }
+    /** Called when a worker disconnects. Returns unsubscribe. */
+    onWorkerDisconnected(handler) {
+        return this.connectionHandler.onWorkerDisconnected(handler);
+    }
+    /**
+     * Register a handler for a specific worker message type.
+     * Messages are routed by the `type` field in the parsed JSON.
+     * Returns an unsubscribe function.
+     */
+    onWorkerMessage(type, handler) {
+        return this.connectionHandler.onMessage(type, handler);
+    }
+    // ========== Send Messages ==========
+    /** Send a JSON message to a specific worker. Returns false if failed. */
+    send(workerId, message) {
+        return this.pool.send(workerId, message);
+    }
+    /** Broadcast a JSON message to all connected workers. */
+    broadcast(message) {
+        this.pool.broadcast(message);
+    }
+    // ========== Pool Queries ==========
+    /** Get the least-loaded available worker supporting the given model. */
+    getAvailableWorker(model) {
+        const worker = this.pool.getAvailableWorker(model);
+        return worker !== null ? (0, WorkerPool_js_1.toWorkerInfo)(worker) : null;
+    }
+    /** Get any available worker (model-agnostic). */
+    getAnyAvailableWorker() {
+        const worker = this.pool.getAnyAvailableWorker();
+        return worker !== null ? (0, WorkerPool_js_1.toWorkerInfo)(worker) : null;
+    }
+    /** Total connected worker count. */
+    getWorkerCount() {
+        return this.pool.getCount();
+    }
+    /** Available worker count. */
+    getAvailableWorkerCount() {
+        return this.pool.getAvailableCount();
+    }
+    /** Get public info about all connected workers. */
+    getWorkerInfo() {
+        return this.pool.getWorkerInfoList();
+    }
+    // ========== Request Tracking ==========
+    /** Track a request as assigned to a worker. */
+    trackRequest(workerId, requestId) {
+        this.pool.trackRequest(workerId, requestId);
+    }
+    /** Release a tracked request. */
+    releaseRequest(requestId, options) {
+        this.pool.releaseRequest(requestId, options);
+    }
+    // ========== HTTP & WebSocket Extensibility ==========
+    /** Add an HTTP handler. Handlers are called in order until one returns true. */
+    addHttpHandler(handler) {
+        this.httpHandlers.push(handler);
+    }
+    /** Add an additional WebSocket endpoint at a specific path. */
+    addWebSocketEndpoint(path, handler) {
+        const wss = new ws_1.WebSocketServer({ noServer: true });
+        wss.on("connection", (ws) => {
+            handler(ws);
+        });
+        wss.on("error", (error) => {
+            this.logger.error("WebSocket server error", {
+                path,
+                error: error.message,
+            });
+        });
+        this.additionalEndpoints.set(path, { wss, handler });
+    }
+    // ========== Server Lifecycle ==========
+    start() {
+        return new Promise((resolve, reject) => {
+            if (this.httpServer !== null) {
+                reject(new Error("WorkerServer is already running"));
+                return;
+            }
+            this.httpServer = (0, http_1.createServer)((req, res) => {
+                void this.handleHttpRequest(req, res);
+            });
+            this.workerWss = new ws_1.WebSocketServer({ noServer: true });
+            this.workerWss.on("connection", (ws) => {
+                this.connectionHandler.handleConnection(ws);
+            });
+            this.workerWss.on("error", (error) => {
+                this.logger.error("Worker WebSocket server error", {
+                    error: error.message,
+                });
+            });
+            // Route WebSocket upgrades by URL path
+            this.httpServer.on("upgrade", (request, socket, head) => {
+                const pathname = request.url ?? "/";
+                // Check additional endpoints first
+                const endpoint = this.additionalEndpoints.get(pathname);
+                if (endpoint !== undefined) {
+                    endpoint.wss.handleUpgrade(request, socket, head, (ws) => {
+                        endpoint.wss.emit("connection", ws, request);
+                    });
+                    return;
+                }
+                // Default: worker connections
+                const wss = this.workerWss;
+                if (wss !== null) {
+                    wss.handleUpgrade(request, socket, head, (ws) => {
+                        wss.emit("connection", ws, request);
+                    });
+                }
+            });
+            this.httpServer.on("error", (error) => {
+                this.logger.error("HTTP server error", { error: error.message });
+                reject(error);
+            });
+            this.httpServer.listen(this.port, () => {
+                this.logger.info("HTTP + WebSocket server started", {
+                    port: this.port,
+                });
+                this.healthCheckInterval = setInterval(() => {
+                    this.runHealthCheck();
+                }, this.healthCheckIntervalMs);
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        if (this.healthCheckInterval !== null) {
+            clearInterval(this.healthCheckInterval);
+            this.healthCheckInterval = null;
+        }
+        if (this.httpServer === null) {
+            return;
+        }
+        this.pool.closeAll();
+        if (this.workerWss !== null) {
+            this.workerWss.close();
+            this.workerWss = null;
+        }
+        for (const { wss } of this.additionalEndpoints.values()) {
+            wss.close();
+        }
+        this.additionalEndpoints.clear();
+        const server = this.httpServer;
+        return new Promise((resolve) => {
+            server.close(() => {
+                this.httpServer = null;
+                this.logger.info("HTTP + WebSocket server stopped");
+                resolve();
+            });
+        });
+    }
+    // ========== Private ==========
+    runHealthCheck() {
+        const deadWorkerIds = this.pool.checkHealth(this.heartbeatTimeoutMs);
+        for (const workerId of deadWorkerIds) {
+            const worker = this.pool.get(workerId);
+            if (worker !== undefined) {
+                this.logger.warn("Worker connection presumed dead, closing", {
+                    workerId,
+                });
+                try {
+                    worker.websocket.close(4003, "Heartbeat timeout");
+                }
+                catch {
+                    // Ignore close errors
+                }
+            }
+        }
+    }
+    async handleHttpRequest(req, res) {
+        for (const handler of this.httpHandlers) {
+            try {
+                const handled = await handler(req, res);
+                if (handled) {
+                    return;
+                }
+            }
+            catch (err) {
+                this.logger.error("HTTP handler error", {
+                    error: err instanceof Error ? err.message : String(err),
+                    url: req.url,
+                });
+            }
+        }
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found" }));
+    }
+}
+exports.WorkerServer = WorkerServer;
+//# sourceMappingURL=WorkerServer.js.map

package/dist/WorkerServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerServer.js","sourceRoot":"","sources":["../src/WorkerServer.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { WorkerServer } from "./WorkerServer.js";
+export { WorkerPool } from "./WorkerPool.js";
+export { WorkerStatus, type ModelInfo, type WorkerCapabilities, type WorkerInfo, type WorkerServerOptions, type WorkerServerLogger, type HttpRequestHandler, type WorkerMessageHandler, type WorkerConnectedHandler, type WorkerDisconnectedHandler, type WebSocketConnectionHandler, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,YAAY,EACZ,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,GAChC,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerStatus = exports.WorkerPool = exports.WorkerServer = void 0;
+var WorkerServer_js_1 = require("./WorkerServer.js");
+Object.defineProperty(exports, "WorkerServer", { enumerable: true, get: function () { return WorkerServer_js_1.WorkerServer; } });
+var WorkerPool_js_1 = require("./WorkerPool.js");
+Object.defineProperty(exports, "WorkerPool", { enumerable: true, get: function () { return WorkerPool_js_1.WorkerPool; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "WorkerStatus", { enumerable: true, get: function () { return types_js_1.WorkerStatus; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qDAAiD;AAAxC,+GAAA,YAAY,OAAA;AACrB,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,uCAYoB;AAXlB,wGAAA,YAAY,OAAA"}

package/dist/safeCompare.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Timing-safe string comparison to prevent brute-force attacks.
+ * Always takes constant time regardless of where strings differ.
+ */
+export declare function safeCompare(a: string, b: string): boolean;
+//# sourceMappingURL=safeCompare.d.ts.map

package/dist/safeCompare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeCompare.d.ts","sourceRoot":"","sources":["../src/safeCompare.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAWzD"}

package/dist/safeCompare.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeCompare = safeCompare;
+const crypto_1 = require("crypto");
+/**
+ * Timing-safe string comparison to prevent brute-force attacks.
+ * Always takes constant time regardless of where strings differ.
+ */
+function safeCompare(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) {
+        // Compare bufA against itself so the timing is consistent
+        (0, crypto_1.timingSafeEqual)(bufA, bufA);
+        return false;
+    }
+    return (0, crypto_1.timingSafeEqual)(bufA, bufB);
+}
+//# sourceMappingURL=safeCompare.js.map

package/dist/safeCompare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeCompare.js","sourceRoot":"","sources":["../src/safeCompare.ts"],"names":[],"mappings":";;AAMA,kCAWC;AAjBD,mCAAyC;AAEzC;;;GAGG;AACH,SAAgB,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAE5B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,0DAA0D;QAC1D,IAAA,wBAAe,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAA,wBAAe,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+import type { IncomingMessage, ServerResponse } from "http";
+import type WebSocket from "ws";
+/**
+ * Status of a connected worker.
+ * Managed automatically based on request tracking and heartbeat.
+ */
+export declare enum WorkerStatus {
+    Available = "available",
+    Busy = "busy",
+    Draining = "draining",
+    Unhealthy = "unhealthy"
+}
+/**
+ * Describes a model that a worker can run.
+ */
+export interface ModelInfo {
+    modelId: string;
+    displayName: string;
+    maxContextTokens: number;
+    maxOutputTokens: number;
+    supportsStreaming: boolean;
+    supportsVision?: boolean;
+    supportsTools?: boolean;
+}
+/**
+ * Describes the capabilities and resources of a worker.
+ */
+export interface WorkerCapabilities {
+    models: ModelInfo[];
+    maxConcurrentRequests: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Public worker info exposed to consumers.
+ * Does NOT include the raw WebSocket reference.
+ */
+export interface WorkerInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly status: WorkerStatus;
+    readonly capabilities: WorkerCapabilities;
+    readonly sessionId: string;
+    readonly connectedAt: Date;
+    readonly lastHeartbeat: Date;
+    readonly activeRequests: number;
+    readonly completedRequests: number;
+    readonly pendingRequestIds: ReadonlySet<string>;
+}
+/**
+ * Internal connected worker state (includes WebSocket).
+ */
+export interface ConnectedWorker {
+    readonly id: string;
+    readonly name: string;
+    readonly websocket: WebSocket;
+    readonly capabilities: WorkerCapabilities;
+    status: WorkerStatus;
+    readonly sessionId: string;
+    readonly connectedAt: Date;
+    lastHeartbeat: Date;
+    activeRequests: number;
+    readonly pendingRequests: Set<string>;
+    completedRequests: number;
+}
+/** Configuration for the WorkerServer. */
+export interface WorkerServerOptions {
+    /** Port for the HTTP + WebSocket server */
+    port: number;
+    /** Authentication token required from workers (optional) */
+    authToken?: string;
+    /** How long before a missed heartbeat marks unhealthy (default: 60000) */
+    heartbeatTimeoutMs?: number;
+    /** How often to check for stale connections (default: 10000) */
+    healthCheckIntervalMs?: number;
+    /** Heartbeat interval communicated to workers (default: 15000) */
+    heartbeatIntervalMs?: number;
+    /** Logger instance (optional, defaults to no-op) */
+    logger?: WorkerServerLogger;
+}
+/** Minimal logger interface compatible with @hardlydifficult/logger. */
+export interface WorkerServerLogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+/** HTTP request handler. Return true if handled. */
+export type HttpRequestHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+/** Handler for typed worker messages. */
+export type WorkerMessageHandler<T = Record<string, unknown>> = (worker: WorkerInfo, message: T) => void;
+/** Handler for worker lifecycle events. */
+export type WorkerConnectedHandler = (worker: WorkerInfo) => void;
+export type WorkerDisconnectedHandler = (worker: WorkerInfo, pendingRequestIds: ReadonlySet<string>) => void;
+/** Handler for additional WebSocket endpoints. */
+export type WebSocketConnectionHandler = (ws: WebSocket) => void;
+/** Worker registration message (worker → server) */
+export interface RegistrationMessage {
+    type: "worker_registration";
+    workerId: string;
+    workerName: string;
+    capabilities: WorkerCapabilities;
+    authToken?: string;
+}
+/** Registration acknowledgment (server → worker) */
+export interface RegistrationAckMessage {
+    type: "worker_registration_ack";
+    success: boolean;
+    error?: string;
+    sessionId?: string;
+    heartbeatIntervalMs?: number;
+}
+/** Heartbeat message (worker → server) */
+export interface HeartbeatMessage {
+    type: "heartbeat";
+    workerId: string;
+    timestamp: string;
+}
+/** Heartbeat acknowledgment (server → worker) */
+export interface HeartbeatAckMessage {
+    type: "heartbeat_ack";
+    timestamp: string;
+    nextHeartbeatDeadline: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerStatus = void 0;
+/**
+ * Status of a connected worker.
+ * Managed automatically based on request tracking and heartbeat.
+ */
+var WorkerStatus;
+(function (WorkerStatus) {
+    WorkerStatus["Available"] = "available";
+    WorkerStatus["Busy"] = "busy";
+    WorkerStatus["Draining"] = "draining";
+    WorkerStatus["Unhealthy"] = "unhealthy";
+})(WorkerStatus || (exports.WorkerStatus = WorkerStatus = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAIA;;;GAGG;AACH,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,uCAAuB,CAAA;IACvB,6BAAa,CAAA;IACb,qCAAqB,CAAA;IACrB,uCAAuB,CAAA;AACzB,CAAC,EALW,YAAY,4BAAZ,YAAY,QAKvB"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hardlydifficult/worker-server",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "ws": "8.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.2.3",
+    "@types/ws": "8.18.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}