@agentforge/core 0.16.7 → 0.16.8

package/dist/index.cjs

@@ -4229,24 +4229,68 @@ function formatAgentResumedEvent(threadId) {
 }
 
 // src/streaming/websocket.ts
+var WEBSOCKET_OPEN = 1;
+function parseWebSocketMessage(data) {
+  if (typeof data !== "string") {
+    return data;
+  }
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}
+function normalizeThrownError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function createHeartbeatCapabilityError() {
+  return new Error(
+    "WebSocket heartbeat requires ping() and terminate() support on the provided socket"
+  );
+}
+function closeIncompatibleHeartbeatSocket(socket) {
+  if (typeof socket.close === "function") {
+    try {
+      socket.close();
+      return;
+    } catch {
+    }
+  }
+  if (typeof socket.terminate === "function") {
+    try {
+      socket.terminate();
+    } catch {
+    }
+  }
+}
 function createWebSocketHandler(options) {
   const { onConnect, onMessage, onError, onClose, heartbeat = 0 } = options;
   return function handler(ws, req) {
+    const socket = ws;
     let heartbeatInterval = null;
     let isAlive = true;
     if (heartbeat > 0) {
+      if (typeof ws.ping !== "function" || typeof ws.terminate !== "function") {
+        if (onError) {
+          onError(ws, createHeartbeatCapabilityError());
+        }
+        closeIncompatibleHeartbeatSocket(socket);
+        return;
+      }
+      const ping = ws.ping.bind(ws);
+      const terminate = ws.terminate.bind(ws);
       heartbeatInterval = setInterval(() => {
         if (!isAlive) {
           if (heartbeatInterval) {
             clearInterval(heartbeatInterval);
           }
-          ws.terminate();
+          terminate();
           return;
         }
         isAlive = false;
-        ws.ping();
+        ping();
       }, heartbeat);
-      ws.on("pong", () => {
+      socket.on("pong", () => {
         isAlive = true;
       });
     }
@@ -4255,37 +4299,28 @@ function createWebSocketHandler(options) {
         onConnect(ws, req);
       } catch (error) {
         if (onError) {
-          onError(ws, error);
+          onError(ws, normalizeThrownError(error));
         }
       }
     }
-    ws.on("message", async (data) => {
+    socket.on("message", async (data) => {
       try {
-        let message;
-        if (typeof data === "string") {
-          try {
-            message = JSON.parse(data);
-          } catch {
-            message = data;
-          }
-        } else {
-          message = data;
-        }
+        const message = parseWebSocketMessage(data);
         if (onMessage) {
           await onMessage(ws, message);
         }
       } catch (error) {
         if (onError) {
-          onError(ws, error);
+          onError(ws, normalizeThrownError(error));
         }
       }
     });
-    ws.on("error", (error) => {
+    socket.on("error", (error) => {
       if (onError) {
         onError(ws, error);
       }
     });
-    ws.on("close", (code, reason) => {
+    socket.on("close", (code, reason) => {
       if (heartbeatInterval) {
         clearInterval(heartbeatInterval);
       }
@@ -4296,14 +4331,14 @@ function createWebSocketHandler(options) {
   };
 }
 function sendMessage(ws, message) {
-  if (ws.readyState === 1) {
+  if (ws.readyState === WEBSOCKET_OPEN) {
     ws.send(JSON.stringify(message));
   }
 }
 function broadcast(clients, message) {
   const data = JSON.stringify(message);
   for (const client of clients) {
-    if (client.readyState === 1) {
+    if (client.readyState === WEBSOCKET_OPEN) {
       client.send(data);
     }
   }

package/dist/index.d.cts

@@ -4573,29 +4573,87 @@ interface SSEFormatter<T = any> {
     /** Format stream as SSE events */
     format(stream: AsyncIterable<T>): AsyncIterable<string>;
 }
+/**
+ * Binary WebSocket payload
+ */
+type WebSocketBinaryData = ArrayBuffer | ArrayBufferView | ReadonlyArray<ArrayBufferView>;
+/**
+ * Raw WebSocket message payload
+ */
+type WebSocketRawMessage = string | WebSocketBinaryData;
+/**
+ * WebSocket close reason payload
+ */
+type WebSocketCloseReason = string | WebSocketBinaryData;
+/**
+ * Minimal WebSocket-like connection contract used by streaming helpers
+ */
+type WebSocketEvent = 'pong' | 'message' | 'error' | 'close';
+/**
+ * Typed WebSocket event handler
+ */
+type WebSocketEventHandler<TEvent extends WebSocketEvent, TMessage, TCloseReason> = TEvent extends 'pong' ? () => void : TEvent extends 'message' ? (data: TMessage) => void | Promise<void> : TEvent extends 'error' ? (error: Error) => void : (code?: number, reason?: TCloseReason) => void;
+interface WebSocketConnection<TMessage = WebSocketRawMessage, TCloseReason = WebSocketCloseReason> {
+    /** Socket ready state */
+    readyState: number;
+    /** Register event handler */
+    on<TEvent extends WebSocketEvent>(event: TEvent, handler: WebSocketEventHandler<TEvent, TMessage, TCloseReason>): void;
+    /** Send string data */
+    send(data: string): void;
+    /** Close gracefully when supported by the implementation */
+    close?(): void;
+    /** Send ping when heartbeat support is available */
+    ping?(): void;
+    /** Force terminate socket when supported by the implementation */
+    terminate?(): void;
+}
+type WebSocketConnectionTypeParts<TSocket extends WebSocketConnection> = TSocket extends WebSocketConnection<infer TMessage, infer TCloseReason> ? {
+    message: TMessage;
+    closeReason: TCloseReason;
+} : {
+    message: WebSocketRawMessage;
+    closeReason: WebSocketCloseReason;
+};
+/**
+ * Extract message payload type from a WebSocket-like connection
+ */
+type WebSocketMessageFor<TSocket extends WebSocketConnection> = WebSocketConnectionTypeParts<TSocket>['message'];
+/**
+ * Extract close reason type from a WebSocket-like connection
+ */
+type WebSocketCloseReasonFor<TSocket extends WebSocketConnection> = WebSocketConnectionTypeParts<TSocket>['closeReason'];
+/**
+ * Minimal WebSocket-like send target used by send/broadcast helpers
+ */
+interface WebSocketSendTarget {
+    /** Socket ready state */
+    readyState: number;
+    /** Send string data */
+    send(data: string): void;
+}
 /**
  * WebSocket message
  */
-interface WebSocketMessage {
+interface WebSocketMessage<TData = unknown> {
     /** Message type */
     type: string;
     /** Message data */
-    data?: any;
+    data?: TData;
     /** Error information */
     error?: string;
 }
 /**
  * WebSocket handler options
  */
-interface WebSocketHandlerOptions {
+interface WebSocketHandlerOptions<TSocket extends WebSocketConnection = WebSocketConnection, TRequest = unknown> {
     /** Connection handler */
-    onConnect?: (ws: any, req?: any) => void;
+    onConnect?: (ws: TSocket, req?: TRequest) => void;
     /** Message handler */
-    onMessage?: (ws: any, message: any) => Promise<void>;
+    onMessage?: (ws: TSocket, message: unknown) => void | Promise<void>;
     /** Error handler */
-    onError?: (ws: any, error: Error) => void;
+    onError?: (ws: TSocket, error: Error) => void;
     /** Close handler */
-    onClose?: (ws: any, code?: number, reason?: string) => void;
+    onClose?: (ws: TSocket, code?: number, reason?: WebSocketCloseReasonFor<TSocket>) => void;
     /** Heartbeat interval (ms) */
     heartbeat?: number;
 }
@@ -4937,21 +4995,21 @@ declare function formatAgentResumedEvent(threadId: string): SSEEvent;
  * wss.on('connection', handler);
  * ```
  */
-declare function createWebSocketHandler(options: WebSocketHandlerOptions): (ws: any, req?: any) => void;
+declare function createWebSocketHandler<TSocket extends WebSocketConnection = WebSocketConnection, TRequest = unknown>(options: WebSocketHandlerOptions<TSocket, TRequest>): (ws: TSocket, req?: TRequest) => void;
 /**
  * Send a message through WebSocket
  *
  * Automatically serializes objects to JSON
  */
-declare function sendMessage(ws: any, message: WebSocketMessage): void;
+declare function sendMessage<TData = unknown>(ws: WebSocketSendTarget, message: WebSocketMessage<TData>): void;
 /**
  * Broadcast a message to multiple WebSocket clients
  */
-declare function broadcast(clients: Set<any>, message: WebSocketMessage): void;
+declare function broadcast<TData = unknown, TSocket extends WebSocketSendTarget = WebSocketSendTarget>(clients: Set<TSocket>, message: WebSocketMessage<TData>): void;
 /**
  * Create a WebSocket message
  */
-declare function createMessage(type: string, data?: any, error?: string): WebSocketMessage;
+declare function createMessage<TData = unknown>(type: string, data?: TData, error?: string): WebSocketMessage<TData>;
 
 /**
  * Connection pooling for database and HTTP clients
@@ -5597,4 +5655,4 @@ declare function renderTemplate(template: string, options: RenderTemplateOptions
  */
 declare function loadPrompt(promptName: string, options?: RenderTemplateOptions | PromptVariableMap, promptsDir?: string): string;
 
-export { AgentError, type AgentResumedEventData, type AgentWaitingEventData, type AggregateNode, type Alert, type AlertChannel, AlertManager, type AlertManagerOptions, type AlertRule, type AlertSeverity, type AnyInterrupt, type ApprovalRequiredInterrupt, type AuditLogEntry, type AuditLogQuery, AuditLogger, type AuditLoggerOptions, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CacheKeyGenerator, type CachingOptions, type CheckInterruptOptions, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConcurrencyOptions, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type CustomAlertChannel, type CustomInterrupt, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type EmailAlertChannel, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type EvictionStrategy, type ExecutionMetrics, type GenericAlertChannel, type HealthCheck, type HealthCheckConfig, type HealthCheckResult, HealthChecker, type HealthCheckerOptions, type HealthReport, type HealthStatus, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type HumanInLoopEventData, type HumanInLoopEventType, type HumanRequest, type HumanRequestEventData, type HumanRequestInterrupt, type HumanRequestPriority, type HumanRequestStatus, type HumanResponseEventData, type InterruptData, type InterruptEventData, type InterruptType, type JsonObject, type JsonPrimitive, type JsonValue, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, type LoggingOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority$1 as Priority, type ProductionPresetOptions, type ProfileReport, type ProfileSample, type ProfileStats, Profiler, type ProfilerOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type PromptVariableMap, type PromptVariableValue, type RateLimitOptions, type RateLimitStrategy, type ReducerFunction, RegistryEvent, type RenderTemplateOptions, type RequestConfig, type ResumeCommand, type ResumeEventData, type ResumeOptions, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SlackAlertChannel, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThreadInfo, type ThreadStatus, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolHealthCheckResult, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolRelations, ToolRelationsSchema, type ToolSimulatorConfig, type TracingOptions, type ValidationErrorHandler, type ValidationMode, type ValidationOptions, type ValidatorFunction, type WebSocketHandlerOptions, type WebSocketMessage, type WebhookAlertChannel, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createAlertManager, createApprovalRequiredInterrupt, createAuditLogger, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createCustomInterrupt, createDatabasePool, createErrorReporter, createHealthChecker, createHeartbeat, createHttpPool, createHumanRequestInterrupt, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProfiler, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSharedCache, createSharedConcurrencyController, createSharedRateLimiter, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, formatAgentResumedEvent, formatAgentWaitingEvent, formatHumanRequestEvent, formatHumanResponseEvent, formatInterruptEvent, formatResumeEvent, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getThreadStatus, getToolDescription, getToolJsonSchema, isApprovalRequiredInterrupt, isCustomInterrupt, isHumanRequestInterrupt, isMemoryCheckpointer, isTracingEnabled, loadPrompt, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, renderTemplate, retry, safeValidateSchemaDescriptions, sanitizeValue, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withCache, withConcurrency, withErrorHandler, withLogging, withMetrics, withRateLimit, withRetry, withTimeout, withTracing, withValidation };
+export { AgentError, type AgentResumedEventData, type AgentWaitingEventData, type AggregateNode, type Alert, type AlertChannel, AlertManager, type AlertManagerOptions, type AlertRule, type AlertSeverity, type AnyInterrupt, type ApprovalRequiredInterrupt, type AuditLogEntry, type AuditLogQuery, AuditLogger, type AuditLoggerOptions, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CacheKeyGenerator, type CachingOptions, type CheckInterruptOptions, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConcurrencyOptions, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type CustomAlertChannel, type CustomInterrupt, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type EmailAlertChannel, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type EvictionStrategy, type ExecutionMetrics, type GenericAlertChannel, type HealthCheck, type HealthCheckConfig, type HealthCheckResult, HealthChecker, type HealthCheckerOptions, type HealthReport, type HealthStatus, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type HumanInLoopEventData, type HumanInLoopEventType, type HumanRequest, type HumanRequestEventData, type HumanRequestInterrupt, type HumanRequestPriority, type HumanRequestStatus, type HumanResponseEventData, type InterruptData, type InterruptEventData, type InterruptType, type JsonObject, type JsonPrimitive, type JsonValue, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, type LoggingOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority$1 as Priority, type ProductionPresetOptions, type ProfileReport, type ProfileSample, type ProfileStats, Profiler, type ProfilerOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type PromptVariableMap, type PromptVariableValue, type RateLimitOptions, type RateLimitStrategy, type ReducerFunction, RegistryEvent, type RenderTemplateOptions, type RequestConfig, type ResumeCommand, type ResumeEventData, type ResumeOptions, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SlackAlertChannel, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThreadInfo, type ThreadStatus, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolHealthCheckResult, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolRelations, ToolRelationsSchema, type ToolSimulatorConfig, type TracingOptions, type ValidationErrorHandler, type ValidationMode, type ValidationOptions, type ValidatorFunction, type WebSocketBinaryData, type WebSocketCloseReason, type WebSocketCloseReasonFor, type WebSocketConnection, type WebSocketEvent, type WebSocketEventHandler, type WebSocketHandlerOptions, type WebSocketMessage, type WebSocketMessageFor, type WebSocketRawMessage, type WebSocketSendTarget, type WebhookAlertChannel, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createAlertManager, createApprovalRequiredInterrupt, createAuditLogger, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createCustomInterrupt, createDatabasePool, createErrorReporter, createHealthChecker, createHeartbeat, createHttpPool, createHumanRequestInterrupt, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProfiler, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSharedCache, createSharedConcurrencyController, createSharedRateLimiter, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, formatAgentResumedEvent, formatAgentWaitingEvent, formatHumanRequestEvent, formatHumanResponseEvent, formatInterruptEvent, formatResumeEvent, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getThreadStatus, getToolDescription, getToolJsonSchema, isApprovalRequiredInterrupt, isCustomInterrupt, isHumanRequestInterrupt, isMemoryCheckpointer, isTracingEnabled, loadPrompt, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, renderTemplate, retry, safeValidateSchemaDescriptions, sanitizeValue, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withCache, withConcurrency, withErrorHandler, withLogging, withMetrics, withRateLimit, withRetry, withTimeout, withTracing, withValidation };

package/dist/index.d.ts

@@ -4573,29 +4573,87 @@ interface SSEFormatter<T = any> {
     /** Format stream as SSE events */
     format(stream: AsyncIterable<T>): AsyncIterable<string>;
 }
+/**
+ * Binary WebSocket payload
+ */
+type WebSocketBinaryData = ArrayBuffer | ArrayBufferView | ReadonlyArray<ArrayBufferView>;
+/**
+ * Raw WebSocket message payload
+ */
+type WebSocketRawMessage = string | WebSocketBinaryData;
+/**
+ * WebSocket close reason payload
+ */
+type WebSocketCloseReason = string | WebSocketBinaryData;
+/**
+ * Minimal WebSocket-like connection contract used by streaming helpers
+ */
+type WebSocketEvent = 'pong' | 'message' | 'error' | 'close';
+/**
+ * Typed WebSocket event handler
+ */
+type WebSocketEventHandler<TEvent extends WebSocketEvent, TMessage, TCloseReason> = TEvent extends 'pong' ? () => void : TEvent extends 'message' ? (data: TMessage) => void | Promise<void> : TEvent extends 'error' ? (error: Error) => void : (code?: number, reason?: TCloseReason) => void;
+interface WebSocketConnection<TMessage = WebSocketRawMessage, TCloseReason = WebSocketCloseReason> {
+    /** Socket ready state */
+    readyState: number;
+    /** Register event handler */
+    on<TEvent extends WebSocketEvent>(event: TEvent, handler: WebSocketEventHandler<TEvent, TMessage, TCloseReason>): void;
+    /** Send string data */
+    send(data: string): void;
+    /** Close gracefully when supported by the implementation */
+    close?(): void;
+    /** Send ping when heartbeat support is available */
+    ping?(): void;
+    /** Force terminate socket when supported by the implementation */
+    terminate?(): void;
+}
+type WebSocketConnectionTypeParts<TSocket extends WebSocketConnection> = TSocket extends WebSocketConnection<infer TMessage, infer TCloseReason> ? {
+    message: TMessage;
+    closeReason: TCloseReason;
+} : {
+    message: WebSocketRawMessage;
+    closeReason: WebSocketCloseReason;
+};
+/**
+ * Extract message payload type from a WebSocket-like connection
+ */
+type WebSocketMessageFor<TSocket extends WebSocketConnection> = WebSocketConnectionTypeParts<TSocket>['message'];
+/**
+ * Extract close reason type from a WebSocket-like connection
+ */
+type WebSocketCloseReasonFor<TSocket extends WebSocketConnection> = WebSocketConnectionTypeParts<TSocket>['closeReason'];
+/**
+ * Minimal WebSocket-like send target used by send/broadcast helpers
+ */
+interface WebSocketSendTarget {
+    /** Socket ready state */
+    readyState: number;
+    /** Send string data */
+    send(data: string): void;
+}
 /**
  * WebSocket message
  */
-interface WebSocketMessage {
+interface WebSocketMessage<TData = unknown> {
     /** Message type */
     type: string;
     /** Message data */
-    data?: any;
+    data?: TData;
     /** Error information */
     error?: string;
 }
 /**
  * WebSocket handler options
  */
-interface WebSocketHandlerOptions {
+interface WebSocketHandlerOptions<TSocket extends WebSocketConnection = WebSocketConnection, TRequest = unknown> {
     /** Connection handler */
-    onConnect?: (ws: any, req?: any) => void;
+    onConnect?: (ws: TSocket, req?: TRequest) => void;
     /** Message handler */
-    onMessage?: (ws: any, message: any) => Promise<void>;
+    onMessage?: (ws: TSocket, message: unknown) => void | Promise<void>;
     /** Error handler */
-    onError?: (ws: any, error: Error) => void;
+    onError?: (ws: TSocket, error: Error) => void;
     /** Close handler */
-    onClose?: (ws: any, code?: number, reason?: string) => void;
+    onClose?: (ws: TSocket, code?: number, reason?: WebSocketCloseReasonFor<TSocket>) => void;
     /** Heartbeat interval (ms) */
     heartbeat?: number;
 }
@@ -4937,21 +4995,21 @@ declare function formatAgentResumedEvent(threadId: string): SSEEvent;
  * wss.on('connection', handler);
  * ```
  */
-declare function createWebSocketHandler(options: WebSocketHandlerOptions): (ws: any, req?: any) => void;
+declare function createWebSocketHandler<TSocket extends WebSocketConnection = WebSocketConnection, TRequest = unknown>(options: WebSocketHandlerOptions<TSocket, TRequest>): (ws: TSocket, req?: TRequest) => void;
 /**
  * Send a message through WebSocket
  *
  * Automatically serializes objects to JSON
  */
-declare function sendMessage(ws: any, message: WebSocketMessage): void;
+declare function sendMessage<TData = unknown>(ws: WebSocketSendTarget, message: WebSocketMessage<TData>): void;
 /**
  * Broadcast a message to multiple WebSocket clients
  */
-declare function broadcast(clients: Set<any>, message: WebSocketMessage): void;
+declare function broadcast<TData = unknown, TSocket extends WebSocketSendTarget = WebSocketSendTarget>(clients: Set<TSocket>, message: WebSocketMessage<TData>): void;
 /**
  * Create a WebSocket message
  */
-declare function createMessage(type: string, data?: any, error?: string): WebSocketMessage;
+declare function createMessage<TData = unknown>(type: string, data?: TData, error?: string): WebSocketMessage<TData>;
 
 /**
  * Connection pooling for database and HTTP clients
@@ -5597,4 +5655,4 @@ declare function renderTemplate(template: string, options: RenderTemplateOptions
  */
 declare function loadPrompt(promptName: string, options?: RenderTemplateOptions | PromptVariableMap, promptsDir?: string): string;
 
-export { AgentError, type AgentResumedEventData, type AgentWaitingEventData, type AggregateNode, type Alert, type AlertChannel, AlertManager, type AlertManagerOptions, type AlertRule, type AlertSeverity, type AnyInterrupt, type ApprovalRequiredInterrupt, type AuditLogEntry, type AuditLogQuery, AuditLogger, type AuditLoggerOptions, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CacheKeyGenerator, type CachingOptions, type CheckInterruptOptions, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConcurrencyOptions, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type CustomAlertChannel, type CustomInterrupt, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type EmailAlertChannel, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type EvictionStrategy, type ExecutionMetrics, type GenericAlertChannel, type HealthCheck, type HealthCheckConfig, type HealthCheckResult, HealthChecker, type HealthCheckerOptions, type HealthReport, type HealthStatus, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type HumanInLoopEventData, type HumanInLoopEventType, type HumanRequest, type HumanRequestEventData, type HumanRequestInterrupt, type HumanRequestPriority, type HumanRequestStatus, type HumanResponseEventData, type InterruptData, type InterruptEventData, type InterruptType, type JsonObject, type JsonPrimitive, type JsonValue, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, type LoggingOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority$1 as Priority, type ProductionPresetOptions, type ProfileReport, type ProfileSample, type ProfileStats, Profiler, type ProfilerOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type PromptVariableMap, type PromptVariableValue, type RateLimitOptions, type RateLimitStrategy, type ReducerFunction, RegistryEvent, type RenderTemplateOptions, type RequestConfig, type ResumeCommand, type ResumeEventData, type ResumeOptions, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SlackAlertChannel, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThreadInfo, type ThreadStatus, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolHealthCheckResult, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolRelations, ToolRelationsSchema, type ToolSimulatorConfig, type TracingOptions, type ValidationErrorHandler, type ValidationMode, type ValidationOptions, type ValidatorFunction, type WebSocketHandlerOptions, type WebSocketMessage, type WebhookAlertChannel, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createAlertManager, createApprovalRequiredInterrupt, createAuditLogger, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createCustomInterrupt, createDatabasePool, createErrorReporter, createHealthChecker, createHeartbeat, createHttpPool, createHumanRequestInterrupt, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProfiler, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSharedCache, createSharedConcurrencyController, createSharedRateLimiter, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, formatAgentResumedEvent, formatAgentWaitingEvent, formatHumanRequestEvent, formatHumanResponseEvent, formatInterruptEvent, formatResumeEvent, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getThreadStatus, getToolDescription, getToolJsonSchema, isApprovalRequiredInterrupt, isCustomInterrupt, isHumanRequestInterrupt, isMemoryCheckpointer, isTracingEnabled, loadPrompt, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, renderTemplate, retry, safeValidateSchemaDescriptions, sanitizeValue, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withCache, withConcurrency, withErrorHandler, withLogging, withMetrics, withRateLimit, withRetry, withTimeout, withTracing, withValidation };
+export { AgentError, type AgentResumedEventData, type AgentWaitingEventData, type AggregateNode, type Alert, type AlertChannel, AlertManager, type AlertManagerOptions, type AlertRule, type AlertSeverity, type AnyInterrupt, type ApprovalRequiredInterrupt, type AuditLogEntry, type AuditLogQuery, AuditLogger, type AuditLoggerOptions, type BackoffStrategy, type BatchOptions, BatchProcessor, type BatchProcessorOptions, type BatchStats, type CacheKeyGenerator, type CachingOptions, type CheckInterruptOptions, type CheckpointHistoryOptions, type CheckpointerOptions, type ChunkOptions, CircuitBreaker, type CircuitBreakerOptions, type CircuitBreakerStats, type CircuitState, type ComposeGraphsOptions, type ComposeOptions, type ComposeToolConfig, type ComposedTool, type ConcurrencyOptions, type ConditionalConfig, type ConditionalRouter, type ConditionalRouterConfig, ConnectionPool, type ConnectionPoolOptions, type ConversationConfig, type CustomAlertChannel, type CustomInterrupt, type DatabaseConfig, type DatabaseConnection, DatabasePool, type DatabasePoolOptions, type DevelopmentPresetOptions, type EmailAlertChannel, type ErrorContext, type ErrorHandlerOptions, type ErrorReporter, type ErrorReporterOptions, type EventHandler, type EvictionStrategy, type ExecutionMetrics, type GenericAlertChannel, type HealthCheck, type HealthCheckConfig, type HealthCheckResult, HealthChecker, type HealthCheckerOptions, type HealthReport, type HealthStatus, type HttpClient, type HttpConfig, HttpPool, type HttpPoolConfig, type HttpPoolOptions, type HttpResponse, type HumanInLoopEventData, type HumanInLoopEventType, type HumanRequest, type HumanRequestEventData, type HumanRequestInterrupt, type HumanRequestPriority, type HumanRequestStatus, type HumanResponseEventData, type InterruptData, type InterruptEventData, type InterruptType, type JsonObject, type JsonPrimitive, type JsonValue, type LangSmithConfig, type LogEntry, LogLevel, type Logger, type LoggerOptions, type LoggingOptions, ManagedTool, type ManagedToolConfig, type ManagedToolStats, MemoryManager, type MemoryManagerOptions, type MemoryStats, type MetricEntry, MetricType, type Metrics, type MetricsNodeOptions, type Middleware, MiddlewareChain, type MiddlewareContext, type MiddlewareFactory, type MiddlewareMetadata, type MiddlewareWithMetadata, MissingDescriptionError, type MockToolConfig, type MockToolResponse, type NodeFunction, type NodeFunctionWithContext, type ParallelNode, type ParallelWorkflowConfig, type ParallelWorkflowOptions, type PoolConfig, type PoolStats, type Priority$1 as Priority, type ProductionPresetOptions, type ProfileReport, type ProfileSample, type ProfileStats, Profiler, type ProfilerOptions, type Progress, type ProgressTracker, type ProgressTrackerOptions, type PromptOptions, type PromptVariableMap, type PromptVariableValue, type RateLimitOptions, type RateLimitStrategy, type ReducerFunction, RegistryEvent, type RenderTemplateOptions, type RequestConfig, type ResumeCommand, type ResumeEventData, type ResumeOptions, type RetryOptions, type RetryPolicy, type RouteCondition, type RouteMap, type RouteName, type SSEEvent, type SSEFormatter, type SSEFormatterOptions, type SequentialNode, type SequentialWorkflowOptions, type SimpleMiddleware, type SlackAlertChannel, type SqliteCheckpointerOptions, type StateChannelConfig, type SubgraphBuilder, type TestingPresetOptions, type ThreadConfig, type ThreadInfo, type ThreadStatus, type ThrottleOptions, TimeoutError, type TimeoutOptions, type Timer, type Tool, type BackoffStrategy$1 as ToolBackoffStrategy, ToolBuilder, ToolCategory, ToolCategorySchema, type ToolExample, ToolExampleSchema, type ToolExecution, type ToolExecutorConfig, type ToolHealthCheckResult, type ToolInvocation, type ToolMetadata, ToolMetadataSchema, ToolNameSchema, ToolRegistry, type ToolRelations, ToolRelationsSchema, type ToolSimulatorConfig, type TracingOptions, type ValidationErrorHandler, type ValidationMode, type ValidationOptions, type ValidatorFunction, type WebSocketBinaryData, type WebSocketCloseReason, type WebSocketCloseReasonFor, type WebSocketConnection, type WebSocketEvent, type WebSocketEventHandler, type WebSocketHandlerOptions, type WebSocketMessage, type WebSocketMessageFor, type WebSocketRawMessage, type WebSocketSendTarget, type WebhookAlertChannel, batch, broadcast, cache, chain, chunk, clearThread, collect, compose, composeGraphs, composeTool, composeWithOptions, conditional, configureLangSmith, createAlertManager, createApprovalRequiredInterrupt, createAuditLogger, createBatchProcessor, createBinaryRouter, createCircuitBreaker, createConditionalRouter, createConnectionPool, createConversationConfig, createCustomInterrupt, createDatabasePool, createErrorReporter, createHealthChecker, createHeartbeat, createHttpPool, createHumanRequestInterrupt, createLogger, createManagedTool, createMemoryCheckpointer, createMemoryManager, createMessage, createMetrics, createMiddlewareContext, createMockTool, createMultiRouter, createParallelWorkflow, createProfiler, createProgressTracker, createSSEFormatter, createSequentialWorkflow, createSharedCache, createSharedConcurrencyController, createSharedRateLimiter, createSqliteCheckpointer, createStateAnnotation, createSubgraph, createThreadConfig, createTool, createToolExecutor, createToolSimulator, createToolUnsafe, createWebSocketHandler, development, filter, formatAgentResumedEvent, formatAgentWaitingEvent, formatHumanRequestEvent, formatHumanResponseEvent, formatInterruptEvent, formatResumeEvent, generateThreadId, getCheckpointHistory, getLangSmithConfig, getLatestCheckpoint, getMissingDescriptions, getThreadStatus, getToolDescription, getToolJsonSchema, isApprovalRequiredInterrupt, isCustomInterrupt, isHumanRequestInterrupt, isMemoryCheckpointer, isTracingEnabled, loadPrompt, map, merge, mergeState, parallel, parseSSEEvent, presets, production, reduce, renderTemplate, retry, safeValidateSchemaDescriptions, sanitizeValue, sendMessage, sequential, sequentialBuilder, take, testing, throttle, timeout, toLangChainTool, toLangChainTools, toolBuilder, validateSchemaDescriptions, validateState, validateTool, validateToolMetadata, validateToolName, withCache, withConcurrency, withErrorHandler, withLogging, withMetrics, withRateLimit, withRetry, withTimeout, withTracing, withValidation };

package/dist/index.js

@@ -4054,24 +4054,68 @@ function formatAgentResumedEvent(threadId) {
 }
 
 // src/streaming/websocket.ts
+var WEBSOCKET_OPEN = 1;
+function parseWebSocketMessage(data) {
+  if (typeof data !== "string") {
+    return data;
+  }
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}
+function normalizeThrownError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function createHeartbeatCapabilityError() {
+  return new Error(
+    "WebSocket heartbeat requires ping() and terminate() support on the provided socket"
+  );
+}
+function closeIncompatibleHeartbeatSocket(socket) {
+  if (typeof socket.close === "function") {
+    try {
+      socket.close();
+      return;
+    } catch {
+    }
+  }
+  if (typeof socket.terminate === "function") {
+    try {
+      socket.terminate();
+    } catch {
+    }
+  }
+}
 function createWebSocketHandler(options) {
   const { onConnect, onMessage, onError, onClose, heartbeat = 0 } = options;
   return function handler(ws, req) {
+    const socket = ws;
     let heartbeatInterval = null;
     let isAlive = true;
     if (heartbeat > 0) {
+      if (typeof ws.ping !== "function" || typeof ws.terminate !== "function") {
+        if (onError) {
+          onError(ws, createHeartbeatCapabilityError());
+        }
+        closeIncompatibleHeartbeatSocket(socket);
+        return;
+      }
+      const ping = ws.ping.bind(ws);
+      const terminate = ws.terminate.bind(ws);
       heartbeatInterval = setInterval(() => {
         if (!isAlive) {
           if (heartbeatInterval) {
             clearInterval(heartbeatInterval);
           }
-          ws.terminate();
+          terminate();
           return;
         }
         isAlive = false;
-        ws.ping();
+        ping();
       }, heartbeat);
-      ws.on("pong", () => {
+      socket.on("pong", () => {
         isAlive = true;
       });
     }
@@ -4080,37 +4124,28 @@ function createWebSocketHandler(options) {
         onConnect(ws, req);
       } catch (error) {
         if (onError) {
-          onError(ws, error);
+          onError(ws, normalizeThrownError(error));
         }
       }
     }
-    ws.on("message", async (data) => {
+    socket.on("message", async (data) => {
       try {
-        let message;
-        if (typeof data === "string") {
-          try {
-            message = JSON.parse(data);
-          } catch {
-            message = data;
-          }
-        } else {
-          message = data;
-        }
+        const message = parseWebSocketMessage(data);
         if (onMessage) {
           await onMessage(ws, message);
         }
       } catch (error) {
         if (onError) {
-          onError(ws, error);
+          onError(ws, normalizeThrownError(error));
         }
       }
     });
-    ws.on("error", (error) => {
+    socket.on("error", (error) => {
       if (onError) {
         onError(ws, error);
       }
     });
-    ws.on("close", (code, reason) => {
+    socket.on("close", (code, reason) => {
       if (heartbeatInterval) {
         clearInterval(heartbeatInterval);
       }
@@ -4121,14 +4156,14 @@ function createWebSocketHandler(options) {
   };
 }
 function sendMessage(ws, message) {
-  if (ws.readyState === 1) {
+  if (ws.readyState === WEBSOCKET_OPEN) {
     ws.send(JSON.stringify(message));
   }
 }
 function broadcast(clients, message) {
   const data = JSON.stringify(message);
   for (const client of clients) {
-    if (client.readyState === 1) {
+    if (client.readyState === WEBSOCKET_OPEN) {
       client.send(data);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/core",
-  "version": "0.16.7",
+  "version": "0.16.8",
   "description": "Production-ready TypeScript agent framework built on LangGraph with orchestration, middleware, and typed abstractions.",
   "type": "module",
   "main": "./dist/index.cjs",