zerg-ztc 0.1.7 → 0.1.11

package/src/agent/tools/screenshot.ts

@@ -0,0 +1,821 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { readFile, unlink } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { Tool } from './types.js';
+import { ToolCapability } from '../runtime/capabilities.js';
+
+const execAsync = promisify(exec);
+
+// --- Types ---
+
+export interface ScreenshotResult {
+  type: 'image';
+  mediaType: string;
+  data: string;  // base64
+  description: string;
+}
+
+export interface WindowInfo {
+  windowId: number;
+  pid: number;
+  appName: string;
+  title: string;
+  bounds?: { x: number; y: number; width: number; height: number };
+}
+
+// --- Helper Functions ---
+
+async function getWindowListMac(): Promise<WindowInfo[]> {
+  // Use Swift to get window list via CGWindowListCopyWindowInfo
+  // Swift provides reliable access to CoreGraphics APIs
+  const swiftScript = `
+import Foundation
+import CoreGraphics
+
+if let windowList = CGWindowListCopyWindowInfo([.optionOnScreenOnly, .excludeDesktopElements], kCGNullWindowID) as? [[String: Any]] {
+    var results: [[String: Any]] = []
+
+    for window in windowList {
+        guard let windowId = window[kCGWindowNumber as String] as? Int,
+              let pid = window[kCGWindowOwnerPID as String] as? Int,
+              let appName = window[kCGWindowOwnerName as String] as? String,
+              windowId > 0 else { continue }
+
+        let title = window[kCGWindowName as String] as? String ?? ""
+        let layer = window[kCGWindowLayer as String] as? Int ?? 0
+
+        if layer < 0 { continue }
+
+        if let bounds = window[kCGWindowBounds as String] as? [String: Any],
+           let width = bounds["Width"] as? Double,
+           let height = bounds["Height"] as? Double {
+            // Skip tiny windows (menu bar items, etc.) but keep reasonably sized ones
+            if width < 50 || height < 50 { continue }
+
+            results.append([
+                "windowId": windowId,
+                "pid": pid,
+                "appName": appName,
+                "title": title,
+                "bounds": ["x": 0, "y": 0, "width": Int(width), "height": Int(height)]
+            ])
+        }
+    }
+
+    if let data = try? JSONSerialization.data(withJSONObject: results, options: []),
+       let json = String(data: data, encoding: .utf8) {
+        print(json)
+    }
+}
+`;
+
+  try {
+    const { writeFile, unlink: unlinkFile } = await import('fs/promises');
+    const scriptPath = join(tmpdir(), `ztc-windowlist-${Date.now()}.swift`);
+    await writeFile(scriptPath, swiftScript);
+
+    try {
+      const { stdout } = await execAsync(`swift "${scriptPath}"`, {
+        timeout: 15000
+      });
+      await unlinkFile(scriptPath).catch(() => {});
+
+      const parsed = JSON.parse(stdout.trim());
+      if (Array.isArray(parsed) && parsed.length > 0) {
+        return parsed;
+      }
+    } catch {
+      await unlinkFile(scriptPath).catch(() => {});
+    }
+
+    // Fallback to simpler AppleScript approach
+    return getWindowListMacFallback();
+  } catch {
+    return getWindowListMacFallback();
+  }
+}
+
+async function getWindowListMacFallback(): Promise<WindowInfo[]> {
+  // Simpler fallback using AppleScript
+  const script = `
+    tell application "System Events"
+      set windowList to {}
+      repeat with proc in (every process whose background only is false)
+        try
+          set procName to name of proc
+          set procPID to unix id of proc
+          repeat with win in (every window of proc)
+            try
+              set winName to name of win
+              set end of windowList to procName & "|||" & procPID & "|||" & winName
+            end try
+          end repeat
+        end try
+      end repeat
+      return windowList
+    end tell
+  `;
+
+  try {
+    const { stdout } = await execAsync(`osascript -e '${script.replace(/'/g, "'\"'\"'")}'`, {
+      timeout: 10000
+    });
+
+    const lines = stdout.trim().split(', ');
+    return lines.map((line, idx) => {
+      const [appName, pid, title] = line.split('|||');
+      return {
+        windowId: idx, // AppleScript doesn't give us real window IDs
+        pid: parseInt(pid) || 0,
+        appName: appName || 'Unknown',
+        title: title || ''
+      };
+    }).filter(w => w.appName && w.appName !== 'Unknown');
+  } catch {
+    return [];
+  }
+}
+
+async function getWindowListLinux(): Promise<WindowInfo[]> {
+  try {
+    // Try wmctrl first
+    const { stdout } = await execAsync('wmctrl -l -p', { timeout: 5000 });
+    const lines = stdout.trim().split('\n');
+
+    return lines.map(line => {
+      const parts = line.split(/\s+/);
+      const windowId = parseInt(parts[0], 16);
+      const pid = parseInt(parts[2]) || 0;
+      const title = parts.slice(4).join(' ');
+
+      return {
+        windowId,
+        pid,
+        appName: title.split(' - ').pop() || title,
+        title
+      };
+    });
+  } catch {
+    // Try xdotool as fallback
+    try {
+      const { stdout } = await execAsync('xdotool search --onlyvisible --name ""', { timeout: 5000 });
+      const windowIds = stdout.trim().split('\n').filter(Boolean);
+
+      const windows: WindowInfo[] = [];
+      for (const id of windowIds.slice(0, 20)) { // Limit to 20 windows
+        try {
+          const { stdout: name } = await execAsync(`xdotool getwindowname ${id}`, { timeout: 1000 });
+          const { stdout: pid } = await execAsync(`xdotool getwindowpid ${id}`, { timeout: 1000 });
+          windows.push({
+            windowId: parseInt(id),
+            pid: parseInt(pid.trim()) || 0,
+            appName: name.trim().split(' - ').pop() || name.trim(),
+            title: name.trim()
+          });
+        } catch {
+          continue;
+        }
+      }
+      return windows;
+    } catch {
+      return [];
+    }
+  }
+}
+
+async function getWindowListWindows(): Promise<WindowInfo[]> {
+  const psScript = `
+    Add-Type @"
+    using System;
+    using System.Runtime.InteropServices;
+    using System.Collections.Generic;
+    using System.Text;
+    using System.Diagnostics;
+
+    public class WindowHelper {
+        [DllImport("user32.dll")]
+        public static extern bool EnumWindows(EnumWindowsProc lpEnumFunc, IntPtr lParam);
+
+        [DllImport("user32.dll")]
+        public static extern int GetWindowText(IntPtr hWnd, StringBuilder lpString, int nMaxCount);
+
+        [DllImport("user32.dll")]
+        public static extern bool IsWindowVisible(IntPtr hWnd);
+
+        [DllImport("user32.dll")]
+        public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);
+
+        public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);
+
+        public static List<string> GetWindows() {
+            var windows = new List<string>();
+            EnumWindows((hWnd, lParam) => {
+                if (IsWindowVisible(hWnd)) {
+                    var sb = new StringBuilder(256);
+                    GetWindowText(hWnd, sb, 256);
+                    var title = sb.ToString();
+                    if (!string.IsNullOrWhiteSpace(title)) {
+                        uint pid;
+                        GetWindowThreadProcessId(hWnd, out pid);
+                        try {
+                            var proc = Process.GetProcessById((int)pid);
+                            windows.Add(hWnd.ToInt64() + "|||" + pid + "|||" + proc.ProcessName + "|||" + title);
+                        } catch {}
+                    }
+                }
+                return true;
+            }, IntPtr.Zero);
+            return windows;
+        }
+    }
+"@
+    [WindowHelper]::GetWindows() | ForEach-Object { $_ }
+  `;
+
+  try {
+    const { stdout } = await execAsync(`powershell -Command "${psScript.replace(/"/g, '\\"').replace(/\n/g, ' ')}"`, {
+      timeout: 15000
+    });
+
+    return stdout.trim().split('\n').filter(Boolean).map(line => {
+      const [windowId, pid, appName, title] = line.split('|||');
+      return {
+        windowId: parseInt(windowId) || 0,
+        pid: parseInt(pid) || 0,
+        appName: appName || 'Unknown',
+        title: title || ''
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+
+async function findWindowByPid(pid: number): Promise<WindowInfo | null> {
+  const platform = process.platform;
+  let windows: WindowInfo[] = [];
+
+  if (platform === 'darwin') {
+    windows = await getWindowListMac();
+  } else if (platform === 'linux') {
+    windows = await getWindowListLinux();
+  } else if (platform === 'win32') {
+    windows = await getWindowListWindows();
+  }
+
+  return windows.find(w => w.pid === pid) || null;
+}
+
+async function findWindowByApp(appName: string): Promise<WindowInfo | null> {
+  const platform = process.platform;
+  let windows: WindowInfo[] = [];
+
+  if (platform === 'darwin') {
+    windows = await getWindowListMac();
+  } else if (platform === 'linux') {
+    windows = await getWindowListLinux();
+  } else if (platform === 'win32') {
+    windows = await getWindowListWindows();
+  }
+
+  const lower = appName.toLowerCase();
+  return windows.find(w =>
+    w.appName.toLowerCase().includes(lower) ||
+    w.title.toLowerCase().includes(lower)
+  ) || null;
+}
+
+// Check if we have screen recording permission on macOS
+async function checkScreenRecordingPermission(): Promise<boolean> {
+  if (process.platform !== 'darwin') return true;
+
+  try {
+    // Try to capture a tiny region - if it fails with permission error, we know
+    const testPath = join(tmpdir(), `ztc-perm-test-${Date.now()}.png`);
+    await execAsync(`screencapture -x -R0,0,1,1 "${testPath}"`, { timeout: 5000 });
+    await unlink(testPath).catch(() => {});
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Compress image if it exceeds size limit (4MB to leave room for base64 overhead)
+const MAX_IMAGE_SIZE = 4 * 1024 * 1024; // 4MB
+
+async function compressImageIfNeeded(imagePath: string): Promise<Buffer> {
+  const imageBuffer = await readFile(imagePath);
+
+  // If under the limit, return as-is
+  if (imageBuffer.length <= MAX_IMAGE_SIZE) {
+    return imageBuffer;
+  }
+
+  const platform = process.platform;
+
+  // Try to compress using platform tools
+  if (platform === 'darwin') {
+    // Use sips to resize the image
+    const compressedPath = imagePath.replace('.png', '-compressed.jpg');
+
+    // Calculate target max dimension based on size ratio
+    // Rough estimate: 4K screen is ~8M pixels at 24-bit = ~24MB uncompressed PNG
+    // We want to get to ~4MB, so roughly 1/6 the pixels = ~40% linear scale
+    const ratio = Math.sqrt(MAX_IMAGE_SIZE / imageBuffer.length) * 0.7;
+    const maxDimension = Math.max(800, Math.floor(2000 * ratio)); // At least 800px, scale from 2000px base
+
+    try {
+      // Convert to JPEG and resize - sips uses pixel values, not percentages
+      await execAsync(
+        `sips -s format jpeg -s formatOptions 70 -Z ${maxDimension} "${imagePath}" --out "${compressedPath}"`,
+        { timeout: 30000 }
+      );
+
+      const compressedBuffer = await readFile(compressedPath);
+      await unlink(compressedPath).catch(() => {});
+
+      if (compressedBuffer.length <= MAX_IMAGE_SIZE) {
+        return compressedBuffer;
+      }
+
+      // If still too large, try more aggressive compression
+      await execAsync(
+        `sips -s format jpeg -s formatOptions 50 -Z 1200 "${imagePath}" --out "${compressedPath}"`,
+        { timeout: 30000 }
+      );
+
+      const moreCompressedBuffer = await readFile(compressedPath);
+      await unlink(compressedPath).catch(() => {});
+
+      if (moreCompressedBuffer.length <= MAX_IMAGE_SIZE) {
+        return moreCompressedBuffer;
+      }
+
+      // Last resort: very aggressive compression
+      await execAsync(
+        `sips -s format jpeg -s formatOptions 40 -Z 800 "${imagePath}" --out "${compressedPath}"`,
+        { timeout: 30000 }
+      );
+
+      const finalBuffer = await readFile(compressedPath);
+      await unlink(compressedPath).catch(() => {});
+      return finalBuffer;
+    } catch {
+      // If compression fails, return original (API will error if too large)
+      return imageBuffer;
+    }
+  } else if (platform === 'linux') {
+    // Try using ImageMagick convert
+    const compressedPath = imagePath.replace('.png', '-compressed.jpg');
+    const ratio = Math.sqrt(MAX_IMAGE_SIZE / imageBuffer.length) * 0.8;
+    const scalePercent = Math.max(20, Math.min(90, Math.floor(ratio * 100)));
+
+    try {
+      await execAsync(
+        `convert "${imagePath}" -resize ${scalePercent}% -quality 70 "${compressedPath}"`,
+        { timeout: 30000 }
+      );
+
+      const compressedBuffer = await readFile(compressedPath);
+      await unlink(compressedPath).catch(() => {});
+      return compressedBuffer;
+    } catch {
+      return imageBuffer;
+    }
+  }
+
+  // No compression available, return original
+  return imageBuffer;
+}
+
+async function captureWindow(windowId: number, tempPath: string): Promise<void> {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    // macOS: screencapture -l <windowID>
+    try {
+      await execAsync(`screencapture -x -l ${windowId} "${tempPath}"`, { timeout: 30000 });
+    } catch (err) {
+      const message = (err as Error).message;
+      if (message.includes('could not create image from window')) {
+        // Check if it's a permission issue
+        const hasPermission = await checkScreenRecordingPermission();
+        if (!hasPermission) {
+          throw new Error(
+            'Screen Recording permission required. Go to System Settings > Privacy & Security > Screen Recording and enable your terminal app (iTerm, Terminal, etc.)'
+          );
+        }
+        throw new Error(`Window capture failed for window ID ${windowId}. The window may be minimized or on a different Space.`);
+      }
+      throw err;
+    }
+  } else if (platform === 'linux') {
+    // Linux: try import with window ID
+    try {
+      await execAsync(`import -window ${windowId} "${tempPath}"`, { timeout: 30000 });
+    } catch {
+      // Fallback to xwd + convert
+      await execAsync(`xwd -id ${windowId} | convert xwd:- "${tempPath}"`, { timeout: 30000 });
+    }
+  } else if (platform === 'win32') {
+    // Windows: use .NET to capture specific window
+    const psScript = `
+      Add-Type -AssemblyName System.Windows.Forms
+      Add-Type -AssemblyName System.Drawing
+      Add-Type @"
+        using System;
+        using System.Runtime.InteropServices;
+        using System.Drawing;
+
+        public class WindowCapture {
+            [DllImport("user32.dll")]
+            public static extern bool GetWindowRect(IntPtr hWnd, out RECT lpRect);
+
+            [StructLayout(LayoutKind.Sequential)]
+            public struct RECT {
+                public int Left, Top, Right, Bottom;
+            }
+
+            public static Rectangle GetBounds(IntPtr hWnd) {
+                RECT rect;
+                GetWindowRect(hWnd, out rect);
+                return new Rectangle(rect.Left, rect.Top, rect.Right - rect.Left, rect.Bottom - rect.Top);
+            }
+        }
+"@
+      $hwnd = [IntPtr]${windowId}
+      $bounds = [WindowCapture]::GetBounds($hwnd)
+      $bitmap = New-Object System.Drawing.Bitmap($bounds.Width, $bounds.Height)
+      $graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+      $graphics.CopyFromScreen($bounds.Location, [System.Drawing.Point]::Empty, $bounds.Size)
+      $bitmap.Save('${tempPath.replace(/\\/g, '\\\\')}')
+      $graphics.Dispose()
+      $bitmap.Dispose()
+    `;
+    await execAsync(`powershell -Command "${psScript.replace(/"/g, '\\"').replace(/\n/g, '; ')}"`, { timeout: 30000 });
+  } else {
+    throw new Error(`Window capture not supported on platform: ${platform}`);
+  }
+}
+
+async function captureFullScreen(tempPath: string, display?: number, delay?: number): Promise<void> {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    let cmd = 'screencapture -x';
+    if (delay && delay > 0) {
+      cmd += ` -T${delay}`;
+    }
+    if (display !== undefined) {
+      cmd += ` -D${display}`;
+    }
+    cmd += ` "${tempPath}"`;
+    await execAsync(cmd, { timeout: 30000 + (delay || 0) * 1000 });
+  } else if (platform === 'linux') {
+    if (delay && delay > 0) {
+      await new Promise(resolve => setTimeout(resolve, delay * 1000));
+    }
+
+    const commands = [
+      `gnome-screenshot -f "${tempPath}"`,
+      `scrot "${tempPath}"`,
+      `import -window root "${tempPath}"`
+    ];
+
+    let success = false;
+    for (const cmd of commands) {
+      try {
+        await execAsync(cmd, { timeout: 30000 });
+        success = true;
+        break;
+      } catch {
+        continue;
+      }
+    }
+
+    if (!success) {
+      throw new Error('No screenshot tool available. Install gnome-screenshot, scrot, or ImageMagick.');
+    }
+  } else if (platform === 'win32') {
+    if (delay && delay > 0) {
+      await new Promise(resolve => setTimeout(resolve, delay * 1000));
+    }
+
+    const psScript = `
+      Add-Type -AssemblyName System.Windows.Forms
+      $screen = [System.Windows.Forms.Screen]::PrimaryScreen
+      $bitmap = New-Object System.Drawing.Bitmap($screen.Bounds.Width, $screen.Bounds.Height)
+      $graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+      $graphics.CopyFromScreen($screen.Bounds.Location, [System.Drawing.Point]::Empty, $screen.Bounds.Size)
+      $bitmap.Save('${tempPath.replace(/\\/g, '\\\\')}')
+      $graphics.Dispose()
+      $bitmap.Dispose()
+    `;
+    await execAsync(`powershell -Command "${psScript.replace(/\n/g, '; ')}"`, { timeout: 30000 });
+  } else {
+    throw new Error(`Screenshot not supported on platform: ${platform}`);
+  }
+}
+
+// --- Screenshot Tool ---
+
+export const screenshotTool: Tool = {
+  capabilities: [ToolCapability.SCREEN_CAPTURE],
+  definition: {
+    name: 'screenshot',
+    description: 'Capture a screenshot. Can capture the full screen, a specific window by ID, by PID, or by app name.',
+    parameters: {
+      type: 'object',
+      properties: {
+        windowId: {
+          type: 'number',
+          description: 'Specific window ID to capture (from list_windows)'
+        },
+        pid: {
+          type: 'number',
+          description: 'Process ID - captures the first window belonging to this process'
+        },
+        app: {
+          type: 'string',
+          description: 'App name to capture (partial match, e.g., "Safari", "Chrome", "Terminal")'
+        },
+        display: {
+          type: 'number',
+          description: 'Display number for full-screen capture (default: main display)'
+        },
+        delay: {
+          type: 'number',
+          description: 'Delay in seconds before capture (default: 0)'
+        }
+      },
+      required: []
+    }
+  },
+  execute: async (args) => {
+    const windowId = args.windowId !== undefined ? Number(args.windowId) : undefined;
+    const pid = args.pid !== undefined ? Number(args.pid) : undefined;
+    const app = args.app !== undefined ? String(args.app) : undefined;
+    const display = args.display !== undefined ? Number(args.display) : undefined;
+    const delay = args.delay !== undefined ? Number(args.delay) : 0;
+
+    const timestamp = Date.now();
+    const tempPath = join(tmpdir(), `ztc-screenshot-${timestamp}.png`);
+
+    try {
+      let description = 'Screenshot captured';
+
+      if (windowId !== undefined) {
+        // Capture specific window by ID
+        await captureWindow(windowId, tempPath);
+        description = `Window ${windowId} captured`;
+      } else if (pid !== undefined) {
+        // Find window by PID and capture it
+        const window = await findWindowByPid(pid);
+        if (!window) {
+          throw new Error(`No visible window found for PID ${pid}`);
+        }
+        await captureWindow(window.windowId, tempPath);
+        description = `Window captured: ${window.appName} - ${window.title} (PID: ${pid})`;
+      } else if (app !== undefined) {
+        // Find window by app name and capture it
+        const window = await findWindowByApp(app);
+        if (!window) {
+          throw new Error(`No visible window found for app "${app}"`);
+        }
+        await captureWindow(window.windowId, tempPath);
+        description = `Window captured: ${window.appName} - ${window.title}`;
+      } else {
+        // Full screen capture
+        if (delay > 0) {
+          await new Promise(resolve => setTimeout(resolve, delay * 1000));
+        }
+        await captureFullScreen(tempPath, display);
+        description = 'Full screen captured';
+      }
+
+      // Read and compress the image if needed
+      const originalSize = (await readFile(tempPath)).length;
+      const imageBuffer = await compressImageIfNeeded(tempPath);
+      const base64Data = imageBuffer.toString('base64');
+      const wasCompressed = imageBuffer.length < originalSize;
+
+      // Clean up temp file
+      try {
+        await unlink(tempPath);
+      } catch {
+        // Ignore cleanup errors
+      }
+
+      // Determine media type based on whether compression converted to JPEG
+      const mediaType = wasCompressed ? 'image/jpeg' : 'image/png';
+      const sizeInfo = wasCompressed
+        ? `${imageBuffer.length} bytes, compressed from ${originalSize} bytes`
+        : `${imageBuffer.length} bytes`;
+
+      const result: ScreenshotResult = {
+        type: 'image',
+        mediaType,
+        data: base64Data,
+        description: `${description} (${sizeInfo})`
+      };
+
+      return JSON.stringify(result);
+    } catch (err) {
+      try {
+        await unlink(tempPath);
+      } catch {
+        // Ignore
+      }
+
+      const message = (err as Error).message;
+      throw new Error(`Screenshot failed: ${message}`);
+    }
+  }
+};
+
+// --- List Windows Tool ---
+
+export const listWindowsTool: Tool = {
+  capabilities: [ToolCapability.SCREEN_CAPTURE],
+  definition: {
+    name: 'list_windows',
+    description: 'List all visible windows with their IDs, PIDs, app names, and titles. Use this to find window IDs for targeted screenshots.',
+    parameters: {
+      type: 'object',
+      properties: {
+        filter: {
+          type: 'string',
+          description: 'Optional filter to match app name or title (case-insensitive)'
+        }
+      },
+      required: []
+    }
+  },
+  execute: async (args) => {
+    const filter = args.filter ? String(args.filter).toLowerCase() : undefined;
+    const platform = process.platform;
+
+    let windows: WindowInfo[] = [];
+
+    if (platform === 'darwin') {
+      windows = await getWindowListMac();
+    } else if (platform === 'linux') {
+      windows = await getWindowListLinux();
+    } else if (platform === 'win32') {
+      windows = await getWindowListWindows();
+    } else {
+      throw new Error(`Window listing not supported on platform: ${platform}`);
+    }
+
+    if (filter) {
+      windows = windows.filter(w =>
+        w.appName.toLowerCase().includes(filter) ||
+        w.title.toLowerCase().includes(filter)
+      );
+    }
+
+    if (windows.length === 0) {
+      return filter
+        ? `No windows found matching "${filter}"`
+        : 'No visible windows found';
+    }
+
+    const lines = windows.map(w => {
+      const boundsStr = w.bounds
+        ? ` [${w.bounds.width}x${w.bounds.height}]`
+        : '';
+      return `• Window ${w.windowId} (PID ${w.pid}): ${w.appName}${w.title ? ` - "${w.title}"` : ''}${boundsStr}`;
+    });
+
+    return `Found ${windows.length} window(s):\n${lines.join('\n')}`;
+  }
+};
+
+// --- Run and Monitor Tool ---
+
+export const runAndMonitorTool: Tool = {
+  capabilities: [ToolCapability.SCREEN_CAPTURE, ToolCapability.SHELL_EXEC],
+  definition: {
+    name: 'run_and_capture',
+    description: 'Launch an application and capture its window after it opens. Useful for running a command and seeing its visual output.',
+    parameters: {
+      type: 'object',
+      properties: {
+        command: {
+          type: 'string',
+          description: 'Command to run (e.g., "open -a Safari https://example.com" on macOS, "firefox https://example.com" on Linux)'
+        },
+        waitMs: {
+          type: 'number',
+          description: 'Milliseconds to wait for app to open before capturing (default: 2000)'
+        },
+        app: {
+          type: 'string',
+          description: 'App name to capture after launch (if different from command). Will search for window by this name.'
+        }
+      },
+      required: ['command']
+    }
+  },
+  execute: async (args) => {
+    const command = String(args.command);
+    const waitMs = args.waitMs !== undefined ? Number(args.waitMs) : 2000;
+    const appName = args.app ? String(args.app) : undefined;
+
+    // Launch the application
+    try {
+      // Use spawn behavior - don't wait for command to finish
+      execAsync(command, { timeout: 5000 }).catch(() => {});
+    } catch {
+      // Ignore - app may have launched successfully even if command returns
+    }
+
+    // Wait for app to open
+    await new Promise(resolve => setTimeout(resolve, waitMs));
+
+    // Try to find and capture the window
+    const platform = process.platform;
+    let windows: WindowInfo[] = [];
+
+    if (platform === 'darwin') {
+      windows = await getWindowListMac();
+    } else if (platform === 'linux') {
+      windows = await getWindowListLinux();
+    } else if (platform === 'win32') {
+      windows = await getWindowListWindows();
+    }
+
+    // Find the app window
+    let targetWindow: WindowInfo | undefined;
+
+    if (appName) {
+      const lower = appName.toLowerCase();
+      targetWindow = windows.find(w =>
+        w.appName.toLowerCase().includes(lower) ||
+        w.title.toLowerCase().includes(lower)
+      );
+    } else {
+      // Try to extract app name from command
+      const cmdParts = command.split(/\s+/);
+      // Look for app name in common patterns
+      const openIdx = cmdParts.indexOf('-a');
+      if (openIdx !== -1 && cmdParts[openIdx + 1]) {
+        const appFromCmd = cmdParts[openIdx + 1].toLowerCase();
+        targetWindow = windows.find(w => w.appName.toLowerCase().includes(appFromCmd));
+      }
+
+      if (!targetWindow) {
+        // Try matching last part of command
+        const lastPart = cmdParts[cmdParts.length - 1]?.toLowerCase() || '';
+        targetWindow = windows.find(w =>
+          w.appName.toLowerCase().includes(lastPart) ||
+          w.title.toLowerCase().includes(lastPart)
+        );
+      }
+    }
+
+    if (!targetWindow) {
+      // If we can't find the specific window, return list of windows
+      const windowList = windows.slice(0, 10).map(w =>
+        `• ${w.appName}${w.title ? ` - "${w.title}"` : ''} (Window ${w.windowId})`
+      ).join('\n');
+
+      return `App launched but window not found. Recent windows:\n${windowList}\n\nUse screenshot with a specific windowId or app name.`;
+    }
+
+    // Capture the window
+    const timestamp = Date.now();
+    const tempPath = join(tmpdir(), `ztc-screenshot-${timestamp}.png`);
+
+    try {
+      await captureWindow(targetWindow.windowId, tempPath);
+
+      const imageBuffer = await readFile(tempPath);
+      const base64Data = imageBuffer.toString('base64');
+
+      try {
+        await unlink(tempPath);
+      } catch {
+        // Ignore
+      }
+
+      const result: ScreenshotResult = {
+        type: 'image',
+        mediaType: 'image/png',
+        data: base64Data,
+        description: `Captured ${targetWindow.appName}${targetWindow.title ? ` - "${targetWindow.title}"` : ''} (${imageBuffer.length} bytes)`
+      };
+
+      return JSON.stringify(result);
+    } catch (err) {
+      try {
+        await unlink(tempPath);
+      } catch {
+        // Ignore
+      }
+      throw new Error(`Failed to capture window: ${(err as Error).message}`);
+    }
+  }
+};