@agentxjs/core 1.9.5-dev → 1.9.7-dev

package/dist/network/index.d.ts

@@ -0,0 +1,567 @@
+import { JsonRpc, IParsedObject } from 'jsonrpc-lite';
+export { JsonRpcError } from 'jsonrpc-lite';
+import { S as SystemEvent } from '../base-m40r3Qgu.js';
+
+/**
+ * Network Types - Channel interfaces for client-server communication
+ *
+ * Provides transport-agnostic interfaces that can be implemented with:
+ * - WebSocket (Node.js, Browser)
+ * - Durable Objects WebSocket (Cloudflare Workers)
+ * - HTTP/2, gRPC, etc.
+ */
+/**
+ * Unsubscribe function type
+ */
+type Unsubscribe = () => void;
+/**
+ * Minimal HTTP server interface for attaching WebSocket
+ * Avoids Node.js dependency in types package
+ */
+interface MinimalHTTPServer {
+    on(event: "upgrade", listener: (request: unknown, socket: unknown, head: unknown) => void): void;
+}
+/**
+ * Options for reliable message sending
+ */
+interface SendReliableOptions {
+    /**
+     * Callback when client acknowledges receipt
+     */
+    onAck?: () => void;
+    /**
+     * Timeout in milliseconds (default: 5000)
+     */
+    timeout?: number;
+    /**
+     * Callback when ACK times out
+     */
+    onTimeout?: () => void;
+}
+/**
+ * ChannelConnection - Server-side representation of a client connection
+ */
+interface ChannelConnection {
+    /**
+     * Unique connection ID
+     */
+    readonly id: string;
+    /**
+     * Send message to this client (fire-and-forget)
+     */
+    send(message: string): void;
+    /**
+     * Send message with acknowledgment
+     *
+     * The message is wrapped with a unique ID. Client automatically sends ACK
+     * when received. Server triggers onAck callback upon receiving ACK.
+     *
+     * This is handled transparently by the Network layer.
+     */
+    sendReliable(message: string, options?: SendReliableOptions): void;
+    /**
+     * Register message handler
+     */
+    onMessage(handler: (message: string) => void): Unsubscribe;
+    /**
+     * Register close handler
+     */
+    onClose(handler: () => void): Unsubscribe;
+    /**
+     * Register error handler
+     */
+    onError(handler: (error: Error) => void): Unsubscribe;
+    /**
+     * Close this connection
+     */
+    close(): void;
+}
+/**
+ * ChannelServer - Accepts client connections
+ */
+interface ChannelServer {
+    /**
+     * Start listening on a port (standalone mode)
+     */
+    listen(port: number, host?: string): Promise<void>;
+    /**
+     * Attach to an existing HTTP server
+     */
+    attach(server: MinimalHTTPServer, path?: string): void;
+    /**
+     * Register connection handler
+     */
+    onConnection(handler: (connection: ChannelConnection) => void): Unsubscribe;
+    /**
+     * Broadcast message to all connected clients
+     */
+    broadcast(message: string): void;
+    /**
+     * Close server and all connections
+     */
+    close(): Promise<void>;
+    /**
+     * Dispose resources
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * ChannelServerOptions - Server configuration
+ */
+interface ChannelServerOptions {
+    /**
+     * Enable heartbeat/ping-pong (default: true)
+     */
+    heartbeat?: boolean;
+    /**
+     * Heartbeat interval in ms (default: 30000)
+     */
+    heartbeatInterval?: number;
+    /**
+     * Enable debug logging (default: false)
+     */
+    debug?: boolean;
+}
+/**
+ * Connection state
+ */
+type ConnectionState = "connecting" | "open" | "closing" | "closed";
+/**
+ * ChannelClient - Connects to server
+ */
+interface ChannelClient {
+    /**
+     * Connection state
+     */
+    readonly readyState: ConnectionState;
+    /**
+     * Connect to server
+     */
+    connect(): Promise<void>;
+    /**
+     * Send message to server
+     */
+    send(message: string): void;
+    /**
+     * Register message handler
+     */
+    onMessage(handler: (message: string) => void): Unsubscribe;
+    /**
+     * Register open handler
+     */
+    onOpen(handler: () => void): Unsubscribe;
+    /**
+     * Register close handler
+     */
+    onClose(handler: () => void): Unsubscribe;
+    /**
+     * Register error handler
+     */
+    onError(handler: (error: Error) => void): Unsubscribe;
+    /**
+     * Close connection
+     */
+    close(): void;
+    /**
+     * Dispose resources
+     */
+    dispose(): void;
+}
+/**
+ * ChannelClientOptions - Client configuration
+ */
+interface ChannelClientOptions {
+    /**
+     * Server URL
+     */
+    serverUrl: string;
+    /**
+     * Enable auto-reconnect (default: true in browser, false in Node.js)
+     */
+    autoReconnect?: boolean;
+    /**
+     * Min reconnection delay in ms (default: 1000)
+     */
+    minReconnectionDelay?: number;
+    /**
+     * Max reconnection delay in ms (default: 10000)
+     */
+    maxReconnectionDelay?: number;
+    /**
+     * Max retry attempts (default: Infinity)
+     */
+    maxRetries?: number;
+    /**
+     * Connection timeout in ms (default: 4000)
+     */
+    connectionTimeout?: number;
+    /**
+     * Enable debug logging (default: false)
+     */
+    debug?: boolean;
+    /**
+     * Custom headers for WebSocket connection
+     *
+     * - Node.js: Headers are sent during WebSocket handshake
+     * - Browser: Headers are sent in first authentication message
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+}
+/**
+ * ChannelServerProvider - Factory for creating ChannelServer instances
+ */
+interface ChannelServerProvider {
+    createServer(options?: ChannelServerOptions): ChannelServer;
+}
+/**
+ * ChannelClientProvider - Factory for creating ChannelClient instances
+ */
+interface ChannelClientProvider {
+    createClient(options: ChannelClientOptions): ChannelClient;
+}
+
+/**
+ * Reliable Message Protocol
+ *
+ * Internal protocol for message acknowledgment between server and client.
+ * This is transparent to the application layer.
+ *
+ * Flow:
+ * 1. Server sends: { __msgId: "xxx", __payload: "actual message" }
+ * 2. Client receives, extracts payload, sends: { __ack: "xxx" }
+ * 3. Server receives ACK, triggers onAck callback
+ */
+/**
+ * ReliableWrapper - Wrapper for reliable messages (server → client)
+ *
+ * Contains the original message payload with a unique ID for tracking.
+ */
+interface ReliableWrapper {
+    /** Unique message ID for tracking */
+    __msgId: string;
+    /** Original message payload */
+    __payload: string;
+}
+/**
+ * AckMessage - Acknowledgment message (client → server)
+ *
+ * Sent automatically by client when receiving a reliable message.
+ */
+interface AckMessage {
+    /** Message ID being acknowledged */
+    __ack: string;
+}
+/**
+ * Check if data is a ReliableWrapper
+ */
+declare function isReliableWrapper(data: unknown): data is ReliableWrapper;
+/**
+ * Check if data is an AckMessage
+ */
+declare function isAckMessage(data: unknown): data is AckMessage;
+/**
+ * Wrap a message for reliable delivery
+ */
+declare function wrapMessage(msgId: string, payload: string): ReliableWrapper;
+/**
+ * Create an ACK message
+ */
+declare function createAck(msgId: string): AckMessage;
+/**
+ * Unwrap a reliable message, returning the original payload
+ */
+declare function unwrapMessage(wrapper: ReliableWrapper): string;
+/**
+ * Generate a unique message ID
+ */
+declare function generateMessageId(): string;
+
+/**
+ * JSON-RPC 2.0 Protocol for AgentX Network Communication
+ *
+ * Uses jsonrpc-lite for message parsing/serialization.
+ *
+ * Message Types:
+ * - Request: Client → Server (has id, expects response)
+ * - Response: Server → Client (success or error)
+ * - Notification: Server → Client (no id, stream events)
+ *
+ * @see https://www.jsonrpc.org/specification
+ */
+
+/**
+ * All RPC method names supported by AgentX
+ */
+type RpcMethod = "container.create" | "container.get" | "container.list" | "image.create" | "image.get" | "image.list" | "image.delete" | "image.run" | "image.stop" | "image.update" | "image.messages" | "agent.get" | "agent.list" | "agent.destroy" | "agent.destroyAll" | "agent.interrupt" | "message.send";
+/**
+ * Notification method names (server push)
+ */
+type NotificationMethod = "stream.event" | "control.ack";
+/**
+ * JSON-RPC Request structure
+ */
+interface RpcRequest<M extends RpcMethod = RpcMethod, P = unknown> {
+    jsonrpc: "2.0";
+    method: M;
+    params: P;
+    id: string | number;
+}
+/**
+ * JSON-RPC Success Response structure
+ */
+interface RpcSuccessResponse<R = unknown> {
+    jsonrpc: "2.0";
+    result: R;
+    id: string | number;
+}
+/**
+ * JSON-RPC Error Response structure
+ */
+interface RpcErrorResponse {
+    jsonrpc: "2.0";
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id: string | number | null;
+}
+/**
+ * JSON-RPC Notification structure (no id, no response expected)
+ */
+interface RpcNotification<M extends NotificationMethod = NotificationMethod, P = unknown> {
+    jsonrpc: "2.0";
+    method: M;
+    params: P;
+}
+/**
+ * Stream event notification params
+ */
+interface StreamEventParams {
+    topic: string;
+    event: SystemEvent;
+}
+/**
+ * Control ACK notification params
+ */
+interface ControlAckParams {
+    msgId: string;
+}
+declare const RpcErrorCodes: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly SERVER_ERROR: -32000;
+    readonly NOT_FOUND: 404;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly TIMEOUT: 408;
+};
+/**
+ * Create a JSON-RPC request
+ */
+declare function createRequest(id: string | number, method: RpcMethod | string, params: unknown): JsonRpc;
+/**
+ * Create a JSON-RPC notification (no response expected)
+ */
+declare function createNotification(method: NotificationMethod | string, params: unknown): JsonRpc;
+/**
+ * Create a stream event notification
+ */
+declare function createStreamEvent(topic: string, event: SystemEvent): JsonRpc;
+/**
+ * Create an ACK notification
+ */
+declare function createAckNotification(msgId: string): JsonRpc;
+/**
+ * Create a success response
+ */
+declare function createSuccessResponse(id: string | number, result: unknown): JsonRpc;
+/**
+ * Create an error response
+ */
+declare function createErrorResponse(id: string | number | null, code: number, message: string, data?: unknown): JsonRpc;
+/**
+ * Parse a JSON-RPC message string
+ */
+declare function parseMessage(message: string): IParsedObject | IParsedObject[];
+/**
+ * Parse a JSON-RPC message object
+ */
+declare function parseMessageObject(obj: unknown): IParsedObject;
+/**
+ * Check if parsed message is a request
+ */
+declare function isRequest(parsed: IParsedObject): boolean;
+/**
+ * Check if parsed message is a notification
+ */
+declare function isNotification(parsed: IParsedObject): boolean;
+/**
+ * Check if parsed message is a success response
+ */
+declare function isSuccessResponse(parsed: IParsedObject): boolean;
+/**
+ * Check if parsed message is an error response
+ */
+declare function isErrorResponse(parsed: IParsedObject): boolean;
+/**
+ * Check if parsed message is invalid
+ */
+declare function isInvalid(parsed: IParsedObject): boolean;
+/**
+ * Check if notification is a stream event
+ */
+declare function isStreamEvent(parsed: IParsedObject): parsed is IParsedObject & {
+    payload: RpcNotification<"stream.event", StreamEventParams>;
+};
+/**
+ * Check if notification is a control ACK
+ */
+declare function isControlAck(parsed: IParsedObject): parsed is IParsedObject & {
+    payload: RpcNotification<"control.ack", ControlAckParams>;
+};
+/**
+ * Map old event type names to new RPC method names
+ */
+declare const eventTypeToRpcMethod: Record<string, RpcMethod>;
+/**
+ * Map RPC method names back to response event types
+ */
+declare const rpcMethodToResponseType: Record<RpcMethod, string>;
+
+/**
+ * RpcClient - JSON-RPC 2.0 Client over WebSocket
+ *
+ * Provides:
+ * - Request/Response with automatic ID matching
+ * - Notification handling (stream events)
+ * - Timeout management
+ * - Reconnection support
+ *
+ * @example
+ * ```typescript
+ * const client = new RpcClient({ url: "ws://localhost:5200" });
+ * await client.connect();
+ *
+ * // RPC call
+ * const result = await client.call("container.list", {});
+ *
+ * // Stream events
+ * client.onNotification("stream.event", (params) => {
+ *   console.log("Event:", params.event);
+ * });
+ *
+ * // Subscribe to topic
+ * client.notify("subscribe", { topic: "session-123" });
+ * ```
+ */
+
+/**
+ * RpcClient configuration
+ */
+interface RpcClientConfig {
+    /**
+     * WebSocket URL
+     */
+    url: string;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Auto reconnect on disconnect (default: true)
+     */
+    autoReconnect?: boolean;
+    /**
+     * Reconnect delay in milliseconds (default: 3000)
+     */
+    reconnectDelay?: number;
+    /**
+     * Headers for authentication (Node.js only, sent in first message for browser)
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * Notification handler
+ */
+type NotificationHandler = (method: string, params: unknown) => void;
+/**
+ * Stream event handler
+ */
+type StreamEventHandler = (topic: string, event: SystemEvent) => void;
+/**
+ * Connection state
+ */
+type RpcClientState = "disconnected" | "connecting" | "connected";
+/**
+ * JSON-RPC 2.0 Client
+ */
+declare class RpcClient {
+    private readonly config;
+    private readonly timeout;
+    private readonly pendingRequests;
+    private readonly notificationHandlers;
+    private readonly streamEventHandlers;
+    private ws;
+    private state;
+    private requestId;
+    private reconnectTimer;
+    private disposed;
+    constructor(config: RpcClientConfig);
+    /**
+     * Current connection state
+     */
+    get connectionState(): RpcClientState;
+    /**
+     * Whether client is connected
+     */
+    get connected(): boolean;
+    /**
+     * Connect to server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from server
+     */
+    disconnect(): void;
+    /**
+     * Dispose client and clean up resources
+     */
+    dispose(): void;
+    private scheduleReconnect;
+    /**
+     * Call an RPC method and wait for response
+     */
+    call<T = unknown>(method: RpcMethod, params: unknown): Promise<T>;
+    /**
+     * Send a notification (no response expected)
+     */
+    notify(method: NotificationMethod | string, params: unknown): void;
+    /**
+     * Subscribe to a topic (convenience method)
+     */
+    subscribe(topic: string): void;
+    /**
+     * Unsubscribe from a topic (convenience method)
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Register handler for all notifications
+     */
+    onNotification(handler: NotificationHandler): () => void;
+    /**
+     * Register handler for stream events
+     */
+    onStreamEvent(handler: StreamEventHandler): () => void;
+    private handleMessage;
+    private handleParsedMessage;
+}
+
+export { type AckMessage, type ChannelClient, type ChannelClientOptions, type ChannelClientProvider, type ChannelConnection, type ChannelServer, type ChannelServerOptions, type ChannelServerProvider, type ConnectionState, type ControlAckParams, type MinimalHTTPServer, type NotificationMethod, type ReliableWrapper, RpcClient, type RpcClientConfig, type RpcClientState, RpcErrorCodes, type RpcErrorResponse, type RpcMethod, type RpcNotification, type RpcRequest, type RpcSuccessResponse, type SendReliableOptions, type StreamEventParams, type Unsubscribe, createAck, createAckNotification, createErrorResponse, createNotification, createRequest, createStreamEvent, createSuccessResponse, eventTypeToRpcMethod, generateMessageId, isAckMessage, isControlAck, isErrorResponse, isInvalid, isNotification, isReliableWrapper, isRequest, isStreamEvent, isSuccessResponse, parseMessage, parseMessageObject, rpcMethodToResponseType, unwrapMessage, wrapMessage };