@ebowwa/mcp-terminal 1.0.8

package/ROLLBACK.md

@@ -0,0 +1,388 @@
+# Terminal MCP Rollback Plan
+
+**Team:** terminal-mcp-fix
+**Date:** 2026-02-05
+**Safety Engineer:** safety agent
+
+---
+
+## Executive Summary
+
+This document provides comprehensive rollback procedures for the terminal MCP recursive loop fix. The fix addresses a critical bug where tool implementation functions had naming conflicts with imported terminal functions, causing infinite recursion.
+
+---
+
+## Bug Analysis
+
+### Root Cause
+
+The terminal MCP stdio server had naming collisions between:
+1. **Imported terminal functions** (e.g., `execSSH`, `listTmuxSessions`, `listFiles`)
+2. **MCP tool wrapper functions** (e.g., `execSSHTool`, `listTmuxSessionsTool`, `listFilesTool`)
+
+When the MCP server tried to call an imported function, it instead called its own wrapper function, causing infinite recursion.
+
+### Affected Files
+
+- `/packages/src/terminal/mcp/stdio.ts` - **CRITICAL**
+- `/packages/src/terminal/mcp/index.ts` - HTTP version (similar pattern)
+
+### Critical Code Locations
+
+#### stdio.ts Line 561 (BUGGY)
+```typescript
+case "list_sessions":
+  return await listSessions();  // BUG: Calls itself instead of listSessionsTool()
+```
+
+#### stdio.ts Line 577 (BUGGY)
+```typescript
+case "list_tmux_sessions":
+  return await listTmuxSessions();  // BUG: Recursive call to imported function
+```
+
+#### stdio.ts Line 579 (BUGGY)
+```typescript
+case "list_files":
+  return await listFiles(args.host, args.path);  // BUG: Recursive call
+```
+
+---
+
+## Changes Being Made
+
+### Diff Summary
+
+```diff
+diff --git a/src/terminal/mcp/stdio.ts b/src/terminal/mcp/stdio.ts
+@@ -120,7 +120,7 @@ interface MCPTool {
+ // Tool Implementations
+ //=============
+
+-async function listSessions(): Promise<string> {
++async function listSessionsTool(): Promise<string> {
+   const sessions = getAllSessionInfo();
+   ...
+
+@@ -145,7 +145,7 @@ async function listSessions(): Promise<string> {
+   return lines.join("\n");
+ }
+
+-async function getSessionInfo(sessionId: string): Promise<string> {
++async function getSessionInfoTool(sessionId: string): Promise<string> {
+   ...
+
+@@ -220,7 +220,7 @@ async function closeSession(sessionId: string): Promise<string> {
+   }
+ }
+
+-async function execSSH(host: string, command: string, options?: Partial<SSHOptions>): Promise<string> {
++async function execSSHTool(host: string, command: string, options?: Partial<SSHOptions>): Promise<string> {
+   ...
+
+@@ -242,7 +242,7 @@ async function testConnection(host: string): Promise<string> {
+   }
+ }
+
+-async function listTmuxSessions(): Promise<string> {
++async function listTmuxSessionsTool(): Promise<string> {
+   ...
+
+@@ -269,7 +269,7 @@ async function listTmuxSessions(): Promise<string> {
+   }
+ }
+
+-async function listFiles(host: string, path: string = "."): Promise<string> {
++async function listFilesTool(host: string, path: string = "."): Promise<string> {
+   ...
+
+@@ -560,29 +560,29 @@ async function handleToolCall(name: string, args: any): Promise<string> {
+     case "list_sessions":
+-      return await listSessions();
++      return await listSessionsTool();
+     case "get_session_info":
+       return await getSessionInfoTool(args.session_id);
+     case "create_session":
+       return await createSessionTool(args.host, args.type, args.command);
+     case "write_command":
+       return await writeCommandTool(args.session_id, args.command);
+     case "resize_session":
+       return await resizeSessionTool(args.session_id, args.rows, args.cols);
+     case "close_session":
+       return await closeSessionTool(args.session_id);
+     case "exec_ssh":
+-      return await execSSH(args.host, args.command, args.options);
++      return await execSSHTool(args.host, args.command, args.options);
+     case "test_connection":
+       return await testConnection(args.host);
+     case "list_tmux_sessions":
+-      return await listTmuxSessions();
++      return await listTmuxSessionsTool();
+     case "list_files":
+-      return await listFiles(args.host, args.path);
++      return await listFilesTool(args.host, args.path);
+     case "upload_file":
+       return await uploadFileTool(args.host, args.local_path, args.remote_path);
+     case "download_file":
+       return await downloadFileTool(args.host, args.remote_path, args.local_path);
+     case "get_active_connections":
+       return await getActiveConnectionsTool();
+     default:
+       throw new Error(`Unknown tool: ${name}`);
+```
+
+---
+
+## Rollback Procedures
+
+### Quick Rollback (Emergency)
+
+If the fix causes unexpected issues:
+
+```bash
+# 1. Navigate to packages directory
+cd /Users/ebowwa/Desktop/codespaces/packages
+
+# 2. Restore original file from git
+git checkout HEAD -- src/terminal/mcp/stdio.ts
+
+# 3. Rebuild if needed
+cd src/terminal/mcp
+bun build stdio.ts --outfile stdio.js
+
+# 4. Restart MCP server
+# Kill existing process and restart
+```
+
+### Complete Rollback to Last Known Good
+
+```bash
+# 1. Check current state
+cd /Users/ebowwa/Desktop/codespaces/packages
+git log --oneline -5
+
+# 2. Reset to last known good commit
+# (Identify commit before the fix)
+git reset --hard <commit-hash>
+
+# 3. Force push if already pushed (USE WITH CAUTION)
+git push --force origin feat/glm-daemon
+```
+
+### Selective Rollback (Partial Fix)
+
+If only certain functions need reverting:
+
+```bash
+# Restore specific function from git
+git checkout HEAD -- src/terminal/mcp/stdio.ts
+
+# Then manually cherry-pick specific fixes
+```
+
+---
+
+## Verification Checklist
+
+Before deploying the fix, verify:
+
+### Code Review
+- [ ] All tool wrapper functions have `Tool` suffix
+- [ ] No function names shadow imported functions
+- [ ] `handleToolCall` uses correct function names
+- [ ] All MCP tools mapped to correct implementations
+
+### Testing
+- [ ] No recursion in `execSSH`
+- [ ] No recursion in `listTmuxSessions`
+- [ ] No recursion in `listFiles`
+- [ ] No recursion in `listSessions`
+- [ ] No recursion in `getSessionInfo`
+- [ ] No recursion in `createSession`
+- [ ] No recursion in `writeCommand`
+- [ ] No recursion in `resizeSession`
+- [ ] No recursion in `closeSession`
+- [ ] No recursion in `uploadFile`
+- [ ] No recursion in `downloadFile`
+- [ ] No recursion in `getActiveConnections`
+
+### MCP Protocol
+- [ ] MCP protocol initialization works
+- [ ] Tools list endpoint returns correct tools
+- [ ] Tools can be called successfully
+- [ ] Error handling works correctly
+
+### Integration Testing
+- [ ] Can connect to VPS via SSH
+- [ ] Can list tmux sessions
+- [ ] Can list files on remote host
+- [ ] Can execute commands via SSH
+- [ ] Discord bot integration works
+
+---
+
+## Monitoring After Deployment
+
+### Key Metrics to Monitor
+
+1. **Process Health**
+   - CPU usage (should be normal, not 100%)
+   - Memory usage (should not grow indefinitely)
+   - Process uptime (should not crash/restart loop)
+
+2. **MCP Server Health**
+   - Response times (should be < 1s for most operations)
+   - Error rates (should be near zero)
+   - Successful tool executions
+
+3. **Discord Bot**
+   - Bot responsiveness
+   - Command execution success rate
+   - No "hang" or timeout issues
+
+### Warning Signs
+
+**IMMEDIATE ROLLBACK IF:**
+- CPU usage spikes to 100% (indicates recursion)
+- Memory grows indefinitely (indicates memory leak)
+- Process crashes within 5 minutes
+- Discord bot becomes unresponsive
+- SSH connections fail or timeout
+
+### Log Monitoring
+
+```bash
+# Monitor for recursion errors
+tail -f /var/log/terminal-mcp.log | grep -i "maximum call stack"
+
+# Monitor for high CPU
+top -p $(pgrep -f "stdio.ts")
+
+# Monitor for process crashes
+watch -n 5 'pgrep -f "stdio.ts" || echo "PROCESS DOWN"'
+```
+
+---
+
+## Recovery Steps
+
+If Rollback is Needed
+
+1. **Immediate Actions**
+   ```bash
+   # Kill the MCP process
+   pkill -f "stdio.ts"
+
+   # Restore from git
+   cd /Users/ebowwa/Desktop/codespaces/packages
+   git checkout HEAD -- src/terminal/mcp/stdio.ts
+
+   # Rebuild
+   bun build src/terminal/mcp/stdio.ts --outfile src/terminal/mcp/stdio.js
+
+   # Restart
+   # Use your normal startup procedure
+   ```
+
+2. **Verify Rollback**
+   ```bash
+   # Test basic functionality
+   curl http://localhost:8913/health
+
+   # Test MCP connection
+   # Your MCP test script
+   ```
+
+3. **Document Incident**
+   - What went wrong
+   - When it was detected
+   - What was rolled back
+   - Lessons learned
+
+---
+
+## Prevention for Future
+
+### Code Review Checklist
+
+Before merging any MCP server changes:
+
+- [ ] No function name shadowing
+- [ ] All tool wrappers have distinct names
+- [ ] Imports are aliased if conflicts exist
+- [ ] Static analysis passes
+- [ ] Manual testing completed
+
+### Development Guidelines
+
+1. **Naming Convention**
+   - MCP tool implementations: `*Tool` suffix
+   - Imported functions: use `as` alias if needed
+   - Never use same name for different purposes
+
+2. **Testing**
+   - Always test with real MCP client
+   - Test each tool individually
+   - Test error conditions
+   - Monitor for recursion (CPU spikes)
+
+3. **Code Review**
+   - Peer review required for MCP changes
+   - Check for naming conflicts
+   - Verify no shadowing
+
+---
+
+## Contact Information
+
+**Team Lead:** team-lead
+**Safety Engineer:** safety agent
+**Fixer:** fixer agent
+**Tester:** tester agent
+
+---
+
+## Appendix: Git Commands Reference
+
+```bash
+# View current changes
+git diff src/terminal/mcp/stdio.ts
+
+# View file history
+git log --oneline -10 -- src/terminal/mcp/stdio.ts
+
+# Show specific commit
+git show <commit-hash>:src/terminal/mcp/stdio.ts
+
+# Create backup before changes
+cp src/terminal/mcp/stdio.ts src/terminal/mcp/stdio.ts.backup
+
+# Restore from backup
+cp src/terminal/mcp/stdio.ts.backup src/terminal/mcp/stdio.ts
+
+# Stash changes temporarily
+git stash push -m "backup before fix" src/terminal/mcp/stdio.ts
+
+# Unstash if needed
+git stash pop
+
+# Create rollback branch
+git checkout -b rollback/terminal-mcp-fix
+
+# Merge rollback to main
+git checkout feat/glm-daemon
+git merge rollback/terminal-mcp-fix
+```
+
+---
+
+## Status
+
+- [ ] Rollback plan created
+- [ ] Team notified
+- [ ] Backup procedures tested
+- [ ] Monitoring in place
+- [ ] Ready for deployment
+
+**Last Updated:** 2026-02-05
+**Document Version:** 1.0