junis 0.3.11 → 0.3.13

package/dist/cli/index.js

@@ -491,7 +491,7 @@ var FilesystemTools = class {
         "- 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: opening System Preferences URLs for permissions (e.g. open 'x-apple.systempreferences:...').",
+        "- 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.",
@@ -1633,9 +1633,10 @@ Cause: ${e.message}${hint}` }],
         "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).",
         "",
-        "PERMISSIONS (macOS): Screen Recording permission is needed. If denied, run via execute_command:",
-        "  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-        "Toggle ON for 'screencapture' (or your terminal app), then retry."
+        "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"),
@@ -1779,10 +1780,13 @@ 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();
@@ -1821,27 +1825,33 @@ var DesktopTools = class {
         "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): use desktop_screenshot + coordinate-based desktop_click instead.",
+        "- 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: Requires Accessibility + Screen Recording for 'peekaboo'.",
-        "If denied, run via execute_command:",
-        "  1. peekaboo permissions --json-output",
-        "  2. open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'",
-        "  3. open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-        "Toggle ON for 'peekaboo', then retry.",
+        "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. 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 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;
@@ -1862,27 +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 macOS Accessibility permission for 'peekaboo'.",
+        "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) }]
@@ -1892,23 +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: Always capture the accessibility tree first to verify the correct element is focused before typing.",
-        "For Korean/Japanese/Chinese text or emoji, use desktop_paste instead \u2014 keyboard input does not support CJK characters.",
+        "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.",
         "",
-        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
+        "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) }]
@@ -1922,7 +1957,8 @@ 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 macOS Accessibility permission for 'peekaboo'.",
+        "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"),
@@ -1947,7 +1983,8 @@ 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 macOS Accessibility permission for 'peekaboo'.",
+        "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"),
@@ -2004,7 +2041,8 @@ var DesktopTools = class {
         "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.",
         "",
-        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'."
+        "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.")
@@ -2041,23 +2079,41 @@ var DesktopTools = class {
     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 macOS Screen Recording permission for 'peekaboo'.",
+        "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;
@@ -2085,7 +2141,8 @@ 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 macOS Accessibility permission for 'peekaboo'.",
+        "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"),
@@ -2118,21 +2175,24 @@ var DesktopTools = class {
     server.tool(
       "desktop_paste",
       [
-        "Paste text via clipboard into the focused element. Use this for Korean, Japanese, Chinese, emoji, or any non-ASCII text.",
+        "Paste text via clipboard into the focused element. Automatically sets clipboard, pastes (Cmd+V), then restores previous clipboard.",
         "",
-        "Unlike desktop_type (which sends keyboard input character-by-character), this uses the system clipboard to paste text, supporting all character sets including CJK and emoji.",
+        "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.",
         "",
-        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
+        `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 into the focused element (supports Korean, Japanese, Chinese, emoji)"),
+        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 = ["type", "--paste", text];
+        const args = ["paste", text];
         if (app) args.push("--app", app);
         const result = await peekaboo(args);
         return {
@@ -2145,8 +2205,10 @@ var DesktopTools = class {
       [
         "Launch or bring to front a macOS application. Use this as the FIRST STEP when automating any app.",
         "",
-        "This uses macOS native 'open -a' command. The app will be launched if not running, or brought to front if already running.",
-        "After launching, wait briefly then use desktop_see to capture the accessibility tree.",
+        "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"),
@@ -2155,29 +2217,30 @@ var DesktopTools = class {
       },
       async ({ app }) => {
         checkBlacklist(app);
-        await execa("open", ["-a", app]);
-        await new Promise((r) => setTimeout(r, 1500));
+        const args = ["app", "launch", app, "--wait-until-ready"];
+        const result = await peekaboo(args);
         return {
-          content: [{ type: "text", text: `Launched ${app}` }]
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
       }
     );
     server.tool(
       "desktop_open_url",
       [
-        "Open a URL in the default browser or a specified app. Also works for file paths and custom URL schemes.",
+        "Open a URL or file with its default (or specified) application.",
         "",
-        "Examples: 'https://google.com', 'file:///path/to/file.html', 'x-apple.systempreferences:...'"
+        "Examples: 'https://google.com', '~/Documents/report.pdf', 'x-apple.systempreferences:...'"
       ].join("\n"),
       {
-        url: z5.string().describe("URL to open (https://, file://, or custom scheme)"),
-        app: z5.string().optional().describe("Specific app to open the URL with (e.g. 'Google Chrome', 'Firefox')")
+        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 = app ? ["-a", app, url] : [url];
-        await execa("open", args);
+        const args = ["open", url];
+        if (app) args.push("--app", app);
+        const result = await peekaboo(args);
         return {
-          content: [{ type: "text", text: `Opened: ${url}` }]
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
       }
     );

package/dist/server/mcp.js

@@ -77,7 +77,7 @@ var FilesystemTools = class {
         "- 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: opening System Preferences URLs for permissions (e.g. open 'x-apple.systempreferences:...').",
+        "- 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.",
@@ -1219,9 +1219,10 @@ Cause: ${e.message}${hint}` }],
         "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).",
         "",
-        "PERMISSIONS (macOS): Screen Recording permission is needed. If denied, run via execute_command:",
-        "  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-        "Toggle ON for 'screencapture' (or your terminal app), then retry."
+        "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"),
@@ -1365,10 +1366,13 @@ 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();
@@ -1407,27 +1411,33 @@ var DesktopTools = class {
         "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): use desktop_screenshot + coordinate-based desktop_click instead.",
+        "- 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: Requires Accessibility + Screen Recording for 'peekaboo'.",
-        "If denied, run via execute_command:",
-        "  1. peekaboo permissions --json-output",
-        "  2. open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'",
-        "  3. open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-        "Toggle ON for 'peekaboo', then retry.",
+        "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. 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 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;
@@ -1448,27 +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 macOS Accessibility permission for 'peekaboo'.",
+        "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) }]
@@ -1478,23 +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: Always capture the accessibility tree first to verify the correct element is focused before typing.",
-        "For Korean/Japanese/Chinese text or emoji, use desktop_paste instead \u2014 keyboard input does not support CJK characters.",
+        "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.",
         "",
-        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
+        "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) }]
@@ -1508,7 +1543,8 @@ 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 macOS Accessibility permission for 'peekaboo'.",
+        "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"),
@@ -1533,7 +1569,8 @@ 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 macOS Accessibility permission for 'peekaboo'.",
+        "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"),
@@ -1590,7 +1627,8 @@ var DesktopTools = class {
         "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.",
         "",
-        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'."
+        "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.")
@@ -1627,23 +1665,41 @@ var DesktopTools = class {
     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 macOS Screen Recording permission for 'peekaboo'.",
+        "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;
@@ -1671,7 +1727,8 @@ 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 macOS Accessibility permission for 'peekaboo'.",
+        "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"),
@@ -1704,21 +1761,24 @@ var DesktopTools = class {
     server.tool(
       "desktop_paste",
       [
-        "Paste text via clipboard into the focused element. Use this for Korean, Japanese, Chinese, emoji, or any non-ASCII text.",
+        "Paste text via clipboard into the focused element. Automatically sets clipboard, pastes (Cmd+V), then restores previous clipboard.",
         "",
-        "Unlike desktop_type (which sends keyboard input character-by-character), this uses the system clipboard to paste text, supporting all character sets including CJK and emoji.",
+        "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.",
         "",
-        "PERMISSIONS: Requires macOS Accessibility permission for 'peekaboo'.",
+        `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 into the focused element (supports Korean, Japanese, Chinese, emoji)"),
+        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 = ["type", "--paste", text];
+        const args = ["paste", text];
         if (app) args.push("--app", app);
         const result = await peekaboo(args);
         return {
@@ -1731,8 +1791,10 @@ var DesktopTools = class {
       [
         "Launch or bring to front a macOS application. Use this as the FIRST STEP when automating any app.",
         "",
-        "This uses macOS native 'open -a' command. The app will be launched if not running, or brought to front if already running.",
-        "After launching, wait briefly then use desktop_see to capture the accessibility tree.",
+        "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"),
@@ -1741,29 +1803,30 @@ var DesktopTools = class {
       },
       async ({ app }) => {
         checkBlacklist(app);
-        await execa("open", ["-a", app]);
-        await new Promise((r) => setTimeout(r, 1500));
+        const args = ["app", "launch", app, "--wait-until-ready"];
+        const result = await peekaboo(args);
         return {
-          content: [{ type: "text", text: `Launched ${app}` }]
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
       }
     );
     server.tool(
       "desktop_open_url",
       [
-        "Open a URL in the default browser or a specified app. Also works for file paths and custom URL schemes.",
+        "Open a URL or file with its default (or specified) application.",
         "",
-        "Examples: 'https://google.com', 'file:///path/to/file.html', 'x-apple.systempreferences:...'"
+        "Examples: 'https://google.com', '~/Documents/report.pdf', 'x-apple.systempreferences:...'"
       ].join("\n"),
       {
-        url: z5.string().describe("URL to open (https://, file://, or custom scheme)"),
-        app: z5.string().optional().describe("Specific app to open the URL with (e.g. 'Google Chrome', 'Firefox')")
+        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 = app ? ["-a", app, url] : [url];
-        await execa("open", args);
+        const args = ["open", url];
+        if (app) args.push("--app", app);
+        const result = await peekaboo(args);
         return {
-          content: [{ type: "text", text: `Opened: ${url}` }]
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
       }
     );

package/dist/server/stdio.js

@@ -78,7 +78,7 @@ var FilesystemTools = class {
         "- 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: opening System Preferences URLs for permissions (e.g. open 'x-apple.systempreferences:...').",
+        "- 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.",
@@ -1220,9 +1220,10 @@ Cause: ${e.message}${hint}` }],
         "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).",
         "",
-        "PERMISSIONS (macOS): Screen Recording permission is needed. If denied, run via execute_command:",
-        "  open 'x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture'",
-        "Toggle ON for 'screencapture' (or your terminal app), then retry."
+        "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.11",
+  "version": "0.3.13",
   "description": "One-line device control for AI agents",
   "type": "module",
   "bin": {