multipool: add public client registry API and client event forwarding; add demos & update tests

- expose safe Client Registry API on MultiWorkflowPool (getClients, getClient, getClientsForWorkflow, getIdleClients, hasClientsForWorkflow, getPoolStats)
- forward all ComfyUI WebSocket events through PoolEventManager as "client:<event>" with ClientEventPayload
- add ClientEventPayload type and update interfaces/d.ts/maps
- add demos/tests: event-forwarding-demo, client-registry-api-demo (src + dist + maps)
- update profiling and two-stage simulation tests to use localhost hosts
- update CHANGELOG to document new API, events, demos and added types

Author: igorls

CHANGELOG.md

@@ -56,13 +56,24 @@ console.log('Profile Stats:', result.profileStats);
 * **JobQueueProcessor** – Per-workflow queue processing with event-driven job assignment
 * **JobStateRegistry** – Centralized job lifecycle management with profiling integration
 * **PoolEventManager** – Extensible event system for custom monitoring and integration
+* **Public Client Registry API** – Safe access to client information and pool statistics
+  * `getClients()` – Get all registered clients with their current state
+  * `getClient(url)` – Get specific client information by URL
+  * `getClientsForWorkflow(workflow)` – Find clients with affinity for a workflow
+  * `getIdleClients()` – Get all currently available workers
+  * `hasClientsForWorkflow(workflow)` – Check if workflow can be executed
+  * `getPoolStats()` – Comprehensive pool statistics (client counts, queue depths)
 
 **Events Supported:**
 
 * Job lifecycle: `job:queued`, `job:started`, `job:completed`, `job:failed`, `job:cancelled`
 * Progress tracking: Real-time progress updates with node execution tracking
 * Preview streaming: `b_preview_meta` events with blob and metadata
 * Client state: Automatic idle/busy transitions, offline detection
+* **All ComfyUI Events**: Every WebSocket event from clients is forwarded with `client:` prefix
+  * Examples: `client:status`, `client:progress`, `client:executing`, `client:execution_cached`, `client:executed`, `client:execution_success`
+  * Use `pool.attachEventHook(eventType, listener)` to subscribe to any client event
+  * Event payload includes `clientUrl`, `clientName`, `eventType`, and original `eventData`
 
 **Performance:**
 
@@ -75,14 +86,16 @@ console.log('Profile Stats:', result.profileStats);
 
 * `docs/multipool-profiling.md` – Profiling guide for MultiWorkflowPool
 * `src/multipool/tests/profiling-demo.ts` – Complete profiling demonstration
+* `src/multipool/tests/event-forwarding-demo.ts` – Event system demonstration
+* `src/multipool/tests/client-registry-api-demo.ts` – Client registry API examples
 * `src/multipool/tests/two-stage-edit-simulation.ts` – Multi-user workflow simulation
 
 **New Exports:**
 
 * `MultiWorkflowPool` – Main pool class
 * `JobProfiler` – Per-job execution profiling (MultiWorkflowPool variant)
 * `Logger` / `createLogger` – Structured logging infrastructure
-* Types: `MultiWorkflowPoolOptions`, `JobResults`, `JobState`, `JobProfileStats`
+* Types: `MultiWorkflowPoolOptions`, `JobResults`, `JobState`, `JobProfileStats`, `PoolEvent`, `ClientEventPayload`
 
 **Use Cases:**
 

dist/multipool/interfaces.d.ts

@@ -1,8 +1,25 @@
 import { LogLevel } from "./logger.js";
+/**
+ * Pool event emitted through PoolEventManager
+ * All ComfyUI client events are forwarded with the prefix "client:"
+ */
 export interface PoolEvent {
     type: string;
     payload: any;
 }
+/**
+ * Client event payload forwarded from ComfyUI WebSocket events
+ */
+export interface ClientEventPayload {
+    /** URL of the client that emitted the event */
+    clientUrl: string;
+    /** Node name of the client */
+    clientName: string;
+    /** Original ComfyUI event type (status, progress, executing, etc.) */
+    eventType: string;
+    /** Original event data from ComfyUI */
+    eventData: any;
+}
 export interface MultiWorkflowPoolOptions {
     connectionTimeoutMs?: number;
     enableMonitoring?: boolean;

dist/multipool/interfaces.d.ts.map

@@ -39,5 +39,65 @@ export declare class MultiWorkflowPool {
         blob: Blob;
         metadata: any;
     }) => void): void;
+    /**
+     * Get a list of all registered clients with their current state
+     * @returns Array of client information objects
+     */
+    getClients(): Array<{
+        url: string;
+        nodeName: string;
+        state: "idle" | "busy" | "offline";
+        priority?: number;
+        workflowAffinityHashes?: string[];
+    }>;
+    /**
+     * Get information about a specific client by URL
+     * @param clientUrl - The URL of the client to query
+     * @returns Client information or null if not found
+     */
+    getClient(clientUrl: string): {
+        url: string;
+        nodeName: string;
+        state: "idle" | "busy" | "offline";
+        priority?: number;
+        workflowAffinityHashes?: string[];
+    } | null;
+    /**
+     * Get all clients that have affinity for a specific workflow
+     * @param workflow - The workflow to check affinity for
+     * @returns Array of client URLs that can handle this workflow
+     */
+    getClientsForWorkflow(workflow: Workflow<any>): string[];
+    /**
+     * Get all idle clients currently available for work
+     * @returns Array of idle client information
+     */
+    getIdleClients(): Array<{
+        url: string;
+        nodeName: string;
+        priority?: number;
+    }>;
+    /**
+     * Check if there are any clients available for a specific workflow
+     * @param workflow - The workflow to check
+     * @returns True if at least one client has affinity for this workflow
+     */
+    hasClientsForWorkflow(workflow: Workflow<any>): boolean;
+    /**
+     * Get statistics about the pool's current state
+     * @returns Pool statistics including client counts and queue depths
+     */
+    getPoolStats(): {
+        totalClients: number;
+        idleClients: number;
+        busyClients: number;
+        offlineClients: number;
+        totalQueues: number;
+        queues: Array<{
+            workflowHash: string;
+            pendingJobs: number;
+            type: "general" | "specific";
+        }>;
+    };
 }
 //# sourceMappingURL=multi-workflow-pool.d.ts.map