@epiphytic/claudecodeui 1.0.0

package/server/orchestrator/protocol.js

@@ -0,0 +1,299 @@
+/**
+ * Orchestrator Protocol
+ *
+ * Defines message types and serialization/parsing for communication
+ * between claudecodeui and the orchestrator server.
+ */
+
+/**
+ * Message Types (Outbound: claudecodeui → Orchestrator)
+ */
+export const OutboundMessageTypes = {
+  REGISTER: "register",
+  STATUS_UPDATE: "status_update",
+  PING: "ping",
+  RESPONSE: "response",
+  RESPONSE_CHUNK: "response_chunk",
+  RESPONSE_COMPLETE: "response_complete",
+  ERROR: "error",
+  HTTP_PROXY_RESPONSE: "http_proxy_response",
+};
+
+/**
+ * Message Types (Inbound: Orchestrator → claudecodeui)
+ */
+export const InboundMessageTypes = {
+  REGISTERED: "registered",
+  PONG: "pong",
+  COMMAND: "command",
+  ERROR: "error",
+  USER_REQUEST: "user_request",
+  USER_REQUEST_FOLLOW_UP: "user_request_follow_up",
+  HTTP_PROXY_REQUEST: "http_proxy_request",
+};
+
+/**
+ * Status values for status updates
+ */
+export const StatusValues = {
+  IDLE: "idle",
+  ACTIVE: "active",
+  BUSY: "busy",
+};
+
+/**
+ * Command types from orchestrator
+ */
+export const CommandTypes = {
+  DISCONNECT: "disconnect",
+  REFRESH_STATUS: "refresh_status",
+};
+
+/**
+ * Creates a registration message
+ * @param {string} clientId - Unique client identifier
+ * @param {string} userToken - Authentication token from orchestrator
+ * @param {Object} metadata - Additional client metadata
+ * @returns {Object} Registration message
+ */
+export function createRegisterMessage(clientId, userToken, metadata = {}) {
+  return {
+    type: OutboundMessageTypes.REGISTER,
+    client_id: clientId,
+    user_token: userToken,
+    metadata: {
+      hostname: metadata.hostname || "",
+      project: metadata.project || "",
+      status: metadata.status || StatusValues.IDLE,
+      version: metadata.version || "1.0.0",
+      ...metadata,
+    },
+  };
+}
+
+/**
+ * Creates a status update message
+ * @param {string} clientId - Unique client identifier
+ * @param {string} status - Current status (idle, active, busy)
+ * @returns {Object} Status update message
+ */
+export function createStatusUpdateMessage(clientId, status) {
+  return {
+    type: OutboundMessageTypes.STATUS_UPDATE,
+    client_id: clientId,
+    status,
+  };
+}
+
+/**
+ * Creates a ping message
+ * @param {string} clientId - Unique client identifier
+ * @returns {Object} Ping message
+ */
+export function createPingMessage(clientId) {
+  return {
+    type: OutboundMessageTypes.PING,
+    client_id: clientId,
+  };
+}
+
+/**
+ * Creates a response message (for proxied requests)
+ * @param {string} requestId - Original request ID
+ * @param {Object} data - Response data
+ * @returns {Object} Response message
+ */
+export function createResponseMessage(requestId, data) {
+  return {
+    type: OutboundMessageTypes.RESPONSE,
+    request_id: requestId,
+    data,
+  };
+}
+
+/**
+ * Creates a response chunk message (for streaming)
+ * @param {string} requestId - Original request ID
+ * @param {Object} data - Chunk data
+ * @returns {Object} Response chunk message
+ */
+export function createResponseChunkMessage(requestId, data) {
+  return {
+    type: OutboundMessageTypes.RESPONSE_CHUNK,
+    request_id: requestId,
+    data,
+  };
+}
+
+/**
+ * Creates a response complete message
+ * @param {string} requestId - Original request ID
+ * @param {Object} data - Final data (optional)
+ * @returns {Object} Response complete message
+ */
+export function createResponseCompleteMessage(requestId, data = null) {
+  return {
+    type: OutboundMessageTypes.RESPONSE_COMPLETE,
+    request_id: requestId,
+    ...(data !== null && data !== undefined && { data }),
+  };
+}
+
+/**
+ * Creates an error message
+ * @param {string} requestId - Request ID (if applicable)
+ * @param {string} message - Error message
+ * @returns {Object} Error message
+ */
+export function createErrorMessage(requestId, message) {
+  return {
+    type: OutboundMessageTypes.ERROR,
+    ...(requestId && { request_id: requestId }),
+    message,
+  };
+}
+
+/**
+ * Serializes a message to JSON string
+ * @param {Object} message - Message object
+ * @returns {string} JSON string
+ */
+export function serialize(message) {
+  return JSON.stringify(message);
+}
+
+/**
+ * Parses a JSON string to message object
+ * @param {string} data - JSON string
+ * @returns {Object|null} Parsed message or null if invalid
+ */
+export function parse(data) {
+  try {
+    return JSON.parse(data);
+  } catch (error) {
+    console.error("[ORCHESTRATOR] Failed to parse message:", error.message);
+    return null;
+  }
+}
+
+/**
+ * Validates an inbound message has required fields
+ * @param {Object} message - Message to validate
+ * @returns {boolean} True if valid
+ */
+export function validateInboundMessage(message) {
+  if (!message || typeof message !== "object") {
+    return false;
+  }
+
+  if (!message.type) {
+    return false;
+  }
+
+  // Validate specific message types
+  switch (message.type) {
+    case InboundMessageTypes.REGISTERED:
+      return typeof message.success === "boolean";
+
+    case InboundMessageTypes.PONG:
+      return true;
+
+    case InboundMessageTypes.COMMAND:
+      return typeof message.command === "string";
+
+    case InboundMessageTypes.ERROR:
+      return typeof message.message === "string";
+
+    case InboundMessageTypes.USER_REQUEST:
+      // user_request message structure:
+      // {
+      //   type: "user_request",
+      //   request_id: string,          // Unique request identifier
+      //   action: string,              // Action to perform (e.g., "claude-command")
+      //   payload: {
+      //     auth_token?: string,       // GitHub OAuth token for pass-through auth
+      //     user?: {                   // Optional pre-validated user info
+      //       id: string,
+      //       username: string,
+      //       email?: string
+      //     },
+      //     ...                        // Action-specific payload data
+      //   }
+      // }
+      return (
+        typeof message.request_id === "string" &&
+        typeof message.action === "string"
+      );
+
+    case InboundMessageTypes.USER_REQUEST_FOLLOW_UP:
+      // user_request_follow_up message structure:
+      // {
+      //   type: "user_request_follow_up",
+      //   request_id: string,          // Request ID of existing session
+      //   payload: {
+      //     ...                        // Follow-up message data
+      //   }
+      // }
+      return typeof message.request_id === "string";
+
+    case InboundMessageTypes.HTTP_PROXY_REQUEST:
+      // http_proxy_request message structure:
+      // {
+      //   type: "http_proxy_request",
+      //   request_id: string,          // Unique request identifier
+      //   method: string,              // HTTP method (GET, POST, etc.)
+      //   path: string,                // Request path
+      //   headers: [[string, string]], // Headers as key-value pairs
+      //   body?: string,               // Optional request body
+      //   query?: string,              // Optional query string
+      //   proxy_base?: string,         // Base path for URL rewriting (e.g., "/clients/{id}/proxy")
+      // }
+      return (
+        typeof message.request_id === "string" &&
+        typeof message.method === "string" &&
+        typeof message.path === "string"
+      );
+
+    default:
+      // Unknown message types are considered valid (forward compatibility)
+      return true;
+  }
+}
+
+/**
+ * Creates an auth error response message
+ * @param {string} requestId - Request ID
+ * @param {string} error - Error message
+ * @returns {Object} Auth error message
+ */
+export function createAuthErrorMessage(requestId, error) {
+  return {
+    type: OutboundMessageTypes.ERROR,
+    request_id: requestId,
+    auth_error: true,
+    message: error,
+  };
+}
+
+/**
+ * Creates an HTTP proxy response message
+ * @param {string} requestId - Original request ID
+ * @param {number} status - HTTP status code
+ * @param {Array<[string, string]>} headers - Response headers as [key, value] pairs
+ * @param {string} body - Response body
+ * @returns {Object} HTTP proxy response message
+ */
+export function createHttpProxyResponseMessage(
+  requestId,
+  status,
+  headers,
+  body,
+) {
+  return {
+    type: OutboundMessageTypes.HTTP_PROXY_RESPONSE,
+    request_id: requestId,
+    status,
+    headers,
+    body,
+  };
+}

package/server/orchestrator/proxy.js

@@ -0,0 +1,364 @@
+/**
+ * Orchestrator Proxy
+ *
+ * Provides a proxy layer that allows existing WebSocket handlers to work
+ * with requests forwarded through the orchestrator. The OrchestratorProxySocket
+ * implements a WebSocket-like interface so existing handlers can be reused unchanged.
+ */
+
+import { EventEmitter } from "events";
+import { createAuthErrorMessage, InboundMessageTypes } from "./protocol.js";
+import { createGitHubAuthFromEnv } from "./github-auth.js";
+
+/**
+ * OrchestratorProxySocket
+ *
+ * A "virtual WebSocket" that wraps orchestrator client communication.
+ * Allows existing handleChatConnection and related handlers to work
+ * with orchestrator-proxied requests without modification.
+ */
+export class OrchestratorProxySocket extends EventEmitter {
+  /**
+   * Creates a new proxy socket
+   * @param {OrchestratorClient} orchestratorClient - The orchestrator client
+   * @param {string} requestId - The request ID for this proxied session
+   * @param {Object} [options] - Additional options
+   * @param {Object} [options.user] - User info to attach (like normal WebSocket)
+   */
+  constructor(orchestratorClient, requestId, options = {}) {
+    super();
+
+    this.orchestratorClient = orchestratorClient;
+    this.requestId = requestId;
+    this.user = options.user || {
+      id: "orchestrator",
+      username: "orchestrator",
+    };
+
+    // Mimic WebSocket readyState constants
+    this.CONNECTING = 0;
+    this.OPEN = 1;
+    this.CLOSING = 2;
+    this.CLOSED = 3;
+
+    // Start in OPEN state since the orchestrator connection is already established
+    this._readyState = this.OPEN;
+
+    // Track if this socket has been closed
+    this._closed = false;
+  }
+
+  /**
+   * Gets the current ready state (WebSocket-compatible)
+   * @returns {number} Ready state constant
+   */
+  get readyState() {
+    if (this._closed) {
+      return this.CLOSED;
+    }
+    if (!this.orchestratorClient || !this.orchestratorClient.isConnected) {
+      return this.CLOSED;
+    }
+    return this._readyState;
+  }
+
+  /**
+   * Sends data through the orchestrator connection
+   * This is the key method that existing handlers use to send responses.
+   * @param {string|Object} data - Data to send
+   */
+  send(data) {
+    if (this._closed || !this.orchestratorClient) {
+      console.warn("[ORCHESTRATOR-PROXY] Cannot send, socket closed");
+      return;
+    }
+
+    // Parse data if it's a string
+    let parsedData = data;
+    if (typeof data === "string") {
+      try {
+        parsedData = JSON.parse(data);
+      } catch (e) {
+        // Not JSON, send as-is wrapped in data field
+        parsedData = { raw: data };
+      }
+    }
+
+    // Forward through orchestrator as a response chunk
+    this.orchestratorClient.sendResponseChunk(this.requestId, parsedData);
+  }
+
+  /**
+   * Closes the proxy socket
+   * @param {number} [code] - Close code
+   * @param {string} [reason] - Close reason
+   */
+  close(code, reason) {
+    if (this._closed) {
+      return;
+    }
+
+    this._closed = true;
+    this._readyState = this.CLOSED;
+
+    // Send completion message through orchestrator
+    if (this.orchestratorClient && this.orchestratorClient.isConnected) {
+      this.orchestratorClient.sendResponseComplete(this.requestId, {
+        code: code || 1000,
+        reason: reason || "Normal close",
+      });
+    }
+
+    this.emit("close", code, reason);
+  }
+
+  /**
+   * Terminates the connection immediately
+   */
+  terminate() {
+    this.close(1006, "Terminated");
+  }
+
+  /**
+   * Simulates receiving a message (for orchestrator to inject user messages)
+   * @param {Object} data - Message data from user via orchestrator
+   */
+  injectMessage(data) {
+    if (this._closed) {
+      return;
+    }
+
+    // Emit as if it came from the WebSocket
+    this.emit("message", JSON.stringify(data));
+  }
+
+  /**
+   * Simulates an error (for orchestrator to inject errors)
+   * @param {Error} error - Error object
+   */
+  injectError(error) {
+    this.emit("error", error);
+  }
+}
+
+/**
+ * OrchestratorProxyWriter
+ *
+ * Wraps OrchestratorProxySocket to match the WebSocketWriter interface
+ * used in server/index.js handleChatConnection
+ */
+export class OrchestratorProxyWriter {
+  /**
+   * Creates a new proxy writer
+   * @param {OrchestratorProxySocket} proxySocket - The proxy socket
+   */
+  constructor(proxySocket) {
+    this.proxySocket = proxySocket;
+    this.sessionId = null;
+    this.isWebSocketWriter = true;
+  }
+
+  /**
+   * Sends data through the proxy
+   * @param {Object} data - Data to send
+   */
+  send(data) {
+    if (this.proxySocket.readyState === this.proxySocket.OPEN) {
+      // Send as JSON (matches WebSocketWriter behavior)
+      this.proxySocket.send(data);
+    }
+  }
+
+  /**
+   * Sets the session ID
+   * @param {string} sessionId - Session ID
+   */
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+
+  /**
+   * Gets the session ID
+   * @returns {string|null} Session ID
+   */
+  getSessionId() {
+    return this.sessionId;
+  }
+}
+
+/**
+ * Creates a request handler for orchestrator user requests
+ *
+ * This factory creates a handler that:
+ * 1. Authenticates the request using pass-through GitHub OAuth
+ * 2. Creates a proxy socket for each request
+ * 3. Routes the request to the appropriate existing handler
+ * 4. Manages the proxy socket lifecycle
+ *
+ * @param {Object} handlers - Object containing handler functions
+ * @param {Function} handlers.handleChatMessage - Function to handle chat messages
+ * @param {Object} statusHooks - Status tracking hooks
+ * @param {Object} [authConfig] - Authentication configuration override
+ * @returns {Object} Object with handleUserRequest and setupFollowUpListener functions
+ */
+export function createUserRequestHandler(
+  handlers,
+  statusHooks,
+  authConfig = null,
+) {
+  // Track active proxy sockets by request ID
+  const activeProxySockets = new Map();
+
+  // Initialize GitHub auth validator from env or config
+  const githubAuth = authConfig || createGitHubAuthFromEnv();
+
+  // Track if follow-up listener has been registered
+  let followUpListenerRegistered = false;
+
+  /**
+   * Sets up the follow-up message listener on the orchestrator client
+   * @param {OrchestratorClient} orchestratorClient - The orchestrator client
+   */
+  function setupFollowUpListener(orchestratorClient) {
+    if (followUpListenerRegistered) {
+      return;
+    }
+
+    // Listen for follow-up messages
+    orchestratorClient.on(
+      InboundMessageTypes.USER_REQUEST_FOLLOW_UP,
+      (message) => {
+        const { request_id: requestId, payload } = message;
+        const handled = handleFollowUpMessage(
+          activeProxySockets,
+          requestId,
+          payload || {},
+        );
+        if (!handled) {
+          console.warn(
+            `[ORCHESTRATOR-PROXY] No active session found for follow-up request ${requestId}`,
+          );
+        }
+      },
+    );
+
+    followUpListenerRegistered = true;
+    console.log("[ORCHESTRATOR-PROXY] Follow-up message listener registered");
+  }
+
+  async function handleUserRequest(orchestratorClient, message) {
+    const { request_id: requestId, action } = message;
+    // Initialize payload to prevent undefined mutation errors
+    let payload = message.payload || {};
+
+    // Ensure follow-up listener is registered
+    setupFollowUpListener(orchestratorClient);
+
+    // Check if authentication is required (GitHub auth configured)
+    if (githubAuth.isConfigured) {
+      // Extract auth token from payload
+      const authToken = payload.auth_token;
+
+      // Validate the token
+      const authResult = await githubAuth.validate(authToken);
+
+      if (!authResult.authenticated) {
+        console.warn(
+          `[ORCHESTRATOR-PROXY] Authentication failed for request ${requestId}: ${authResult.error}`,
+        );
+        // Send auth error back through orchestrator
+        const errorMsg = createAuthErrorMessage(requestId, authResult.error);
+        orchestratorClient.ws?.send(JSON.stringify(errorMsg));
+        return null;
+      }
+
+      // Authentication succeeded - attach user info to payload
+      console.log(
+        `[ORCHESTRATOR-PROXY] Authenticated user: ${authResult.user.username} (${authResult.user.authMethod})`,
+      );
+      // Use the validated user info
+      payload.user = authResult.user;
+    }
+
+    // Create proxy socket for this request
+    const proxySocket = new OrchestratorProxySocket(
+      orchestratorClient,
+      requestId,
+      { user: payload?.user },
+    );
+
+    // Track connection for status
+    const connectionId = `orchestrator-${requestId}`;
+    statusHooks?.onConnectionOpen?.(connectionId);
+
+    // Store in active map
+    activeProxySockets.set(requestId, proxySocket);
+
+    // Clean up on close
+    proxySocket.on("close", () => {
+      activeProxySockets.delete(requestId);
+      statusHooks?.onConnectionClose?.(connectionId);
+    });
+
+    // Create writer wrapper
+    const writer = new OrchestratorProxyWriter(proxySocket);
+
+    // Route based on action
+    switch (action) {
+      case "claude-command":
+      case "cursor-command":
+      case "codex-command":
+      case "abort-session":
+      case "claude-permission-response":
+      case "cursor-abort":
+      case "check-session-status":
+      case "get-active-sessions":
+        // Inject the message as if it came from a real WebSocket
+        // The existing handler will process it via the 'message' event
+        if (handlers.handleChatMessage) {
+          handlers.handleChatMessage(
+            proxySocket,
+            writer,
+            JSON.stringify({ ...payload, type: action }),
+          );
+        }
+        break;
+
+      case "close":
+        // Handle close request
+        proxySocket.close(payload?.code, payload?.reason);
+        break;
+
+      default:
+        console.warn(`[ORCHESTRATOR-PROXY] Unknown action: ${action}`);
+        orchestratorClient.sendError(requestId, `Unknown action: ${action}`);
+        proxySocket.close(4000, "Unknown action");
+    }
+
+    return proxySocket;
+  }
+
+  // Return both the handler and setup function
+  // The handler also auto-registers the listener on first call for convenience
+  return handleUserRequest;
+}
+
+/**
+ * Handles follow-up messages for an existing proxied session
+ *
+ * @param {Map} activeProxySockets - Map of active proxy sockets
+ * @param {string} requestId - Request ID
+ * @param {Object} payload - Message payload
+ * @returns {boolean} True if handled, false if socket not found
+ */
+export function handleFollowUpMessage(activeProxySockets, requestId, payload) {
+  const proxySocket = activeProxySockets.get(requestId);
+  if (!proxySocket) {
+    return false;
+  }
+
+  proxySocket.injectMessage(payload);
+  return true;
+}
+
+export default OrchestratorProxySocket;