@bytespell/amux-client 0.0.19

package/src/client.ts

@@ -0,0 +1,445 @@
+import type { ServerMessage, AgentInfo, ModelInfo, SessionMetadata } from '@bytespell/amux-types';
+import { Connection } from './connection.js';
+import { Accumulator } from './accumulator.js';
+import type {
+  AmuxClientOptions,
+  AmuxClientEvents,
+  ConnectionStatus,
+  Message,
+  Turn,
+  PermissionOptionData,
+} from './types.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type EventHandler = (data: any) => void;
+type EventHandlers = Map<keyof AmuxClientEvents, Set<EventHandler>>;
+
+/**
+ * AmuxClient - WebSocket client for consuming amux
+ *
+ * Provides:
+ * - Connection management with auto-reconnect
+ * - Type-safe event subscription
+ * - Command methods for server interaction
+ * - Message accumulation for UI rendering
+ *
+ * @example
+ * ```typescript
+ * const client = new AmuxClient({ url: 'ws://localhost:3000/ws' });
+ *
+ * client.on('ready', (data) => console.log('Ready:', data.cwd));
+ * client.on('update', (update) => console.log('Update:', update));
+ *
+ * client.connect();
+ * client.prompt('Hello!');
+ * ```
+ */
+export class AmuxClient {
+  private connection: Connection;
+  private accumulator: Accumulator;
+  private handlers: EventHandlers = new Map();
+
+  // Session state (updated from events)
+  private _cwd: string | null = null;
+  private _sessionId: string | null = null;
+  private _agent: AgentInfo | null = null;
+  private _availableAgents: Array<{ id: string; name: string }> = [];
+  private _availableModels: ModelInfo[] = [];
+  private _currentModelId: string | null = null;
+  private _capabilities: unknown = null;
+  private _sessions: SessionMetadata[] = [];
+  private _isReady = false;
+  private _isProcessing = false;
+  private _pendingPermission: AmuxClientEvents['permission_request'] | null = null;
+
+  constructor(options: AmuxClientOptions) {
+    this.connection = new Connection({
+      url: options.url,
+      reconnect: options.reconnect ?? true,
+      reconnectInterval: options.reconnectInterval ?? 1000,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? Infinity,
+    });
+
+    this.accumulator = new Accumulator();
+
+    // Wire up connection events
+    this.connection.on('message', (msg) => this.handleMessage(msg));
+    this.connection.on('status', (status) => this.handleStatusChange(status));
+    this.connection.on('close', () => {
+      this._isReady = false;
+    });
+
+    // Auto-connect if enabled
+    if (options.autoConnect !== false) {
+      this.connect();
+    }
+  }
+
+  // ============================================================
+  // Connection lifecycle
+  // ============================================================
+
+  /**
+   * Connect to the WebSocket server
+   */
+  connect(): void {
+    this.connection.connect();
+  }
+
+  /**
+   * Disconnect from the WebSocket server
+   */
+  disconnect(): void {
+    this.connection.disconnect();
+  }
+
+  /**
+   * Whether WebSocket is connected
+   */
+  get isConnected(): boolean {
+    return this.connection.isConnected;
+  }
+
+  /**
+   * Whether client is ready (connected and received 'ready' event)
+   */
+  get isReady(): boolean {
+    return this._isReady;
+  }
+
+  /**
+   * Current connection status
+   */
+  get connectionStatus(): ConnectionStatus {
+    return this.connection.status;
+  }
+
+  // ============================================================
+  // Event subscription
+  // ============================================================
+
+  /**
+   * Subscribe to an event
+   */
+  on<K extends keyof AmuxClientEvents>(
+    event: K,
+    handler: (data: AmuxClientEvents[K]) => void
+  ): void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler as EventHandler);
+  }
+
+  /**
+   * Unsubscribe from an event
+   */
+  off<K extends keyof AmuxClientEvents>(
+    event: K,
+    handler: (data: AmuxClientEvents[K]) => void
+  ): void {
+    this.handlers.get(event)?.delete(handler as EventHandler);
+  }
+
+  /**
+   * Emit an event to handlers
+   */
+  private emit<K extends keyof AmuxClientEvents>(event: K, data: AmuxClientEvents[K]): void {
+    const handlers = this.handlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(data);
+      }
+    }
+  }
+
+  // ============================================================
+  // Session state (read-only)
+  // ============================================================
+
+  /** Current working directory */
+  get cwd(): string | null {
+    return this._cwd;
+  }
+
+  /** Current session ID */
+  get sessionId(): string | null {
+    return this._sessionId;
+  }
+
+  /** Current agent info */
+  get agent(): AgentInfo | null {
+    return this._agent;
+  }
+
+  /** Available agents */
+  get availableAgents(): Array<{ id: string; name: string }> {
+    return this._availableAgents;
+  }
+
+  /** Available models */
+  get availableModels(): ModelInfo[] {
+    return this._availableModels;
+  }
+
+  /** Current model ID */
+  get currentModelId(): string | null {
+    return this._currentModelId;
+  }
+
+  /** Agent capabilities */
+  get capabilities(): unknown {
+    return this._capabilities;
+  }
+
+  /** List of sessions (from list_sessions response) */
+  get sessions(): SessionMetadata[] {
+    return this._sessions;
+  }
+
+  // ============================================================
+  // Derived state (computed)
+  // ============================================================
+
+  /** Whether currently processing a turn */
+  get isProcessing(): boolean {
+    return this._isProcessing;
+  }
+
+  /** Whether agent is actively streaming */
+  get isStreaming(): boolean {
+    return this.accumulator.currentTurn?.status === 'streaming';
+  }
+
+  /** Whether blocked on permission request */
+  get isAwaitingPermission(): boolean {
+    return this._pendingPermission !== null;
+  }
+
+  /** Current pending permission request */
+  get pendingPermission(): AmuxClientEvents['permission_request'] | null {
+    return this._pendingPermission;
+  }
+
+  // ============================================================
+  // Message accumulator access
+  // ============================================================
+
+  /** All accumulated messages */
+  get messages(): Message[] {
+    return this.accumulator.messages;
+  }
+
+  /** All turns */
+  get turns(): Turn[] {
+    return this.accumulator.turns;
+  }
+
+  /** Current active turn */
+  get currentTurn(): Turn | null {
+    return this.accumulator.currentTurn;
+  }
+
+  /** Last user message */
+  get lastUserMessage(): Message | null {
+    return this.accumulator.lastUserMessage;
+  }
+
+  /** Last assistant message */
+  get lastAssistantMessage(): Message | null {
+    return this.accumulator.lastAssistantMessage;
+  }
+
+  // ============================================================
+  // Commands (fire-and-forget)
+  // ============================================================
+
+  /**
+   * Send a prompt to the agent
+   */
+  prompt(message: string): void {
+    this.connection.send({ type: 'prompt', message });
+  }
+
+  /**
+   * Cancel current operation
+   */
+  cancel(): void {
+    this.connection.send({ type: 'cancel' });
+  }
+
+  /**
+   * Respond to a permission request
+   */
+  respondToPermission(requestId: string, optionId: string): void {
+    this.connection.send({ type: 'permission_response', requestId, optionId });
+    this._pendingPermission = null;
+    this.accumulator.resumeStreaming();
+  }
+
+  /**
+   * Change working directory
+   */
+  changeCwd(path: string): void {
+    this.connection.send({ type: 'change_cwd', path });
+  }
+
+  /**
+   * Create a new session
+   */
+  newSession(): void {
+    this.connection.send({ type: 'new_session' });
+    this.accumulator.clear();
+  }
+
+  /**
+   * Change agent type
+   */
+  changeAgent(agentType: string): void {
+    this.connection.send({ type: 'change_agent', agentType });
+    this.accumulator.clear();
+  }
+
+  /**
+   * Set session mode
+   */
+  setMode(modeId: string): void {
+    this.connection.send({ type: 'set_mode', modeId });
+  }
+
+  /**
+   * Set model
+   */
+  setModel(modelId: string): void {
+    this.connection.send({ type: 'set_model', modelId });
+  }
+
+  /**
+   * Request list of sessions
+   */
+  requestSessions(): void {
+    this.connection.send({ type: 'list_sessions' });
+  }
+
+  /**
+   * Switch to a different session
+   */
+  switchSession(sessionId: string): void {
+    this.connection.send({ type: 'switch_session', sessionId });
+    this.accumulator.clear();
+  }
+
+  /**
+   * Request history for current session
+   */
+  requestHistory(): void {
+    this.connection.send({ type: 'get_history' });
+  }
+
+  // ============================================================
+  // Internal message handling
+  // ============================================================
+
+  private handleMessage(msg: ServerMessage): void {
+    switch (msg.type) {
+      case 'ready':
+        this._isReady = true;
+        this._cwd = msg.cwd;
+        this._sessionId = msg.sessionId;
+        this._agent = msg.agent;
+        this._availableAgents = msg.availableAgents;
+        this._availableModels = msg.availableModels ?? [];
+        this._currentModelId = msg.currentModelId ?? null;
+        this._capabilities = msg.capabilities;
+        this.emit('ready', msg);
+        break;
+
+      case 'connecting':
+        this._isReady = false;
+        this.emit('connecting', {});
+        break;
+
+      case 'session_update':
+        this.accumulator.processUpdate(msg.update);
+        this.emit('update', msg.update);
+        this.emit('messages_updated', { messages: this.messages });
+        this.emit('turns_updated', { turns: this.turns });
+        break;
+
+      case 'turn_start':
+        this._isProcessing = true;
+        this.accumulator.startTurn();
+        this.emit('turn_start', {});
+        break;
+
+      case 'turn_end':
+        this._isProcessing = false;
+        this.accumulator.endTurn();
+        this.emit('turn_end', {});
+        this.emit('messages_updated', { messages: this.messages });
+        this.emit('turns_updated', { turns: this.turns });
+        break;
+
+      case 'permission_request': {
+        const permissionData = {
+          requestId: msg.requestId,
+          toolCall: msg.toolCall,
+          options: msg.options as unknown as PermissionOptionData[],
+        };
+        this._pendingPermission = permissionData;
+        this.accumulator.setAwaitingPermission();
+        this.emit('permission_request', permissionData);
+        break;
+      }
+
+      case 'prompt_complete':
+        this.emit('prompt_complete', msg);
+        break;
+
+      case 'session_created':
+        this._sessionId = msg.sessionId;
+        this.emit('session_created', msg);
+        break;
+
+      case 'session_switched':
+        this._sessionId = msg.sessionId;
+        this.emit('session_switched', msg);
+        break;
+
+      case 'history_replay':
+        this.accumulator.replayHistory(msg.events);
+        this.emit('history_replay', msg);
+        this.emit('messages_updated', { messages: this.messages });
+        this.emit('turns_updated', { turns: this.turns });
+        break;
+
+      case 'history':
+        this.emit('history', msg);
+        break;
+
+      case 'sessions':
+        this._sessions = msg.sessions;
+        this.emit('sessions', msg);
+        break;
+
+      case 'error':
+        this.emit('error', msg);
+        break;
+
+      case 'agent_exit':
+        this._isReady = false;
+        this._isProcessing = false;
+        this.emit('agent_exit', msg);
+        break;
+    }
+  }
+
+  private handleStatusChange(status: ConnectionStatus): void {
+    if (status === 'ready') {
+      this._isReady = true;
+    } else if (status === 'disconnected') {
+      this._isReady = false;
+    }
+    this.emit('connection_status', { status });
+  }
+}

package/src/connection.ts

@@ -0,0 +1,194 @@
+import type { ClientMessage, ServerMessage } from '@bytespell/amux-types';
+import type { ConnectionStatus } from './types.js';
+
+/**
+ * Event handler types for Connection
+ */
+export interface ConnectionEvents {
+  open: () => void;
+  close: (event: { code: number; reason: string; wasClean: boolean }) => void;
+  message: (message: ServerMessage) => void;
+  error: (error: Event) => void;
+  status: (status: ConnectionStatus) => void;
+}
+
+/**
+ * Connection options
+ */
+export interface ConnectionOptions {
+  url: string;
+  reconnect?: boolean;
+  reconnectInterval?: number;
+  maxReconnectAttempts?: number;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type EventHandler = (...args: any[]) => void;
+type HandlerMap = Map<keyof ConnectionEvents, Set<EventHandler>>;
+
+/**
+ * WebSocket connection manager with auto-reconnect
+ */
+export class Connection {
+  private ws: WebSocket | null = null;
+  private reconnectAttempts = 0;
+  private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+  private _status: ConnectionStatus = 'disconnected';
+  private handlers: HandlerMap = new Map();
+
+  private readonly url: string;
+  private readonly reconnect: boolean;
+  private readonly reconnectInterval: number;
+  private readonly maxReconnectAttempts: number;
+
+  constructor(options: ConnectionOptions) {
+    this.url = options.url;
+    this.reconnect = options.reconnect ?? true;
+    this.reconnectInterval = options.reconnectInterval ?? 1000;
+    this.maxReconnectAttempts = options.maxReconnectAttempts ?? Infinity;
+  }
+
+  /**
+   * Current connection status
+   */
+  get status(): ConnectionStatus {
+    return this._status;
+  }
+
+  /**
+   * Whether the connection is open
+   */
+  get isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  /**
+   * Add event listener
+   */
+  on<K extends keyof ConnectionEvents>(event: K, handler: ConnectionEvents[K]): void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler as EventHandler);
+  }
+
+  /**
+   * Remove event listener
+   */
+  off<K extends keyof ConnectionEvents>(event: K, handler: ConnectionEvents[K]): void {
+    this.handlers.get(event)?.delete(handler as EventHandler);
+  }
+
+  /**
+   * Emit event to handlers
+   */
+  private emit<K extends keyof ConnectionEvents>(
+    event: K,
+    ...args: Parameters<ConnectionEvents[K]>
+  ): void {
+    const handlers = this.handlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(...args);
+      }
+    }
+  }
+
+  /**
+   * Set and emit status change
+   */
+  private setStatus(status: ConnectionStatus): void {
+    if (this._status !== status) {
+      this._status = status;
+      this.emit('status', status);
+    }
+  }
+
+  /**
+   * Connect to WebSocket server
+   */
+  connect(): void {
+    if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {
+      return;
+    }
+
+    this.setStatus('connecting');
+    this.ws = new WebSocket(this.url);
+
+    this.ws.onopen = () => {
+      this.reconnectAttempts = 0;
+      this.setStatus('connected');
+      this.emit('open');
+    };
+
+    this.ws.onclose = (event) => {
+      this.setStatus('disconnected');
+      this.emit('close', { code: event.code, reason: event.reason, wasClean: event.wasClean });
+      this.ws = null;
+
+      if (this.reconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
+        this.scheduleReconnect();
+      }
+    };
+
+    this.ws.onerror = (error) => {
+      this.emit('error', error);
+    };
+
+    this.ws.onmessage = (event) => {
+      try {
+        const message = JSON.parse(event.data as string) as ServerMessage;
+        this.emit('message', message);
+      } catch {
+        console.error('[amux-client] Failed to parse message:', event.data);
+      }
+    };
+  }
+
+  /**
+   * Disconnect from WebSocket server
+   */
+  disconnect(): void {
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    this.reconnectAttempts = this.maxReconnectAttempts; // Prevent reconnect
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.setStatus('disconnected');
+  }
+
+  /**
+   * Send a message to the server
+   */
+  send(message: ClientMessage): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      console.warn('[amux-client] Cannot send message: not connected');
+      return;
+    }
+    this.ws.send(JSON.stringify(message));
+  }
+
+  /**
+   * Schedule a reconnection attempt
+   */
+  private scheduleReconnect(): void {
+    if (this.reconnectTimeout) return;
+
+    this.reconnectAttempts++;
+    const delay = Math.min(
+      this.reconnectInterval * Math.pow(2, this.reconnectAttempts - 1),
+      30000 // Max 30 seconds
+    );
+
+    console.log(`[amux-client] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
+
+    this.reconnectTimeout = setTimeout(() => {
+      this.reconnectTimeout = null;
+      this.connect();
+    }, delay);
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * @bytespell/amux-client
+ *
+ * Client library for consuming amux over WebSocket.
+ *
+ * @example
+ * ```typescript
+ * import { AmuxClient } from '@bytespell/amux-client';
+ *
+ * const client = new AmuxClient({ url: 'ws://localhost:3000/ws' });
+ *
+ * client.on('ready', (data) => {
+ *   console.log('Ready:', data.cwd);
+ * });
+ *
+ * client.on('update', (update) => {
+ *   console.log('Update:', update);
+ * });
+ *
+ * client.connect();
+ * client.prompt('Hello!');
+ * ```
+ *
+ * For React integration, use:
+ * ```typescript
+ * import { AmuxProvider, useAmux } from '@bytespell/amux-client/react';
+ * ```
+ */
+
+// Main client
+export { AmuxClient } from './client.js';
+
+// Supporting classes
+export { Connection } from './connection.js';
+export type { ConnectionOptions, ConnectionEvents } from './connection.js';
+
+export { Accumulator } from './accumulator.js';
+
+// Client types
+export type {
+  AmuxClientOptions,
+  AmuxClientEvents,
+  ConnectionStatus,
+  Message,
+  Turn,
+  ToolCallState,
+  ContentBlock,
+} from './types.js';
+
+// Re-export shared types for convenience
+export type {
+  ServerMessage,
+  ClientMessage,
+  SessionUpdate,
+  AgentInfo,
+  ModelInfo,
+  SessionMetadata,
+  PermissionRequest,
+} from '@bytespell/amux-types';