junis 0.3.10 → 0.3.12

package/dist/cli/index.js

@@ -456,7 +456,10 @@ var toolPermissions = {
   desktop_hotkey: "confirm",
   desktop_scroll: "confirm",
   desktop_menu: "confirm",
+  desktop_paste: "confirm",
   desktop_screenshot: "confirm",
+  desktop_open_app: "auto",
+  desktop_open_url: "auto",
   cron_create: "confirm",
   cron_delete: "confirm",
   edit_block: "confirm",
@@ -487,6 +490,8 @@ var FilesystemTools = class {
         "ROUTING:",
         "- Use for system commands, package managers (npm, pip, brew), git, build tools, and scripting.",
         "- For reading files prefer read_file, for editing prefer edit_block, for searching prefer search_code.",
+        "- NOT for macOS app GUI interaction. When the user asks to interact with, control, or automate any application (clicking, typing, reading screen, navigating menus), use the desktop_* tools instead (desktop_open_app, desktop_see, desktop_click, desktop_type, desktop_paste, desktop_hotkey, desktop_scroll, desktop_menu, desktop_screenshot).",
+        "- The ONLY exception: permission fix commands (swift -e for CGRequestScreenCaptureAccess/AXIsProcessTrustedWithOptions, peekaboo permissions, or open 'x-apple.systempreferences:...').",
         "",
         "BEHAVIOR:",
         "- Execute commands directly when the user requests them. Do not ask for confirmation \u2014 the user has already decided.",
@@ -1626,7 +1631,12 @@ Cause: ${e.message}${hint}` }],
         "Start or stop screen recording. Captures the full screen as MP4 video.",
         "",
         "Use action='start' to begin, action='stop' to end and save. Only one recording can be active at a time.",
-        "Platform-specific: macOS (screencapture -v), Windows/Linux (ffmpeg)."
+        "Platform-specific: macOS (screencapture -v), Windows/Linux (ffmpeg).",
+        "",
+        "PERMISSIONS (macOS): Screen Recording permission is needed (inherited from terminal app).",
+        "If denied, run via execute_command: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+        "\u2192 macOS dialog appears. Ask user to click Allow, then retry.",
+        "Fallback: open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'"
       ].join("\n"),
       {
         action: z4.enum(["start", "stop"]).describe("'start': begin recording, 'stop': end recording and save the file"),
@@ -1716,10 +1726,28 @@ import { execFile as execFile2 } from "child_process";
 import { promisify as promisify4 } from "util";
 import { platform as platform2 } from "os";
 var execFileAsync2 = promisify4(execFile2);
+async function requestMacOSPermissions() {
+  try {
+    await execFileAsync2("swift", ["-e", `
+      import CoreGraphics
+      CGRequestScreenCaptureAccess()
+    `], { timeout: 5e3 });
+  } catch {
+  }
+  try {
+    await execFileAsync2("swift", ["-e", `
+      import ApplicationServices
+      let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary
+      AXIsProcessTrustedWithOptions(opts)
+    `], { timeout: 5e3 });
+  } catch {
+  }
+}
 async function ensurePeekaboo() {
   if (platform2() !== "darwin") return false;
   try {
     await execFileAsync2("which", ["peekaboo"]);
+    await requestMacOSPermissions();
     return true;
   } catch {
     console.log("\u23F3 peekaboo not found, installing via brew...");
@@ -1727,6 +1755,7 @@ async function ensurePeekaboo() {
       await execFileAsync2("brew", ["tap", "steipete/tap"], { timeout: 3e4 });
       await execFileAsync2("brew", ["install", "peekaboo"], { timeout: 12e4 });
       console.log("\u2705 peekaboo installed");
+      await requestMacOSPermissions();
       return true;
     } catch (brewErr) {
       console.warn("\u26A0\uFE0F  peekaboo install failed:", brewErr.message);
@@ -1751,11 +1780,18 @@ var consecutiveFailures = 0;
 var MAX_CONSECUTIVE_FAILURES = 2;
 var PERM_FIX_HINT = [
   "\n\n\u{1F527} PERMISSION FIX \u2014 run these via execute_command:",
-  "1. Check status:  peekaboo permissions --json-output",
-  "2. Screen Recording:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-  "3. Accessibility:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'",
-  "Toggle ON for 'peekaboo' in the opened panel, then retry."
+  "1. Check: peekaboo permissions --json-output",
+  "2. Screen Recording: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+  "3. Accessibility: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+  "\u2192 macOS system dialogs appear. Ask user to click Allow, then retry.",
+  "NOTE: peekaboo inherits permissions from the terminal app \u2014 do NOT look for 'peekaboo' in System Preferences.",
+  "Fallback (if Swift fails): open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
+  "  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'"
 ].join("\n");
+function isPermissionError(msg) {
+  const lower = msg.toLowerCase();
+  return lower.includes("permission") || lower.includes("accessibility") || lower.includes("screen recording") || lower.includes("not trusted") || lower.includes("not allowed") || lower.includes("denied");
+}
 async function peekaboo(args) {
   try {
     const { stdout } = await execa("peekaboo", [...args, "--json-output"]);
@@ -1763,14 +1799,13 @@ async function peekaboo(args) {
     return JSON.parse(stdout);
   } catch (err) {
     consecutiveFailures++;
-    const msg = err.message?.toLowerCase() ?? "";
-    const isPermError = msg.includes("permission") || msg.includes("accessibility") || msg.includes("screen recording") || msg.includes("not trusted") || msg.includes("not allowed") || msg.includes("denied");
-    const hint = isPermError ? PERM_FIX_HINT : "";
+    const msg = err.message ?? "";
+    const hint = isPermissionError(msg) ? PERM_FIX_HINT : "";
     if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
       consecutiveFailures = 0;
-      throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${err.message}${hint}`);
+      throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${msg}${hint}`);
     }
-    throw new Error(`${err.message}${hint}`);
+    throw new Error(`${msg}${hint}`);
   }
 }
 function checkBlacklist(app) {
@@ -1785,25 +1820,38 @@ var DesktopTools = class {
       [
         "Capture the macOS Accessibility Tree snapshot for a running application. Returns a structured element list with IDs, roles, labels, and positions.",
         "",
-        "WORKFLOW: List running apps \u2192 capture accessibility tree \u2192 find target element by role/label \u2192 interact using element ID or label (click, type, scroll).",
-        "Pass the returned snapshotId to subsequent interaction calls for 240x speed improvement (cached lookup vs. full re-scan).",
+        "WHEN TO USE DESKTOP TOOLS:",
+        "When the user asks to interact with, control, or automate ANY macOS application \u2014 use desktop_* tools, NOT execute_command.",
+        "Workflow: desktop_open_app \u2192 desktop_see \u2192 desktop_click/type/paste \u2192 verify with desktop_see or desktop_screenshot.",
+        "",
+        "WORKFLOW TIPS:",
+        "- If accessibility tree times out (complex UI apps like KakaoTalk): increase timeout parameter, or fall back to:",
+        "  desktop_screenshot \u2192 desktop_list_windows (get window bounds x,y,w,h) \u2192 calculate coordinates \u2192 desktop_click with coords parameter.",
+        "- For Korean/Japanese/Chinese text input: always use desktop_paste (NOT desktop_type).",
+        "- For multi-window apps: use desktop_list_windows to find specific windows.",
+        "- Pass snapshotId to subsequent calls for 240x speed improvement.",
+        "- Double-click to open items (e.g. chat windows in KakaoTalk): use desktop_click with doubleClick=true.",
         "",
-        "PERMISSIONS: Desktop tools require macOS Accessibility + Screen Recording permissions for 'peekaboo'.",
-        "If a tool fails with permission error, use execute_command to:",
+        "PERMISSIONS: Requires Accessibility + Screen Recording.",
+        "peekaboo inherits permissions from the parent terminal app \u2014 it does NOT need its own entry in System Preferences.",
+        "If denied, fix via execute_command:",
         "  1. peekaboo permissions --json-output  (check which are missing)",
-        "  2. open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'",
-        "  3. open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-        "Ask the user to toggle ON for 'peekaboo', then retry.",
+        "  2. Screen Recording: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+        "  3. Accessibility: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+        "  \u2192 macOS system dialogs appear. Ask user to click Allow, then retry.",
+        "  Fallback: open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
         "",
-        "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger an automatic safety stop."
+        "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
       ].join("\n"),
       {
-        app: z5.string().optional().describe("App name to target (e.g. 'Safari', 'Notes', 'Google Chrome'). Omit for the frontmost app.")
+        app: z5.string().optional().describe("App name to target (e.g. 'Safari', 'Notes', 'Google Chrome'). Omit for the frontmost app."),
+        timeout: z5.number().optional().describe("Timeout in seconds (default: 20). Increase for complex UI apps. If it still times out, fall back to desktop_screenshot + coordinate-based desktop_click.")
       },
-      async ({ app }) => {
+      async ({ app, timeout }) => {
         checkBlacklist(app);
         const args = ["see"];
         if (app) args.push("--app", app);
+        if (timeout) args.push("--timeout-seconds", String(timeout));
         const result = await peekaboo(args);
         const data = result.data;
         const snapshotId = data?.snapshot_id ?? result.snapshotId ?? result.snapshot_id;
@@ -1824,25 +1872,48 @@ var DesktopTools = class {
     server.tool(
       "desktop_click",
       [
-        "Click a macOS UI element by its accessibility label, ID, or x,y coordinates.",
+        "Click a macOS UI element by text query, element ID, or x,y coordinates.",
+        "",
+        "PARAMETER GUIDE:",
+        "- query: Text/label to search for (e.g. 'Save', 'Submit'). Searches visible UI elements.",
+        "- on: Element ID from a previous desktop_see snapshot (e.g. 'B1', 'T2'). Fastest with snapshotId.",
+        "- coords: Click at exact screen coordinates as 'x,y' (e.g. '1070,188'). Use when accessibility tree times out.",
         "",
-        "The 'on' parameter accepts: element label text (e.g. 'Save'), accessibility ID from a previous accessibility tree capture, or coordinates as 'x,y' string.",
-        "For faster interaction, pass the snapshotId from a recent accessibility tree capture.",
+        "PROVEN WORKFLOW (from KakaoTalk automation):",
+        "1. Try desktop_see first to get element IDs \u2192 click with 'on' parameter.",
+        "2. If desktop_see times out: use desktop_screenshot \u2192 calculate coordinates \u2192 click with 'coords'.",
+        "3. Use desktop_list_windows to get window bounds (x,y,w,h) for coordinate calculation.",
+        "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app).",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
       ].join("\n"),
       {
-        on: z5.string().describe("Element label, accessibility ID, or 'x,y' coordinates to click"),
-        app: z5.string().optional().describe("App name to target (e.g. 'Safari')"),
-        snapshot: z5.string().optional().describe("snapshotId from a previous accessibility tree capture for cached interaction (240x faster)"),
-        doubleClick: z5.boolean().optional().default(false).describe("Double-click instead of single click")
+        query: z5.string().optional().describe("Text/label to search and click (e.g. 'Save', 'Submit Button')"),
+        on: z5.string().optional().describe("Element ID from desktop_see snapshot (e.g. 'B1', 'T2')"),
+        coords: z5.string().optional().describe("Screen coordinates as 'x,y' (e.g. '1070,188'). Use when accessibility tree is unavailable."),
+        app: z5.string().optional().describe("App name to target (e.g. 'Safari', 'KakaoTalk')"),
+        snapshot: z5.string().optional().describe("snapshotId from desktop_see for cached interaction (240x faster)"),
+        doubleClick: z5.boolean().optional().default(false).describe("Double-click instead of single click (e.g. open files, open chat windows)"),
+        rightClick: z5.boolean().optional().default(false).describe("Right-click (context menu)")
       },
-      async ({ on, app, snapshot, doubleClick }) => {
+      async ({ query, on, coords, app, snapshot, doubleClick, rightClick }) => {
         checkBlacklist(app);
-        const args = ["click", "--on", on];
+        if (!query && !on && !coords) {
+          throw new Error("Provide at least one of: query (text search), on (element ID), or coords ('x,y').");
+        }
+        const args = ["click"];
+        if (coords) {
+          args.push("--coords", coords);
+        } else if (on) {
+          args.push("--on", on);
+        } else if (query) {
+          args.push(query);
+        }
         if (app) args.push("--app", app);
         if (snapshot) args.push("--snapshot", snapshot);
-        if (doubleClick) args.push("--double-click");
+        if (doubleClick) args.push("--double");
+        if (rightClick) args.push("--right");
         const result = await peekaboo(args);
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -1852,20 +1923,27 @@ var DesktopTools = class {
     server.tool(
       "desktop_type",
       [
-        "Type text into the currently focused UI element on macOS. The text is sent as keyboard input character-by-character.",
+        "Type text into the currently focused UI element on macOS via keyboard simulation.",
+        "",
+        "IMPORTANT: For Korean/Japanese/Chinese/emoji text, use desktop_paste instead \u2014 keyboard simulation does not support CJK.",
+        "Always click the target input field first (via desktop_click) before typing.",
         "",
-        "IMPORTANT: Always capture the accessibility tree first to verify the correct element is focused before typing.",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app).",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
-        text: z5.string().describe("Text to type into the focused element"),
-        app: z5.string().optional().describe("App name to focus before typing")
+        text: z5.string().describe("Text to type (ASCII only \u2014 for CJK/emoji use desktop_paste)"),
+        app: z5.string().optional().describe("App name to focus before typing"),
+        pressReturn: z5.boolean().optional().default(false).describe("Press Return/Enter after typing (e.g. to send a message or submit a form)"),
+        clear: z5.boolean().optional().default(false).describe("Clear the field before typing (Cmd+A, Delete)")
       },
-      async ({ text, app }) => {
+      async ({ text, app, pressReturn, clear }) => {
         checkBlacklist(app);
         const args = ["type", text];
         if (app) args.push("--app", app);
+        if (clear) args.push("--clear");
+        if (pressReturn) args.push("--return");
         const result = await peekaboo(args);
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -1879,6 +1957,9 @@ var DesktopTools = class {
         "",
         "Common shortcuts: 'cmd,c' (copy), 'cmd,v' (paste), 'cmd,z' (undo), 'cmd,s' (save), 'cmd,w' (close tab), 'cmd,q' (quit), 'cmd,shift,t' (reopen tab), 'cmd,tab' (switch app).",
         "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1902,6 +1983,9 @@ var DesktopTools = class {
         "",
         "Use 'ticks' to control scroll distance (default: 3, higher = more scrolling). Can target a specific element by label or ID from a previous accessibility tree capture.",
         "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1939,11 +2023,13 @@ var DesktopTools = class {
           };
         } catch (err) {
           consecutiveFailures++;
+          const msg = err.message ?? "";
+          const hint = isPermissionError(msg) ? PERM_FIX_HINT : "";
           if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
             consecutiveFailures = 0;
-            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${err.message}`);
+            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${msg}${hint}`);
           }
-          throw err;
+          throw new Error(`${msg}${hint}`);
         }
       }
     );
@@ -1953,7 +2039,10 @@ var DesktopTools = class {
         "List all open windows on macOS, optionally filtered by app name. Returns window titles and metadata.",
         "",
         "If no app is specified, lists windows for the frontmost application.",
-        "Use this after identifying running apps to find specific windows before capturing the accessibility tree or taking a screenshot."
+        "Use this after identifying running apps to find specific windows before capturing the accessibility tree or taking a screenshot.",
+        "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'"
       ].join("\n"),
       {
         app: z5.string().optional().describe("Filter by app name. Omit to query the frontmost app.")
@@ -1977,32 +2066,54 @@ var DesktopTools = class {
           };
         } catch (err) {
           consecutiveFailures++;
+          const msg = err.message ?? "";
+          const hint = isPermissionError(msg) ? PERM_FIX_HINT : "";
           if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
             consecutiveFailures = 0;
-            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${err.message}`);
+            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${msg}${hint}`);
           }
-          throw err;
+          throw new Error(`${msg}${hint}`);
         }
       }
     );
     server.tool(
       "desktop_screenshot",
       [
-        "Take a high-quality macOS screenshot (Retina display support). Returns base64 image data.",
+        "Take a high-quality macOS screenshot. Returns base64 image data.",
+        "",
+        "MODES:",
+        "- 'screen': full display capture (default). Use screenIndex for multi-monitor setups.",
+        "- 'window': specific app window. Specify with app, windowTitle, or windowIndex.",
+        "- 'frontmost': capture only the frontmost window.",
+        "- 'auto': peekaboo chooses the best mode automatically.",
+        "",
+        "TARGETING SPECIFIC WINDOWS:",
+        "- app: capture by app name (e.g. 'Safari', 'KakaoTalk')",
+        "- windowTitle: capture a specific window by title (partial match supported)",
+        "- windowIndex: capture by window z-order (0 = frontmost window of the app)",
+        "- screenIndex: which display to capture in 'screen' mode (0-based, for multi-monitor)",
         "",
-        "MODES: 'screen' captures the full display, 'window' captures a specific app window.",
         "TIP: Prefer the accessibility tree for understanding UI structure \u2014 use screenshots only when visual appearance matters (layouts, images, colors).",
         "",
+        "PERMISSIONS: Requires Screen Recording (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
-        app: z5.string().optional().describe("Capture a specific app's window (by name)"),
-        mode: z5.enum(["screen", "window"]).optional().default("screen").describe("'screen': full display capture, 'window': specific app window only")
+        app: z5.string().optional().describe("Capture a specific app's window (by name, e.g. 'Safari', 'KakaoTalk')"),
+        mode: z5.enum(["screen", "window", "frontmost", "auto"]).optional().default("screen").describe("'screen': full display, 'window': specific app window, 'frontmost': frontmost window, 'auto': peekaboo decides"),
+        windowTitle: z5.string().optional().describe("Capture window by title (partial match). Use with mode='window'."),
+        windowIndex: z5.number().optional().describe("Window z-order index (0 = frontmost window of the app). Use with mode='window'."),
+        screenIndex: z5.number().optional().describe("Display index for multi-monitor (0-based). Use with mode='screen'.")
       },
-      async ({ app, mode }) => {
+      async ({ app, mode, windowTitle, windowIndex, screenIndex }) => {
         checkBlacklist(app);
         const args = ["image", "--mode", mode];
         if (app) args.push("--app", app);
+        if (windowTitle) args.push("--window-title", windowTitle);
+        if (windowIndex !== void 0) args.push("--window-index", String(windowIndex));
+        if (screenIndex !== void 0) args.push("--screen-index", String(screenIndex));
         const result = await peekaboo(args);
         const data = result.data;
         const files = data?.files;
@@ -2030,6 +2141,9 @@ var DesktopTools = class {
         "Examples: ['File', 'New Tab'], ['Edit', 'Find', 'Find...'], ['View', 'Enter Full Screen'].",
         "Omit the 'app' parameter to target the frontmost app. The target app must be running.",
         "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -2048,14 +2162,88 @@ var DesktopTools = class {
           };
         } catch (err) {
           consecutiveFailures++;
+          const msg = err.message ?? "";
+          const hint = isPermissionError(msg) ? PERM_FIX_HINT : "";
           if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
             consecutiveFailures = 0;
-            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${err.message}`);
+            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${msg}${hint}`);
           }
-          throw err;
+          throw new Error(`${msg}${hint}`);
         }
       }
     );
+    server.tool(
+      "desktop_paste",
+      [
+        "Paste text via clipboard into the focused element. Automatically sets clipboard, pastes (Cmd+V), then restores previous clipboard.",
+        "",
+        "ALWAYS USE THIS instead of desktop_type for: Korean, Japanese, Chinese, emoji, or any non-ASCII text.",
+        "Unlike desktop_type (keyboard simulation), this uses the system clipboard \u2014 works with ALL character sets.",
+        "",
+        `PROVEN: In KakaoTalk automation, 'peekaboo paste "\uC548\uB155?"' successfully sent Korean text while 'type' would have failed.`,
+        "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app).",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
+      ].join("\n"),
+      {
+        text: z5.string().describe("Text to paste (supports Korean, Japanese, Chinese, emoji, any Unicode)"),
+        app: z5.string().optional().describe("App name to focus before pasting")
+      },
+      async ({ text, app }) => {
+        checkBlacklist(app);
+        const args = ["paste", text];
+        if (app) args.push("--app", app);
+        const result = await peekaboo(args);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      }
+    );
+    server.tool(
+      "desktop_open_app",
+      [
+        "Launch or bring to front a macOS application. Use this as the FIRST STEP when automating any app.",
+        "",
+        "PROVEN WORKFLOW (from KakaoTalk automation):",
+        "1. desktop_open_app \u2192 2. desktop_list_apps (verify) \u2192 3. desktop_see or desktop_screenshot \u2192 4. interact",
+        "",
+        "After launching, use desktop_list_apps to confirm the app is running, then desktop_see to capture UI.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked for automation safety."
+      ].join("\n"),
+      {
+        app: z5.string().describe("Application name to launch (e.g. 'Safari', 'Notes', 'KakaoTalk', 'Google Chrome')")
+      },
+      async ({ app }) => {
+        checkBlacklist(app);
+        const args = ["app", "launch", app, "--wait-until-ready"];
+        const result = await peekaboo(args);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      }
+    );
+    server.tool(
+      "desktop_open_url",
+      [
+        "Open a URL or file with its default (or specified) application.",
+        "",
+        "Examples: 'https://google.com', '~/Documents/report.pdf', 'x-apple.systempreferences:...'"
+      ].join("\n"),
+      {
+        url: z5.string().describe("URL or file path to open"),
+        app: z5.string().optional().describe("Specific app to open with (e.g. 'Google Chrome', 'Preview')")
+      },
+      async ({ url, app }) => {
+        const args = ["open", url];
+        if (app) args.push("--app", app);
+        const result = await peekaboo(args);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      }
+    );
   }
 };
 

package/dist/server/mcp.js

@@ -42,7 +42,10 @@ var toolPermissions = {
   desktop_hotkey: "confirm",
   desktop_scroll: "confirm",
   desktop_menu: "confirm",
+  desktop_paste: "confirm",
   desktop_screenshot: "confirm",
+  desktop_open_app: "auto",
+  desktop_open_url: "auto",
   cron_create: "confirm",
   cron_delete: "confirm",
   edit_block: "confirm",
@@ -73,6 +76,8 @@ var FilesystemTools = class {
         "ROUTING:",
         "- Use for system commands, package managers (npm, pip, brew), git, build tools, and scripting.",
         "- For reading files prefer read_file, for editing prefer edit_block, for searching prefer search_code.",
+        "- NOT for macOS app GUI interaction. When the user asks to interact with, control, or automate any application (clicking, typing, reading screen, navigating menus), use the desktop_* tools instead (desktop_open_app, desktop_see, desktop_click, desktop_type, desktop_paste, desktop_hotkey, desktop_scroll, desktop_menu, desktop_screenshot).",
+        "- The ONLY exception: permission fix commands (swift -e for CGRequestScreenCaptureAccess/AXIsProcessTrustedWithOptions, peekaboo permissions, or open 'x-apple.systempreferences:...').",
         "",
         "BEHAVIOR:",
         "- Execute commands directly when the user requests them. Do not ask for confirmation \u2014 the user has already decided.",
@@ -1212,7 +1217,12 @@ Cause: ${e.message}${hint}` }],
         "Start or stop screen recording. Captures the full screen as MP4 video.",
         "",
         "Use action='start' to begin, action='stop' to end and save. Only one recording can be active at a time.",
-        "Platform-specific: macOS (screencapture -v), Windows/Linux (ffmpeg)."
+        "Platform-specific: macOS (screencapture -v), Windows/Linux (ffmpeg).",
+        "",
+        "PERMISSIONS (macOS): Screen Recording permission is needed (inherited from terminal app).",
+        "If denied, run via execute_command: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+        "\u2192 macOS dialog appears. Ask user to click Allow, then retry.",
+        "Fallback: open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'"
       ].join("\n"),
       {
         action: z4.enum(["start", "stop"]).describe("'start': begin recording, 'stop': end recording and save the file"),
@@ -1302,10 +1312,28 @@ import { execFile as execFile2 } from "child_process";
 import { promisify as promisify4 } from "util";
 import { platform as platform2 } from "os";
 var execFileAsync2 = promisify4(execFile2);
+async function requestMacOSPermissions() {
+  try {
+    await execFileAsync2("swift", ["-e", `
+      import CoreGraphics
+      CGRequestScreenCaptureAccess()
+    `], { timeout: 5e3 });
+  } catch {
+  }
+  try {
+    await execFileAsync2("swift", ["-e", `
+      import ApplicationServices
+      let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary
+      AXIsProcessTrustedWithOptions(opts)
+    `], { timeout: 5e3 });
+  } catch {
+  }
+}
 async function ensurePeekaboo() {
   if (platform2() !== "darwin") return false;
   try {
     await execFileAsync2("which", ["peekaboo"]);
+    await requestMacOSPermissions();
     return true;
   } catch {
     console.log("\u23F3 peekaboo not found, installing via brew...");
@@ -1313,6 +1341,7 @@ async function ensurePeekaboo() {
       await execFileAsync2("brew", ["tap", "steipete/tap"], { timeout: 3e4 });
       await execFileAsync2("brew", ["install", "peekaboo"], { timeout: 12e4 });
       console.log("\u2705 peekaboo installed");
+      await requestMacOSPermissions();
       return true;
     } catch (brewErr) {
       console.warn("\u26A0\uFE0F  peekaboo install failed:", brewErr.message);
@@ -1337,11 +1366,18 @@ var consecutiveFailures = 0;
 var MAX_CONSECUTIVE_FAILURES = 2;
 var PERM_FIX_HINT = [
   "\n\n\u{1F527} PERMISSION FIX \u2014 run these via execute_command:",
-  "1. Check status:  peekaboo permissions --json-output",
-  "2. Screen Recording:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-  "3. Accessibility:  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'",
-  "Toggle ON for 'peekaboo' in the opened panel, then retry."
+  "1. Check: peekaboo permissions --json-output",
+  "2. Screen Recording: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+  "3. Accessibility: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+  "\u2192 macOS system dialogs appear. Ask user to click Allow, then retry.",
+  "NOTE: peekaboo inherits permissions from the terminal app \u2014 do NOT look for 'peekaboo' in System Preferences.",
+  "Fallback (if Swift fails): open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
+  "  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'"
 ].join("\n");
+function isPermissionError(msg) {
+  const lower = msg.toLowerCase();
+  return lower.includes("permission") || lower.includes("accessibility") || lower.includes("screen recording") || lower.includes("not trusted") || lower.includes("not allowed") || lower.includes("denied");
+}
 async function peekaboo(args) {
   try {
     const { stdout } = await execa("peekaboo", [...args, "--json-output"]);
@@ -1349,14 +1385,13 @@ async function peekaboo(args) {
     return JSON.parse(stdout);
   } catch (err) {
     consecutiveFailures++;
-    const msg = err.message?.toLowerCase() ?? "";
-    const isPermError = msg.includes("permission") || msg.includes("accessibility") || msg.includes("screen recording") || msg.includes("not trusted") || msg.includes("not allowed") || msg.includes("denied");
-    const hint = isPermError ? PERM_FIX_HINT : "";
+    const msg = err.message ?? "";
+    const hint = isPermissionError(msg) ? PERM_FIX_HINT : "";
     if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
       consecutiveFailures = 0;
-      throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${err.message}${hint}`);
+      throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${msg}${hint}`);
     }
-    throw new Error(`${err.message}${hint}`);
+    throw new Error(`${msg}${hint}`);
   }
 }
 function checkBlacklist(app) {
@@ -1371,25 +1406,38 @@ var DesktopTools = class {
       [
         "Capture the macOS Accessibility Tree snapshot for a running application. Returns a structured element list with IDs, roles, labels, and positions.",
         "",
-        "WORKFLOW: List running apps \u2192 capture accessibility tree \u2192 find target element by role/label \u2192 interact using element ID or label (click, type, scroll).",
-        "Pass the returned snapshotId to subsequent interaction calls for 240x speed improvement (cached lookup vs. full re-scan).",
+        "WHEN TO USE DESKTOP TOOLS:",
+        "When the user asks to interact with, control, or automate ANY macOS application \u2014 use desktop_* tools, NOT execute_command.",
+        "Workflow: desktop_open_app \u2192 desktop_see \u2192 desktop_click/type/paste \u2192 verify with desktop_see or desktop_screenshot.",
+        "",
+        "WORKFLOW TIPS:",
+        "- If accessibility tree times out (complex UI apps like KakaoTalk): increase timeout parameter, or fall back to:",
+        "  desktop_screenshot \u2192 desktop_list_windows (get window bounds x,y,w,h) \u2192 calculate coordinates \u2192 desktop_click with coords parameter.",
+        "- For Korean/Japanese/Chinese text input: always use desktop_paste (NOT desktop_type).",
+        "- For multi-window apps: use desktop_list_windows to find specific windows.",
+        "- Pass snapshotId to subsequent calls for 240x speed improvement.",
+        "- Double-click to open items (e.g. chat windows in KakaoTalk): use desktop_click with doubleClick=true.",
         "",
-        "PERMISSIONS: Desktop tools require macOS Accessibility + Screen Recording permissions for 'peekaboo'.",
-        "If a tool fails with permission error, use execute_command to:",
+        "PERMISSIONS: Requires Accessibility + Screen Recording.",
+        "peekaboo inherits permissions from the parent terminal app \u2014 it does NOT need its own entry in System Preferences.",
+        "If denied, fix via execute_command:",
         "  1. peekaboo permissions --json-output  (check which are missing)",
-        "  2. open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'",
-        "  3. open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-        "Ask the user to toggle ON for 'peekaboo', then retry.",
+        "  2. Screen Recording: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+        "  3. Accessibility: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+        "  \u2192 macOS system dialogs appear. Ask user to click Allow, then retry.",
+        "  Fallback: open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
         "",
-        "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger an automatic safety stop."
+        "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
       ].join("\n"),
       {
-        app: z5.string().optional().describe("App name to target (e.g. 'Safari', 'Notes', 'Google Chrome'). Omit for the frontmost app.")
+        app: z5.string().optional().describe("App name to target (e.g. 'Safari', 'Notes', 'Google Chrome'). Omit for the frontmost app."),
+        timeout: z5.number().optional().describe("Timeout in seconds (default: 20). Increase for complex UI apps. If it still times out, fall back to desktop_screenshot + coordinate-based desktop_click.")
       },
-      async ({ app }) => {
+      async ({ app, timeout }) => {
         checkBlacklist(app);
         const args = ["see"];
         if (app) args.push("--app", app);
+        if (timeout) args.push("--timeout-seconds", String(timeout));
         const result = await peekaboo(args);
         const data = result.data;
         const snapshotId = data?.snapshot_id ?? result.snapshotId ?? result.snapshot_id;
@@ -1410,25 +1458,48 @@ var DesktopTools = class {
     server.tool(
       "desktop_click",
       [
-        "Click a macOS UI element by its accessibility label, ID, or x,y coordinates.",
+        "Click a macOS UI element by text query, element ID, or x,y coordinates.",
+        "",
+        "PARAMETER GUIDE:",
+        "- query: Text/label to search for (e.g. 'Save', 'Submit'). Searches visible UI elements.",
+        "- on: Element ID from a previous desktop_see snapshot (e.g. 'B1', 'T2'). Fastest with snapshotId.",
+        "- coords: Click at exact screen coordinates as 'x,y' (e.g. '1070,188'). Use when accessibility tree times out.",
         "",
-        "The 'on' parameter accepts: element label text (e.g. 'Save'), accessibility ID from a previous accessibility tree capture, or coordinates as 'x,y' string.",
-        "For faster interaction, pass the snapshotId from a recent accessibility tree capture.",
+        "PROVEN WORKFLOW (from KakaoTalk automation):",
+        "1. Try desktop_see first to get element IDs \u2192 click with 'on' parameter.",
+        "2. If desktop_see times out: use desktop_screenshot \u2192 calculate coordinates \u2192 click with 'coords'.",
+        "3. Use desktop_list_windows to get window bounds (x,y,w,h) for coordinate calculation.",
+        "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app).",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked. Two consecutive failures trigger automatic safety stop."
       ].join("\n"),
       {
-        on: z5.string().describe("Element label, accessibility ID, or 'x,y' coordinates to click"),
-        app: z5.string().optional().describe("App name to target (e.g. 'Safari')"),
-        snapshot: z5.string().optional().describe("snapshotId from a previous accessibility tree capture for cached interaction (240x faster)"),
-        doubleClick: z5.boolean().optional().default(false).describe("Double-click instead of single click")
+        query: z5.string().optional().describe("Text/label to search and click (e.g. 'Save', 'Submit Button')"),
+        on: z5.string().optional().describe("Element ID from desktop_see snapshot (e.g. 'B1', 'T2')"),
+        coords: z5.string().optional().describe("Screen coordinates as 'x,y' (e.g. '1070,188'). Use when accessibility tree is unavailable."),
+        app: z5.string().optional().describe("App name to target (e.g. 'Safari', 'KakaoTalk')"),
+        snapshot: z5.string().optional().describe("snapshotId from desktop_see for cached interaction (240x faster)"),
+        doubleClick: z5.boolean().optional().default(false).describe("Double-click instead of single click (e.g. open files, open chat windows)"),
+        rightClick: z5.boolean().optional().default(false).describe("Right-click (context menu)")
       },
-      async ({ on, app, snapshot, doubleClick }) => {
+      async ({ query, on, coords, app, snapshot, doubleClick, rightClick }) => {
         checkBlacklist(app);
-        const args = ["click", "--on", on];
+        if (!query && !on && !coords) {
+          throw new Error("Provide at least one of: query (text search), on (element ID), or coords ('x,y').");
+        }
+        const args = ["click"];
+        if (coords) {
+          args.push("--coords", coords);
+        } else if (on) {
+          args.push("--on", on);
+        } else if (query) {
+          args.push(query);
+        }
         if (app) args.push("--app", app);
         if (snapshot) args.push("--snapshot", snapshot);
-        if (doubleClick) args.push("--double-click");
+        if (doubleClick) args.push("--double");
+        if (rightClick) args.push("--right");
         const result = await peekaboo(args);
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -1438,20 +1509,27 @@ var DesktopTools = class {
     server.tool(
       "desktop_type",
       [
-        "Type text into the currently focused UI element on macOS. The text is sent as keyboard input character-by-character.",
+        "Type text into the currently focused UI element on macOS via keyboard simulation.",
+        "",
+        "IMPORTANT: For Korean/Japanese/Chinese/emoji text, use desktop_paste instead \u2014 keyboard simulation does not support CJK.",
+        "Always click the target input field first (via desktop_click) before typing.",
         "",
-        "IMPORTANT: Always capture the accessibility tree first to verify the correct element is focused before typing.",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app).",
         "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
-        text: z5.string().describe("Text to type into the focused element"),
-        app: z5.string().optional().describe("App name to focus before typing")
+        text: z5.string().describe("Text to type (ASCII only \u2014 for CJK/emoji use desktop_paste)"),
+        app: z5.string().optional().describe("App name to focus before typing"),
+        pressReturn: z5.boolean().optional().default(false).describe("Press Return/Enter after typing (e.g. to send a message or submit a form)"),
+        clear: z5.boolean().optional().default(false).describe("Clear the field before typing (Cmd+A, Delete)")
       },
-      async ({ text, app }) => {
+      async ({ text, app, pressReturn, clear }) => {
         checkBlacklist(app);
         const args = ["type", text];
         if (app) args.push("--app", app);
+        if (clear) args.push("--clear");
+        if (pressReturn) args.push("--return");
         const result = await peekaboo(args);
         return {
           content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -1465,6 +1543,9 @@ var DesktopTools = class {
         "",
         "Common shortcuts: 'cmd,c' (copy), 'cmd,v' (paste), 'cmd,z' (undo), 'cmd,s' (save), 'cmd,w' (close tab), 'cmd,q' (quit), 'cmd,shift,t' (reopen tab), 'cmd,tab' (switch app).",
         "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1488,6 +1569,9 @@ var DesktopTools = class {
         "",
         "Use 'ticks' to control scroll distance (default: 3, higher = more scrolling). Can target a specific element by label or ID from a previous accessibility tree capture.",
         "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1525,11 +1609,13 @@ var DesktopTools = class {
           };
         } catch (err) {
           consecutiveFailures++;
+          const msg = err.message ?? "";
+          const hint = isPermissionError(msg) ? PERM_FIX_HINT : "";
           if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
             consecutiveFailures = 0;
-            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${err.message}`);
+            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${msg}${hint}`);
           }
-          throw err;
+          throw new Error(`${msg}${hint}`);
         }
       }
     );
@@ -1539,7 +1625,10 @@ var DesktopTools = class {
         "List all open windows on macOS, optionally filtered by app name. Returns window titles and metadata.",
         "",
         "If no app is specified, lists windows for the frontmost application.",
-        "Use this after identifying running apps to find specific windows before capturing the accessibility tree or taking a screenshot."
+        "Use this after identifying running apps to find specific windows before capturing the accessibility tree or taking a screenshot.",
+        "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'"
       ].join("\n"),
       {
         app: z5.string().optional().describe("Filter by app name. Omit to query the frontmost app.")
@@ -1563,32 +1652,54 @@ var DesktopTools = class {
           };
         } catch (err) {
           consecutiveFailures++;
+          const msg = err.message ?? "";
+          const hint = isPermissionError(msg) ? PERM_FIX_HINT : "";
           if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
             consecutiveFailures = 0;
-            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${err.message}`);
+            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${msg}${hint}`);
           }
-          throw err;
+          throw new Error(`${msg}${hint}`);
         }
       }
     );
     server.tool(
       "desktop_screenshot",
       [
-        "Take a high-quality macOS screenshot (Retina display support). Returns base64 image data.",
+        "Take a high-quality macOS screenshot. Returns base64 image data.",
+        "",
+        "MODES:",
+        "- 'screen': full display capture (default). Use screenIndex for multi-monitor setups.",
+        "- 'window': specific app window. Specify with app, windowTitle, or windowIndex.",
+        "- 'frontmost': capture only the frontmost window.",
+        "- 'auto': peekaboo chooses the best mode automatically.",
+        "",
+        "TARGETING SPECIFIC WINDOWS:",
+        "- app: capture by app name (e.g. 'Safari', 'KakaoTalk')",
+        "- windowTitle: capture a specific window by title (partial match supported)",
+        "- windowIndex: capture by window z-order (0 = frontmost window of the app)",
+        "- screenIndex: which display to capture in 'screen' mode (0-based, for multi-monitor)",
         "",
-        "MODES: 'screen' captures the full display, 'window' captures a specific app window.",
         "TIP: Prefer the accessibility tree for understanding UI structure \u2014 use screenshots only when visual appearance matters (layouts, images, colors).",
         "",
+        "PERMISSIONS: Requires Screen Recording (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
-        app: z5.string().optional().describe("Capture a specific app's window (by name)"),
-        mode: z5.enum(["screen", "window"]).optional().default("screen").describe("'screen': full display capture, 'window': specific app window only")
+        app: z5.string().optional().describe("Capture a specific app's window (by name, e.g. 'Safari', 'KakaoTalk')"),
+        mode: z5.enum(["screen", "window", "frontmost", "auto"]).optional().default("screen").describe("'screen': full display, 'window': specific app window, 'frontmost': frontmost window, 'auto': peekaboo decides"),
+        windowTitle: z5.string().optional().describe("Capture window by title (partial match). Use with mode='window'."),
+        windowIndex: z5.number().optional().describe("Window z-order index (0 = frontmost window of the app). Use with mode='window'."),
+        screenIndex: z5.number().optional().describe("Display index for multi-monitor (0-based). Use with mode='screen'.")
       },
-      async ({ app, mode }) => {
+      async ({ app, mode, windowTitle, windowIndex, screenIndex }) => {
         checkBlacklist(app);
         const args = ["image", "--mode", mode];
         if (app) args.push("--app", app);
+        if (windowTitle) args.push("--window-title", windowTitle);
+        if (windowIndex !== void 0) args.push("--window-index", String(windowIndex));
+        if (screenIndex !== void 0) args.push("--screen-index", String(screenIndex));
         const result = await peekaboo(args);
         const data = result.data;
         const files = data?.files;
@@ -1616,6 +1727,9 @@ var DesktopTools = class {
         "Examples: ['File', 'New Tab'], ['Edit', 'Find', 'Find...'], ['View', 'Enter Full Screen'].",
         "Omit the 'app' parameter to target the frontmost app. The target app must be running.",
         "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app, not peekaboo itself).",
+        "Fix if denied via execute_command: swift -e 'import ApplicationServices; let opts = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary; AXIsProcessTrustedWithOptions(opts)'",
+        "",
         "SAFETY: Terminal, iTerm, and Finder are blocked."
       ].join("\n"),
       {
@@ -1634,14 +1748,88 @@ var DesktopTools = class {
           };
         } catch (err) {
           consecutiveFailures++;
+          const msg = err.message ?? "";
+          const hint = isPermissionError(msg) ? PERM_FIX_HINT : "";
           if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
             consecutiveFailures = 0;
-            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${err.message}`);
+            throw new Error(`peekaboo failed ${MAX_CONSECUTIVE_FAILURES} times in a row. Auto-stopped for safety. Last error: ${msg}${hint}`);
           }
-          throw err;
+          throw new Error(`${msg}${hint}`);
         }
       }
     );
+    server.tool(
+      "desktop_paste",
+      [
+        "Paste text via clipboard into the focused element. Automatically sets clipboard, pastes (Cmd+V), then restores previous clipboard.",
+        "",
+        "ALWAYS USE THIS instead of desktop_type for: Korean, Japanese, Chinese, emoji, or any non-ASCII text.",
+        "Unlike desktop_type (keyboard simulation), this uses the system clipboard \u2014 works with ALL character sets.",
+        "",
+        `PROVEN: In KakaoTalk automation, 'peekaboo paste "\uC548\uB155?"' successfully sent Korean text while 'type' would have failed.`,
+        "",
+        "PERMISSIONS: Requires Accessibility (inherited from terminal app).",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked."
+      ].join("\n"),
+      {
+        text: z5.string().describe("Text to paste (supports Korean, Japanese, Chinese, emoji, any Unicode)"),
+        app: z5.string().optional().describe("App name to focus before pasting")
+      },
+      async ({ text, app }) => {
+        checkBlacklist(app);
+        const args = ["paste", text];
+        if (app) args.push("--app", app);
+        const result = await peekaboo(args);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      }
+    );
+    server.tool(
+      "desktop_open_app",
+      [
+        "Launch or bring to front a macOS application. Use this as the FIRST STEP when automating any app.",
+        "",
+        "PROVEN WORKFLOW (from KakaoTalk automation):",
+        "1. desktop_open_app \u2192 2. desktop_list_apps (verify) \u2192 3. desktop_see or desktop_screenshot \u2192 4. interact",
+        "",
+        "After launching, use desktop_list_apps to confirm the app is running, then desktop_see to capture UI.",
+        "",
+        "SAFETY: Terminal, iTerm, and Finder are blocked for automation safety."
+      ].join("\n"),
+      {
+        app: z5.string().describe("Application name to launch (e.g. 'Safari', 'Notes', 'KakaoTalk', 'Google Chrome')")
+      },
+      async ({ app }) => {
+        checkBlacklist(app);
+        const args = ["app", "launch", app, "--wait-until-ready"];
+        const result = await peekaboo(args);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      }
+    );
+    server.tool(
+      "desktop_open_url",
+      [
+        "Open a URL or file with its default (or specified) application.",
+        "",
+        "Examples: 'https://google.com', '~/Documents/report.pdf', 'x-apple.systempreferences:...'"
+      ].join("\n"),
+      {
+        url: z5.string().describe("URL or file path to open"),
+        app: z5.string().optional().describe("Specific app to open with (e.g. 'Google Chrome', 'Preview')")
+      },
+      async ({ url, app }) => {
+        const args = ["open", url];
+        if (app) args.push("--app", app);
+        const result = await peekaboo(args);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      }
+    );
   }
 };
 

package/dist/server/stdio.js

@@ -43,7 +43,10 @@ var toolPermissions = {
   desktop_hotkey: "confirm",
   desktop_scroll: "confirm",
   desktop_menu: "confirm",
+  desktop_paste: "confirm",
   desktop_screenshot: "confirm",
+  desktop_open_app: "auto",
+  desktop_open_url: "auto",
   cron_create: "confirm",
   cron_delete: "confirm",
   edit_block: "confirm",
@@ -74,6 +77,8 @@ var FilesystemTools = class {
         "ROUTING:",
         "- Use for system commands, package managers (npm, pip, brew), git, build tools, and scripting.",
         "- For reading files prefer read_file, for editing prefer edit_block, for searching prefer search_code.",
+        "- NOT for macOS app GUI interaction. When the user asks to interact with, control, or automate any application (clicking, typing, reading screen, navigating menus), use the desktop_* tools instead (desktop_open_app, desktop_see, desktop_click, desktop_type, desktop_paste, desktop_hotkey, desktop_scroll, desktop_menu, desktop_screenshot).",
+        "- The ONLY exception: permission fix commands (swift -e for CGRequestScreenCaptureAccess/AXIsProcessTrustedWithOptions, peekaboo permissions, or open 'x-apple.systempreferences:...').",
         "",
         "BEHAVIOR:",
         "- Execute commands directly when the user requests them. Do not ask for confirmation \u2014 the user has already decided.",
@@ -1213,7 +1218,12 @@ Cause: ${e.message}${hint}` }],
         "Start or stop screen recording. Captures the full screen as MP4 video.",
         "",
         "Use action='start' to begin, action='stop' to end and save. Only one recording can be active at a time.",
-        "Platform-specific: macOS (screencapture -v), Windows/Linux (ffmpeg)."
+        "Platform-specific: macOS (screencapture -v), Windows/Linux (ffmpeg).",
+        "",
+        "PERMISSIONS (macOS): Screen Recording permission is needed (inherited from terminal app).",
+        "If denied, run via execute_command: swift -e 'import CoreGraphics; CGRequestScreenCaptureAccess()'",
+        "\u2192 macOS dialog appears. Ask user to click Allow, then retry.",
+        "Fallback: open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'"
       ].join("\n"),
       {
         action: z4.enum(["start", "stop"]).describe("'start': begin recording, 'stop': end recording and save the file"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "junis",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "One-line device control for AI agents",
   "type": "module",
   "bin": {