seahorse-bash-client 1.0.0

package/src/pty-manager.ts

@@ -0,0 +1,430 @@
+/**
+ * PTY Manager - Manages multiple PTY sessions with rolling output buffers
+ */
+
+import * as pty from 'node-pty';
+import { v4 as uuidv4 } from 'uuid';
+import { EventEmitter } from 'events';
+import {
+  PTYSession,
+  SessionStatus,
+  OutputLine,
+  BashSpawnInput,
+  BashExecInput,
+  BashWriteInput,
+  BashReadInput,
+  BashListInput,
+  BashKillInput,
+  BashSpawnResponse,
+  BashExecResponse,
+  BashWriteResponse,
+  BashReadResponse,
+  BashListResponse,
+  BashKillResponse,
+} from './types';
+
+// Special key mappings
+const SPECIAL_KEYS: Record<string, string> = {
+  'ctrl+c': '\x03',
+  'ctrl+d': '\x04',
+  'ctrl+z': '\x1a',
+  'enter': '\r',
+  'tab': '\t',
+  'up': '\x1b[A',
+  'down': '\x1b[B',
+  'left': '\x1b[D',
+  'right': '\x1b[C',
+};
+
+interface ManagedSession {
+  session: PTYSession;
+  ptyProcess: pty.IPty;
+  outputBuffer: OutputLine[];
+  notifyOnExit: boolean;
+}
+
+export class PTYManager extends EventEmitter {
+  private sessions: Map<string, ManagedSession> = new Map();
+  private maxOutputLines: number;
+  private defaultShell: string;
+
+  constructor(options: { maxOutputLines?: number; defaultShell?: string } = {}) {
+    super();
+    this.maxOutputLines = options.maxOutputLines || 50000;
+    this.defaultShell = options.defaultShell || process.env.SHELL || '/bin/bash';
+  }
+
+  /**
+   * Spawn a new PTY session
+   */
+  async spawn(input: BashSpawnInput): Promise<BashSpawnResponse> {
+    const sessionId = `pty_${uuidv4().slice(0, 8)}`;
+    const shell = input.shell || this.defaultShell;
+    const cwd = input.cwd || process.cwd();
+
+    // Build the command
+    const shellArgs = input.command
+      ? ['-c', `${input.command}${input.args ? ' ' + input.args.join(' ') : ''}`]
+      : [];
+
+    // Merge environment
+    const env = { ...process.env, ...input.env } as Record<string, string>;
+
+    // Create PTY process
+    const ptyProcess = pty.spawn(shell, shellArgs, {
+      name: 'xterm-256color',
+      cols: input.cols || 120,
+      rows: input.rows || 30,
+      cwd,
+      env,
+    });
+
+    const session: PTYSession = {
+      id: sessionId,
+      name: input.name,
+      pid: ptyProcess.pid,
+      command: input.command || '',
+      args: input.args || [],
+      cwd,
+      status: 'running',
+      createdAt: new Date(),
+      lineCount: 0,
+    };
+
+    const managedSession: ManagedSession = {
+      session,
+      ptyProcess,
+      outputBuffer: [],
+      notifyOnExit: input.notifyOnExit !== false,
+    };
+
+    this.sessions.set(sessionId, managedSession);
+
+    // Handle output
+    ptyProcess.onData((data: string) => {
+      this.appendOutput(sessionId, data);
+    });
+
+    // Handle exit
+    ptyProcess.onExit(({ exitCode, signal }) => {
+      const ms = this.sessions.get(sessionId);
+      if (ms) {
+        ms.session.status = signal ? 'killed' : 'exited';
+        ms.session.exitCode = exitCode;
+        ms.session.signal = signal?.toString();
+
+        if (ms.notifyOnExit) {
+          this.emit('session:exited', {
+            sessionId,
+            exitCode,
+            signal: signal?.toString(),
+            duration: Date.now() - ms.session.createdAt.getTime(),
+            finalLineCount: ms.session.lineCount,
+          });
+        }
+      }
+    });
+
+    return {
+      sessionId,
+      pid: ptyProcess.pid,
+      command: input.command || '',
+      status: 'running',
+      message: 'Session created and command started',
+    };
+  }
+
+  /**
+   * Execute a command synchronously and wait for completion
+   */
+  async exec(input: BashExecInput): Promise<BashExecResponse> {
+    return new Promise((resolve) => {
+      const shell = this.defaultShell;
+      const cwd = input.cwd || process.cwd();
+      const timeout = Math.min(input.timeout || 30000, 600000); // Max 10 minutes
+      const env = { ...process.env, ...input.env } as Record<string, string>;
+
+      let stdout = '';
+      let stderr = '';
+      let timedOut = false;
+      const startTime = Date.now();
+
+      const ptyProcess = pty.spawn(shell, ['-c', input.command], {
+        name: 'xterm-256color',
+        cols: 120,
+        rows: 30,
+        cwd,
+        env,
+      });
+
+      // Timeout handler
+      const timeoutId = setTimeout(() => {
+        timedOut = true;
+        ptyProcess.kill();
+      }, timeout);
+
+      // Collect output
+      ptyProcess.onData((data: string) => {
+        stdout += data;
+      });
+
+      // Handle exit
+      ptyProcess.onExit(({ exitCode }) => {
+        clearTimeout(timeoutId);
+        resolve({
+          exitCode: timedOut ? -1 : exitCode,
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+          duration: Date.now() - startTime,
+          timedOut,
+        });
+      });
+    });
+  }
+
+  /**
+   * Write data to a PTY session
+   */
+  write(input: BashWriteInput): BashWriteResponse {
+    const ms = this.sessions.get(input.sessionId);
+    if (!ms) {
+      throw new Error(`Session not found: ${input.sessionId}`);
+    }
+
+    if (ms.session.status !== 'running') {
+      throw new Error(`Session is not running: ${input.sessionId}`);
+    }
+
+    let data = input.data || '';
+    if (input.specialKey) {
+      data = SPECIAL_KEYS[input.specialKey] || '';
+    }
+
+    if (!data) {
+      throw new Error('No data or specialKey provided');
+    }
+
+    ms.ptyProcess.write(data);
+
+    return {
+      success: true,
+      bytesWritten: data.length,
+      sessionStatus: ms.session.status,
+    };
+  }
+
+  /**
+   * Read output from a PTY session
+   */
+  read(input: BashReadInput): BashReadResponse {
+    const ms = this.sessions.get(input.sessionId);
+    if (!ms) {
+      throw new Error(`Session not found: ${input.sessionId}`);
+    }
+
+    let lines = [...ms.outputBuffer];
+
+    // Filter by pattern
+    if (input.pattern) {
+      const regex = new RegExp(input.pattern, input.ignoreCase ? 'i' : '');
+      lines = lines.filter((line) => regex.test(line.text));
+    }
+
+    // Filter by timestamp
+    if (input.since) {
+      const sinceDate = new Date(input.since);
+      lines = lines.filter((line) => line.timestamp >= sinceDate);
+    }
+
+    const totalLines = lines.length;
+
+    // Apply pagination
+    const offset = input.offset || 0;
+    const limit = Math.min(input.limit || 100, 1000);
+
+    if (input.tail) {
+      // Return last N lines
+      lines = lines.slice(Math.max(0, lines.length - limit));
+    } else {
+      lines = lines.slice(offset, offset + limit);
+    }
+
+    return {
+      sessionId: input.sessionId,
+      lines: lines.map((l, idx) => ({
+        line: input.tail ? totalLines - lines.length + idx + 1 : offset + idx + 1,
+        text: l.text,
+        timestamp: l.timestamp.toISOString(),
+      })),
+      totalLines: ms.session.lineCount,
+      hasMore: offset + limit < totalLines,
+      sessionStatus: ms.session.status,
+    };
+  }
+
+  /**
+   * List all PTY sessions
+   */
+  list(input: BashListInput = {}): BashListResponse {
+    const sessions: BashListResponse['sessions'] = [];
+    let running = 0,
+      exited = 0,
+      killed = 0;
+
+    for (const [, ms] of this.sessions) {
+      // Count by status
+      if (ms.session.status === 'running') running++;
+      else if (ms.session.status === 'exited') exited++;
+      else if (ms.session.status === 'killed') killed++;
+
+      // Filter by status
+      if (input.status && input.status !== 'all' && ms.session.status !== input.status) {
+        continue;
+      }
+
+      const sessionInfo: BashListResponse['sessions'][0] = {
+        sessionId: ms.session.id,
+        name: ms.session.name,
+        pid: ms.session.pid,
+        command: ms.session.command,
+        status: ms.session.status,
+        createdAt: ms.session.createdAt.toISOString(),
+        lineCount: ms.session.lineCount,
+        cwd: ms.session.cwd,
+      };
+
+      // Include recent output if requested
+      if (input.includeOutput) {
+        const outputLines = input.outputLines || 5;
+        sessionInfo.recentOutput = ms.outputBuffer
+          .slice(-outputLines)
+          .map((l) => l.text);
+      }
+
+      sessions.push(sessionInfo);
+    }
+
+    return {
+      sessions,
+      summary: {
+        total: this.sessions.size,
+        running,
+        exited,
+        killed,
+      },
+    };
+  }
+
+  /**
+   * Kill a PTY session
+   */
+  async kill(input: BashKillInput): Promise<BashKillResponse> {
+    const ms = this.sessions.get(input.sessionId);
+    if (!ms) {
+      throw new Error(`Session not found: ${input.sessionId}`);
+    }
+
+    const signal = input.signal || 'SIGTERM';
+    const gracePeriod = input.gracePeriod || 5000;
+    const finalLineCount = ms.session.lineCount;
+
+    if (ms.session.status === 'running') {
+      // Send signal
+      ms.ptyProcess.kill(signal);
+
+      // Wait for graceful termination
+      if (signal === 'SIGTERM') {
+        await new Promise<void>((resolve) => {
+          const checkInterval = setInterval(() => {
+            if (ms.session.status !== 'running') {
+              clearInterval(checkInterval);
+              resolve();
+            }
+          }, 100);
+
+          setTimeout(() => {
+            clearInterval(checkInterval);
+            if (ms.session.status === 'running') {
+              ms.ptyProcess.kill('SIGKILL');
+            }
+            resolve();
+          }, gracePeriod);
+        });
+      }
+
+      ms.session.status = 'killed';
+      ms.session.signal = signal;
+    }
+
+    // Cleanup if requested
+    if (input.cleanup) {
+      this.sessions.delete(input.sessionId);
+    }
+
+    return {
+      sessionId: input.sessionId,
+      exitCode: ms.session.exitCode,
+      signal,
+      cleaned: input.cleanup || false,
+      finalLineCount,
+      message: input.cleanup
+        ? 'Session terminated and cleaned up'
+        : 'Session terminated successfully',
+    };
+  }
+
+  /**
+   * Get a session by ID
+   */
+  getSession(sessionId: string): PTYSession | undefined {
+    return this.sessions.get(sessionId)?.session;
+  }
+
+  /**
+   * Shutdown all sessions
+   */
+  async shutdown(): Promise<void> {
+    const promises: Promise<BashKillResponse>[] = [];
+    for (const [sessionId, ms] of this.sessions) {
+      if (ms.session.status === 'running') {
+        promises.push(this.kill({ sessionId, cleanup: true }));
+      }
+    }
+    await Promise.all(promises);
+    this.sessions.clear();
+  }
+
+  /**
+   * Append output to a session's buffer
+   */
+  private appendOutput(sessionId: string, data: string): void {
+    const ms = this.sessions.get(sessionId);
+    if (!ms) return;
+
+    // Split by newlines and add to buffer
+    const lines = data.split(/\r?\n/);
+    const now = new Date();
+
+    for (const text of lines) {
+      if (text || lines.length === 1) {
+        ms.outputBuffer.push({
+          line: ms.session.lineCount + 1,
+          text,
+          timestamp: now,
+        });
+        ms.session.lineCount++;
+
+        // Trim buffer if too large
+        if (ms.outputBuffer.length > this.maxOutputLines) {
+          ms.outputBuffer.shift();
+        }
+      }
+    }
+
+    // Emit output event
+    this.emit('output', { sessionId, data });
+  }
+}
+
+// Export singleton instance
+export const ptyManager = new PTYManager();

package/src/tools.ts

@@ -0,0 +1,217 @@
+/**
+ * MCP Tool Definitions for Seahorse Bash Client
+ */
+
+import { ToolDefinition } from './types';
+
+export const TOOL_DEFINITIONS: ToolDefinition[] = [
+  {
+    name: 'bash_spawn',
+    description:
+      'Create a new PTY session and run a command in background. Use this for long-running processes like dev servers, watchers, or any command that needs persistent terminal state.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description: "Command to execute (e.g., 'npm run dev', 'python server.py')",
+        },
+        args: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Command arguments (optional)',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Working directory (default: current directory)',
+        },
+        env: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+          description: 'Additional environment variables',
+        },
+        name: {
+          type: 'string',
+          description: 'Session name/identifier (optional, auto-generated if not provided)',
+        },
+        shell: {
+          type: 'string',
+          enum: ['bash', 'sh', 'zsh'],
+          default: 'bash',
+          description: 'Shell to use',
+        },
+        cols: {
+          type: 'integer',
+          default: 120,
+          description: 'Terminal columns',
+        },
+        rows: {
+          type: 'integer',
+          default: 30,
+          description: 'Terminal rows',
+        },
+        notifyOnExit: {
+          type: 'boolean',
+          default: true,
+          description: 'Whether to send notification when process exits',
+        },
+      },
+      required: ['command'],
+    },
+  },
+  {
+    name: 'bash_exec',
+    description:
+      'Execute a command synchronously and wait for completion. Use this for quick commands that should finish within the timeout. Output is returned directly.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description: 'Bash command to execute',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Working directory (optional)',
+        },
+        timeout: {
+          type: 'integer',
+          default: 30000,
+          description: 'Timeout in milliseconds (default 30s, max 600s)',
+        },
+        env: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+          description: 'Additional environment variables',
+        },
+      },
+      required: ['command'],
+    },
+  },
+  {
+    name: 'bash_write',
+    description:
+      'Write data or send special keys to a running PTY session. Use this to send input to interactive programs, including Ctrl+C to interrupt.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: 'Target session ID',
+        },
+        data: {
+          type: 'string',
+          description: 'Text data to send',
+        },
+        specialKey: {
+          type: 'string',
+          enum: ['ctrl+c', 'ctrl+d', 'ctrl+z', 'enter', 'tab', 'up', 'down', 'left', 'right'],
+          description: 'Special key to send (alternative to data)',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'bash_read',
+    description:
+      'Read output from a PTY session buffer. Supports pagination, filtering by regex pattern, and retrieving output since a specific timestamp.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: 'Target session ID',
+        },
+        offset: {
+          type: 'integer',
+          default: 0,
+          description: 'Starting line number (0-indexed)',
+        },
+        limit: {
+          type: 'integer',
+          default: 100,
+          maximum: 1000,
+          description: 'Maximum lines to return',
+        },
+        pattern: {
+          type: 'string',
+          description: 'Regex pattern to filter lines (optional)',
+        },
+        ignoreCase: {
+          type: 'boolean',
+          default: false,
+          description: 'Case-insensitive pattern matching',
+        },
+        since: {
+          type: 'string',
+          format: 'date-time',
+          description: 'Return output after this timestamp (optional)',
+        },
+        tail: {
+          type: 'boolean',
+          default: false,
+          description: 'If true, return last N lines instead of from offset',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'bash_list',
+    description:
+      'List all PTY sessions with their status. Optionally include recent output from each session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          enum: ['all', 'running', 'exited', 'killed'],
+          default: 'all',
+          description: 'Filter by session status',
+        },
+        includeOutput: {
+          type: 'boolean',
+          default: false,
+          description: 'Include recent output lines',
+        },
+        outputLines: {
+          type: 'integer',
+          default: 5,
+          description: 'Number of output lines to include if includeOutput=true',
+        },
+      },
+    },
+  },
+  {
+    name: 'bash_kill',
+    description:
+      'Terminate a PTY session. Sends SIGTERM by default with graceful shutdown, then SIGKILL if needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: 'Session ID to terminate',
+        },
+        signal: {
+          type: 'string',
+          enum: ['SIGTERM', 'SIGKILL', 'SIGINT'],
+          default: 'SIGTERM',
+          description: 'Signal to send',
+        },
+        cleanup: {
+          type: 'boolean',
+          default: false,
+          description: 'If true, remove session from list (deletes output buffer)',
+        },
+        gracePeriod: {
+          type: 'integer',
+          default: 5000,
+          description: 'Time to wait before SIGKILL after SIGTERM (ms)',
+        },
+      },
+      required: ['sessionId'],
+    },
+  },
+];