seahorse-bash-client 1.0.0

package/src/types.ts

@@ -0,0 +1,221 @@
+/**
+ * Seahorse Bash Client Types
+ */
+
+// PTY Session Types
+export type SessionStatus = 'running' | 'exited' | 'killed';
+
+export interface PTYSession {
+  id: string;
+  name?: string;
+  pid: number;
+  command: string;
+  args: string[];
+  cwd: string;
+  status: SessionStatus;
+  createdAt: Date;
+  exitCode?: number;
+  signal?: string;
+  lineCount: number;
+}
+
+export interface OutputLine {
+  line: number;
+  text: string;
+  timestamp: Date;
+}
+
+// Tool Input Types
+export interface BashSpawnInput {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  name?: string;
+  shell?: 'bash' | 'sh' | 'zsh';
+  cols?: number;
+  rows?: number;
+  notifyOnExit?: boolean;
+}
+
+export interface BashExecInput {
+  command: string;
+  cwd?: string;
+  timeout?: number;
+  env?: Record<string, string>;
+}
+
+export interface BashWriteInput {
+  sessionId: string;
+  data?: string;
+  specialKey?: 'ctrl+c' | 'ctrl+d' | 'ctrl+z' | 'enter' | 'tab' | 'up' | 'down' | 'left' | 'right';
+}
+
+export interface BashReadInput {
+  sessionId: string;
+  offset?: number;
+  limit?: number;
+  pattern?: string;
+  ignoreCase?: boolean;
+  since?: string;
+  tail?: boolean;
+}
+
+export interface BashListInput {
+  status?: 'all' | 'running' | 'exited' | 'killed';
+  includeOutput?: boolean;
+  outputLines?: number;
+}
+
+export interface BashKillInput {
+  sessionId: string;
+  signal?: 'SIGTERM' | 'SIGKILL' | 'SIGINT';
+  cleanup?: boolean;
+  gracePeriod?: number;
+}
+
+// Tool Response Types
+export interface BashSpawnResponse {
+  sessionId: string;
+  pid: number;
+  command: string;
+  status: SessionStatus;
+  message: string;
+}
+
+export interface BashExecResponse {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  duration: number;
+  timedOut: boolean;
+}
+
+export interface BashWriteResponse {
+  success: boolean;
+  bytesWritten: number;
+  sessionStatus: SessionStatus;
+}
+
+export interface BashReadResponse {
+  sessionId: string;
+  lines: Array<{ line: number; text: string; timestamp: string }>;
+  totalLines: number;
+  hasMore: boolean;
+  sessionStatus: SessionStatus;
+}
+
+export interface BashListResponse {
+  sessions: Array<{
+    sessionId: string;
+    name?: string;
+    pid: number;
+    command: string;
+    status: SessionStatus;
+    createdAt: string;
+    lineCount: number;
+    cwd: string;
+    recentOutput?: string[];
+  }>;
+  summary: {
+    total: number;
+    running: number;
+    exited: number;
+    killed: number;
+  };
+}
+
+export interface BashKillResponse {
+  sessionId: string;
+  exitCode?: number;
+  signal: string;
+  cleaned: boolean;
+  finalLineCount: number;
+  message: string;
+}
+
+// WebSocket Protocol Types
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: object;
+}
+
+export interface RegisterMessage {
+  type: 'registration';
+  tools: ToolDefinition[];
+  metadata: {
+    version: string;
+    hostname: string;
+    platform: string;
+    shell: string;
+  };
+}
+
+export interface ToolCallMessage {
+  type: 'tool_call';
+  request_id: string;
+  method: string;
+  params: {
+    name: string;
+    arguments: Record<string, unknown>;
+  };
+}
+
+export interface ToolResponseMessage {
+  type: 'tool_response';
+  request_id: string;
+  content: Array<{ type: 'text'; text: string }>;
+  isError: boolean;
+  error?: string;
+}
+
+export interface NotificationMessage {
+  type: 'notification';
+  method: string;
+  params: Record<string, unknown>;
+}
+
+export interface HeartbeatMessage {
+  type: 'heartbeat';
+}
+
+export interface HeartbeatAckMessage {
+  type: 'heartbeat_ack';
+}
+
+export interface RegistrationAckMessage {
+  type: 'registration_ack';
+  server_name: string;
+  registered_tools: number;
+  tool_names: string[];
+}
+
+export interface ErrorMessage {
+  type: 'error';
+  error: string;
+}
+
+export type WebSocketMessage =
+  | RegisterMessage
+  | ToolCallMessage
+  | ToolResponseMessage
+  | NotificationMessage
+  | HeartbeatMessage
+  | HeartbeatAckMessage
+  | RegistrationAckMessage
+  | ErrorMessage;
+
+// Configuration
+export interface ClientConfig {
+  serverUrl: string;
+  serverName: string;
+  reconnectInterval?: number;
+  heartbeatInterval?: number;
+  maxOutputLines?: number;
+  defaultShell?: string;
+  allowedCommands?: string[];
+  blockedCommands?: string[];
+  allowedCwdPaths?: string[];
+  insecure?: boolean; // Skip SSL certificate verification
+}

package/src/websocket-client.ts

@@ -0,0 +1,374 @@
+/**
+ * WebSocket Client - Connects to Seahorse Agent and handles MCP tool calls
+ */
+
+import WebSocket from 'ws';
+import { EventEmitter } from 'events';
+import os from 'os';
+import https from 'https';
+import http from 'http';
+import {
+  ClientConfig,
+  RegisterMessage,
+  ToolCallMessage,
+  ToolResponseMessage,
+  NotificationMessage,
+  WebSocketMessage,
+} from './types';
+import { PTYManager } from './pty-manager';
+import { TOOL_DEFINITIONS } from './tools';
+
+export class WebSocketClient extends EventEmitter {
+  private ws: WebSocket | null = null;
+  private config: ClientConfig;
+  private ptyManager: PTYManager;
+  private reconnectTimer: NodeJS.Timeout | null = null;
+  private heartbeatTimer: NodeJS.Timeout | null = null;
+  private isConnected = false;
+  private isShuttingDown = false;
+
+  constructor(config: ClientConfig) {
+    super();
+    this.config = {
+      reconnectInterval: 5000,
+      heartbeatInterval: 30000,
+      maxOutputLines: 50000,
+      ...config,
+    };
+    this.ptyManager = new PTYManager({
+      maxOutputLines: this.config.maxOutputLines,
+      defaultShell: this.config.defaultShell,
+    });
+
+    // Forward session exit events
+    this.ptyManager.on('session:exited', (data) => {
+      this.sendNotification('session/exited', data);
+    });
+  }
+
+  /**
+   * Connect to the Seahorse Agent
+   */
+  async connect(): Promise<void> {
+    if (this.isShuttingDown) return;
+
+    return new Promise((resolve, reject) => {
+      try {
+        const url = new URL(this.config.serverUrl);
+        const isSecure = url.protocol === 'wss:';
+
+        // Create agent that forces HTTP/1.1 (no ALPN for HTTP/2)
+        const agent = isSecure
+          ? new https.Agent({
+              rejectUnauthorized: !this.config.insecure,
+              // Force HTTP/1.1 by not advertising HTTP/2
+              ALPNProtocols: ['http/1.1'],
+            })
+          : new http.Agent();
+
+        const wsOptions: WebSocket.ClientOptions = {
+          agent,
+          perMessageDeflate: false,
+        };
+
+        this.ws = new WebSocket(this.config.serverUrl, wsOptions);
+
+        this.ws.on('open', () => {
+          this.isConnected = true;
+          this.emit('connected');
+          this.register();
+          this.startHeartbeat();
+          resolve();
+        });
+
+        this.ws.on('message', (data: Buffer) => {
+          this.handleMessage(data);
+        });
+
+        this.ws.on('close', (code: number, reason: Buffer) => {
+          this.isConnected = false;
+          this.stopHeartbeat();
+          this.emit('disconnected', { code, reason: reason.toString() });
+
+          if (!this.isShuttingDown) {
+            this.scheduleReconnect();
+          }
+        });
+
+        this.ws.on('error', (error: Error) => {
+          this.emit('error', error);
+          if (!this.isConnected) {
+            reject(error);
+          }
+        });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Disconnect from the server
+   */
+  async disconnect(): Promise<void> {
+    this.isShuttingDown = true;
+
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    this.stopHeartbeat();
+
+    // Shutdown all PTY sessions
+    await this.ptyManager.shutdown();
+
+    if (this.ws) {
+      this.ws.close(1000, 'Client shutdown');
+      this.ws = null;
+    }
+  }
+
+  /**
+   * Register tools with the agent
+   */
+  private register(): void {
+    // Note: Server expects "registration" type, not "register"
+    const message = {
+      type: 'registration',
+      tools: TOOL_DEFINITIONS,
+      metadata: {
+        version: '1.0.0',
+        hostname: os.hostname(),
+        platform: process.platform,
+        shell: this.config.defaultShell || process.env.SHELL || '/bin/bash',
+      },
+    };
+
+    this.send(message as any);
+  }
+
+  /**
+   * Handle incoming WebSocket messages
+   */
+  private handleMessage(data: Buffer): void {
+    try {
+      const message: WebSocketMessage = JSON.parse(data.toString());
+
+      switch (message.type) {
+        case 'tool_call':
+          this.handleToolCall(message as ToolCallMessage);
+          break;
+        case 'heartbeat':
+        case 'heartbeat_ack':
+          // Respond to heartbeat, ignore ack
+          if (message.type === 'heartbeat') {
+            this.send({ type: 'heartbeat' });
+          }
+          break;
+        case 'registration_ack':
+          // Server acknowledged registration
+          const ackData = message as { type: string; server_name: string; registered_tools: number; tool_names: string[] };
+          this.emit('registered', {
+            serverName: ackData.server_name,
+            tools: TOOL_DEFINITIONS,
+            registeredCount: ackData.registered_tools,
+          });
+          break;
+        case 'error':
+          const errorData = message as { type: string; error: string };
+          this.emit('error', new Error(`Server error: ${errorData.error}`));
+          break;
+        default:
+          this.emit('message', message);
+      }
+    } catch (error) {
+      this.emit('error', new Error(`Failed to parse message: ${error}`));
+    }
+  }
+
+  /**
+   * Handle a tool call from the agent
+   */
+  private async handleToolCall(message: ToolCallMessage): Promise<void> {
+    const { request_id, params } = message;
+    const { name, arguments: args } = params;
+
+    this.emit('tool:call', { name, args, requestId: request_id });
+
+    try {
+      const result = await this.executeTool(name, args);
+      this.sendToolResponse(request_id, result, false);
+      this.emit('tool:success', { name, requestId: request_id });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.sendToolResponse(request_id, { error: errorMessage }, true, errorMessage);
+      this.emit('tool:error', { name, requestId: request_id, error: errorMessage });
+    }
+  }
+
+  /**
+   * Execute a tool
+   */
+  private async executeTool(
+    name: string,
+    args: Record<string, unknown>
+  ): Promise<object> {
+    // Validate allowed commands if configured
+    if (this.config.allowedCommands && name.startsWith('bash_')) {
+      const command = (args.command as string) || '';
+      const isAllowed = this.config.allowedCommands.some(
+        (allowed) => command.startsWith(allowed) || command === allowed
+      );
+      if (!isAllowed) {
+        throw new Error(`Command not in allowed list: ${command}`);
+      }
+    }
+
+    // Validate blocked commands if configured
+    if (this.config.blockedCommands && name.startsWith('bash_')) {
+      const command = (args.command as string) || '';
+      const isBlocked = this.config.blockedCommands.some(
+        (blocked) => command.includes(blocked) || command.startsWith(blocked)
+      );
+      if (isBlocked) {
+        throw new Error(`Command is blocked: ${command}`);
+      }
+    }
+
+    // Validate cwd if restrictions are configured
+    if (this.config.allowedCwdPaths && args.cwd) {
+      const cwd = args.cwd as string;
+      const isAllowed = this.config.allowedCwdPaths.some((allowed) => cwd.startsWith(allowed));
+      if (!isAllowed) {
+        throw new Error(`Working directory not allowed: ${cwd}`);
+      }
+    }
+
+    switch (name) {
+      case 'bash_spawn':
+        return this.ptyManager.spawn(args as any);
+
+      case 'bash_exec':
+        return this.ptyManager.exec(args as any);
+
+      case 'bash_write':
+        return this.ptyManager.write(args as any);
+
+      case 'bash_read':
+        return this.ptyManager.read(args as any);
+
+      case 'bash_list':
+        return this.ptyManager.list(args as any);
+
+      case 'bash_kill':
+        return this.ptyManager.kill(args as any);
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  }
+
+  /**
+   * Send a tool response
+   */
+  private sendToolResponse(
+    requestId: string,
+    result: object,
+    isError: boolean,
+    errorMessage?: string
+  ): void {
+    const response: ToolResponseMessage = {
+      type: 'tool_response',
+      request_id: requestId,
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+      isError,
+      ...(errorMessage && { error: errorMessage }),
+    };
+
+    this.send(response);
+  }
+
+  /**
+   * Send a notification to the agent
+   */
+  private sendNotification(method: string, params: Record<string, unknown>): void {
+    if (!this.isConnected) return;
+
+    const notification: NotificationMessage = {
+      type: 'notification',
+      method,
+      params,
+    };
+
+    this.send(notification);
+    this.emit('notification:sent', { method, params });
+  }
+
+  /**
+   * Send a message through the WebSocket
+   */
+  private send(message: WebSocketMessage): void {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(message));
+    }
+  }
+
+  /**
+   * Schedule a reconnection attempt
+   */
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) return;
+
+    this.emit('reconnecting', { interval: this.config.reconnectInterval });
+
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      try {
+        await this.connect();
+      } catch (error) {
+        // Will retry via close handler
+      }
+    }, this.config.reconnectInterval);
+  }
+
+  /**
+   * Start heartbeat timer
+   */
+  private startHeartbeat(): void {
+    this.heartbeatTimer = setInterval(() => {
+      if (this.isConnected) {
+        this.send({ type: 'heartbeat' });
+      }
+    }, this.config.heartbeatInterval);
+  }
+
+  /**
+   * Stop heartbeat timer
+   */
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  /**
+   * Get connection status
+   */
+  get connected(): boolean {
+    return this.isConnected;
+  }
+
+  /**
+   * Get PTY manager for direct access
+   */
+  get pty(): PTYManager {
+    return this.ptyManager;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    testTimeout: 30000,
+    hookTimeout: 10000,
+    include: ['src/**/*.test.ts'],
+  },
+});