@agentxjs/core 1.9.1-dev

package/src/network/jsonrpc.ts

@@ -0,0 +1,336 @@
+/**
+ * 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
+ */
+
+import {
+  request as jsonrpcRequest,
+  notification as jsonrpcNotification,
+  success as jsonrpcSuccess,
+  error as jsonrpcError,
+  parse as jsonrpcParse,
+  parseObject as jsonrpcParseObject,
+  JsonRpcError,
+} from "jsonrpc-lite";
+import type { IParsedObject, JsonRpc } from "jsonrpc-lite";
+import type { SystemEvent } from "../event/types/base";
+
+// ============================================================================
+// Re-export jsonrpc-lite types and functions
+// ============================================================================
+
+export { JsonRpcError };
+export type { IParsedObject, JsonRpc };
+
+// ============================================================================
+// RPC Method Names
+// ============================================================================
+
+/**
+ * All RPC method names supported by AgentX
+ */
+export type RpcMethod =
+  // Container
+  | "container.create"
+  | "container.get"
+  | "container.list"
+  // Image
+  | "image.create"
+  | "image.get"
+  | "image.list"
+  | "image.delete"
+  | "image.run"
+  | "image.stop"
+  | "image.update"
+  | "image.messages"
+  // Agent
+  | "agent.get"
+  | "agent.list"
+  | "agent.destroy"
+  | "agent.destroyAll"
+  | "agent.interrupt"
+  // Message
+  | "message.send";
+
+/**
+ * Notification method names (server push)
+ */
+export type NotificationMethod =
+  | "stream.event" // Stream events (text_delta, tool_call, etc.)
+  | "control.ack"; // ACK for reliable delivery
+
+// ============================================================================
+// Request/Response Type Definitions
+// ============================================================================
+
+/**
+ * JSON-RPC Request structure
+ */
+export interface RpcRequest<M extends RpcMethod = RpcMethod, P = unknown> {
+  jsonrpc: "2.0";
+  method: M;
+  params: P;
+  id: string | number;
+}
+
+/**
+ * JSON-RPC Success Response structure
+ */
+export interface RpcSuccessResponse<R = unknown> {
+  jsonrpc: "2.0";
+  result: R;
+  id: string | number;
+}
+
+/**
+ * JSON-RPC Error Response structure
+ */
+export 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)
+ */
+export interface RpcNotification<M extends NotificationMethod = NotificationMethod, P = unknown> {
+  jsonrpc: "2.0";
+  method: M;
+  params: P;
+}
+
+/**
+ * Stream event notification params
+ */
+export interface StreamEventParams {
+  topic: string;
+  event: SystemEvent;
+}
+
+/**
+ * Control ACK notification params
+ */
+export interface ControlAckParams {
+  msgId: string;
+}
+
+// ============================================================================
+// Standard JSON-RPC Error Codes
+// ============================================================================
+
+export const RpcErrorCodes = {
+  // Standard JSON-RPC errors
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  // Server errors (reserved: -32000 to -32099)
+  SERVER_ERROR: -32000,
+  // Application errors (custom)
+  NOT_FOUND: 404,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  TIMEOUT: 408,
+} as const;
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Create a JSON-RPC request
+ */
+export function createRequest(
+  id: string | number,
+  method: RpcMethod | string,
+  params: unknown
+): JsonRpc {
+  return jsonrpcRequest(id, method, params as Record<string, unknown>);
+}
+
+/**
+ * Create a JSON-RPC notification (no response expected)
+ */
+export function createNotification(method: NotificationMethod | string, params: unknown): JsonRpc {
+  return jsonrpcNotification(method, params as Record<string, unknown>);
+}
+
+/**
+ * Create a stream event notification
+ */
+export function createStreamEvent(topic: string, event: SystemEvent): JsonRpc {
+  return jsonrpcNotification("stream.event", { topic, event });
+}
+
+/**
+ * Create an ACK notification
+ */
+export function createAckNotification(msgId: string): JsonRpc {
+  return jsonrpcNotification("control.ack", { msgId });
+}
+
+/**
+ * Create a success response
+ */
+export function createSuccessResponse(id: string | number, result: unknown): JsonRpc {
+  return jsonrpcSuccess(id, result as Record<string, unknown>);
+}
+
+/**
+ * Create an error response
+ */
+export function createErrorResponse(
+  id: string | number | null,
+  code: number,
+  message: string,
+  data?: unknown
+): JsonRpc {
+  return jsonrpcError(id, new JsonRpcError(message, code, data));
+}
+
+/**
+ * Parse a JSON-RPC message string
+ */
+export function parseMessage(message: string): IParsedObject | IParsedObject[] {
+  return jsonrpcParse(message);
+}
+
+/**
+ * Parse a JSON-RPC message object
+ */
+export function parseMessageObject(obj: unknown): IParsedObject {
+  return jsonrpcParseObject(obj);
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Check if parsed message is a request
+ */
+export function isRequest(parsed: IParsedObject): boolean {
+  return parsed.type === "request";
+}
+
+/**
+ * Check if parsed message is a notification
+ */
+export function isNotification(parsed: IParsedObject): boolean {
+  return parsed.type === "notification";
+}
+
+/**
+ * Check if parsed message is a success response
+ */
+export function isSuccessResponse(parsed: IParsedObject): boolean {
+  return parsed.type === "success";
+}
+
+/**
+ * Check if parsed message is an error response
+ */
+export function isErrorResponse(parsed: IParsedObject): boolean {
+  return parsed.type === "error";
+}
+
+/**
+ * Check if parsed message is invalid
+ */
+export function isInvalid(parsed: IParsedObject): boolean {
+  return parsed.type === "invalid";
+}
+
+/**
+ * Check if notification is a stream event
+ */
+export function isStreamEvent(parsed: IParsedObject): parsed is IParsedObject & {
+  payload: RpcNotification<"stream.event", StreamEventParams>;
+} {
+  if (parsed.type !== "notification") return false;
+  const payload = parsed.payload as RpcNotification;
+  return payload.method === "stream.event";
+}
+
+/**
+ * Check if notification is a control ACK
+ */
+export function isControlAck(parsed: IParsedObject): parsed is IParsedObject & {
+  payload: RpcNotification<"control.ack", ControlAckParams>;
+} {
+  if (parsed.type !== "notification") return false;
+  const payload = parsed.payload as RpcNotification;
+  return payload.method === "control.ack";
+}
+
+// ============================================================================
+// Method Name Mapping (for backward compatibility)
+// ============================================================================
+
+/**
+ * Map old event type names to new RPC method names
+ */
+export const eventTypeToRpcMethod: Record<string, RpcMethod> = {
+  // Container
+  container_create_request: "container.create",
+  container_get_request: "container.get",
+  container_list_request: "container.list",
+  // Image
+  image_create_request: "image.create",
+  image_get_request: "image.get",
+  image_list_request: "image.list",
+  image_delete_request: "image.delete",
+  image_run_request: "image.run",
+  image_stop_request: "image.stop",
+  image_update_request: "image.update",
+  image_messages_request: "image.messages",
+  // Agent
+  agent_get_request: "agent.get",
+  agent_list_request: "agent.list",
+  agent_destroy_request: "agent.destroy",
+  agent_destroy_all_request: "agent.destroyAll",
+  agent_interrupt_request: "agent.interrupt",
+  // Message
+  message_send_request: "message.send",
+};
+
+/**
+ * Map RPC method names back to response event types
+ */
+export const rpcMethodToResponseType: Record<RpcMethod, string> = {
+  // Container
+  "container.create": "container_create_response",
+  "container.get": "container_get_response",
+  "container.list": "container_list_response",
+  // Image
+  "image.create": "image_create_response",
+  "image.get": "image_get_response",
+  "image.list": "image_list_response",
+  "image.delete": "image_delete_response",
+  "image.run": "image_run_response",
+  "image.stop": "image_stop_response",
+  "image.update": "image_update_response",
+  "image.messages": "image_messages_response",
+  // Agent
+  "agent.get": "agent_get_response",
+  "agent.list": "agent_list_response",
+  "agent.destroy": "agent_destroy_response",
+  "agent.destroyAll": "agent_destroy_all_response",
+  "agent.interrupt": "agent_interrupt_response",
+  // Message
+  "message.send": "message_send_response",
+};

package/src/network/protocol.ts

@@ -0,0 +1,90 @@
+/**
+ * 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
+ */
+
+// ============================================================================
+// Protocol Types
+// ============================================================================
+
+/**
+ * ReliableWrapper - Wrapper for reliable messages (server → client)
+ *
+ * Contains the original message payload with a unique ID for tracking.
+ */
+export 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.
+ */
+export interface AckMessage {
+  /** Message ID being acknowledged */
+  __ack: string;
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Check if data is a ReliableWrapper
+ */
+export function isReliableWrapper(data: unknown): data is ReliableWrapper {
+  return typeof data === "object" && data !== null && "__msgId" in data && "__payload" in data;
+}
+
+/**
+ * Check if data is an AckMessage
+ */
+export function isAckMessage(data: unknown): data is AckMessage {
+  return typeof data === "object" && data !== null && "__ack" in data;
+}
+
+// ============================================================================
+// Protocol Helpers
+// ============================================================================
+
+/**
+ * Wrap a message for reliable delivery
+ */
+export function wrapMessage(msgId: string, payload: string): ReliableWrapper {
+  return { __msgId: msgId, __payload: payload };
+}
+
+/**
+ * Create an ACK message
+ */
+export function createAck(msgId: string): AckMessage {
+  return { __ack: msgId };
+}
+
+/**
+ * Unwrap a reliable message, returning the original payload
+ */
+export function unwrapMessage(wrapper: ReliableWrapper): string {
+  return wrapper.__payload;
+}
+
+/**
+ * Generate a unique message ID
+ */
+export function generateMessageId(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}

package/src/network/types.ts

@@ -0,0 +1,284 @@
+/**
+ * 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.
+ */
+
+// ============================================================================
+// Common Types
+// ============================================================================
+
+/**
+ * Unsubscribe function type
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Minimal HTTP server interface for attaching WebSocket
+ * Avoids Node.js dependency in types package
+ */
+export interface MinimalHTTPServer {
+  on(event: "upgrade", listener: (request: unknown, socket: unknown, head: unknown) => void): void;
+}
+
+// ============================================================================
+// Reliable Message Options
+// ============================================================================
+
+/**
+ * Options for reliable message sending
+ */
+export interface SendReliableOptions {
+  /**
+   * Callback when client acknowledges receipt
+   */
+  onAck?: () => void;
+
+  /**
+   * Timeout in milliseconds (default: 5000)
+   */
+  timeout?: number;
+
+  /**
+   * Callback when ACK times out
+   */
+  onTimeout?: () => void;
+}
+
+// ============================================================================
+// Channel Connection (Server-side)
+// ============================================================================
+
+/**
+ * ChannelConnection - Server-side representation of a client connection
+ */
+export 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;
+}
+
+// ============================================================================
+// Channel Server
+// ============================================================================
+
+/**
+ * ChannelServer - Accepts client connections
+ */
+export 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
+ */
+export 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;
+}
+
+// ============================================================================
+// Channel Client
+// ============================================================================
+
+/**
+ * Connection state
+ */
+export type ConnectionState = "connecting" | "open" | "closing" | "closed";
+
+/**
+ * ChannelClient - Connects to server
+ */
+export 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
+ */
+export 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>>);
+}
+
+// ============================================================================
+// Channel Provider
+// ============================================================================
+
+/**
+ * ChannelServerProvider - Factory for creating ChannelServer instances
+ */
+export interface ChannelServerProvider {
+  createServer(options?: ChannelServerOptions): ChannelServer;
+}
+
+/**
+ * ChannelClientProvider - Factory for creating ChannelClient instances
+ */
+export interface ChannelClientProvider {
+  createClient(options: ChannelClientOptions): ChannelClient;
+}